@kradle/challenges 0.2.0 → 0.2.1

package/AGENTS.md

@@ -68,10 +68,10 @@ The main engine that:
 - `build()`: Generates all MCFunctions and calls `savePack()`
 
 **Generated MCFunctions:**
-1. `start_challenge` - Initial setup, tags players, sets game state
-2. `init_participants` - Per-player setup (delayed 1 second via schedule)
-3. `on_tick` - Main loop: updates variables, processes events, checks end condition
-4. `end_challenge` - Announces winners, saves game state
+1. `start_challenge` - Initial setup, tags players, sets game state (runs globally)
+2. `init_participants` - Player setup (runs globally, delayed 1 second via schedule)
+3. `on_tick` - Main loop: updates variables, processes events, checks end condition (runs globally every tick)
+4. `end_challenge` - Announces winners, saves game state (runs globally)
 
 #### 2. Actions Library (`actions.ts`)
 
@@ -90,13 +90,21 @@ Pre-built game operations. Each action is a function that generates Sandstone co
 **Implementation Pattern:**
 ```typescript
 export const Actions = {
-  give: (params: { item: string; count: number; nbt?: object }) => {
-    give("@s", `minecraft:${params.item}`, params.count);
+  give: ({ item, target, count = 1 }: { item: ITEMS; target: TargetNames; count?: number }) => {
+    give(mapTarget(target), item, count);
   },
   // ...
 };
 ```
 
+**Target Mapping:**
+The `mapTarget()` function converts `TargetNames` to selectors:
+- `"all"` → `@a[tag=kradle_participant]`
+- `"self"` → `"@s"`
+- `SelectorClass` → passed through
+- `"minecraft:entity_type"` → `@e[type=minecraft:entity_type]`
+- Other strings → `@a[tag=<string>]` (treated as team names)
+
 #### 3. Variable System (`types.ts`, `challenge.ts`)
 
 **Variable Types:**
