redscript-mc 1.2.16 → 1.2.18

package/dist/builtins/metadata.js

@@ -929,15 +929,12 @@ exports.BUILTIN_METADATA = {
  */
 function builtinToDeclaration(def) {
     const lines = [];
-    // Doc comments
+    // Doc comments (English only)
     lines.push(`/// ${def.doc}`);
-    if (def.docZh) {
-        lines.push(`/// ${def.docZh}`);
-    }
     // Param docs
     for (const p of def.params) {
-        const opt = p.required ? '' : '?';
-        lines.push(`/// @param ${p.name}${opt} ${p.doc}`);
+        const optTag = p.required ? '' : ' (optional)';
+        lines.push(`/// @param ${p.name} ${p.doc}${optTag}`);
     }
     // Returns
     if (def.returns !== 'void') {
@@ -947,15 +944,9 @@ function builtinToDeclaration(def) {
     for (const ex of def.examples) {
         lines.push(`/// @example ${ex.split('\n')[0]}`);
     }
-    // Signature
+    // Signature - use default value syntax instead of ? for optional params
     const paramStrs = def.params.map(p => {
-        const opt = p.required ? '' : '?';
         let type = p.type;
-        // Map to .d.mcrs types
-        if (type === 'selector')
-            type = 'selector';
-        if (type === 'BlockPos')
-            type = 'BlockPos';
         if (type === 'effect')
             type = 'string';
         if (type === 'sound')
@@ -970,9 +961,10 @@ function builtinToDeclaration(def) {
             type = 'string';
         if (type === 'nbt')
             type = 'string';
-        if (type === 'coord')
-            type = 'coord';
-        return `${p.name}${opt}: ${type}`;
+        if (!p.required && p.default !== undefined) {
+            return `${p.name}: ${type} = ${p.default}`;
+        }
+        return `${p.name}: ${type}`;
     });
     const retType = def.returns;
     lines.push(`declare fn ${def.name}(${paramStrs.join(', ')}): ${retType};`);

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',
@@ -222,6 +223,15 @@ class Lexer {
                     value += this.advance();
                 }
             }
+            // Check for ident (e.g. ~height → macro variable offset)
+            if (/[a-zA-Z_]/.test(this.peek())) {
+                let ident = '';
+                while (/[a-zA-Z0-9_]/.test(this.peek())) {
+                    ident += this.advance();
+                }
+                // Store as rel_coord with embedded ident: ~height
+                value += ident;
+            }
             this.addToken('rel_coord', value, startLine, startCol);
             return;
         }

package/dist/lowering/index.d.ts

@@ -60,6 +60,7 @@ export declare class Lowering {
      * used in a literal position), returns the param name; otherwise null.
      */
     private tryGetMacroParam;
+    private tryGetMacroParamByName;
     /**
      * Converts an expression to a string for use as a builtin arg.
      * If the expression is a macro param, returns `$(name)` and sets macroParam.

package/dist/lowering/index.js

@@ -354,6 +354,15 @@ class Lowering {
             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.
@@ -363,6 +372,38 @@ class Lowering {
         if (macroParam) {
             return { str: `$(${macroParam})`, macroParam };
         }
+        // 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 ^
+            const rest = val.slice(1);
+            // If rest is an identifier (not a number), treat as macro param
+            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) };
         }

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());
             }
@@ -213,12 +218,19 @@ class Parser {
     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);
+        // Infer type from value if not provided
+        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(); // consume 'let'
@@ -247,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')) {