redscript-mc 1.0.0

package/docs/STRUCTURE_TARGET.md

@@ -0,0 +1,80 @@
+# Structure Target
+
+`--target structure` emits a Minecraft structure file (`.nbt`) containing command blocks loaded with the compiled output. This is useful when you want to place the compiler output directly in-world with a Structure Block or `/place structure`, instead of copying loose command blocks by hand.
+
+## Workflow
+
+Compile a source file into a raw structure NBT:
+
+```bash
+redscript compile --target structure src/examples/arena.rs -o arena.nbt
+```
+
+Then copy the generated file into your datapack's `structures/` folder, for example:
+
+```text
+world/datapacks/my_pack/structures/arena.nbt
+```
+
+After reloading the datapack, place it in-game:
+
+```mcfunction
+/place structure my_pack:arena ~ ~ ~
+```
+
+You can also preview and load the same file with a Structure Block.
+
+## Layout
+
+Each non-comment, non-blank line from each generated `.mcfunction` file becomes one command block. Blocks are laid out eastward, then wrapped row-by-row in a snake-friendly grid with a maximum width of 16.
+
+```text
+Layer Y=0
+
+[0,0,0] [1,0,0] [2,0,0] ... [15,0,0]
+[0,0,1] [1,0,1] [2,0,1] ... [15,0,1]
+[0,0,2] [1,0,2] [2,0,2] ... [15,0,2]
+```
+
+Palette usage:
+
+- Impulse command block: first command in a non-tick function
+- Chain command block: subsequent commands in the same function
+- Repeating command block: first command in `__tick`, with `auto: 1b`
+
+## Optimizations
+
+The structure target runs an extra optimization pass after normal IR optimization. It rewrites simple control flow into native command block chaining so the placed structure can branch without extra helper functions.
+
+Conditional chain blocks:
+
+- A plain chain command block always runs after the previous block.
+- A conditional chain command block runs only if the previous block succeeded.
+- RedScript uses this to flatten small `if` / `else` bodies directly into the chain.
+
+Before:
+
+```mcfunction
+execute if score $cond rs matches 1.. run function demo:test/then_0
+```
+
+After:
+
+```mcfunction
+execute if score $cond rs matches 1..
+say big
+give @s diamond
+```
+
+The first command block is unconditional. The following inlined blocks are emitted as conditional chain command blocks, so they run only when the guard succeeds.
+
+Inlining threshold:
+
+- RedScript inlines small branch targets up to 8 commands.
+- Larger branches still fall back to helper function calls.
+
+## Limitations
+
+- Minecraft structures are practical only up to roughly 32k placed blocks before they become awkward to manage.
+- Individual command block commands are still limited to 32767 characters.
+- The structure target serializes command blocks only; it does not gzip the output.

package/docs/mc-reference/commands.md