@@ -118,9 +126,11 @@ export const Actions = {
 **Score Events:**
 - Track previous tick values to detect changes
 - Fire when score reaches target (fire_once) or while condition holds (repeatable)
-- Processed separately for global vs individual variables
+- For individual variables: events fire per-player
+- For global variables: events fire globally
 
 **Advancement Events:**
+- Always fire per-player (advancement triggers are inherently per-player)
 - Converted to score events internally
 - Advancement grants → score increment → event fires
 - Advancement revoked after triggering

package/LLM_README.md

@@ -53,9 +53,18 @@ Minecraft runs at 20 ticks per second. Time values in this API are in ticks:
 - 1 minute = 1200 ticks (60 * 20)
 - 5 minutes = 6000 ticks
 
-### Namespace
+### Namespace & Item IDs
 
-Items and entities are namespaced with `minecraft:` - for example, you should use `minecraft:diamond` instead of `diamond`. Same for entities.
+**IMPORTANT:** Most Actions require the full `minecraft:` prefix for items, blocks, and entities:
+- ✅ Correct: `item: "minecraft:diamond_sword"`
+- ❌ Wrong: `item: "diamond_sword"`
+
+The only exceptions are when the API explicitly accepts an item without the namespace (check each Action's documentation).
+
+**Examples:**
+- Items: `"minecraft:diamond"`, `"minecraft:iron_sword"`, `"minecraft:cooked_beef"`
+- Blocks: `"minecraft:stone"`, `"minecraft:diamond_block"`
+- Entities: `"minecraft:zombie"`, `"minecraft:pig"`, `"minecraft:creeper"`
 
 ### Scores
 
@@ -74,6 +83,14 @@ Roles define player groups (e.g., teams). Each role can have different win condi
 
 ## createChallenge API
 
+### Required Imports
+
+```typescript
+import { createChallenge, Actions, forEveryPlayer } from "@kradle/challenges";
+import { _, execute, Selector, rel, abs } from "sandstone";
+import type { Score } from "sandstone";
+```
+
 ### Signature
 
 ```typescript
@@ -244,7 +261,7 @@ current_y_position: {
   type: "individual",
   objective_type: "dummy",
   updater: (value) => {
-    execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
+    value.set(Actions.getCurrentPlayerPosition().y)
   },
 }
 ```
@@ -306,6 +323,8 @@ score.lowerOrEqualThan(number | Score);
 
 ### Lifecycle Events
 
+All lifecycle events run globally (not per-player).
+
 #### `start_challenge`
 
 Runs once when the challenge starts. Use for global setup.
@@ -320,19 +339,19 @@ start_challenge: () => {
 
 #### `init_participants`
 
-Runs once per player after start (delayed 1 second). Use for player setup.
+Runs 1 second after start_challenge. Use for player setup. It still runs globally.
 
 ```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] });
+  Actions.give({ target: "all", item: "minecraft:diamond_sword", count: 1 });
+  Actions.setAttribute({ target: "all", attribute_: "generic.max_health", value: 40 });
+  Actions.teleport({ target: "all", x: 0, y: 100, z: 0, absolute: true });
 }
 ```
 
 #### `on_tick`
 
-Runs every tick for each player. Use sparingly for performance.
+Runs every tick. Use sparingly for performance.
 
 ```typescript
 on_tick: () => {
@@ -385,7 +404,7 @@ Score events watch a variable and trigger when it reaches a specified target val
 ```typescript
 {
   score: variables.death_count,
-  mode: "fire_once",  // Triggers once when death_count changes from 0
+  mode: "fire_once",  // Triggers once when death_count changes away from initial value
   actions: () => {
     Actions.announce({ message: "First death!" });
   },
@@ -400,6 +419,8 @@ Score events watch a variable and trigger when it reaches a specified target val
 
 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).
 
+Advancement-based events always fire per-player.
+
 **Parameters:**
 - `criteria` (required): Array of advancement trigger objects with optional conditions
 - `mode` (required): `"fire_once"` or `"repeatable"`
@@ -424,7 +445,7 @@ Advancement events trigger when a Minecraft advancement criterion is met. Intern
   ],
   mode: "repeatable",
   actions: () => {
-    Actions.increment({ score: variables.pvp_hits });
+    Actions.increment({ variable: variables.pvp_hits });
     Actions.announce({ message: "PvP hit!" });
   },
 }
@@ -439,7 +460,7 @@ Advancement events trigger when a Minecraft advancement criterion is met. Intern
   ],
   mode: "repeatable",
   actions: () => {
-    Actions.increment({ score: variables.combat_actions });
+    Actions.increment({ variable: variables.combat_actions });
   },
 }
 ```
@@ -459,12 +480,26 @@ See the [Minecraft Wiki](https://minecraft.fandom.com/wiki/Advancement/JSON_form
 
 ## Actions
 
+Actions are higher-level functions that wrap common Minecraft operations. They provide:
+- Automatic target mapping (`"all"`, `"self"`, team names → proper selectors)
+- Integration with Kradle's interface (e.g., `Actions.announce` messages appear in Kradle)
+- Consistent API for common operations
+
+For advanced use cases not covered by Actions, you can fall back to Sandstone's lower-level functions directly (`give`, `tellraw`, `effect`, `kill`, `execute`, etc.). See [Sandstone Integration](#sandstone-integration).
+
 All actions are called via the `Actions` object:
 
 ```typescript
 import { Actions } from "@kradle/challenges";
 ```
 
+### Target Parameter
+
+Many actions accept a `target` parameter of type `TargetNames`, which can be:
+- `"all"` - Targets all participants (maps to `@a[tag=kradle_participant]`)
+- `"self"` - Targets the current player (maps to `@s`)
+- Any `Selector` instance - Custom selector for fine-grained targeting (e.g., `Selector("@a", { team: "red" })`)
+
 ### Communication
 
 #### `Actions.announce(params)`
@@ -473,24 +508,44 @@ Broadcast message to all players with KRADLE tag.
 
 ```typescript
 Actions.announce({
-  message: string;  // Message text
+  message: JSONTextComponent;  // Message (string or formatted object)
+});
+
+// Simple string:
+Actions.announce({ message: "Game starting!" });
+
+// Formatted JSONTextComponent:
+Actions.announce({
+  message: [
+    { text: "Player ", color: "white" },
+    { selector: "@s", color: "gold", bold: true },
+    { text: " won the game!", color: "green" }
+  ]
 });
 ```
 
 #### `Actions.tellraw(params)`
 
-Send formatted message to specific target.
+Send formatted message to specific target. **Note:** These messages are only visible to players in-game and will not appear in Kradle's interface. Use `Actions.announce` for messages that should be visible in Kradle.
 
 ```typescript
 Actions.tellraw({
-  target: string;  // Selector (e.g., "@a", "@s", "@p")
-  message: JSONTextComponent;  // Minecraft JSON text
+  target: TargetNames;       // "all", "self", or any selector
+  message: JSONTextComponent; // Message (string or formatted object)
 });
 
