Added a custom calendar system

Packages/com.jovian.calendar/README.md

@@ -0,0 +1,151 @@
+# 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 |