@@ -0,0 +1,259 @@
+# Minecraft Java Edition — Command Reference for RedScript
+
+*Source: minecraft.wiki — Java Edition only*
+
+
+---
+
+
+## `/scoreboard`
+
+```
+scoreboard objectives add <objective> <criteria> [<displayName>]
+scoreboard objectives remove <objective>
+scoreboard objectives setdisplay <slot> [<objective>]
+scoreboard players set <targets> <objective> <score>
+scoreboard players add <targets> <objective> <score>
+scoreboard players remove <targets> <objective> <score>
+scoreboard players reset <targets> [<objective>]
+scoreboard players get <target> <objective>
+scoreboard players operation <targets> <targetObjective> <operation> <source> <sourceObjective>
+  operations: = += -= *= /= %= < > ><
+scoreboard players enable <targets> <objective>   [for trigger objectives]
+```
+
+---
+
+
+## `/execute`
+
+```
+execute [subcommand...] run <command>
+
+Subcommands:
+  as <entity>                      change executor
+  at <entity>                      change position/rotation/dimension to entity
+  in <dimension>                   change dimension
+  positioned <pos>                 change position
+  positioned as <entity>
+  rotated <rot>
+  rotated as <entity>
+  anchored (feet|eyes)
+
+  if/unless entity <entity>        test entity existence
+  if/unless block <pos> <block>    test block
+  if/unless score <target> <obj> (matches <range> | (=|<|<=|>|>=) <source> <obj2>)
+  if/unless blocks <start> <end> <dest> (all|masked)
+  if/unless data (block|entity|storage) <src> <path>
+  if/unless biome <pos> <biome>
+  if/unless predicate <predicate>
+
+  store (result|success) score <targets> <objective>
+  store (result|success) (block|entity|storage) <target> <path> <type> <scale>
+```
+
+---
+
+
+## `/function`
+
+```
+function <name>
+function <name> [<arguments>]
+function <name> with (block <pos> | entity <entity> | storage <source>) [<path>]
+
+<name> = resource location e.g. mypack:path/to/function
+Calls an mcfunction file. Runs synchronously in the same tick.
+Return value available via /return (Java 1.20+)
+```
+
+---
+
+
+## `/data`
+
+```
+data get (block <targetPos> | entity <target> | storage <target>) [<path>] [<scale>]
+data merge (block <targetPos> | entity <target> | storage <target>) <nbt>
+data modify (block <targetPos> | entity <target> | storage <target>) <targetPath> <operation> ...
+  operations:
+    append value <value>
+    append from (block|entity|storage) <source> [<path>]
+    insert <index> value <value>
+    insert <index> from (block|entity|storage) <source> [<path>]
+    prepend value <value>
+    prepend from (block|entity|storage) <source> [<path>]
+    set value <value>
+    set from (block|entity|storage) <source> [<path>]
+data remove (block <targetPos> | entity <target> | storage <target>) <path>
+```
+
+---
+
+
+## `/schedule`
+
+```
+schedule function <function> <time> [append|replace]
+schedule clear <function>
+
+<time> examples: 1t (1 tick), 20t (1 second), 1s, 1d
+append = add to queue even if already scheduled
+replace = (default) replace existing schedule
+```
+
+---
+
+
+## `/return`
+
+```
+return <value>
+return run <command>
+return fail
+
+Sets the return value of the current function.
+<value> = integer
+Available in Java 1.20+
+Propagates return value up the function call chain.
+```
+
+---
+
+
+## `/tag`
+
+```
+tag <targets> add <name>
+tag <targets> remove <name>
+tag <targets> list
+
+Entity tags are string labels.
+Used in selectors: @e[tag=myTag], @e[tag=!excluded]
+```
+
+---
+
+
+## `/trigger`
+
+```
+trigger <objective>
+trigger <objective> add <value>
+trigger <objective> set <value>
+
+Criterion must be "trigger" type.
+Only works if the objective is enabled for the player: scoreboard players enable <player> <obj>
+After triggering, automatically disabled for that player.
+Used to allow non-operator players to interact with datapacks.
+```
+
+---
+
+
+## `/team`
+
+```
+team add <team> [<displayName>]
+team remove <team>
+team join <team> [<members>]
+team leave [<members>]
+team list [<team>]
+team modify <team> <option> <value>
+  options: color, displayName, prefix, suffix, friendlyFire, seeFriendlyInvisibles,
+           nametagVisibility, deathMessageVisibility, collisionRule
+```
+
+---
+
+
+## `/title`
+
+```
+title <targets> title <title>
+title <targets> subtitle <title>
+title <targets> actionbar <title>
+title <targets> clear
+title <targets> reset
+title <targets> times <fadeIn> <stay> <fadeOut>
+
+<title> = JSON text component e.g. {"text":"hello","color":"red"}
+<targets> = entity selector (usually @a or @s)
+Times in ticks.
+```
+
+---
+
+
+## `/tellraw`
+
+```
+tellraw <targets> <message>
+
+<message> = JSON text component:
+  {"text": "hello"}
+  {"text": "click me", "clickEvent": {"action": "run_command", "value": "/say hi"}}
+  {"score": {"name": "@s", "objective": "kills"}}
+  ["array ", "of ", {"text":"components"}]
+```
+
+---
+
+
+## `/effect`
+
+```
+effect give <targets> <effect> [<seconds>] [<amplifier>] [<hideParticles>]
+effect clear [<targets>] [<effect>]
+
+<effect> = effect id e.g. minecraft:speed, minecraft:slowness
+<amplifier> = 0-255 (0 = level 1)
+<seconds> = duration, max 1000000
+<hideParticles> = true|false
+```
+
+---
+
+
+## `/give`
+
+```
+give <targets> <item> [<count>]
+
+<item> = item id with optional NBT e.g. minecraft:diamond, minecraft:written_book{...}
+<count> = 1-2147483647
+```
+
+---
+
+
+## `/kill`
+
+```
+kill [<targets>]
+
+<targets> = entity selector, default = @s
+Kills the entity (sets health to 0, triggers death event).
+```
+
+---
+
+
+## `/summon`
+
+```
+summon <entity> [<pos>] [<nbt>]
+
+<entity> = entity type e.g. minecraft:zombie, minecraft:armor_stand
+<pos> = x y z coordinates
+<nbt> = NBT compound for initialization
+
+Common armor stand trick:
+  summon minecraft:armor_stand ~ ~ ~ {Invisible:1b,Marker:1b,NoGravity:1b,Tags:["myTag"]}
+  - Invisible: no visual
+  - Marker: no hitbox, no physics
+  - Tags: for later @e[tag=myTag] selection
+```
+
+---
+

package/editors/vscode/.vscodeignore

