@kradle/challenges-sdk 0.3.0

package/README.md

@@ -0,0 +1,489 @@
+<!-- This file is for human consumption. If you are an LLM or any AI Agent, make sure to read LLM_README.md for an exhaustive explanation of this package. -->
+
+# @kradle/challenges-sdk
+
+A TypeScript framework for creating Minecraft datapack-based challenges with event-driven game logic, score tracking, and player role management. Built on top of [Sandstone](https://sandstone.dev/).
+
+## Getting started
+
+We strongly recommend using [Kradle's CLI](https://github.com/kradle-ai/cli) to create challenges with the CLI. Make sure to read the CLI's README
+
+If you still want to perform a manual installation, you also need to install the Sandstone peer-dependency:
+```bash
+npm install @kradle/challenges-sdk sandstone@0.14.0-alpha.13
+```
+
+## Quick Start
+
+Like for installation, we strongly recommend using Kradle's CLI to bootstrap a challenge:
+
+```bash
+# Will create a challenge in challenges/my-challenge/
+kradle challenge create my-challenge
+```
+
+
+## API Overview
+
+### `createChallenge(config)`
+
+Creates a new challenge with the specified configuration.
+
+```typescript
+createChallenge({
+  name: string;                    // Challenge name (used for datapack)
+  kradle_challenge_path: string;   // Output directory for generated datapack
+  roles: readonly string[];        // Player roles (e.g., ["attacker", "defender"])
+  GAME_DURATION?: number;          // Duration in ticks (default: 6000 = 5 minutes)
+  custom_variables: Record<string, VariableDefinition>;
+})
+```
+
+### Fluent Builder Methods
+
+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
+```
+
+## Variables
+
+Variables are the core mechanism for tracking game state. All variables are automatically updated each tick.
+
+### Built-in Variables
+
+These variables are always available:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `death_count` | individual | Number of times the player has died |
+| `has_never_died` | individual | 1 if player hasn't died, 0 otherwise |
+| `alive_players` | global | Count of living participants |
+| `main_score` | individual | Primary score displayed on sidebar |
+| `game_timer` | global | Ticks elapsed since game start |
+| `game_state` | global | Current state (0=CREATED, 1=OFF, 2=ON) |
+| `player_count` | global | Total number of participants |
+| `player_number` | individual | Unique player ID (1 to N) |
+
+### Custom Variable Types
+
+#### Individual Variables (per-player)
+
+Track values for each player separately.
+
+**Objective-based** (uses Minecraft statistics):
+```typescript
+pigs_killed: {
+  type: "individual",
+  objective_type: "minecraft.killed:minecraft.pig",
+  default: 0,
+}
+```
+
+**Dummy** (computed values):
+```typescript
+current_height: {
+  type: "individual",
+  objective_type: "dummy",
+  updater: (value) => {
+    value.set(Actions.getPlayerPosition().y)
+  },
+}
+```
+
+#### Global Variables (shared)
+
+Track values across all players.
+
+```typescript
+max_score: {
+  type: "global",
+  hidden: false,  // optional: hide from scoreboard
+  default: 0,
+  updater: (value, { main_score }) => {
+    value.set(0);
+    forEveryPlayer(() => {
+      _.if(main_score.greaterThan(value), () => {
+        value.set(main_score);
+      });
+    });
+  },
+}
+```
+
+### Updater Functions
+
+Updaters run every tick and receive `(currentValue, allVariables)`:
+
+```typescript
+updater: (value, { main_score, death_count, game_timer }) => {
+  // Set value based on other variables
+  value.set(0);
+  _.if(main_score.greaterThan(10), () => {
+    value.set(1);
+  });
+}
+```
+
+If you track a Minecraft objective, you do not need an updater!
+
+## Events
+
+### Lifecycle Events
+
+Lifecycle events are triggered once on specific occasions.
+
+```typescript
+.events((variables, roles) => ({
+  start_challenge: () => {
+    // Runs once when the challenge starts
+    Actions.setTime({ time: "day" });
+    Actions.announce({ message: "Game starting!" });
+  },
+
+  init_participants: () => {
+    // Runs 1s after the challenge starts
+    Actions.give({ target: "all", item: "minecraft:diamond_sword", count: 1 });
+    Actions.setAttribute({ target: "all", attribute_: "generic.max_health", value: 40 });
+  },
+
+  on_tick: () => {
+    // Runs once every tick
+  },
+
+  end_challenge: () => {
+    // Runs when the challenge ends
+    Actions.announce({ message: "Game over!" });
+  },
+}))
+```
+
+### Custom Events
+
+Custom events trigger actions based on score thresholds or Minecraft advancements.
+
+#### Score-based events
+
+Score events watch a variable and trigger when it reaches a target value. 
+
+- **`score`**: The variable to watch.
+- **`target`** (optional): The target value. If omitted, triggers on any score change
+- **`mode`**:
+  - `"fire_once"`: Triggers once when the score reaches the target (per player for individual variables)
+  - `"repeatable"`: Triggers every tick while the score is at target
+
+For individual variables, events fire per-player; for global variables, events fire globally.
+
+```typescript
+.custom_events((variables, roles) => [
+  {
+    score: variables.diamonds,
+    target: 5,
+    mode: "fire_once",
+    actions: () => {
+      Actions.announce({ message: "Someone collected 5 diamonds!" });
+    },
+  },
+])
+```
+
+If `target` is omitted, the event triggers whenever the score changes (useful for reacting to any increment).
+
+#### Advancement-based events
+
+Advancement events trigger when a Minecraft advancement criterion is met (e.g., player attacks, item picked up). The criteria follow the [Minecraft Advancement JSON format](https://minecraft.fandom.com/wiki/Advancement/JSON_format).
+
+Advancement-based events always fire per-player.
+
+- **`criteria`**: Array of advancement triggers with optional conditions
+- **`mode`**:
+  - `"fire_once"`: Triggers once per player when the advancement is granted
+  - `"repeatable"`: Triggers every time the advancement criterion is met (advancement is auto-revoked to allow re-triggering)
+
+```typescript
+.custom_events((variables, roles) => [
+  {
+    criteria: [
+      {
+        trigger: "minecraft:player_hurt_entity",
+        conditions: {
+          entity: { type: "minecraft:player" }  // Only PvP hits
+        }
+      }
+    ],
+    mode: "repeatable",
+    actions: () => {
+      Actions.increment({ variable: variables.pvp_hits });
+    },
+  },
+])
+```
+
+## End Conditions
+
+Define when the game ends:
+
+```typescript
+.end_condition(({ objective_complete }) => objective_complete.equalTo(1))
+```
+
+Multiple conditions can be combined:
+```typescript
+.end_condition(({ alive_players, objective_complete }) =>
+  _.or(
+    alive_players.equalTo(1),
+    objective_complete.equalTo(1)
+  )
+)
+```
+
+Ending conditions are evaluated once per tick, at the global level (not individually). It means you should not check for individual variables here - instead, you should aggregate these individual variables into a global custom variable, that you then check in the ending condition.
+
+## Win Conditions
+
+Define how winners are determined per role:
+
+```typescript
+.win_conditions((variables, { attacker, defender }) => ({
+  [attacker]: variables.kills.greaterOrEqualThan(5),
+  [defender]: variables.survived.equalTo(1),
+}))
+```
+
+## Actions
+
+Actions are higher-level functions that wrap common Minecraft operations, designed to work seamlessly with Kradle's challenge system. They handle target mapping, formatting, and integration with Kradle's interface automatically.
+
+For more advanced use cases, you can always fall back to Sandstone's lower-level functions directly (e.g., `give`, `tellraw`, `effect`, `kill`, `execute`). See the [Sandstone Integration](#sandstone-integration) section below.
+
+### Communication
+```typescript
+// Simple string message
+Actions.announce({ message: "Hello everyone!" });
+
+// Formatted JSONTextComponent message
+Actions.announce({
+  message: [
+    { text: "Player ", color: "white" },
+    { selector: "@s", color: "gold", bold: true },
+    { text: " scored!", color: "green" }
+  ]
+});
+
+// Send to specific target (only visible in-game, not in Kradle's interface)
+Actions.tellraw({ target: "all", message: ["Hello ", { text: "world", color: "gold" }] });
+Actions.tellraw({ target: "self", message: { text: "You win!", color: "green", bold: true } });
+```
+
+### Items & Inventory
+```typescript
+Actions.give({ target: "self", item: "minecraft:diamond_sword", count: 1 });
+Actions.giveLoot({
+  target: "self",
+  items: [
+    { name: "minecraft:diamond", count: 5, weight: 1 },
+    { name: "minecraft:iron_ingot", count: 10, weight: 3 }
+  ]
+});
+Actions.clear({ target: "self" });
+
+// Count items - returns a Score variable
+const count = Actions.countItems({ target: "self", item: "minecraft:diamond" });
+// Use in conditions or set to custom variables
+_.if(count.greaterThan(5), () => { /* ... */ });
+
+// Get player position - returns { x, y, z } Score variables
+const pos = Actions.getCurrentPlayerPosition();
+_.if(pos.y.greaterThan(100), () => { /* player is high up */ });
+```
+
+### Entities
+```typescript
+Actions.summonMultiple({ entity: "minecraft:zombie", count: 5, x: 0, y: 64, z: 0, absolute: true });
+Actions.kill({ selector: Selector("@e", { type: "minecraft:zombie" }) });
+Actions.teleport({ target: "self", x: 0, y: 100, z: 0, absolute: true });
+```
+
+### World
+```typescript
+Actions.setBlock({ block: "minecraft:diamond_block", x: 0, y: 64, z: 0, absolute: true });
+Actions.fill({
+  block: "minecraft:stone",
+  x1: 0, y1: 64, z1: 0,
+  x2: 10, y2: 64, z2: 10,
+  absolute: true,
+  mode: "fill"  // "fill", "line", or "pyramid"
+});
+Actions.setTime({ time: "day" });  // or "night" or specific tick value
+Actions.gamerule({ rule: "doDaylightCycle", value: false });
+```
+
+### Scores
+```typescript
+Actions.set({ variable: variables.main_score, value: 10 });
+Actions.set({ variable: variables.main_score, value: variables.diamonds });
+Actions.increment({ variable: variables.counter });
+Actions.decrement({ variable: variables.counter });
+```
+
+### Player Attributes
+```typescript
+Actions.setAttribute({ target: "self", attribute_: "generic.max_health", value: 40 });
+Actions.setAttribute({ target: "self", attribute_: "generic.movement_speed", value: 0.2 });
+```
+
+### Custom Commands
+```typescript
+Actions.custom(() => {
+  // Any Sandstone code here
+  execute.as("@a").run.effect.give("@s", "speed", 10, 1);
+});
+```
+
+## Utilities
+
+### `forEveryPlayer(callback)`
+
+Execute code for each participant at their location:
+
+```typescript
+import { forEveryPlayer } from "@kradle/challenges-sdk";
+
+forEveryPlayer(() => {
+  // Runs as each player, at their position
+  execute.run.particle("minecraft:flame", rel(0, 1, 0));
+});
+```
+
+## Example: Battle Royale
+
+```typescript
+import { createChallenge, Actions, forEveryPlayer } from "@kradle/challenges-sdk";
+import { _, Selector } 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,
+    },
+    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.announce({ message: "Last player standing wins!" });
+    },
+    init_participants: () => {
+      Actions.give({ target: "all", item: "minecraft:stone_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:leather_chestplate", count: 1 });
+    },
+  }))
+  .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: Capture the Flag
+
+```typescript
+import { createChallenge, Actions } from "@kradle/challenges-sdk";
+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_enemy_flag: {
+      type: "individual",
+      updater: (value: Score) => {
+        value.set(0);
+        // Check if player holds the enemy team's banner
+        _.if(Selector("@s", {
+          nbt: { Inventory: [{ id: "minecraft:red_banner" }] }
+        }), () => {
+          value.set(1);
+        });
+      },
+    },
+    at_home_base: {
+      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_enemy_flag, at_home_base }) => {
+        value.set(0);
+        _.if(_.and(
+          holds_enemy_flag.equalTo(1),
+          at_home_base.equalTo(1)
+        ), () => {
+          value.set(1);
+        });
+      },
+    },
+  },
+})
+  .events(() => ({
+    start_challenge: () => {
+      Actions.announce({ message: "Capture the enemy flag!" });
+    },
+  }))
+  .custom_events(({ captured_flag }) => [
+    {
+      score: captured_flag,
+      target: 1,
+      mode: "fire_once",
+      actions: () => {
+        Actions.announce({ message: "Flag captured!" });
+      },
+    },
+  ])
+  .end_condition(({ captured_flag }) => captured_flag.equalTo(1))
+  .win_conditions(({ captured_flag }, { red_team, blue_team }) => ({
+    [red_team]: captured_flag.equalTo(1),
+    [blue_team]: captured_flag.equalTo(0),
+  }));
+```
+

