redscript-mc 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 All notable changes to RedScript will be documented in this file.
 
+## [1.2.0] - 2026-03-12
+
+### Added
+- `is` type narrowing for entity checks (`if (e is Player)`)
+- `impl` blocks for struct methods
+- Static method calls (`Type::method()`)
+- Timer OOP API in stdlib
+- `setTimeout(delay, callback)` builtin
+- `setInterval(delay, callback)` builtin
+- `clearInterval(id)` builtin
+- `@on(Event)` static event system
+- PlayerDeath, PlayerJoin, BlockBreak, EntityKill, ItemUse
+- Automatic namespace prefixing for scoreboard objectives
+- Comprehensive MC tag constants (313 tags)
+
+### Changed
+- Stdlib timer functions now use OOP API
+
+## [1.1.0] - 2026-03-12
+
+### Language Features
+- **Variable selector syntax**: `execute if entity p[x_rotation=-90..-45]` now works in foreach loops
+- **New selector filters**: `x_rotation`, `y_rotation`, `x`, `y`, `z` for rotation and position checks
+- **Duplicate binding detection**: Error when redeclaring foreach variables
+
+### Builtins
+- `effect_clear(target, [effect])` — Clear all or specific effects
+- `data_merge(target, nbt)` — Merge NBT data into entities
+
+### Standard Library
+- `effects.mcrs` — Effect shortcuts (speed, strength, regen, buff_all...)
+- `world.mcrs` — World/gamerule helpers (set_day, weather_clear, enable_keep_inventory...)
+- `inventory.mcrs` — Inventory management (give_kit_warrior, clear_inventory...)
+- `particles.mcrs` — Particle effects (hearts_at, flames, sparkles_at...)
+- `spawn.mcrs` — Teleport utilities (teleport_to, gather_all, goto_lobby...)
+- `teams.mcrs` — Team management (create_red_team, setup_two_teams...)
+- `bossbar.mcrs` — Bossbar helpers (create_progress_bar, update_bar...)
+- `interactions.mcrs` — Input detection (check_look_up, on_right_click, on_sneak_click...)
+
+### Bug Fixes
+- Negative coordinates in summon/tp/particle now work correctly
+- Stdlib particles use coordinates instead of selectors
+
+### Documentation
+- Added tutorials: Zombie Survival, Capture the Flag, Parkour Race
+- Added local debugging guide
+- Added stdlib reference page
+- Added Paper server testing guide
+
+### Community
+- CONTRIBUTING.md with development guide
+- GitHub issue/PR templates
+- CHANGELOG.md
+
 ## [1.0.0] - 2026-03-12
 
 ### 🎉 Initial Release

package/dist/__tests__/cli.test.js

@@ -66,6 +66,144 @@ describe('CLI API', () => {
             expect(result.ir.functions.filter(fn => fn.name === 'from_a')).toHaveLength(1);
             expect(result.ir.functions.filter(fn => fn.name === 'from_b')).toHaveLength(1);
         });
