redscript-mc 2.1.0 → 2.2.1

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__/schedule.test.js

@@ -95,4 +95,109 @@ describe('@schedule decorator', () => {
         expect(startFn).toContain('function test:_schedule_after_one_second');
     });
 });
+describe('setTimeout / setInterval codegen', () => {
+    test('setTimeout lifts lambda to __timeout_callback_0 and schedules it', () => {
+        const source = `
+      fn start() {
+        setTimeout(20, () => {
+          say("later");
+        });
+      }
+    `;
+        const result = (0, compile_1.compile)(source, { namespace: 'ns' });
+        const startFn = getFile(result.files, 'start.mcfunction');
+        const cbFn = getFile(result.files, '__timeout_callback_0.mcfunction');
+        expect(startFn).toContain('schedule function ns:__timeout_callback_0 20t');
+        expect(cbFn).toBeDefined();
+        expect(cbFn).toContain('say later');
+    });
+    test('setInterval lambda reschedules itself at the end', () => {
+        const source = `
+      fn start() {
+        setInterval(10, () => {
+          say("tick");
+        });
+      }
+    `;
+        const result = (0, compile_1.compile)(source, { namespace: 'ns' });
+        const cbFn = getFile(result.files, '__timeout_callback_0.mcfunction');
+        expect(cbFn).toBeDefined();
+        expect(cbFn).toContain('schedule function ns:__timeout_callback_0 10t');
+    });
+    test('multiple setTimeout calls get unique callback names', () => {
+        const source = `
+      fn start() {
+        setTimeout(10, () => { say("a"); });
+        setTimeout(20, () => { say("b"); });
+      }
+    `;
+        const result = (0, compile_1.compile)(source, { namespace: 'ns' });
+        const cb0 = getFile(result.files, '__timeout_callback_0.mcfunction');
+        const cb1 = getFile(result.files, '__timeout_callback_1.mcfunction');
+        expect(cb0).toBeDefined();
+        expect(cb1).toBeDefined();
+        expect(cb0).toContain('say a');
+        expect(cb1).toContain('say b');
+    });
+});
+const TIMER_STRUCT = `
+struct Timer {
+    _id: int,
+    _duration: int
+}
+impl Timer {
+    fn new(duration: int) -> Timer {
+        return { _id: 0, _duration: duration };
+    }
+    fn start(self) {}
+    fn pause(self) {}
+    fn reset(self) {}
+    fn tick(self) {}
+    fn done(self) -> bool { return false; }
+    fn elapsed(self) -> int { return 0; }
+}
+`;
+describe('Timer static allocation codegen', () => {
+    test('Timer::new() initializes unique scoreboard slots', () => {
+        const source = TIMER_STRUCT + `
+fn init() {
+    let t: Timer = Timer::new(20);
+}
+`;
+        const result = (0, compile_1.compile)(source, { namespace: 'ns' });
+        const initFn = getFile(result.files, 'init.mcfunction');
+        expect(initFn).toContain('scoreboard players set __timer_0_ticks ns 0');
+        expect(initFn).toContain('scoreboard players set __timer_0_active ns 0');
+    });
+    test('Timer.start() inlines to scoreboard set active=1', () => {
+        const source = TIMER_STRUCT + `
+fn init() {
+    let t: Timer = Timer::new(20);
+    t.start();
+}
+`;
+        const result = (0, compile_1.compile)(source, { namespace: 'ns' });
+        const initFn = getFile(result.files, 'init.mcfunction');
+        expect(initFn).toContain('scoreboard players set __timer_0_active ns 1');
+        expect(initFn).not.toContain('function ns:timer/start');
+    });
+    test('two Timer::new() calls get distinct IDs', () => {
+        const source = TIMER_STRUCT + `
+fn init() {
+    let t0: Timer = Timer::new(10);
+    let t1: Timer = Timer::new(20);
+    t0.start();
+    t1.start();
+}
+`;
+        const result = (0, compile_1.compile)(source, { namespace: 'ns' });
+        const initFn = getFile(result.files, 'init.mcfunction');
+        // Both timers initialized
+        expect(initFn).toContain('__timer_0_ticks');
+        expect(initFn).toContain('__timer_1_ticks');
+        // Both started with unique slot names
+        expect(initFn).toContain('scoreboard players set __timer_0_active ns 1');
+        expect(initFn).toContain('scoreboard players set __timer_1_active ns 1');
+    });
+});
 //# sourceMappingURL=schedule.test.js.map

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/__tests__/typechecker.test.js

@@ -246,6 +246,69 @@ fn test() {
             expect(errors.length).toBeGreaterThan(0);
             expect(errors[0].message).toContain('Return type mismatch: expected void, got int');
         });
