@kradle/challenges-sdk 0.11.0 → 0.13.0

package/dist/runtime/types.d.ts

@@ -0,0 +1,963 @@
+import type { Duration, Ticks } from "./time.js";
+import type { BlockId, Box, EffectId, EndReason, EntityTypeId, ItemId, ItemMeta, ItemStack, Json, GameMode, Marker, SdkEndState, Status, Vec3 } from "./wire.js";
+import type { Entity, EntityFilter, Equipment } from "./world.js";
+/** A per-run parameter the configuration declares; a job may override its default. */
+export type ParamSpec = 
+/** A number, with its default. */
+{
+    type: "number";
+    /** The value when the job sets none. */
+    default: number;
+}
+/** A string, with its default. */
+ | {
+    type: "string";
+    /** The value when the job sets none. */
+    default: string;
+}
+/** A boolean, with its default. */
+ | {
+    type: "boolean";
+    /** The value when the job sets none. */
+    default: boolean;
+};
+/** The shape of config.ts that the runtime reads. Roles, end states, locations and params become literal types. */
+export interface ChallengeConfig {
+    /** The challenge's display name. */
+    name: string;
+    /** The roles by id. The keys become the `role` literal type. */
+    roles: Record<string, {
+        /** What the role does, shown to the player. */
+        description?: string;
+        /** The role's task text, shown to the player. */
+        specificTask?: string;
+        /** The seats the run must fill for this role. */
+        minParticipants?: number;
+    }>;
+    /** The execution configuration. The `locations` names become a literal type. */
+    challengeConfig: {
+        /** The named locations, by name; the run supplies their coordinates. */
+        locations?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    /** The end states a challenge may report: a list, or a record of id to description. */
+    endStates?: readonly string[] | Record<string, string>;
+    /** The per-run parameters, with their defaults. */
+    params?: Record<string, ParamSpec>;
+}
+/** The role ids of a configuration, as a literal type. */
+export type RoleOf<C extends ChallengeConfig> = keyof C["roles"] & string;
+/** The end state ids of a configuration, as a literal type; `string` when none are declared. */
+export type EndStateOf<C extends ChallengeConfig> = C["endStates"] extends readonly (infer E)[] ? E & string : C["endStates"] extends Record<infer K, string> ? K & string : string;
+/** The location names of a configuration, as a literal type; `never` without locations. */
+export type LocationOf<C extends ChallengeConfig> = C["challengeConfig"] extends {
+    locations: infer L;
+} ? keyof L & string : never;
+/** The resolved parameter values of a configuration: each `type` becomes its primitive type. */
+export type ParamsOf<C extends ChallengeConfig> = C["params"] extends Record<string, ParamSpec> ? {
+    [K in keyof C["params"]]: C["params"][K] extends {
+        type: "number";
+    } ? number : C["params"][K] extends {
+        type: "string";
+    } ? string : boolean;
+} : Record<string, never>;
+/**
+ * The vote `skills.voteForPlayer` casts in. Its options are the other participants' names, so it
+ * declares no `options`: `votes: { player: { final: true } }`.
+ */
+export declare const PLAYER_VOTE = "player";
+/** The part of a vote declaration that makes types: the options. */
+export type VoteOptionsDecl = {
+    readonly options?: readonly string[] | undefined;
+};
+/** The votes of a declaration, by id. */
+export type VotesDecl = Record<string, VoteOptionsDecl>;
+/** The vote ids of a declaration, as a literal type. */
+export type VoteIdOf<V extends VotesDecl> = keyof V & string;
+/** The option type of one vote: a participant name for the player vote, that vote's declared options otherwise. */
+export type OptionFor<V extends VotesDecl, Id> = Id extends typeof PLAYER_VOTE ? string : Id extends keyof V ? V[Id] extends {
+    readonly options: readonly (infer O)[];
+} ? O & string : never : never;
+/** One vote's rules. `options` are the choices; the `player` vote has none. */
+export interface VoteRule<R, Pl, O extends string> {
+    /** `true` (the default): one vote per open round. `false`: a new vote replaces the old one until the round closes. */
+    final?: boolean;
+    /** `false` (the default): an eliminated player's vote is refused. */
+    allowEliminated?: boolean;
+    /** The `player` vote only. `false` (the default): a player cannot vote for themself. */
+    allowSelf?: boolean;
+    /** The challenge's veto, a pure predicate. `true` accepts; a string refuses with that feedback to the voter. */
+    accept?: (g: R, voter: Pl, option: O) => true | string;
+}
+/** Read-only through every level: the engine writes the observations, a rule reads them. */
+export type DeepReadonly<X> = X extends (infer E)[] ? ReadonlyArray<DeepReadonly<E>> : X extends (...args: never[]) => unknown ? X : X extends object ? {
+    readonly [K in keyof X]: DeepReadonly<X[K]>;
+} : X;
+/** The roster facts of a participant: fixed for the run. */
+export interface Roster<C extends ChallengeConfig, R extends RoleOf<C> = RoleOf<C>> {
+    /** The player's name, unique in the run. */
+    readonly name: string;
+    /** The role the run assigned. */
+    readonly role: R;
+    /** One-based, from the run's participant list; stable for the run. */
+    readonly seatNumber: number;
+    /** `true` for a human participant, `false` for an agent. */
+    readonly human: boolean;
+}
+/** What the engine reports about a participant. A rule reads these; the SDK writes them. */
+export interface Observed {
+    /** Whether the player is online. */
+    readonly connected: boolean;
+    /** Whether the player is alive; `false` between a death and the respawn. */
+    readonly alive: boolean;
+    /** Whether the player left the game: a death under `life: "single"`, or `g.eliminate`. */
+    readonly eliminated: boolean;
+    /** `true` while the player is in the game: not eliminated. */
+    readonly isActive: boolean;
+    /** How many times the player died. */
+    readonly deaths: number;
+    /** How many participants the player killed. */
+    readonly kills: number;
+    /** The reported score: derived by `outcome.scores`, or set with `g.setScore` / `g.addScore`. */
+    readonly score: number;
+    /** The position, in blocks. Set from the first sample onward; a disconnected player keeps the last one. */
+    readonly pos: Readonly<Vec3>;
+    /** Degrees, Minecraft convention. */
+    readonly yaw: number;
+    /** Degrees, Minecraft convention. */
+    readonly pitch: number;
+    /** Degrees, Minecraft convention. */
+    readonly headYaw: number;
+    /** The server's entity id; `null` before the first sample. */
+    readonly entityId: number | null;
+    /** The player's uuid; `null` before the first sample. */
+    readonly uuid: string | null;
+    /** Worn and held items by slot (main, off, head, chest, legs, feet). */
+    readonly equipment: DeepReadonly<Equipment>;
+    /** Whether the player is invisible. */
+    readonly invisible: boolean;
+    /** Half-hearts. */
+    readonly health: number;
+    /** The food level, 0..20. */
+    readonly food: number;
+    /** The game mode. */
+    readonly gamemode: GameMode;
+    /** The item in the main hand; `null` for an empty hand. */
+    readonly held: ItemId | null;
+    /** Inventory by slot: 0-35 main (0-8 hotbar), 36-39 armor, 40 offhand. */
+    readonly slots: DeepReadonly<Record<number, ItemStack>>;
+    /** Item counts over every slot, by item id. */
+    readonly inventory: DeepReadonly<Record<string, number>>;
+    /** The declared zones the player stands in. */
+    readonly zones: readonly string[];
+}
+/** A participant as the state initializers see it: the roster and the observations, no state yet. */
+export type ObservedPlayer<C extends ChallengeConfig, R extends RoleOf<C> = RoleOf<C>> = Roster<C, R> & Observed;
+/** The challenge's per-player state, resolved for every role of the config. */
+export type PlayerMap<C extends ChallengeConfig> = {
+    [R in RoleOf<C>]: object;
+};
+/** The map `player` (shared) and `players` (per role) declare: a role without its own entry gets the shared state. */
+export type ResolvePlayers<C extends ChallengeConfig, P extends object, PS> = {
+    [R in RoleOf<C>]: R extends keyof PS ? (PS[R] extends object ? PS[R] : P) : P;
+};
+/** One participant of role `R` in a handler: the observations plus its own writable `state`. */
+export type PlayerOf<C extends ChallengeConfig, PM extends PlayerMap<C>, R extends RoleOf<C>> = ObservedPlayer<C, R> & {
+    /** The challenge's own data for this player, from the initializer; a handler writes it. */
+    readonly state: PM[R];
+};
+/** The same participant in a pure callback: its `state` is read-only too. */
+export type ReadPlayerOf<C extends ChallengeConfig, PM extends PlayerMap<C>, R extends RoleOf<C>> = ObservedPlayer<C, R> & {
+    /** The challenge's own data for this player, read-only here. */
+    readonly state: DeepReadonly<PM[R]>;
+};
+/**
+ * A participant: one member per role, discriminated by `role`, so `p.role === "p1"`
+ * narrows to that role's state (an inferred type predicate does the same in `filter`).
+ */
+export type Player<C extends ChallengeConfig, PM extends PlayerMap<C> = PlayerMap<C>> = {
+    [R in RoleOf<C>]: PlayerOf<C, PM, R>;
+}[RoleOf<C>];
+/** A participant in a pure callback: its `state` is read-only. */
+export type ReadPlayer<C extends ChallengeConfig, PM extends PlayerMap<C> = PlayerMap<C>> = {
+    [R in RoleOf<C>]: ReadPlayerOf<C, PM, R>;
+}[RoleOf<C>];
+/** A player, or anything named like one: what a message target, a log line or a winner check takes. */
+export type Named = {
+    /** The player's name. */
+    readonly name: string;
+};
+/** The player type a context works with: `type Pl = PlayerIn<G>`. */
+export type PlayerIn<Cx> = Cx extends {
+    readonly players: ReadonlyArray<infer Pl>;
+} ? Pl : never;
+/** An observed block: the id and its state properties, e.g. `{ id: "minecraft:oak_stairs", props: { facing: "east" } }`. */
+export interface BlockState {
+    /** The block id, without the state: `minecraft:oak_stairs`. */
+    readonly id: BlockId;
+    /** The state properties, e.g. `{ facing: "east" }`; empty for a block without state. */
+    readonly props: Readonly<Record<string, string>>;
+}
+/** A block to place: an id, or an id with state properties and block entity data (SNBT, for a banner or a sign). */
+export type BlockSpec = BlockId | {
+    /** The block id. */
+    id: BlockId;
+    /** The state properties to set, e.g. `{ facing: "east" }`. */
+    props?: Record<string, string>;
+    /** The block entity data, as SNBT (a sign's text, a banner's patterns). */
+    blockEntity?: string;
+};
+/** A block predicate: an id (any state), an id with the properties that must match, or a function over the state. */
+export type BlockMatch = BlockId | {
+    /** The block id. */
+    id: BlockId;
+    /** The properties that must match; the block may have more. */
+    props?: Record<string, string>;
+} | ((state: BlockState) => boolean);
+/** An item to give or put in a container: an id, or an id with a count and metadata. */
+export type ItemRequest = ItemId | ({
+    /** The item id. */
+    id: ItemId;
+    /** How many; default 1. */
+    count?: number;
+    /** Raw item data (SNBT), merged with the metadata fields. */
+    snbt?: string;
+} & ItemMeta);
+/** An item predicate for counts: an id, or an id with the metadata that must match. */
+export type ItemMatch = ItemId | ({
+    /** The item id. */
+    id: ItemId;
+} & ItemMeta);
+/** Integer block coordinates. `toBlockPos` floors a position. */
+export type BlockPos = {
+    /** East. */
+    x: number;
+    /** Up. */
+    y: number;
+    /** South. */
+    z: number;
+};
+/** The run's seeded generator. Every draw advances the state in the reducer, so a replay draws the same values. */
+export interface Random {
+    /** A whole number between `lo` and `hi`, both inclusive. */
+    int(lo: number, hi: number): number;
+    /** One element; `undefined` for an empty list. */
+    pick<X>(items: readonly [X, ...X[]]): X;
+    /** One element; `undefined` for an empty list. */
+    pick<X>(items: readonly X[]): X | undefined;
+    /** A new array with the elements in random order. */
+    shuffle<X>(items: readonly X[]): X[];
+    /** One element, weighted; `undefined` when the weights sum to zero. */
+    weighted<X>(items: ReadonlyArray<{
+        /** The relative weight; 0 never picks the element. */
+        weight: number;
+        /** The element. */
+        value: X;
+    }>): X | undefined;
+}
+/** What the state initializers receive. Not a context: the state does not exist yet. */
+export interface Init<C extends ChallengeConfig> {
+    /** The run's parameter values: the job's overrides over the configuration's defaults. */
+    readonly params: ParamsOf<C>;
+    /** The seeded generator. Closed after the initializers: keep the values, not the generator. */
+    readonly random: Random;
+    /** The observed roster, positions included, no state yet. */
+    readonly players: ReadonlyArray<ObservedPlayer<C>>;
+    /** The declared locations of the configuration, by name. */
+    readonly locations: Readonly<Record<LocationOf<C>, Vec3>>;
+}
+/** What the game-over hook and the judge data receive: frozen when the game ended. */
+export interface Result<C extends ChallengeConfig> {
+    /** The winners' names, as `game_over` carries them. */
+    readonly winners: readonly string[];
+    /** A declared end state, an SDK error state, or "" when no end state was classified. */
+    readonly endState: EndStateOf<C> | SdkEndState | "";
+    /** Why the game ended: a rule, the time, a phase's `"END"`, `endGame`, or an error. */
+    readonly reason: EndReason;
+    /** The phase the game ended in; `null` without phases. */
+    readonly phase: string | null;
+    /** Ticks from game start to the end. */
+    readonly elapsed: Ticks;
+    /** Ticks from the last phase entry to the end. */
+    readonly phaseElapsed: Ticks;
+    /** Whether the player is in `winners`. */
+    isWinner(player: Named): boolean;
+}
+/** Who receives a message: one player, several, or `"all"`. */
+export type To<Pl> = Pl | readonly Pl[] | "all";
+/** What `g.title` shows. */
+export type TitleOptions = {
+    /** The main line. */
+    title: string;
+    /** The smaller line under the title. */
+    subtitle?: string | undefined;
+    /** Fade-in time. Default 10 ticks. */
+    fadeIn?: Duration | undefined;
+    /** Time on the screen. Default 70 ticks. */
+    stay?: Duration | undefined;
+    /** Fade-out time. Default 20 ticks. */
+    fadeOut?: Duration | undefined;
+};
+/** The state type a context exposes: writable in a handler, read-only in a pure callback. */
+type StateFor<G, W extends boolean> = W extends true ? G : DeepReadonly<G>;
+type PlayerFor<C extends ChallengeConfig, PM extends PlayerMap<C>, W extends boolean> = W extends true ? Player<C, PM> : ReadPlayer<C, PM>;
+type PlayerOfFor<C extends ChallengeConfig, PM extends PlayerMap<C>, R extends RoleOf<C>, W extends boolean> = W extends true ? PlayerOf<C, PM, R> : ReadPlayerOf<C, PM, R>;
+/**
+ * The reads every context has. `W` says whether the state and the players are writable
+ * (a handler) or read-only (a pure callback).
+ */
+export interface Reads<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string, V extends VotesDecl, W extends boolean> {
+    /** The shared challenge data. Read-only in a pure callback; a handler writes it. */
+    readonly state: StateFor<G, W>;
+    /** The run's parameter values. */
+    readonly params: ParamsOf<C>;
+    /** Every participant, in roster order. */
+    readonly players: ReadonlyArray<PlayerFor<C, PM, W>>;
+    /** The participants still in the game: not eliminated. */
+    readonly activePlayers: ReadonlyArray<PlayerFor<C, PM, W>>;
+    /** A participant by name; `undefined` for a name that is not a participant. */
+    player(name: string): PlayerFor<C, PM, W> | undefined;
+    /** The participants of one role, typed with that role's state. */
+    playersWithRole<R extends RoleOf<C>>(role: R): PlayerOfFor<C, PM, R, W>[];
+    /** The one participant of a role. Throws unless exactly one participant has it. */
+    playerWithRole<R extends RoleOf<C>>(role: R): PlayerOfFor<C, PM, R, W>;
+    /** The server tick, absolute. */
+    readonly tick: number;
+    /** Ticks since the game started. */
+    readonly elapsed: Ticks;
+    /** The stage: CONNECTING, SETUP, PLAYING, OVER. */
+    readonly status: Status;
+    /** The current phase; `null` before the first entry and without phases. */
+    readonly phase: Ph | null;
+    /** The entry number of the current phase: it grows at every transition (1 for the first phase), across all phases; 0 without a phase. */
+    readonly phaseEntry: number;
+    /** Ticks since the current phase was entered; 0 without a phase. */
+    readonly phaseElapsed: Ticks;
+    /** Ticks left in the current phase; `null` without a duration. */
+    readonly phaseRemaining: Ticks | null;
+    /** A declared location of the configuration. */
+    location(name: LocationOf<C>): Vec3;
+    /** Marker entities from `markers`: all of them, or those carrying `tag` exactly. */
+    markers(tag?: string): Marker[];
+    /** A declared zone by name, or any box: whether the block at the player's feet is inside. */
+    inZone(player: PlayerFor<C, PM, W>, zone: NoInfer<Z> | Box): boolean;
+    /** How many of an item a player holds over every slot. */
+    countItems(player: PlayerFor<C, PM, W>, item: ItemMatch): number;
+    /** The block id at `at` (`minecraft:oak_fence`); `undefined` outside the loaded chunks. */
+    blockAt(at: Vec3): BlockId | undefined;
+    /** The block with its state properties; `undefined` outside the loaded chunks. */
+    blockStateAt(at: Vec3): BlockState | undefined;
+    /** Whether the block at `at` matches. Throws `block_unknown` outside the loaded chunks. */
+    blockMatches(at: Vec3, match: BlockMatch): boolean;
+    /** The count of matching blocks in a box. Throws `block_unknown` when a chunk of the box is not loaded, unless `partial`. */
+    blockCount(box: Box, match: BlockMatch, opts?: {
+        /** `true`: count the loaded chunks only instead of throwing on an unloaded one. */
+        partial?: boolean;
+    }): number;
+    /** The positions of matching blocks in a box, up to `limit`. Throws like `blockCount`. */
+    findBlocks(box: Box, match: BlockMatch, opts?: {
+        /** At most this many positions. */
+        limit?: number;
+        /** `true`: search the loaded chunks only instead of throwing on an unloaded one. */
+        partial?: boolean;
+    }): BlockPos[];
+    /** Whether every chunk of the box is loaded in the mirror. */
+    regionLoaded(box: Box): boolean;
+    /** The world time of day, 0..24000. */
+    readonly worldTime: number;
+    /** Non-player entities: all, or those in a box, of a type, or with a tag (`"kradle.*"` matches a prefix). */
+    entities(filter?: EntityFilter): ReadonlyArray<DeepReadonly<Entity>>;
+    /** One entity by id; `undefined` when the mirror does not hold it. */
+    entity(id: string): DeepReadonly<Entity> | undefined;
+    /** The contents of a container the mirror holds, by item id; `undefined` for a block the mirror does not know. */
+    containerContents(at: Vec3): Readonly<Record<string, number>> | undefined;
+    /** The accepted votes of the current round: voter name to option. */
+    votes<Id extends VoteIdOf<V>>(voteId: Id): Readonly<Record<string, OptionFor<V, Id>>>;
+    /** One voter's option in the current round, or `undefined`. */
+    vote<Id extends VoteIdOf<V>>(player: Named, voteId: Id): OptionFor<V, Id> | undefined;
+    /** Whether a round of the vote is open. */
+    voteOpen(voteId: VoteIdOf<V>): boolean;
+    /** The counts per option, the leading options, and the active players who did not vote. */
+    tally<Id extends VoteIdOf<V>>(voteId: Id): {
+        /** Votes per option, for the options that got any. */
+        counts: Readonly<Record<string, number>>;
+        /** The options with the most votes; empty without a vote. */
+        leaders: OptionFor<V, Id>[];
+        /** The active players who did not vote in this round. */
+        abstaining: PlayerFor<C, PM, W>[];
+    };
+}
+/**
+ * The read-only context: every read, no write, no effect. The pure callbacks get it:
+ * `outcome.scores`, `outcome.endWhen`, `outcome.winners`, `outcome.endState`, `judgeContext`,
+ * a phase's `until`, a functional `duration` or `next`, a vote's `accept`.
+ */
+export interface ReadCtx<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string, V extends VotesDecl> extends Reads<C, G, PM, Ph, Z, T, V, false> {
+}
+/** The messages and metrics: what a notification-only callback may do. */
+export interface NotifyOps {
+    /** A public chat line. */
+    say(message: string): void;
+    /** A private chat line to one player, several, or all. */
+    tell(to: To<Named>, message: string): void;
+    /** A title on the screen. Durations default to the server's (10 ticks in, 70 stay, 20 out). */
+    title(to: To<Named>, options: TitleOptions): void;
+    /** A line in the run log; `player` attributes it, `data` goes along as JSON. */
+    log(message: string, opts?: {
+        /** The player the line is about; the run log files it under that participant. */
+        player?: Named | undefined;
+        /** JSON data along with the line. */
+        data?: Json | undefined;
+    }): void;
+    /** A metric of the run: the last value per name reaches the run result. Per player with `player`. */
+    setMetric(name: string, value: number, opts?: {
+        /** The player the metric belongs to; global without one. */
+        player?: Named | undefined;
+    }): void;
+    /** An achievement line in the run log. */
+    achievement(player: Named, id: string): void;
+}
+/** The notification context: reads plus messages and metrics. The game-over hook gets it. */
+export interface NotifyCtx<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string, V extends VotesDecl> extends ReadCtx<C, G, PM, Ph, Z, T, V>, NotifyOps {
+}
+/** The world effects: queued for the engine, applied on the next tick (in the setup batches during setup). */
+export interface EffectOps<C extends ChallengeConfig, PM extends PlayerMap<C>> {
+    /** Gives items to a player. `count` overrides the request's count. */
+    give(player: Player<C, PM>, item: ItemRequest, count?: number): void;
+    /** Removes items from a player's inventory: one item (up to `count`), or everything. */
+    clear(player: Player<C, PM>, item?: ItemId, count?: number): void;
+    /** Applies a status effect for `duration`. */
+    effect(player: Player<C, PM>, options: {
+        /** The status effect id, e.g. `minecraft:speed`. */
+        id: EffectId;
+        /** How long it lasts. */
+        duration: Duration;
+        /** The level minus one; default 0. */
+        amplifier?: number;
+    }): void;
+    /** Moves a player to `to`. */
+    teleport(player: Player<C, PM>, to: Vec3): void;
+    /** Kills a player. A death event follows. */
+    kill(player: Player<C, PM>): void;
+    /** Sets a player's game mode. */
+    gamemode(player: Player<C, PM>, mode: GameMode): void;
+    /** Sets a player attribute, e.g. `minecraft:generic.max_health`. */
+    attribute(player: Player<C, PM>, attribute: string, value: number): void;
+    /** Fills a box with one block. The mirror updates when the engine reports the fill. */
+    fill(from: Vec3, to: Vec3, block: BlockSpec): void;
+    /** Sets one block. The mirror updates when the engine reports the change. */
+    setBlock(at: Vec3, block: BlockSpec): void;
+    /** Summons an entity; `nbt` is SNBT for its data. */
+    summon(entity: EntityTypeId, at: Vec3, opts?: {
+        /** The entity data, as SNBT (a name, tags, equipment). */
+        nbt?: string;
+    }): void;
+    /** Removes entities in the run's world; players are never removed. */
+    killEntities(entities?: EntityTypeId[]): void;
+    /** Sets the time of day. */
+    time(value: "day" | "noon" | "night" | "midnight"): void;
+    /** Sets a game rule, e.g. `doDaylightCycle`. */
+    gamerule(rule: string, value: boolean | number): void;
+    /** Sets the world spawn: participants respawn there, the watcher and spectators are moved there. */
+    setSpawn(at: Vec3): void;
+    /** Moves and resizes the world border; `over` animates the size change. */
+    worldBorder(opts: {
+        /** The new center. */
+        center?: {
+            /** East. */
+            x: number;
+            /** South. */
+            z: number;
+        };
+        /** The new diameter, in blocks. */
+        size?: number;
+        /** The time the size change takes; at once without it. */
+        over?: Duration;
+    }): void;
+    /** Replaces the contents of a chest or other container block. */
+    container(at: Vec3, items: ItemRequest[]): void;
+    /**
+     * The escape hatch. Logged. Prefer a typed method. The arena runs only the gameplay commands on its
+     * allowlist (no `fill`, `setblock`, `clone`, `place`, `data`, `item`, `forceload`: a command fires no
+     * block event, so the mirror would miss it); a refused command comes back as `effectFailed`.
+     */
+    command(cmd: string): void;
+}
+/** The setup context: every read, every message, every world effect, the state writes. No phase, end, timer, vote or walk. */
+export interface SetupCtx<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string, V extends VotesDecl> extends Reads<C, G, PM, Ph, Z, T, V, true>, NotifyOps, EffectOps<C, PM> {
+    /** Sets a player's score. Throws `score_derived` when `outcome.scores` computes the scores. */
+    setScore(player: Player<C, PM>, score: number): void;
+    /** Adds to a player's score. Throws `score_derived` when `outcome.scores` computes the scores. */
+    addScore(player: Player<C, PM>, delta: number): void;
+    /** Removes a player from the game (spectator). `isActive` becomes false. */
+    eliminate(player: Player<C, PM>): void;
+    /** The run's seeded generator. Every draw advances the state, so a replay draws the same values. */
+    readonly random: Random;
+}
+/** The gameplay context: everything, including the phase and end requests, timers, votes, walks and batches. */
+export interface Ctx<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string, V extends VotesDecl> extends SetupCtx<C, G, PM, Ph, Z, T, V> {
+    /**
+     * Requests a phase: exit the current phase, enter `phase`. An event's handlers form one group
+     * (every global `on` in order, then the phase's): the request applies once the group returned,
+     * so a later handler of the same event still sees the current phase, and a second request in
+     * the group throws `phase_twice`. A request from `enter` applies after `enter` (a chain, up to
+     * the budget of 8 per event). Not available in `exit` or in a pure callback.
+     */
+    startPhase(phase: Ph): void;
+    /** Ends the current phase through its `next`. Throws without a `next`. */
+    endPhase(): void;
+    /** Requests the end of the game. Later callbacks of this event are skipped; this callback continues. */
+    endGame(endState?: EndStateOf<C>): void;
+    /** A named timer. `on.timer({ name })` fires when it is due; scheduling again resets it. */
+    schedule(name: NoInfer<T>, after: Duration): void;
+    /** Cancels a scheduled timer. No effect when the timer is not scheduled. */
+    cancel(name: NoInfer<T>): void;
+    /** Opens a round of the vote and clears the previous votes. Throws `vote_open` when a round is open. */
+    openVote(voteId: VoteIdOf<V>): void;
+    /** Closes the round; the votes stay readable. */
+    closeVote(voteId: VoteIdOf<V>): void;
+    /** Clears the votes and starts a new round number, open or closed as before: a request stamped with the old round is refused. */
+    resetVote(voteId: VoteIdOf<V>): void;
+    /** The arena walks the bot; a failed walk teleports unless fallback is "none". `on.walkDone` reports. */
+    walk(player: Player<C, PM>, to: Vec3, opts?: {
+        /** What happens when the walk fails: a teleport to `to` (the default), or nothing. */
+        fallback?: "teleport" | "none";
+    }): void;
+    /** Effects queued inside `fn` go out as one named batch; `on.batchDone` reports. Throws `batch_pending` on a duplicate name. */
+    batch(name: string, fn: () => void): void;
+}
+type H<Cx, E> = (g: Cx, e: E) => void;
+/** Handlers receive resolved players. Events for names that are not participants never reach them. */
+export interface Handlers<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string, V extends VotesDecl> {
+    /** Every server tick (20 per second). */
+    tick?: (g: Ctx<C, G, PM, Ph, Z, T, V>) => void;
+    /** A participant connected. */
+    joined?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+    }>;
+    /** A participant disconnected. */
+    left?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+    }>;
+    /** One event per tick in which the player moved. */
+    move?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The position before. */
+        from: Vec3;
+        /** The position now. */
+        to: Vec3;
+    }>;
+    /** A participant took damage. `attacker` is set when another participant caused it. */
+    damaged?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The damage, in half-hearts. */
+        amount: number;
+        /** The damage cause, as the server names it. */
+        cause: string;
+        /** The participant who caused it, when one did. */
+        attacker?: Player<C, PM> | undefined;
+    }>;
+    /** A participant died. `killer` is set when another participant caused it. */
+    died?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The death cause, as the server names it. */
+        cause: string;
+        /** The participant who caused it, when one did. */
+        killer?: Player<C, PM> | undefined;
+    }>;
+    /** A participant respawned (`life: "respawn"`). */
+    respawned?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+    }>;
+    /** A non-player entity appeared in the mirror. */
+    entitySpawned?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The entity, as observed. */
+        entity: DeepReadonly<Entity>;
+    }>;
+    /** An entity's reported fields changed (health, tags, item, equipment). */
+    entityChanged?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The entity now. */
+        entity: DeepReadonly<Entity>;
+        /** The entity before the change. */
+        was: DeepReadonly<Entity>;
+    }>;
+    /** A non-player entity left the mirror: it died, or the server removed it. */
+    entityRemoved?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The entity's last observation. */
+        entity: DeepReadonly<Entity>;
+        /** Why: it died, or the server removed it. */
+        cause: "died" | "removed";
+        /** The participant who killed it, when one did. */
+        killer?: Player<C, PM> | undefined;
+    }>;
+    /** A participant picked an item up from the ground. */
+    pickup?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The item id. */
+        item: ItemId;
+        /** How many. */
+        count: number;
+        /** Where the item was. */
+        at: Vec3;
+    }>;
+    /** A participant's count of one item changed. */
+    inventory?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The item id. */
+        item: ItemId;
+        /** The count now. */
+        count: number;
+    }>;
+    /** A participant broke a block. The mirror already shows the block after the break. */
+    blockBroken?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The block position. */
+        at: Vec3;
+        /** The block state that was there. */
+        block: BlockState;
+    }>;
+    /** A participant placed a block. The mirror already shows the placed state. */
+    blockPlaced?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The block position. */
+        at: Vec3;
+        /** The placed block state. */
+        block: BlockState;
+    }>;
+    /** A participant right-clicked a block; `item` is what the hand held. */
+    blockUsed?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The block position. */
+        at: Vec3;
+        /** The block state. */
+        block: BlockState;
+        /** The item in the hand, when one. */
+        item?: ItemId | undefined;
+    }>;
+    /** A container's contents changed: the counts after the change and the deltas. `by` only when the engine is certain. */
+    container?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The container block. */
+        at: Vec3;
+        /** The container's block id. */
+        block: BlockId;
+        /** The counts per item id after the change. */
+        items: Readonly<Record<string, number>>;
+        /** The count deltas, per item. */
+        changes: Array<{
+            /** The item id. */
+            item: ItemId;
+            /** The count change; positive for items added. */
+            delta: number;
+        }>;
+        /** The participant who moved the items, when the engine is certain. */
+        by?: Player<C, PM> | undefined;
+        /** `true` when the container block is gone. */
+        removed: boolean;
+    }>;
+    /**
+     * Every block that changed this tick, whatever the cause. A fill is one entry with its `box`.
+     * The mirror already shows the new states.
+     */
+    blocksChanged?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The changes: one per block, or one per fill. */
+        changes: Array<(Vec3 & {
+            /** The block id now. */
+            block: BlockId;
+            /** The block id before, when known. */
+            was?: BlockId | undefined;
+            /** What changed it (break, place, burn, ...). */
+            cause?: string | undefined;
+            /** The participant who did it, when one did. */
+            by?: Player<C, PM> | undefined;
+        }) | {
+            /** The filled box. */
+            box: Box;
+            /** The block id now. */
+            block: BlockId;
+            cause: "fill";
+        }>;
+    }>;
+    /** A participant's feet entered a declared zone. */
+    zoneEntered?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The zone name. */
+        zone: Z;
+    }>;
+    /** A participant's feet left a declared zone. */
+    zoneLeft?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The zone name. */
+        zone: Z;
+    }>;
+    /** A participant sent a public chat line. */
+    chat?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The line. */
+        text: string;
+    }>;
+    /** A participant swung an arm: a mining or attack attempt (`swing`), or the off hand (`swing_off`). */
+    animation?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The arm: the main hand, or the off hand. */
+        animation: "swing" | "swing_off";
+    }>;
+    /** A participant's game mode changed. */
+    gamemode?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** The game mode now. */
+        gamemode: GameMode;
+    }>;
+    /** Accepted votes only. The SDK answered the rejected ones. */
+    vote?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        [Id in VoteIdOf<V>]: {
+            /** The voter. */
+            player: Player<C, PM>;
+            /** The vote. */
+            voteId: Id;
+            /** The accepted option. */
+            option: OptionFor<V, Id>;
+        };
+    }[VoteIdOf<V>]>;
+    /** A walk requested with `g.walk` ended. `ok` is `false` when the bot did not arrive. */
+    walkDone?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The participant. */
+        player: Player<C, PM>;
+        /** `true` when the bot arrived. */
+        ok: boolean;
+    }>;
+    /** A timer scheduled with `g.schedule` is due. */
+    timer?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The timer name. */
+        name: T;
+    }>;
+    /** A named batch ran. `failed` lists the effects the engine refused. */
+    batchDone?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The batch name. */
+        name: string;
+        /** Whether every effect applied. */
+        ok: boolean;
+        /** The effects the engine refused. */
+        failed: Array<{
+            /** The effect's index in the batch. */
+            index: number;
+            /** Why it failed. */
+            detail: string;
+        }>;
+    }>;
+    /** The engine refused one effect. `effect` echoes it; `batch` names the batch when it is still pending. */
+    effectFailed?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The effect kind. */
+        kind: string;
+        /** Why. */
+        detail: string;
+        /** The refused effect, as sent. */
+        effect?: unknown;
+        /** The batch it was in, when that batch is still pending. */
+        batch?: {
+            /** The batch name. */
+            name: string;
+            /** The effect's index in the batch. */
+            index: number;
+        } | undefined;
+    }>;
+    /** A server event the engine forwards by name, with its JSON data. */
+    custom?: H<Ctx<C, G, PM, Ph, Z, T, V>, {
+        /** The event name. */
+        name: string;
+        /** The participant it is about, when one. */
+        player?: Player<C, PM> | undefined;
+        /** The event's JSON data. */
+        data: Json;
+    }>;
+}
+/** One timed step of a phase: at `elapsed` since entry, or `remaining` before its end (needs a `duration`). */
+export type PhaseStep<Cx> = 
+/** Runs once, `elapsed` after the phase entry. */
+{
+    /** How long after the phase entry. */
+    elapsed: Duration;
+    /** Not with `elapsed`. */
+    remaining?: never;
+    /** What runs. */
+    run: (g: Cx) => void;
+}
+/** Runs once, `remaining` before the phase's timeout (the phase needs a `duration`). */
+ | {
+    /** How long before the phase's timeout. */
+    remaining: Duration;
+    /** Not with `remaining`. */
+    elapsed?: never;
+    /** What runs. */
+    run: (g: Cx) => void;
+};
+/** The behavior of one declared phase: how long it lasts, where it goes, and its handlers. */
+export interface PhaseSpec<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string, V extends VotesDecl> {
+    /**
+     * The phase's length. Without it and without `until`, the phase lasts one tick (a pass-through).
+     * A function is evaluated once, when the phase is entered.
+     */
+    duration?: Duration | ((g: ReadCtx<C, G, PM, Ph, Z, T, V>) => Duration);
+    /** Where the phase goes when it ends: a phase name, `"END"`, or a function of the read-only context. */
+    next: Ph | "END" | ((g: ReadCtx<C, G, PM, Ph, Z, T, V>) => Ph | "END");
+    /** The phase ends as soon as this holds. Evaluated after the handlers of every event. */
+    until?: (g: ReadCtx<C, G, PM, Ph, Z, T, V>) => boolean;
+    /** Runs when the phase is entered, after `duration` is resolved. */
+    enter?: (g: Ctx<C, G, PM, Ph, Z, T, V>) => void;
+    /** Runs when the phase is left, also when the game ends. No phase or end request inside it. */
+    exit?: (g: Ctx<C, G, PM, Ph, Z, T, V>) => void;
+    /** Once per phase entry. */
+    at?: Array<PhaseStep<Ctx<C, G, PM, Ph, Z, T, V>>>;
+    /** Repeating steps, counted from the phase entry. */
+    every?: Array<{
+        /** The time between two runs. */
+        interval: Duration;
+        /** What runs. */
+        run: (g: Ctx<C, G, PM, Ph, Z, T, V>) => void;
+    }>;
+    /** Handlers that run only in this phase, after the global `on` for the same event. */
+    on?: Handlers<C, G, PM, Ph, Z, T, V>;
+}
+/** How the game ends and who wins. The SDK computes all of it after every reduction; nothing here has effects. */
+export interface Outcome<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string, V extends VotesDecl> {
+    /**
+     * Derived scores: computed after every reduction, not only at the end. When present, `setScore`
+     * and `addScore` are refused. Pure: every evaluation reads the previous committed scores.
+     */
+    scores?: (g: ReadCtx<C, G, PM, Ph, Z, T, V>, player: ReadPlayer<C, PM>) => number;
+    /** The end rule, checked after every reduction. The game duration ends the game on its own. */
+    endWhen?: (g: ReadCtx<C, G, PM, Ph, Z, T, V>) => boolean;
+    /** The winners at the end. Default: no winner. */
+    winners?: (g: ReadCtx<C, G, PM, Ph, Z, T, V>) => ReadonlyArray<{
+        /** The player's name. */
+        name: string;
+    }>;
+    /** The end state at the end. Default: `""`. */
+    endState?: (g: ReadCtx<C, G, PM, Ph, Z, T, V>) => EndStateOf<C>;
+}
+/** World setup the SDK applies before the game. Every field but `spawn` has today's default; `false` skips all of it. */
+export interface World {
+    /** The world spawn: participants respawn there, the watcher and spectators are moved there. */
+    spawn?: Vec3;
+    /** The time of day set before the game. `false` leaves the world's time. Default `"day"`. */
+    time?: "day" | "noon" | "night" | "midnight" | false;
+    /** Whether the time of day advances. Default `false`. */
+    daylightCycle?: boolean;
+    /** Whether mobs spawn on their own. Default `false`. */
+    mobSpawning?: boolean;
+    /** Whether health regenerates from food. Default `true`. */
+    naturalRegeneration?: boolean;
+    /** The participants' maximum health, in half-hearts. `false` leaves the attribute. Default 20. */
+    maxHealth?: number | false;
+}
+/** The values `world` uses for the fields a declaration omits. */
+export declare const WORLD_DEFAULTS: Required<Omit<World, "spawn">>;
+/** The state initializers. `player` is the state of every role; `players` overrides it per role. */
+export interface StateDecl<C extends ChallengeConfig, G, P, PS> {
+    /** The shared data. Default: `{}`. */
+    game?: (init: Init<C>) => G;
+    /** The state of every participant, unless `players` names the role. Default: `{}`. */
+    player?: (player: ObservedPlayer<C>, init: Init<C>) => P;
+    /** The state per role; a role listed here does not use `player`. */
+    players?: {
+        [R in keyof PS]: (player: ObservedPlayer<C, R & RoleOf<C>>, init: Init<C>) => PS[R];
+    };
+}
+/**
+ * The root declaration of `defineChallenge(config, decl)`: data, the state initializers and pure
+ * predicates. No event handler lives here; the steps carry them.
+ */
+export interface Decl<C extends ChallengeConfig, G, P, PS, Ph extends string, Z extends string, T extends string, V extends VotesDecl> {
+    /** The state initializers. They run once, at the end of CONNECTING, with the observed roster. */
+    state?: StateDecl<C, G, P, PS>;
+    /** "single": one death eliminates (spectator). "respawn": deaths count, the player plays on. */
+    life: "single" | "respawn";
+    /** Time from game start to the end. Omit for no time limit. */
+    duration?: Duration;
+    /** World setup before the game (time, game rules, spawn). `false` skips it; omit for the defaults. */
+    world?: World | false;
+    /** Named boxes, evaluated every tick from the players' positions: `on.zoneEntered/zoneLeft`, `g.inZone`, `player.zones`. */
+    zones?: Record<Z, Box>;
+    /** Timer names for `g.schedule` / `on.timer`. */
+    timers?: readonly T[];
+    /** Tagged entities to read from the world before the game (`g.markers`). Chunks in `within` are loaded first. */
+    markers?: {
+        /** The scoreboard tags that mark an entity, matched exactly; a tag that ends with `*` is a prefix (`kradle.island.*` matches `kradle.island.north`). */
+        tags: string[];
+        /** The box the engine loads first, so far markers are found too. */
+        within?: Box;
+    };
+    /** The votes, with their options. The `player` vote declares none. */
+    votes?: V & {
+        [Id in keyof V]: VoteRule<ReadCtx<C, G, ResolvePlayers<C, P & object, PS>, Ph, Z, T, V>, ReadPlayer<C, ResolvePlayers<C, P & object, PS>>, OptionFor<V, Id>>;
+    };
+    /** The phase names. Each gets its behavior in a `.phase(name, {...})` step. */
+    phases?: readonly Ph[];
+    /** The phase the game starts in. Default: the first name of `phases`. */
+    initialPhase?: NoInfer<Ph>;
+}
+/** A callback registered from a rule: `(g, ...) => void`. */
+export type Step<Cx> = (g: Cx) => void;
+/** The context types of a challenge, for helpers: `type G = CtxOf<typeof challenge>`. */
+export type CtxOf<Ch> = Ch extends ChallengeApi<infer C, infer G, infer PM, infer Ph, infer Z, infer T, infer V> ? Ctx<C, G, PM, Ph, Z, T, V> : never;
+/** The read-only context of a challenge, for helpers used in pure callbacks. */
+export type ReadCtxOf<Ch> = Ch extends ChallengeApi<infer C, infer G, infer PM, infer Ph, infer Z, infer T, infer V> ? ReadCtx<C, G, PM, Ph, Z, T, V> : never;
+/** The setup context of a challenge, for helpers used in `.setup()`. */
+export type SetupCtxOf<Ch> = Ch extends ChallengeApi<infer C, infer G, infer PM, infer Ph, infer Z, infer T, infer V> ? SetupCtx<C, G, PM, Ph, Z, T, V> : never;
+/** The notification context of a challenge, for helpers used in `.onOver()`. */
+export type NotifyCtxOf<Ch> = Ch extends ChallengeApi<infer C, infer G, infer PM, infer Ph, infer Z, infer T, infer V> ? NotifyCtx<C, G, PM, Ph, Z, T, V> : never;
+/**
+ * The challenge object `defineChallenge` returns. Every step registers behavior and returns the
+ * same object, so a definition reads as one chain or as separate statements. `init()` locks it.
+ */
+export interface ChallengeApi<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string, V extends VotesDecl> {
+    /** The configuration the challenge was defined with. */
+    readonly config: C;
+    /** The declared zones, for tests. */
+    readonly zones: Readonly<Record<string, Box>>;
+    /** World build. Its effects go out as batches; the game starts after the engine confirms them all. */
+    setup(fn: Step<SetupCtx<C, G, PM, Ph, Z, T, V>>): this;
+    /** Runs on the first tick of PLAYING, after the setup batches are confirmed. */
+    start(fn: Step<Ctx<C, G, PM, Ph, Z, T, V>>): this;
+    /** The behavior of a declared phase. One step per phase name. */
+    phase(name: Ph, spec: PhaseSpec<C, G, PM, Ph, Z, T, V>): this;
+    /** One-shot steps after game start, `>=` semantics. */
+    at(steps: Array<{
+        /** When, after the game start. */
+        at: Duration;
+        /** What runs. */
+        run: Step<Ctx<C, G, PM, Ph, Z, T, V>>;
+    }>): this;
+    /** Repeating steps. After a gap they run once, not once per missed interval. */
+    every(steps: Array<{
+        /** The time between two runs. */
+        interval: Duration;
+        /** What runs. */
+        run: Step<Ctx<C, G, PM, Ph, Z, T, V>>;
+    }>): this;
+    /** Event handlers. Several calls add up, in call order. */
+    on(handlers: Handlers<C, G, PM, Ph, Z, T, V>): this;
+    /** The result rules. Required: `init()` refuses a challenge without it. */
+    outcome(outcome: Outcome<C, G, PM, Ph, Z, T, V>): this;
+    /** Runs once the result is frozen: messages and titles, no state writes. */
+    onOver(fn: (g: NotifyCtx<C, G, PM, Ph, Z, T, V>, result: Result<C>) => void): this;
+    /** An object sent with `game_over` for the LLM judge; the backend takes an object, not another JSON value. */
+    judgeContext(fn: (g: ReadCtx<C, G, PM, Ph, Z, T, V>, result: Result<C>) => Record<string, Json>): this;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map