redscript-mc 1.0.0

package/docs/LANGUAGE_REFERENCE.md

@@ -0,0 +1,415 @@
+# RedScript Language Reference
+
+This document describes the syntax RedScript accepts today.
+
+## Program Structure
+
+A source file may optionally declare a namespace, followed by any number of `struct` and `fn` declarations.
+
+```rs
+namespace turret;
+
+struct TurretState { health: int }
+
+fn main() {}
+```
+
+If no namespace is provided, the CLI derives one from the filename or uses the compile option you pass.
+
+## Types
+
+RedScript currently supports these primitive types:
+
+| Type | Notes |
+|:--|:--|
+| `int` | Scoreboard-backed integer values |
+| `bool` | Lowered as `0` or `1` |
+| `float` | Fixed-point values scaled by `1000` |
+| `string` | Used primarily in builtin calls |
+| `void` | Function return type when no value is produced |
+
+Composite types:
+
+| Type form | Example |
+|:--|:--|
+| Struct | `TurretState` |
+| Array | `int[]`, `string[]` |
+
+### Variables
+
+```rs
+let hp: int = 20;
+let enabled: bool = true;
+let speed: float = 1.5;
+let name: string = "turret";
+let numbers: int[] = [1, 2, 3];
+```
+
+Type annotations are supported on `let` bindings and function parameters. Function return types use `->`.
+
+## Functions
+
+Functions use C-style syntax and may return values.
+
+```rs
+fn add(a: int, b: int) -> int {
+    return a + b;
+}
+
+fn announce() {
+    say("Ready");
+}
+```
+
+Rules:
+
+- Parameters are positional.
+- A missing return type defaults to `void`.
+- `return;` is valid in `void` functions.
+- Function calls are synchronous and compile to `function <namespace>:<name>`.
+
+## Control Flow
+
+### `if` / `else`
+
+```rs
+fn reward(kills: int) {
+    if (kills >= 10) {
+        give(@s, "minecraft:diamond", 1);
+    } else {
+        tell(@s, "Keep going.");
+    }
+}
+```
+
+`else if` chains are expressed as nested `if` inside `else`.
+
+### `while`
+
+```rs
+fn countdown() {
+    let n: int = 5;
+    while (n > 0) {
+        n -= 1;
+    }
+}
+```
+
+### `for`
+
+RedScript supports C-style `for` loops.
+
+```rs
+fn repeat() {
+    for (let i: int = 0; i < 5; i += 1) {
+        say("tick");
+    }
+}
+```
+
+The initializer is optional, and compound assignment is supported in the step clause.
+
+### `foreach`
+
+`foreach` iterates over a selector by extracting the body into a helper function and running it with `execute as ... run function ...`.
+
+```rs
+fn notify_players() {
+    foreach (player in @a) {
+        title(player, "Fight!");
+    }
+}
+```
+
+Inside the loop body, the bound variable refers to the current entity context.
+
+## Structs
+
+Structs group fields and are stored in Minecraft storage.
+
+```rs
+struct TurretState {
+    health: int,
+    level: int
+}
+
+fn create() {
+    let state: TurretState = { health: 40, level: 1 };
+    state.health = 50;
+    let hp = state.health;
+}
+```
+
+Supported operations:
+
+- Struct declaration
+- Struct literals
+- Field read
+- Field assignment
+- Compound assignment on fields such as `state.health += 5`
+
+## Arrays
+
+Arrays are currently backed by Minecraft storage.
+
+```rs
+fn sample() {
+    let nums: int[] = [1, 2, 3];
+    nums.push(4);
+    let first = nums[0];
+}
+```
+
+Current support includes:
+
+- Empty arrays: `[]`
+- Array literals with initial values
+- `push(...)`
+- Index reads such as `arr[0]`
+
+## Decorators
+
+Decorators attach runtime behavior to functions.
+
+### `@tick`
+
+Runs every game tick through the generated `__tick.mcfunction`.
+
+```rs
+@tick
+fn heartbeat() {
+    say("tick");
+}
+```
+
+### `@tick(rate=N)`
+
+Runs every `N` ticks using a generated scoreboard counter.
+
+```rs
+@tick(rate=20)
+fn once_per_second() {
+    say("1 second");
+}
+```
+
+### `@on_trigger("name")`
+
+Generates trigger plumbing for `/trigger name`.
+
+```rs
+@on_trigger("shop_buy")
+fn handle_shop() {
+    complete_purchase();
+}
+```
+
+The compiler creates:
+
+- a trigger objective in `__load.mcfunction`
+- a dispatch function
+- trigger checks inside `__tick.mcfunction`
+
+## Execute Context
+
+RedScript supports both shorthand context blocks and explicit `execute ... run { ... }`.
+
+### `as`
+
+```rs
+as @a {
+    say("Hello from each player");
+}
+```
+
+### `at`
+
+```rs
+at @s {
+    summon("zombie", "~", "~", "~");
+}
+```
+
+### Combined `as` and `at`
+
+```rs
+as @a at @s {
+    particle("flame", "~", "~", "~");
+}
+```
+
+### `execute ... run { ... }`
+
+Supported subcommands today:
+
+- `as <selector>`
+- `at <selector>`
+- `if entity <selector>`
+- `unless entity <selector>`
+- `in <dimension>`
+
+Examples:
+
+```rs
+execute as @a run {
+    say("Hello");
+}
+
+execute as @a at @s run {
+    particle("flame", "~", "~", "~");
+}
+
+execute as @a if entity @s[tag=admin] run {
+    give(@s, "minecraft:diamond", 1);
+}
+
+execute as @a unless entity @s[tag=dead] run {
+    effect(@s, "regeneration", 5);
+}
+
+execute as @a at @s if entity @s[tag=vip] in overworld run {
+    title(@s, "VIP");
+}
+```
+
+## Selectors
+
+Entity selectors are first-class expressions and can be passed directly to builtins.
+
+### Supported selector heads
+
+| Selector | Meaning |
+|:--|:--|
+| `@a` | All players |
+| `@e` | All entities |
+| `@s` | Current executor |
+| `@p` | Nearest player |
+
+### Common filters
+
+```rs
+@e[type=zombie]
+@e[type=zombie, distance=..8]
+@e[type=armor_stand, tag=turret]
+@a[scores={kills=10..}]
+@p[distance=..5]
+```
+
+Supported filter categories in the current parser:
+
+- `type`
+- `distance` with ranges such as `..5`, `1..`, `1..10`
+- `tag`
+- score filters
+- `limit`
+- `sort`
+- `nbt`
+- `gamemode`
+
+## Coordinates
+
+Block positions are first-class values with the `BlockPos` type.
+
+### Absolute coordinates
+
+```rs
+let spawn: BlockPos = (0, 64, 0);
+setblock((4, 65, 4), "minecraft:gold_block");
+```
+
+### Relative coordinates
+
+```rs
+tp(@s, (~1, ~0, ~-1));
+```
+
+### Local coordinates
+
+```rs
+tp(@s, (^0, ^1, ^0));
+```
+
+### Mixed coordinates
+
+```rs
+setblock((~0, 64, ~0), "minecraft:stone");
+```
+
+Each component can be:
+
+- an absolute integer like `64`
+- a relative coordinate like `~` or `~-2`
+- a local coordinate like `^` or `^3`
+
+## Builtins
+
+The compiler recognizes these builtins and lowers them directly to Minecraft commands or runtime helpers.
+
+| Builtin | Returns | Notes |
+|:--|:--|:--|
+| `say(msg)` | `void` | Emits `say` |
+| `tell(sel, msg)` | `void` | Emits `tellraw` with a plain text JSON component |
+| `title(sel, msg)` | `void` | Emits `title <sel> title` |
+| `give(sel, item, count?)` | `void` | Default count is `1` |
+| `effect(sel, effect, duration?, amplifier?)` | `void` | Defaults: duration `30`, amplifier `0` |
+| `summon(type, x?, y?, z?, nbt?)` | `void` | Defaults position to `~ ~ ~` |
+| `particle(name, x?, y?, z?)` | `void` | Defaults position to `~ ~ ~` |
+| `tp(sel, x?, y?, z?)` | `void` | Also accepts `tp(sel, pos)` with `BlockPos` |
+| `setblock(x, y, z, block)` | `void` | Also accepts `setblock(pos, block)` with `BlockPos` |
+| `fill(x1, y1, z1, x2, y2, z2, block)` | `void` | Also accepts `fill(from, to, block)` with `BlockPos` |
+| `clone(x1, y1, z1, x2, y2, z2, dx, dy, dz)` | `void` | Also accepts `clone(from, to, dest)` with `BlockPos` |
+| `kill(sel?)` | `void` | Defaults to `@s` |
+| `scoreboard_get(target, objective)` | `int` | Reads a scoreboard score |
+| `score(target, objective)` | `int` | Alias of `scoreboard_get` |
+| `scoreboard_set(target, objective, value)` | `void` | Writes a scoreboard score |
+| `data_get(kind, target, path, scale?)` | `int` | Reads NBT with `data get` |
+| `random(min, max)` | `int` | Uses `scoreboard players random` for pre-1.20.3 compatibility |
+| `random_native(min, max)` | `int` | Uses `/random value <min> <max>` (MC 1.20.3+) |
+| `random_sequence(sequence, seed?)` | `void` | Uses `/random reset <sequence> <seed>`; default seed is `0` (MC 1.20.3+) |
+| `spawn_object(x, y, z)` | world object handle | Spawns an invisible armor stand with generated tags |
+| `raw(cmd)` | `void` | Emits a literal Minecraft command |
+
+### Entity helper methods
+
+These are written as member calls on selectors or spawned object handles:
+
+| Method | Returns | Example |
+|:--|:--|:--|
+| `entity.tag(name)` | `void` | `@s.tag("boss");` |
+| `entity.untag(name)` | `void` | `@s.untag("boss");` |
+| `entity.has_tag(name)` | `bool` | `let boss: bool = @s.has_tag("boss");` |
+
+## Operators
+
+Arithmetic and comparison operators:
+
+- `+`, `-`, `*`, `/`, `%`
+- `==`, `!=`, `<`, `<=`, `>`, `>=`
+- `&&`, `||`
+- unary `-`, `!`
+
+Assignment operators:
+
+- `=`
+- `+=`
+- `-=`
+- `*=`
+- `/=`
+- `%=`
+
+## Raw Commands
+
+Use `raw(...)` when you need an escape hatch for a command RedScript does not model directly.
+
+```rs
+fn admin() {
+    raw("gamemode creative @a");
+}
+```
+
+## Notes on Numeric Semantics
+
+- `int` values map directly to scoreboard integers.
+- `bool` is lowered as integer `0` or `1`.
+- `float` is stored as fixed-point `value * 1000`.
+- String values are currently most useful as builtin arguments rather than general-purpose data values.

