View as Markdown · AI documentation index

Class: Clock

Defined in: clock.ts:83

The in-fiction clock of the game.

Game time is independent of wall-clock time: it starts at a fixed fictional timestamp, persists with the save, and by default only moves when the game says so. That makes it usable for schedules, cooldowns, day/night cycles, and message timestamps without making saves or tests depend on when they ran.

State is stored as an anchor pair rather than a running counter, so "realtime" mode needs no interval to stay correct across saves, page reloads, and suspended tabs.

Remarks

advance(), set(), pause(), resume(), setMode(), and setScale() mutate game state, so call them from event handlers - never while a passage renders.

Example

import { Clock, HOUR, MINUTE } from '@react-text-game/core/clock';

// Manual mode (default): time moves only when the game moves it.
Clock.advance(30 * MINUTE);
console.log(new Date(Clock.now()).toISOString());

// Realtime mode: one real second becomes one game minute.
Clock.setMode('realtime');
Clock.setScale(60);

Constructors

Constructor

new Clock(): Clock

Returns

Clock

Accessors

isPaused

Get Signature

get static isPaused(): boolean

Defined in: clock.ts:121

Whether "realtime" accrual is frozen.

Returns

boolean

---

mode

Get Signature

get static mode(): ClockMode

Defined in: clock.ts:107

How game time currently advances.

Returns

ClockMode

---

scale

Get Signature

get static scale(): number

Defined in: clock.ts:114

Multiplier applied to elapsed wall-clock time in "realtime" mode.

Returns

number

---

selfState

Get Signature

get static selfState(): ClockState

Defined in: clock.ts:91

Reactive clock state, for hooks that need to re-render on clock changes.

Remarks

Read game time through Clock.now instead; this getter exists for subscription, not for arithmetic.

Returns

ClockState

Methods

_resetForTesting()

static _resetForTesting(): void

Defined in: clock.ts:331

Internal

Restores defaults and the real wall-clock source.

Returns

void

---

_setNowProvider()

static _setNowProvider(provider): void

Defined in: clock.ts:322

Internal

Replaces the wall-clock source. Tests only.

Parameters

provider

() => number

Returns

void

---

advance()

static advance(ms): void

Defined in: clock.ts:141

Moves game time forward by ms.

Works in both modes and regardless of Clock.isPaused: an explicit advance is always honoured. A negative value moves time backwards.

Parameters

ms

number

Milliseconds to add to the current game time

Returns

void

Throws

Error if ms is not finite

Example

h.actions([
  { content: 'Sleep until morning', action: () => Clock.advance(8 * HOUR) },
]);

---

init()

static init(options?): void

Defined in: clock.ts:251

Internal

Applies clock options during Game.init().

Parameters

options?

ClockOptions

Returns

void

---

load()

static load(): void

Defined in: clock.ts:301

Internal

Restores game time from storage, re-anchoring wall-clock time to now.

Returns

void

Remarks

Re-anchoring is what keeps real time that passed while the save sat on disk out of game time. A save without clock data leaves the clock alone.

---

now()

static now(): number

Defined in: clock.ts:100

Current game time in milliseconds.

Returns

number

Game time, suitable for new Date(...)

---

pause()

static pause(): void

Defined in: clock.ts:205

Freezes "realtime" accrual, preserving the current game time.

Returns

void

Remarks

A no-op in "manual" mode beyond setting the flag, since manual time does not flow on its own.

---

resume()

static resume(): void

Defined in: clock.ts:220

Resumes "realtime" accrual from the current game time.

Returns

void

---

save()

static save(): void

Defined in: clock.ts:278

Internal

Writes the resolved game time to storage.

Returns

void

---

set()

static set(timestamp): void

Defined in: clock.ts:156

Sets game time to an absolute timestamp.

Parameters

timestamp

number

Game time in milliseconds

Returns

void

Throws

Error if timestamp is not finite

---

setMode()

static setMode(mode): void

Defined in: clock.ts:170

Switches how game time advances, preserving the current game time.

Parameters

mode

ClockMode

The new clock mode

Returns

void

---

setScale()

static setScale(scale): void

Defined in: clock.ts:184

Changes the "realtime" multiplier, preserving the current game time.

Parameters

scale

number

Multiplier applied to elapsed wall-clock time

Returns

void

Throws

Error if scale is not a finite positive number

---

subscribe()

static subscribe(callback): () => void

Defined in: clock.ts:242

Subscribes to clock state changes.

Parameters

callback

() => void

Invoked after every clock state change

Returns

Unsubscribe function

(): void

Returns

void

Remarks

Fires when the clock is advanced, set, paused, resumed, or reconfigured - not continuously as "realtime" time flows, because flowing time mutates nothing. For a ticking display use useGameTime(tickMs).