@@ -0,0 +1,10 @@
+.vscode/**
+**/*.map
+**/.eslintrc.json
+node_modules/**
+src/**
+build.mjs
+tsconfig.json
+package-lock.json
+*.vsix
+# out/ is included (bundled extension)

package/editors/vscode/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bkmashiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/editors/vscode/README.md

@@ -0,0 +1,78 @@
+# RedScript VSCode Extension
+
+Syntax highlighting and snippets for [RedScript](https://github.com/bkmashiro/redscript) — a compiler targeting Minecraft Java Edition datapacks.
+
+## Features
+
+- **RedScript syntax highlighting** (`.rs` files)
+  - Keywords: `fn`, `let`, `struct`, `if`, `while`, `for`, `foreach`, `as`, `at`
+  - Entity selectors: `@a`, `@e[type=zombie, distance=..5]`, etc.
+  - Range literals: `..5`, `1..`, `1..10`
+  - Decorators: `@tick`, `@tick(rate=20)`, `@on_trigger("name")`
+  - Built-in functions: `say`, `kill`, `give`, `effect`, `raw`, `random`, `spawn_object`
+  - Types: `int`, `float`, `bool`, `string`, `void`
+
+- **mcfunction syntax highlighting** (`.mcfunction` files)
+  - Full command syntax from [MinecraftCommands/syntax-mcfunction](https://github.com/MinecraftCommands/syntax-mcfunction)
+  - Entity selectors, NBT, coordinates, resource locations
+
+- **Code snippets**
+  - `fn` → function declaration
+  - `tickfn` → `@tick` function
+  - `tickratefn` → `@tick(rate=N)` function
+  - `trigfn` → `@on_trigger` handler
+  - `foreach` → entity foreach loop
+  - `struct` → struct declaration
+  - `for` → C-style for loop
+  - `spawn` → spawn_object call
+  - And more...
+
+## Install
+
+### From VSIX (manual)
+
+```bash
+cd editors/vscode
+npm install -g @vscode/vsce
+vsce package
+code --install-extension redscript-vscode-0.1.0.vsix
+```
+
+### Note on `.rs` extension
+
+RedScript uses `.rs` files, same as Rust. If you have the Rust extension installed, you may need to associate `.rs` files with RedScript manually:
+
+```json
+// settings.json
+{
+  "files.associations": {
+    "*.rs": "redscript"
+  }
+}
+```
+
+Or use `.mcrs` extension (we may switch to this in future).
+
+## Usage
+
+Write RedScript code with full syntax highlighting:
+
+```
+@tick(rate=20)
+fn check_zombies() {
+    foreach (z in @e[type=zombie, distance=..10]) {
+        kill(z);
+    }
+}
+
+@on_trigger("claim_reward")
+fn handle_claim() {
+    give(@s, "minecraft:diamond", 1);
+}
+```
+
+Compile with the CLI:
+
+```bash
+redscript compile src/main.rs -o dist/mypack/
+```

package/editors/vscode/build.mjs

@@ -0,0 +1,28 @@
+import esbuild from 'esbuild'
+
+const watch = process.argv.includes('--watch')
+
+/** @type {import('esbuild').BuildOptions} */
+const config = {
+  entryPoints: ['src/extension.ts'],
+  bundle: true,
+  outfile: 'out/extension.js',
+  external: ['vscode'],   // vscode is provided by the host, never bundle it
+  format: 'cjs',
+  platform: 'node',
+  target: 'node18',
+  sourcemap: false,
+  minify: false,
+  // Stub out Node builtins that the compiler might use
+  // (they're fine in the extension since it runs in Node)
+  // The compiler uses fs/path, which are available in the extension host
+}
+
+if (watch) {
+  const ctx = await esbuild.context(config)
+  await ctx.watch()
+  console.log('Watching for changes...')
+} else {
+  await esbuild.build(config)
+  console.log('Built out/extension.js')
+}

package/editors/vscode/mcfunction-language-configuration.json

@@ -0,0 +1,28 @@
+{
+    "comments": {
+        // symbol used for single line comment. Remove this entry if your language does not support line comments
+        "lineComment": "#",
+    },
+    // symbols used as brackets
+    "brackets": [
+        ["{", "}"],
+        ["[", "]"],
+        ["(", ")"]
+    ],
+    // symbols that are auto closed when typing
+    "autoClosingPairs": [
+        ["{", "}"],
+        ["[", "]"],
+        ["(", ")"],
+        ["\"", "\""],
+        ["'", "'"]
+    ],
+    // symbols that can be used to surround a selection
+    "surroundingPairs": [
+        ["{", "}"],
+        ["[", "]"],
+        ["(", ")"],
+        ["\"", "\""],
+        ["'", "'"]
+    ]
+}