@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.2

package/dist/docs/guides/tick-controller.md

@@ -0,0 +1,569 @@
+# Tick controllers
+
+A tick controller makes ticks happen on their own, on a schedule your logic decides, and can say when the game is finished. This guide explains the model, then is the reference for writing one.
+
+## The model
+
+By default, ticks are manual: a participant or facilitator presses a control, or a command is sent, to advance the game. That suits a game that moves one decision at a time. Some games need time to move on its own, or at a pace that depends on what is happening in the simulation. Some also need to end when a goal is met rather than after a fixed number of ticks.
+
+A tick controller answers both. It is a function, `GetTickController`, that the runtime calls after each tick. It looks at the game state and returns how long to wait before the next automatic tick, and whether the game is now over.
+
+- **Logic-driven.** The interval is code, not a static setting, so it can vary with game state, participant decisions, or anything else in the context it reads
+- **Called after the fact.** The runtime asks after every tick (including initialisation, so the function always sees a fully initialised state), and again whenever a write changes a capability it reads. It never runs the engine itself
+- **Manual ticks still work.** Automatic timing supplements the manual tick control rather than replacing it. A manual tick simply restarts the countdown from the next answer
+- **Two ways to schedule.** Return an interval ('every 60 seconds') for a cadence, or an absolute time ('every day at midnight') for a wall-clock schedule
+- **Paused is not complete.** Turning the timer off leaves a game that still accepts manual ticks. Declaring it complete ends it: no further ticks, manual or automatic, until it is reset or undone
+
+In an independent game each team has its own timer; in a shared-state game one timer serves the cohort.
+
+### When to use one
+
+Use a tick controller when:
+
+- Your game should advance in real time without manual intervention
+- The pace of the simulation should vary based on game state
+- You want to switch between automatic and manual modes during a game
+- The game must end the moment a participant's write meets a goal, rather than at the next tick (see [Game completion](#game-completion))
+
+You do not need one for a game where participants advance each tick themselves, and you do not need one just to end a game on a goal: the engine can do that alone.
+
+## The result
+
+`GetTickController` returns a [`TickControllerResult`](../api/sdk.md#tickcontrollerresult):
+
+- **`enabled`**: `true` sets a timer, and when it fires the next tick executes and `GetTickController` is called again to schedule the one after. `false` schedules nothing, and the game behaves as if it had no tick controller: ticks are manual only
+- **`intervalMs`**: milliseconds until the next automatic tick (`60_000` is one minute). Required when `enabled` is `true` and there is no `nextTickAt`; beside a `nextTickAt` it is only a display hint, and it may be left out when the timer is off
+- **`nextTickAt`**: when set, the next tick is scheduled at that absolute time instead of after `intervalMs` (see [Scheduling at fixed times](#scheduling-at-fixed-times))
+- **`complete`**: `true` permanently ends the game. No further ticks are allowed, manual or automatic, until the game is reset or undone (see [Game completion](#game-completion))
+
+Every duration is in milliseconds and every timestamp is milliseconds since the epoch.
+
+## Creating a tick controller
+
+```bash
+pnpm run sdk new tick_controller '{
+  "definition": {},
+  "logic": {
+    "directory": ".",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+This creates:
+
+```
+tick_controller/
+├── tick_controller.sdk.json   # Definition
+├── logic.ts                   # GetTickController function
+└── types.ts                   # Auto-generated
+```
+
+The bundle holds `reads`, `uses`, and `settings` (the settings resources it reads); `logic.ts` holds the `GetTickController` function.
+
+### Wiring it to a game
+
+Nothing to do: a package declares whatever is on disk, and a game uses whichever tick controller its package declares, so the directory `pnpm run sdk new tick_controller` created is the whole of the wiring. A package declares at most one.
+
+## Writing the logic
+
+The generated `tick_controller/logic.ts` exports a `GetTickController` function. Build interval-based results with `intervalTick(intervalMs)`, the sanctioned helper that validates the cadence for you. It takes **milliseconds**:
+
+```typescript
+import { GetTickControllerFunction, intervalTick } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+    context,
+    settings,
+}) => {
+    return intervalTick(60_000); // fire next tick in 60 seconds
+};
+```
+
+### Interval bounds
+
+The effective interval (the gap until the next automatic tick) is bounded: a minimum of 30 seconds and a maximum of 7 days. `intervalTick()` rejects anything outside that range, as well as fractional, zero, negative, `NaN`, and `Infinity` values, with a message that names the limit and points you back at the helper. A value written in seconds fails loudly: `intervalTick(60)` is 60 milliseconds, and is refused with 'Effective tick cadence of 60 ms (under a second) is below the 30-second minimum (30000 ms)'. The same bounds apply to `scheduledTick()` (see [Scheduling at fixed times](#scheduling-at-fixed-times)), measured against the real gap to `nextTickAt`. If a game needs to tick less often than once a week, set `enabled: false` and drive ticks by another means.
+
+### Cadence cookbook
+
+Common cadences, ready to drop into `GetTickController`:
+
+```typescript
+import { intervalTick, scheduledTick, nextDailyAt, nextWeeklyAt } from '@seriousgaming/sdk';
+
+// Every 30 seconds (the fastest allowed cadence)
+return intervalTick(30_000);
+
+// Every 5 minutes
+return intervalTick(5 * 60_000);
+
+// Every day at midnight UTC
+return scheduledTick(nextDailyAt(0, 0, { now: meta.now }));
+
+// Every Monday at 09:00 in New York
+return scheduledTick(nextWeeklyAt(1, 9, 0, { timezone: 'America/New_York', now: meta.now }));
+
+// Manual ticks only (no automatic timer)
+return { enabled: false };
+```
+
+### Returning a dynamic interval
+
+The function receives the capabilities it reads, so you can vary the interval based on state:
+
+```typescript
+export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+    context,
+    settings,
+}) => {
+    // Speed up as the game progresses, but never below the 30-second floor
+    const { CurrentTick } = context.progress;
+    const intervalMs = Math.max(
+        30_000,
+        settings.tick_controller.BaseIntervalMs - CurrentTick * 2_000
+    );
+
+    return intervalTick(intervalMs);
+};
+```
+
+### Disabling the timer conditionally
+
+Return `enabled: false` to switch to manual-only mode:
+
+```typescript
+export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+    context,
+    settings,
+}) => {
+    const { WaitingForInput } = context.progress;
+
+    return {
+        intervalMs: settings.tick_controller.TickIntervalMs,
+        enabled: !WaitingForInput,
+    };
+};
+```
+
+### Stopping the clock while the waiting room is open
+
+Opening the session's waiting room swaps every participant's game UI for the game's [waiting room UI](./waiting-room.md). It pauses nothing by itself (automatic ticks keep firing while participants wait), so if you want play genuinely halted, say so here:
+
+```typescript
+export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+    settings,
+    waitingRoomOpen,
+}) => {
+    return {
+        intervalMs: settings.tick_controller.TickIntervalMs,
+        enabled: !waitingRoomOpen,
+    };
+};
+```
+
+A controller also receives `participants`, the participants of every team in `teams`, so 'tick once everyone present has submitted' can count who is present without a roster in context, and `meta.now`, the instant the evaluation's operation started.
+
+`waitingRoomOpen` is on every `GetTickController` call, whether or not the game declares a waiting room UI. The decision sits here rather than in the runtime because only the author knows which kind of game this is: one where parking the session should stop the world, or one whose simulation should keep advancing in the background while participants are held. Without the check, a facilitator who parks a session for a ten-minute discussion returns to teams whose game has moved on without them.
+
+Combine it with your other conditions the usual way: `enabled: !waitingRoomOpen && !WaitingForInput`.
+
+## Reading capabilities
+
+Tick controllers can declare capabilities they read, just like the engine. This enables type-safe access to context variables and triggers `types.ts` generation.
+
+Reads do a second job here that they do not do for an engine: they decide when your controller runs again.
+
+### Declaring reads
+
+```bash
+pnpm run sdk new tick_controller '{
+  "definition": {
+    "reads": ["progress"]
+  },
+  "logic": {
+    "directory": ".",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+After running `pnpm run generate`, a `types.ts` file is created:
+
+```typescript
+// tick_controller/types.ts  (auto-generated)
+export interface Context {
+    progress: {
+        CurrentTick: number;
+        Phase: string;
+    };
+}
+export type Settings = Record<string, never>; // no settings declared
+```
+
+Import this in `logic.ts` for full type safety:
+
+```typescript
+import type { Context, Settings } from './types';
+```
+
+### Reads decide when you are called again
+
+Your controller runs after every tick. It also runs whenever a context write changes one of the capabilities you declared you read.
+
+That second rule is what makes conditions like 'tick as soon as every team has submitted' possible. Without it your controller would only ever see state as it stood after the previous tick, so a submission that should have triggered a tick would sit there until the next one came round anyway.
+
+```json
+{
+    "reads": ["decisions"]
+}
+```
+
+```typescript
+export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+    teams,
+}) => {
+    // Called again the moment any team writes `decisions`, so this answer is
+    // never more than a write behind. `teams` holds every team in a
+    // shared-state game, and the one team otherwise.
+    const waitingOn = teams.filter((t) => !t.context.decisions.Submitted).map((t) => t.teamId);
+    return { intervalMs: 60_000, enabled: waitingOn.length > 0 };
+};
+```
+
+**Declare no reads and you run on every write.** That is the right choice for a controller whose answer comes from somewhere other than context, such as one computing a deadline from the wall clock:
+
+```json
+{
+    "reads": []
+}
+```
+
+**The trap to know about.** If you compute a deadline from the wall clock **and** declare reads, you are called only when those reads change, so a deadline you would have recomputed on an unrelated write is not recomputed. In practice this rarely matters: the host schedules from the last answer you gave, and fires an immediate catch-up tick if the target has already passed. If you want to be called on every write regardless, declare no reads.
+
+**Why it is gated at all.** A re-run is an execution of your logic. Ungated, that is once per keystroke per participant, and in a large session most of those cannot change your answer: a controller that reads only a tick's outputs is unaffected by writes to that tick's decisions. Your `reads` declaration already says which is which, so nothing extra is needed from you.
+
+A re-run only recomputes timing. The engine does not run, no snapshot is taken, and the tick counter does not move. Returning `complete: true` from one still ends the game.
+
+A re-run that returns the same answer as before changes nothing: the countdown carries on, a facilitator's extension stands, and a paused timer keeps the time it had left. Only a different answer starts a new window, so a write that switches the timer on or changes `intervalMs` takes effect at once, while a busy team writing all round cannot push its own tick back.
+
+## Adding settings
+
+If your tick controller's interval or behaviour needs to be tunable per game, put the value in a settings resource and list it in the controller's `settings`:
+
+```bash
+pnpm run sdk new settings '{
+  "definition": {
+    "identifier": "tick_controller",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "TickIntervalMs": { "type": "integer", "default": 60000, "minimum": 30000 }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+
+pnpm run sdk new tick_controller '{
+  "definition": { "settings": ["tick_controller"] },
+  "logic": {
+    "directory": ".",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+Then use `settings.tick_controller.TickIntervalMs` in your logic. Naming the unit in the setting keeps a facilitator from typing seconds where milliseconds are meant. It resolves like any setting, under the settings identifier `tick_controller` (see [Overriding settings](./settings.md#overriding-settings)). Naming the settings resource after the slot is a convention, not a rule: a controller can read the engine's settings too, by listing them (`"settings": ["engine", "tick_controller"]`).
+
+## Game completion
+
+A game ends after its `maxTicks`, or earlier when something declares it complete. A game that ends because a condition is met (a revenue target reached, a resource depleted, a deadline passed) rather than after a fixed count is a goal-based game, and there are two ways to build one.
+
+### From the engine
+
+For most goal-based games the simpler route is the engine's own `complete`, returned from `Run`. It needs no tick controller at all:
+
+```typescript
+export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
+    const next = { ...context /* ...this round's updates */ };
+    return {
+        capabilities: next,
+        complete: next.financials.Profit >= settings.goal.ProfitTarget,
+    };
+};
+```
+
+`complete: true` ends the game for the team this `Run` ran for. In an independent game each team finishes on its own; in a shared-state game one team's completion ends it for every team, because they share one clock. An aggregate engine returns `complete` under `shared` to end it for every team, or on a `teams` entry to end it for that team alone. `complete: false`, or leaving it out, carries on: completion cannot be withdrawn this way.
+
+### From the tick controller
+
+The engine's `complete` is read at a tick, so a goal reached by a participant's write between ticks ends the game at the next tick. Reach for the controller's `complete` when the game must end on the write itself: the runtime calls the tick controller again after a write that changes a capability it reads (see [Reads decide when you are called again](#reads-decide-when-you-are-called-again)), so it can end the game there and then.
+
+```typescript
+export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+    context,
+    settings,
+}) => {
+    const profit = context.financials?.Profit ?? 0;
+    return { enabled: false, complete: profit >= settings.tick_controller.ProfitTarget };
+};
+```
+
+With the timer off, `intervalMs` can be left out. A controller that also times ticks passes `complete` to the helpers instead: `intervalTick(60_000, { complete })` and `scheduledTick(nextTickAt, { complete })`.
+
+### Leaving out `maxTicks`
+
+A goal-based game can omit `maxTicks` from `seriousgaming.sdk.json` entirely:
+
+```json
+{
+    "identifier": "com.example.goaldriven",
+    "supportedLocales": ["en"],
+    "locales": { "en": { "name": "Goal Driven" } }
+}
+```
+
+Or keep `maxTicks` as a safety ceiling: both apply, and whichever triggers first ends the game.
+
+With neither `maxTicks` nor a tick controller, only the engine can end the game, by returning `complete: true` from `Run`. The build warns rather than failing, because it cannot see whether the engine ever does. A tick controller that exists only to report completion can be replaced by the engine's `complete`.
+
+### When a game is complete
+
+- The dev server rejects further tick requests, disables the dev drawer's **Tick** button, and reports the session as complete (`complete: true` on the state every client reads, including the output of `sdk tick` and `sdk view`)
+- A further `sdk tick` fails with `TICK_FAILED` (exit code 4) and the message 'The game is complete', or 'Team is already complete' for one team of an independent game
+- Undo and reset both clear the completion flag, so the game can tick again after either operation
+
+### `enabled: false` or `complete: true`
+
+| Behaviour          | `enabled: false` | `complete: true`             |
+| ------------------ | ---------------- | ---------------------------- |
+| Automatic timer    | Disabled         | Disabled                     |
+| Manual ticks       | Still allowed    | Rejected                     |
+| CLI ticks          | Still allowed    | Rejected (exit code 4)       |
+| After reset / undo | N/A              | Cleared, game can tick again |
+
+Use `enabled: false` when you want to pause automatic progression but still allow manual advancement. Use `complete: true` when the game is genuinely over.
+
+### Multi-team completion
+
+The tick controller always receives a `teams` argument, one `{ teamId, index, context }` entry per team the call covers, sorted by index: the same entry shape an aggregate engine's `teams` uses. In a shared-state game it holds every team, so you can check whether all teams (or any team) have reached the goal, and name the ones you are still waiting for by `teamId` or `index`. In an independent game each team has its own timer and its own controller call, so `teams` holds only that team. A single-team game gets one entry. Each `context` is projected onto the controller's declared `reads`, like its own `context`:
+
+```typescript
+export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+    settings,
+    teams,
+}) => {
+    // The game ends when every team hits the target
+    const allDone = teams.every(
+        (t) => (t.context.financials?.Profit ?? 0) >= settings.tick_controller.ProfitTarget
+    );
+    return { enabled: false, complete: allDone };
+};
+```
+
+A game that ends this way can leave `maxTicks` out of `seriousgaming.sdk.json` altogether, so the controller is the only thing that completes it.
+
+## How timing works
+
+`GetTickController` is called **after each tick completes** (including the initialisation tick), and again after a write that changes a capability it reads. This means:
+
+1. The initial game state is fully set up before any timing decisions are made
+2. Every tick updates context before the next interval is calculated
+3. Manual ticks reset the countdown: returning `enabled: true` does not disable manual ticks, and after each one the timer restarts from the new answer
+
+If a timer fires while a tick is still executing, the timer firing is dropped. The timer reschedules itself once the running tick completes, so ticks never stack up.
+
+Each call has a time limit, like an engine call (see [Time limits](./engine.md#time-limits)).
+
+### Results outside the bounds
+
+A result the helpers would refuse, such as a hand-written `intervalMs: 10_000`, is not honoured as it stands. The dev server clamps it to the nearest bound, 30 seconds or 7 days, and reports the clamp as an error so you see it, which is what a production runtime does too. Build your results with `intervalTick()` and `scheduledTick()` to catch this while you write the controller rather than while it runs.
+
+A result holds only `enabled`, `intervalMs`, `nextTickAt` and `complete`, and `enabled` and `complete` are booleans. A result with any other key, or with `complete: 'no'`, is not clamped: the evaluation fails, the failure is reported naming the key, and the timer stops, as it does when the controller throws.
+
+## Pausing, resuming and extending
+
+A facilitator controls the timer from the session UI. Under `sdk dev` you can also drive it from the dev drawer's Session tab, or from the command line with [`sdk timer`](../cli-reference.md#the-tick-timer):
+
+| Control       | Effect                                                                                                                                                                                 |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pauseTimer`  | Stops the automatic timer. Manual ticks still work                                                                                                                                     |
+| `resumeTimer` | Restarts it. An interval schedule continues from the time that was left; a `nextTickAt` schedule asks `GetTickController` again, so a target that passed during the pause is not fired |
+| `extendTick`  | Moves the scheduled tick by a number of milliseconds, forwards or back, for this tick only. The interval your controller returns for later ticks is untouched                          |
+
+Each takes an optional team. In an independent game every team has its own timer, and leaving the team out applies the control to all of them.
+
+```bash
+pnpm run sdk timer                      # what the timer is doing
+pnpm run sdk timer pause
+pnpm run sdk timer extend 120           # two more minutes (the CLI takes seconds)
+pnpm run sdk timer resume --team 2   # one team, in an independent game
+```
+
+The current schedule, a [`TimerState`](../api/sdk-ui.md#timerstate) with every duration and timestamp in milliseconds, is pushed to every game UI. UIs subscribe with `useUserInterfaceTimer` and render their own countdown or progress bar. See [Displaying the tick timer](./ui.md#displaying-the-tick-timer) in the user interfaces guide.
+
+## Testing without waiting
+
+A one-minute timer takes a minute to test, and the 30-second floor means none takes less. Start the dev server on a fake clock instead, and move time yourself:
+
+```bash
+pnpm run sdk dev --fake-clock
+pnpm run sdk clock advance 180   # three minutes: a one-minute timer ticks three times
+```
+
+Time stands still until you move it, and `clock advance` runs every automatic tick that falls due on the way, so a test says how much time passes rather than sleeping for it. A paused timer does not tick however far you move the clock, and time only moves forward. From a Playwright test, post `{ "type": "advanceClock", "byMs": 180000 }` to `/api/command`.
+
+Your UIs count down against the browser's own clock, not the session's, so after an advance a countdown reads long by however far you moved it. The ticks, the tick count and `nextTickAt` are all the session's, and are right.
+
+## Scheduling at fixed times
+
+Instead of ticking on an interval ('every 60 seconds'), you can schedule ticks at specific wall-clock times ('every day at midnight'). Return `nextTickAt`, an absolute timestamp in milliseconds since epoch, and the runtime fires the tick at that exact time.
+
+There are two timing modes:
+
+- **Interval-based**: return an `intervalMs` in milliseconds. The next tick fires that long after the current tick completes. Good for simulations that run on a cadence
+- **Scheduled**: return a `nextTickAt` timestamp. The next tick fires at that exact wall-clock time. Good for games that tick at fixed times of day
+
+When `nextTickAt` is set, it takes precedence over `intervalMs`, which is then optional and only a display hint for UIs.
+
+The SDK provides helpers that compute the next occurrence of a daily or weekly time, with optional timezone support:
+
+### Daily schedule
+
+```typescript
+import { GetTickControllerFunction, nextDailyAt, scheduledTick } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+    settings,
+    meta,
+}) => {
+    // Tick once per day at the configured time
+    return scheduledTick(
+        nextDailyAt(settings.tick_controller.TickHour, settings.tick_controller.TickMinute, {
+            timezone: settings.tick_controller.Timezone,
+            now: meta.now,
+        })
+    );
+};
+```
+
+### Multiple times per day
+
+Use `nextDailyFromSchedule` to pick the soonest time from a list:
+
+```typescript
+import { nextDailyFromSchedule, scheduledTick } from '@seriousgaming/sdk';
+
+// Tick at 09:00 and 17:00 UTC every day
+return scheduledTick(
+    nextDailyFromSchedule(
+        [
+            { hours: 9, minutes: 0 },
+            { hours: 17, minutes: 0 },
+        ],
+        { now: meta.now }
+    )
+);
+```
+
+### Weekly schedule
+
+```typescript
+import { nextWeeklyAt, scheduledTick } from '@seriousgaming/sdk';
+
+// Tick every Monday at 09:00 in New York
+return scheduledTick(nextWeeklyAt(1, 9, 0, { timezone: 'America/New_York', now: meta.now }));
+```
+
+### Timezone support
+
+Pass `now: meta.now` to every schedule helper, so the next tick is computed from the operation's time rather than the host clock. All schedule helpers also accept an optional `timezone` parameter using IANA timezone names. DST transitions are handled automatically: the helpers always return the correct UTC timestamp for the next occurrence of the target wall-clock time.
+
+```typescript
+// Midnight in Sydney: resolves to 14:00 UTC (AEST) or 13:00 UTC (AEDT)
+nextDailyAt(0, 0, { timezone: 'Australia/Sydney', now: meta.now });
+```
+
+Put the timezone in the tick controller's settings to make it configurable per game, so facilitators can set the schedule to match their participants' timezone.
+
+### How `scheduledTick` works
+
+`scheduledTick(nextTickAt)` builds a complete `TickControllerResult`:
+
+```typescript
+{
+    enabled: true,
+    intervalMs: /* computed milliseconds until nextTickAt */,
+    nextTickAt: /* the timestamp you passed in */,
+}
+```
+
+The `intervalMs` field is computed for you, so a UI drawing a progress bar has the window's full length to draw against.
+
+`scheduledTick()` validates the effective cadence (the real gap to `nextTickAt`) against the same 30-second floor and 7-day ceiling as `intervalTick()`. A schedule that would tick sooner than 30 seconds out, or further than 7 days out, is rejected with a clear message rather than honoured. A `nextTickAt` already in the past is exempt: it fires one immediate catch-up tick (see [Missed ticks](#missed-ticks)).
+
+### Missed ticks
+
+If the server was down when a scheduled tick should have fired, the runtime detects that `nextTickAt` is in the past and fires one tick immediately. The tick controller then re-evaluates and returns the next future target time.
+
+### Pause and resume
+
+Pause/resume behaves differently for scheduled ticks than for interval-based ticks:
+
+| Scenario                           | Interval mode                 | Scheduled mode (`nextTickAt`)           |
+| ---------------------------------- | ----------------------------- | --------------------------------------- |
+| Resume after short pause           | Continues from remaining time | Re-evaluates against current wall clock |
+| Resume after scheduled time passed | N/A                           | Skips to next future occurrence         |
+| Server was down at scheduled time  | N/A                           | Fires immediately on restart            |
+
+When a facilitator pauses a scheduled game and resumes after the scheduled time has passed, the missed tick is **not** fired. The tick controller re-evaluates and returns the next future occurrence. This is intentional: pausing is an explicit 'stop the game' action.
+
+This is different from a server outage, where `nextTickAt` is in the past and the runtime fires one tick immediately to catch up.
+
+## Updating a tick controller
+
+A game holds one tick controller, in the `tick_controller/` slot, and the slot is its identifier. There is nothing to name and nothing to rename, so `update` takes only the change:
+
+```bash
+# Patch one field
+pnpm run sdk update tick_controller --patch '[
+  { "op": "replace", "path": "/definition/reads", "value": ["progress"] }
+]'
+
+# Replace the whole definition
+pnpm run sdk update tick_controller '{
+  "definition": { "reads": ["progress"] },
+  "logic": { "directory": ".", "entrypoint": "logic.ts" },
+  "rootDirectory": "."
+}'
+```
+
+There is no interactive mode: with nothing to name and nothing to pick, the
+command prints these two invocations instead of prompting.
+
+## Deleting a tick controller
+
+```bash
+pnpm run sdk delete tick_controller
+```
+
+This empties the `tick_controller/` slot. A package declares whatever is on disk, so removing the directory is the whole of the removal: there is no reference anywhere to clear.
+
+## Best practices
+
+1. **Start with a fixed interval.** Get the game working first, then add dynamic timing
+2. **Use `enabled: false` over a very long interval.** It is more explicit, and it disables UI timer indicators
+3. **Keep logic simple.** `GetTickController` runs frequently, and each call has a time limit (see [Time limits](./engine.md#time-limits)); avoid expensive operations
+4. **Use settings for the interval.** They make the interval easy to tune per game without changing code
+
+## Next steps
+
+- [End a game when a condition is met](../recipes/end-game-on-condition.md): the goal-based game, step by step
+- [Shaping games](./games.md): what a game declares, including `maxTicks`
+- [Type safety](./type-safety.md): understanding generated `types.ts` files
+- [Create a tick controller](../recipes/create-tick-controller.md): quick step-by-step recipe