Skip to content

osrlib.core.clock

How much game time has passed, counted in rounds.

GameClock is the entry point. Create one, call advance whenever the party spends time, and read rounds, turns, and days off it. Each call to advance returns the turn and day boundaries the clock crossed, as BoundaryCrossing values. Handle each one as the end of a turn or a day: burn a torch down, check for wandering monsters, or eat a day's rations.

The members, in the order you use them:

In an ordinary game you never build a clock yourself. A GameSession has one and advances it as commands take time, and EffectsLedger.advance takes the session's clock when it ages poison, light, and other effects. Build your own when you use the kernel, osrlib's rules functions, without a session and still want time to pass.

B/X measures time in three units: the round of 10 seconds, the turn of 10 minutes, and the day. The clock stores one integer count of rounds, the smallest unit, so the arithmetic is exact and the whole clock saves as one number. An advance that ends exactly on a boundary counts as crossing it: a torch lit at turn 0 burns out when the clock reaches turn 6, not turn 7.

Typical usage:

from osrlib.core.clock import GameClock, TimeUnit

clock = GameClock()

# Six turns of searching: one crossing per turn, none for a day.
crossings = clock.advance(6, TimeUnit.TURN)
assert [(crossing.unit, crossing.index) for crossing in crossings] == [
    (TimeUnit.TURN, 1),
    (TimeUnit.TURN, 2),
    (TimeUnit.TURN, 3),
    (TimeUnit.TURN, 4),
    (TimeUnit.TURN, 5),
    (TimeUnit.TURN, 6),
]
assert (clock.rounds, clock.turns, clock.days) == (360, 6, 0)

# Ten rounds of combat cross nothing: the clock is mid-turn.
assert clock.advance(10) == []
assert clock.rounds == 370

ROUNDS_PER_DAY module-attribute

ROUNDS_PER_DAY = ROUNDS_PER_TURN * TURNS_PER_DAY

How many rounds make up one day, which is 8640.

It's ROUNDS_PER_TURN * TURNS_PER_DAY rather than a separate number, so it can never disagree with ROUNDS_PER_TURN or TURNS_PER_DAY.

ROUNDS_PER_TURN module-attribute

ROUNDS_PER_TURN: Final = 60

How many rounds make up one exploration turn, which is ten minutes of story time.

The round is the combat unit and the turn is the exploration unit, and this is the conversion between them. Use it to say how long something lasts in the other unit: a torch that burns for six turns burns for 6 * ROUNDS_PER_TURN rounds.

Every duration the SRD prints, in turns or in rounds, assumes this ratio. To work in a unit of your own, advance the clock by rounds and convert the result yourself.

SECONDS_PER_ROUND module-attribute

SECONDS_PER_ROUND = 10

How many seconds of story time one combat round takes.

The rules functions don't use this. It's here so you can put a wall-clock duration on the screen, or pace an animation, without writing 10 into your own code. The B/X rules give no unit finer than the round, so there's nothing below it to count.

TURNS_PER_DAY module-attribute

TURNS_PER_DAY = 144

How many exploration turns make up one day.

That's a full 24 hours of turns, not only the ones spent underground. A session consumes the party's daily rations and water at each day boundary.

BoundaryCrossing

Bases: BaseModel

One turn or day boundary that the clock passed during an advance.

advance returns a list of these, earliest first. Go through the list in order and handle the end of each turn or day. There are no round crossings: every round is a round boundary, so their count is the number of rounds you advanced.

The model is frozen, so you can keep a crossing as a record of when something happened.

Examples:

from osrlib.core.clock import GameClock, TimeUnit

# A day boundary is also a turn boundary, and the turn is reported first.
clock = GameClock(rounds=8580)
crossings = clock.advance(1, TimeUnit.TURN)
assert [(crossing.unit, crossing.index, crossing.round) for crossing in crossings] == [
    (TimeUnit.TURN, 144, 8640),
    (TimeUnit.DAY, 1, 8640),
]

unit instance-attribute

unit: TimeUnit

Which kind of boundary this is, TimeUnit.TURN or TimeUnit.DAY.

A crossing is never TimeUnit.ROUND. An advance of n rounds crosses n round boundaries, so listing them would only repeat the number you passed in.

index class-attribute instance-attribute

index: int = Field(ge=1)

Which boundary of that kind, counted from the start of the game.

