@kradle/challenges-sdk 0.5.3 → 0.6.1

package/LLM_README.md

@@ -6,15 +6,50 @@ This document provides exhaustive API documentation for AI agents using the `@kr
 
 1. [Overview](#overview)
 2. [Installation](#installation)
-3. [Core Concepts](#core-concepts)
-4. [createChallenge API](#createchallenge-api)
-5. [Variables](#variables)
-6. [Events](#events)
-7. [Actions](#actions)
-8. [Utilities](#utilities)
-9. [Sandstone Integration](#sandstone-integration)
-10. [Complete Examples](#complete-examples)
-11. [Common Patterns](#common-patterns)
+3. [Helpers — start here](#helpers--start-here)
+4. [Core Concepts](#core-concepts)
+5. [createChallenge API](#createchallenge-api)
+6. [Variables](#variables)
+7. [Events](#events)
+8. [Actions](#actions)
+9. [Utilities](#utilities)
+10. [Sandstone Integration](#sandstone-integration)
+11. [Complete Examples](#complete-examples)
+12. [Common Patterns](#common-patterns)
+13. [Common Gotchas](#common-gotchas)
+
+---
+
+## Helpers — start here
+
+These compress arena geometry / detection patterns that show up in nearly every challenge. Reach for them before writing raw `Actions.fill` loops or `execute if block` chains.
+
+| Helper | What it does | Use instead of |
+|--------|--------------|----------------|
+| **`Actions.box(...)`** | Stone floor + 4 walls (or full hollow box, with optional roof / interior clearing) — single call. Full reference below in [World](#world). | Five separate `Actions.fill` calls per arena |
+| **`Actions.flatArena({ block, center, radius, headroom? })`** | Single-block-thick floor + cleared airspace above, no walls. The "open ground for things to move on" pattern from boss-brawl, sumo-arena, wave-survival, stalker. | Two manual `Actions.fill` calls (one stone, one air) per arena |
+| **`Actions.countEntities({ entity?, tag?, volume? }): Score`** | Counts entities matching any combination of `entity` type, `tag`, and/or `volume`. Returns an anonymous `Score` — the caller assigns it into their custom_variable (`value.set(Actions.countEntities({ entity: "minecraft:zombie" }))`). At least one filter must be provided (counting "every entity in the world" throws at build). Drop-in replacement for the `value.set(0); execute.as(Selector("@e", { type })).run(() => value.add(1))` pattern that shows up in 8+ challenges' custom_variable updaters. | Hand-rolled `execute.as(Selector(...)).run(...)` chain |
+| **`Actions.countBlocksInRegion(...)` / `Actions.countBlocksRelativeTo(...)`** | Counts a block ID across a 3D region; returns a `Score` you can drive end-states off. | `_.if(_.block(abs(x,y,z), ...))` chains across many cells |
+| **`Actions.maxPlayerScore({ score, min? }): Score`** | Reads a per-player `Score` and returns the maximum across all players as an anonymous `Score`. `min` (default 0) seeds the result before the sweep — 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. Caller writes into a global custom_variable: `value.set(Actions.maxPlayerScore({ score: diamonds }))`. Lets `Actions.setEndStates` / `.end_condition` reference "any player has X" semantics correctly. | Manual `execute as @a if score @s …` loops |
+| **`Actions.randomInt({ min, max }): Score`** | Uniform random integer in `[min, max]` returned as an anonymous `Score`. Wraps Minecraft's `random value` (which Sandstone has no typed wrapper for; this helper exists so user code never reaches for `raw`). | `raw("execute store result score … run random value …")` |
+| **`Actions.detectBlockMissing({ at, expected }): Score`** | Returns 1 if the block at `at` is NOT `expected`, 0 if it is. Non-latching — wrap in `_.if(missing, () => value.set(1))` for the latching "once broken, stays broken" pattern (castle-ctf, castle-siege, beanstalk). | Manual `_.if(_.not(_.block(abs(...), expected)), () => value.set(1))` |
+| **`Actions.knockbackWithLevitation({ target, mode, durationSeconds, amplifier })`** | Levitation (or levitation + slow-fall) effect for non-lethal displacement. | Hand-rolled `effect give … levitation` |
+
+Worked example using `Actions.box`:
+
+```typescript
+import { Actions } from "@kradle/challenges-sdk";
+
+// 17×17 stone arena, 4-block walls, no roof — what boss-solo / melee-arena need.
+Actions.box({
+  block: "minecraft:stone",
+  from: { x: -8, y: -60, z: -8 },
+  to:   { x:  8, y: -56, z:  8 },
+  absolute: true,
+  hollow: true,
+  floor: "minecraft:stone",
+});
+```
 
 ---
 
@@ -123,9 +158,49 @@ interface _BaseConfig<ROLES, VARIABLES> {
   // Optional: World spawn point for the challenge
   // Can be explicit coordinates or an entity selector (e.g., from Actions.getLocation)
   spawnPoint?: { x: number; y: number; z: number } | SelectorClass;
+
+  // Optional: Per-rule overrides for the implicit setup the SDK applies
+  // inside start_challenge / init_participants. See "Implicit setup" below.
+  defaults?: {
+    time?: "day" | "noon" | "night" | "midnight" | false;  // default: "day"
+    daylightCycle?: boolean;                                // default: false
+    mobSpawning?: boolean;                                  // default: false
+    naturalRegeneration?: boolean;                          // default: true
+    clearInventory?: boolean;                               // default: true
+    maxHealth?: number | false;                             // default: 20
+  } | false;
 }
 ```
 
