@kradle/challenges-sdk 0.5.3 → 0.6.1

package/README.md

@@ -13,6 +13,8 @@ If you still want to perform a manual installation, you also need to install the
 npm install @kradle/challenges-sdk sandstone@0.14.0-alpha.13
 ```
 
+Add `"type": "module"` to your project's `package.json`. Challenge files use ES module syntax (`import …`) and Node otherwise reparses them as ES modules at every CI run with a `MODULE_TYPELESS_PACKAGE_JSON` warning + per-file overhead.
+
 ## Quick Start
 
 Like for installation, we strongly recommend using Kradle's CLI to bootstrap a challenge:
@@ -22,6 +24,31 @@ Like for installation, we strongly recommend using Kradle's CLI to bootstrap a c
 kradle challenge create my-challenge
 ```
 
+## Local Development
+
+Working on the SDK locally and want to test against a real challenge project (e.g. `team-kradle-challenges`)?
+
+**Use `npm pack` + tarball install — not `npm link`.**
+
+```bash
+# 1. In the SDK repo
+npm run build
+npm pack    # produces kradle-challenges-sdk-<version>.tgz
+
+# 2. In the consumer project
+npm install /absolute/path/to/kradle-challenges-sdk-<version>.tgz
+```
+
+After every SDK change, repeat both steps (a one-line script is fine).
+
+### Why not `npm link`?
+
+`sandstone` is a peer dependency. `npm link` keeps the SDK's own `node_modules` in play, so the SDK ends up resolving `sandstone` from one location while the consumer resolves it from another. You end up with **two `sandstone` instances loaded in the same process**, which produces some confusing failure modes:
+
+- `instanceof SelectorClass` returns `false` for selectors created by the consumer (they're instances of the *other* `SelectorClass`).
+- The runtime `Flow` registry gets split, so `_.if(...)` calls inside `forEveryPlayer` throw `Entering child function without registering a root function`.
+
+`npm pack` + install gives the consumer a single flat `sandstone` install, which is what production users get. No duplication, no `instanceof` surprises, no flow-registry split.
 
 ## API Overview
 
@@ -46,12 +73,14 @@ The challenge builder uses a fluent API:
 
 ```typescript
 createChallenge(config)
-  .events(callback)           // Define lifecycle event handlers
-  .custom_events(callback)    // Define score/advancement-triggered events
-  .end_condition(callback)    // Define when the game ends
-  .win_conditions(callback)   // Define win conditions per role
+  .events(callback)               // Lifecycle events; call Actions.setEndStates from on_tick
+  .custom_events(callback)        // OPTIONAL — score-threshold side effects (announce, sound, etc.)
+  .end_condition(callback)        // OPTIONAL — when the game should end (auto-includes GAME_DURATION timer)
+  .win_conditions(callback)       // Per-role win conditions
 ```
 
+> For the standard "win / loss / timeout" pattern, call `Actions.setEndStates({ ... })` from inside `events.on_tick` and feed its return value into `.end_condition()` so the game ends as soon as any end-state fires. See the API reference for the full signature.
+
 ## Variables
 
 Variables are the core mechanism for tracking game state. All variables are automatically updated each tick.
@@ -291,6 +320,7 @@ Actions.giveLoot({
     { name: "minecraft:iron_ingot", count: 10, weight: 3 }
   ]
 });
+
 Actions.clear({ target: "self" });
 
 // Count items - returns a Score variable
@@ -314,6 +344,34 @@ const spawn = Actions.getLocation({ name: "spawn" });
 Actions.teleport({ target: "all", toEntity: spawn });
 ```
 
+### Selectors
+```typescript
+// "Is @s standing on the block at (x, y, z)?" — returns a Selector usable
+// inside _.if(...). Use this instead of Selector("@s", { x, y, z }) which
+// silently passes for everyone (Minecraft selector x/y/z without dx/dy/dz
+// is the origin for distance math, not a position constraint).
+_.if(Actions.standingOnBlock({ x: PAD.x, y: PAD.y, z: PAD.z, role: "alice" }), () => {
+  // Alice is on the pad above (PAD.x, PAD.y, PAD.z). Run trigger logic here.
+});
+```
+
+### Cross-player score aggregation
+```typescript
+// Compute the maximum across all players' per-player scores. Returns an
+// anonymous Score the caller can write into a global custom_variable.
+// Lets `Actions.setEndStates` / `.end_condition` reference "any player has X"
+// semantics correctly (those checks run as the server entity, so per-player
+// scores read 0 there).
+max_score: {
+  type: "global",
+  default: 0,
+  updater: (value, { score }) => {
+    value.set(Actions.maxPlayerScore({ score }));
+    // Pass `min: -1000` if your per-player score can go below 0.
+  },
+}
+```
+
 ### Locations
 ```typescript
 // Get a location marker by name (must be defined in config.ts locations)
@@ -348,6 +406,30 @@ Actions.increment({ variable: variables.counter });
 Actions.decrement({ variable: variables.counter });
 ```
 
+### Voting
+
+Declare votes in `config.ts` (`challengeConfig.votingOptions`, e.g. `{ selectroom: ["red", "green", "blue"] }`). Agents cast a vote with `skills.voteForOption(voteId, option)`; the arena records it as player tags the actions below read. See LLM_README.md → "Voting" for the full flow.
+
+```typescript
+// Announce the vote to all agents.
+Actions.promptVote({ voteId: "selectroom", prompt: "Pick a room!", options: ["red", "green", "blue"] });
+
+// Condition: did this player vote (for a specific option)?
+Actions.votedFor("selectroom");          // voted at all
+Actions.votedFor("selectroom", "red");   // voted red
+
+// Resolve when everyone's in (or a 30s timer fires), defaulting non-voters, then move by choice.
+// votedFor is a per-player condition, so check it inside forEveryPlayer (makes @s each participant):
+_.if(_.or(Actions.allVotesIn("selectroom"), game_timer.greaterOrEqualThan(600)), () => {
+  Actions.assignDefaultVotes({ voteId: "selectroom", default: "red" });
+  forEveryPlayer(() => {
+    _.if(Actions.votedFor("selectroom", "red"), () => {
+      Actions.teleport({ target: "self", x: 10, y: -60, z: 10, absolute: true });
+    });
+  });
+});
+```
+
 ### Player Attributes
 ```typescript
 Actions.setAttribute({ target: "self", attribute_: "generic.max_health", value: 40 });