@kradle/challenges-sdk 0.5.3 → 0.6.1

package/dist/actions.js

@@ -25,6 +25,35 @@ function mapTarget(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.
@@ -33,6 +62,65 @@ exports.Actions = {
     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.
@@ -58,6 +146,7 @@ exports.Actions = {
      * @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
@@ -165,6 +254,34 @@ exports.Actions = {
     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.
@@ -207,6 +324,50 @@ exports.Actions = {
         }
         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.
      */
@@ -265,6 +426,137 @@ exports.Actions = {
     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.
@@ -284,8 +576,8 @@ exports.Actions = {
      * @param {boolean} absolute - Whether the coordinates are absolute or relative.
      */
     summonItem: ({ item, x, y, z, absolute }) => {
-        const abs = absolute ? "" : "~";
-        (0, sandstone_1.raw)(`summon item ${abs}${x} ${abs}${y} ${abs}${z} {Item:{id:"${item}",Count:1b}}`);
+        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.
@@ -299,6 +591,219 @@ exports.Actions = {
         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).
@@ -333,5 +838,296 @@ exports.Actions = {
         }
         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 init_participants (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