The first turn of play is 1 and the sixth is 6, so the ordinal matches the way the rules count durations ("burns for six turns").

round class-attribute instance-attribute

round: int = Field(ge=1)

The clock reading at which the boundary sits, in rounds since the start of the game.

Turn 6 sits at round 360. Use it to stamp whatever you record at the boundary, so the record and the clock agree.

GameClock

Bases: BaseModel

How much time has passed in the game, as a count of rounds.

Call GameClock() to start a game at time zero, or GameClock(rounds=n) to resume one. A GameSession creates one and stores it on session.clock, so call the constructor only when you run the kernel without a session. In a session, spend time by executing commands, or with GameSession.advance_rounds and GameSession.advance_turns. Those also age effects and consume rations. Advancing session.clock yourself does neither.

Unlike most models in the kernel, this one is mutable. advance moves the same clock forward instead of returning a new one, because everything that spends time shares one clock. Pass the clock itself to anything that takes time, not a copy, or the copies fall out of step. Assigning rounds directly works and is validated, but it reports no boundaries, so use advance.

The clock saves as one field, rounds, and GameClock.model_validate(document) reads it back.

Examples:

from osrlib.core.clock import GameClock, TimeUnit

clock = GameClock()
crossings = clock.advance(2, TimeUnit.TURN)
assert clock.turns == 2
assert [crossing.index for crossing in crossings if crossing.unit is TimeUnit.TURN] == [1, 2]

# The whole clock round-trips as one field.
assert GameClock.model_validate(clock.model_dump()).rounds == 120

rounds class-attribute instance-attribute

rounds: int = Field(default=0, ge=0)

Rounds elapsed since the start of the game.

The clock's only stored value. turns and days are computed from it. Advancing is what normally changes it, and it can never go below zero.

turns property

turns: int

Return the number of whole exploration turns elapsed, rounding down.

Read it for a "how long have we been down here" display. A turn in progress doesn't count until it finishes, so a clock at round 59 still reads 0 turns.

days property

days: int

Return the number of whole days elapsed, rounding down.

Read it to tell how many days of rations the party has eaten. A day in progress doesn't count until it finishes.

advance

advance(n: int, unit: TimeUnit = ROUND) -> list[BoundaryCrossing]

Advance the clock and report the turn and day boundaries crossed.

Call this whenever the party spends time, then act on the crossings you get back. The clock moves in place, and the return value is the list of crossings, not a new clock.

If you're aging effects as well as counting time, call EffectsLedger.advance instead and pass it this clock. It advances the clock for you and returns the events for effects that ticked and expired. This method changes no effects. In a session, call GameSession.advance_rounds instead.

Parameters:

Name Type Description Default
n int

How many units to advance. Must be non-negative. Zero is legal and crosses nothing.

required
unit TimeUnit

The unit to advance in.

ROUND

Returns:

Type Description
list[BoundaryCrossing]

Every turn and day boundary in the advanced span, in chronological order, with a coinciding turn boundary before its day boundary. A boundary the advance ends on exactly is included. The position you started from isn't, because the advance that reached it already reported it.

Raises:

Type Description
ValueError

If n is negative. Time never runs backwards, so to rewind a game, restore it from a save.

Examples:

from osrlib.core.clock import GameClock, TimeUnit

clock = GameClock()

# A round of combat crosses nothing.
assert clock.advance(1) == []

# Searching a room takes a turn, and the turn boundary comes back.
crossings = clock.advance(1, TimeUnit.TURN)
assert [(crossing.unit, crossing.index) for crossing in crossings] == [(TimeUnit.TURN, 1)]
assert clock.rounds == 61

TimeUnit

Bases: StrEnum

The unit an amount of game time is counted in.

Pass one to advance to say what your number means, and read one off a BoundaryCrossing to see which kind of boundary you crossed. The rounds each unit is worth are ROUNDS_PER_TURN and ROUNDS_PER_DAY.

ROUND class-attribute instance-attribute

ROUND = 'round'

The combat unit, ten seconds of story time.

One attack, one spell, or one move in a fight takes a round.

TURN class-attribute instance-attribute

TURN = 'turn'

The exploration unit, ten minutes of story time.

A search takes a turn, and so does the shortest rest. Walking through the dungeon adds up toward a turn, and a party covers its exploration movement rate in one.

DAY class-attribute instance-attribute

DAY = 'day'

The supply unit, a full day of story time.

A session consumes the party's rations and water at each day boundary.