package/docs/MC_MAPPING.md

@@ -0,0 +1,280 @@
+# RedScript to Minecraft Mapping
+
+This document explains how the compiler maps RedScript constructs onto Minecraft commands and generated files.
+
+## Pipeline Overview
+
+The compiler pipeline is:
+
+```text
+Lexer -> Parser -> AST -> IR Lowering -> Optimizer -> CodeGen
+```
+
+The lowering stage converts RedScript syntax into a simple three-address IR. The optimizer rewrites that IR, and code generation emits datapack files or command block JSON.
+
+## Variables
+
+### Local scalar variables
+
+Scalar locals such as `int`, `bool`, and fixed-point `float` values are stored as scoreboard entries on the `rs` objective.
+
+Example RedScript:
+
+```rs
+fn sample() {
+    let x: int = 42;
+}
+```
+
+Typical generated command pattern:
+
+```mcfunction
+scoreboard players set $x rs 42
+```
+
+The compiler uses fake-player names such as:
+
+- `$x`
+- `$t0`
+- `$ret`
+
+This keeps temporary values and user variables addressable through standard scoreboard operations.
+
+### Booleans
+
+Booleans are represented as:
+
+- `0` for false
+- `1` for true
+
+Conditions are compiled into `execute if score ... matches 1..` style checks.
+
+### Floats
+
+`float` values are stored as fixed-point integers scaled by `1000`.
+
+Example:
+
+```rs
+let speed: float = 1.5;
+```
+
+becomes an internal scoreboard value of `1500`.
+
+Multiplication and division insert scaling correction steps during lowering so arithmetic remains approximately correct under the fixed-point scheme.
+
+## Functions
+
+Each RedScript function becomes one or more `.mcfunction` files in the generated namespace.
+
+Example:
+
+```rs
+fn reward_player() {
+    give(@s, "minecraft:diamond", 1);
+}
+```
+
+becomes a datapack function like:
+
+```text
+data/<namespace>/function/reward_player.mcfunction
+```
+
+Function calls map to Minecraft `function` commands:
+
+```mcfunction
+function <namespace>:reward_player
+```
+
+The compiler also generates runtime entrypoints such as:
+
+- `__load.mcfunction`
+- `__tick.mcfunction`
+- trigger dispatch helpers like `__trigger_<name>_dispatch.mcfunction`
+
+## Control Flow
+
+RedScript control flow is lowered into basic blocks and conditional jumps, then emitted as `execute if score ... run function ...` patterns.
+
+Examples:
+
+- `if` creates conditional branches plus merge blocks.
+- `while` and `for` create explicit loop check, body, and exit blocks.
+- `foreach` extracts the loop body into a helper function and runs it with `execute as <selector> run function ...`.
+
+## Selectors and Execution Context
+
+Selectors such as `@a`, `@e[type=zombie]`, and `@s` are preserved directly in emitted commands.
+
+Context blocks map as follows:
+
+| RedScript | Minecraft form |
+|:--|:--|
+| `as @a { ... }` | `execute as @a run function ...` |
+| `at @s { ... }` | `execute at @s run function ...` |
+| `execute as @a if entity @s[tag=vip] run { ... }` | `execute as @a if entity @s[tag=vip] run function ...` |
+
+The body is extracted into a helper `.mcfunction` so the generated `execute` command stays simple and composable.
+
+## Builtins
+
+Many RedScript builtins compile almost directly to one Minecraft command.
+
+Examples:
+
+| RedScript | Generated command pattern |
+|:--|:--|
+| `say("Hello")` | `say Hello` |
+| `give(@s, "minecraft:bread", 1)` | `give @s minecraft:bread 1` |
+| `kill(@e[type=zombie])` | `kill @e[type=zombie]` |
+| `title(@a, "Fight!")` | `title @a title {"text":"Fight!"}` |
+| `scoreboard_set(@s, "kills", 5)` | `scoreboard players set @s kills 5` |
+
+Other builtins need special lowering:
+
+- `scoreboard_get(...)` reads a scoreboard into a compiler-managed temp variable.
+- `data_get(...)` uses `execute store result score ... run data get ...`.
+- `random(...)` uses `scoreboard players random` for legacy compatibility.
+- `random_native(...)` uses `/random value <min> <max>` on MC 1.20.3+.
+- `random_sequence(...)` uses `/random reset <sequence> <seed>` on MC 1.20.3+.
+- `spawn_object(...)` spawns an invisible armor stand and returns a selector handle.
+
+## Structs
+
+Structs are stored in Minecraft storage under `rs:heap`.
+
+Example:
+
+```rs
+struct Point { x: int, y: int }
+
+fn test() {
+    let p: Point = { x: 10, y: 20 };
+    p.x = 30;
+}
+```
+
+Typical generated patterns:
+
+```mcfunction
+data modify storage rs:heap point_p.x set value 10
+data modify storage rs:heap point_p.y set value 20
+data modify storage rs:heap point_p.x set value 30
+```
+
+Field reads use `data get storage ...` together with `execute store result score ...`.
+
+## Arrays
+
+Arrays are represented with Minecraft storage and currently behave like NBT-backed collections.
+
+Example:
+
+```rs
+let arr: int[] = [1, 2, 3];
+arr.push(4);
+let first = arr[0];
+```
+
+Typical generated patterns:
+
+```mcfunction
+data modify storage rs:heap arr set value []
+data modify storage rs:heap arr append value 1
+data modify storage rs:heap arr append value 2
+data modify storage rs:heap arr append value 3
+data modify storage rs:heap arr append value 4
+```
+
+This part of the storage model is still evolving, so larger collection features should be treated as early-stage compared with scalar scoreboard variables.
+
+## World Objects
+
+`spawn_object(...)` creates an invisible marker armor stand and uses tags plus scoreboards to model a world-backed object.
+
+Example:
+
+```rs
+let turret = spawn_object(0, 64, 0);
+turret.health = 100;
+turret.tag("turret");
+```
+
+Typical generated behavior:
+
+- summon an armor stand with tags like `__rs_obj_<n>`
+- address it with a selector such as `@e[tag=__rs_obj_<n>,limit=1]`
+- map field writes to scoreboard or storage operations
+- map `tag(...)` and `untag(...)` to the vanilla `tag` command
+
+## Tick and Trigger Decorators
+
+### `@tick`
+
+Tick handlers are registered through `data/minecraft/tags/function/tick.json` and invoked from `__tick.mcfunction`.
+
+### `@tick(rate=N)`
+
+Rate-limited tick handlers get an extra scoreboard counter. The compiler inserts logic equivalent to:
+
+1. increment the counter every tick
+2. check whether it has reached `N`
+3. reset it when the body runs
+
+### `@on_trigger("name")`
+
+Trigger handlers generate:
+
+- `scoreboard objectives add <name> trigger` in `__load.mcfunction`
+- trigger checks in `__tick.mcfunction`
+- a dispatch function that calls the user handler and clears the trigger score
+
+## Command Block Target
+
+In command block mode, the compiler emits a JSON description for command block placement instead of a datapack directory. This is meant for command-block-based setups while reusing the same frontend, lowering, and optimization pipeline.
+
+## Optimizations
+
+The optimizer currently includes three core passes.
+
+### Constant folding
+
+Compile-time constant expressions are evaluated early.
+
+Example:
+
+```rs
+return 2 + 3;
+```
+
+is simplified to an IR constant equivalent to `5`.
+
+### Copy propagation
+
+Redundant temporaries are removed when values can be forwarded safely.
+
+Example idea:
+
+```rs
+let x: int = 10;
+let y: int = x;
+return y;
+```
+
+can emit fewer scoreboard moves because `y` can reuse the known value of `x`.
+
+### Dead code elimination
+
+Assignments whose results are never read are removed before code generation. This reduces scoreboard churn and helps keep generated datapacks smaller and easier to inspect.
+
+## Practical Consequences
+
+The mapping strategy is intentionally pragmatic:
+
+- scoreboard storage is fast and predictable for scalar logic
+- storage-backed structs and arrays handle composite data
+- helper functions keep `execute`-heavy control flow manageable
+- optimization passes reduce unnecessary commands before codegen
+
+That combination is what lets RedScript express higher-level gameplay logic while still compiling to vanilla Minecraft primitives.