redscript-mc 2.1.0 → 2.1.1

package/README.md

@@ -192,6 +192,22 @@ fn on_diamond() {
 fn on_death() {
     scoreboard_add(@s, #deaths, 1);
 }
+
+// Delay execution by N ticks (20t = 1 second)
+@schedule(ticks=20)
+fn after_one_second(): void {
+    title(@a, "One second later!");
+}
+
+// Spread a heavy loop across multiple ticks (batch=N iterations/tick)
+@coroutine(batch=50, onDone=all_done)
+fn process_all(): void {
+    let i: int = 0;
+    while (i < 1000) {
+        // work spread over ~20 ticks instead of lagging one tick
+        i = i + 1;
+    }
+}
 ```
 
 #### Control Flow
@@ -316,6 +332,26 @@ fn show_fib() {
 
 ---
 
+### Examples
+
+The `examples/` directory contains ready-to-compile demos:
+
+| File | What it shows |
+|---|---|
+| `readme-demo.mcrs` | Real-time sine wave particles — `@tick`, `foreach`, f-strings, math stdlib |
+| `math-showcase.mcrs` | All stdlib math modules: trig, vectors, BigInt, fractals |
+| `showcase.mcrs` | Full feature tour: structs, enums, `match`, lambdas, `@tick`/`@load` |
+| `coroutine-demo.mcrs` | `@coroutine(batch=50)` — spread 1000 iterations across ~20 ticks |
+| `enum-demo.mcrs` | Enum state machine: NPC AI cycling Idle → Moving → Attacking with `match` |
+| `scheduler-demo.mcrs` | `@schedule(ticks=20)` — delayed events, chained schedules |
+
+Compile any example:
+```bash
+node dist/cli.js compile examples/coroutine-demo.mcrs -o ~/mc-server/datapacks/demo --namespace demo
+```
+
+---
+
 ### Further Reading
 
 | | |

package/dist/src/__tests__/lsp.test.js

@@ -10,6 +10,7 @@ const lexer_1 = require("../lexer");
 const parser_1 = require("../parser");
 const typechecker_1 = require("../typechecker");
 const diagnostics_1 = require("../diagnostics");
+const metadata_1 = require("../builtins/metadata");
 // ---------------------------------------------------------------------------
 // Helpers mirrored from lsp/server.ts (tested independently)
 // ---------------------------------------------------------------------------
@@ -231,6 +232,81 @@ fn anotherFn(x: int): int { return x; }
     });
 });
 // ---------------------------------------------------------------------------
+// Hover — builtin functions
+// ---------------------------------------------------------------------------
+const DECORATOR_DOCS = {
+    tick: 'Runs every MC game tick (~20 Hz). No arguments.',
+    load: 'Runs on `/reload`. Use for initialization logic.',
+    coroutine: 'Splits loops into tick-spread continuations. Arg: `batch=N` (steps per tick, default 1).',
+    schedule: 'Schedules the function to run after N ticks. Arg: `ticks=N`.',
+    on_trigger: 'Runs when a trigger scoreboard objective is set by a player. Arg: trigger name.',
+    keep: 'Prevents the compiler from dead-code-eliminating this function.',
+    on: 'Generic event handler decorator.',
+    on_advancement: 'Runs when a player earns an advancement. Arg: advancement id.',
+    on_craft: 'Runs when a player crafts an item. Arg: item id.',
+    on_death: 'Runs when a player dies.',
+    on_join_team: 'Runs when a player joins a team. Arg: team name.',
+    on_login: 'Runs when a player logs in.',
+};
+describe('LSP hover — builtin functions', () => {
+    it('has metadata for say', () => {
+        const b = metadata_1.BUILTIN_METADATA['say'];
+        expect(b).toBeDefined();
+        expect(b.params.length).toBeGreaterThan(0);
+        expect(b.returns).toBe('void');
+        expect(b.doc).toBeTruthy();
+    });
+    it('has metadata for kill', () => {
+        const b = metadata_1.BUILTIN_METADATA['kill'];
+        expect(b).toBeDefined();
+        expect(b.returns).toBe('void');
+    });
+    it('has metadata for tellraw', () => {
+        const b = metadata_1.BUILTIN_METADATA['tellraw'];
+        expect(b).toBeDefined();
+        const paramStr = b.params.map(p => `${p.name}: ${p.type}${p.required ? '' : '?'}`).join(', ');
+        const sig = `fn ${b.name}(${paramStr}): ${b.returns}`;
+        expect(sig).toMatch(/^fn tellraw/);
+        expect(sig).toContain('target');
+    });
+    it('formats builtin hover markdown', () => {
+        const b = metadata_1.BUILTIN_METADATA['particle'];
+        expect(b).toBeDefined();
+        const paramStr = b.params.map(p => `${p.name}: ${p.type}${p.required ? '' : '?'}`).join(', ');
+        const sig = `fn ${b.name}(${paramStr}): ${b.returns}`;
+        const markdown = `\`\`\`redscript\n${sig}\n\`\`\`\n${b.doc}`;
+        expect(markdown).toContain('```redscript');
+        expect(markdown).toContain('fn particle');
+        expect(markdown).toContain(b.doc);
+    });
+});
+// ---------------------------------------------------------------------------
+// Hover — decorators
+// ---------------------------------------------------------------------------
+describe('LSP hover — decorators', () => {
+    it('has docs for @tick', () => {
+        expect(DECORATOR_DOCS['tick']).toContain('tick');
+    });
+    it('has docs for @load', () => {
+        expect(DECORATOR_DOCS['load']).toContain('reload');
+    });
+    it('has docs for @coroutine', () => {
+        expect(DECORATOR_DOCS['coroutine']).toContain('batch');
+    });
+    it('has docs for @schedule', () => {
+        expect(DECORATOR_DOCS['schedule']).toContain('ticks');
+    });
+    it('has docs for @on_trigger', () => {
+        expect(DECORATOR_DOCS['on_trigger']).toContain('trigger');
+    });
+    it('formats decorator hover markdown', () => {
+        const name = 'tick';
+        const doc = DECORATOR_DOCS[name];
+        const markdown = `**@${name}** — ${doc}`;
+        expect(markdown).toBe(`**@tick** — ${DECORATOR_DOCS['tick']}`);
+    });
+});
+// ---------------------------------------------------------------------------
 // Server module import (smoke test — does not start stdio)
 // ---------------------------------------------------------------------------
 describe('LSP server module', () => {

package/dist/src/__tests__/mc-syntax.test.js

@@ -38,7 +38,7 @@ const path = __importStar(require("path"));
 const compile_1 = require("../compile");
 const mc_validator_1 = require("../mc-validator");
 const FIXTURE_PATH = path.join(__dirname, 'fixtures', 'mc-commands-1.21.4.json');
-const EXAMPLES = ['counter', 'arena', 'shop', 'quiz', 'turret'];
+const EXAMPLES = ['shop', 'quiz', 'turret'];
 function getCommands(source, namespace = 'test') {
     const result = (0, compile_1.compile)(source, { namespace });
     expect(result.success).toBe(true);
@@ -56,11 +56,6 @@ function validateSource(validator, source, namespace) {
 }
 describe('MC Command Syntax Validation', () => {
     const validator = new mc_validator_1.MCCommandValidator(FIXTURE_PATH);
-    test('counter example generates valid MC commands', () => {
-        const src = fs.readFileSync(path.join(__dirname, '..', 'examples', 'counter.mcrs'), 'utf-8');
-        const errors = validateSource(validator, src, 'counter');
-        expect(errors).toHaveLength(0);
-    });
     EXAMPLES.forEach(name => {
         test(`${name}.mcrs generates valid MC commands`, () => {
             const src = fs.readFileSync(path.join(__dirname, '..', 'examples', `${name}.mcrs`), 'utf-8');

package/dist/src/__tests__/stdlib-include.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/__tests__/stdlib-include.test.js

@@ -0,0 +1,86 @@
+"use strict";
+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 path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const compile_1 = require("../emit/compile");
+describe('stdlib include path', () => {
+    it('import "stdlib/math" resolves to the stdlib math module', () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rs-stdlib-'));
+        const mainPath = path.join(tempDir, 'main.mcrs');
+        fs.writeFileSync(mainPath, 'import "stdlib/math";\nfn main() { let x: int = abs(-5); }\n');
+        const source = fs.readFileSync(mainPath, 'utf-8');
+        const result = (0, compile_1.compile)(source, { namespace: 'test', filePath: mainPath });
+        expect(result.files.some(f => f.path.includes('abs'))).toBe(true);
+    });
+    it('import "stdlib/math.mcrs" also resolves (explicit extension)', () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rs-stdlib-'));
+        const mainPath = path.join(tempDir, 'main.mcrs');
+        fs.writeFileSync(mainPath, 'import "stdlib/math.mcrs";\nfn main() { let x: int = abs(-5); }\n');
+        const source = fs.readFileSync(mainPath, 'utf-8');
+        const result = (0, compile_1.compile)(source, { namespace: 'test', filePath: mainPath });
+        expect(result.files.some(f => f.path.includes('abs'))).toBe(true);
+    });
+    it('import "stdlib/vec" resolves to the stdlib vec module', () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rs-stdlib-'));
+        const mainPath = path.join(tempDir, 'main.mcrs');
+        fs.writeFileSync(mainPath, 'import "stdlib/vec";\nfn main() { let d: int = dot2d(1, 2, 3, 4); }\n');
+        const source = fs.readFileSync(mainPath, 'utf-8');
+        const result = (0, compile_1.compile)(source, { namespace: 'test', filePath: mainPath });
+        expect(result.files.some(f => f.path.includes('dot2d'))).toBe(true);
+    });
+    it('non-existent stdlib module gives a clear error', () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rs-stdlib-'));
+        const mainPath = path.join(tempDir, 'main.mcrs');
+        fs.writeFileSync(mainPath, 'import "stdlib/nonexistent";\nfn main() {}\n');
+        const source = fs.readFileSync(mainPath, 'utf-8');
+        expect(() => (0, compile_1.compile)(source, { namespace: 'test', filePath: mainPath }))
+            .toThrow(/Cannot import/);
+    });
+    it('--include flag allows importing from custom directory', () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rs-include-'));
+        const libDir = path.join(tempDir, 'mylibs');
+        fs.mkdirSync(libDir);
+        const mainPath = path.join(tempDir, 'main.mcrs');
+        const libPath = path.join(libDir, 'helpers.mcrs');
+        fs.writeFileSync(libPath, 'fn triple(x: int) -> int { return x + x + x; }\n');
+        fs.writeFileSync(mainPath, 'import "helpers";\nfn main() { let x: int = triple(3); }\n');
+        const source = fs.readFileSync(mainPath, 'utf-8');
+        const result = (0, compile_1.compile)(source, { namespace: 'test', filePath: mainPath, includeDirs: [libDir] });
+        expect(result.files.some(f => f.path.includes('triple'))).toBe(true);
+    });
+});
+//# sourceMappingURL=stdlib-include.test.js.map

package/dist/src/cli.js

@@ -89,6 +89,7 @@ Options:
   --mc-version <ver>     Target Minecraft version (default: 1.21). Affects codegen features.
                          e.g. --mc-version 1.20.2, --mc-version 1.19
   --lenient              Treat type errors as warnings instead of blocking compilation
+  --include <dir>        Add a directory to the import search path (repeatable)
   -h, --help             Show this help message
 `);
 }
@@ -210,6 +211,12 @@ function parseArgs(args) {
             result.lenient = true;
             i++;
         }
+        else if (arg === '--include') {
+            if (!result.includeDirs)
+                result.includeDirs = [];
+            result.includeDirs.push(args[++i]);
+            i++;
+        }
         else if (!result.command) {
             result.command = arg;
             i++;
@@ -229,7 +236,7 @@ function deriveNamespace(filePath) {
     // Convert to valid identifier: lowercase, replace non-alphanumeric with underscore
     return basename.toLowerCase().replace(/[^a-z0-9]/g, '_');
 }
-function compileCommand(file, output, namespace, sourceMap = false, mcVersionStr, lenient = false) {
+function compileCommand(file, output, namespace, sourceMap = false, mcVersionStr, lenient = false, includeDirs) {
     // Read source file
     if (!fs.existsSync(file)) {
         console.error(`Error: File not found: ${file}`);
@@ -247,7 +254,7 @@ function compileCommand(file, output, namespace, sourceMap = false, mcVersionStr
     }
     const source = fs.readFileSync(file, 'utf-8');
     try {
-        const result = (0, index_1.compile)(source, { namespace, filePath: file, generateSourceMap: sourceMap, mcVersion, lenient });
+        const result = (0, index_1.compile)(source, { namespace, filePath: file, generateSourceMap: sourceMap, mcVersion, lenient, includeDirs });
         for (const w of result.warnings) {
             console.error(`Warning: ${w}`);
         }
@@ -411,7 +418,7 @@ async function main() {
             {
                 const namespace = parsed.namespace ?? deriveNamespace(parsed.file);
                 const output = parsed.output ?? './dist';
-                compileCommand(parsed.file, output, namespace, parsed.sourceMap, parsed.mcVersionStr, parsed.lenient);
+                compileCommand(parsed.file, output, namespace, parsed.sourceMap, parsed.mcVersionStr, parsed.lenient, parsed.includeDirs);
             }
             break;
         case 'watch':

package/dist/src/compile.d.ts

@@ -32,6 +32,7 @@ export declare function resolveSourceLine(combinedLine: number, ranges: SourceRa
 interface PreprocessOptions {
     filePath?: string;
     seen?: Set<string>;
+    includeDirs?: string[];
 }
 export declare function preprocessSourceWithMetadata(source: string, options?: PreprocessOptions): PreprocessedSource;
 export declare function preprocessSource(source: string, options?: PreprocessOptions): string;

package/dist/src/compile.js

@@ -75,6 +75,31 @@ function isLibrarySource(source) {
     }
     return false;
 }
+/** Resolve an import specifier to an absolute file path, trying multiple locations. */
+function resolveImportPath(spec, fromFile, includeDirs) {
+    const candidates = spec.endsWith('.mcrs') ? [spec] : [spec, spec + '.mcrs'];
+    for (const candidate of candidates) {
+        // 1. Relative to the importing file
+        const rel = path.resolve(path.dirname(fromFile), candidate);
+        if (fs.existsSync(rel))
+            return rel;
+        // 2. stdlib directory (package root / src / stdlib)
+        //    Strip leading 'stdlib/' prefix so `import "stdlib/math"` resolves to
+        //    <stdlibDir>/math.mcrs rather than <stdlibDir>/stdlib/math.mcrs.
+        const stdlibDir = path.resolve(__dirname, '..', 'src', 'stdlib');
+        const stdlibCandidate = candidate.replace(/^stdlib\//, '');
+        const stdlib = path.resolve(stdlibDir, stdlibCandidate);
+        if (fs.existsSync(stdlib))
+            return stdlib;
+        // 3. Extra include dirs
+        for (const dir of includeDirs) {
+            const extra = path.resolve(dir, candidate);
+            if (fs.existsSync(extra))
+                return extra;
+        }
+    }
+    return null;
+}
 function countLines(source) {
     return source === '' ? 0 : source.split('\n').length;
 }
@@ -88,6 +113,7 @@ function offsetRanges(ranges, lineOffset) {
 function preprocessSourceWithMetadata(source, options = {}) {
     const { filePath } = options;
     const seen = options.seen ?? new Set();
+    const includeDirs = options.includeDirs ?? [];
     if (filePath) {
         seen.add(path.resolve(filePath));
     }
@@ -105,27 +131,24 @@ function preprocessSourceWithMetadata(source, options = {}) {
             if (!filePath) {
                 throw new diagnostics_1.DiagnosticError('ParseError', 'Import statements require a file path', { line: i + 1, col: 1 }, lines);
             }
-            const importPath = path.resolve(path.dirname(filePath), match[1]);
+            const importPath = resolveImportPath(match[1], filePath, includeDirs);
+            if (!importPath) {
+                throw new diagnostics_1.DiagnosticError('ParseError', `Cannot import '${match[1]}'`, { file: filePath, line: i + 1, col: 1 }, lines);
+            }
             if (!seen.has(importPath)) {
                 seen.add(importPath);
-                let importedSource;
-                try {
-                    importedSource = fs.readFileSync(importPath, 'utf-8');
-                }
-                catch {
-                    throw new diagnostics_1.DiagnosticError('ParseError', `Cannot import '${match[1]}'`, { file: filePath, line: i + 1, col: 1 }, lines);
-                }
+                const importedSource = fs.readFileSync(importPath, 'utf-8');
                 if (isLibrarySource(importedSource)) {
                     // Library file: parse separately so its functions are DCE-eligible.
                     // Also collect any transitive library imports inside it.
-                    const nested = preprocessSourceWithMetadata(importedSource, { filePath: importPath, seen });
+                    const nested = preprocessSourceWithMetadata(importedSource, { filePath: importPath, seen, includeDirs });
                     libraryImports.push({ source: importedSource, filePath: importPath });
                     // Propagate transitive library imports (e.g. math.mcrs imports vec.mcrs)
                     if (nested.libraryImports)
                         libraryImports.push(...nested.libraryImports);
                 }
                 else {
-                    imports.push(preprocessSourceWithMetadata(importedSource, { filePath: importPath, seen }));
+                    imports.push(preprocessSourceWithMetadata(importedSource, { filePath: importPath, seen, includeDirs }));
                 }
             }
             continue;

package/dist/src/emit/compile.d.ts

@@ -19,6 +19,8 @@ export interface CompileOptions {
      * Use for gradual migration or testing with existing codebases that have type errors.
      */
     lenient?: boolean;
+    /** Extra directories to search when resolving imports (in addition to relative and stdlib). */
+    includeDirs?: string[];
 }
 export interface CompileResult {
     files: DatapackFile[];

package/dist/src/emit/compile.js

@@ -22,10 +22,10 @@ const budget_1 = require("../lir/budget");
 const mc_version_1 = require("../types/mc-version");
 const typechecker_1 = require("../typechecker");
 function compile(source, options = {}) {
-    const { namespace = 'redscript', filePath, generateSourceMap = false, mcVersion = mc_version_1.DEFAULT_MC_VERSION, lenient = false } = options;
+    const { namespace = 'redscript', filePath, generateSourceMap = false, mcVersion = mc_version_1.DEFAULT_MC_VERSION, lenient = false, includeDirs } = options;
     const warnings = [];
     // Preprocess: resolve import directives, merge imported sources
-    const preprocessed = (0, compile_1.preprocessSourceWithMetadata)(source, { filePath });
+    const preprocessed = (0, compile_1.preprocessSourceWithMetadata)(source, { filePath, includeDirs });
     const processedSource = preprocessed.source;
     // Stage 1: Lex + Parse → AST
     const lexer = new lexer_1.Lexer(processedSource);

package/dist/src/lsp/server.js

@@ -16,6 +16,7 @@ const lexer_1 = require("../lexer");
 const parser_1 = require("../parser");
 const typechecker_1 = require("../typechecker");
 const diagnostics_1 = require("../diagnostics");
+const metadata_1 = require("../builtins/metadata");
 // ---------------------------------------------------------------------------
 // Connection and document manager
 // ---------------------------------------------------------------------------
@@ -82,6 +83,23 @@ function toDiagnostic(err) {
     };
 }
 // ---------------------------------------------------------------------------
+// Decorator hover docs
+// ---------------------------------------------------------------------------
+const DECORATOR_DOCS = {
+    tick: 'Runs every MC game tick (~20 Hz). No arguments.',
+    load: 'Runs on `/reload`. Use for initialization logic.',
+    coroutine: 'Splits loops into tick-spread continuations. Arg: `batch=N` (steps per tick, default 1).',
+    schedule: 'Schedules the function to run after N ticks. Arg: `ticks=N`.',
+    on_trigger: 'Runs when a trigger scoreboard objective is set by a player. Arg: trigger name.',
+    keep: 'Prevents the compiler from dead-code-eliminating this function.',
+    on: 'Generic event handler decorator.',
+    on_advancement: 'Runs when a player earns an advancement. Arg: advancement id.',
+    on_craft: 'Runs when a player crafts an item. Arg: item id.',
+    on_death: 'Runs when a player dies.',
+    on_join_team: 'Runs when a player joins a team. Arg: team name.',
+    on_login: 'Runs when a player logs in.',
+};
+// ---------------------------------------------------------------------------
 // Hover helpers
 // ---------------------------------------------------------------------------
 /** Find the word at a position in a text. */
@@ -239,9 +257,42 @@ connection.onHover((params) => {
     const program = cached?.program ?? null;
     if (!program)
         return null;
+    // Check if cursor is on a decorator (@tick, @load, etc.)
+    const lines = source.split('\n');
+    const lineText = lines[params.position.line] ?? '';
+    const decoratorMatch = lineText.match(/@([a-zA-Z_][a-zA-Z0-9_]*)/);
+    if (decoratorMatch) {
+        const ch = params.position.character;
+        const atIdx = lineText.indexOf('@');
+        const decoratorEnd = atIdx + 1 + decoratorMatch[1].length;
+        if (ch >= atIdx && ch <= decoratorEnd) {
+            const decoratorName = decoratorMatch[1];
+            const decoratorDoc = DECORATOR_DOCS[decoratorName];
+            if (decoratorDoc) {
+                const content = {
+                    kind: node_1.MarkupKind.Markdown,
+                    value: `**@${decoratorName}** — ${decoratorDoc}`,
+                };
+                return { contents: content };
+            }
+        }
+    }
     const word = wordAt(source, params.position);
     if (!word)
         return null;
+    // Check builtins
+    const builtin = metadata_1.BUILTIN_METADATA[word];
+    if (builtin) {
+        const paramStr = builtin.params
+            .map(p => `${p.name}: ${p.type}${p.required ? '' : '?'}`)
+            .join(', ');
+        const sig = `fn ${builtin.name}(${paramStr}): ${builtin.returns}`;
+        const content = {
+            kind: node_1.MarkupKind.Markdown,
+            value: `\`\`\`redscript\n${sig}\n\`\`\`\n${builtin.doc}`,
+        };
+        return { contents: content };
+    }
     // Check if it's a known function
     const fn = findFunction(program, word);
     if (fn) {

package/editors/vscode/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "redscript-vscode",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "redscript-vscode",
-      "version": "1.2.8",
+      "version": "1.2.9",
       "license": "MIT",
       "dependencies": {
         "redscript": "file:../../",
@@ -24,7 +24,7 @@
     },
     "../..": {
       "name": "redscript-mc",
-      "version": "2.1.0",
+      "version": "2.1.1",
       "license": "MIT",
       "dependencies": {
         "vscode-languageserver": "^9.0.1",

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.2.8",
+  "version": "1.2.9",
   "publisher": "bkmashiro",
   "icon": "icon.png",
   "license": "MIT",

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

@@ -8,6 +8,7 @@
       "patterns": [
         { "include": "#comments" },
         { "include": "#decorators" },
+        { "include": "#fstring" },
         { "include": "#string-interpolation" },
         { "include": "#strings" },
         { "include": "#keywords" },
@@ -91,6 +92,39 @@
       ]
     },
 
+    "fstring": {
+      "comment": "f-string: f\"Hello {name}\" — f prefix gets special color, {expr} highlighted",
+      "begin": "(f)(\")",
+      "beginCaptures": {
+        "1": { "name": "storage.type.string.redscript" },
+        "2": { "name": "punctuation.definition.string.begin.redscript" }
+      },
+      "end": "\"",
+      "endCaptures": {
+        "0": { "name": "punctuation.definition.string.end.redscript" }
+      },
+      "name": "string.interpolated.redscript",
+      "patterns": [
+        {
+          "begin": "\\{",
+          "end": "\\}",
+          "beginCaptures": { "0": { "name": "punctuation.definition.interpolation.begin.redscript" } },
+          "endCaptures":   { "0": { "name": "punctuation.definition.interpolation.end.redscript" } },
+          "contentName": "meta.interpolation.redscript",
+          "patterns": [
+            { "include": "#selectors" },
+            { "include": "#numbers" },
+            { "include": "#fn-call" },
+            {
+              "name": "variable.other.redscript",
+              "match": "[a-zA-Z_][a-zA-Z0-9_]*"
+            }
+          ]
+        },
+        { "name": "constant.character.escape.redscript", "match": "\\\\." }
+      ]
+    },
+
     "string-interpolation": {
       "comment": "Interpolated string with ${expr} — highlight the expression inside",
       "begin": "\"(?=[^\"]*\\$\\{)",

package/examples/coroutine-demo.mcrs

@@ -0,0 +1,50 @@
+// coroutine-demo.mcrs — Spread particle generation across multiple ticks
+//
+// @coroutine(batch=50) processes 50 iterations per tick, so 1000 total
+// iterations take ~20 ticks instead of lagging one tick.
+//
+// Usage:
+//   /function demo:start_particle_wave   begin the wave
+//   /function demo:stop_particle_wave    cancel the wave
+
+import "../src/stdlib/math.mcrs"
+
+let wave_running: bool = false;
+
+@load
+fn init() {
+    wave_running = false;
+}
+
+// Spread 1000 iterations across ~20 ticks (50 per tick)
+@coroutine(batch=50, onDone=wave_done)
+fn generate_wave(): void {
+    let i: int = 0;
+    while (i < 1000) {
+        let angle: int = (i * 360) / 1000;
+        let px: int = sin_fixed(angle);
+        let py: int = cos_fixed(angle);
+        raw("particle minecraft:end_rod ^${px} ^100 ^${py} 0 0 0 0 1 force @a");
+        i = i + 1;
+    }
+}
+
+fn wave_done(): void {
+    wave_running = false;
+    title(@a, "Wave complete!");
+}
+
+fn start_particle_wave(): void {
+    if (wave_running) {
+        tell(@a, "Wave already running.");
+        return;
+    }
+    wave_running = true;
+    title(@a, "Starting particle wave...");
+    generate_wave();
+}
+
+fn stop_particle_wave(): void {
+    wave_running = false;
+    title(@a, "Wave stopped.");
+}