@kradle/challenges 0.1.0 → 0.2.0

package/LLM_README.md

@@ -0,0 +1,1380 @@
+# LLM_README.md - @kradle/challenges API Reference
+
+This document provides exhaustive API documentation for AI agents using the `@kradle/challenges` package. This is the complete reference for creating Minecraft datapack-based challenges.
+
+## Table of Contents
+
+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)
+
+---
+
+## Overview
+
+`@kradle/challenges` is a TypeScript framework for creating Minecraft challenges that compile to datapacks. It provides:
+
+- **Variable System**: Track per-player and global game state with automatic tick updates
+- **Event System**: Lifecycle hooks and custom event triggers based on scores/advancements
+- **Actions Library**: Pre-built game operations (give items, teleport, announce, etc.)
+- **Role Management**: Assign players to teams with role-specific win conditions
+- **Sandstone Integration**: Full access to Sandstone's Minecraft command generation
+
+**Key Principle**: Challenges are defined declaratively. You specify variables, events, and conditions - the framework generates the datapack.
+
+---
+
+## Installation
+
+```bash
+npm install @kradle/challenges sandstone@0.14.0-alpha.13
+```
+
+**Requirements:**
+- Node.js >= 22.18.0
+- Sandstone 0.14.0-alpha.13 (peer dependency)
+
+---
+
+## Core Concepts
+
+### Ticks
+
+Minecraft runs at 20 ticks per second. Time values in this API are in ticks:
+- 1 second = 20 ticks
+- 1 minute = 1200 ticks (60 * 20)
+- 5 minutes = 6000 ticks
+
+### Namespace
+
+Items and entities are namespaced with `minecraft:` - for example, you should use `minecraft:diamond` instead of `diamond`. Same for entities.
+
+### Scores
+
+All variables are backed by Minecraft scoreboards. The `Score` type from Sandstone represents a scoreboard value. Scores support comparison methods:
+- `score.equalTo(value)` / `score.equalTo(otherScore)`
+- `score.greaterThan(value)`
+- `score.greaterOrEqualThan(value)`
+- `score.lowerThan(value)`
+- `score.lowerOrEqualThan(value)`
+
+### Roles
+
+Roles define player groups (e.g., teams). Each role can have different win conditions. All players assigned to a role share that role's win condition.
+
+---
+
+## createChallenge API
+
+### Signature
+
+```typescript
+function createChallenge<
+  ROLES extends readonly string[],
+  VARIABLES extends Record<string, _InputVariableType>
+>(config: _BaseConfig<ROLES, VARIABLES>): ChallengeBuilder
+```
+
+### Configuration Object
+
+```typescript
+interface _BaseConfig<ROLES, VARIABLES> {
+  // Required: Challenge name (used for datapack namespace)
+  name: string;
+
+  // Required: Output path for generated datapack
+  kradle_challenge_path: string;
+
+  // Required: Player roles as readonly tuple
+  // Example: ["attacker", "defender"] as const
+  roles: ROLES;
+
+  // Required: Custom variable definitions
+  custom_variables: VARIABLES;
+
+  // Optional: Game duration in ticks (default: 6000 = 5 minutes)
+  GAME_DURATION?: number;
+}
+```
+
+### Builder Methods
+
+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(callback)`
+
+```typescript
+.events((variables: Variables, roles: Roles) => {
+  return {
+    start_challenge?: () => void;    // Runs once when game starts
+    init_participants?: () => void;  // Runs once per player after start
+    on_tick?: () => void;            // Runs every tick for each player
+    end_challenge?: () => void;      // Runs once when game ends
+  };
+})
+```
+
+#### `.custom_events(callback)`
+
+```typescript
+.custom_events((variables: Variables, roles: Roles) => {
+  return Array<ScoreEvent | AdvancementEvent>;
+})
+```
+
+**Score Event:**
+```typescript
+{
+  score: Score;           // Variable to watch
+  target: number;         // Threshold value
+  mode: "fire_once" | "repeatable";
+  actions: () => void;    // Actions to execute
+}
+```
+
+**Advancement Event:**
+```typescript
+{
+  criteria: Array<{ trigger: string; conditions?: object }>;
+  mode: "fire_once" | "repeatable";
+  actions: () => void;
+}
+```
+
+#### `.end_condition(callback)`
+
+```typescript
+.end_condition((variables: Variables, roles: Roles) => {
+  return Condition;  // Returns a Sandstone condition
+})
+```
+
+#### `.win_conditions(callback)`
+
+```typescript
+.win_conditions((variables: Variables, roles: Roles) => {
+  return {
+    [roleName: string]: Condition;  // One condition per role
+  };
+})
+```
+
+---
+
+## Variables
+
+### Built-in Variables
+
+These are always available in every challenge:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `death_count` | individual | Player's death count (Minecraft `deathCount` objective) |
+| `has_never_died` | individual | 1 if player has never died, 0 otherwise |
+| `alive_players` | global | Count of living participants |
+| `main_score` | individual | Primary score shown on sidebar |
+| `game_timer` | global | Ticks since game start (increments each tick) |
+| `game_state` | global | 0=CREATED, 1=OFF, 2=ON |
+| `player_count` | global | Total participant count |
+| `player_number` | individual | Unique player ID (1 to N) |
+
+### Custom Variable Definition
+
+```typescript
+custom_variables: {
+  variable_name: {
+    type: "individual" | "global";
+    objective_type?: string;  // Minecraft objective criterion
+    hidden?: boolean;         // Hide from scoreboard (global only)
+    default?: number;         // Initial value
+    updater?: UpdaterFunction;
+  }
+}
+```
+
+### Variable Types
+
+#### Individual Objective-Based
+
+Automatically tracks Minecraft statistics:
+
+```typescript
+pigs_killed: {
+  type: "individual",
+  objective_type: "minecraft.killed:minecraft.pig",
+  default: 0,
+}
+```
+
+Common objective types:
+- `"minecraft.killed:minecraft.<entity>"` - Entities killed
+- `"minecraft.killed_by:minecraft.<entity>"` - Killed by entity
+- `"minecraft.picked_up:minecraft.<item>"` - Items picked up
+- `"minecraft.mined:minecraft.<block>"` - Blocks mined
+- `"minecraft.used:minecraft.<item>"` - Items used
+- `"minecraft.crafted:minecraft.<item>"` - Items crafted
+- `"playerKillCount"` - PvP kills
+- `"deathCount"` - Deaths
+- `"dummy"` - Manual/computed value
+
+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.
+
+#### Individual Dummy
+
+Computed per-player values:
+
+```typescript
+current_y_position: {
+  type: "individual",
+  objective_type: "dummy",
+  updater: (value) => {
+    execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
+  },
+}
+```
+
+#### Global Variables
+
+Shared across all players:
+
+```typescript
+max_score_global: {
+  type: "global",
+  hidden: false,
+  default: 0,
+  updater: (value, { main_score }) => {
+    value.set(0);
+    forEveryPlayer(() => {
+      _.if(main_score.greaterThan(value), () => {
+        value.set(main_score);
+      });
+    });
+  },
+}
+```
+
+### Updater Function Signature
+
+```typescript
+type UpdaterFunction = (
+  value: Score,                    // Current variable's score
+  variables: Record<string, Score> // All variables including built-ins
+) => void;
+```
+
+Updaters run every tick. They should be idempotent. They are not necessary if the variable is individual and tracks a Minecraft objective.
+
+### Score Methods
+
+All variables are `Score` objects with these methods:
+
+```typescript
+// Set value
+score.set(number | Score);
+
+// Arithmetic
+score.add(number | Score);
+score.remove(number | Score);
+
+// Comparison (return Condition)
+score.equalTo(number | Score);
+score.greaterThan(number | Score);
+score.greaterOrEqualThan(number | Score);
+score.lowerThan(number | Score);
+score.lowerOrEqualThan(number | Score);
+```
+
+---
+
+## Events
+
+### Lifecycle Events
+
+#### `start_challenge`
+
+Runs once when the challenge starts. Use for global setup.
+
+```typescript
+start_challenge: () => {
+  Actions.setTime({ time: "day" });
+  Actions.gamerule({ rule: "doDaylightCycle", value: false });
+  Actions.announce({ message: "Game starting!" });
+}
+```
+
+#### `init_participants`
+
+Runs once per player after start (delayed 1 second). Use for player setup.
+
+```typescript
+init_participants: () => {
+  Actions.give({ item: "minecraft:diamond_sword", count: 1 });
+  Actions.setAttribute({ attribute: "generic.max_health", value: 40 });
+  Actions.teleport({ target: "@s", pos: [0, 100, 0] });
+}
+```
+
+#### `on_tick`
+
+Runs every tick for each player. Use sparingly for performance.
+
+```typescript
+on_tick: () => {
+  // Check something every tick
+}
+```
+
+#### `end_challenge`
+
+Runs once when the game ends. Use for cleanup and announcements.
+
+```typescript
+end_challenge: () => {
+  Actions.announce({ message: "Game over!" });
+}
+```
+
+### Custom Events
+
+Custom events allow you to trigger actions based on score thresholds or Minecraft advancement criteria.
+
+#### Score-Based Events
+
+Score events watch a variable and trigger when it reaches a specified target value. They are evaluated every tick.
+
+**Parameters:**
+- `score` (required): The `Score` variable to watch
+- `target` (optional): The threshold value. If omitted, triggers on any score change
+- `mode` (required): `"fire_once"` or `"repeatable"`
+- `actions` (required): Function containing actions to execute
+
+**How it works:**
+1. Every tick, the system compares the current score to the target
+2. For `"fire_once"`: triggers once when `score == target` (tracks previous value to detect the 1st time threshold is met)
+3. For `"repeatable"`: triggers every tick while `score == target`
+4. For individual variables, events fire per-player; for global variables, events fire once globally
+
+```typescript
+{
+  score: variables.diamonds,
+  target: 10,
+  mode: "fire_once",
+  actions: () => {
+    Actions.announce({ message: "10 diamonds collected!" });
+  },
+}
+```
+
+**Without target (triggers on any change):**
+```typescript
+{
+  score: variables.death_count,
+  mode: "fire_once",  // Triggers once when death_count changes from 0
+  actions: () => {
+    Actions.announce({ message: "First death!" });
+  },
+}
+```
+
+**Modes:**
+- `"fire_once"`: Triggers once when threshold is reached (per player for individual variables). Uses previous tick comparison to detect when the score crosses the target.
+- `"repeatable"`: Triggers every tick while `score >= target`. Useful for continuous effects.
+
+#### Advancement-Based Events
+
+Advancement events trigger when a Minecraft advancement criterion is met. Internally, an advancement is created that grants when the criterion triggers, which then fires the event. The `criteria` array follows the [Minecraft Advancement JSON format](https://minecraft.fandom.com/wiki/Advancement/JSON_format).
+
+**Parameters:**
+- `criteria` (required): Array of advancement trigger objects with optional conditions
+- `mode` (required): `"fire_once"` or `"repeatable"`
+- `actions` (required): Function containing actions to execute
+
+**How it works:**
+1. An advancement is generated with your specified criteria
+2. When Minecraft grants the advancement (criterion met), the event fires
+3. For `"repeatable"`: the advancement is automatically revoked so it can trigger again
+4. For `"fire_once"`: the advancement stays granted, preventing re-triggering
+
+**Simple example - Track when a player hits another player:**
+```typescript
+{
+  criteria: [
+    {
+      trigger: "minecraft:player_hurt_entity",
+      conditions: {
+        entity: { type: "minecraft:player" }
+      }
+    }
+  ],
+  mode: "repeatable",
+  actions: () => {
+    Actions.increment({ score: variables.pvp_hits });
+    Actions.announce({ message: "PvP hit!" });
+  },
+}
+```
+
+**Multiple triggers example:**
+```typescript
+{
+  criteria: [
+    { trigger: "minecraft:player_hurt_entity" },
+    { trigger: "minecraft:entity_hurt_player" },
+  ],
+  mode: "repeatable",
+  actions: () => {
+    Actions.increment({ score: variables.combat_actions });
+  },
+}
+```
+
+Common triggers:
+- `"minecraft:player_hurt_entity"` - Player attacks entity
+- `"minecraft:entity_hurt_player"` - Entity attacks player
+- `"minecraft:player_killed_entity"` - Player kills entity
+- `"minecraft:consume_item"` - Item consumed
+- `"minecraft:inventory_changed"` - Inventory changes
+- `"minecraft:location"` - Player at location
+- `"minecraft:enter_block"` - Player enters block
+
+See the [Minecraft Wiki](https://minecraft.fandom.com/wiki/Advancement/JSON_format#List_of_triggers) for the full list of triggers and their conditions.
+
+---
+
+## Actions
+
+All actions are called via the `Actions` object:
+
+```typescript
+import { Actions } from "@kradle/challenges";
+```
+
+### Communication
+
+#### `Actions.announce(params)`
+
+Broadcast message to all players with KRADLE tag.
+
+```typescript
+Actions.announce({
+  message: string;  // Message text
+});
+```
+
+#### `Actions.tellraw(params)`
+
+Send formatted message to specific target.
+
+```typescript
+Actions.tellraw({
+  target: string;  // Selector (e.g., "@a", "@s", "@p")
+  message: JSONTextComponent;  // Minecraft JSON text
+});
+
+// Example:
+Actions.tellraw({
+  target: "@a",
+  message: { text: "Hello!", color: "gold", bold: true }
+});
+```
+
+### Items & Inventory
+
+#### `Actions.give(params)`
+
+Give items to current player.
+
+```typescript
+Actions.give({
+  item: string;        // Item ID without "minecraft:" prefix
+  count: number;       // Amount
+  nbt?: NBTObject;     // Optional NBT data
+});
+
+// Examples:
+Actions.give({ item: "minecraft:diamond_sword", count: 1 });
+Actions.give({
+  item: "minecraft:diamond_sword",
+  count: 1,
+  nbt: {
+    Enchantments: [{ id: "minecraft:sharpness", lvl: 5 }]
+  }
+});
+```
+
+#### `Actions.giveLoot(params)`
+
+Give random items from loot table.
+
+```typescript
+Actions.giveLoot({
+  loot_table: string;  // Loot table path
+  count: number;       // Number of rolls
+});
+
+// Example:
+Actions.giveLoot({
+  loot_table: "minecraft:chests/simple_dungeon",
+  count: 3
+});
+```
+
+#### `Actions.clear(params)`
+
+Clear items from player inventory.
+
+```typescript
+Actions.clear({
+  item?: string;  // Item to clear (omit for all items)
+});
+
+// Examples:
+Actions.clear({ item: "diamond" });
+Actions.clear({});  // Clear everything
+```
+
+#### `Actions.countItems(params)`
+
+Count the number of a specific item in a target's inventory. Creates and returns a temporary variable with the count.
+
+```typescript
+Actions.countItems({
+  target: TargetNames;  // The target to count items for
+  item: ITEMS;          // The item to count
+}): Score;              // Returns a new variable containing the count
+
+// Example - Use directly in conditions:
+_.if(Actions.countItems({ target: "self", item: "minecraft:diamond" }).greaterThan(5), () => {
+  Actions.announce({ message: "You have more than 5 diamonds!" });
+});
+
+// Example - Store in a variable for later use:
+const diamondCount = Actions.countItems({ target: "self", item: "minecraft:diamond" });
+_.if(diamondCount.greaterThan(10), () => {
+  Actions.announce({ message: "You have more than 10 diamonds!" });
+});
+
+// Example - Set a custom variable from the count:
+const count = Actions.countItems({ target: "self", item: "minecraft:diamond" });
+variables.my_diamond_count.set(count);
+```
+
+**Note:** This action creates a temporary variable internally using `Variable()` and uses `execute.store.result.score` with `clear` command (count 0) to count items without removing them from the inventory.
+
+### Entities
+
+#### `Actions.summonMultiple(params)`
+
+Summon multiple entities at location.
+
+```typescript
+Actions.summonMultiple({
+  entity: string;       // Entity ID
+  count: number;        // How many
+  pos: [number, number, number];  // Coordinates
+});
+
+// Example:
+Actions.summonMultiple({
+  entity: "zombie",
+  count: 5,
+  pos: [0, 64, 0]
+});
+```
+
+#### `Actions.summonItem(params)`
+
+Summon item entity at location.
+
+```typescript
+Actions.summonItem({
+  item: string;
+  pos: [number, number, number];
+  count?: number;
+  nbt?: NBTObject;
+});
+```
+
+#### `Actions.kill(params)`
+
+Kill entities matching selector.
+
+```typescript
+Actions.kill({
+  target: string;  // Entity selector
+});
+
+// Examples:
+Actions.kill({ target: "@e[type=zombie]" });
+Actions.kill({ target: "@e[type=!player]" });
+```
+
+#### `Actions.teleport(params)`
+
+Teleport entity to location.
+
+```typescript
+Actions.teleport({
+  target: string;  // Entity selector
+  pos: [number, number, number];  // Destination
+});
+
+// Example:
+Actions.teleport({
+  target: "@s",
+  pos: [0, 100, 0]
+});
+```
+
+### World
+
+#### `Actions.setBlock(params)`
+
+Set a single block.
+
+```typescript
+Actions.setBlock({
+  pos: [number, number, number];
+  block: string;  // Block ID
+});
+
+// Example:
+Actions.setBlock({
+  pos: [0, 64, 0],
+  block: "diamond_block"
+});
+```
+
+#### `Actions.fill(params)`
+
+Fill region with blocks.
+
+```typescript
+Actions.fill({
+  start: [number, number, number];
+  end: [number, number, number];
+  block: string;
+  mode: "fill" | "line" | "pyramid";
+});
+
+// Example:
+Actions.fill({
+  start: [0, 64, 0],
+  end: [10, 64, 10],
+  block: "stone",
+  mode: "fill"
+});
+```
+
+#### `Actions.setTime(params)`
+
+Set world time.
+
+```typescript
+Actions.setTime({
+  time: "day" | "night" | number;  // Named or tick value
+});
+
+// Examples:
+Actions.setTime({ time: "day" });
+Actions.setTime({ time: 6000 });  // Noon
+```
+
+#### `Actions.gamerule(params)`
+
+Set a gamerule.
+
+```typescript
+Actions.gamerule({
+  rule: string;
+  value: boolean | number;
+});
+
+// Examples:
+Actions.gamerule({ rule: "doDaylightCycle", value: false });
+Actions.gamerule({ rule: "mobGriefing", value: false });
+Actions.gamerule({ rule: "randomTickSpeed", value: 0 });
+```
+
+### Scores
+
+#### `Actions.set(params)`
+
+Set score to value or copy from another score.
+
+```typescript
+// Set to number
+Actions.set({
+  score: Score;
+  value: number;
+});
+
+// Copy from another score
+Actions.set({
+  score: Score;
+  source: Score;
+});
+
+// Examples:
+Actions.set({ score: variables.main_score, value: 0 });
+Actions.set({ score: variables.main_score, source: variables.diamonds });
+```
+
+#### `Actions.increment(params)`
+
+Add 1 to score.
+
+```typescript
+Actions.increment({
+  score: Score;
+});
+```
+
+#### `Actions.decrement(params)`
+
+Subtract 1 from score.
+
+```typescript
+Actions.decrement({
+  score: Score;
+});
+```
+
+### Player Attributes
+
+#### `Actions.setAttribute(params)`
+
+Set entity attribute.
+
+```typescript
+Actions.setAttribute({
+  attribute: string;  // Attribute name
+  value: number;
+});
+
+// Examples:
+Actions.setAttribute({ attribute: "max_health", value: 40 });
+Actions.setAttribute({ attribute: "movement_speed", value: 0.2 });
+Actions.setAttribute({ attribute: "attack_damage", value: 10 });
+```
+
+Common attributes:
+- `"max_health"` - Maximum HP (default 20)
+- `"movement_speed"` - Walk speed (default 0.1)
+- `"attack_damage"` - Base attack damage
+- `"armor"` - Armor points
+- `"knockback_resistance"` - Knockback resistance (0-1)
+
+
+### Logging
+
+#### `Actions.log_variable(params)`
+
+Log variable to watcher system (debugging).
+
+```typescript
+Actions.log_variable({
+  message: string;
+  variable: Score;
+  store: string;
+});
+```
+
+---
+
+## Utilities
+
+### `forEveryPlayer(callback)`
+
+Execute code for each participant at their location.
+
+```typescript
+import { forEveryPlayer } from "@kradle/challenges";
+
+forEveryPlayer(() => {
+  // Runs as(@s) at(@s) for each participant
+  // @s is the current player
+});
+```
+
+**Example - Find maximum score:**
+```typescript
+max_score: {
+  type: "global",
+  updater: (value, { main_score }) => {
+    value.set(0);
+    forEveryPlayer(() => {
+      _.if(main_score.greaterThan(value), () => {
+        value.set(main_score);
+      });
+    });
+  },
+}
+```
+
+### Constants
+
+```typescript
+import { ALL, KRADLE_PARTICIPANT_TAG, WINNER_TAG } from "@kradle/challenges";
+
+// ALL - Selector for all participants: @a[tag=kradle_participant]
+// KRADLE_PARTICIPANT_TAG - Tag name: "kradle_participant"
+// WINNER_TAG - Tag name: "kradle_winner"
+```
+
+---
+
+## Sandstone Integration
+
+This package is built on Sandstone. You can use Sandstone APIs directly:
+
+```typescript
+import { _, execute, Selector, rel, abs, MCFunction } from "sandstone";
+```
+
+### Conditions with `_`
+
+```typescript
+// Single condition
+_.if(score.greaterThan(10), () => {
+  // actions
+});
+
+// Combined conditions
+_.if(_.and(
+  score1.greaterThan(5),
+  score2.equalTo(1)
+), () => {
+  // actions
+});
+
+_.if(_.or(
+  condition1,
+  condition2
+), () => {
+  // actions
+});
+
+// Block check
+_.if(_.block(rel(0, -1, 0), "minecraft:diamond_block"), () => {
+  // Player standing on diamond block
+});
+```
+
+### Execute Commands
+
+```typescript
+// Store result in score
+execute.as("@s").store.result.score(myScore).run.data.get.entity("@s", "Pos[1]");
+
+// Run at location
+execute.at("@s").run.particle("minecraft:flame", rel(0, 1, 0));
+
+// Conditional execution
+execute.if.score(myScore, ">=", 10).run.say("High score!");
+```
+
+### Selectors
+
+```typescript
+import { Selector } from "sandstone";
+
+// With arguments
+Selector("@a", { tag: "my_tag" });
+Selector("@e", { type: "zombie", limit: 1, sort: "nearest" });
+
+// NBT check
+Selector("@s", {
+  nbt: { Inventory: [{ id: "minecraft:diamond" }] }
+});
+```
+
+### Relative/Absolute Coordinates
+
+```typescript
+import { rel, abs } from "sandstone";
+
+rel(0, 1, 0);   // ~ ~1 ~
+abs(0, 64, 0);  // 0 64 0
+```
+
+---
+
+## Complete Examples
+
+### Example 1: Speed Challenge - First to Kill 2 Pigs
+
+```typescript
+import { createChallenge, Actions, forEveryPlayer } from "@kradle/challenges";
+import { _ } from "sandstone";
+
+createChallenge({
+  name: "pig-farming",
+  kradle_challenge_path: "./output",
+  roles: ["farmer"] as const,
+  GAME_DURATION: 2 * 60 * 20,  // 2 minutes
+  custom_variables: {
+    pigs_farmed: {
+      type: "individual",
+      objective_type: "minecraft.killed:minecraft.pig",
+      default: 0,
+      updater: (value, { main_score }) => {
+        main_score.set(value);
+      },
+    },
+    game_over: {
+      type: "global",
+      updater: (value, { pigs_farmed }) => {
+        value.set(0);
+        forEveryPlayer(() => {
+          _.if(pigs_farmed.greaterOrEqualThan(2), () => {
+            value.set(1);
+          });
+        });
+      },
+    },
+  },
+})
+  .events(() => ({
+    start_challenge: () => {
+      Actions.setTime({ time: "day" });
+      Actions.announce({ message: "First to kill 2 pigs wins!" });
+    },
+    init_participants: () => {
+      Actions.give({ item: "minecraft:iron_sword", count: 1 });
+    },
+  }))
+  .custom_events(({ pigs_farmed }) => [
+    {
+      score: pigs_farmed,
+      target: 1,
+      mode: "fire_once",
+      actions: () => {
+        Actions.announce({ message: "First pig down!" });
+      },
+    },
+  ])
+  .end_condition(({ game_over }) => game_over.equalTo(1))
+  .win_conditions(({ pigs_farmed }, { farmer }) => ({
+    [farmer]: pigs_farmed.greaterOrEqualThan(2),
+  }));
+```
+
+### Example 2: Climb Challenge - Reach Highest Point
+
+```typescript
+import { createChallenge, Actions, forEveryPlayer } from "@kradle/challenges";
+import { _, execute } from "sandstone";
+
+createChallenge({
+  name: "climb",
+  kradle_challenge_path: "./output",
+  roles: ["climber"] as const,
+  GAME_DURATION: 3 * 60 * 20,
+  custom_variables: {
+    current_height: {
+      type: "individual",
+      objective_type: "dummy",
+      updater: (value) => {
+        execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
+      },
+    },
+    max_height: {
+      type: "individual",
+      updater: (value, { current_height, main_score }) => {
+        _.if(current_height.greaterThan(value), () => {
+          value.set(current_height);
+        });
+        main_score.set(value);
+      },
+    },
+    max_height_global: {
+      type: "global",
+      updater: (value, { max_height }) => {
+        value.set(0);
+        forEveryPlayer(() => {
+          _.if(max_height.greaterThan(value), () => {
+            value.set(max_height);
+          });
+        });
+      },
+    },
+    is_winner: {
+      type: "individual",
+      updater: (value, { max_height, max_height_global, has_never_died }) => {
+        value.set(0);
+        _.if(_.and(
+          max_height.equalTo(max_height_global),
+          max_height.greaterThan(0),
+          has_never_died.equalTo(1)
+        ), () => {
+          value.set(1);
+        });
+      },
+    },
+  },
+})
+  .events(() => ({
+    start_challenge: () => {
+      Actions.setTime({ time: "day" });
+      Actions.announce({ message: "Climb as high as you can!" });
+    },
+    init_participants: () => {
+      Actions.give({ item: "minecraft:cobblestone", count: 64 });
+      Actions.give({ item: "minecraft:cobblestone", count: 64 });
+    },
+  }))
+  .custom_events(() => [])
+  .end_condition(({ game_timer }) => game_timer.greaterThan(3 * 60 * 20))
+  .win_conditions(({ is_winner }, { climber }) => ({
+    [climber]: is_winner.equalTo(1),
+  }));
+```
+
+### Example 3: Battle Royale - Last Player Standing
+
+```typescript
+import { createChallenge, Actions } from "@kradle/challenges";
+import { _ } from "sandstone";
+
+createChallenge({
+  name: "battle-royale",
+  kradle_challenge_path: "./output",
+  roles: ["fighter"] as const,
+  GAME_DURATION: 5 * 60 * 20,
+  custom_variables: {
+    kills: {
+      type: "individual",
+      objective_type: "playerKillCount",
+      default: 0,
+      updater: (value, { main_score }) => {
+        main_score.set(value);
+      },
+    },
+    sole_survivor: {
+      type: "individual",
+      updater: (value, { alive_players, has_never_died }) => {
+        value.set(0);
+        _.if(_.and(
+          alive_players.equalTo(1),
+          has_never_died.equalTo(1)
+        ), () => {
+          value.set(1);
+        });
+      },
+    },
+  },
+})
+  .events(() => ({
+    start_challenge: () => {
+      Actions.setTime({ time: "day" });
+      Actions.gamerule({ rule: "naturalRegeneration", value: false });
+      Actions.announce({ message: "Last player standing wins!" });
+    },
+    init_participants: () => {
+      Actions.give({ item: "minecraft:stone_sword", count: 1 });
+      Actions.give({ item: "minecraft:leather_chestplate", count: 1 });
+      Actions.give({ item: "minecraft:cooked_beef", count: 10 });
+    },
+  }))
+  .custom_events(({ kills }) => [
+    {
+      score: kills,
+      target: 1,
+      mode: "fire_once",
+      actions: () => {
+        Actions.announce({ message: "First blood!" });
+      },
+    },
+  ])
+  .end_condition(({ alive_players }) => alive_players.equalTo(1))
+  .win_conditions(({ sole_survivor }, { fighter }) => ({
+    [fighter]: sole_survivor.equalTo(1),
+  }));
+```
+
+### Example 4: Team-Based - Hunters vs Protectors
+
+```typescript
+import { createChallenge, Actions, forEveryPlayer } from "@kradle/challenges";
+import { _ } from "sandstone";
+
+createChallenge({
+  name: "pig-farming-v2",
+  kradle_challenge_path: "./output",
+  roles: ["pighunter", "pigsaver"] as const,
+  GAME_DURATION: 2 * 60 * 20,
+  custom_variables: {
+    pigs_killed: {
+      type: "individual",
+      objective_type: "minecraft.killed:minecraft.pig",
+      default: 0,
+      updater: (value, { main_score }) => {
+        main_score.set(value);
+      },
+    },
+    pig_killed_max: {
+      type: "global",
+      updater: (value, { pigs_killed }) => {
+        value.set(0);
+        forEveryPlayer(() => {
+          _.if(pigs_killed.greaterThan(value), () => {
+            value.set(pigs_killed);
+          });
+        });
+      },
+    },
+  },
+})
+  .events((vars, { pighunter, pigsaver }) => ({
+    start_challenge: () => {
+      Actions.setTime({ time: "day" });
+      Actions.announce({ message: "Hunters: Kill 2 pigs! Protectors: Stop them!" });
+    },
+    init_participants: () => {
+      // Different items based on role would be set via role-specific logic
+      Actions.give({ item: "minecraft:wooden_sword", count: 1 });
+    },
+  }))
+  .custom_events(() => [])
+  .end_condition(({ pig_killed_max }) => pig_killed_max.greaterOrEqualThan(2))
+  .win_conditions(({ pig_killed_max }, { pighunter, pigsaver }) => ({
+    [pighunter]: pig_killed_max.greaterOrEqualThan(2),
+    [pigsaver]: pig_killed_max.lowerThan(2),
+  }));
+```
+
+### Example 5: Capture the Flag
+
+```typescript
+import { createChallenge, Actions } from "@kradle/challenges";
+import { _, Selector, rel } from "sandstone";
+import type { Score } from "sandstone";
+
+createChallenge({
+  name: "capture-the-flag",
+  kradle_challenge_path: "./output",
+  roles: ["red_team", "blue_team"] as const,
+  GAME_DURATION: 5 * 60 * 20,
+  custom_variables: {
+    holds_red_banner: {
+      type: "individual",
+      updater: (value: Score) => {
+        value.set(0);
+        _.if(Selector("@s", {
+          nbt: { Inventory: [{ id: "minecraft:red_banner" }] }
+        }), () => {
+          value.set(1);
+        });
+      },
+    },
+    stands_blue_wool: {
+      type: "individual",
+      updater: (value: Score) => {
+        value.set(0);
+        _.if(_.block(rel(0, -1, 0), "minecraft:blue_wool"), () => {
+          value.set(1);
+        });
+      },
+    },
+    captured_flag: {
+      type: "individual",
+      updater: (value, { holds_red_banner, stands_blue_wool, main_score }) => {
+        value.set(0);
+        _.if(_.and(
+          holds_red_banner.equalTo(1),
+          stands_blue_wool.equalTo(1)
+        ), () => {
+          value.set(1);
+          main_score.set(1);
+        });
+      },
+    },
+  },
+})
+  .events(() => ({
+    start_challenge: () => {
+      Actions.announce({ message: "Capture the enemy flag and return to base!" });
+    },
+    init_participants: () => {
+      Actions.give({ item: "minecraft:iron_sword", count: 1 });
+    },
+  }))
+  .custom_events(({ captured_flag }) => [
+    {
+      score: captured_flag,
+      target: 1,
+      mode: "fire_once",
+      actions: () => {
+        Actions.announce({ message: "Flag captured! Game over!" });
+      },
+    },
+  ])
+  .end_condition(({ captured_flag }) => captured_flag.equalTo(1))
+  .win_conditions(({ captured_flag }, { red_team, blue_team }) => ({
+    [red_team]: captured_flag.equalTo(0),
+    [blue_team]: captured_flag.equalTo(1),
+  }));
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Sync Variable to Main Score
+
+```typescript
+my_variable: {
+  type: "individual",
+  objective_type: "some_criterion",
+  updater: (value, { main_score }) => {
+    main_score.set(value);
+  },
+}
+```
+
+### Pattern 2: Find Global Maximum
+
+```typescript
+max_global: {
+  type: "global",
+  updater: (value, { individual_score }) => {
+    value.set(0);
+    forEveryPlayer(() => {
+      _.if(individual_score.greaterThan(value), () => {
+        value.set(individual_score);
+      });
+    });
+  },
+}
+```
+
+### Pattern 3: Winner Detection (Has Max Score + Alive)
+
+```typescript
+is_winner: {
+  type: "individual",
+  updater: (value, { main_score, max_global, has_never_died }) => {
+    value.set(0);
+    _.if(_.and(
+      main_score.equalTo(max_global),
+      main_score.greaterThan(0),
+      has_never_died.equalTo(1)
+    ), () => {
+      value.set(1);
+    });
+  },
+}
+```
+
+### Pattern 4: Track Player Position
+
+```typescript
+current_y: {
+  type: "individual",
+  objective_type: "dummy",
+  updater: (value) => {
+    execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
+  },
+}
+```
+
+### Pattern 5: Check Inventory for Item
+
+```typescript
+has_diamond: {
+  type: "individual",
+  updater: (value: Score) => {
+    value.set(0);
+    _.if(Selector("@s", {
+      nbt: { Inventory: [{ id: "minecraft:diamond" }] }
+    }), () => {
+      value.set(1);
+    });
+  },
+}
+```
+
+### Pattern 6: Check Block Below Player
+
+```typescript
+on_gold_block: {
+  type: "individual",
+  updater: (value: Score) => {
+    value.set(0);
+    _.if(_.block(rel(0, -1, 0), "minecraft:gold_block"), () => {
+      value.set(1);
+    });
+  },
+}
+```
+
+### Pattern 7: Count Entities
+
+```typescript
+zombie_count: {
+  type: "global",
+  updater: (value) => {
+    value.set(0);
+    execute.as(Selector("@e", { type: "zombie" })).run(() => {
+      value.add(1);
+    });
+  },
+}
+```
+
+### Pattern 8: Simple End Condition
+
+```typescript
+.end_condition(({ objective_complete }) => objective_complete.equalTo(1))
+```
+
+### Pattern 9: Multi-Condition End
+
+```typescript
+.end_condition(({ alive_players, objective_complete }) =>
+  _.or(
+    alive_players.equalTo(1),
+    objective_complete.equalTo(1)
+  )
+)
+```
+
+### Pattern 10: Opposing Team Win Conditions
+
+```typescript
+.win_conditions(({ team_a_score, team_b_score }, { team_a, team_b }) => ({
+  [team_a]: team_a_score.greaterThan(team_b_score),
+  [team_b]: team_b_score.greaterThan(team_a_score),
+}))
+```
+
+---
+
+## 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)
+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`
+7. **Time is in ticks** - multiply seconds by 20
+8. **Win conditions are per-role** - each role needs its own condition
+9. **Custom events fire per-player** for individual variables