-// Example:
+// Examples:
 Actions.tellraw({
-  target: "@a",
-  message: { text: "Hello!", color: "gold", bold: true }
+  target: "all",
+  message: ["Hello, ", { text: "world!", color: "gold", bold: true }]
+});
+Actions.tellraw({
+  target: "self",
+  message: "You won!"
+});
+Actions.tellraw({
+  target: "self",
+  message: { text: "Critical hit!", color: "red", bold: true }
 });
 ```
 
@@ -498,60 +553,66 @@ Actions.tellraw({
 
 #### `Actions.give(params)`
 
-Give items to current player.
+Give items to a target.
 
 ```typescript
 Actions.give({
-  item: string;        // Item ID without "minecraft:" prefix
-  count: number;       // Amount
-  nbt?: NBTObject;     // Optional NBT data
+  target: TargetNames;  // "all", "self", or any selector
+  item: string;         // Item ID (with "minecraft:" prefix)
+  count?: number;       // Amount (default: 1)
 });
 
 // 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.give({ target: "self", item: "minecraft:diamond_sword", count: 1 });
+Actions.give({ target: "all", item: "minecraft:diamond", count: 10 });
+Actions.give({ target: Selector("@a", { team: "red" }), item: "minecraft:iron_sword", count: 1 });
 ```
 
+**Note:** The `target` parameter can be:
+- `"all"` - All participants
+- `"self"` - Current player (`@s`)
+- Any `Selector` instance for custom targeting
+
 #### `Actions.giveLoot(params)`
 
-Give random items from loot table.
+Give random items from weighted loot table.
 
 ```typescript
 Actions.giveLoot({
-  loot_table: string;  // Loot table path
-  count: number;       // Number of rolls
+  target: TargetNames;  // "all", "self", or any selector
+  items: [{ name: ITEMS; count: number; weight: number }];  // Weighted item list
 });
 
 // Example:
 Actions.giveLoot({
-  loot_table: "minecraft:chests/simple_dungeon",
-  count: 3
+  target: "self",
+  items: [
+    { name: "minecraft:diamond", count: 5, weight: 1 },
+    { name: "minecraft:iron_ingot", count: 10, weight: 3 },
+    { name: "minecraft:gold_ingot", count: 7, weight: 2 }
+  ]
 });
 ```
 
+**Note:** This creates a weighted loot table. Items with higher weights are more likely to be selected.
+
 #### `Actions.clear(params)`
 
-Clear items from player inventory.
+Clear all items from a target's inventory.
 
 ```typescript
 Actions.clear({
-  item?: string;  // Item to clear (omit for all items)
+  target: TargetNames;  // "all", "self", or any selector
 });
 
 // Examples:
