152 lines
5.0 KiB
Markdown
152 lines
5.0 KiB
Markdown
# Jovian Calendar
|
|
|
|
A configurable in-game calendar and world clock system for Unity. Supports custom day lengths, hours, minutes, months with variable lengths, named months, week tracking, and a serializable date-time struct. No external dependencies.
|
|
|
|
## Requirements
|
|
|
|
- Unity 2022.3 or later
|
|
- No additional package dependencies
|
|
|
|
## Quick Start
|
|
|
|
### 1. Create a CalendarSettings asset
|
|
|
|
In the Unity Editor, go to **Assets > Create > Jovian > Calendar > Calendar Settings**.
|
|
|
|
Configure:
|
|
- **Seconds Per Full Day**: How many real-time seconds equal one full in-game day (the 0-1 cycle)
|
|
- **Hours Per Day**: In-world hours per day (e.g. 24)
|
|
- **Minutes Per Hour**: In-world minutes per hour (e.g. 60)
|
|
- **Days Per Month**: Array defining the length of each month. Array length = months per year
|
|
- **Month Names**: Display names for each month (must match Days Per Month length)
|
|
- **Days Per Week**: Optional week length (0 to disable)
|
|
- **Start Date**: Starting year, month, day, hour, minute for the clock
|
|
|
|
### 2. Create and tick a WorldClock
|
|
|
|
```csharp
|
|
using Jovian.Calendar;
|
|
|
|
// Create the clock from settings
|
|
var clock = new WorldClock(calendarSettings);
|
|
|
|
// Each frame, feed it a 0-1 normalized day progress
|
|
clock.Tick(normalizedDayTime);
|
|
|
|
// Query the current date and time
|
|
WorldDateTime now = clock.Now;
|
|
Debug.Log($"Year {now.year}, {clock.GetMonthName()} {now.DisplayDay}, {now.TimeString}");
|
|
```
|
|
|
|
### 3. Display the date
|
|
|
|
```csharp
|
|
// Individual fields
|
|
int year = clock.Now.year;
|
|
int month = clock.Now.DisplayMonth; // 1-indexed
|
|
int day = clock.Now.DisplayDay; // 1-indexed
|
|
string time = clock.Now.TimeString; // "HH:MM"
|
|
|
|
// Full display string
|
|
string full = clock.FullStringNamed();
|
|
// e.g. "14:30, 5th day of Frostmoon, year 3"
|
|
```
|
|
|
|
## CalendarSettings
|
|
|
|
ScriptableObject defining calendar rules. Create via **Assets > Create > Jovian > Calendar > Calendar Settings**.
|
|
|
|
| Field | Type | Description |
|
|
|---|---|---|
|
|
| `secondsPerFullDay` | float | Real-time seconds for one full 0-1 day cycle |
|
|
| `hoursPerDay` | int | In-world hours per day |
|
|
| `minutesPerHour` | int | In-world minutes per hour |
|
|
| `daysPerMonth` | int[] | Days in each month. Array length = months per year |
|
|
| `monthNames` | string[] | Display name per month. Must match daysPerMonth length |
|
|
| `daysPerWeek` | int | Days per week (0 to disable week tracking) |
|
|
| `startYear` | int | Starting year |
|
|
| `startMonth` | int | Starting month (0-indexed) |
|
|
| `startDay` | int | Starting day (0-indexed) |
|
|
| `startHour` | int | Starting hour |
|
|
| `startMinute` | int | Starting minute |
|
|
|
|
**Computed properties:**
|
|
- `MonthsPerYear` -- derived from daysPerMonth array length
|
|
- `TotalDaysInYear` -- sum of all daysPerMonth entries
|
|
- `MinutesPerDay` -- hoursPerDay * minutesPerHour
|
|
|
|
## WorldClock
|
|
|
|
The core clock class. Feed it a normalized 0-1 day progress each tick. It accumulates world-minutes internally, handling day wrap-around and fractional minute accumulation across frames.
|
|
|
|
```csharp
|
|
var clock = new WorldClock(settings);
|
|
|
|
// Tick with normalized time (0 = midnight, 0.5 = noon, 1 = next midnight)
|
|
clock.Tick(normalizedTime);
|
|
|
|
// Manual time skip (sleep, rest, cutscene)
|
|
clock.AdvanceMinutes(480); // skip 8 hours
|
|
|
|
// Queries
|
|
WorldDateTime now = clock.Now;
|
|
long elapsed = clock.TotalElapsedMinutes;
|
|
float normalized = clock.NormalizedTimeOfDay; // 0-1 for lighting/skybox
|
|
int weekday = clock.DayOfWeek; // 0-indexed, -1 if disabled
|
|
string monthName = clock.GetMonthName();
|
|
string display = clock.FullStringNamed();
|
|
```
|
|
|
|
## WorldDateTime
|
|
|
|
A serializable struct representing a point in calendar time. Implements `IEquatable<WorldDateTime>` and `IComparable<WorldDateTime>` for collections and sorting.
|
|
|
|
```csharp
|
|
WorldDateTime dt = clock.Now;
|
|
|
|
// 0-indexed fields
|
|
dt.year; dt.month; dt.day; dt.hour; dt.minute;
|
|
|
|
// 1-indexed display properties
|
|
dt.DisplayDay; // day + 1
|
|
dt.DisplayMonth; // month + 1
|
|
|
|
// Formatting
|
|
dt.TimeString; // "14:30"
|
|
dt.DateString; // "5/3/1"
|
|
dt.FullString; // "5/3/1 14:30"
|
|
|
|
// Comparison
|
|
if(dateA < dateB) { ... }
|
|
if(dateA == dateB) { ... }
|
|
var sorted = dates.OrderBy(d => d);
|
|
```
|
|
|
|
## Integration Example
|
|
|
|
```csharp
|
|
// In your game state initialization:
|
|
var calendarSettings = Addressables.LoadAssetAsync<CalendarSettings>("CalendarSettings").WaitForCompletion();
|
|
var worldClock = new WorldClock(calendarSettings);
|
|
|
|
// In your time handler's Tick():
|
|
float normalizedTime = localTime / dayLength;
|
|
worldClock.Tick(normalizedTime);
|
|
|
|
// Update UI:
|
|
dayText.text = $"Day {worldClock.Now.DisplayDay}, {worldClock.GetMonthName()}";
|
|
|
|
// Use NormalizedTimeOfDay for visual effects:
|
|
float t = worldClock.NormalizedTimeOfDay;
|
|
skyboxMaterial.SetFloat("_Blend", t);
|
|
directionalLight.intensity = sunCurve.Evaluate(t);
|
|
```
|
|
|
|
## API Reference
|
|
|
|
| Type | Description |
|
|
|---|---|
|
|
| `CalendarSettings` | ScriptableObject defining calendar rules (day length, months, weeks, start date) |
|
|
| `WorldClock` | Core clock class. Tick with normalized time, query WorldDateTime |
|
|
| `WorldDateTime` | Serializable struct for date-time values. IEquatable, IComparable, operator overloads |
|