In GameCalendar

Overview

In-Game Calendar gives your game world a living, functional sense of time. A single GameCalendar scene singleton drives everything — either mirroring the player's real system clock or advancing at a configurable in-game speed. The WallCalendar prop reads from it every day tick and updates a 3D wall calendar mesh: the correct month illustration is shown, days that have passed are crossed off in red, and today's cell is highlighted.

When the month rolls over, the CalendarPageTurn component plays a skinned mesh page-turn animation, snapping a texture of the completed calendar before the new month loads in. A SunController demo component drives a directional light as a sun with seasonal arc variation.

Requirements

Package Contents

Quick Start

The included demo scene open in Unity, showing the WallCalendar prop, GameCalendar singleton, and SunController all wired up and ready to run.

Option A — Use the Demo Scene

Open InGameCalendar/Demo/DemoScene and press Play. Everything is already connected.

Option B — Add to your own scene

GameCalendar Singleton

Scene singleton that tracks in-game date and time. Add once to a persistent GameObject. All other components find it automatically via GameCalendar.Instance.

Namespace: ChrisBurns.InGameCalendar

The GameCalendar Inspector — toggle between Real-World Clock and In-Game mode, set the starting date, and control how fast in-game time advances.

// Example: jump to July 4th at 9am
GameCalendar.Instance.JumpToDate(CalendarMonth.July, 4, 9f);

// Example: set time of day
GameCalendar.Instance.SetTime("14:30");

// Example: read current date
int day   = GameCalendar.Instance.Day;
int month = GameCalendar.Instance.Month;

void Start()
{
    GameCalendar.Instance.OnDayChanged  += HandleNewDay;
    GameCalendar.Instance.OnMonthChanged += HandleNewMonth;
}

void HandleNewDay()  { /* spawn daily events, refresh quest states, etc. */ }
void HandleNewMonth() { /* change season, update shop inventory, etc. */ }

WallCalendar Prop Controller

Reads from GameCalendar on the OnDayChanged event and updates all prop visuals: the month illustration texture, month name label, day-of-week column headers, and the 35-cell (5 rows × 7 columns) grid of DayMarker cells. Can alternatively sync to the Cozy: Stylized Weather time system — see Cozy Weather Integration.

Namespace: ChrisBurns

The WallCalendar Inspector — assign the GameCalendar reference, top image Renderer, month label, grid container, and configure colour settings for past, present, and future day cells.

Scene Setup (from scratch)

The WallCalendar GameObject hierarchy — the GridContainer holds the GridLayoutGroup that positions 35 DayMarker cells, with a separate row above for the day-of-week column headers.

The included prefab is already fully configured. If you need to set up a WallCalendar manually:

1

Add the WallCalendar mesh — Place the WallCalendar.fbx model in your scene and assign materials from the Materials folder.

2

Add a WallCalendar component — Assign the topImageRenderer to the top-panel mesh Renderer. Assign a TMP_Text to monthLabelTMP.

3

Set up the grid container — Create a child Canvas (World Space), add a Panel with a GridLayoutGroup. Assign this panel as gridContainer.

4

Assign the DayMarker prefab — Drag DayMarker.prefab into the dayMarkerPrefab slot. Click Populate Grid in the Inspector to instantiate 35 cells.

5

Assign the DaysOfTheWeek prefab — Set up a header row above the grid. Assign to dayOfWeekLabelPrefab and click Populate Day Labels.

⚠️

The Populate Grid button destroys existing cell children before recreating them. If you have customised individual cells, back them up first.

DayMarker Cell Component

Placed on the root of each day-cell prefab. Controlled entirely by WallCalendar — you do not need to call any methods on it directly.

Namespace: ChrisBurns

The DayMarker prefab Inspector — assign the X mark object, cell image, and date label. Each cell is automatically set to one of three states: past day (red X), today (highlighted), or future day (neutral).

Inspector Fields

CalendarPageTurn Animation

Listens for WallCalendar.OnBeforeMonthRefresh, snapshots the live RenderTexture, and triggers a skinned mesh page-turn animation.

Namespace: ChrisBurns

The page-turn animation mid-flip — the skinned mesh page peels back showing the previous month's illustration on the front and the incoming month's live RenderTexture on the reverse.

Setup

Inspector Properties

SunController Demo

Drives a scene Directional Light as a sun, reading GameCalendar.Hour and Month every Update. Requires a Light component on the same GameObject.

Namespace: ChrisBurns.InGameCalendar.Demo

Texture Atlas

The top illustration panel uses a 4×4 UV-sliced texture atlas (16 cells total). Months map to cells 0–11; cells 12–15 are available for cover, back, and spare pages.

The included CalendarImages.png — a 4×4 texture atlas containing all 12 month illustrations (cells 0–11) plus spare cells for cover, back, and blank pages. Swap this texture to use your own artwork.