+        it('rejects setTimeout inside a loop', () => {
+            const errors = typeCheck(`
+fn test() {
+    while (true) {
+        setTimeout(20, () => { say("x"); });
+    }
+}
+`);
+            expect(errors.length).toBeGreaterThan(0);
+            expect(errors[0].message).toContain('cannot be called inside a loop');
+        });
+        it('rejects setTimeout inside an if body', () => {
+            const errors = typeCheck(`
+fn test() {
+    if (true) {
+        setTimeout(20, () => { say("x"); });
+    }
+}
+`);
+            expect(errors.length).toBeGreaterThan(0);
+            expect(errors[0].message).toContain('cannot be called inside an if/else body');
+        });
+        it('rejects setInterval inside a loop', () => {
+            const errors = typeCheck(`
+fn test() {
+    while (true) {
+        setInterval(20, () => { say("x"); });
+    }
+}
+`);
+            expect(errors.length).toBeGreaterThan(0);
+            expect(errors[0].message).toContain('cannot be called inside a loop');
+        });
+        it('rejects Timer::new() inside a loop', () => {
+            const errors = typeCheck(`
+struct Timer { _id: int, _duration: int }
+impl Timer {
+    fn new(duration: int) -> Timer { return { _id: 0, _duration: duration }; }
+}
+fn test() {
+    while (true) {
+        let t: Timer = Timer::new(10);
+    }
+}
+`);
+            expect(errors.length).toBeGreaterThan(0);
+            expect(errors[0].message).toContain('Timer::new() cannot be called inside a loop');
+        });
+        it('rejects Timer::new() inside an if body', () => {
+            const errors = typeCheck(`
+struct Timer { _id: int, _duration: int }
+impl Timer {
+    fn new(duration: int) -> Timer { return { _id: 0, _duration: duration }; }
+}
+fn test() {
+    if (true) {
+        let t: Timer = Timer::new(10);
+    }
+}
+`);
+            expect(errors.length).toBeGreaterThan(0);
+            expect(errors[0].message).toContain('Timer::new() cannot be called inside an if/else body');
+        });
         it('allows impl instance methods with inferred self type', () => {
             const errors = typeCheck(`
 struct Timer { duration: int }

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);
@@ -116,6 +116,7 @@ function compile(source, options = {}) {
         const coroResult = (0, coroutine_1.coroutineTransform)(mirOpt, coroutineInfos);
         const mirFinal = coroResult.module;
         tickFunctions.push(...coroResult.generatedTickFunctions);
+        warnings.push(...coroResult.warnings);
         // Stage 5: MIR → LIR
         const lir = (0, lower_3.lowerToLIR)(mirFinal);
         // Stage 6: LIR optimization

package/dist/src/emit/index.js

@@ -152,7 +152,9 @@ function emitInstr(instr, ns, obj, mcVersion) {
             return `execute unless score ${slot(instr.a)} ${cmpToMC(instr.op)} ${slot(instr.b)} run function ${instr.fn}`;
         case 'call_context': {
             const subcmds = instr.subcommands.map(emitSubcmd).join(' ');
-            return `execute ${subcmds} run function ${instr.fn}`;
+            return subcmds
+                ? `execute ${subcmds} run function ${instr.fn}`
+                : `function ${instr.fn}`;
         }
         case 'return_value':
             return `scoreboard players operation $ret ${instr.slot.obj} = ${slot(instr.slot)}`;

package/dist/src/lir/lower.js

@@ -275,6 +275,32 @@ function lowerInstrInner(instr, fn, ctx, instrs) {
             });
             break;
         }
+        case 'score_read': {
+            // execute store result score $dst __obj run scoreboard players get <player> <obj>
+            const dst = ctx.slot(instr.dst);
+            instrs.push({
+                kind: 'store_cmd_to_score',
+                dst,
+                cmd: { kind: 'raw', cmd: `scoreboard players get ${instr.player} ${instr.obj}` },
+            });
+            break;
+        }
+        case 'score_write': {
+            // Write a value to a vanilla MC scoreboard objective
+            if (instr.src.kind === 'const') {
+                instrs.push({ kind: 'raw', cmd: `scoreboard players set ${instr.player} ${instr.obj} ${instr.src.value}` });
+            }
+            else {
+                // execute store result score <player> <obj> run scoreboard players get $src __ns
+                const srcSlot = operandToSlot(instr.src, ctx, instrs);
+                instrs.push({
+                    kind: 'store_cmd_to_score',
+                    dst: { player: instr.player, obj: instr.obj },
+                    cmd: { kind: 'raw', cmd: `scoreboard players get ${srcSlot.player} ${srcSlot.obj}` },
+                });
+            }
+            break;
+        }
         case 'call': {
             // Set parameter slots $p0, $p1, ...
             for (let i = 0; i < instr.args.length; i++) {

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) {