package/dist/actions.d.ts

@@ -0,0 +1,230 @@
+import { type GAMERULES, type JSONTextComponent, type Score, SelectorClass } from "sandstone";
+import type { ATTRIBUTES, BLOCKS, ENTITY_TYPES, ITEMS } from "sandstone/arguments/generated";
+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;
+export declare const Actions: {
+    /**
+     * Send a chat message to everyone.
+     * @param {JSONTextComponent} message - The message to send.
+     */
+    announce: ({ message }: {
+        message: JSONTextComponent;
+    }) => void;
+    /**
+     * Clear the inventory of a target.
+     * @param {TargetNames} target - The target to clear the inventory of.
+     */
+    clear: ({ target }: {
+        target: TargetNames;
+    }) => void;
+    /**
+     * Custom action allowing to run any Sandstone command.
+     *
+     * @param {() => void} callback - The function to execute.
+     */
+    custom: (callback: () => void) => void;
+    /**
+     * Fill a region with a block.
+     * @param {BLOCKS} block - The block to fill the region with.
+     * @param {number} x1 - The x coordinate of the region.
+     * @param {number} y1 - The y coordinate of the region.
+     * @param {number} z1 - The z coordinate of the region.
+     * @param {number} x2 - The x coordinate of the region.
+     * @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.
+     */
+    fill: ({ block, x1, y1, z1, x2, y2, z2, absolute, mode, }: {
+        block: BLOCKS;
+        x1: number;
+        y1: number;
+        z1: number;
+        x2: number;
+        y2: number;
+        z2: number;
+        absolute: boolean;
+        mode: "fill" | "line" | "pyramid";
+    }) => void;
+    /**
+     * Give an item to a target.
+     * @param {ITEMS} item - The item to give.
+     * @param {TargetNames} target - The target to give the item to.
+     * @param {number} count - The number of items to give.
+     */
+    give: ({ item, target, count }: {
+        item: ITEMS;
+        target: TargetNames;
+        count?: number;
+    }) => void;
+    /**
+     * Give loot to a target with a weighted chance for selecting one of the items.
+     * @param {{ name: ITEMS, count: number, weight: number }[]} items - The items to give.
+     * @param {TargetNames} target - The target to give the item to.
+     */
+    giveLoot: ({ items, target }: {
+        items: [{
+            name: ITEMS;
+            count: number;
+            weight: number;
+        }];
+        target: TargetNames;
+    }) => void;
+    /**
+     * Set a gamerule.
+     * @param {GAMERULES} rule - The name of the gamerule.
+     * @param {boolean | number} value - The value to set the gamerule to.
+     */
+    gamerule: ({ rule, value }: {
+        rule: GAMERULES;
+        value: boolean | number;
+    }) => void;
+    /**
+     * Kill entities matching a selector.
+     * @param {SelectorArgument} selector - The entities to kill.
+     */
+    kill: ({ selector }: {
+        selector: TargetNames;
+    }) => void;
+    /**
+     * Set an attribute for a target.
+     * @param {ATTRIBUTES} attribute_ - The attribute to set.
+     * @param {number} value - The value to set the attribute to.
+     * @param {TargetNames} target - The target to set the attribute for.
+     */
+    setAttribute: ({ attribute_, value, target }: {
+        attribute_: ATTRIBUTES;
+        value: number;
+        target: TargetNames;
+    }) => void;
+    /**
+     * Set the time of day.
+     * @param {'day' | 'night'} time_ - The time to set.
+     */
+    setTime: ({ time }: {
+        time: "day" | "night";
+    }) => void;
+    /**
+     * Summon multiple entities at a specific location.
+     */
+    summonMultiple: (params: {
+        entity: ENTITY_TYPES;
+        count: number;
+        x: number;
+        y: number;
+        z: number;
+        absolute: boolean;
+    }) => void;
+    /**
+     * Set the end state of the challenge.
+     * @param {string} end_state - The end state to set.
+     */
+    setEndState: ({ endState }: {
+        endState: string;
+    }) => void;
+    /**
+     * Set a block at a specific location.
+     */
+    setBlock: (params: {
+        block: BLOCKS;
+        x: number;
+        y: number;
+        z: number;
+        absolute: boolean;
+    }) => void;
+    /**
+     * Teleport entities to a specific location.
+     * @param {TargetNames} target - The entities to teleport.
+     * @param {number} x - The x coordinate of the destination.
+     * @param {number} y - The y coordinate of the destination.
+     * @param {number} z - The z coordinate of the destination.
+     * @param {boolean} absolute - Whether the coordinates are absolute or relative.
+     */
+    teleport: ({ target, x, y, z, absolute, }: {
+        target: TargetNames;
+        x: number;
+        y: number;
+        z: number;
+        absolute: boolean;
+    }) => void;
+    /**
+     * Send a chat message to a target.
+     * @param {JSONTextComponent} message - The message to send.
+     * @param {TargetNames} target - The target to send the message to.
+     */
+    tellraw: ({ message, target }: {
+        message: JSONTextComponent;
+        target: TargetNames;
+    }) => void;
+    /**
+     * Increment a score variable by 1.
+     * @param variable - The score variable to increment.
+     */
+    increment: ({ variable }: {
+        variable: Score;
+    }) => void;
+    /**
+     * Decrement a score variable by 1.
+     * @param variable - The score variable to decrement.
+     */
+    decrement: ({ variable }: {
+        variable: Score;
+    }) => void;
+    /**
+     * Set a score variable to a specific value.
+     * @param variable - The score variable to set.
+     * @param value - The value to set the score variable to, which can be a number or another score variable.
+     */
+    set: ({ variable, value }: {
+        variable: Score;
+        value: number | Score;
+    }) => void;
+    /**
+     * log a message with the watcher
+     * @param {string} message - The message to send.
+     * @param {Score} variable - The variable to log.
+     * @param {boolean} store - Whether to store the variable in the backend.
+     */
+    log_variable: ({ message, variable, store }: {
+        message: string;
+        variable: Score;
+        store: boolean;
+    }) => void;
+    /**
+     * Summon an item at a specific location.
+     * @param {ITEMS} item - The item to summon.
+     * @param {number} x - The x coordinate of the location.
+     * @param {number} y - The y coordinate of the location.
+     * @param {number} z - The z coordinate of the location.
+     * @param {boolean} absolute - Whether the coordinates are absolute or relative.
+     */
+    summonItem: ({ item, x, y, z, absolute }: {
+        item: ITEMS;
+        x: number;
+        y: number;
+        z: number;
+        absolute: boolean;
+    }) => void;
+    /**
+     * Count the number of a specific item in a target's inventory.
+     * @param params - The parameters object.
+     * @param params.target - The target to count items for.
+     * @param params.item - The item to count.
+     * @returns The variable containing the item count.
+     */
+    countItems: ({ target, item }: {
+        target: TargetNames;
+        item: ITEMS;
+    }) => Score<string | undefined>;
+    /**
+     * 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).
+     * @returns An object with x, y, z Score variables containing the player's coordinates.
+     */
+    getCurrentPlayerPosition: () => {
+        x: Score<string | undefined>;
+        y: Score<string | undefined>;
+        z: Score<string | undefined>;
+    };
+};
+//# sourceMappingURL=actions.d.ts.map