@kradle/challenges-sdk 0.5.3 → 0.6.1

package/dist/actions.d.ts

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