-Actions.clear({ item: "diamond" });
-Actions.clear({});  // Clear everything
+Actions.clear({ target: "self" });  // Clear current player's inventory
+Actions.clear({ target: "all" });   // Clear all participants' inventories
 ```
 
 #### `Actions.countItems(params)`
 
-Count the number of a specific item in a target's inventory. Creates and returns a temporary variable with the count.
+Count the number of a specific item in a target's inventory. Creates and returns a temporary variable with the count. This is the prefered way of counting items.
 
 ```typescript
 Actions.countItems({
@@ -577,6 +638,39 @@ 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.
 
+#### `Actions.getCurrentPlayerPosition()`
+
+Get the current player's position as x, y, z Score variables. Must be called in a player context (e.g., inside `forEveryPlayer`, individual variables updaters, or when `@s` is a player). This is the prefered way of checking a player's position.
+
+```typescript
+Actions.getCurrentPlayerPosition(): { x: Score; y: Score; z: Score }
+
+// Example - Check if player is above Y=100:
+const pos = Actions.getCurrentPlayerPosition();
+_.if(pos.y.greaterThan(100), () => {
+  Actions.announce({ message: "You reached the sky!" });
+});
+
+// Example - Store position in custom variables:
+const { x, y, z } = Actions.getCurrentPlayerPosition();
+variables.player_x.set(x);
+variables.player_y.set(y);
+variables.player_z.set(z);
+
+// Example - Check if player is in a specific area:
+const pos = Actions.getCurrentPlayerPosition();
+_.if(_.and(
+  pos.x.greaterThan(0),
+  pos.x.lowerThan(100),
+  pos.z.greaterThan(0),
+  pos.z.lowerThan(100)
+), () => {
+  Actions.announce({ message: "You're in the zone!" });
+});
+```
+
+**Note:** This returns integer coordinates (block position). The values are truncated from the player's exact floating-point position.
+
 ### Entities
 
 #### `Actions.summonMultiple(params)`
@@ -585,16 +679,22 @@ Summon multiple entities at location.
 
 ```typescript
 Actions.summonMultiple({
-  entity: string;       // Entity ID
-  count: number;        // How many
-  pos: [number, number, number];  // Coordinates
+  entity: string;    // Entity ID (with "minecraft:" prefix)
+  count: number;     // How many entities to summon
+  x: number;         // X coordinate
+  y: number;         // Y coordinate
+  z: number;         // Z coordinate
+  absolute: boolean; // true for absolute coords, false for relative
 });
 
 // Example:
 Actions.summonMultiple({
-  entity: "zombie",
+  entity: "minecraft:zombie",
   count: 5,
-  pos: [0, 64, 0]
+  x: 0,
+  y: 64,
+  z: 0,
+  absolute: true
 });
 ```
 
@@ -604,10 +704,20 @@ Summon item entity at location.
 
 ```typescript
 Actions.summonItem({
-  item: string;
-  pos: [number, number, number];
-  count?: number;
-  nbt?: NBTObject;
+  item: string;      // Item ID (with "minecraft:" prefix)
+  x: number;         // X coordinate
+  y: number;         // Y coordinate
+  z: number;         // Z coordinate
+  absolute: boolean; // true for absolute coords, false for relative
+});
+
+// Example:
+Actions.summonItem({
+  item: "minecraft:diamond",
+  x: 0,
+  y: 64,
+  z: 0,
+  absolute: true
 });
 ```
 
@@ -617,29 +727,32 @@ Kill entities matching selector.
 
 ```typescript
 Actions.kill({
-  target: string;  // Entity selector
+  selector: TargetNames;  // "all", "self", or any selector
 });
 
 // Examples:
-Actions.kill({ target: "@e[type=zombie]" });
-Actions.kill({ target: "@e[type=!player]" });
+Actions.kill({ selector: Selector("@e", { type: "minecraft:zombie" }) });
+Actions.kill({ selector: Selector("@e", { type: "!minecraft:player" }) });
+Actions.kill({ selector: "all" });  // Kill all participants
 ```
 
 #### `Actions.teleport(params)`
 
-Teleport entity to location.
+Teleport entities to a location.
 
 ```typescript
 Actions.teleport({
-  target: string;  // Entity selector
-  pos: [number, number, number];  // Destination
+  target: TargetNames;  // "all", "self", or any selector
+  x: number;            // X coordinate
+  y: number;            // Y coordinate
+  z: number;            // Z coordinate
+  absolute: boolean;    // true for absolute coords, false for relative
 });
 
-// Example:
-Actions.teleport({
-  target: "@s",
-  pos: [0, 100, 0]
-});
+// Examples:
+Actions.teleport({ target: "self", x: 0, y: 100, z: 0, absolute: true });
+Actions.teleport({ target: "all", x: 0, y: 64, z: 0, absolute: true });
+Actions.teleport({ target: "self", x: 10, y: 0, z: 5, absolute: false });  // Relative position
 ```
 
 ### World
@@ -650,14 +763,20 @@ Set a single block.
 
 ```typescript
 Actions.setBlock({
-  pos: [number, number, number];
-  block: string;  // Block ID
+  block: string;     // Block ID (with "minecraft:" prefix)
+  x: number;         // X coordinate
+  y: number;         // Y coordinate
+  z: number;         // Z coordinate
+  absolute: boolean; // true for absolute coords, false for relative
 });
 
 // Example:
 Actions.setBlock({
-  pos: [0, 64, 0],
-  block: "diamond_block"
+  block: "minecraft:diamond_block",
+  x: 0,
+  y: 64,
+  z: 0,
+  absolute: true
 });
 ```
 
@@ -667,19 +786,33 @@ Fill region with blocks.
 
 ```typescript
 Actions.fill({
-  start: [number, number, number];
-  end: [number, number, number];
-  block: string;
-  mode: "fill" | "line" | "pyramid";
+  block: string;     // Block ID (with "minecraft:" prefix)
+  x1: number;        // Start X coordinate
+  y1: number;        // Start Y coordinate
+  z1: number;        // Start Z coordinate
+  x2: number;        // End X coordinate
+  y2: number;        // End Y coordinate
+  z2: number;        // End Z coordinate
+  absolute: boolean; // true for absolute coords, false for relative
+  mode: "fill" | "line" | "pyramid";  // Fill mode
 });
 
-// Example:
+// Examples:
 Actions.fill({
-  start: [0, 64, 0],
-  end: [10, 64, 10],
-  block: "stone",
+  block: "minecraft:stone",
+  x1: 0, y1: 64, z1: 0,
+  x2: 10, y2: 64, z2: 10,
+  absolute: true,
   mode: "fill"
 });
+
+Actions.fill({
+  block: "minecraft:gold_block",
+  x1: 0, y1: 64, z1: 0,
+  x2: 0, y2: 10, z2: 0,
+  absolute: true,
+  mode: "pyramid"  // Builds a pyramid
+});
 ```
 
 #### `Actions.setTime(params)`
@@ -721,19 +854,13 @@ 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;
+  variable: Score;
+  value: number | Score;
 });
 
 // Examples:
-Actions.set({ score: variables.main_score, value: 0 });
-Actions.set({ score: variables.main_score, source: variables.diamonds });
+Actions.set({ variable: variables.main_score, value: 0 });
+Actions.set({ variable: variables.main_score, value: variables.diamonds });
 ```
 
 #### `Actions.increment(params)`
@@ -742,8 +869,11 @@ Add 1 to score.
 
 ```typescript
 Actions.increment({
-  score: Score;
+  variable: Score;
 });
+
+// Example:
+Actions.increment({ variable: variables.counter });
 ```
 
 #### `Actions.decrement(params)`
@@ -752,34 +882,38 @@ Subtract 1 from score.
 
 ```typescript
 Actions.decrement({
-  score: Score;
+  variable: Score;
 });
+
+// Example:
+Actions.decrement({ variable: variables.counter });
 ```
 
 ### Player Attributes
 
 #### `Actions.setAttribute(params)`
 
-Set entity attribute.
+Set entity attribute for a target.
 
 ```typescript
 Actions.setAttribute({
-  attribute: string;  // Attribute name
-  value: number;
+  target: TargetNames;  // "all", "self", or any selector
+  attribute_: string;   // Attribute name
+  value: number;        // Attribute value
 });
 
 // Examples:
-Actions.setAttribute({ attribute: "max_health", value: 40 });
-Actions.setAttribute({ attribute: "movement_speed", value: 0.2 });
-Actions.setAttribute({ attribute: "attack_damage", value: 10 });
+Actions.setAttribute({ target: "self", attribute_: "generic.max_health", value: 40 });
+Actions.setAttribute({ target: "all", attribute_: "generic.movement_speed", value: 0.2 });
+Actions.setAttribute({ target: "self", attribute_: "generic.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)
+Common attributes (with `generic.` prefix):
+- `"generic.max_health"` - Maximum HP (default 20)
+- `"generic.movement_speed"` - Walk speed (default 0.1)
+- `"generic.attack_damage"` - Base attack damage
+- `"generic.armor"` - Armor points
+- `"generic.knockback_resistance"` - Knockback resistance (0-1)
 
 
 ### Logging
@@ -790,9 +924,16 @@ Log variable to watcher system (debugging).
 
 ```typescript
 Actions.log_variable({
-  message: string;
-  variable: Score;
-  store: string;
+  message: string;   // Log message
+  variable: Score;   // Variable to log
+  store: boolean;    // Whether to store in backend
+});
+
+// Example:
+Actions.log_variable({
+  message: "Player score",
+  variable: variables.main_score,
+  store: true
 });
 ```
 
@@ -810,9 +951,15 @@ import { forEveryPlayer } from "@kradle/challenges";
 forEveryPlayer(() => {
   // Runs as(@s) at(@s) for each participant
   // @s is the current player
+  // All individual variables reference the current player within this context
 });
 ```
 
+**Important Notes:**
+- Individual variables automatically reference the current player (`@s`) within the loop
+- Global variables remain global and are the same across all iterations
+- Each iteration executes at the player's position (`at(@s)`)
+
 **Example - Find maximum score:**
 ```typescript
 max_score: {
@@ -820,6 +967,7 @@ max_score: {
   updater: (value, { main_score }) => {
     value.set(0);
     forEveryPlayer(() => {
+      // main_score here refers to the current player's main_score
       _.if(main_score.greaterThan(value), () => {
         value.set(main_score);
       });
@@ -957,7 +1105,7 @@ createChallenge({
       Actions.announce({ message: "First to kill 2 pigs wins!" });
     },
     init_participants: () => {
-      Actions.give({ item: "minecraft:iron_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:iron_sword", count: 1 });
     },
   }))
   .custom_events(({ pigs_farmed }) => [
@@ -992,7 +1140,7 @@ createChallenge({
       type: "individual",
       objective_type: "dummy",
       updater: (value) => {
-        execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
+        value.set(Actions.getCurrentPlayerPosition().y)
       },
     },
     max_height: {
@@ -1036,8 +1184,8 @@ createChallenge({
       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 });
+      Actions.give({ target: "all", item: "minecraft:cobblestone", count: 64 });
+      Actions.give({ target: "all", item: "minecraft:cobblestone", count: 64 });
     },
   }))
   .custom_events(() => [])
@@ -1088,9 +1236,9 @@ createChallenge({
       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 });
+      Actions.give({ target: "all", item: "minecraft:stone_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:leather_chestplate", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:cooked_beef", count: 10 });
     },
   }))
   .custom_events(({ kills }) => [
@@ -1149,7 +1297,7 @@ createChallenge({
     },
     init_participants: () => {
       // Different items based on role would be set via role-specific logic
-      Actions.give({ item: "minecraft:wooden_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:wooden_sword", count: 1 });
     },
   }))
   .custom_events(() => [])
@@ -1213,7 +1361,7 @@ createChallenge({
       Actions.announce({ message: "Capture the enemy flag and return to base!" });
     },
     init_participants: () => {
-      Actions.give({ item: "minecraft:iron_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:iron_sword", count: 1 });
     },
   }))
   .custom_events(({ captured_flag }) => [
@@ -1290,6 +1438,10 @@ current_y: {
   type: "individual",
   objective_type: "dummy",
   updater: (value) => {
+    // Prefered way: using the dedicated Action
+    value.set(Actions.getCurrentPlayerPosition().y)
+
+    // Alternative way: using execute.store + data.get
     execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
   },
 }

package/README.md

@@ -22,46 +22,6 @@ Like for installation, we strongly recommend using Kradle's CLI to bootstrap a c
 kradle challenge create my-challenge
 ```
 
-```typescript
-import { createChallenge, Actions } from "@kradle/challenges";
-
-createChallenge({
-  name: "my-challenge",
-  kradle_challenge_path: "./output",
-  roles: ["player"] as const,
-  GAME_DURATION: 2 * 60 * 20, // 2 minutes in ticks
-  custom_variables: {
-    diamonds_collected: {
-      type: "individual",
-      objective_type: "minecraft.picked_up:minecraft.diamond",
-      default: 0,
-    },
-  },
-})
-  .events(({ diamonds_collected }) => ({
-    start_challenge: () => {
-      Actions.setTime({ time: "day" });
-      Actions.announce({ message: "Collect as many diamonds as possible!" });
-    },
-    init_participants: () => {
-      Actions.give({ item: "iron_pickaxe", count: 1 });
-    },
-  }))
-  .custom_events(({ diamonds_collected }) => [
-    {
-      score: diamonds_collected,
-      target: 10,
-      mode: "fire_once",
-      actions: () => {
-        Actions.announce({ message: "Someone collected 10 diamonds!" });
-      },
-    },
-  ])
-  .end_condition(({ game_timer }) => game_timer.greaterThan(2 * 60 * 20))
-  .win_conditions(({ diamonds_collected }, { player }) => ({
-    [player]: diamonds_collected.greaterThan(0),
-  }));
-```
 
 ## API Overview
 
@@ -131,7 +91,7 @@ current_height: {
   type: "individual",
   objective_type: "dummy",
   updater: (value) => {
-    execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
+    value.set(Actions.getPlayerPosition().y)
   },
 }
 ```
@@ -176,6 +136,8 @@ If you track a Minecraft objective, you do not need an updater!
 
 ### Lifecycle Events
 
+Lifecycle events are triggered once on specific occasions.
+
 ```typescript
 .events((variables, roles) => ({
   start_challenge: () => {
@@ -185,13 +147,13 @@ If you track a Minecraft objective, you do not need an updater!
   },
 
   init_participants: () => {
-    // Runs once per player after challenge starts
-    Actions.give({ item: "diamond_sword", count: 1 });
-    Actions.setAttribute({ attribute: "max_health", value: 40 });
+    // 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 every tick for each player
+    // Runs once every tick
   },
 
   end_challenge: () => {
@@ -207,14 +169,16 @@ Custom events trigger actions based on score thresholds or Minecraft advancement
 
 #### Score-based events
 
-Score events watch a variable and trigger when it reaches a target value.
+Score events watch a variable and trigger when it reaches a target value. 
 
-- **`score`**: The variable to watch
+- **`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) => [
   {
@@ -234,6 +198,8 @@ If `target` is omitted, the event triggers whenever the score changes (useful fo
 
 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
@@ -252,7 +218,7 @@ Advancement events trigger when a Minecraft advancement criterion is met (e.g.,
     ],
     mode: "repeatable",
     actions: () => {
-      Actions.increment({ score: variables.pvp_hits });
+      Actions.increment({ variable: variables.pvp_hits });
     },
   },
 ])
@@ -291,41 +257,66 @@ Define how winners are determined per role:
 
 ## Actions
 
-Pre-built actions for common game operations:
+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!" });
-Actions.tellraw({ target: "@a", message: { text: "Hello", color: "gold" } });
+
+// 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({ item: "diamond_sword", count: 1 });
-Actions.give({ item: "diamond_sword", count: 1, nbt: { Enchantments: [...] } });
-Actions.giveLoot({ loot_table: "minecraft:chests/simple_dungeon", count: 3 });
-Actions.clear({ item: "diamond" });
+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: "zombie", count: 5, pos: [0, 64, 0] });
-Actions.kill({ target: "@e[type=zombie]" });
-Actions.teleport({ target: "@s", pos: [0, 100, 0] });
+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({ pos: [0, 64, 0], block: "diamond_block" });
+Actions.setBlock({ block: "minecraft:diamond_block", x: 0, y: 64, z: 0, absolute: true });
 Actions.fill({
-  start: [0, 64, 0],
-  end: [10, 64, 10],
-  block: "stone",
+  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
@@ -334,24 +325,24 @@ Actions.gamerule({ rule: "doDaylightCycle", value: false });
 
 ### Scores
 ```typescript
-Actions.set({ score: variables.main_score, value: 10 });
-Actions.set({ score: variables.main_score, source: variables.diamonds });
-Actions.increment({ score: variables.counter });
-Actions.decrement({ score: variables.counter });
+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({ attribute: "max_health", value: 40 });
-Actions.setAttribute({ attribute: "movement_speed", value: 0.2 });
+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({ action: () => {
+Actions.custom(() => {
   // Any Sandstone code here
   execute.as("@a").run.effect.give("@s", "speed", 10, 1);
-}});
+});
 ```
 
 ## Utilities
@@ -406,8 +397,8 @@ createChallenge({
       Actions.announce({ message: "Last player standing wins!" });
     },
     init_participants: () => {
-      Actions.give({ item: "stone_sword", count: 1 });
-      Actions.give({ item: "leather_chestplate", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:stone_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:leather_chestplate", count: 1 });
     },
   }))
   .custom_events(({ kills }) => [

package/dist/actions.d.ts

@@ -149,11 +149,11 @@ export declare const Actions: {
     }) => void;
     /**
      * Send a chat message to a target.
-     * @param {string[]} message - The message to send.
+     * @param {JSONTextComponent} message - The message to send.
      * @param {TargetNames} target - The target to send the message to.
      */
     tellraw: ({ message, target }: {
-        message: string[];
+        message: JSONTextComponent;
         target: TargetNames;
     }) => void;
     /**
@@ -216,5 +216,15 @@ export declare const Actions: {
         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

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/dist/actions.js

@@ -221,7 +221,7 @@ exports.Actions = {
     },
     /**
      * Send a chat message to a target.
-     * @param {string[]} message - The message to send.
+     * @param {JSONTextComponent} message - The message to send.
      * @param {TargetNames} target - The target to send the message to.
      */
     tellraw: ({ message, target }) => {
@@ -284,5 +284,19 @@ exports.Actions = {
         sandstone_1.execute.store.result.score(variable).run.clear(mapTarget(target), item, 0);
         return variable;
     },
+    /**
+     * 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: () => {
+        const x = (0, sandstone_1.Variable)();
+        const y = (0, sandstone_1.Variable)();
+        const z = (0, sandstone_1.Variable)();
+        sandstone_1.execute.store.result.score(x).run.data.get.entity("@s", "Pos[0]");
+        sandstone_1.execute.store.result.score(y).run.data.get.entity("@s", "Pos[1]");
+        sandstone_1.execute.store.result.score(z).run.data.get.entity("@s", "Pos[2]");
+        return { x, y, z };
+    },
 };
 //# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kradle/challenges",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Kradle's challenges API",
   "keywords": [],
   "license": "AGPL-3.0",

package/src/actions.ts

@@ -319,10 +319,10 @@ export const Actions = {
 
 	/**
 	 * Send a chat message to a target.
-	 * @param {string[]} message - The message to send.
+	 * @param {JSONTextComponent} message - The message to send.
 	 * @param {TargetNames} target - The target to send the message to.
 	 */
-	tellraw: ({ message, target }: { message: string[]; target: TargetNames }) => {
+	tellraw: ({ message, target }: { message: JSONTextComponent; target: TargetNames }) => {
 		tellraw(mapTarget(target), message);
 	},
 
@@ -388,4 +388,19 @@ export const Actions = {
 		execute.store.result.score(variable).run.clear(mapTarget(target), item, 0);
 		return variable;
 	},
+
+	/**
+	 * 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: () => {
+		const x = Variable();
+		const y = Variable();
+		const z = Variable();
+		execute.store.result.score(x).run.data.get.entity("@s", "Pos[0]");
+		execute.store.result.score(y).run.data.get.entity("@s", "Pos[1]");
+		execute.store.result.score(z).run.data.get.entity("@s", "Pos[2]");
+		return { x, y, z };
+	},
 } satisfies Record<string, (...args: any[]) => any>;