@kradle/challenges-sdk 0.10.0 → 0.11.0

package/dist/actions.d.ts

@@ -1,901 +0,0 @@
-import { type GAMERULES, type JSONTextComponent, type Score, SelectorClass, type SingleEntityArgument } from "sandstone";
-import type { ATTRIBUTES, BLOCKS, ENTITY_TYPES, ITEMS } from "sandstone/arguments/generated";
-import type { ConditionType } from "sandstone/flow";
-import type { LiteralStringUnion } from "./utils";
-export type TargetNames = LiteralStringUnion<"all" | "self"> | SelectorClass<any, any>;
-export declare function mapTarget(target: string | SelectorClass): SelectorClass<any, any> | string;
-export declare const Actions: {
-    /**
-     * Send a chat message to everyone.
-     * @param {JSONTextComponent} message - The message to send.
-     */
-    announce: ({ message }: {
-        message: JSONTextComponent;
-    }) => void;
-    /**
-     * Pick `count` random participants and tag them. Used to assign hidden
-     * roles in social-deduction challenges — combine with `Actions.tellraw` to
-     * privately notify each tagged participant of their assignment.
-     *
-     * Uses Minecraft's `sort=random,limit=N` selector behavior. The selection
-     * happens at command time (typically `start_challenge`), so it's stable
-     * for the rest of the run.
-     *
-     * @example Saboteur assignment in a 4-player game:
-     * ```ts
-     * start_challenge: () => {
-     *   Actions.assignRandomTag({ tag: "saboteur", count: 1 });
-     *   // Then DM each tagged participant their secret role:
-     *   Actions.tellraw({
-     *     target: Selector("@a", { tag: "saboteur" }),
-     *     message: [{ text: "🔪 You're the saboteur. Stop the miners.", color: "red" }],
-     *   });
-     * }
-     * ```
-     *
-     * `count` is capped to the number of participants — over-asking just tags
-     * everyone available.
-     */
-    assignRandomTag: ({ tag: tagName, count }: {
-        tag: string;
-        count: number;
-    }) => void;
-    /**
-     * Pick a uniform random integer in `[min, max]` (both inclusive) and
-     * return it as an anonymous `Score`. Wraps Minecraft's `random value`
-     * command, which Sandstone does not expose as a typed primitive — this
-     * helper is the abstraction so that user code never has to write `raw`
-     * for randomness.
-     *
-     * Use to randomize challenge state at `start_challenge` (which goal block
-     * is "the" goal, which player a saboteur is paired with for a side-quest,
-     * etc.) so behavior isn't gameable across runs.
-     *
-     * @example Pick one of 4 goal directions per run:
-     * ```ts
-     * goal_index: { type: "global", default: 0 },
-     *
-     * start_challenge: () => {
-     *   variables.goal_index.score.set(Actions.randomInt({ min: 0, max: 3 }));
-     *   // Then branch: _.if(goal_index.equalTo(0), () => place at N), etc.
-     * }
-     * ```
-     */
-    randomInt: ({ min, max }: {
-        min: number;
-        max: number;
-    }) => Score;
-    /**
-     * Clear the inventory of a target.
-     * @param {TargetNames} target - The target to clear the inventory of.
-     */
-    clear: ({ target }: {
-        target: TargetNames;
-    }) => void;
-    /**
-     * Fill a region with a block.
-     * @param {BLOCKS} block - The block to fill the region with.
-     * @param {number} x1 - The x coordinate of the region.
-     * @param {number} y1 - The y coordinate of the region.
-     * @param {number} z1 - The z coordinate of the region.
-     * @param {number} x2 - The x coordinate of the region.
-     * @param {number} y2 - The y coordinate of the region.
-     * @param {number} z2 - The z coordinate of the region.
-     * @param {boolean} absolute - Whether the coordinates are absolute or relative.
-     * @param {"fill" | "line" | "pyramid"} mode - Required. How to fill the region: `"fill"` (solid box between the two points), `"line"` (1-wide line from point 1 to point 2), or `"pyramid"` (pyramid `|y2|` blocks tall, stepping in by 2 per layer). Omitting it throws `Invalid fill mode` at build time.
-     */
-    fill: ({ block, x1, y1, z1, x2, y2, z2, absolute, mode, }: {
-        block: BLOCKS;
-        x1: number;
-        y1: number;
-        z1: number;
-        x2: number;
-        y2: number;
-        z2: number;
-        absolute: boolean;
-        mode: "fill" | "line" | "pyramid";
-    }) => void;
-    /**
-     * Give an item to a target.
-     * @param {ITEMS} item - The item to give.
-     * @param {TargetNames} target - The target to give the item to.
-     * @param {number} count - The number of items to give.
-     */
-    give: ({ item, target, count }: {
-        item: ITEMS;
-        target: TargetNames;
-        count?: number;
-    }) => void;
-    /**
-     * Give loot to a target with a weighted chance for selecting one of the items.
-     * @param {{ name: ITEMS, count: number, weight: number }[]} items - The items to give.
-     * @param {TargetNames} target - The target to give the item to.
-     */
-    giveLoot: ({ items, target }: {
-        items: [{
-            name: ITEMS;
-            count: number;
-            weight: number;
-        }];
-        target: TargetNames;
-    }) => void;
-    /**
-     * Set a gamerule.
-     * @param {GAMERULES} rule - The name of the gamerule.
-     * @param {boolean | number} value - The value to set the gamerule to.
-     */
-    gamerule: ({ rule, value }: {
-        rule: GAMERULES;
-        value: boolean | number;
-    }) => void;
-    /**
-     * Kill entities matching a selector.
-     * @param {SelectorArgument} selector - The entities to kill.
-     */
-    kill: ({ selector }: {
-        selector: TargetNames;
-    }) => void;
-    /**
-     * Set the gamemode of a target. Useful for moving an eliminated player
-     * to spectator without killing them (preserves the entity, lets them
-     * watch the rest of the run).
-     *
-     * @example
-     * Actions.setGamemode({ target: "self", mode: "spectator" });
-     * Actions.setGamemode({ target: "all", mode: "adventure" });
-     */
-    setGamemode: ({ target, mode, }: {
-        target: TargetNames;
-        mode: "survival" | "creative" | "adventure" | "spectator";
-    }) => void;
-    /**
-     * Eliminate a participant from the active round: switch them to
-     * spectator mode (so they can still observe but can't act). Sister
-     * helper to `kill`, intended for vote-out / king-of-the-hill / battle
-     * royale style games where elimination shouldn't end the agent's
-     * connection.
-     *
-     * Note: this only flips gamemode. The challenge author is responsible
-     * for any per-player tracking variable (e.g. `is_alive`).
-     *
-     * @example
-     * Actions.eliminate({ target: "self" });
-     */
-    eliminate: ({ target }: {
-        target: TargetNames;
-    }) => void;
-    /**
-     * Set an attribute for a target.
-     * @param {ATTRIBUTES} attribute_ - The attribute to set.
-     * @param {number} value - The value to set the attribute to.
-     * @param {TargetNames} target - The target to set the attribute for.
-     */
-    setAttribute: ({ attribute_, value, target }: {
-        attribute_: ATTRIBUTES;
-        value: number;
-        target: TargetNames;
-    }) => void;
-    /**
-     * Set the time of day.
-     * @param {'day' | 'night'} time_ - The time to set.
-     */
-    setTime: ({ time }: {
-        time: "day" | "night";
-    }) => void;
-    /**
-     * Summon multiple entities at a specific location.
-     */
-    summonMultiple: (params: {
-        entity: ENTITY_TYPES;
-        count: number;
-        x: number;
-        y: number;
-        z: number;
-        absolute: boolean;
-    }) => void;
-    /**
-     * Set the end state of the challenge.
-     * @param {string} end_state - The end state to set.
-     * @throws {Error} If KRADLE_CHALLENGE_END_STATES is set and endState is not in the list.
-     */
-    setEndState: ({ endState }: {
-        endState: string;
-    }) => void;
-    /**
-     * For each `(name, condition)` pair, emit `_.if(condition, () =>
-     * setEndState(name))` at the current codegen location. Where (and how
-     * often) those checks run is up to the caller — `events.on_tick` for a
-     * per-tick check, `custom_events.actions` for a single fire, etc.
-     *
-     * Returns a `ConditionType` that is true when at least one of the input
-     * conditions is true (i.e. an end-state was applied). Hand it to
-     * `.end_condition()` if you want the game to end as soon as any end-state
-     * has been set; ignore it if the game's end is gated on something else
-     * (timer, separate condition).
-     *
-     * Note: conditions are evaluated in whatever execution context the caller
-     * is in. From `on_tick` that's the server entity, where per-player score
-     * reads silently fail — see `Actions.maxPlayerScore` for the per-player →
-     * global bridge.
-     *
-     * @example
-     * let endReached: ConditionType | undefined;
-     * const challenge = createChallenge({...});
-     * challenge
-     *   .events((vars) => ({
-     *     on_tick: () => {
-     *       endReached = Actions.setEndStates({
-     *         winner_found: vars.top_kills.greaterOrEqualThan(20),
-     *         all_dead: vars.alive_players.equalTo(0),
-     *       });
-     *     },
-     *   }))
-     *   .end_condition(() => endReached!); // game ends as soon as any branch fires
-     */
-    setEndStates: (endStates: Record<string, ConditionType>) => ConditionType;
-    /**
-     * Set a block at a specific location.
-     */
-    setBlock: (params: {
-        block: BLOCKS;
-        x: number;
-        y: number;
-        z: number;
-        absolute: boolean;
-    }) => void;
-    /**
-     * Teleport entities to a specific location, or to another entity.
-     * @param {TargetNames} target - The entities to teleport.
-     * @param {SingleEntityArgument} toEntity - The entity to teleport to.
-     * @param {number} x - The x coordinate of the destination.
-     * @param {number} y - The y coordinate of the destination.
-     * @param {number} z - The z coordinate of the destination.
-     * @param {boolean} absolute - Whether the coordinates are absolute or relative.
-     */
-    teleport: (args: {
-        target: TargetNames;
-        x: number;
-        y: number;
-        z: number;
-        absolute: boolean;
-    } | {
-        target: TargetNames;
-        toEntity: SingleEntityArgument;
-    }) => void;
-    /**
-     * Force the target player(s) to immediately interrupt whatever code they are
-     * running and walk to the given absolute coordinates. Server-initiated: the
-     * challenge forces the move, unlike normal agent movement skills. The agents
-     * always walk to the destination — they are never teleported, even in cheat
-     * mode. Only the interrupt plus a single pathfind are guaranteed; an agent
-     * may decide to walk away again on its next action.
-     * @param {TargetNames} target - "self", "all", a role name, or a Selector.
-     *   "self" is the acting agent and only resolves inside a per-player
-     *   context; a forceMoveTo("self") reachable from a contextless server
-     *   function is caught by the build context-safety check. Raw "@..."
-     *   selector strings are rejected by mapTarget — use "self" or a Selector.
-     * @param {number} x - Absolute x coordinate to move to.
-     * @param {number} y - Absolute y coordinate to move to.
-     * @param {number} z - Absolute z coordinate to move to.
-     */
-    forceMoveTo: ({ target, x, y, z }: {
-        target: TargetNames;
-        x: number;
-        y: number;
-        z: number;
-    }) => void;
-    /**
-     * Send a chat message to a target.
-     * @param {JSONTextComponent} message - The message to send.
-     * @param {TargetNames} target - The target to send the message to.
-     */
-    tellraw: ({ message, target }: {
-        message: JSONTextComponent;
-        target: TargetNames;
-    }) => void;
-    /**
-     * Increment a score variable by 1.
-     * @param variable - The score variable to increment.
-     */
-    increment: ({ variable }: {
-        variable: Score;
-    }) => void;
-    /**
-     * Decrement a score variable by 1.
-     * @param variable - The score variable to decrement.
-     */
-    decrement: ({ variable }: {
-        variable: Score;
-    }) => void;
-    /**
-     * Set a score variable to a specific value.
-     * @param variable - The score variable to set.
-     * @param value - The value to set the score variable to, which can be a number or another score variable.
-     */
-    set: ({ variable, value }: {
-        variable: Score;
-        value: number | Score;
-    }) => void;
-    /**
-     * Selector that matches `@s` only when standing on the block at the
-     * given absolute coordinate. Use this anywhere you'd otherwise have
-     * written `Selector("@s", { x, y, z })` — that bare form does NOT
-     * constrain position (Minecraft treats x/y/z as the selector origin
-     * for distance math, not as a position filter), so the condition
-     * silently passes for everyone. This helper bakes in the right
-     * `dx: 0, dy: 1, dz: 0` volume covering the block above and the
-     * head space, so the selector matches only when the player's feet
-     * are inside the 1×1×1 column at (x, y+1, z).
-     *
-     * @param {number} x - X of the block being stood on.
-     * @param {number} y - Y of the block being stood on (the player's feet are at y+1).
-     * @param {number} z - Z of the block being stood on.
-     * @param {string} [role] - Optional role tag the player must also have.
-     *
-     * @example
-     * // Trigger alice_shared when Alice steps on her pad block.
-     * alice_shared: {
-     *   type: "global",
-     *   default: 0,
-     *   updater: (value) => {
-     *     _.if(value.equalTo(0), () => {
-     *       forEveryPlayer(() => {
-     *         _.if(Actions.standingOnBlock({ x: ALICE_PAD.x, y: ALICE_PAD.y, z: ALICE_PAD.z, role: "alice" }), () => {
-     *           value.set(1);
-     *         });
-     *       });
-     *     });
-     *   },
-     * },
-     */
-    standingOnBlock: ({ x, y, z, role }: {
-        x: number;
-        y: number;
-        z: number;
-        role?: string;
-    }) => SelectorClass<true, true>;
-    /**
-     * Condition that matches `@s` when the player has voted in `voteId` (any
-     * option), or — when `option` is given — only when they voted for that
-     * specific option. Agents cast votes with skills.voteForOption; the arena
-     * records each pick as the player tags kradle.voteOptions.<voteId> and
-     * kradle.voteOptions.<voteId>.<option>.
-     *
-     * It matches `@s`, so use it as a CONDITION in a player context — inside
-     * `forEveryPlayer(...)`, or in `setEndStates` / win conditions. Don't hand it
-     * to `execute.as(...)` from a tick/load context: `@s` resolves to no one
-     * there, so the command runs for nobody (the context-safety check flags this).
-     *
-     * @param {string} voteId - The vote's id, e.g. "selectroom".
-     * @param {string} [option] - Optional specific option, e.g. "red".
-     * @returns {ConditionType} a per-player condition for `_.if` / win conditions.
-     * @throws {Error} If the vote or option isn't declared in config.ts's votingOptions.
-     *
-     * @example
-     * // Teleport everyone who picked the red room.
-     * forEveryPlayer(() => {
-     *   _.if(Actions.votedFor("selectroom", "red"), () => {
-     *     Actions.teleport({ target: "self", x: 10, y: -60, z: 10, absolute: true });
-     *   });
-     * });
-     */
-    votedFor: (voteId: string, option?: string) => SelectorClass<true, true>;
-    /**
-     * Announces a vote to all participants over the `***KRADLE***` channel agents
-     * read, naming the vote and its options. Agents respond with
-     * skills.voteForOption(voteId, option). Compose with `allVotesIn`,
-     * `assignDefaultVotes`, and `votedFor` to build a full vote phase.
-     *
-     * @param {string} voteId - The vote's id, e.g. "selectroom".
-     * @param {string} prompt - Human-readable instruction, e.g. "Pick a room!".
-     * @param {string[]} options - Valid options, e.g. ["red", "green", "blue"].
-     * @throws {Error} If the vote or any option isn't declared in config.ts's votingOptions.
-     *
-     * @example
-     * Actions.promptVote({ voteId: "selectroom", prompt: "Pick a room!", options: ["red", "green"] });
-     */
-    promptVote: ({ voteId, prompt, options }: {
-        voteId: string;
-        prompt: string;
-        options: string[];
-    }) => void;
-    /**
-     * Condition that is true once every participant has voted in `voteId` — i.e.
-     * no participant is still missing the `kradle.voteOptions.<voteId>` tag the
-     * arena writes on each vote. Combine with a timer to end a vote phase as soon
-     * as everyone is in.
-     *
-     * @param {string} voteId - The vote's id, e.g. "selectroom".
-     * @returns {ConditionType} true when all participants have voted.
-     * @throws {Error} If the vote isn't declared in config.ts's votingOptions.
-     *
-     * @example
-     * _.if(_.or(Actions.allVotesIn("selectroom"), vars.voteTimer.greaterOrEqualThan(600)), () => { ... });
-     */
-    allVotesIn: (voteId: string) => import("sandstone/flow").CombinedConditions;
-    /**
-     * Records `default` for every participant who has not voted in `voteId` yet —
-     * call this when a vote phase times out so non-voters are still moved by
-     * `votedFor`. Writes the same tags the arena would (kradle.voteOptions.<voteId>
-     * and kradle.voteOptions.<voteId>.<option>).
-     *
-     * @param {string} voteId - The vote's id, e.g. "selectroom".
-     * @param {string} default - Option assigned to non-voters, e.g. "red".
-     * @throws {Error} If the vote or default option isn't declared in config.ts's votingOptions.
-     *
-     * @example
-     * Actions.assignDefaultVotes({ voteId: "selectroom", default: "red" });
-     */
-    assignDefaultVotes: ({ voteId, default: defaultOption }: {
-        voteId: string;
-        default: string;
-    }) => void;
-    /**
-     * log a message with the watcher
-     * @param {string} message - The message to send.
-     * @param {Score} variable - The variable to log.
-     * @param {boolean} store - Whether to store the variable in the backend.
-     */
-    log_variable: ({ message, variable, store }: {
-        message: string;
-        variable: Score;
-        store: boolean;
-    }) => void;
-    /**
-     * Summon an item at a specific location.
-     * @param {ITEMS} item - The item to summon.
-     * @param {number} x - The x coordinate of the location.
-     * @param {number} y - The y coordinate of the location.
-     * @param {number} z - The z coordinate of the location.
-     * @param {boolean} absolute - Whether the coordinates are absolute or relative.
-     */
-    summonItem: ({ item, x, y, z, absolute }: {
-        item: ITEMS;
-        x: number;
-        y: number;
-        z: number;
-        absolute: boolean;
-    }) => void;
-    /**
-     * Count the number of a specific item in a target's inventory.
-     * @param params - The parameters object.
-     * @param params.target - The target to count items for.
-     * @param params.item - The item to count.
-     * @returns The variable containing the item count.
-     */
-    countItems: ({ target, item }: {
-        target: TargetNames;
-        item: ITEMS;
-    }) => Score<string | undefined>;
-    /**
-     * Compute the maximum value of an individual score across all
-     * participants and store it in a global Variable. Returns the variable.
-     *
-     * Why this helper exists: end-state and end-condition checks evaluated
-     * from `events.on_tick` run in server context (the caller is a non-player
-     * entity), so an `if score @s X matches Y` check on a per-player score
-     * silently fails because @s has no entry on the per-player objective.
-     * Wrapping the comparison in this helper materializes a global "max
-     * across players" value that IS safe to reference from those checks.
-     *
-     * @param {Score} score - The per-player score to aggregate.
-     * @param {number} [min=0] - Lower bound to seed the result with. Pass a
-     *   negative value if your per-player score can go below 0 (e.g. climb's
-     *   `current_height` defaulting to -1000); otherwise the default `0`
-     *   would mask negative actual maxes.
-     * @returns {Score} An anonymous Score containing the max.
-     *
-     * @example
-     * // In a custom_variables global updater:
-     * max_diamonds: {
-     *   type: "global",
-     *   default: 0,
-     *   updater: (value, { diamonds }) => {
-     *     value.set(Actions.maxPlayerScore({ score: diamonds }));
-     *   },
-     * },
-     *
-     * // Then end-states can reference the global:
-     * .events(({ max_diamonds }) => ({
-     *   on_tick: () => Actions.setEndStates({
-     *     winner_found: max_diamonds.greaterOrEqualThan(5),
-     *   }),
-     * }))
-     *
-     * @example
-     * // Climb's max_height — y can go below 0:
-     * max_height_global: {
-     *   type: "global",
-     *   default: -1000,
-     *   updater: (value, { max_height }) => {
-     *     value.set(Actions.maxPlayerScore({ score: max_height, min: -1000 }));
-     *   },
-     * },
-     */
-    maxPlayerScore: ({ score, min }: {
-        score: Score;
-        min?: number;
-    }) => Score;
-    /**
-     * Returns a Sandstone condition that's true when the executing player
-     * (in `as @s` context) is standing on `block`. The default is a
-     * single-cell check (block at `~ ~-1 ~`), but `slop` widens the check
-     * to a `(2*slop+1)×(2*slop+1)` patch around the player's foot position
-     * — useful when the agent's pathfinder leaves them slightly off-center
-     * from a target block (e.g. mineflayer's `goToNearestBlock` reports
-     * success once within ~1.5 blocks of the target, so the agent is
-     * commonly off by a fractional block in x/z).
-     *
-     * Compiles to: `block ~ ~-1 ~ <block>` for slop=0, or an `_.or(...)` of
-     * 9 / 25 / etc. cell checks for slop=1 / 2 / etc.
-     *
-     * @example
-     * // PD-style "did the agent step on the cooperate pad?" check
-     * choice: {
-     *   type: "individual",
-     *   default: 0,
-     *   updater: (value) => {
-     *     _.if(Actions.isStandingOn({ block: "minecraft:lime_wool", slop: 1 }), () => {
-     *       value.set(COOPERATE);
-     *     });
-     *   },
-     * },
-     */
-    isStandingOn: ({ block, slop }: {
-        block: BLOCKS;
-        slop?: number;
-    }) => ConditionType;
-    /**
-     * Count instances of a block within an axis-aligned region. Useful for
-     * detecting agent-built structures without pinning detection to a single
-     * coordinate (which breaks the moment the agent moves before building).
-     *
-     * Implementation note: emits one `execute if block` check per cell in the
-     * region at codegen time, so the region is hard-capped at 4096 cells
-     * (~64×8×8) to keep the generated datapack reasonable.
-     *
-     * @param block The block ID to count (e.g. "minecraft:cobblestone").
-     * @param from First corner of the region (inclusive).
-     * @param to Opposite corner (inclusive).
-     * @param absolute Whether `from` / `to` are absolute world coordinates.
-     * @returns A Sandstone `Score` containing the count.
-     *
-     * @example
-     * // Detect any 5+ cobblestone block tower built within a 12×6×12 zone:
-     * const count = Actions.countBlocksInRegion({
-     *   block: "minecraft:cobblestone",
-     *   from: { x: -6, y: -60, z: -6 },
-     *   to: { x: 6, y: -55, z: 6 },
-     *   absolute: true,
-     * });
-     * _.if(count.greaterOrEqualThan(5), () => Actions.announce({ message: "Tower built!" }));
-     */
-    countBlocksInRegion: ({ block, from, to, absolute, }: {
-        block: BLOCKS;
-        from: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        to: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        absolute: boolean;
-    }) => Score;
-    /**
-     * Count instances of a block in a region centered on a target. Same idea
-     * as `countBlocksInRegion` but the bounds are *relative to the target's
-     * current position* — useful when the region of interest moves with a
-     * player (e.g. "how many X blocks are around the agent right now").
-     *
-     * What this is NOT: it does not verify a structure (the matches don't
-     * have to be contiguous), and it does not prove the target placed them.
-     * Treat the result as "presence count in a volume." Turn it into "the
-     * agent placed N of these" only when the block type doesn't spawn
-     * naturally in your world (and your arena init didn't pre-place any), or
-     * by clearing the volume first and counting the delta.
-     *
-     * Implementation note: emits one `execute as <target> at @s if block`
-     * check per cell at codegen time, so the region is hard-capped at 4096
-     * cells just like `countBlocksInRegion`.
-     *
-     * @example
-     * // Count diamond_block instances within 6 blocks of the agent. Diamond
-     * // blocks don't generate naturally, so in a flat-world challenge whose
-     * // arena init doesn't pre-place any, this is equivalently the count of
-     * // diamond blocks the agent has placed within reach.
-     * diamond_blocks_nearby: {
-     *   type: "individual",
-     *   default: 0,
-     *   updater: (value) => {
-     *     value.set(Actions.countBlocksRelativeTo({
-     *       target: "self",
-     *       block: "minecraft:diamond_block",
-     *       dxRange: [-6, 6],
-     *       dyRange: [-2, 4],
-     *       dzRange: [-6, 6],
-     *     }));
-     *   },
-     * }
-     */
-    countBlocksRelativeTo: ({ target, block, dxRange, dyRange, dzRange, }: {
-        target: TargetNames;
-        block: BLOCKS;
-        dxRange: [number, number];
-        dyRange: [number, number];
-        dzRange: [number, number];
-    }) => Score;
-    /**
-     * Get the current player's position as x, y, z Score variables.
-     * Must be called in a player context (e.g., inside forEveryPlayer or when @s is a player).
-     * @returns An object with x, y, z Score variables containing the player's coordinates.
-     */
-    getCurrentPlayerPosition: () => {
-        x: Score<string | undefined>;
-        y: Score<string | undefined>;
-        z: Score<string | undefined>;
-    };
-    /**
-     * Get a location marker entity by name.
-     * Returns a selector that targets the marker entity with the specified location tag.
-     * Locations must be defined in config.ts under "challengeConfig.locations".
-     * @param {string} name - The name of the location (must match a key in config.locations).
-     * @returns A selector targeting the location marker entity.
-     * @throws {Error} If KRADLE_CHALLENGE_LOCATIONS is set and the location name is not in the list.
-     */
-    getLocation: ({ name }: {
-        name: string;
-    }) => SelectorClass<true, false>;
-    /**
-     * Build a box (4 walls + optional floor/roof) in a single call. Replaces
-     * the typical 5+ `Actions.fill` calls per arena.
-     *
-     * @param block The wall block (e.g. "minecraft:stone").
-     * @param from First corner (inclusive).
-     * @param to Opposite corner (inclusive).
-     * @param absolute Whether coordinates are absolute or player-relative.
-     * @param hollow When true (default), only walls are placed; the interior is left untouched.
-     *               When false, the entire volume is filled with `block`.
-     * @param floor Optional block to fill the floor with (overrides `block` for floor only).
-     * @param roof Optional block to fill the roof with.
-     * @param clearInside When true and `hollow=true`, the interior volume is set to air
-     *                    (useful for clearing existing terrain inside the new box).
-     *
-     * @example
-     * // 13x13x5 stone arena with a stone-bricks floor, no roof, interior cleared
-     * Actions.box({
-     *   block: "minecraft:stone",
-     *   from: { x: -6, y: -60, z: -6 },
-     *   to: { x: 6, y: -55, z: 6 },
-     *   absolute: true,
-     *   hollow: true,
-     *   floor: "minecraft:stone_bricks",
-     *   clearInside: true,
-     * });
-     */
-    box: ({ block, from, to, absolute, hollow, floor, roof, clearInside, }: {
-        block: BLOCKS;
-        from: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        to: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        absolute: boolean;
-        hollow?: boolean;
-        floor?: BLOCKS;
-        roof?: BLOCKS;
-        clearInside?: BLOCKS | boolean;
-    }) => void;
-    /**
-     * Give every participant a list of items in one call. Replaces the
-     * sequence of `Actions.give({ target: "all", item: …, count: … })` calls
-     * that opens nearly every multi-player start_challenge (castle-ctf has
-     * six of them for the iron-sword + 4 armor pieces + food loadout).
-     *
-     * @example PvP standard kit:
-     * ```ts
-     * Actions.giveAll([
-     *   { item: "minecraft:iron_sword" },
-     *   { item: "minecraft:iron_helmet" },
-     *   { item: "minecraft:iron_chestplate" },
-     *   { item: "minecraft:iron_leggings" },
-     *   { item: "minecraft:iron_boots" },
-     *   { item: "minecraft:cooked_beef", count: 5 },
-     * ]);
-     * ```
-     *
-     * `count` defaults to 1. For role-specific equipment, use plain
-     * `Actions.give({ target: roleName, … })`.
-     */
-    giveAll: (items: Array<{
-        item: ITEMS;
-        count?: number;
-    }>) => void;
-    /**
-     * "When the block at this absolute coordinate stops being `expected`, set
-     * `into` to 1." The standard goal_broken / flag_broken global-variable
-     * updater idiom. Latches at 1 — once tripped, stays tripped (so the
-     * end_state fires consistently even if the block is later replaced).
-     *
-     * Replaces the 4-line `_.if(_.not(_.block(abs(...), ...)), () => value.set(1))`
-     * pattern that appears in ~10 challenges' custom_variable updaters
-     * (castle-ctf×2, castle-siege×4, defender-striker, beanstalk, tower-trio,
-     * tunnel-rush, sky-walker, …). Removes the need to import `abs` from
-     * sandstone for this purpose.
-     *
-     * For multi-block checks ("all N landmarks broken" — diamond-hunt,
-     * return-home), keep using the manual `_.if(_.and(...conditions), …)`
-     * pattern — this helper is single-block only.
-     *
-     * @example castle-ctf red flag (latching — once broken, stays broken):
-     * ```ts
-     * red_flag_broken: {
-     *   type: "global",
-     *   default: 0,
-     *   updater: (value) => {
-     *     // Latch: only flip 0→1, never reset to 0. The returned Score is
-     *     // itself a Condition (truthy = non-zero), so no `.equalTo(1)` needed.
-     *     _.if(Actions.detectBlockMissing({
-     *       at: { x: RED_BASE.x, y: RED_BASE.y + 1, z: RED_BASE.z },
-     *       expected: "minecraft:red_wool",
-     *     }), () => value.set(1));
-     *   },
-     * }
-     * ```
-     *
-     * @returns {Score} An anonymous Score: 1 if the block at `at` is NOT
-     *   `expected`, 0 if it is. Non-latching — recomputed every call. Wrap in
-     *   `_.if(missing, () => value.set(1))` (the Score is itself a Condition,
-     *   truthy = non-zero) for the latching "once broken, stays broken" pattern.
-     */
-    detectBlockMissing: ({ at, expected }: {
-        at: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        expected: BLOCKS;
-    }) => Score;
-    /**
-     * Summon a single configurable entity with optional health, attack damage,
-     * movement speed, and tags. Uses Sandstone's typed `summon` + NBT helpers
-     * (`NBT.byte`, `NBT.float`) so that booleans and NBT primitives serialize
-     * correctly — sandstone otherwise emits JS `true` as `{}` (an invalid NBT
-     * token), which broke boss-brawl's `CustomNameVisible: true` summon early on.
-     *
-     * For boss-style configured mobs (boss-solo, boss-brawl). Use
-     * `Actions.summonMultiple` for plain entities without stat overrides.
-     *
-     * @example A 60-HP fast-moving boss zombie:
-     * ```ts
-     * Actions.summonEntityWithStats({
-     *   entity: "minecraft:zombie",
-     *   x: 0, y: -60, z: 0, absolute: true,
-     *   health: 60,
-     *   attackDamage: 6,
-     *   movementSpeed: 0.18,
-     *   tags: ["boss"],   // for `Actions.countEntities({ tag: "boss", … })`
-     * });
-     * ```
-     */
-    summonEntityWithStats: ({ entity, x, y, z, absolute, health, attackDamage, movementSpeed, tags, }: {
-        entity: ENTITY_TYPES;
-        x: number;
-        y: number;
-        z: number;
-        absolute: boolean;
-        health?: number;
-        attackDamage?: number;
-        movementSpeed?: number;
-        tags?: string[];
-    }) => void;
-    /**
-     * Count entities matching any combination of `entity` type, `tag`, and/or
-     * `volume`, returning the count as an anonymous `Score`. At least one
-     * filter must be provided (counting "every entity in the world" is almost
-     * always a bug — guarded at runtime).
-     *
-     * Use this in a global custom_variable updater whose value tracks "how
-     * many Xs are currently in the world", e.g. boss alive (zombie count),
-     * chickens left, sheep in a pen.
-     *
-     * @param entity Optional entity type (e.g. `"minecraft:zombie"`).
-     * @param tag Optional tag filter (Minecraft `@e[tag=…]`). Used by e.g.
-     *   boss-brawl, which counts zombies tagged `"boss"` to ignore wave-spawned mooks.
-     * @param volume Optional bounding box (Minecraft-style: corner + dx/dy/dz
-     *   extents, absolute coords). Omit to count anywhere in the world.
-     * @returns {Score} An anonymous Score holding the count.
-     *
-     * @example boss_alive — counts zombies anywhere
-     * ```ts
-     * boss_alive: {
-     *   type: "global",
-     *   default: 1,
-     *   updater: (value) => {
-     *     value.set(Actions.countEntities({ entity: "minecraft:zombie" }));
-     *   },
-     * }
-     * ```
-     *
-     * @example boss-brawl — count only the tagged boss zombies
-     * ```ts
-     * value.set(Actions.countEntities({ entity: "minecraft:zombie", tag: "boss" }));
-     * ```
-     *
-     * @example sheep_in_pen — counts sheep inside a 3×1×3 box
-     * ```ts
-     * value.set(Actions.countEntities({
-     *   entity: "minecraft:sheep",
-     *   volume: { x: 14, y: -59, z: -1, dx: 2, dy: 1, dz: 2 },
-     * }));
-     * ```
-     */
-    countEntities: ({ entity, tag, volume, }: {
-        entity?: ENTITY_TYPES;
-        tag?: string;
-        volume?: {
-            x: number;
-            y: number;
-            z: number;
-            dx: number;
-            dy: number;
-            dz: number;
-        };
-    }) => Score;
-    /**
-     * Build a flat open arena: a single-block-thick floor at `center.y` with
-     * cleared airspace above up to `headroom` blocks tall. The "no walls,
-     * just open ground for things to move on" pattern shared by sumo-arena,
-     * boss-brawl, wave-survival, stalker, and one half of defender-striker.
-     *
-     * For arenas with walls, use `Actions.box({ hollow: true, floor: … })`.
-     *
-     * @example
-     *   Actions.flatArena({
-     *     block: "minecraft:stone",
-     *     center: { x: 0, y: -60, z: 0 },
-     *     radius: 10,       // 21×21 footprint
-     *     headroom: 4,      // 4 blocks of air above the floor (default 4)
-     *   });
-     */
-    flatArena: ({ block, center, radius, headroom, }: {
-        block: BLOCKS;
-        center: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        radius: number;
-        /** How many blocks of air to clear above the floor. Default 4. */
-        headroom?: number;
-    }) => void;
-    /**
-     * Apply a non-lethal knockback / displacement to a target via Minecraft's
-     * `effect` command. The default effect is a brief levitation (lifts the
-     * target straight up without dealing damage).
-     *
-     * Use `mode: "slowfall"` to combine levitation with slow falling so the
-     * target doesn't take fall damage on landing.
-     *
-     * @example
-     * // Periodic knockback in King-of-the-Hill style:
-     * Actions.knockbackWithLevitation({ target: "all", durationSeconds: 2, amplifier: 6 });
-     *
-     * // Knock with slow-fall for safe landing:
-     * Actions.knockbackWithLevitation({ target: "self", mode: "slowfall", durationSeconds: 3 });
-     */
-    knockbackWithLevitation: ({ target, durationSeconds, amplifier, mode, }: {
-        target: TargetNames;
-        durationSeconds?: number;
-        amplifier?: number;
-        mode?: "levitation" | "slowfall";
-    }) => void;
-};
-//# sourceMappingURL=actions.d.ts.map