redscript-mc 2.1.0 → 2.2.1

package/src/__tests__/lsp.test.ts

@@ -10,6 +10,7 @@ import { Parser } from '../parser'
 import { TypeChecker } from '../typechecker'
 import { DiagnosticError } from '../diagnostics'
 import type { Program, FnDecl, TypeNode } from '../ast/types'
+import { BUILTIN_METADATA } from '../builtins/metadata'
 
 // ---------------------------------------------------------------------------
 // Helpers mirrored from lsp/server.ts (tested independently)
@@ -255,6 +256,94 @@ fn anotherFn(x: int): int { return x; }
   })
 })
 
+// ---------------------------------------------------------------------------
+// Hover — builtin functions
+// ---------------------------------------------------------------------------
+
+const DECORATOR_DOCS: Record<string, string> = {
+  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 = 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 = BUILTIN_METADATA['kill']
+    expect(b).toBeDefined()
+    expect(b.returns).toBe('void')
+  })
+
+  it('has metadata for tellraw', () => {
+    const b = 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 = 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)
 // ---------------------------------------------------------------------------

package/src/__tests__/mc-integration.test.ts

@@ -82,13 +82,25 @@ beforeAll(async () => {
     return
   }
 
-  // ── Write fixtures + use safe reloadData (no /reload confirm) ───────
-  // counter.mcrs
-  if (fs.existsSync(path.join(__dirname, '../examples/counter.mcrs'))) {
-    writeFixture(fs.readFileSync(path.join(__dirname, '../examples/counter.mcrs'), 'utf-8'), 'counter')
+  // ── Clear stale minecraft tag files before writing fixtures ──────────
+  for (const tagFile of ['data/minecraft/tags/function/tick.json', 'data/minecraft/tags/function/load.json',
+                         'data/minecraft/tags/functions/tick.json', 'data/minecraft/tags/functions/load.json']) {
+    const p = path.join(DATAPACK_DIR, tagFile)
+    if (fs.existsSync(p)) fs.writeFileSync(p, JSON.stringify({ values: [] }, null, 2))
   }
-  if (fs.existsSync(path.join(__dirname, '../examples/world_manager.mcrs'))) {
-    writeFixture(fs.readFileSync(path.join(__dirname, '../examples/world_manager.mcrs'), 'utf-8'), 'world_manager')
+
+  // ── Write fixtures + use safe reloadData (no /reload confirm) ───────
+  // counter.mcrs (use fixtures if examples was removed)
+  const counterSrc = fs.existsSync(path.join(__dirname, '../examples/counter.mcrs'))
+    ? fs.readFileSync(path.join(__dirname, '../examples/counter.mcrs'), 'utf-8')
+    : fs.readFileSync(path.join(__dirname, 'fixtures/counter.mcrs'), 'utf-8')
+  writeFixture(counterSrc, 'counter')
+  // world_manager.mcrs
+  const wmPath = fs.existsSync(path.join(__dirname, '../examples/world_manager.mcrs'))
+    ? path.join(__dirname, '../examples/world_manager.mcrs')
+    : path.join(__dirname, '../src/examples/world_manager.mcrs')
+  if (fs.existsSync(wmPath)) {
+    writeFixture(fs.readFileSync(wmPath, 'utf-8'), 'world_manager')
   }
   writeFixture(`
     @tick
@@ -402,9 +414,9 @@ describe('MC Integration Tests', () => {
     
     await mc.fullReset({ clearArea: false, killEntities: true, resetScoreboards: false })
     
-    await mc.command('/summon minecraft:armor_stand 0 65 0')
-    await mc.command('/summon minecraft:armor_stand 2 65 0')
-    await mc.command('/summon minecraft:armor_stand 4 65 0')
+    await mc.command('/summon minecraft:armor_stand 0 65 0 {NoGravity:1b}')
+    await mc.command('/summon minecraft:armor_stand 2 65 0 {NoGravity:1b}')
+    await mc.command('/summon minecraft:armor_stand 4 65 0 {NoGravity:1b}')
     await mc.ticks(5)
     
     const stands = await mc.entities('@e[type=minecraft:armor_stand]')
@@ -573,7 +585,7 @@ describe('E2E Scenario Tests', () => {
     await mc.command('/function match_test:__load')
 
     // Test match on value 2
-    await mc.command('/scoreboard players set $p0 rs 2')
+    await mc.command('/scoreboard players set $p0 __match_test 2')
     await mc.command('/function match_test:classify')
     await mc.ticks(5)
     let out = await mc.scoreboard('#match', 'out')
@@ -581,7 +593,7 @@ describe('E2E Scenario Tests', () => {
     console.log(`  match(2) → out=${out} (expect 20) ✓`)
 
     // Test match on value 3
-    await mc.command('/scoreboard players set $p0 rs 3')
+    await mc.command('/scoreboard players set $p0 __match_test 3')
     await mc.command('/function match_test:classify')
     await mc.ticks(5)
     out = await mc.scoreboard('#match', 'out')
@@ -589,7 +601,7 @@ describe('E2E Scenario Tests', () => {
     console.log(`  match(3) → out=${out} (expect 30) ✓`)
 
     // Test default branch (value 99)
-    await mc.command('/scoreboard players set $p0 rs 99')
+    await mc.command('/scoreboard players set $p0 __match_test 99')
     await mc.command('/function match_test:classify')
     await mc.ticks(5)
     out = await mc.scoreboard('#match', 'out')
@@ -779,7 +791,7 @@ describe('MC Integration - New Features', () => {
     expect(items).toBe(1)        // 1 item matched
 
     await mc.command('/function is_check_test:cleanup').catch(() => {})
-  })
+  }, 30000)  // extended timeout: entity spawn + reload can take >5 s
 
   test('event-test.mcrs: @on(PlayerDeath) compiles and loads', async () => {
     if (!serverOnline) return

package/src/__tests__/mc-syntax.test.ts

@@ -5,7 +5,7 @@ import { compile } from '../compile'
 import { MCCommandValidator } from '../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: string, namespace = 'test'): string[] {
   const result = compile(source, { namespace })
@@ -32,12 +32,6 @@ function validateSource(
 describe('MC Command Syntax Validation', () => {
   const validator = new 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/src/__tests__/schedule.test.ts

@@ -103,3 +103,115 @@ 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 = 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 = 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 = 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 = 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 = 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 = 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')
+  })
+})

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

@@ -0,0 +1,61 @@
+import * as path from 'path'
+import * as fs from 'fs'
+import * as os from 'os'
+import { compile } from '../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 = 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 = 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 = 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(() => 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 = compile(source, { namespace: 'test', filePath: mainPath, includeDirs: [libDir] })
+    expect(result.files.some(f => f.path.includes('triple'))).toBe(true)
+  })
+})

package/src/__tests__/typechecker.test.ts

@@ -270,6 +270,74 @@ fn test() {
       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/src/cli.ts

@@ -57,6 +57,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
 `)
 }
@@ -161,6 +162,7 @@ function parseArgs(args: string[]): {
   sourceMap?: boolean
   mcVersionStr?: string
   lenient?: boolean
+  includeDirs?: string[]
 } {
   const result: ReturnType<typeof parseArgs> = {}
   let i = 0
@@ -189,6 +191,10 @@ function parseArgs(args: string[]): {
     } else if (arg === '--lenient') {
       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++
@@ -216,6 +222,7 @@ function compileCommand(
   sourceMap = false,
   mcVersionStr?: string,
   lenient = false,
+  includeDirs?: string[],
 ): void {
   // Read source file
   if (!fs.existsSync(file)) {
@@ -236,7 +243,7 @@ function compileCommand(
   const source = fs.readFileSync(file, 'utf-8')
 
   try {
-    const result = compile(source, { namespace, filePath: file, generateSourceMap: sourceMap, mcVersion, lenient })
+    const result = compile(source, { namespace, filePath: file, generateSourceMap: sourceMap, mcVersion, lenient, includeDirs })
 
     for (const w of result.warnings) {
       console.error(`Warning: ${w}`)
@@ -435,6 +442,7 @@ async function main(): Promise<void> {
         parsed.sourceMap,
         parsed.mcVersionStr,
         parsed.lenient,
+        parsed.includeDirs,
       )
       }
       break

package/src/compile.ts

@@ -69,6 +69,37 @@ function isLibrarySource(source: string): boolean {
 interface PreprocessOptions {
   filePath?: string
   seen?: Set<string>
+  includeDirs?: string[]
+}
+
+/** Resolve an import specifier to an absolute file path, trying multiple locations. */
+function resolveImportPath(
+  spec: string,
+  fromFile: string,
+  includeDirs: string[]
+): string | null {
+  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: string): number {
@@ -86,6 +117,7 @@ function offsetRanges(ranges: SourceRange[], lineOffset: number): SourceRange[]
 export function preprocessSourceWithMetadata(source: string, options: PreprocessOptions = {}): PreprocessedSource {
   const { filePath } = options
   const seen = options.seen ?? new Set<string>()
+  const includeDirs = options.includeDirs ?? []
 
   if (filePath) {
     seen.add(path.resolve(filePath))
@@ -113,31 +145,28 @@ export function preprocessSourceWithMetadata(source: string, options: Preprocess
         )
       }
 
-      const importPath = path.resolve(path.dirname(filePath), match[1])
+      const importPath = resolveImportPath(match[1], filePath, includeDirs)
+      if (!importPath) {
+        throw new DiagnosticError(
+          'ParseError',
+          `Cannot import '${match[1]}'`,
+          { file: filePath, line: i + 1, col: 1 },
+          lines
+        )
+      }
       if (!seen.has(importPath)) {
         seen.add(importPath)
-        let importedSource: string
-
-        try {
-          importedSource = fs.readFileSync(importPath, 'utf-8')
-        } catch {
-          throw new 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/src/emit/compile.ts

@@ -34,6 +34,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 {
@@ -44,11 +46,11 @@ export interface CompileResult {
 }
 
 export function compile(source: string, options: CompileOptions = {}): CompileResult {
-  const { namespace = 'redscript', filePath, generateSourceMap = false, mcVersion = DEFAULT_MC_VERSION, lenient = false } = options
+  const { namespace = 'redscript', filePath, generateSourceMap = false, mcVersion = DEFAULT_MC_VERSION, lenient = false, includeDirs } = options
   const warnings: string[] = []
 
   // Preprocess: resolve import directives, merge imported sources
-  const preprocessed = preprocessSourceWithMetadata(source, { filePath })
+  const preprocessed = preprocessSourceWithMetadata(source, { filePath, includeDirs })
   const processedSource = preprocessed.source
 
   // Stage 1: Lex + Parse → AST
@@ -144,6 +146,7 @@ export function compile(source: string, options: CompileOptions = {}): CompileRe
     const coroResult = coroutineTransform(mirOpt, coroutineInfos)
     const mirFinal = coroResult.module
     tickFunctions.push(...coroResult.generatedTickFunctions)
+    warnings.push(...coroResult.warnings)
 
     // Stage 5: MIR → LIR
     const lir = lowerToLIR(mirFinal)

package/src/emit/index.ts

@@ -208,7 +208,9 @@ function emitInstr(instr: LIRInstr, ns: string, obj: string, mcVersion: McVersio
 
     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':

package/src/lir/lower.ts

@@ -334,6 +334,33 @@ function lowerInstrInner(
       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++) {