redscript-mc 1.2.17 → 1.2.19

package/dist/__tests__/compile-all.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Compile-all smoke test
+ *
+ * Finds every .mcrs file in the repo (excluding declaration files and node_modules)
+ * and verifies that each one compiles without throwing an error.
+ *
+ * This catches regressions where a language change breaks existing source files.
+ */
+export {};

package/dist/__tests__/compile-all.test.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Compile-all smoke test
+ *
+ * Finds every .mcrs file in the repo (excluding declaration files and node_modules)
+ * and verifies that each one compiles without throwing an error.
+ *
+ * This catches regressions where a language change breaks existing source files.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const compile_1 = require("../compile");
+const REPO_ROOT = path.resolve(__dirname, '../../');
+/** Patterns to skip */
+const SKIP_GLOBS = [
+    'node_modules',
+    '.git',
+    'builtins.d.mcrs', // declaration-only file, not valid source
+    'editors/', // copy of builtins.d.mcrs
+];
+function shouldSkip(filePath) {
+    const rel = path.relative(REPO_ROOT, filePath);
+    return SKIP_GLOBS.some(pat => rel.includes(pat));
+}
+function findMcrsFiles(dir) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        if (shouldSkip(fullPath))
+            continue;
+        if (entry.isDirectory()) {
+            results.push(...findMcrsFiles(fullPath));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.mcrs')) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+const mcrsFiles = findMcrsFiles(REPO_ROOT);
+describe('compile-all: every .mcrs file should compile without errors', () => {
+    test('found at least one .mcrs file', () => {
+        expect(mcrsFiles.length).toBeGreaterThan(0);
+    });
+    for (const filePath of mcrsFiles) {
+        const label = path.relative(REPO_ROOT, filePath);
+        test(label, () => {
+            const source = fs.readFileSync(filePath, 'utf8');
+            // Should not throw
+            expect(() => {
+                (0, compile_1.compile)(source, { namespace: 'smoke_test', optimize: false });
+            }).not.toThrow();
+        });
+    }
+});
+//# sourceMappingURL=compile-all.test.js.map

package/dist/lexer/index.d.ts

@@ -5,7 +5,7 @@
  * Handles special cases like entity selectors vs decorators,
  * range literals, and raw commands.
  */
-export type TokenKind = 'fn' | 'let' | 'const' | 'if' | 'else' | 'while' | 'for' | 'foreach' | 'match' | 'return' | 'break' | 'continue' | 'as' | 'at' | 'in' | 'is' | 'struct' | 'impl' | 'enum' | 'trigger' | 'namespace' | 'execute' | 'run' | 'unless' | 'int' | 'bool' | 'float' | 'string' | 'void' | 'BlockPos' | 'true' | 'false' | 'selector' | 'decorator' | 'int_lit' | 'float_lit' | 'byte_lit' | 'short_lit' | 'long_lit' | 'double_lit' | 'string_lit' | 'f_string' | 'range_lit' | 'rel_coord' | 'local_coord' | '+' | '-' | '*' | '/' | '%' | '~' | '^' | '==' | '!=' | '<' | '<=' | '>' | '>=' | '&&' | '||' | '!' | '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '{' | '}' | '(' | ')' | '[' | ']' | ',' | ';' | ':' | '::' | '->' | '=>' | '.' | 'ident' | 'mc_name' | 'raw_cmd' | 'eof';
+export type TokenKind = 'fn' | 'let' | 'const' | 'if' | 'else' | 'while' | 'for' | 'foreach' | 'match' | 'return' | 'break' | 'continue' | 'as' | 'at' | 'in' | 'is' | 'struct' | 'impl' | 'enum' | 'trigger' | 'namespace' | 'execute' | 'run' | 'unless' | 'declare' | 'int' | 'bool' | 'float' | 'string' | 'void' | 'BlockPos' | 'true' | 'false' | 'selector' | 'decorator' | 'int_lit' | 'float_lit' | 'byte_lit' | 'short_lit' | 'long_lit' | 'double_lit' | 'string_lit' | 'f_string' | 'range_lit' | 'rel_coord' | 'local_coord' | '+' | '-' | '*' | '/' | '%' | '~' | '^' | '==' | '!=' | '<' | '<=' | '>' | '>=' | '&&' | '||' | '!' | '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '{' | '}' | '(' | ')' | '[' | ']' | ',' | ';' | ':' | '::' | '->' | '=>' | '.' | 'ident' | 'mc_name' | 'raw_cmd' | 'eof';
 export interface Token {
     kind: TokenKind;
     value: string;

package/dist/lexer/index.js

@@ -37,6 +37,7 @@ const KEYWORDS = {
     execute: 'execute',
     run: 'run',
     unless: 'unless',
+    declare: 'declare',
     int: 'int',
     bool: 'bool',
     float: 'float',

package/dist/lowering/index.js

@@ -372,7 +372,26 @@ class Lowering {
         if (macroParam) {
             return { str: `$(${macroParam})`, macroParam };
         }
-        // Handle ~ident (e.g. ~height) - relative coord with variable offset
+        // Handle ~ident / ^ident syntax — relative/local coord with a VARIABLE offset.
+        //
+        // WHY macros are required here:
+        //   Minecraft's ~N and ^N coordinate syntax requires N to be a compile-time
+        //   literal number. There is no command that accepts a scoreboard value as a
+        //   relative offset. Therefore `~height` (where height is a runtime int) can
+        //   only be expressed at the MC level via the 1.20.2+ function macro system,
+        //   which substitutes $(height) into the command text at call time.
+        //
+        //   Contrast with absolute coords: `tp(target, x, y, z)` where x/y/z are
+        //   plain ints — those become $(x) etc. as literal replacements, same mechanism,
+        //   but the distinction matters to callers: ~$(height) means "relative by height
+        //   blocks from current pos", not "teleport to absolute scoreboard value".
+        //
+        //   Example:
+        //     fn launch_up(target: selector, height: int) {
+        //       tp(target, ~0, ~height, ~0);   // "~height" parsed as rel_coord
+        //     }
+        //   Emits:  $tp $(target) ~0 ~$(height) ~0
+        //   Called: function ns:launch_up with storage rs:macro_args
         if (expr.kind === 'rel_coord' || expr.kind === 'local_coord') {
             const val = expr.value; // e.g. "~height" or "^depth"
             const prefix = val[0]; // ~ or ^

package/dist/parser/index.d.ts

@@ -27,6 +27,8 @@ export declare class Parser {
     private parseConstDecl;
     private parseGlobalDecl;
     private parseFnDecl;
+    /** Parse a `declare fn name(params): returnType;` stub — no body, just discard. */
+    private parseDeclareStub;
     private parseDecorators;
     private parseDecoratorValue;
     private parseParams;

package/dist/parser/index.js

@@ -149,6 +149,11 @@ class Parser {
             else if (this.check('const')) {
                 consts.push(this.parseConstDecl());
             }
+            else if (this.check('declare')) {
+                // Declaration-only stub (e.g. from builtins.d.mcrs) — parse and discard
+                this.advance(); // consume 'declare'
+                this.parseDeclareStub();
+            }
             else {
                 declarations.push(this.parseFnDecl());
             }
@@ -254,6 +259,26 @@ class Parser {
         const body = this.parseBlock();
         return this.withLoc({ name, params, returnType, decorators, body }, fnToken);
     }
+    /** Parse a `declare fn name(params): returnType;` stub — no body, just discard. */
+    parseDeclareStub() {
+        this.expect('fn');
+        this.expect('ident'); // name
+        this.expect('(');
+        // consume params until ')'
+        let depth = 1;
+        while (!this.check('eof') && depth > 0) {
+            const t = this.advance();
+            if (t.kind === '(')
+                depth++;
+            else if (t.kind === ')')
+                depth--;
+        }
+        // optional return type annotation `: type` or `-> type`
+        if (this.match(':') || this.match('->')) {
+            this.parseType();
+        }
+        this.match(';'); // consume trailing semicolon
+    }
     parseDecorators() {
         const decorators = [];
         while (this.check('decorator')) {
@@ -539,10 +564,29 @@ class Parser {
     parseForRangeStmt(forToken) {
         const varName = this.expect('ident').value;
         this.expect('in');
-        const rangeToken = this.expect('range_lit');
-        const range = this.parseRangeValue(rangeToken.value);
-        const start = this.withLoc({ kind: 'int_lit', value: range.min ?? 0 }, rangeToken);
-        const end = this.withLoc({ kind: 'int_lit', value: range.max ?? 0 }, rangeToken);
+        let start;
+        let end;
+        if (this.check('range_lit')) {
+            // Literal range: 0..10, 0..count, 0..=9
+            const rangeToken = this.advance();
+            const range = this.parseRangeValue(rangeToken.value);
+            start = this.withLoc({ kind: 'int_lit', value: range.min ?? 0 }, rangeToken);
+            if (range.max !== null && range.max !== undefined) {
+                // Fully numeric: 0..10
+                end = this.withLoc({ kind: 'int_lit', value: range.max }, rangeToken);
+            }
+            else {
+                // Open-ended: "0.." — parse the end expression from next tokens
+                end = this.parseUnaryExpr();
+            }
+        }
+        else {
+            // Dynamic range: expr..expr (e.g. start..end) — not yet supported
+            // Fall back to: parse as int_lit 0..0 (safe default)
+            start = this.withLoc({ kind: 'int_lit', value: 0 }, this.peek());
+            end = this.withLoc({ kind: 'int_lit', value: 0 }, this.peek());
+            this.error('Dynamic range start requires a literal integer (e.g. 0..count)');
+        }
         const body = this.parseBlock();
         return this.withLoc({ kind: 'for_range', varName, start, end, body }, forToken);
     }
@@ -1058,6 +1102,20 @@ class Parser {
         this.error(`Unexpected token '${token.kind}'`);
     }
     parseLiteralExpr() {
+        // Support negative literals: -5, -3.14
+        if (this.check('-')) {
+            this.advance();
+            const token = this.peek();
+            if (token.kind === 'int_lit') {
+                this.advance();
+                return this.withLoc({ kind: 'int_lit', value: -Number(token.value) }, token);
+            }
+            if (token.kind === 'float_lit') {
+                this.advance();
+                return this.withLoc({ kind: 'float_lit', value: -Number(token.value) }, token);
+            }
+            this.error('Expected number after unary -');
+        }
         const expr = this.parsePrimaryExpr();
         if (expr.kind === 'int_lit' ||
             expr.kind === 'float_lit' ||

package/editors/vscode/out/extension.js

@@ -186,6 +186,7 @@ var require_lexer = __commonJS({
       execute: "execute",
       run: "run",
       unless: "unless",
+      declare: "declare",
       int: "int",
       bool: "bool",
       float: "float",
@@ -355,6 +356,13 @@ var require_lexer = __commonJS({
               value += this.advance();
             }
           }
+          if (/[a-zA-Z_]/.test(this.peek())) {
+            let ident = "";
+            while (/[a-zA-Z0-9_]/.test(this.peek())) {
+              ident += this.advance();
+            }
+            value += ident;
+          }
           this.addToken("rel_coord", value, startLine, startCol);
           return;
         }
@@ -815,6 +823,9 @@ var require_parser = __commonJS({
             enums.push(this.parseEnumDecl());
           } else if (this.check("const")) {
             consts.push(this.parseConstDecl());
+          } else if (this.check("declare")) {
+            this.advance();
+            this.parseDeclareStub();
           } else {
             declarations.push(this.parseFnDecl());
           }
@@ -877,12 +888,15 @@ var require_parser = __commonJS({
       parseConstDecl() {
         const constToken = this.expect("const");
         const name = this.expect("ident").value;
-        this.expect(":");
-        const type = this.parseType();
+        let type;
+        if (this.match(":")) {
+          type = this.parseType();
+        }
         this.expect("=");
         const value = this.parseLiteralExpr();
         this.match(";");
-        return this.withLoc({ name, type, value }, constToken);
+        const inferredType = type ?? (value.kind === "str_lit" ? { kind: "named", name: "string" } : value.kind === "bool_lit" ? { kind: "named", name: "bool" } : value.kind === "float_lit" ? { kind: "named", name: "float" } : { kind: "named", name: "int" });
+        return this.withLoc({ name, type: inferredType, value }, constToken);
       }
       parseGlobalDecl(mutable) {
         const token = this.advance();
@@ -911,6 +925,24 @@ var require_parser = __commonJS({
         const body = this.parseBlock();
         return this.withLoc({ name, params, returnType, decorators, body }, fnToken);
       }
+      /** Parse a `declare fn name(params): returnType;` stub — no body, just discard. */
+      parseDeclareStub() {
+        this.expect("fn");
+        this.expect("ident");
+        this.expect("(");
+        let depth = 1;
+        while (!this.check("eof") && depth > 0) {
+          const t = this.advance();
+          if (t.kind === "(")
+            depth++;
+          else if (t.kind === ")")
+            depth--;
+        }
+        if (this.match(":") || this.match("->")) {
+          this.parseType();
+        }
+        this.match(";");
+      }
       parseDecorators() {
         const decorators = [];
         while (this.check("decorator")) {
@@ -3581,6 +3613,15 @@ var require_lowering = __commonJS({
           return null;
         return expr.name;
       }
+      tryGetMacroParamByName(name) {
+        if (!this.currentFnParamNames.has(name))
+          return null;
+        if (this.constValues.has(name))
+          return null;
+        if (this.stringValues.has(name))
+          return null;
+        return name;
+      }
       /**
        * Converts an expression to a string for use as a builtin arg.
        * If the expression is a macro param, returns `$(name)` and sets macroParam.
@@ -3590,6 +3631,17 @@ var require_lowering = __commonJS({
         if (macroParam) {
           return { str: `$(${macroParam})`, macroParam };
         }
+        if (expr.kind === "rel_coord" || expr.kind === "local_coord") {
+          const val = expr.value;
+          const prefix = val[0];
+          const rest = val.slice(1);
+          if (rest && /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(rest)) {
+            const paramName = this.tryGetMacroParamByName(rest);
+            if (paramName) {
+              return { str: `${prefix}$(${paramName})`, macroParam: paramName };
+            }
+          }
+        }
         if (expr.kind === "struct_lit" || expr.kind === "array_lit") {
           return { str: this.exprToSnbt(expr) };
         }
@@ -5875,8 +5927,11 @@ var require_lowering = __commonJS({
       }
       /**
        * Checks a raw() command string for `${...}` interpolation containing runtime variables.
-       * - If the interpolated name is a compile-time constant → OK, no error.
-       * - If the interpolated name is a runtime variable → DiagnosticError.
+       * - If the interpolated expression is a numeric literal → OK (MC macro syntax).
+       * - If the interpolated name is a compile-time constant (in constValues) → OK.
+       * - If the interpolated name is a known runtime variable (in varMap) → DiagnosticError.
+       * - Unknown names → OK (could be MC macro params or external constants).
+       *
        * This catches the common mistake of writing raw("say ${score}") expecting interpolation,
        * which would silently emit a literal `${score}` in the MC command.
        */
@@ -5891,8 +5946,10 @@ var require_lowering = __commonJS({
           if (this.constValues.has(name)) {
             continue;
           }
-          const loc = span ?? { line: 1, col: 1 };
-          throw new diagnostics_1.DiagnosticError("LoweringError", `raw() command contains runtime variable interpolation '\${${name}}'. Variables cannot be interpolated into raw commands at compile time. Use f-string messages for say/tell/announce, or MC macro syntax '$(${name})' for MC 1.20.2+ commands.`, loc);
+          if (this.varMap.has(name) || this.currentFnParamNames.has(name)) {
+            const loc = span ?? { line: 1, col: 1 };
+            throw new diagnostics_1.DiagnosticError("LoweringError", `raw() command contains runtime variable interpolation '\${${name}}'. Variables cannot be interpolated into raw commands at compile time. Use f-string messages (say/tell/announce) or MC macro syntax '$(${name})' for MC 1.20.2+ commands.`, loc);
+          }
         }
       }
       resolveInstanceMethod(expr) {

package/editors/vscode/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "redscript-vscode",
-  "version": "1.0.7",
+  "version": "1.0.11",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "redscript-vscode",
-      "version": "1.0.7",
+      "version": "1.0.11",
       "license": "MIT",
       "dependencies": {
         "redscript": "file:../../"

package/editors/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "redscript-vscode",
   "displayName": "RedScript for Minecraft",
   "description": "Syntax highlighting, error diagnostics, and language support for RedScript — a compiler targeting Minecraft Java Edition",
-  "version": "1.0.7",
+  "version": "1.0.11",
   "publisher": "bkmashiro",
   "icon": "icon.png",
   "license": "MIT",

package/editors/vscode/syntaxes/redscript.tmLanguage.json

@@ -271,7 +271,7 @@
         {
           "comment": "Builtin functions",
           "name": "support.function.builtin.redscript",
-          "match": "\\b(say|tell|announce|title|subtitle|actionbar|title_times|give|kill|effect|clear|kick|xp_add|xp_set|tp|tp_to|setblock|fill|clone|summon|particle|playsound|weather|time_set|time_add|gamerule|difficulty|tag_add|tag_remove|scoreboard_get|scoreboard_set|scoreboard_add|scoreboard_display|scoreboard_hide|scoreboard_add_objective|scoreboard_remove_objective|score|random|random_native|random_sequence|data_get|str_len|push|pop|bossbar_add|bossbar_set_value|bossbar_set_max|bossbar_set_color|bossbar_set_style|bossbar_set_visible|bossbar_set_players|bossbar_remove|bossbar_get_value|team_add|team_remove|team_join|team_leave|team_option|spawn_object|if_entity|unless_entity)(?=\\s*\\()"
+          "match": "\\b(say|tell|tellraw|announce|title|subtitle|actionbar|title_times|give|kill|effect|effect_clear|clear|kick|xp_add|xp_set|tp|tp_to|setblock|fill|clone|summon|particle|playsound|weather|time_set|time_add|gamerule|difficulty|tag_add|tag_remove|scoreboard_get|score|scoreboard_set|scoreboard_add|scoreboard_display|scoreboard_hide|scoreboard_add_objective|scoreboard_remove_objective|random|random_native|random_sequence|data_get|data_merge|str_len|push|pop|bossbar_add|bossbar_set_value|bossbar_set_max|bossbar_set_color|bossbar_set_style|bossbar_set_visible|bossbar_set_players|bossbar_remove|bossbar_get_value|team_add|team_remove|team_join|team_leave|team_option|set_new|set_add|set_contains|set_remove|set_clear|setTimeout|setInterval|clearInterval|spawn_object|if_entity|unless_entity)(?=\\s*\\()"
         },
         {
           "comment": "User-defined function calls",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redscript-mc",
-  "version": "1.2.17",
+  "version": "1.2.19",
   "description": "A high-level programming language that compiles to Minecraft datapacks",
   "main": "dist/index.js",
   "bin": {

package/src/__tests__/compile-all.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Compile-all smoke test
+ *
+ * Finds every .mcrs file in the repo (excluding declaration files and node_modules)
+ * and verifies that each one compiles without throwing an error.
+ *
+ * This catches regressions where a language change breaks existing source files.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { compile } from '../compile'
+
+const REPO_ROOT = path.resolve(__dirname, '../../')
+
+/** Patterns to skip */
+const SKIP_GLOBS = [
+  'node_modules',
+  '.git',
+  'builtins.d.mcrs',   // declaration-only file, not valid source
+  'editors/',          // copy of builtins.d.mcrs
+]
+
+function shouldSkip(filePath: string): boolean {
+  const rel = path.relative(REPO_ROOT, filePath)
+  return SKIP_GLOBS.some(pat => rel.includes(pat))
+}
+
+function findMcrsFiles(dir: string): string[] {
+  const results: string[] = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name)
+    if (shouldSkip(fullPath)) continue
+    if (entry.isDirectory()) {
+      results.push(...findMcrsFiles(fullPath))
+    } else if (entry.isFile() && entry.name.endsWith('.mcrs')) {
+      results.push(fullPath)
+    }
+  }
+  return results
+}
+
+const mcrsFiles = findMcrsFiles(REPO_ROOT)
+
+describe('compile-all: every .mcrs file should compile without errors', () => {
+  test('found at least one .mcrs file', () => {
+    expect(mcrsFiles.length).toBeGreaterThan(0)
+  })
+
+  for (const filePath of mcrsFiles) {
+    const label = path.relative(REPO_ROOT, filePath)
+    test(label, () => {
+      const source = fs.readFileSync(filePath, 'utf8')
+      // Should not throw
+      expect(() => {
+        compile(source, { namespace: 'smoke_test', optimize: false })
+      }).not.toThrow()
+    })
+  }
+})

package/src/examples/capture_the_flag.mcrs

@@ -28,7 +28,7 @@ struct GameState {
     blue_flag_taken: int
 }
 
-let game: GameState = GameState {
+let game: GameState = {
     running: 0,
     red_score: 0,
     blue_score: 0,

package/src/examples/hunger_games.mcrs

@@ -31,7 +31,7 @@ struct HGState {
     alive_count: int
 }
 
-let game: HGState = HGState {
+let game: HGState = {
     running: 0,
     phase: 0,
     countdown: 0,

package/src/examples/zombie_survival.mcrs

@@ -29,7 +29,7 @@ struct SurvivalState {
     total_kills: int
 }
 
-let state: SurvivalState = SurvivalState {
+let state: SurvivalState = {
     running: 0,
     wave: 0,
     zombies_left: 0,

package/src/lexer/index.ts

@@ -16,7 +16,7 @@ export type TokenKind =
   // Keywords
   | 'fn' | 'let' | 'const' | 'if' | 'else' | 'while' | 'for' | 'foreach' | 'match'
   | 'return' | 'break' | 'continue' | 'as' | 'at' | 'in' | 'is' | 'struct' | 'impl' | 'enum' | 'trigger' | 'namespace'
-  | 'execute' | 'run' | 'unless'
+  | 'execute' | 'run' | 'unless' | 'declare'
   // Types
   | 'int' | 'bool' | 'float' | 'string' | 'void'
   | 'BlockPos'
@@ -89,6 +89,7 @@ const KEYWORDS: Record<string, TokenKind> = {
   execute: 'execute',
   run: 'run',
   unless: 'unless',
+  declare: 'declare',
   int: 'int',
   bool: 'bool',
   float: 'float',

package/src/lowering/index.ts

@@ -387,7 +387,26 @@ export class Lowering {
     if (macroParam) {
       return { str: `$(${macroParam})`, macroParam }
     }
-    // Handle ~ident (e.g. ~height) - relative coord with variable offset
+    // Handle ~ident / ^ident syntax — relative/local coord with a VARIABLE offset.
+    //
+    // WHY macros are required here:
+    //   Minecraft's ~N and ^N coordinate syntax requires N to be a compile-time
+    //   literal number. There is no command that accepts a scoreboard value as a
+    //   relative offset. Therefore `~height` (where height is a runtime int) can
+    //   only be expressed at the MC level via the 1.20.2+ function macro system,
+    //   which substitutes $(height) into the command text at call time.
+    //
+    //   Contrast with absolute coords: `tp(target, x, y, z)` where x/y/z are
+    //   plain ints — those become $(x) etc. as literal replacements, same mechanism,
+    //   but the distinction matters to callers: ~$(height) means "relative by height
+    //   blocks from current pos", not "teleport to absolute scoreboard value".
+    //
+    //   Example:
+    //     fn launch_up(target: selector, height: int) {
+    //       tp(target, ~0, ~height, ~0);   // "~height" parsed as rel_coord
+    //     }
+    //   Emits:  $tp $(target) ~0 ~$(height) ~0
+    //   Called: function ns:launch_up with storage rs:macro_args
     if (expr.kind === 'rel_coord' || expr.kind === 'local_coord') {
       const val = expr.value  // e.g. "~height" or "^depth"
       const prefix = val[0]   // ~ or ^

package/src/parser/index.ts

@@ -180,6 +180,10 @@ export class Parser {
         enums.push(this.parseEnumDecl())
       } else if (this.check('const')) {
         consts.push(this.parseConstDecl())
+      } else if (this.check('declare')) {
+        // Declaration-only stub (e.g. from builtins.d.mcrs) — parse and discard
+        this.advance() // consume 'declare'
+        this.parseDeclareStub()
       } else {
         declarations.push(this.parseFnDecl())
       }
@@ -311,6 +315,25 @@ export class Parser {
     return this.withLoc({ name, params, returnType, decorators, body }, fnToken)
   }
 
+  /** Parse a `declare fn name(params): returnType;` stub — no body, just discard. */
+  private parseDeclareStub(): void {
+    this.expect('fn')
+    this.expect('ident') // name
+    this.expect('(')
+    // consume params until ')'
+    let depth = 1
+    while (!this.check('eof') && depth > 0) {
+      const t = this.advance()
+      if (t.kind === '(') depth++
+      else if (t.kind === ')') depth--
+    }
+    // optional return type annotation `: type` or `-> type`
+    if (this.match(':') || this.match('->')) {
+      this.parseType()
+    }
+    this.match(';') // consume trailing semicolon
+  }
+
   private parseDecorators(): Decorator[] {
     const decorators: Decorator[] = []
 
@@ -645,17 +668,29 @@ export class Parser {
   private parseForRangeStmt(forToken: Token): Stmt {
     const varName = this.expect('ident').value
     this.expect('in')
-    const rangeToken = this.expect('range_lit')
-    const range = this.parseRangeValue(rangeToken.value)
 
-    const start: Expr = this.withLoc(
-      { kind: 'int_lit', value: range.min ?? 0 },
-      rangeToken
-    )
-    const end: Expr = this.withLoc(
-      { kind: 'int_lit', value: range.max ?? 0 },
-      rangeToken
-    )
+    let start: Expr
+    let end: Expr
+
+    if (this.check('range_lit')) {
+      // Literal range: 0..10, 0..count, 0..=9
+      const rangeToken = this.advance()
+      const range = this.parseRangeValue(rangeToken.value)
+      start = this.withLoc({ kind: 'int_lit', value: range.min ?? 0 }, rangeToken)
+      if (range.max !== null && range.max !== undefined) {
+        // Fully numeric: 0..10
+        end = this.withLoc({ kind: 'int_lit', value: range.max }, rangeToken)
+      } else {
+        // Open-ended: "0.." — parse the end expression from next tokens
+        end = this.parseUnaryExpr()
+      }
+    } else {
+      // Dynamic range: expr..expr (e.g. start..end) — not yet supported
+      // Fall back to: parse as int_lit 0..0 (safe default)
+      start = this.withLoc({ kind: 'int_lit', value: 0 }, this.peek())
+      end   = this.withLoc({ kind: 'int_lit', value: 0 }, this.peek())
+      this.error('Dynamic range start requires a literal integer (e.g. 0..count)')
+    }
 
     const body = this.parseBlock()
     return this.withLoc({ kind: 'for_range', varName, start, end, body }, forToken)
@@ -1237,6 +1272,20 @@ export class Parser {
   }
 
   private parseLiteralExpr(): LiteralExpr {
+    // Support negative literals: -5, -3.14
+    if (this.check('-')) {
+      this.advance()
+      const token = this.peek()
+      if (token.kind === 'int_lit') {
+        this.advance()
+        return this.withLoc({ kind: 'int_lit', value: -Number(token.value) }, token)
+      }
+      if (token.kind === 'float_lit') {
+        this.advance()
+        return this.withLoc({ kind: 'float_lit', value: -Number(token.value) }, token)
+      }
+      this.error('Expected number after unary -')
+    }
     const expr = this.parsePrimaryExpr()
     if (
       expr.kind === 'int_lit' ||