+        it('uses rs-prefixed scoreboard objectives for imported stdlib files', () => {
+            const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'redscript-stdlib-'));
+            const stdlibDir = path.join(tempDir, 'src', 'stdlib');
+            const stdlibPath = path.join(stdlibDir, 'timer.mcrs');
+            const mainPath = path.join(tempDir, 'main.mcrs');
+            fs.mkdirSync(stdlibDir, { recursive: true });
+            fs.writeFileSync(stdlibPath, 'fn tick_timer() { scoreboard_set("#rs", "timer_ticks", 1); }\n');
+            fs.writeFileSync(mainPath, 'import "./src/stdlib/timer.mcrs"\n\nfn main() { tick_timer(); }\n');
+            const source = fs.readFileSync(mainPath, 'utf-8');
+            const result = (0, index_1.compile)(source, { namespace: 'mygame', filePath: mainPath });
+            const tickTimer = result.files.find(file => file.path.endsWith('/tick_timer.mcfunction'));
+            expect(tickTimer?.content).toContain('scoreboard players set #rs rs.timer_ticks 1');
+        });
+        it('adds a call-site hash for stdlib internal scoreboard objectives', () => {
+            const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'redscript-stdlib-hash-'));
+            const stdlibDir = path.join(tempDir, 'src', 'stdlib');
+            const stdlibPath = path.join(stdlibDir, 'timer.mcrs');
+            const mainPath = path.join(tempDir, 'main.mcrs');
+            fs.mkdirSync(stdlibDir, { recursive: true });
+            fs.writeFileSync(stdlibPath, [
+                'fn timer_start(name: string, duration: int) {',
+                '  scoreboard_set("timer_ticks", #rs, duration);',
+                '  scoreboard_set("timer_active", #rs, 1);',
+                '}',
+                '',
+            ].join('\n'));
+            fs.writeFileSync(mainPath, [
+                'import "./src/stdlib/timer.mcrs"',
+                '',
+                'fn main() {',
+                '  timer_start("x", 100);',
+                '  timer_start("x", 100);',
+                '}',
+                '',
+            ].join('\n'));
+            const source = fs.readFileSync(mainPath, 'utf-8');
+            const result = (0, index_1.compile)(source, { namespace: 'mygame', filePath: mainPath });
+            const timerFns = result.files.filter(file => /timer_start__callsite_[0-9a-f]{4}\.mcfunction$/.test(file.path));
+            expect(timerFns).toHaveLength(2);
+            const objectives = timerFns
+                .flatMap(file => [...file.content.matchAll(/rs\._timer_([0-9a-f]{4})/g)].map(match => match[0]));
+            expect(new Set(objectives).size).toBe(2);
+        });
+        it('Timer::new creates timer', () => {
+            const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'redscript-timer-new-'));
+            const mainPath = path.join(tempDir, 'main.mcrs');
+            const timerPath = path.resolve(process.cwd(), 'src/stdlib/timer.mcrs');
+            fs.writeFileSync(mainPath, [
+                `import "${timerPath}"`,
+                '',
+                'fn main() {',
+                '  let timer: Timer = Timer::new(20);',
+                '}',
+                '',
+            ].join('\n'));
+            const source = fs.readFileSync(mainPath, 'utf-8');
+            const result = (0, index_1.compile)(source, { namespace: 'timernew', filePath: mainPath });
+            expect(result.typeErrors).toEqual([]);
+            const newFn = result.files.find(file => file.path.endsWith('/Timer_new.mcfunction'));
+            expect(newFn?.content).toContain('scoreboard players set timer_ticks rs 0');
+            expect(newFn?.content).toContain('scoreboard players set timer_active rs 0');
+        });
+        it('Timer.start/pause/reset', () => {
+            const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'redscript-timer-state-'));
+            const mainPath = path.join(tempDir, 'main.mcrs');
+            const timerPath = path.resolve(process.cwd(), 'src/stdlib/timer.mcrs');
+            fs.writeFileSync(mainPath, [
+                `import "${timerPath}"`,
+                '',
+                'fn main() {',
+                '  let timer: Timer = Timer::new(20);',
+                '  timer.start();',
+                '  timer.pause();',
+                '  timer.reset();',
+                '}',
+                '',
+            ].join('\n'));
+            const source = fs.readFileSync(mainPath, 'utf-8');
+            const result = (0, index_1.compile)(source, { namespace: 'timerstate', filePath: mainPath });
+            expect(result.typeErrors).toEqual([]);
+            const startFn = result.files.find(file => file.path.endsWith('/Timer_start.mcfunction'));
+            const pauseFn = result.files.find(file => file.path.endsWith('/Timer_pause.mcfunction'));
+            const resetFn = result.files.find(file => file.path.endsWith('/Timer_reset.mcfunction'));
+            expect(startFn?.content).toContain('scoreboard players set timer_active rs 1');
+            expect(pauseFn?.content).toContain('scoreboard players set timer_active rs 0');
+            expect(resetFn?.content).toContain('scoreboard players set timer_ticks rs 0');
+        });
+        it('Timer.done returns bool', () => {
+            const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'redscript-timer-done-'));
+            const mainPath = path.join(tempDir, 'main.mcrs');
+            const timerPath = path.resolve(process.cwd(), 'src/stdlib/timer.mcrs');
+            fs.writeFileSync(mainPath, [
+                `import "${timerPath}"`,
+                '',
+                'fn main() {',
+                '  let timer: Timer = Timer::new(20);',
+                '  let finished: bool = timer.done();',
+                '  if (finished) {',
+                '    say("done");',
+                '  }',
+                '}',
+                '',
+            ].join('\n'));
+            const source = fs.readFileSync(mainPath, 'utf-8');
+            const result = (0, index_1.compile)(source, { namespace: 'timerdone', filePath: mainPath });
+            expect(result.typeErrors).toEqual([]);
+            const doneFn = result.files.find(file => file.path.endsWith('/Timer_done.mcfunction'));
+            const mainFn = result.files.find(file => file.path.endsWith('/main.mcfunction'));
+            expect(doneFn?.content).toContain('scoreboard players get timer_ticks rs');
+            expect(doneFn?.content).toContain('return run scoreboard players get');
+            expect(mainFn?.content).toContain('execute if score $finished rs matches 1..');
+        });
+        it('Timer.tick increments', () => {
+            const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'redscript-timer-tick-'));
+            const mainPath = path.join(tempDir, 'main.mcrs');
+            const timerPath = path.resolve(process.cwd(), 'src/stdlib/timer.mcrs');
+            fs.writeFileSync(mainPath, [
+                `import "${timerPath}"`,
+                '',
+                'fn main() {',
+                '  let timer: Timer = Timer::new(20);',
+                '  timer.start();',
+                '  timer.tick();',
+                '}',
+                '',
+            ].join('\n'));
+            const source = fs.readFileSync(mainPath, 'utf-8');
+            const result = (0, index_1.compile)(source, { namespace: 'timertick', filePath: mainPath });
+            expect(result.typeErrors).toEqual([]);
+            const tickOutput = result.files
+                .filter(file => file.path.includes('/Timer_tick'))
+                .map(file => file.content)
+                .join('\n');
+            expect(tickOutput).toContain('scoreboard players get timer_active rs');
+            expect(tickOutput).toContain('scoreboard players get timer_ticks rs');
+            expect(tickOutput).toContain(' += $const_1 rs');
+            expect(tickOutput).toContain('execute store result score timer_ticks rs run scoreboard players get $_');
+        });
     });
     describe('compile()', () => {
         it('compiles simple source', () => {

package/dist/__tests__/codegen.test.js

@@ -117,5 +117,30 @@ describe('generateDatapack', () => {
         expect(json.criteria.trigger.trigger).toBe('minecraft:story/mine_diamond');
         expect(json.rewards.function).toBe('mypack:on_mine_diamond');
     });
+    it('generates static event dispatcher in __tick', () => {
+        const mod = {
+            namespace: 'mypack',
+            globals: [],
+            functions: [{
+                    name: 'handle_death',
+                    params: [],
+                    locals: [],
+                    blocks: [{ label: 'entry', instrs: [], term: { op: 'return' } }],
+                    eventHandler: { eventType: 'PlayerDeath', tag: 'rs.just_died' },
+                }, {
+                    name: 'handle_death_2',
+                    params: [],
+                    locals: [],
+                    blocks: [{ label: 'entry', instrs: [], term: { op: 'return' } }],
+                    eventHandler: { eventType: 'PlayerDeath', tag: 'rs.just_died' },
+                }],
+        };
+        const files = (0, mcfunction_1.generateDatapack)(mod);
+        const tickFn = files.find(f => f.path.includes('__tick.mcfunction'));
+        expect(tickFn).toBeDefined();
+        expect(tickFn.content).toContain('execute as @a[tag=rs.just_died] run function mypack:handle_death');
+        expect(tickFn.content).toContain('execute as @a[tag=rs.just_died] run function mypack:handle_death_2');
+        expect(tickFn.content).toContain('tag @a[tag=rs.just_died] remove rs.just_died');
+    });
 });
 //# sourceMappingURL=codegen.test.js.map

package/dist/__tests__/e2e.test.js

@@ -124,6 +124,184 @@ fn main() {
             expect(mainFn).toContain('"objective":"rs"');
         });
     });