+### Implicit setup (`defaults`)
+
+`createChallenge` applies a small, predictable setup at the top of `start_challenge` and `init_participants` so user code doesn't have to:
+
+- **`start_challenge`** — `time set day`, `gamerule doDaylightCycle false`, `gamerule doMobSpawning false`, `gamerule naturalRegeneration true`.
+- **`init_participants`** — `clear @a[participant]`, `attribute generic.max_health base set 20`.
+
+Override per-rule when needed:
+
+```typescript
+// Wave-defense: keep mob spawns on
+createChallenge({ defaults: { mobSpawning: true }, ... })
+
+// PvP arena that pre-stocks inventory in start_challenge: keep what was given
+createChallenge({ defaults: { clearInventory: false }, ... })
+
+// Boss fight: 30 HP per agent
+createChallenge({ defaults: { maxHealth: 30 }, ... })
+
+// Tight combat tuning: no idle healing
+createChallenge({ defaults: { naturalRegeneration: false }, ... })
+```
+
+Set `defaults: false` to disable implicit setup entirely (you're then responsible for time, gamerules, and per-player init):
+
+```typescript
+createChallenge({ defaults: false, ... })
+```
+
 **Role Validation:** When building a challenge via `kradle challenge build`, the roles in `createChallenge()` are validated against the roles defined in `config.ts`. If a role in `challenge.ts` doesn't match a role in `config.ts`, the build will fail with an error.
 
 **Spawn Point:** The `spawnPoint` option sets the world spawn point and teleports new players to it. It accepts either:
@@ -160,12 +235,14 @@ The builder uses a fluent API. Methods must be called in order:
 
 ```typescript
 createChallenge(config)
-  .events(eventCallback)           // Define lifecycle events
-  .custom_events(customEventCallback)  // Define triggered events
-  .end_condition(endConditionCallback) // Define game end condition
-  .win_conditions(winConditionsCallback) // Define win conditions (triggers build)
+  .events(eventCallback)               // Lifecycle events; call Actions.setEndStates from on_tick
+  .custom_events(customEventCallback)  // OPTIONAL — score-threshold side effects (announce, sound, etc.)
+  .end_condition(endConditionCallback) // OPTIONAL — when the game should end (auto-includes GAME_DURATION timer)
+  .win_conditions(winConditionsCallback) // Per-role win conditions (triggers build)
 ```
 
+**Use `Actions.setEndStates({ ... })` from `events.on_tick` for the standard "win condition X / loss Y / timeout Z" pattern.** It collapses what would otherwise be three `custom_events` entries with manual `Actions.setEndState` calls. Hand its return value (the OR of all conditions) to `.end_condition()` if you want the game to end as soon as any branch fires.
+
 #### `.events(callback)`
 
 ```typescript
@@ -179,7 +256,29 @@ createChallenge(config)
 })
 ```
 
-#### `.custom_events(callback)`
+**Worked example — solo speedrun "break the gold block":**
+
+```typescript
+let endReached: ConditionType | undefined;
+challenge
+  .events(({ goal_broken, alive_players, game_timer }) => ({
+    on_tick: () => {
+      endReached = Actions.setEndStates({
+        goal_reached: goal_broken.equalTo(1),
+        time_up:      _.or(alive_players.equalTo(0), game_timer.greaterOrEqualThan(GAME_DURATION)),
+      });
+    },
+  }))
+  .end_condition(() => endReached!);
+```
+
+End-state names are validated against `config.endStates` at build time (same as direct `Actions.setEndState` calls).
+
+**IMPORTANT — server context:** when called from `events.on_tick`, the conditions passed to `Actions.setEndStates` are evaluated as the server entity (not a participant). Reference **globals only** (e.g. `alive_players`, `game_timer`, your global custom_variables). For "any player has X" semantics, derive a global via a per-player updater first (see `Actions.maxPlayerScore`).
+
+#### `.custom_events(callback)` (optional — for score-threshold side effects)
+
+For triggered side effects keyed off score thresholds — an `announce` when score crosses N, a sound effect, a `repeatable` event. For end-states, prefer `Actions.setEndStates` from `events.on_tick`.
 
 ```typescript
 .custom_events((variables: Variables, roles: Roles) => {
@@ -208,6 +307,8 @@ createChallenge(config)
 
 #### `.end_condition(callback)`
 
+Defines when the game should end. The challenge already auto-ends after `GAME_DURATION` ticks if specified — `.end_condition()` adds an extra termination criterion that's OR'd with the timer. The most common pattern is to capture the return of `Actions.setEndStates(...)` from `on_tick` and feed it back here, so the game ends as soon as any end-state has been applied.
+
 ```typescript
 .end_condition((variables: Variables, roles: Roles) => {
   return Condition;  // Returns a Sandstone condition
@@ -284,6 +385,46 @@ Common objective types:
 
 You can find objectives definition on the [Scoreboard](https://minecraft.fandom.com/wiki/Scoreboard) wiki pagem as well as the [Statistics](https://minecraft.fandom.com/wiki/Statistics) page for more in-depth explanation.
 
+> **⚠️ `minecraft.picked_up` only fires on item-entity pickup, NOT on `Actions.give`.**
+>
+> If you award items via `Actions.give({ item, target, count })` and your `score` uses `objective_type: "minecraft.picked_up:minecraft.<item>"`, the score will stay at `0` because `/give` adds straight to the player's inventory and never spawns the item entity that triggers the statistic.
+>
+> Only one of these patterns will register on `picked_up`:
+> 1. Drop the item with `summon item ... ItemTags ...` so the player walks over it (slow + visible).
+> 2. Track the score yourself in a `dummy` objective and increment it at every payout site.
+>
+> Pattern 2 is almost always what you want for "emeralds awarded so far":
+> ```typescript
+> custom_variables: {
+>   score: {
+>     type: "individual",
+>     objective_type: "dummy",
+>     default: 0,
+>     updater: (value, { main_score }) => main_score.set(value),
+>   },
+>   ticks_in_a: {
+>     type: "individual",
+>     objective_type: "dummy",
+>     default: 0,
+>     // The second argument to `updater` exposes every other custom_variable —
+>     // including `score` — so you can bump it yourself wherever Actions.give fires.
+>     updater: (value, { score }) => {
+>       forEveryPlayer(() => {
+>         _.if(<on_platform>, () => {
+>           value.add(1);
+>           _.if(value.modulo(20).equalTo(0), () => {
+>             Actions.give({ target: "self", item: "minecraft:emerald", count: 1 });
+>             score.add(1);
+>           });
+>         });
+>       });
+>     },
+>   },
+> }
+> ```
+>
+> The same applies to "deduction" via `clear @s emerald N` — `picked_up` does NOT decrement when an item leaves the inventory. If you need a *current-balance* score (e.g. "ended with > 50 emeralds"), pair every `give`/`clear` with explicit `score.add(N)` / `score.remove(N)`.
+
 #### Individual Dummy
 
 Computed per-player values:
@@ -349,6 +490,8 @@ score.lowerThan(number | Score);
 score.lowerOrEqualThan(number | Score);
 ```
 
+A `Score` is itself a Condition that compiles to `unless score @s OBJ matches 0` — i.e. **truthy = non-zero**. So for 0/1 latches, `_.if(flag, ...)` is the short form of `_.if(flag.equalTo(1), ...)`. **But not** for counters that can hit ≥2 — `_.if(alive_players)` matches "≥1 alive", `_.if(alive_players.equalTo(1))` matches "exactly one alive" (the last-player-standing semantic). Use the truthy form only when you're sure the score is bounded to 0/1.
+
 ---
 
 ## Events
@@ -581,6 +724,15 @@ Actions.tellraw({
   target: "self",
   message: { text: "Critical hit!", color: "red", bold: true }
 });
+
+// Score values embed directly into the message — Sandstone serializes them
+// as `{ score: { name, objective } }` and Minecraft renders each recipient's
+// own value. So a single tellraw to "all" shows each player THEIR number,
+// no `forEveryPlayer` + `_.if(player_number.equalTo(N))` branching needed:
+Actions.tellraw({
+  target: "all",
+  message: [{ text: "Your player number is ", color: "yellow" }, player_number],
+});
 ```
 
 ### Items & Inventory
@@ -824,6 +976,110 @@ createChallenge({
 
 **Important:** When building via `kradle challenge build`, locations are validated against the `locations` defined in `config.ts`. If a location name doesn't exist in the config, the build will fail with an error listing valid locations.
 
+#### `Actions.box(params)`
+
+Build a box (4 walls + optional floor/roof) in a single call. Replaces the typical 5+ `Actions.fill` calls per arena.
+
+```typescript
+Actions.box({
+  block: BLOCKS;          // Wall block
+  from: { x, y, z };      // First corner (inclusive)
+  to: { x, y, z };        // Opposite corner (inclusive)
+  absolute: boolean;
+  hollow?: boolean;       // Default true: only walls placed
+  floor?: BLOCKS;         // Optional override block for floor
+  roof?: BLOCKS;          // Optional roof
+  clearInside?: BLOCKS | boolean; // true = air; supply a BLOCKS to fill interior
+});
+
+// Example - 13×13×5 stone arena with 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,
+});
+```
+
+#### `Actions.countBlocksInRegion(params)`
+
+Count instances of a block within an axis-aligned region. Returns a `Score`. Useful for detecting agent-built structures without pinning detection to a single coordinate (which breaks the moment the agent moves before building).
+
+```typescript
+Actions.countBlocksInRegion({
+  block: BLOCKS;        // Block ID to count (e.g. "minecraft:cobblestone")
+  from: { x, y, z };    // First corner (inclusive)
+  to: { x, y, z };      // Opposite corner (inclusive)
+  absolute: boolean;
+}): Score;
+
+// 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!" }));
+```
+
+The region is hard-capped at 4096 cells (~64×8×8) — emits one `execute if block` check per cell at codegen time, so larger regions would bloat the generated datapack. If you need to scan a bigger area, do it in slices.
+
+#### `Actions.countBlocksRelativeTo(params)`
+
+Same as `countBlocksInRegion`, but the bounds are *relative to a target's current position*. Finds structures the agent built nearby regardless of where they wandered after spawning. Returns a `Score`.
+
+```typescript
+Actions.countBlocksRelativeTo({
+  target: TargetNames;          // "self", "all", or any selector
+  block: BLOCKS;
+  dxRange: [number, number];    // x offsets relative to target (e.g. [-8, 8])
+  dyRange: [number, number];    // y offsets (e.g. [0, 5] for "this block + 5 above")
+  dzRange: [number, number];
+}): Score;
+
+// Detect a 5-tall pillar within 8 blocks of the agent (in either direction):
+pillar_built: {
+  type: "individual",
+  default: 0,
+  updater: (value) => {
+    value.set(0);
+    const count = Actions.countBlocksRelativeTo({
+      target: "self",
+      block: "minecraft:cobblestone",
+      dxRange: [-8, 8],
+      dyRange: [0, 5],
+      dzRange: [-8, 8],
+    });
+    _.if(count.greaterOrEqualThan(5), () => value.set(1));
+  },
+}
+```
+
+Use this instead of `countBlocksInRegion` when the build site moves with the agent. Same 4096-cell cap.
+
+#### `Actions.knockbackWithLevitation(params)`
+
+Apply a non-lethal knockback / displacement via Minecraft's `effect` command. Default is a brief levitation (lifts straight up without dealing damage). Pass `mode: "slowfall"` to combine with slow-falling for a soft landing.
+
+```typescript
+Actions.knockbackWithLevitation({
+  target: TargetNames;
+  durationSeconds?: number;  // Default 1
+  amplifier?: number;        // Default 5
+  mode?: "levitation" | "slowfall";
+});
+
+// Periodic knockback in a King-of-the-Hill challenge:
+Actions.knockbackWithLevitation({ target: "all", durationSeconds: 2, amplifier: 6 });
+
+// Knock + slow-fall for safe landing:
+Actions.knockbackWithLevitation({ target: "self", mode: "slowfall", durationSeconds: 3 });
+```
+
 ### World
 
 #### `Actions.setBlock(params)`
@@ -958,6 +1214,127 @@ Actions.decrement({
 Actions.decrement({ variable: variables.counter });
 ```
 
+#### `Actions.standingOnBlock(params)` → `Selector`
+
+Returns a Sandstone selector that matches `@s` ONLY when standing on the block at `(x, y, z)`. Use this anywhere you need a "is the player on this pad / tile / pressure plate?" check — the bare `Selector("@s", { x, y, z })` 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 `dx: 0, dy: 1, dz: 0` so the selector matches the 1×1×2 column above the floor block.
+
+```typescript
+Actions.standingOnBlock({
+  x: number;        // X of the floor block
+  y: number;        // Y of the floor block (player's feet are at y+1)
+  z: number;        // Z of the floor block
+  role?: string;    // Optional role tag the player must also have
+});
+```
+
+```typescript
+// 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); },
+        );
+      });
+    });
+  },
+},
+```
+
+### Voting
+
+Challenges can offer named votes, declared in `config.ts` as `challengeConfig.votingOptions` (e.g. `{ selectroom: ["red", "green", "blue"] }`). Agents cast a vote with `skills.voteForOption(voteId, option)`; the arena validates it (rejecting unknown options and second votes) and records the choice as the player tags `kradle.voteOptions.<voteId>` (voted-at-all) and `kradle.voteOptions.<voteId>.<option>` (the choice). The actions below read and drive those tags, so you can build a full "discuss → vote → act on the result" phase (see Pattern 13). Vote ids and options must be tag-safe and dot-free (`[A-Za-z0-9_-]`). Like `getLocation`, the vote actions validate at build time against the declared `votingOptions`: an undeclared vote id (or an option not in that vote) fails `kradle challenge build`, catching typos early.
+
+#### `Actions.votedFor(voteId, option?)` → `Selector`
+
+Per-player condition matching `@s` when the player has voted in `voteId` (any option), or — when `option` is given — only when they voted for that specific option. Use it in `_.if` (inside `forEveryPlayer`), `setEndStates`, or win conditions. It matches `@s`, so **do not** pass it to `execute.as(...)` from a tick/load context — `@s` resolves to no one there and the command runs for nobody (the build's context-safety check flags this).
+
+```typescript
+Actions.votedFor("selectroom");          // voted in selectroom at all
+Actions.votedFor("selectroom", "red");   // voted specifically for red
+```
+
+```typescript
+// Move everyone who picked the red room — votedFor is a per-player condition,
+// so check it inside forEveryPlayer (which makes @s each participant).
+forEveryPlayer(() => {
+  _.if(Actions.votedFor("selectroom", "red"), () => {
+    Actions.teleport({ target: "self", x: 10, y: -60, z: 10, absolute: true });
+  });
+});
+```
+
+#### `Actions.promptVote(params)`
+
+Announce a vote to all participants over the `***KRADLE***` channel agents read, naming the vote and its options.
+
+```typescript
+Actions.promptVote({
+  voteId: string;     // matches a key in config votingOptions
+  prompt: string;     // human-readable instruction
+  options: string[];  // the valid options to surface
+});
+
+// Example:
+Actions.promptVote({ voteId: "selectroom", prompt: "Pick a room!", options: ["red", "green", "blue"] });
+```
+
+#### `Actions.allVotesIn(voteId)` → `ConditionType`
+
+True once every participant has voted in `voteId` (no participant is still missing the `kradle.voteOptions.<voteId>` tag). Combine with a timer to end a vote phase as soon as everyone is in.
+
+```typescript
+_.if(_.or(Actions.allVotesIn("selectroom"), game_timer.greaterOrEqualThan(600)), () => {
+  // resolve the vote (600 ticks = 30s)
+});
+```
+
+#### `Actions.assignDefaultVotes(params)`
+
+Record `default` for every participant who has not voted in `voteId` yet — call it on timeout so non-voters are still moved by `votedFor`. Writes the same tags the arena would.
+
+```typescript
+Actions.assignDefaultVotes({
+  voteId: string;   // the vote
+  default: string;  // option assigned to non-voters
+});
+
+// Example:
+Actions.assignDefaultVotes({ voteId: "selectroom", default: "red" });
+```
+
+**Full vote phase** — prompt once, resolve when all are in or 30s elapse, default non-voters, then move each player by their choice. Gate the resolve block behind a global `resolved` flag so it fires once:
+
+```typescript
+// config.ts: challengeConfig.votingOptions = { selectroom: ["red", "green", "blue"] }
+const ROOMS = { red: { x: 10, y: -60, z: 10 }, green: { x: 20, y: -60, z: 10 }, blue: { x: 30, y: -60, z: 10 } };
+
+challenge.events(({ game_timer, resolved }) => ({
+  start_challenge: () => {
+    Actions.promptVote({ voteId: "selectroom", prompt: "Pick a room!", options: Object.keys(ROOMS) });
+  },
+  on_tick: () => {
+    _.if(resolved.equalTo(0), () => {
+      _.if(_.or(Actions.allVotesIn("selectroom"), game_timer.greaterOrEqualThan(600)), () => {
+        resolved.set(1);
+        Actions.assignDefaultVotes({ voteId: "selectroom", default: "red" });
+        forEveryPlayer(() => {
+          for (const [option, pos] of Object.entries(ROOMS)) {
+            _.if(Actions.votedFor("selectroom", option), () => {
+              Actions.teleport({ target: "self", x: pos.x, y: pos.y, z: pos.z, absolute: true });
+            });
+          }
+        });
+      });
+    });
+  },
+}));
+```
+
 ### Player Attributes
 
 #### `Actions.setAttribute(params)`
@@ -1041,6 +1418,36 @@ Actions.setEndState({ endState: "defeat" });
 Actions.setEndState({ endState: "unknown" }); // Error: Invalid end state "unknown"
 ```
 
+#### `Actions.setEndStates(map): ConditionType`
+
+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's 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).
+
+```typescript
+Actions.setEndStates({
+  [endStateName: string]: ConditionType,
+}): ConditionType;
+```
+
+```typescript
+let endReached: ConditionType | undefined;
+challenge
+  .events(({ goal_broken, alive_players, game_timer }) => ({
+    on_tick: () => {
+      endReached = Actions.setEndStates({
+        goal_reached: goal_broken.equalTo(1),
+        time_up:      _.or(alive_players.equalTo(0), game_timer.greaterOrEqualThan(GAME_DURATION)),
+      });
+    },
+  }))
+  .end_condition(() => endReached!);
+```
+
+End-state names are validated against `config.endStates` at build time, same as direct `Actions.setEndState` calls.
+
+**Note: server context** — when called from `events.on_tick` (the most common spot), conditions are evaluated as the server entity, where per-player score reads silently fail. Reference globals only; for "any player has X" semantics use `Actions.maxPlayerScore` to materialize a global first.
+
 ---
 
 ## Utilities
@@ -1059,6 +1466,24 @@ forEveryPlayer(() => {
 });
 ```
 
+### `forEachOtherPlayer(callback)`
+
+Inside a `forEveryPlayer` (or any "@s is an outer participant") context, run `callback` for every OTHER participant. Inside the callback `@s` is the inner participant; the outer participant is no longer `@s` but is tagged `kradle_pair_self` for the duration of the inner loop so you can refer to them.
+
+Visits ordered pairs (each unordered pair appears twice, once with each direction). For each-pair-once semantics, gate the callback on `other.player_number > self.player_number`.
+
+```typescript
+import { forEveryPlayer, forEachOtherPlayer } from "@kradle/challenges-sdk";
+
+forEveryPlayer(() => {
+  forEachOtherPlayer(() => {
+    // @s = the inner player; @a[tag=kradle_pair_self] = the outer player.
+    // Useful for matchup-style logic: prisoner's dilemma payoffs, alliance
+    // detection, "did I bump into another player" events, etc.
+  });
+});
+```
+
 **Important Notes:**
 - Individual variables automatically reference the current player (`@s`) within the loop
 - Global variables remain global and are the same across all iterations
@@ -1259,12 +1684,8 @@ createChallenge({
     max_height_global: {
       type: "global",
       updater: (value, { max_height }) => {
-        value.set(0);
-        forEveryPlayer(() => {
-          _.if(max_height.greaterThan(value), () => {
-            value.set(max_height);
-          });
-        });
+        // Pass `min: -1000` because climber Y can go below 0 (lava drops, void).
+        value.set(Actions.maxPlayerScore({ score: max_height, min: -1000 }));
       },
     },
     is_winner: {
@@ -1384,12 +1805,7 @@ createChallenge({
     pig_killed_max: {
       type: "global",
       updater: (value, { pigs_killed }) => {
-        value.set(0);
-        forEveryPlayer(() => {
-          _.if(pigs_killed.greaterThan(value), () => {
-            value.set(pigs_killed);
-          });
-        });
+        value.set(Actions.maxPlayerScore({ score: pigs_killed }));
       },
     },
   },
@@ -1489,6 +1905,22 @@ createChallenge({
 
 ## Common Patterns
 
+| # | Pattern | Use when | Canonical challenge |
+|---|---------|----------|---------------------|
+| 1 | Sync variable to main_score | Score should display on the watcher leaderboard | sprint, patience |
+| 2 | Find global maximum | "Highest score wins" comparisons | crafters-race, splat-rush |
+| 3 | Winner detection (has max + alive) | Latched is_winner that requires surviving | prisoners-dilemma, king-of-the-hill |
+| 4 | Track player position | Per-player coordinate snapshot for distance/region checks | sprint, lighthouse |
+| 5 | Check inventory for item | "Has the agent crafted X yet?" | crafters-race, biome-bazaar |
+| 6 | Check block below player | "Is the agent on a specific tile?" — use `Actions.standingOnBlock` | sacrifice, reputation |
+| 7 | Count entities | Wave / mob accounting | wave-survivor, zombie-survival |
+| 8 | Simple end condition | Single-condition timer or score gate | sprint |
+| 9 | Multi-condition end | OR of timer / score / event gates | crafters-race |
+| 10 | Opposing-team win conditions | Capture-the-flag style 0/1 flag state | castle-ctf, capture-the-flag |
+| 11 | Per-participant win attribution inside a single role | Same role, but only some win (saboteur vs miners) | saboteur |
+| 12 | Sequential turn-taking | "One player acts at a time" — current_voter gate | cascade, adaptive |
+| 13 | Two-phase game (sequential broadcast → simultaneous decision) | Vote after public discussion | common-knowledge |
+
 ### Pattern 1: Sync Variable to Main Score
 
 ```typescript
@@ -1507,16 +1939,13 @@ my_variable: {
 max_global: {
   type: "global",
   updater: (value, { individual_score }) => {
-    value.set(0);
-    forEveryPlayer(() => {
-      _.if(individual_score.greaterThan(value), () => {
-        value.set(individual_score);
-      });
-    });
+    value.set(Actions.maxPlayerScore({ score: individual_score }));
   },
 }
 ```
 
+Pass `min: -1000` (or any sufficiently-negative bound) when the per-player score can go below 0 — the default `min: 0` would otherwise mask negative actual maxes.
+
 ### Pattern 3: Winner Detection (Has Max Score + Alive)
 
 ```typescript
@@ -1587,14 +2016,13 @@ on_gold_block: {
 zombie_count: {
   type: "global",
   updater: (value) => {
-    value.set(0);
-    execute.as(Selector("@e", { type: "zombie" })).run(() => {
-      value.add(1);
-    });
+    value.set(Actions.countEntities({ entity: "minecraft:zombie" }));
   },
 }
 ```
 
+Combine filters with `tag` and/or `volume` for "zombies in the arena" or "tagged hunt targets only". At least one filter must be provided (counting "every entity in the world" throws at build time).
+
 ### Pattern 8: Simple End Condition
 
 ```typescript
@@ -1621,13 +2049,228 @@ zombie_count: {
 }))
 ```
 
+### Pattern 11: Per-participant Win Attribution Inside a Single Role
+
+For asymmetric games where one role hides another (e.g. social deduction: 1 secret saboteur + 3 miners share the same `player` role), `.win_conditions` is keyed by role but its body runs `as @a[tag=<role>]` — so `@s` is each participant. Filter further inside the condition with `Selector("@s", { tag })`:
+
+```typescript
+.win_conditions(({ saboteur_alive, diamonds_mined }, { player }) => ({
+  [player]: _.or(
+    _.and(
+      Selector("@s", { tag: "saboteur" } as any),
+      saboteur_alive.equalTo(1),
+      diamonds_mined.lowerThan(4),
+    ),
+    _.and(
+      Selector("@s", { tag: "!saboteur" } as any),
+      _.or(diamonds_mined.greaterOrEqualThan(4), saboteur_alive.equalTo(0)),
+    ),
+  ),
+}))
+```
+
+This is how saboteur ends up correctly attributing the win to the saboteur participant when miners run out of time, and to all miners when they catch the impostor — without needing a separate `saboteur` role. The `as any` cast on the negated tag is a Sandstone selector-typing limitation; `tag: "!saboteur"` is a valid Minecraft selector token but the type narrowing doesn't model it.
+
+### Pattern 12: Sequential turn-taking (one player acts at a time)
+
+For games where only one participant should act per tick — like cascade's information-cascade voting where each voter must wait their turn — gate the action updater on `player_number == current_voter`. The SDK's built-in `player_number` is per-player (1, 2, 3, … assigned in init_participants); maintain a global `current_voter` that you bump when a player completes their turn:
+
+```typescript
+custom_variables: {
+  // ... your other variables ...
+  current_voter: { type: "global", default: 1 },
+  has_voted: { type: "individual", objective_type: "dummy", default: 0 },
+  vote: {
+    type: "individual",
+    objective_type: "dummy",
+    default: -1,
+    updater: (value, { current_voter, has_voted, player_number }) => {
+      forEveryPlayer(() => {
+        _.if(
+          _.and(has_voted.equalTo(0), player_number.equalTo(current_voter)),
+          () => {
+            _.if(Actions.standingOnBlock(RED_PAD), () => {
+              value.set(0);
+              has_voted.set(1);
+              current_voter.add(1);
+            });
+            _.if(Actions.standingOnBlock(BLUE_PAD), () => {
+              value.set(1);
+              has_voted.set(1);
+              current_voter.add(1);
+            });
+          },
+        );
+      });
+    },
+  },
+},
+// Announce each turn boundary via custom_events keyed on current_voter:
+.custom_events(({ current_voter }) => [
+  { score: current_voter, target: 2, mode: "fire_once",
+    actions: () => Actions.announce({ message: [{ text: "Voter 2's turn.", color: "yellow" }] }) },
+  { score: current_voter, target: 3, mode: "fire_once",
+    actions: () => Actions.announce({ message: [{ text: "Voter 3's turn.", color: "yellow" }] }) },
+  // ... one per voter beyond the first ...
+])
+```
+
+The compiled mcfunction reads `execute if score @s has_voted matches 0 if score @s player_number = current_voter kradle.board run …` — the player_number-vs-current_voter equality is what enforces serialization. Used by cascade and adaptive.
+
+### Pattern 13: Two-phase game (sequential broadcast, then simultaneous decision)
+
+Common-knowledge formation games and similar designs need a sequential phase 1 (one act per turn) followed by a simultaneous phase 2 (all act independently in private). Phase 1 reuses Pattern 12; phase 2 gates on a global "phase 1 complete" condition AND uses **per-player rooms** so each player's decision stays private:
+
+```typescript
+custom_variables: {
+  // ... phase 1: same as Pattern 12 ...
+  broadcasts_done: {
+    type: "global",
+    default: 0,
+    updater: (value, { has_broadcast }) => {
+      value.set(0);
+      forEveryPlayer(() => { value.add(has_broadcast); });
+    },
+  },
+  has_voted_final: { type: "individual", objective_type: "dummy", default: 0 },
+  final_vote: {
+    type: "individual",
+    objective_type: "dummy",
+    default: -1,
+    updater: (value, { broadcasts_done, has_voted_final, player_number }) => {
+      // Per-player room layout — keeps each player's vote private until all cast.
+      const FINAL_PADS = [
+        { red: FINAL_RED_P1, blue: FINAL_BLUE_P1 },
+        { red: FINAL_RED_P2, blue: FINAL_BLUE_P2 },
+        { red: FINAL_RED_P3, blue: FINAL_BLUE_P3 },
+      ];
+      forEveryPlayer(() => {
+        _.if(
+          _.and(broadcasts_done.equalTo(3), has_voted_final.equalTo(0)),
+          () => {
+            FINAL_PADS.forEach((pads, idx) => {
+              _.if(player_number.equalTo(idx + 1), () => {
+                _.if(Actions.standingOnBlock(pads.red), () => {
+                  value.set(0);
+                  has_voted_final.set(1);
+                });
+                _.if(Actions.standingOnBlock(pads.blue), () => {
+                  value.set(1);
+                  has_voted_final.set(1);
+                });
+              });
+            });
+          },
+        );
+      });
+    },
+  },
+},
+// In init_participants, tell each player their player_number — without it, agents can't tell
+// which "Voter 2's turn" announcement is theirs and can't navigate to the right phase-2 room.
+// One tellraw to "all" with player_number embedded does it (each recipient sees their own value):
+//   Actions.tellraw({ target: "all", message: ["Your player number is ", player_number] });
+```
+
+**Collective-win tip:** for "all-or-nothing" reward (everyone wins iff every vote is correct AND unanimous), add a global `correct_votes` updater that sums `(has_voted_final == 1 AND final_vote == truth)` per player; then `.win_conditions` can gate `[role]: correct_votes.equalTo(N)`. Used by common-knowledge.
+
+**Skill-based voting (alternative to pads):** when the decision is a choice among named options rather than a physical location, skip the per-player rooms entirely. Declare `votingOptions` in `config.ts`, have agents call `skills.voteForOption(voteId, option)` (votes are private — each agent whispers the watcher), and read the result with `Actions.votedFor(voteId, option?)`. Use `Actions.promptVote` to announce the vote, `Actions.allVotesIn(voteId)` (paired with a `game_timer` deadline) to detect when everyone's cast, and `Actions.assignDefaultVotes` to default non-voters on timeout — see the **Voting** section under Actions. The pad-based approach above is still the right choice when the vote *is* a spatial commitment (which room you walk into) or you want votes visible via player position.
+
+---
+
+## Common Gotchas
+
+These are real bugs that bit AI authors building the existing challenge corpus. Read before authoring; reach for the SDK helper called out where one exists.
+
+### Relative coords in global custom_variable updaters resolve at world origin (0, 0, 0)
+
+`_.block(rel(...))` and any sandstone command using `rel(...)` inside a **global** variable updater evaluates relative to the server entity at `(0, 0, 0)`, not at any player position. A "is the player standing on the trigger pad" check that uses `rel(0, -1, 0)` will silently always look at one block below world origin.
+
+**Fix:** wrap the updater body in `forEveryPlayer(() => { ... })` so the relative coords resolve at `@s` (each player's position):
+
+```ts
+trigger_pressed: {
+  type: "global",
+  default: 0,
+  updater: (value) => {
+    forEveryPlayer(() => {
+      _.if(_.block(rel(0, -1, 0), "minecraft:gold_block"), () => {
+        value.set(1);
+      });
+    });
+  },
+}
+```
+
+This bit sequence-pad's wool-pad detection when the updater ran at world origin instead of per-player.
+
+### Sandstone NBT serialization: `true` → `{}`, `false` → `0b`
+
+Both are invalid NBT tokens. Any time you'd reach for sandstone's typed `summon(entity, abs(...), { CustomNameVisible: true, … })`, the resulting datapack command will be malformed and the summon will fail silently in-game.
+
+**Fix:** use **`Actions.summonEntityWithStats`** for boss-style configured mobs (HP / attack damage / movement speed / tags). It builds the NBT command string directly via sandstone's `raw()` and dodges the gotcha. For un-configured spawns, plain `Actions.summonMultiple` works fine.
+
+### `Actions.tagEntity?.(...)` / `Actions.tagPlayer` don't exist
+
+These look plausible but aren't on the Actions object. Optional-chaining (`Actions.tagEntity?.(...)`) silently no-ops, which means your "mark hunt targets" call does nothing and your tagged-entity selectors find zero matches.
+
+**Fix:** import `tag` from sandstone directly: `tag("@e[type=chicken,distance=..1]").add("hunt_target")`. Or design around tags entirely — chicken-chase ended up counting all chickens since flat-world has no naturally-spawned ones to confuse the count.
+
+### `score.lessThan` doesn't exist; use `lowerThan`
+
+Sandstone's `Score` API uses `lowerThan` and `greaterThan`. `lessThan` and `moreThan` look like reasonable guesses but TypeScript won't catch them at build time without `tsc --noEmit` (the kradle CLI build doesn't run strict tsc).
+
+### `scheduled_events` / `setInterval`-style helpers don't exist
+
+For "spawn a wave every N seconds", use `.custom_events` with one `fire_once` score event per wave keyed off `game_timer` at the right tick value. wave-survival uses 3 explicit entries; golem-ally maps an array of `WAVE_TICKS` to `custom_events` entries with `.map(...)`.
+
+### `gamerule "pvp"` is not a real gamerule in 1.20.4
+
+PvP is on by default in flat-world. Spyglass validation rejects this rule. Just don't set it.
+
+### End-state names are validated at build time against `config.ts → endStates`
+
+`Actions.setEndState({ endState: "x" })` and `Actions.setEndStates({ x: ... })` both check each name against the `endStates` map declared in your `config.ts`. A typo throws at build time, not at runtime — useful to lean on, but means you must keep `config.ts` in sync when adding/renaming an end state.
+
+### `events.on_tick` and `.custom_events` run as the server entity, not as participants
+
+Same context issue as the global-updater gotcha above. End-state conditions that reference a per-player score directly will silently fail (server has no entry on a per-player objective; `if score @s X matches Y` short-circuits the whole compound). For "any player has X" semantics in the conditions you pass to `Actions.setEndStates` from `on_tick`, derive a global via a per-player updater first (e.g. `Actions.maxPlayerScore({ score })`), then reference that global in the condition.
+
+### `Selector("@s", { x, y, z })` does NOT constrain position
+
+This is the trap that bit `sacrifice` — the alice/bob "stepped on the pad" check fired the moment the player existed because the selector didn't actually require position. In Minecraft selectors, `x/y/z` without `dx/dy/dz` defines the *origin* used for distance/volume math, not a position filter. Without a volume the entity check passes for everyone.
+
+**Fix:** use `Actions.standingOnBlock({ x, y, z, role? })` (recommended) — it bakes in the right `dx: 0, dy: 1, dz: 0` so the selector matches a 1×1×2 column above the floor block. If you must hand-roll the selector, include `dx`/`dy`/`dz` explicitly:
+
+```typescript
+// ❌ Silently passes for every entity:
+Selector("@s", { tag: "alice", x: PAD.x, y: PAD.y + 1, z: PAD.z })
+
+// ✅ Matches only when feet are at (PAD.x, PAD.y+1, PAD.z):
+Selector("@s", { tag: "alice", x: PAD.x, y: PAD.y + 1, z: PAD.z, dx: 0, dy: 1, dz: 0 })
+// or — preferred:
+Actions.standingOnBlock({ x: PAD.x, y: PAD.y, z: PAD.z, role: "alice" })
+```
+
+### `minecraft.picked_up:<item>` does NOT fire on `Actions.give` (also: does NOT decrement on `clear`)
+
+Already covered in the "Common objective types" section earlier — short version: `objective_type: "minecraft.picked_up:..."` only counts ITEM-ENTITY pickups. `/give` writes straight to inventory and bypasses the statistic. Same for `clear` — the counter doesn't go down. Use `objective_type: "dummy"` and bump the score yourself next to every `Actions.give` / `clear` call (the `updater` second arg exposes other custom_variables, so you can grab `{ score }` and call `score.add(N)` / `score.remove(N)` inline).
+
+### Don't reach for `raw("scoreboard players add ...")`
+
+Sandstone exports `scoreboard`, `give`, `clear`, `execute`, `Selector`, `_.if` etc. as typed builders — use them. The `raw()` string skips type-checking, hard-codes objective names so a `score` rename silently breaks the command, and is harder to spot in code review. For per-target score updates from a global context, use `execute.as(Selector("@a", { tag: alice })).run(() => score.add(10))` — `@s` resolves correctly inside the `run` body.
+
+### Roles get tagged with the bare role name, not `kradle_<role>`
+
+If your challenge has `roles: ["alice", "bob"] as const`, the kradle runtime adds `kradle_participant` plus the bare role name (`alice`, `bob`) as tags. Selectors filtering by `tag: "kradle_alice"` match nobody. Use `tag: "alice"`.
+
 ---
 
 ## Tips for LLMs
 
 1. **Always use `as const`** for roles array to get proper type inference
 2. **Updaters should be idempotent** - they run every tick
-3. **Use `forEveryPlayer` for global aggregations** (max, count, any/all checks)
+3. **Reach for the helper before hand-rolling an aggregation** — `Actions.maxPlayerScore` for cross-player max, `Actions.countEntities` for entity counts. Drop to `forEveryPlayer` only when no helper covers the shape.
 4. **Import `_` from sandstone** for conditions (`_.if`, `_.and`, `_.or`)
 5. **Variables are Scores** - use `.set()`, `.add()`, comparison methods
 6. **Main score is displayed** - sync your primary metric to `main_score`