redscript-mc 1.0.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug Report
+about: Something isn't compiling right or producing wrong output
+title: '[Bug] '
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+<!-- A clear description of what went wrong -->
+
+## Source file (minimal repro)
+
+```rs
+// Paste the smallest .rs file that reproduces the issue
+```
+
+## Expected output
+
+```
+# What MC commands / datapack structure did you expect?
+```
+
+## Actual output / error
+
+```
+# Paste the compiler error or wrong mcfunction output
+```
+
+## Environment
+
+- RedScript version: <!-- run `redscript --version` -->
+- Node.js version:
+- OS:
+- Target: `datapack` / `structure`
+
+## Additional context
+
+<!-- Anything else: MC version, optimizer on/off, etc. -->

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: Feature Request
+about: New language feature, builtin, or tooling idea
+title: '[Feature] '
+labels: enhancement
+assignees: ''
+---
+
+## What do you want to do?
+
+<!-- Describe the game logic or workflow you're trying to build -->
+
+## What would the syntax look like?
+
+```rs
+// Show what you wish you could write in RedScript
+```
+
+## What MC commands should it compile to?
+
+```
+# Expected mcfunction output (approximate is fine)
+```
+
+## Why is this useful?
+
+<!-- What games or use cases does this enable? -->
+
+## Alternatives considered
+
+<!-- Any workarounds you've tried? -->

package/.github/ISSUE_TEMPLATE/wrong_output.md

@@ -0,0 +1,33 @@
+---
+name: Wrong MC Output
+about: Compiler produces syntactically valid but semantically wrong commands
+title: '[Output] '
+labels: wrong-output
+assignees: ''
+---
+
+## Source
+
+```rs
+// The RedScript code
+```
+
+## Compiled output (actual)
+
+```mcfunction
+# What the compiler produced
+```
+
+## Expected output
+
+```mcfunction
+# What you expected
+```
+
+## MC version
+
+<!-- 1.21.4 / 1.21 / etc. -->
+
+## Notes
+
+<!-- Does it happen with --no-optimize? Which builtins/features are involved? -->

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+## What does this PR do?
+
+<!-- Brief description -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New language feature
+- [ ] New builtin / stdlib
+- [ ] Optimizer improvement
+- [ ] Tooling / CLI
+- [ ] Docs
+
+## Checklist
+
+- [ ] `npm run build` passes
+- [ ] `npm test` passes (all existing tests green)
+- [ ] New tests added for new behavior
+- [ ] If adding a builtin: added to `docs/LANGUAGE_REFERENCE.md` and wiki Builtins page
+- [ ] If changing syntax: updated `docs/LANGUAGE_REFERENCE.md`
+
+## Test coverage
+
+<!-- Which test file(s) cover this change? -->
+
+## Example
+
+```rs
+// Show a RedScript snippet demonstrating the new feature
+```
+
+```mcfunction
+# Show the expected compiled output
+```

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm install
+      - run: npm test
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm install
+      - run: npm run build

package/.github/workflows/publish-extension.yml

@@ -0,0 +1,35 @@
+name: Publish VSCode Extension
+
+on:
+  push:
+    tags:
+      - 'vscode-v*'   # trigger on tags like vscode-v0.2.0
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install vsce & ovsx
+        run: npm install -g @vscode/vsce ovsx
+
+      - name: Package extension
+        working-directory: editors/vscode
+        run: vsce package --no-dependencies
+
+      - name: Publish to VS Marketplace
+        working-directory: editors/vscode
+        env:
+          VSCE_PAT: ${{ secrets.VSCE_PAT }}
+        run: vsce publish --no-dependencies -p "$VSCE_PAT"
+
+      - name: Publish to Open VSX
+        working-directory: editors/vscode
+        env:
+          OVSX_PAT: ${{ secrets.OVSX_PAT }}
+        run: ovsx publish *.vsix -p "$OVSX_PAT"

package/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/README.md