+    describe('timer builtins', () => {
+        it('generates scheduled timer helper functions', () => {
+            const files = compile(`
+fn main() {
+    let intervalId: int = setInterval(20, () => {
+        say("tick");
+    });
+    setTimeout(100, () => {
+        say("later");
+    });
+    clearInterval(intervalId);
+}
+`);
+            const mainFn = getFunction(files, 'main');
+            const intervalFn = getFunction(files, '__interval_0');
+            const intervalBodyFn = getFunction(files, '__interval_body_0');
+            const timeoutFn = getFunction(files, '__timeout_0');
+            expect(mainFn).toBeDefined();
+            expect(mainFn).toContain('schedule function test:__interval_0 20t');
+            expect(mainFn).toContain('schedule function test:__timeout_0 100t');
+            expect(mainFn).toContain('schedule clear test:__interval_0');
+            expect(intervalFn).toContain('function test:__interval_body_0');
+            expect(intervalFn).toContain('schedule function test:__interval_0 20t');
+            expect(intervalBodyFn).toContain('say tick');
+            expect(timeoutFn).toContain('say later');
+        });
+    });
+    describe('is type narrowing', () => {
+        it('type checks and compiles entity narrowing inside foreach blocks', () => {
+            const source = `
+fn main() {
+    foreach (e in @e) {
+        if (e is Player) {
+            kill(e);
+        }
+        if (e is Zombie) {
+            kill(e);
+        }
+    }
+}
+`;
+            expect(typeCheck(source)).toEqual([]);
+            const files = compile(source);
+            const mainFn = getFunction(files, 'main');
+            const foreachFn = getSubFunction(files, 'main', 'foreach_0');
+            const thenFiles = files.filter(file => file.path.includes('/main/then_') && file.content.includes('kill @s'));
+            expect(mainFn).toContain('execute as @e run function test:main/foreach_0');
+            expect(foreachFn).toContain('execute if entity @s[type=player] run function test:main/then_');
+            expect(foreachFn).toContain('execute if entity @s[type=zombie] run function test:main/then_');
+            expect(thenFiles).toHaveLength(2);
+        });
+    });
+    describe('impl blocks', () => {
+        it('compiles static and instance impl methods end to end', () => {
+            const source = `
+struct Point { x: int, y: int }
+
+impl Point {
+    fn new(x: int, y: int) -> Point {
+        return { x: x, y: y };
+    }
+
+    fn distance(self) -> int {
+        return self.x + self.y;
+    }
+}
+
+fn main() {
+    let p: Point = Point::new(1, 2);
+    let d: int = p.distance();
+    say("\${d}");
+}
+`;
+            expect(typeCheck(source)).toEqual([]);
+            const files = compile(source);
+            const mainFn = getFunction(files, 'main');
+            const staticFn = getFunction(files, 'Point_new');
+            const instanceFn = getFunction(files, 'Point_distance');
+            expect(mainFn).toContain('function test:Point_new');
+            expect(mainFn).toContain('function test:Point_distance');
+            expect(staticFn).toBeDefined();
+            expect(instanceFn).toBeDefined();
+        });
+    });
+    describe('namespace prefixing', () => {
+        it('prefixes user objectives but preserves mc_name and qualified objectives', () => {
+            const files = compile(`
+fn main() {
+    scoreboard_set("timer", #rs, 100);
+    scoreboard_set(@s, "timer", 100);
+    scoreboard_set(@s, #health, 20);
+    scoreboard_set(@s, "custom.timer", 1);
+}
+`, 'pack');
+            const mainFn = getFunction(files, 'main');
+            expect(mainFn).toContain('scoreboard players set timer rs 100');
+            expect(mainFn).toContain('scoreboard players set @s pack.timer 100');
+            expect(mainFn).toContain('scoreboard players set @s health 20');
+            expect(mainFn).toContain('scoreboard players set @s custom.timer 1');
+        });
+    });
+    describe('Timer OOP API', () => {
+        it('compiles the Timer impl API end to end', () => {
+            const source = `
+struct Timer {
+    _id: int,
+    _duration: int
+}
+
+impl Timer {
+    fn new(duration: int) -> Timer {
+        scoreboard_set("timer_ticks", #rs, 0);
+        scoreboard_set("timer_active", #rs, 0);
+        return { _id: 0, _duration: duration };
+    }
+
+    fn start(self) {
+        scoreboard_set("timer_active", #rs, 1);
+    }
+
+    fn pause(self) {
+        scoreboard_set("timer_active", #rs, 0);
+    }
+
+    fn reset(self) {
+        scoreboard_set("timer_ticks", #rs, 0);
+    }
+
+    fn done(self) -> bool {
+        let ticks: int = scoreboard_get("timer_ticks", #rs);
+        return ticks >= self._duration;
+    }
+
+    fn tick(self) {
+        let active: int = scoreboard_get("timer_active", #rs);
+        let ticks: int = scoreboard_get("timer_ticks", #rs);
+
+        if (active == 1) {
+            if (ticks < self._duration) {
+                scoreboard_set("timer_ticks", #rs, ticks + 1);
+            }
+        }
+    }
+}
+
+fn main() {
+    let t: Timer = Timer::new(100);
+    t.start();
+    t.tick();
+    let finished: bool = t.done();
+    if (finished) {
+        say("done");
+    }
+    t.pause();
+    t.reset();
+}
+`;
+            expect(typeCheck(source)).toEqual([]);
+            const files = compile(source, 'timerapi');
+            const mainFn = getFunction(files, 'main');
+            const newFn = getFunction(files, 'Timer_new');
+            const startFn = getFunction(files, 'Timer_start');
+            const tickFn = getFunction(files, 'Timer_tick');
+            const doneFn = getFunction(files, 'Timer_done');
+            const pauseFn = getFunction(files, 'Timer_pause');
+            const resetFn = getFunction(files, 'Timer_reset');
+            expect(mainFn).toContain('function timerapi:Timer_new');
+            expect(mainFn).toContain('function timerapi:Timer_start');
+            expect(mainFn).toContain('function timerapi:Timer_tick');
+            expect(mainFn).toContain('function timerapi:Timer_done');
+            expect(newFn).toContain('scoreboard players set timer_ticks rs 0');
+            expect(startFn).toContain('scoreboard players set timer_active rs 1');
+            expect(tickFn).toContain('scoreboard players get timer_active rs');
+            expect(doneFn).toContain('scoreboard players get timer_ticks rs');
+            expect(pauseFn).toContain('scoreboard players set timer_active rs 0');
+            expect(resetFn).toContain('scoreboard players set timer_ticks rs 0');
+        });
+    });
     describe('advancement event decorators', () => {
         it('generates advancement json with reward function path', () => {
             const source = `
@@ -276,12 +454,12 @@ fn test() {
 }
 `;
             const fn = getFunction(compile(source), 'test');
-            expect(fn).toContain('scoreboard objectives setdisplay sidebar kills');
-            expect(fn).toContain('scoreboard objectives setdisplay list coins');
-            expect(fn).toContain('scoreboard objectives setdisplay belowName hp');
+            expect(fn).toContain('scoreboard objectives setdisplay sidebar test.kills');
+            expect(fn).toContain('scoreboard objectives setdisplay list test.coins');
+            expect(fn).toContain('scoreboard objectives setdisplay belowName test.hp');
             expect(fn).toContain('scoreboard objectives setdisplay sidebar');
-            expect(fn).toContain('scoreboard objectives add kills playerKillCount "Kill Count"');
-            expect(fn).toContain('scoreboard objectives remove kills');
+            expect(fn).toContain('scoreboard objectives add test.kills playerKillCount "Kill Count"');
+            expect(fn).toContain('scoreboard objectives remove test.kills');
         });
         it('compiles bossbar builtins', () => {
             const source = `
@@ -485,7 +663,7 @@ fn test() -> int {
             const fn = getFunction(files, 'test');
             expect(fn).toBeDefined();
             expect(fn).toContain('execute store result score');
-            expect(fn).toContain('scoreboard players get PlayerName kill_count');
+            expect(fn).toContain('scoreboard players get PlayerName test.kill_count');
         });
         it('compiles scoreboard_get with @s selector', () => {
             const source = `
@@ -497,7 +675,7 @@ fn test() -> int {
             const files = compile(source);
             const fn = getFunction(files, 'test');
             expect(fn).toBeDefined();
-            expect(fn).toContain('scoreboard players get @s kill_count');
+            expect(fn).toContain('scoreboard players get @s test.kill_count');
         });
         it('compiles scoreboard_set with constant value', () => {
             const source = `
@@ -508,7 +686,7 @@ fn test() {
             const files = compile(source);
             const fn = getFunction(files, 'test');
             expect(fn).toBeDefined();
-            expect(fn).toContain('scoreboard players set PlayerName kill_count 100');
+            expect(fn).toContain('scoreboard players set PlayerName test.kill_count 100');
         });
         it('compiles scoreboard_set with variable value', () => {
             const source = `
@@ -522,7 +700,7 @@ fn test() {
                 .filter(f => f.path.includes('test'))
                 .map(f => f.content)
                 .join('\n');
-            expect(allContent).toContain('execute store result score @s score');
+            expect(allContent).toContain('execute store result score @s test.score');
         });
         it('compiles score() as expression', () => {
             const source = `
@@ -548,7 +726,7 @@ fn double_score() -> int {
             const files = compile(source);
             const fn = getFunction(files, 'double_score');
             expect(fn).toBeDefined();
-            expect(fn).toContain('scoreboard players get @s points');
+            expect(fn).toContain('scoreboard players get @s test.points');
         });
     });
     describe('Built-in functions', () => {
@@ -1342,10 +1520,10 @@ fn heal(amount: int) {
     });
     describe('backward compat: string objective still works', () => {
         const source = `fn test() { let x: int = scoreboard_get(@s, "kills"); }`;
-        it('compiles "kills" string to bare objective name', () => {
+        it('prefixes plain string objectives with the active namespace', () => {
             const files = compile(source, 'compat');
             const fn = getFunction(files, 'test');
-            expect(fn).toContain('scoreboard players get @s kills');
+            expect(fn).toContain('scoreboard players get @s compat.kills');
         });
     });
     describe('#mc_name with fake player target', () => {

package/dist/__tests__/lexer.test.js

@@ -10,10 +10,16 @@ function kinds(tokens) {
 describe('Lexer', () => {
     describe('keywords', () => {
         it('recognizes all keywords', () => {
-            const tokens = tokenize('fn let const if else while for foreach match return as at in struct enum trigger namespace');
+            const tokens = tokenize('fn let const if else while for foreach match return as at in is struct impl enum trigger namespace');
             expect(kinds(tokens)).toEqual([
                 'fn', 'let', 'const', 'if', 'else', 'while', 'for', 'foreach', 'match',
-                'return', 'as', 'at', 'in', 'struct', 'enum', 'trigger', 'namespace', 'eof'
+                'return', 'as', 'at', 'in', 'is', 'struct', 'impl', 'enum', 'trigger', 'namespace', 'eof'
+            ]);
+        });
+        it('tokenizes is-check and impl syntax with their dedicated keywords', () => {
+            const tokens = tokenize('if (e is Player) { } impl Point { }');
+            expect(kinds(tokens)).toEqual([
+                'if', '(', 'ident', 'is', 'ident', ')', '{', '}', 'impl', 'ident', '{', '}', 'eof',
             ]);
         });
         it('recognizes type keywords', () => {
@@ -169,6 +175,10 @@ describe('Lexer', () => {
             const tokens = tokenize('=>');
             expect(kinds(tokens)).toEqual(['=>', 'eof']);
         });
+        it('tokenizes static method separators for impl methods', () => {
+            const tokens = tokenize('Point::new()');
+            expect(kinds(tokens)).toEqual(['ident', '::', 'ident', '(', ')', 'eof']);
+        });
     });
     describe('delimiters', () => {
         it('tokenizes all delimiters', () => {