@kradle/challenges-sdk 0.10.0 → 0.12.0

package/dist/actions.js

@@ -1,1155 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Actions = void 0;
-exports.mapTarget = mapTarget;
-const node_crypto_1 = __importDefault(require("node:crypto"));
-const sandstone_1 = require("sandstone");
-const commands_1 = require("./commands");
-const constants_1 = require("./constants");
-function mapTarget(target) {
-    switch (target) {
-        case "all":
-            return constants_1.ALL;
-        case "self":
-            return "@s";
-    }
-    if (target instanceof sandstone_1.SelectorClass) {
-        return target;
-    }
-    // Raw selectors ("@s", "@a", "@p", "@e", "@r") are a footgun: they fall
-    // through to the role-tag branch as Selector("@a", { tag: "@s" }) and
-    // silently match nobody. Require "self", "all", a role name, or a Selector.
-    if (target.startsWith("@")) {
-        throw new Error(`mapTarget: raw selector "${target}" is not allowed — use "self", "all", a role name, or a Selector(...).`);
-    }
-    // check if the target is a valid entity type
-    if (target.startsWith("minecraft:")) {
-        return (0, sandstone_1.Selector)("@e", { type: target });
-    }
-    return (0, sandstone_1.Selector)("@a", { tag: target }); // Treat unknown string targets as a role name (roles are stored as player tags)
-}
-/**
- * Throws if `voteId` — or, when given, `option` — isn't declared in config.ts's
- * `challengeConfig.votingOptions` (passed at build time as
- * `KRADLE_CHALLENGE_VOTING_OPTIONS`), mirroring `getLocation`/`setEndState`.
- * No-op when the env var is unset (e.g. running `challenge.ts` outside the CLI).
- */
-function assertDeclaredVote(voteId, option) {
-    const declared = process.env.KRADLE_CHALLENGE_VOTING_OPTIONS;
-    if (!declared)
-        return;
-    const votes = JSON.parse(declared);
-    const options = votes[voteId];
-    if (!options) {
-        throw new Error(`Invalid vote "${voteId}". Valid votes are: ${Object.keys(votes).join(", ")}. ` +
-            `Make sure the vote is defined in config.ts under "challengeConfig.votingOptions".`);
-    }
-    if (option !== undefined && !options.includes(option)) {
-        throw new Error(`Invalid option "${option}" for vote "${voteId}". Valid options are: ${options.join(", ")}.`);
-    }
-}
-/**
- * Selects participants who haven't voted in `voteId` yet (missing the
- * `kradle.voteOptions.<voteId>` tag). The multi-tag, `!`-negated form needs
- * `as never` because Sandstone's Selector `tag` type doesn't accept a string[]
- * (same workaround as api_utils.ts).
- */
-function participantsMissingVote(voteId) {
-    return (0, sandstone_1.Selector)("@a", { tag: [constants_1.KRADLE_PARTICIPANT_TAG, `!kradle.voteOptions.${voteId}`] });
-}
-exports.Actions = {
-    /**
-     * Send a chat message to everyone.
-     * @param {JSONTextComponent} message - The message to send.
-     */
-    announce: ({ message }) => {
-        (0, sandstone_1.tellraw)("@a", ["\n", { text: constants_1.DISPLAY_TAG, color: "aqua" }, " | ", message, "\n"]);
-    },
-    /**
-     * 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 }) => {
-        sandstone_1.execute.as((0, sandstone_1.Selector)("@a", { tag: constants_1.KRADLE_PARTICIPANT_TAG, sort: "random", limit: count })).run(() => {
-            (0, sandstone_1.tag)("@s").add(tagName);
-        });
-    },
-    /**
-     * 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 }) => {
-        const result = (0, sandstone_1.Variable)(0);
-        // Sandstone has no typed wrapper for `random value <min>..<max>`.
-        // This is the single legitimate `raw` in the SDK — encapsulating it
-        // here means user code never has to. Once Sandstone gains the
-        // command, swap the body for `execute.store.result.score(result).run.random.value(...)`.
-        (0, sandstone_1.raw)(`execute store result score ${result.target} ${result.objective.name} run random value ${min}..${max}`);
-        return result;
-    },
-    /**
-     * Clear the inventory of a target.
-     * @param {TargetNames} target - The target to clear the inventory of.
-     */
-    clear: ({ target }) => {
-        (0, sandstone_1.clear)(mapTarget(target));
-    },
-    /**
-     * 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, }) => {
-        // fill the region with the block
-        if (mode === "fill") {
-            const coordinates1 = absolute ? (0, sandstone_1.abs)(x1, y1, z1) : (0, sandstone_1.rel)(x1, y1, z1);
-            const coordinates2 = absolute ? (0, sandstone_1.abs)(x2, y2, z2) : (0, sandstone_1.rel)(x2, y2, z2);
-            (0, sandstone_1.fill)(coordinates1, coordinates2, block);
-            return;
-        }
-        // draw a line from the first coordinate to the second coordinate
-        if (mode === "line") {
-            const dx = x2 - x1;
-            const dy = y2 - y1;
-            const dz = z2 - z1;
-            const length = Math.max(Math.abs(dx), Math.abs(dy), Math.abs(dz));
-            const stepX = dx / length || 0;
-            const stepY = dy / length || 0;
-            const stepZ = dz / length || 0;
-            for (let i = 0; i <= length; i++) {
-                const x = Math.round(x1 + stepX * i);
-                const y = Math.round(y1 + stepY * i);
-                const z = Math.round(z1 + stepZ * i);
-                (0, sandstone_1.setblock)(absolute ? (0, sandstone_1.abs)(x, y, z) : (0, sandstone_1.rel)(x, y, z), block);
-            }
-            return;
-        }
-        if (mode === "pyramid") {
-            const height = Math.abs(y2);
-            const direction = Math.sign(y2); // +1 for up, -1 for down
-            for (let i = 0; i < height; i++) {
-                const y = y1 + i * direction;
-                const layerRadius = (height - 1 - i) * 2;
-                const minX = x1 - layerRadius;
-                const maxX = x1 + layerRadius;
-                const minZ = z1 - layerRadius;
-                const maxZ = z1 + layerRadius;
-                for (let x = minX; x <= maxX; x++) {
-                    for (let z = minZ; z <= maxZ; z++) {
-                        (0, sandstone_1.setblock)(absolute ? (0, sandstone_1.abs)(x, y, z) : (0, sandstone_1.rel)(x, y, z), block);
-                    }
-                }
-            }
-            return;
-        }
-        // if mode is not fill or line, throw an error
-        throw new Error(`Invalid fill mode: ${mode}`);
-    },
-    /**
-     * 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 = 1 }) => {
-        (0, sandstone_1.give)(mapTarget(target), item, count);
-    },
-    /**
-     * 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 }) => {
-        // sort incoming items and create a hash for table re-use
-        const lootItemsSorted = [...items].sort((a, b) => a.name.localeCompare(b.name));
-        const lootItemsJson = JSON.stringify(lootItemsSorted);
-        const lootItemsHash = node_crypto_1.default.createHash("sha256").update(lootItemsJson).digest("hex");
-        const lootTableName = `loot_${lootItemsHash}`.slice(0, 16);
-        // create the entries for the loot table
-        const entries = items.map((item) => ({
-            type: "minecraft:item",
-            name: item.name,
-            weight: item.weight,
-            functions: [
-                {
-                    function: "set_count",
-                    count: item.count,
-                },
-            ],
-        }));
-        // create the loot table with simple settings
-        const lootTable = {
-            type: "minecraft:generic",
-            pools: [
-                {
-                    rolls: 1,
-                    entries,
-                },
-            ],
-        };
-        // on conflict, ignore because we can re-use duplicate loot tables
-        (0, sandstone_1.LootTable)(lootTableName, lootTable, { onConflict: "ignore" }).give(mapTarget(target));
-    },
-    /**
-     * 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 }) => {
-        (0, sandstone_1.gamerule)(rule, value);
-    },
-    /**
-     * Kill entities matching a selector.
-     * @param {SelectorArgument} selector - The entities to kill.
-     */
-    kill: ({ selector }) => {
-        (0, sandstone_1.kill)(mapTarget(selector));
-    },
-    /**
-     * 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, }) => {
-        (0, sandstone_1.gamemode)(mode, mapTarget(target));
-    },
-    /**
-     * 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 }) => {
-        (0, sandstone_1.gamemode)("spectator", mapTarget(target));
-    },
-    /**
-     * 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 }) => {
-        sandstone_1.execute.as(mapTarget(target)).run.attribute("@s", attribute_).baseSet(value);
-    },
-    /**
-     * Set the time of day.
-     * @param {'day' | 'night'} time_ - The time to set.
-     */
-    setTime: ({ time }) => {
-        sandstone_1.time.set(time);
-    },
-    /**
-     * Summon multiple entities at a specific location.
-     */
-    summonMultiple: (params) => {
-        const coordinates = params.absolute ? (0, sandstone_1.abs)(params.x, params.y, params.z) : (0, sandstone_1.rel)(params.x, params.y, params.z);
-        for (let i = 0; i < params.count; i++) {
-            (0, sandstone_1.summon)(params.entity, coordinates);
-        }
-    },
-    /**
-     * 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 }) => {
-        // Validate end state against allowed values if env var is set
-        const allowedEndStates = process.env.KRADLE_CHALLENGE_END_STATES;
-        if (allowedEndStates) {
-            const validEndStates = JSON.parse(allowedEndStates);
-            if (!validEndStates.includes(endState)) {
-                throw new Error(`Invalid end state "${endState}". Valid end states are: ${validEndStates.join(", ")}. ` +
-                    `Make sure the end state is defined in config.ts under "endStates".`);
-            }
-        }
-        sandstone_1.data.modify.storage(constants_1.KRADLE_STORAGE, constants_1.END_STATE_KEY).set.value(endState);
-    },
-    /**
-     * 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) => {
-        const entries = Object.entries(endStates);
-        if (entries.length === 0) {
-            throw new Error("Actions.setEndStates: at least one end-state must be provided.");
-        }
-        for (const [name, condition] of entries) {
-            sandstone_1._.if(condition, () => {
-                exports.Actions.setEndState({ endState: name });
-            });
-        }
-        const conditions = entries.map(([, condition]) => condition);
-        return conditions.length === 1 ? conditions[0] : sandstone_1._.or(...conditions);
-    },
-    /**
-     * Set a block at a specific location.
-     */
-    setBlock: (params) => {
-        const coordinates = params.absolute ? (0, sandstone_1.abs)(params.x, params.y, params.z) : (0, sandstone_1.rel)(params.x, params.y, params.z);
-        (0, sandstone_1.setblock)(coordinates, params.block);
-    },
-    /**
-     * 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) => {
-        if ("x" in args) {
-            const { target, x, y, z, absolute } = args;
-            const coordinates = absolute ? (0, sandstone_1.abs)(x, y, z) : (0, sandstone_1.rel)(x, y, z);
-            (0, sandstone_1.teleport)(mapTarget(target), coordinates);
-        }
-        else {
-            const { target, toEntity } = args;
-            (0, sandstone_1.teleport)(mapTarget(target), toEntity);
-        }
-    },
-    /**
-     * 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 }) => {
-        const t = mapTarget(target);
-        // mapTarget returns the "@s" string for "self"; wrap it as a Selector so
-        // the command can emit it. @s only resolves per-player, so a misplaced
-        // forceMoveTo("self") is caught by the context-safety check, not here.
-        const selector = t instanceof sandstone_1.SelectorClass ? t : (0, sandstone_1.Selector)("@s");
-        commands_1.Commands.forceMoveTo(selector, x, y, z);
-    },
-    /**
-     * 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 }) => {
-        (0, sandstone_1.tellraw)(mapTarget(target), ["\n", { text: constants_1.DISPLAY_TAG, color: "aqua" }, " | ", message, "\n"]);
-    },
-    // Score operations
-    /**
-     * Increment a score variable by 1.
-     * @param variable - The score variable to increment.
-     */
-    increment: ({ variable }) => {
-        variable.add(1);
-    },
-    /**
-     * Decrement a score variable by 1.
-     * @param variable - The score variable to decrement.
-     */
-    decrement: ({ variable }) => {
-        variable.remove(1);
-    },
-    /**
-     * 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.set(value);
-    },
-    /**
-     * 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 }) => (0, sandstone_1.Selector)("@s", {
-        ...(role ? { tag: role } : {}),
-        x,
-        y: y + 1,
-        z,
-        dx: 0,
-        dy: 1,
-        dz: 0,
-    }),
-    /**
-     * 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, option) => {
-        assertDeclaredVote(voteId, option);
-        return (0, sandstone_1.Selector)("@s", {
-            tag: `kradle.voteOptions.${voteId}${option ? `.${option}` : ""}`,
-        });
-    },
-    /**
-     * 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 }) => {
-        assertDeclaredVote(voteId);
-        for (const option of options)
-            assertDeclaredVote(voteId, option);
-        exports.Actions.announce({
-            message: `${prompt} Vote with skills.voteForOption("${voteId}", option) — options: ${options.join(", ")}.`,
-        });
-    },
-    /**
-     * 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) => {
-        assertDeclaredVote(voteId);
-        return sandstone_1._.not(participantsMissingVote(voteId));
-    },
-    /**
-     * 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 }) => {
-        assertDeclaredVote(voteId, defaultOption);
-        sandstone_1.execute.as(participantsMissingVote(voteId)).run(() => {
-            (0, sandstone_1.tag)("@s").add(`kradle.voteOptions.${voteId}`);
-            (0, sandstone_1.tag)("@s").add(`kradle.voteOptions.${voteId}.${defaultOption}`);
-        });
-    },
-    /**
-     * 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.
-     */
-    // WARNING: the logs must have precisely this structure to be read by the watcher. DO NOT CHANGE THE STRUCTURE.
-    log_variable: ({ message, variable, store }) => {
-        commands_1.Commands.logVariable(message, variable, store);
-    },
-    /**
-     * 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 }) => {
-        const pos = absolute ? (0, sandstone_1.abs)(x, y, z) : (0, sandstone_1.rel)(x, y, z);
-        (0, sandstone_1.summon)("minecraft:item", pos, { Item: { id: item, Count: sandstone_1.NBT.byte(1) } });
-    },
-    /**
-     * 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 }) => {
-        const variable = (0, sandstone_1.Variable)();
-        sandstone_1.execute.store.result.score(variable).run.clear(mapTarget(target), item, 0);
-        return variable;
-    },
-    /**
-     * 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 = 0 }) => {
-        const result = (0, sandstone_1.Variable)(min);
-        // Iterate over participants; for each, if their `score` exceeds the
-        // running max, copy it in. Same pattern an author would write by
-        // hand with forEveryPlayer + _.if(score.greaterThan(result), ...).
-        sandstone_1.execute.as(constants_1.ALL).run(() => {
-            sandstone_1._.if(score.greaterThan(result), () => {
-                result.set(score);
-            });
-        });
-        return result;
-    },
-    /**
-     * 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 = 0 }) => {
-        if (slop < 0 || !Number.isInteger(slop)) {
-            throw new Error(`Actions.isStandingOn: slop must be a non-negative integer, got ${slop}`);
-        }
-        if (slop === 0) {
-            return sandstone_1._.block((0, sandstone_1.rel)(0, -1, 0), block);
-        }
-        const conditions = [];
-        for (let dx = -slop; dx <= slop; dx++) {
-            for (let dz = -slop; dz <= slop; dz++) {
-                conditions.push(sandstone_1._.block((0, sandstone_1.rel)(dx, -1, dz), block));
-            }
-        }
-        return sandstone_1._.or(...conditions);
-    },
-    /**
-     * 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, }) => {
-        const x1 = Math.min(from.x, to.x);
-        const x2 = Math.max(from.x, to.x);
-        const y1 = Math.min(from.y, to.y);
-        const y2 = Math.max(from.y, to.y);
-        const z1 = Math.min(from.z, to.z);
-        const z2 = Math.max(from.z, to.z);
-        const cellCount = (x2 - x1 + 1) * (y2 - y1 + 1) * (z2 - z1 + 1);
-        const MAX_CELLS = 4096;
-        if (cellCount > MAX_CELLS) {
-            throw new Error(`Actions.countBlocksInRegion: region has ${cellCount} cells, exceeding the safety cap of ${MAX_CELLS}. ` +
-                `Reduce the bounding box or use a smaller scan area.`);
-        }
-        const counter = (0, sandstone_1.Variable)();
-        counter.set(0);
-        for (let x = x1; x <= x2; x++) {
-            for (let y = y1; y <= y2; y++) {
-                for (let z = z1; z <= z2; z++) {
-                    const coords = absolute ? (0, sandstone_1.abs)(x, y, z) : (0, sandstone_1.rel)(x, y, z);
-                    sandstone_1.execute.if.block(coords, block).run(() => {
-                        counter.add(1);
-                    });
-                }
-            }
-        }
-        return counter;
-    },
-    /**
-     * 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, }) => {
-        const [dx1, dx2] = [Math.min(...dxRange), Math.max(...dxRange)];
-        const [dy1, dy2] = [Math.min(...dyRange), Math.max(...dyRange)];
-        const [dz1, dz2] = [Math.min(...dzRange), Math.max(...dzRange)];
-        const cellCount = (dx2 - dx1 + 1) * (dy2 - dy1 + 1) * (dz2 - dz1 + 1);
-        const MAX_CELLS = 4096;
-        if (cellCount > MAX_CELLS) {
-            throw new Error(`Actions.countBlocksRelativeTo: region has ${cellCount} cells, exceeding the safety cap of ${MAX_CELLS}. ` +
-                `Reduce dx/dy/dzRange or scan in slices.`);
-        }
-        const counter = (0, sandstone_1.Variable)();
-        counter.set(0);
-        sandstone_1.execute
-            .as(mapTarget(target))
-            .at("@s")
-            .run(() => {
-            for (let dx = dx1; dx <= dx2; dx++) {
-                for (let dy = dy1; dy <= dy2; dy++) {
-                    for (let dz = dz1; dz <= dz2; dz++) {
-                        sandstone_1.execute.if.block((0, sandstone_1.rel)(dx, dy, dz), block).run(() => {
-                            counter.add(1);
-                        });
-                    }
-                }
-            }
-        });
-        return counter;
-    },
-    /**
-     * 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: () => {
-        const x = (0, sandstone_1.Variable)();
-        const y = (0, sandstone_1.Variable)();
-        const z = (0, sandstone_1.Variable)();
-        sandstone_1.execute.store.result.score(x).run.data.get.entity("@s", "Pos[0]");
-        sandstone_1.execute.store.result.score(y).run.data.get.entity("@s", "Pos[1]");
-        sandstone_1.execute.store.result.score(z).run.data.get.entity("@s", "Pos[2]");
-        return { x, y, z };
-    },
-    /**
-     * 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 }) => {
-        // Validate location against allowed values if env var is set
-        const allowedLocations = process.env.KRADLE_CHALLENGE_LOCATIONS;
-        if (allowedLocations) {
-            const validLocations = JSON.parse(allowedLocations);
-            if (!validLocations.includes(name)) {
-                throw new Error(`Invalid location "${name}". Valid locations are: ${validLocations.join(", ")}. ` +
-                    `Make sure the location is defined in config.ts under "challengeConfig.locations".`);
-            }
-        }
-        return (0, sandstone_1.Selector)("@e", { type: "minecraft:marker", tag: `kradle.location.${name}`, limit: 1 });
-    },
-    /**
-     * 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 = true, floor, roof, clearInside = false, }) => {
-        const x1 = Math.min(from.x, to.x);
-        const x2 = Math.max(from.x, to.x);
-        const y1 = Math.min(from.y, to.y);
-        const y2 = Math.max(from.y, to.y);
-        const z1 = Math.min(from.z, to.z);
-        const z2 = Math.max(from.z, to.z);
-        const fillRegion = (b, ax, ay, az, bx, by, bz) => {
-            const c1 = absolute ? (0, sandstone_1.abs)(ax, ay, az) : (0, sandstone_1.rel)(ax, ay, az);
-            const c2 = absolute ? (0, sandstone_1.abs)(bx, by, bz) : (0, sandstone_1.rel)(bx, by, bz);
-            (0, sandstone_1.fill)(c1, c2, b);
-        };
-        if (!hollow) {
-            fillRegion(block, x1, y1, z1, x2, y2, z2);
-            if (floor)
-                fillRegion(floor, x1, y1, z1, x2, y1, z2);
-            if (roof)
-                fillRegion(roof, x1, y2, z1, x2, y2, z2);
-            return;
-        }
-        // Walls: two pairs of opposite faces.
-        // North/south
-        fillRegion(block, x1, y1, z1, x2, y2, z1);
-        fillRegion(block, x1, y1, z2, x2, y2, z2);
-        // East/west
-        fillRegion(block, x1, y1, z1, x1, y2, z2);
-        fillRegion(block, x2, y1, z1, x2, y2, z2);
-        if (floor)
-            fillRegion(floor, x1, y1, z1, x2, y1, z2);
-        if (roof)
-            fillRegion(roof, x1, y2, z1, x2, y2, z2);
-        if (clearInside) {
-            const interiorBlock = clearInside === true ? "minecraft:air" : clearInside;
-            // Only fill the interior if there's actually room (>= 3 in each axis).
-            if (x2 - x1 >= 2 && y2 - y1 >= 2 && z2 - z1 >= 2) {
-                fillRegion(interiorBlock, x1 + 1, y1 + 1, z1 + 1, x2 - 1, y2 - 1, z2 - 1);
-            }
-        }
-    },
-    /**
-     * 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) => {
-        for (const it of items) {
-            (0, sandstone_1.give)(mapTarget("all"), it.item, it.count ?? 1);
-        }
-    },
-    /**
-     * "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 }) => {
-        const result = (0, sandstone_1.Variable)(0);
-        sandstone_1._.if(sandstone_1._.not(sandstone_1._.block((0, sandstone_1.abs)(at.x, at.y, at.z), expected)), () => {
-            result.set(1);
-        });
-        return result;
-    },
-    /**
-     * 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, }) => {
-        const attributes = [];
-        if (health !== undefined)
-            attributes.push({ Name: "generic.max_health", Base: health });
-        if (attackDamage !== undefined)
-            attributes.push({ Name: "generic.attack_damage", Base: attackDamage });
-        if (movementSpeed !== undefined)
-            attributes.push({ Name: "generic.movement_speed", Base: movementSpeed });
-        const nbt = {};
-        if (health !== undefined)
-            nbt.Health = sandstone_1.NBT.float(health);
-        if (attributes.length > 0)
-            nbt.Attributes = attributes;
-        if (tags !== undefined && tags.length > 0)
-            nbt.Tags = tags;
-        const pos = absolute ? (0, sandstone_1.abs)(x, y, z) : (0, sandstone_1.rel)(x, y, z);
-        (0, sandstone_1.summon)(entity, pos, nbt);
-    },
-    /**
-     * 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, }) => {
-        if (!entity && !tag && !volume) {
-            throw new Error("Actions.countEntities requires at least one of `entity`, `tag`, or `volume` — counting every entity in the world is almost always a bug.");
-        }
-        const result = (0, sandstone_1.Variable)(0);
-        const selectorParams = {};
-        if (entity)
-            selectorParams.type = entity;
-        if (tag)
-            selectorParams.tag = tag;
-        if (volume) {
-            selectorParams.x = volume.x;
-            selectorParams.y = volume.y;
-            selectorParams.z = volume.z;
-            selectorParams.dx = volume.dx;
-            selectorParams.dy = volume.dy;
-            selectorParams.dz = volume.dz;
-        }
-        sandstone_1.execute.as((0, sandstone_1.Selector)("@e", selectorParams)).run(() => {
-            result.add(1);
-        });
-        return result;
-    },
-    /**
-     * 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 = 4, }) => {
-        const x_min = center.x - radius;
-        const x_max = center.x + radius;
-        const z_min = center.z - radius;
-        const z_max = center.z + radius;
-        // Floor at center.y.
-        (0, sandstone_1.fill)((0, sandstone_1.abs)(x_min, center.y, z_min), (0, sandstone_1.abs)(x_max, center.y, z_max), block);
-        // Clear air above (skip if headroom <= 0).
-        if (headroom > 0) {
-            (0, sandstone_1.fill)((0, sandstone_1.abs)(x_min, center.y + 1, z_min), (0, sandstone_1.abs)(x_max, center.y + headroom, z_max), "minecraft:air");
-        }
-    },
-    /**
-     * 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 = 1, amplifier = 5, mode = "levitation", }) => {
-        const t = mapTarget(target);
-        sandstone_1.effect.give(t, "minecraft:levitation", durationSeconds, amplifier, true);
-        if (mode === "slowfall") {
-            // 8s of slow-falling — covers most levitation falls without damage.
-            sandstone_1.effect.give(t, "minecraft:slow_falling", durationSeconds + 8, 0, true);
-        }
-    },
-};
-//# sourceMappingURL=actions.js.map