@@ -0,0 +1,261 @@
+<div align="center">
+
+<img src="https://img.shields.io/badge/RedScript-1.0-red?style=for-the-badge&logo=minecraft&logoColor=white" alt="RedScript" />
+
+**A typed scripting language that compiles to Minecraft datapacks.**
+
+Write clean game logic. RedScript handles the scoreboard spaghetti.
+
+[![CI](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![tests](https://img.shields.io/badge/tests-423%20passing-brightgreen)](./src/__tests__)
+
+[中文版](./README.zh.md) · [Wiki](https://github.com/bkmashiro/redscript/wiki) · [Quick Start](#quick-start)
+
+</div>
+
+---
+
+### What is RedScript?
+
+You want to make a Minecraft mini-game. You need a countdown timer, kill counter, respawn logic, and a scoreboard display. In vanilla MC, that's 40+ `.mcfunction` files, hundreds of `execute if score` commands, and a weekend of debugging.
+
+With RedScript, it's this:
+
+```rs
+// pvp_game.rs
+import "stdlib/player.rs"
+
+const GAME_TIME: int = 300;
+
+@tick(rate=20)
+fn every_second() {
+    let time: int = scoreboard_get(#game, #timer);
+
+    if (time <= 0) {
+        end_game();
+        return;
+    }
+
+    scoreboard_set(#game, #timer, time - 1);
+    actionbar(@a, "⏱ ${time}s remaining");
+}
+
+fn start_game() {
+    scoreboard_set(#game, #timer, GAME_TIME);
+    scoreboard_set(#game, #running, 1);
+    title(@a, "Fight!", "Game started");
+    tp(@a, (0, 64, 0));
+}
+
+fn end_game() {
+    scoreboard_set(#game, #running, 0);
+    title(@a, "Game Over!");
+    announce("Thanks for playing!");
+}
+
+@on_death
+fn on_kill() {
+    scoreboard_add(@s, #kills, 1);
+}
+```
+
+One file. Compiles to a ready-to-use datapack in seconds.
+
+---
+
+### Quick Start
+
+#### Install
+
+```bash
+npm install -g redscript
+```
+
+#### Compile
+
+```bash
+redscript compile pvp_game.rs -o ./my-datapack
+```
+
+```
+✓ Compiled pvp_game.rs
+  Namespace : pvp_game
+  Functions : 7
+  Commands  : 34  →  28  (optimizer: −18%)
+  Output    : ./my-datapack/
+```
+
+#### Deploy
+
+Drop the output folder into your world's `datapacks/` directory and run `/reload`. Done.
+
+---
+
+### The Language
+
+#### Variables & Types
+
+```rs
+let x: int = 42;
+let name: string = "Steve";
+let spawn: BlockPos = (0, 64, 0);
+let nearby: BlockPos = (~5, ~0, ~5);   // relative coords
+const MAX: int = 100;                  // compile-time constant
+```
+
+#### MC Names (Objectives, Tags, Teams)
+
+Use `#name` for Minecraft identifiers — no quotes needed:
+
+```rs
+// Objectives, fake players, tags, teams — write without quotes
+let hp: int = scoreboard_get(@s, #health);
+scoreboard_set(#game, #timer, 300);     // fake player #game, objective timer
+tag_add(@s, #hasKey);
+team_join(#red, @s);
+gamerule(#keepInventory, true);
+
+// String literals still work (backward compatible)
+scoreboard_get(@s, "health")            // same output as #health
+```
+
+#### Functions & Defaults
+
+```rs
+fn greet(player: selector, msg: string = "Welcome!") {
+    tell(player, msg);
+}
+
+greet(@s);              // uses default message
+greet(@a, "Hello!");    // override
+```
+
+#### Decorators
+
+```rs
+@tick                  // every tick
+fn heartbeat() { ... }
+
+@tick(rate=20)         // every second
+fn every_second() { ... }
+
+@on_advancement("story/mine_diamond")
+fn on_diamond() {
+    give(@s, "minecraft:diamond", 5);
+}
+
+@on_death
+fn on_death() {
+    scoreboard_add(@s, #deaths, 1);
+}
+```
+
+#### Control Flow
+
+```rs
+if (hp <= 0) {
+    respawn();
+} else if (hp < 5) {
+    warn_player();
+}
+
+for (let i: int = 0; i < 10; i = i + 1) {
+    summon("minecraft:zombie", (i, 64, 0));
+}
+
+foreach (player in @a) {
+    heal(player, 2);
+}
+```
+
+#### Structs & Enums
+
+```rs
+enum Phase { Lobby, Playing, Ended }
+
+struct Player {
+    score: int,
+    alive: bool,
+}
+
+match (phase) {
+    Phase::Lobby   => { announce("Waiting..."); }
+    Phase::Playing => { every_second(); }
+    Phase::Ended   => { show_scoreboard(); }
+}
+```
+
+#### Lambdas
+
+```rs
+fn apply(f: (int) -> int, x: int) -> int {
+    return f(x);
+}
+
+let double = (x: int) -> int { return x * 2; };
+apply(double, 5);  // 10
+```
+
+#### Arrays
+
+```rs
+let scores: int[] = [];
+push(scores, 42);
+
+foreach (s in scores) {
+    announce("Score: ${s}");
+}
+```
+
+---
+
+### CLI Reference
+
+```
+redscript compile <file>       Compile to datapack (default) or structure
+  -o, --output <dir>           Output directory         [default: ./out]
+  --target datapack|structure  Output format            [default: datapack]
+  --namespace <ns>             Datapack namespace       [default: filename]
+  --no-optimize                Skip optimizer passes
+  --stats                      Print optimizer statistics
+
+redscript repl                 Interactive REPL
+redscript validate <file>      Validate MC commands
+```
+
+---
+
+### Standard Library
+
+```rs
+import "stdlib/math.rs"       // abs, min, max, clamp
+import "stdlib/player.rs"     // is_alive, in_range, get_health
+import "stdlib/timer.rs"      // start_timer, tick_timer, has_elapsed
+import "stdlib/cooldown.rs"   // set_cooldown, check_cooldown
+import "stdlib/mobs.rs"       // ZOMBIE, SKELETON, CREEPER, ... (60+ constants)
+```
+
+---
+
+### Further Reading
+
+| | |
+|---|---|
+| 📖 [Language Reference](docs/LANGUAGE_REFERENCE.md) | Full syntax & type system |
+| 🔧 [Builtins](https://github.com/bkmashiro/redscript/wiki/Builtins) | All 34+ MC builtin functions |
+| ⚡ [Optimizer](https://github.com/bkmashiro/redscript/wiki/Optimizer) | How the optimizer works |
+| 🧱 [Structure Target](docs/STRUCTURE_TARGET.md) | Compile to NBT command block structures |
+| 🧪 [Integration Testing](https://github.com/bkmashiro/redscript/wiki/Integration-Testing) | Test against a real Paper server |
+| 🏗 [Implementation Guide](docs/IMPLEMENTATION_GUIDE.md) | Compiler internals |
+
+---
+
+<div align="center">
+
+MIT License · Copyright © 2026 [bkmashiro](https://github.com/bkmashiro)
+
+*Write less. Build more. Ship faster.*
+
+</div>