Custom Art

To replace the month illustrations with your own artwork:

Week Start Day

Toggle the Week Starts On Sunday checkbox on the WallCalendar component. The grid columns and day-of-week headers update automatically — no scene rebuild needed.

Two RenderTexture + Material pairs are included: WallCalendarMondayStartRT and WallCalendarSundayStartRT. Use whichever matches your setting.

Cozy Weather Integration

WallCalendar can drive its date directly from Cozy: Stylized Weather (DistantLands) instead of GameCalendar — useful if Cozy is already your project's source of truth for time of day and seasons.

How it works

In Cozy mode the calendar subscribes to Cozy's onNewDay event and reads the month, day, and year from the Cozy time module each refresh. The month is resolved from Cozy's own month name (so custom month-profile lengths are respected); if the name doesn't match a standard English month name, it falls back to the year-percentage. OnBeforeMonthRefresh still fires on month rollover, so the CalendarPageTurn animation works unchanged.

Configuring Time Speed

The gameMinutesPerRealSecond field on GameCalendar controls how fast in-game time passes.

GameCalendar.Instance.gameMinutesPerRealSecond = 120f; // 2x speed

Scripting Integration

Subscribing to day and month changes

using ChrisBurns.InGameCalendar;

public class QuestSystem : MonoBehaviour
{
    void Start()
    {
        GameCalendar.Instance.OnDayChanged   += OnNewDay;
        GameCalendar.Instance.OnMonthChanged += OnNewMonth;
    }

    void OnDestroy()
    {
        // Always unsubscribe to prevent memory leaks
        if (GameCalendar.Instance != null)
        {
            GameCalendar.Instance.OnDayChanged   -= OnNewDay;
            GameCalendar.Instance.OnMonthChanged -= OnNewMonth;
        }
    }

    void OnNewDay()
    {
        int day   = GameCalendar.Instance.Day;
        int month = GameCalendar.Instance.Month;
        Debug.Log($"New day: {day}/{month}");
    }

    void OnNewMonth()
    {
        // Rotate stock, change season, etc.
    }
}

Forcing a calendar refresh from code

// After changing the date manually, force the wall calendar to refresh visuals.
// Note: WallCalendar lives in the ChrisBurns namespace (add: using ChrisBurns;)
FindFirstObjectByType<WallCalendar>().Refresh();

FAQ

The calendar shows the wrong month illustration

Check that Texture Property Name on WallCalendar matches your pipeline — _BaseMap for URP/HDRP, _MainTex for Built-in. Also verify Atlas Columns/Rows match your texture.

The day grid isn't positioned correctly

The grid container needs a GridLayoutGroup with a cell size and spacing that fits your mesh. Check the prefab's Grid Canvas settings for reference values.

The page-turn animation doesn't play

Ensure the Animator has a Trigger parameter named exactly PageTurn. Confirm the Animation Event at the end of the clip calls OnPageTurnComplete on the CalendarPageTurn component, not WallCalendar. Note also that with Suppress On Start enabled (the default), the very first month change after entering Play Mode is intentionally not animated.

Can I use this without the wall calendar mesh?

Yes — GameCalendar is completely decoupled. Use it as a standalone game clock and subscribe to its events to drive any other system.

Does this work with a custom time system?

Partially. GameCalendar.ClockInterface exposes the clock through the IGameClock, IScalableClock, and IMonthChangedNotifier interfaces, so your own systems can consume in-game time without depending on GameCalendar directly. WallCalendar itself accepts two time sources: a GameCalendar reference, or Cozy: Stylized Weather via the built-in Cozy integration — it does not accept an arbitrary custom IGameClock implementation.

Can I have multiple wall calendars in one scene?

Yes. Each WallCalendar subscribes to the same GameCalendar singleton independently. All instances update in sync.

Changelog

v1.0.1 — Asset Store Review Fixes

• New: optional Cozy: Stylized Weather integration — tick useCozyWeather on WallCalendar with the COZY_WEATHER define to drive the calendar from Cozy's time module
• Editor: Populate Grid / Populate Day Labels now destroy existing children via Undo.DestroyObjectImmediate, fixing MissingReferenceException errors on play-mode entry
• GameCalendar date properties now default to a valid date, so reads before Awake (e.g. another script's OnValidate) never see an invalid 0/0/0 date
• Day grid consolidated to a 35-cell (5×7) layout — months needing a sixth row wrap into the first row's blank cells

v1.0.0 — Initial Release

• GameCalendar singleton with real-world and in-game clock modes
• WallCalendar prop with 35-cell (5×7) day grid, X marks, month illustration atlas
• CalendarPageTurn with RenderTexture snapshot and skinned mesh animation
• SunController demo component with seasonal arc
• Monday-start and Sunday-start variants
• Three texture atlas themes: Default, Cars, Landscapes
• Demo scene included