@kradle/challenges-sdk 0.10.0 → 0.12.0

package/dist/runtime/sdk.d.ts

@@ -0,0 +1,1038 @@
+import { type BlockMatch, type Equipment, type ChunkMessage, type Entity, type EntityFilter, type EntityMove, type EquipmentChange, type OtherPlayer, type WorldState } from "./world.js";
+export type { BlockMatch, Chunk, ChunkMessage, Entity, EntityFilter, EntityMove, Equipment, EquipmentChange, EquipmentSlot, Equipped, OtherPlayer, Section, WorldState, } from "./world.js";
+export { applyEquipment, blockIdOf, bounds, inBox } from "./world.js";
+export type ParamSpec = {
+    type: "number";
+    default: number;
+} | {
+    type: "string";
+    default: string;
+} | {
+    type: "boolean";
+    default: boolean;
+};
+/** The shape of config.ts that the runtime reads. Roles, vote options, end states and params become literal types. */
+export interface ChallengeConfig {
+    name: string;
+    roles: Record<string, {
+        description?: string;
+        specificTask?: string;
+        minParticipants?: number;
+    }>;
+    challengeConfig: {
+        votingOptions?: Record<string, readonly string[]>;
+        locations?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    endStates?: readonly string[] | Record<string, string>;
+    params?: Record<string, ParamSpec>;
+}
+export type RoleOf<C extends ChallengeConfig> = keyof C["roles"] & string;
+export type VotingOptionsOf<C extends ChallengeConfig> = C["challengeConfig"] extends {
+    votingOptions: infer V;
+} ? V : Record<never, never>;
+/**
+ * The vote `skills.voteForPlayer` casts in. Its options are the other participants' names, so it
+ * needs no `votingOptions` entry: a challenge opens it with `votes: { player: {...} }`.
+ */
+export declare const PLAYER_VOTE = "player";
+export type VoteIdOf<C extends ChallengeConfig> = (keyof VotingOptionsOf<C> & string) | typeof PLAYER_VOTE;
+export type OptionOf<C extends ChallengeConfig> = VotingOptionsOf<C>[keyof VotingOptionsOf<C>] extends readonly (infer O)[] ? O & string : never;
+/** The option type of one vote: a participant name for the player vote, that vote's configured options otherwise. */
+export type OptionFor<C extends ChallengeConfig, V> = V extends typeof PLAYER_VOTE ? string : V extends keyof VotingOptionsOf<C> ? VotingOptionsOf<C>[V] extends readonly (infer O)[] ? O & string : never : never;
+export type EndStateOf<C extends ChallengeConfig> = C["endStates"] extends readonly (infer E)[] ? E & string : C["endStates"] extends Record<infer K, string> ? K & string : string;
+export type LocationOf<C extends ChallengeConfig> = C["challengeConfig"] extends {
+    locations: infer L;
+} ? keyof L & string : never;
+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>;
+declare const ticksBrand: unique symbol;
+/** A number of server ticks (20 per second). Made with seconds(), minutes() or ticks(). */
+export type Ticks = number & {
+    readonly [ticksBrand]: true;
+};
+/** "35s", "2m", "40t", or a Ticks value. A bare number is not a duration. */
+export type Duration = Ticks | `${number}s` | `${number}m` | `${number}t`;
+export declare const TICKS_PER_SECOND = 20;
+export declare const ticks: (n: number) => Ticks;
+export declare const seconds: (n: number) => Ticks;
+export declare const minutes: (n: number) => Ticks;
+/** The ticks of a duration: "35s", "2m", "40t" or a Ticks value. Throws on a negative, non-finite or malformed one. */
+export declare function toTicks(d: Duration): Ticks;
+/** `a + b`, as ticks. */
+export declare const addDuration: (a: Duration, b: Duration) => Ticks;
+/** `a - b`, as ticks, clamped at zero: a countdown that passed its deadline reads 0, not an error. */
+export declare const subtractDuration: (a: Duration, b: Duration) => Ticks;
+/** A duration in seconds (for messages): `asSeconds("90s")` is 90, `asSeconds(ticks(30))` is 1.5. */
+export declare const asSeconds: (d: Duration) => number;
+/** A duration in minutes (for messages): `asMinutes("90s")` is 1.5. */
+export declare const asMinutes: (d: Duration) => number;
+export type Vec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/** Block coordinates, both corners inclusive. A player is in a box when the block at their feet is inside. */
+export type Box = {
+    from: Vec3;
+    to: Vec3;
+};
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type Block = `minecraft:${string}`;
+export type Item = `minecraft:${string}`;
+export type EntityType = `minecraft:${string}`;
+export type EffectId = `minecraft:${string}`;
+export type GameMode = "survival" | "creative" | "adventure" | "spectator";
+export type Participant = {
+    name: string;
+    role: string;
+    human?: boolean;
+};
+/**
+ * A tagged entity the world carries (armor stands, markers): where a challenge finds its spawns and chest spots.
+ * `tags` are the entity's scoreboard tags; `g.markers(tag)` returns the markers that carry exactly that tag.
+ */
+export type Marker = {
+    type: EntityType;
+    at: Vec3;
+    name?: string | undefined;
+    tags: string[];
+};
+export type ContainerItem = {
+    slot?: number | undefined;
+    item: Item;
+    count: number;
+    nbt?: string | undefined;
+};
+/** Title timing in server ticks (20 per second), as `/title times`. */
+export type TitleTimes = {
+    fadeIn: number;
+    stay: number;
+    fadeOut: number;
+};
+/** What an engine can supply. The arena reports them in run_started; the SDK checks the challenge's needs against them. */
+export type Capability = "move" | "damage" | "death" | "pickup" | "inventory" | "blocks" | "zones" | "entities" | "custom" | "batch" | "query" | "walk" | "mirror" | "chat" | "lifecycle" | "requests" | "containers";
+export declare const ALL_CAPABILITIES: Capability[];
+export type Event = {
+    type: "run_started";
+    seed: number;
+    participants: Participant[];
+    params: Record<string, Json>;
+    capabilities: Capability[];
+    locations?: Record<string, Vec3> | undefined;
+    markers?: Marker[] | undefined;
+} | {
+    type: "tick";
+    serverTick: number;
+    /** Every online player whose sample changed since the previous tick; the first tick after configure has them all. */
+    players?: PlayerSample[] | undefined;
+    /** Entities that moved since the previous tick. */
+    entities?: EntityMove[] | undefined;
+    /** The world time of day, when it changed. */
+    time?: number | undefined;
+} | {
+    type: "player_joined";
+    name: string;
+    participant?: boolean | undefined;
+    uuid?: string | undefined;
+    id?: number | undefined;
+    gamemode?: GameMode | undefined;
+} | {
+    type: "gamemode";
+    name: string;
+    gamemode: GameMode;
+    uuid?: string | undefined;
+    participant?: boolean | undefined;
+} | {
+    type: "player_left";
+    name: string;
+    participant?: boolean | undefined;
+    uuid?: string | undefined;
+    id?: number | undefined;
+} | {
+    type: "player_moved";
+    name: string;
+    to: Vec3;
+    maxY: number;
+    minY: number;
+} | {
+    type: "player_damaged";
+    name: string;
+    amount: number;
+    cause: string;
+    attacker?: string | undefined;
+} | {
+    type: "player_died";
+    name: string;
+    cause: string;
+    killer?: string | undefined;
+} | {
+    type: "player_respawned";
+    name: string;
+} | {
+    type: "item_picked_up";
+    name: string;
+    item: Item;
+    count: number;
+    at: Vec3;
+} | {
+    type: "inventory";
+    name: string;
+    slots: Array<{
+        slot: number;
+        item?: Item | undefined;
+        count?: number | undefined;
+    }>;
+} | {
+    type: "block_broken";
+    name: string;
+    at: Vec3;
+    block: Block;
+} | {
+    type: "block_placed";
+    name: string;
+    at: Vec3;
+    block: Block;
+} | {
+    type: "block_used";
+    name: string;
+    at: Vec3;
+    block: Block;
+    item?: Item | undefined;
+}
+/**
+ * The contents of a declared container changed (or its first snapshot, `initial`): the changed
+ * slots only, like `inventory`. `by` names the player who had it open, when the engine knows.
+ */
+ | {
+    type: "container";
+    at: Vec3;
+    block: Block;
+    slots: Array<{
+        slot: number;
+        item?: Item | undefined;
+        count?: number | undefined;
+    }>;
+    by?: string | undefined;
+    initial?: boolean | undefined;
+} | {
+    type: "entity_spawned";
+    id: string;
+    entity: EntityType;
+    at: Vec3;
+    tags?: string[] | undefined;
+    name?: string | undefined;
+    health?: number | undefined;
+    item?: Item | undefined;
+    count?: number | undefined;
+    uuid?: string | undefined;
+    yaw?: number | undefined;
+    pitch?: number | undefined;
+    headYaw?: number | undefined;
+    equipment?: EquipmentChange[] | undefined;
+    invisible?: boolean | undefined;
+    villager?: {
+        type: string;
+        profession: string;
+        level: number;
+    } | undefined;
+} | {
+    type: "entity_changed";
+    id: string;
+    tags?: string[] | undefined;
+    name?: string | undefined;
+    health?: number | undefined;
+    item?: Item | undefined;
+    count?: number | undefined;
+    equipment?: EquipmentChange[] | undefined;
+    invisible?: boolean | undefined;
+    villager?: {
+        type: string;
+        profession: string;
+        level: number;
+    } | undefined;
+} | {
+    type: "animation";
+    name: string;
+    animation: "swing" | "swing_off";
+} | {
+    type: "entity_removed";
+    id: string;
+    cause: "died" | "removed";
+    killer?: string | undefined;
+} | ({
+    type: "chunk";
+} & ChunkMessage) | {
+    type: "chunk_unloaded";
+    x: number;
+    z: number;
+} | {
+    type: "blocks_changed";
+    changes: Array<Vec3 & {
+        block: Block;
+        was?: Block | undefined;
+        cause?: string | undefined;
+        by?: string | undefined;
+    }>;
+} | {
+    type: "blocks_filled";
+    from: Vec3;
+    to: Vec3;
+    block: Block;
+} | {
+    type: "chat";
+    from: string;
+    text: string;
+    uuid?: string | undefined;
+} | {
+    type: "vote_attempt";
+    attemptId: string;
+    name: string;
+    voteId: string;
+    option: string;
+} | {
+    type: "effect_result";
+    id: string;
+    ok: boolean;
+    detail?: string | undefined;
+} | {
+    type: "effect_failed";
+    kind: string;
+    detail: string;
+} | {
+    type: "custom";
+    name: string;
+    player?: string | undefined;
+    data: Json;
+};
+/** One player's changed fields since the previous tick. `pos` comes with the extrema since the previous sample. */
+export type PlayerSample = {
+    name: string;
+    participant: boolean;
+    /** The server's entity id and the player's uuid, on the first sample. */
+    id?: number | undefined;
+    uuid?: string | undefined;
+    pos?: Vec3 | undefined;
+    maxY?: number | undefined;
+    minY?: number | undefined;
+    /** Degrees, Minecraft convention; sent with `pos`. */
+    yaw?: number | undefined;
+    pitch?: number | undefined;
+    headYaw?: number | undefined;
+    health?: number | undefined;
+    food?: number | undefined;
+    gamemode?: GameMode | undefined;
+    held?: Item | null | undefined;
+    equipment?: EquipmentChange[] | undefined;
+    invisible?: boolean | undefined;
+};
+export type Effect = {
+    kind: "fill";
+    from: Vec3;
+    to: Vec3;
+    block: Block;
+} | {
+    kind: "setblock";
+    at: Vec3;
+    block: Block;
+    nbt?: string | undefined;
+} | {
+    kind: "give";
+    player: string;
+    item: Item;
+    count: number;
+    nbt?: string | undefined;
+} | {
+    kind: "clear";
+    player: string;
+    item?: Item | undefined;
+    count?: number | undefined;
+} | {
+    kind: "teleport";
+    player: string;
+    to: Vec3;
+} | {
+    kind: "effect";
+    player: string;
+    effect: EffectId;
+    seconds: number;
+    amplifier: number;
+} | {
+    kind: "summon";
+    entity: EntityType;
+    at: Vec3;
+    nbt?: string | undefined;
+} | {
+    kind: "kill_entities";
+    entities?: EntityType[] | undefined;
+} | {
+    kind: "kill";
+    player: string;
+} | {
+    kind: "gamemode";
+    player: string;
+    mode: GameMode;
+} | {
+    kind: "attribute";
+    player: string;
+    attribute: string;
+    value: number;
+} | {
+    kind: "time";
+    value: "day" | "noon" | "night" | "midnight";
+} | {
+    kind: "gamerule";
+    rule: string;
+    value: boolean | number;
+} | {
+    kind: "title";
+    player?: string | undefined;
+    title: string;
+    subtitle?: string | undefined;
+    times?: TitleTimes | undefined;
+} | {
+    kind: "worldborder";
+    center?: {
+        x: number;
+        z: number;
+    } | undefined;
+    size?: number | undefined;
+    seconds?: number | undefined;
+} | {
+    kind: "container";
+    at: Vec3;
+    items: ContainerItem[];
+} | {
+    kind: "spawn";
+    at: Vec3;
+} | {
+    kind: "eliminate";
+    player: string;
+} | {
+    kind: "announce";
+    message: string;
+    to?: string | undefined;
+} | {
+    kind: "command";
+    cmd: string;
+};
+export type Action = {
+    type: "effect";
+    effect: Effect;
+} | {
+    type: "batch";
+    id: string;
+    effects: Effect[];
+} | {
+    type: "walk";
+    id: string;
+    player: string;
+    to: Vec3;
+    fallback: "teleport" | "none";
+} | {
+    type: "vote_decision";
+    attemptId: string;
+    accepted: boolean;
+    feedback?: string | undefined;
+} | {
+    type: "log";
+    player?: string | undefined;
+    message: string;
+    data?: Json | undefined;
+} | {
+    type: "score";
+    player: string;
+    score: number;
+} | {
+    type: "store";
+    name: string;
+    value: number;
+    player?: string | undefined;
+} | {
+    type: "game_over";
+    winners: string[];
+    endState: string;
+    judgeContext?: Record<string, Json> | undefined;
+};
+export type Status = "LOBBY" | "SETUP" | "PLAYING" | "OVER";
+/** The end states the SDK reports on its own: a failed setup, a thrown rule, facts the engine lacks. */
+export type SdkEndState = "error_setup" | "error_challenge" | "error_unsupported_facts";
+/** What `onOver` receives: the names on the wire, the same winners as players, and a membership check. */
+export interface OverResult<C extends ChallengeConfig, PM extends PlayerMap<C>> {
+    /** The winners' names, as `game_over` carries them. */
+    winners: string[];
+    /** The same winners as player objects. */
+    winnerPlayers: Player<C, PM>[];
+    isWinner(player: {
+        name: string;
+    }): boolean;
+    /** A declared end state, an SDK error state, or "" when no end state was classified. */
+    endState: EndStateOf<C> | SdkEndState | "";
+}
+/** Fields the SDK keeps on every player. The challenge's P is merged on top; P may not reuse these names. */
+export interface Built {
+    alive: boolean;
+    eliminated: boolean;
+    deaths: number;
+    kills: number;
+    /** Reported to the run result whenever it changes. */
+    score: number;
+    pos: Vec3 | null;
+    /** Degrees, Minecraft convention. */
+    yaw: number;
+    pitch: number;
+    headYaw: number;
+    /** The server's entity id and uuid, once the first sample arrived. */
+    entityId: number | null;
+    uuid: string | null;
+    /** Worn and held items by slot (main, off, head, chest, legs, feet). */
+    equipment: Equipment;
+    invisible: boolean;
+    health: number;
+    food: number;
+    gamemode: GameMode;
+    held: Item | null;
+    /** Inventory by slot: 0-35 main (0-8 hotbar), 36-39 armor, 40 offhand. */
+    slots: Record<number, {
+        item: Item;
+        count: number;
+    }>;
+    /** Item counts over every slot. */
+    inventory: Record<string, number>;
+    /** The declared zones the player stands in. */
+    zones: string[];
+    human: boolean;
+}
+export interface Roster<C extends ChallengeConfig, R extends RoleOf<C> = RoleOf<C>> {
+    name: string;
+    role: R;
+    number: number;
+    connected: boolean;
+}
+/** 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;
+};
+/** 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 SDK's fields as a rule sees them: `score` is the challenge's to write,
+ * everything else is an observation the engine reported (or the SDK derived)
+ * and a rule cannot change it. `g.eliminate` sets `eliminated`.
+ */
+export type Observed = DeepReadonly<Omit<Built, "score">> & Pick<Built, "score">;
+/** One participant of role `R`, as a rule sees it: the SDK's fields (observations read-only) plus the challenge's state for that role. */
+export type PlayerOf<C extends ChallengeConfig, PM extends PlayerMap<C>, R extends RoleOf<C>> = Readonly<Roster<C, R>> & Observed & PM[R];
+/** The same participant with the SDK's write access: the state's shape, never a rule's. */
+export type StatePlayerOf<C extends ChallengeConfig, PM extends PlayerMap<C>, R extends RoleOf<C>> = Roster<C, R> & Built & PM[R];
+export type StatePlayer<C extends ChallengeConfig, PM extends PlayerMap<C> = PlayerMap<C>> = {
+    [R in RoleOf<C>]: StatePlayerOf<C, PM, R>;
+}[RoleOf<C>];
+/**
+ * A participant: one member per role, discriminated by `role`, so `p.role === "p1"`
+ * narrows to that role's fields (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>];
+/** The context type of a built challenge, for tests and helpers called from a rule: `ContextOfChallenge<typeof sky>`. */
+export type ContextOfChallenge<Ch extends {
+    ctx: unknown;
+}> = Ch["ctx"];
+/** The player type a context works with: `type Pl = PlayerIn<typeof sky.ctx>`. */
+export type PlayerIn<Cx> = Cx extends {
+    readonly players: ReadonlyArray<infer Pl>;
+} ? Pl : never;
+type SdkOwned = keyof Built | keyof Roster<ChallengeConfig>;
+/** A compile-time check: the challenge's per-player fields may not reuse an SDK-owned name. */
+export type NoBuilt<P> = [Extract<keyof P, SdkOwned>] extends [never] ? unknown : {
+    "error: this player field is owned by the SDK": Extract<keyof P, SdkOwned>;
+};
+/** The same check over every role of `players`: a required key per offending role, so the error names it. */
+export type NoBuiltIn<PS> = {
+    [R in keyof PS as [Extract<keyof PS[R], SdkOwned>] extends [never] ? never : R]: {
+        "error: this player field is owned by the SDK": Extract<keyof PS[R], SdkOwned>;
+    };
+};
+export interface State<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string> {
+    seed: number;
+    rng: number;
+    params: ParamsOf<C>;
+    capabilities: Capability[];
+    locations: Record<string, Vec3>;
+    markers: Marker[];
+    status: Status;
+    tick: number;
+    dt: number;
+    startTick: number;
+    setupTick: number;
+    phase: Ph | "END";
+    phaseStartTick: number;
+    phaseEntries: number;
+    fired: Record<string, true>;
+    every: Record<string, number>;
+    timers: Record<string, number>;
+    players: Record<string, StatePlayer<C, PM>>;
+    game: G;
+    votes: Record<string, Record<string, string>>;
+    walks: Record<string, {
+        player: string;
+        fallback: "teleport" | "none";
+    } & Vec3>;
+    /** The declared containers' contents by "x,y,z": slot to item, as the engine reported them. */
+    containers: Record<string, {
+        block: Block;
+        slots: Record<number, {
+            item: Item;
+            count: number;
+        }>;
+    }>;
+    /** The world mirror. Updated by copy, so a reduction shares it with the state before it. */
+    world: WorldState;
+    nextId: number;
+    winners: string[];
+    endState: string;
+}
+export type To<C extends ChallengeConfig, PM extends PlayerMap<C>> = Player<C, PM> | Player<C, PM>[] | "all";
+export interface Ctx<C extends ChallengeConfig, G = Record<string, never>, PM extends PlayerMap<C> = PlayerMap<C>, Ph extends string = string, Z extends string = never, T extends string = never> {
+    readonly game: G;
+    readonly params: ParamsOf<C>;
+    /** Participants in the order of the run's participant list. */
+    readonly players: Player<C, PM>[];
+    /** Participants still in the game. */
+    readonly active: Player<C, PM>[];
+    player(name: string): Player<C, PM> | undefined;
+    /** The participants of one role, typed with that role's fields. */
+    role<R extends RoleOf<C>>(role: R): PlayerOf<C, PM, R>[];
+    one<R extends RoleOf<C>>(role: R): PlayerOf<C, PM, R> | undefined;
+    readonly tick: number;
+    readonly dt: number;
+    readonly elapsed: number;
+    readonly phase: Ph | "END";
+    readonly phaseElapsed: number;
+    readonly phaseRemaining: number;
+    location(name: LocationOf<C>): Vec3;
+    /** Marker entities from `spec.markers`: all of them, or those carrying `tag`. */
+    markers(tag?: string): Marker[];
+    /**
+     * Item counts in a declared container, by its name in `containers` or by position;
+     * undefined before the engine reported it. (`g.container(at, items)` is the effect that fills one.)
+     */
+    contents(target: string | Vec3): Readonly<Record<string, number>> | undefined;
+    /** A declared zone by name, or any box. */
+    inZone(player: Player<C, PM>, zone: NoInfer<Z> | Box): boolean;
+    count(player: Player<C, PM>, item: Item): number;
+    /** Players online who are not participants: the watcher, spectators, humans in the lobby. */
+    readonly others: ReadonlyArray<DeepReadonly<OtherPlayer>>;
+    /** The block id at `at` (`minecraft:oak_fence`); undefined outside the loaded chunks. */
+    blockAt(at: Vec3): Block | undefined;
+    /** The full block state at `at` (`minecraft:oak_fence[north=true,...]`). */
+    blockStateAt(at: Vec3): Block | undefined;
+    /** The world time of day, 0..24000. */
+    readonly worldTime: number;
+    blockCount(box: Box, block: BlockMatch): number;
+    findBlocks(box: Box, block: BlockMatch, limit?: number): Vec3[];
+    /** 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>>;
+    entity(id: string): DeepReadonly<Entity> | undefined;
+    /** The accepted votes of one round: voter name to option. A participant without a vote is absent. */
+    votes<V extends VoteIdOf<C>>(voteId: V): Readonly<Record<string, OptionFor<C, V>>>;
+    vote<V extends VoteIdOf<C>>(player: Player<C, PM>, voteId: V): OptionFor<C, V> | undefined;
+    /** Forgets every vote in voteId: a new round. */
+    openVote(voteId: VoteIdOf<C>): void;
+    goTo(phase: Ph | "END"): void;
+    end(endState?: EndStateOf<C>): void;
+    eliminate(player: Player<C, PM>): void;
+    /** A named timer. `on.timer({ name })` fires when it is due; scheduling again resets it. */
+    schedule(name: NoInfer<T>, after: Duration): void;
+    cancel(name: NoInfer<T>): void;
+    rand(min: number, max: number): number;
+    pick<X>(items: readonly X[]): X;
+    shuffle<X>(items: readonly X[]): X[];
+    say(message: string): void;
+    tell(to: To<C, PM>, message: string): void;
+    title(to: To<C, PM>, title: string, subtitle?: string | undefined, times?: TitleTimes | undefined): void;
+    log(player: Player<C, PM> | null, message: string, data?: Json | undefined): void;
+    /** A stored variable: the last value per name reaches the run result (`runs get` shows them). Global without a player. */
+    store(name: string, value: number, player?: Player<C, PM> | undefined): void;
+    achievement(player: Player<C, PM>, id: string): void;
+    give(player: Player<C, PM>, item: Item, count?: number | undefined, nbt?: string | undefined): void;
+    clear(player: Player<C, PM>, item?: Item | undefined, count?: number | undefined): void;
+    effect(player: Player<C, PM>, effect: EffectId, seconds: number, amplifier?: number): void;
+    teleport(player: Player<C, PM>, to: Vec3): 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?: {
+        fallback?: "teleport" | "none";
+    }): void;
+    kill(player: Player<C, PM>): void;
+    gamemode(player: Player<C, PM>, mode: GameMode): void;
+    attribute(player: Player<C, PM>, attribute: string, value: number): void;
+    fill(from: Vec3, to: Vec3, block: Block): void;
+    setblock(at: Vec3, block: Block, nbt?: string | undefined): void;
+    summon(entity: EntityType, at: Vec3, nbt?: string | undefined): void;
+    /** Removes entities in the run's world; players are never removed. */
+    killEntities(entities?: EntityType[] | undefined): void;
+    time(value: "day" | "noon" | "night" | "midnight"): void;
+    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; `seconds` animates the size change. */
+    worldBorder(opts: {
+        center?: {
+            x: number;
+            z: number;
+        };
+        size?: number;
+        seconds?: number;
+    }): void;
+    /** Replaces the contents of a chest or other container block. */
+    container(at: Vec3, items: ContainerItem[]): void;
+    /**
+     * The escape hatch. Logged. Prefer a typed verb. The arena runs only the
+     * gameplay commands on its allowlist (no server administration, no `fill`,
+     * `setblock`, `clone`, `place`, `fillbiome`, `data` or `forceload`: a command
+     * fires no block event, so the mirror would miss it); a refused command
+     * comes back as `effectFailed`.
+     */
+    command(cmd: string): 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> {
+    tick?: (g: Ctx<C, G, PM, Ph, Z, T>) => void;
+    joined?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+    }>;
+    left?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+    }>;
+    move?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        from: Vec3 | null;
+        to: Vec3;
+        maxY: number;
+        minY: number;
+    }>;
+    damaged?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        amount: number;
+        cause: string;
+        attacker?: Player<C, PM> | undefined;
+    }>;
+    died?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        cause: string;
+        killer?: Player<C, PM> | undefined;
+    }>;
+    respawned?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+    }>;
+    entitySpawned?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        entity: Entity;
+    }>;
+    entityRemoved?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        entity: Entity;
+        cause: "died" | "removed";
+        killer?: Player<C, PM> | undefined;
+    }>;
+    pickup?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        item: Item;
+        count: number;
+        at: Vec3;
+    }>;
+    /** A participant's count of one item changed. */
+    inventory?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        item: Item;
+        count: number;
+    }>;
+    blockBroken?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        at: Vec3;
+        block: Block;
+    }>;
+    blockPlaced?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        at: Vec3;
+        block: Block;
+    }>;
+    blockUsed?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        at: Vec3;
+        block: Block;
+        item?: Item | undefined;
+    }>;
+    /** A declared container's contents changed: the counts after the change and the deltas. */
+    container?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        at: Vec3;
+        block: Block;
+        items: Readonly<Record<string, number>>;
+        changes: Array<{
+            item: Item;
+            delta: number;
+        }>;
+        by?: Player<C, PM> | undefined;
+    }>;
+    /** Every block that changed this tick, whatever the cause. */
+    blocksChanged?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        changes: Array<Vec3 & {
+            block: Block;
+            was?: Block | undefined;
+            cause?: string | undefined;
+            by?: Player<C, PM> | undefined;
+        }>;
+    }>;
+    zoneEntered?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        zone: Z;
+    }>;
+    zoneLeft?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        zone: Z;
+    }>;
+    chat?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        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>, {
+        player: Player<C, PM>;
+        animation: "swing" | "swing_off";
+    }>;
+    /** A participant's game mode changed. */
+    gamemode?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        gamemode: GameMode;
+    }>;
+    /** Accepted votes only. The SDK answered the rejected ones. */
+    vote?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        [V in VoteIdOf<C>]: {
+            player: Player<C, PM>;
+            voteId: V;
+            option: OptionFor<C, V>;
+        };
+    }[VoteIdOf<C>]>;
+    walkDone?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        player: Player<C, PM>;
+        ok: boolean;
+    }>;
+    timer?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        name: T;
+    }>;
+    effectFailed?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        kind: string;
+        detail: string;
+    }>;
+    custom?: H<Ctx<C, G, PM, Ph, Z, T>, {
+        name: string;
+        player?: Player<C, PM> | undefined;
+        data: Json;
+    }>;
+}
+export type PhaseStep<Cx> = ({
+    elapsed: Duration;
+} | {
+    remaining: Duration;
+}) & {
+    run: (g: Cx) => void;
+};
+export interface PhaseSpec<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string> {
+    duration?: Duration;
+    enter?: (g: Ctx<C, G, PM, Ph, Z, T>) => void;
+    exit?: (g: Ctx<C, G, PM, Ph, Z, T>) => void;
+    /** Phase names come from the keys of `phases`, never from a `next` literal. */
+    next?: NoInfer<Ph> | "END" | ((g: Ctx<C, G, PM, Ph, Z, T>) => NoInfer<Ph> | "END");
+    /** Once per phase entry: `elapsed` since entry, or `remaining` before its end (needs `duration`). */
+    at?: Array<PhaseStep<Ctx<C, G, PM, Ph, Z, T>>>;
+    every?: Array<{
+        interval: Duration;
+        run: (g: Ctx<C, G, PM, Ph, Z, T>) => void;
+    }>;
+    /** Handlers that run only in this phase, after the global `on` for the same event. */
+    on?: Handlers<C, G, PM, Ph, Z, T>;
+}
+/** Cost knobs for the world mirror. Everything is on by default; a large world can narrow it. */
+export interface Mirror {
+    /** "participants" leaves the watcher, spectators and lobby players out of the ticks. */
+    players?: "all" | "participants";
+    entities?: boolean | {
+        within: Box;
+    };
+    blocks?: boolean | {
+        within: Box;
+    };
+}
+/** World setup the SDK applies before the game. Every field but `spawn` has today's default (an unset `spawn` emits nothing); `false` on `world` skips all of it. */
+export interface World {
+    /** The world spawn: participants respawn there, the watcher and spectators are moved there. */
+    spawn?: Vec3;
+    time?: "day" | "noon" | "night" | "midnight" | false;
+    daylightCycle?: boolean;
+    mobSpawning?: boolean;
+    naturalRegeneration?: boolean;
+    maxHealth?: number | false;
+}
+export declare const WORLD_DEFAULTS: Required<Omit<World, "spawn">>;
+export interface Spec<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string, T extends string> {
+    /** Time from game start to the end. Omit for no time limit. */
+    duration?: Duration;
+    /** "single": one death eliminates (spectator). "respawn": deaths count, the player plays on. */
+    life: "single" | "respawn";
+    world?: World | false;
+    announce?: {
+        deaths?: boolean;
+        gameOver?: boolean;
+    };
+    mirror?: Mirror;
+    /** 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?: {
+        tags: string[];
+        within?: Box;
+    };
+    /**
+     * Named containers (chests, barrels) whose contents the engine reports: `g.contents(name)`,
+     * `g.contents(at)`, `on.container`. The rules read what is in the chest, not what left a hand.
+     */
+    containers?: Record<string, Vec3>;
+    /** World build. Its effects go out as ONE batch; the game starts after the engine confirms it. */
+    setup?: (g: Ctx<C, G, PM, Ph, Z, T>) => void;
+    /** Runs on the first tick of PLAYING, after the setup batch is confirmed. */
+    start?: (g: Ctx<C, G, PM, Ph, Z, T>) => void;
+    phases?: Record<Ph, PhaseSpec<C, G, PM, Ph, Z, T>>;
+    /** One-shot steps `at` after game start, `>=` semantics. */
+    at?: Array<{
+        at: Duration;
+        run: (g: Ctx<C, G, PM, Ph, Z, T>) => void;
+    }>;
+    /** Repeating steps. After a gap they run once, not once per missed interval. */
+    every?: Array<{
+        interval: Duration;
+        run: (g: Ctx<C, G, PM, Ph, Z, T>) => void;
+    }>;
+    /** Vote ids and options come from config.challengeConfig.votingOptions. */
+    votes?: {
+        [V in VoteIdOf<C>]?: {
+            /** `true` (the default, also for a vote with no rule): a participant votes once per round. `false`: a new vote replaces the old one. */
+            final?: boolean;
+            phases?: NoInfer<Ph>[];
+            /** The challenge's veto. `true` accepts; a string refuses with that feedback to the voter. */
+            open?: (g: Ctx<C, G, PM, Ph, Z, T>, player: Player<C, PM>, option: OptionFor<C, V>) => true | string;
+        };
+    };
+    on?: Handlers<C, G, PM, Ph, Z, T>;
+    /** Extra end condition, checked after every reduction. */
+    end?: (g: Ctx<C, G, PM, Ph, Z, T>) => boolean;
+    winners?: (g: Ctx<C, G, PM, Ph, Z, T>) => ReadonlyArray<{
+        name: string;
+    }>;
+    /** Runs once the winners and end state are final, before game_over: result titles, a last announcement. */
+    onOver?: (g: Ctx<C, G, PM, Ph, Z, T>, result: OverResult<C, PM>) => void;
+    endState?: (g: Ctx<C, G, PM, Ph, Z, T>) => EndStateOf<C>;
+    /** An object sent with `game_over` for the LLM judge (the challenge never calls the judge); the backend takes an object, not another JSON value. */
+    judgeContext?: (g: Ctx<C, G, PM, Ph, Z, T>) => Record<string, Json>;
+}
+/** What the arena reads before the run. */
+export interface RuntimeManifest {
+    runtime: 1;
+    name: string;
+    life: "single" | "respawn";
+    /** The role ids the rules know: the backend checks them against the challenge's configuration at activation. */
+    roles: string[];
+    /** The location names the configuration declares, when it declares any. */
+    locations?: string[] | undefined;
+    mirror?: Mirror | undefined;
+    markers?: {
+        tags: string[];
+        within?: Box | undefined;
+    } | undefined;
+    /** The containers the rules read (`containers` in the spec): the engine reports their contents. */
+    containers?: Vec3[] | undefined;
+}
+export interface Challenge<C extends ChallengeConfig, G, PM extends PlayerMap<C>, Ph extends string, Z extends string = never, T extends string = never> {
+    config: C;
+    manifest: RuntimeManifest;
+    /** The declared zones, for tests. */
+    zones: Record<string, Box>;
+    /**
+     * A type, not a value: `type G = typeof sky.ctx` is the context a helper
+     * function takes. Reading it at run time throws. Call helpers from inside a
+     * function (`endState: (g) => classify(g)`); passing one as a property value
+     * (`endState: classify`) makes the challenge's type depend on itself.
+     */
+    readonly ctx: Ctx<C, G, PM, Ph, Z, T>;
+    init(): State<C, G, PM, Ph>;
+    reduce(s: State<C, G, PM, Ph>, e: Event): {
+        state: State<C, G, PM, Ph>;
+        actions: Action[];
+    };
+}
+/** The shape every built challenge bundle exports as `default`. */
+export type AnyChallenge = Challenge<any, any, any, any, any, any>;
+/** The state initializers. `player` is the state of every role; `players` overrides it per role. */
+export interface StateDecl<C extends ChallengeConfig, G, P, PS> {
+    game?: () => G;
+    player?: (roster: Roster<C>) => P;
+    players?: {
+        [R in keyof PS]: (roster: Roster<C, R & RoleOf<C>>) => PS[R];
+    };
+}
+/**
+ * The context type for helper functions, from the config and the object that
+ * holds the state initializers (and any zones or timers the helpers use),
+ * before the challenge exists:
+ *
+ *   const decl = { game: () => ({ chests: [] as Vec3[] }), player: () => ({ island: "" }) };
+ *   type G = ContextOf<typeof config, typeof decl>;
+ *   export default defineChallenge(config, { ...decl, ...rules });
+ *
+ * `typeof x.ctx` on the challenge gives the same type, but only helpers called
+ * from inside a rule may use it (`endState: (g) => classify(g)`): a helper
+ * passed as the property value (`endState: classify`) makes the challenge's
+ * type circular.
+ */
+export type ContextOf<C extends ChallengeConfig, D> = Ctx<C, D extends {
+    game: () => infer G;
+} ? G : Record<string, never>, ResolvePlayers<C, D extends {
+    player: (...a: never[]) => infer P;
+} ? P extends object ? P : Record<string, never> : Record<string, never>, D extends {
+    players: infer PS;
+} ? {
+    [R in keyof PS]: PS[R] extends (...a: never[]) => infer S ? S : never;
+} : Record<never, never>>, string, D extends {
+    zones: infer Zs;
+} ? keyof Zs & string : never, D extends {
+    timers: readonly (infer T)[];
+} ? (T extends string ? T : never) : never>;
+type AnyCtx = Ctx<ChallengeConfig, unknown, PlayerMap<ChallengeConfig>, string, string, string>;
+type AnyPlayer = Player<ChallengeConfig>;
+export declare const End: {
+    allEliminated: (g: AnyCtx) => boolean;
+};
+export declare const Win: {
+    /** Highest score among the eligible players (default: still in the game), if it reaches `min` (default 1). Ties win together. */
+    topScore: (opts?: {
+        min?: number;
+        eligible?: (p: AnyPlayer) => boolean;
+    }) => (g: AnyCtx) => AnyPlayer[];
+    scoreAtLeast: (min: number) => (g: AnyCtx) => AnyPlayer[];
+};
+export declare function defineChallenge<const C extends ChallengeConfig, G extends object = Record<string, never>, P extends object = Record<string, never>, PS extends Partial<Record<RoleOf<C>, object>> = Record<never, never>, Ph extends string = "MAIN", Z extends string = never, T extends string = never>(config: C, spec: Spec<C, G, ResolvePlayers<C, P, PS>, Ph, Z, T> & StateDecl<C, G, P, PS> & NoBuilt<P> & NoBuiltIn<PS>): Challenge<C, G, ResolvePlayers<C, P, PS>, Ph, Z, T>;
+//# sourceMappingURL=sdk.d.ts.map