@kradle/cli 0.2.3 → 0.2.4

package/oclif.manifest.json

@@ -800,5 +800,5 @@
       ]
     }
   },
-  "version": "0.2.3"
+  "version": "0.2.4"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kradle/cli",
-	"version": "0.2.3",
+	"version": "0.2.4",
 	"description": "Kradle's CLI. Manage challenges, experiments, agents and more!",
 	"keywords": [
 		"cli"

package/static/ai_docs/LLM_API_REFERENCE.md

@@ -261,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)
   },
 }
 ```
@@ -323,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.
@@ -337,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({ target: "self", item: "minecraft:diamond_sword", count: 1 });
-  Actions.setAttribute({ target: "self", attribute_: "generic.max_health", value: 40 });
-  Actions.teleport({ target: "self", x: 0, y: 100, z: 0, absolute: true });
+  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: () => {
@@ -402,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!" });
   },
@@ -417,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"`
@@ -476,6 +480,13 @@ 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
@@ -497,28 +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: TargetNames;  // "all", "self", or any selector
-  message: string[];    // Message array
+  target: TargetNames;       // "all", "self", or any selector
+  message: JSONTextComponent; // Message (string or formatted object)
 });
 
-// Example:
+// Examples:
 Actions.tellraw({
   target: "all",
   message: ["Hello, ", { text: "world!", color: "gold", bold: true }]
 });
 Actions.tellraw({
   target: "self",
-  message: ["You won!"]
+  message: "You won!"
+});
+Actions.tellraw({
+  target: "self",
+  message: { text: "Critical hit!", color: "red", bold: true }
 });
 ```
 
@@ -611,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)`
@@ -1045,7 +1105,7 @@ createChallenge({
       Actions.announce({ message: "First to kill 2 pigs wins!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:iron_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:iron_sword", count: 1 });
     },
   }))
   .custom_events(({ pigs_farmed }) => [
@@ -1080,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: {
@@ -1124,8 +1184,8 @@ createChallenge({
       Actions.announce({ message: "Climb as high as you can!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:cobblestone", count: 64 });
-      Actions.give({ target: "self", 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(() => [])
@@ -1176,9 +1236,9 @@ createChallenge({
       Actions.announce({ message: "Last player standing wins!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:stone_sword", count: 1 });
-      Actions.give({ target: "self", item: "minecraft:leather_chestplate", count: 1 });
-      Actions.give({ target: "self", 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 }) => [
@@ -1237,7 +1297,7 @@ createChallenge({
     },
     init_participants: () => {
       // Different items based on role would be set via role-specific logic
-      Actions.give({ target: "self", item: "minecraft:wooden_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:wooden_sword", count: 1 });
     },
   }))
   .custom_events(() => [])
@@ -1301,7 +1361,7 @@ createChallenge({
       Actions.announce({ message: "Capture the enemy flag and return to base!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:iron_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:iron_sword", count: 1 });
     },
   }))
   .custom_events(({ captured_flag }) => [
@@ -1378,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]");
   },
 }