redscript-mc 1.0.0 → 1.2.0

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,72 @@
+name: 🐛 Bug Report
+description: Report a bug in RedScript
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the sections below.
+        
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened?
+      placeholder: A clear description of the bug
+    validations:
+      required: true
+      
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Code to Reproduce
+      description: Minimal RedScript code that triggers the bug
+      render: rust
+      placeholder: |
+        fn example() {
+            // your code here
+        }
+    validations:
+      required: true
+      
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should have happened?
+    validations:
+      required: true
+      
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened?
+    validations:
+      required: true
+      
+  - type: input
+    id: version
+    attributes:
+      label: RedScript Version
+      description: Run `redscript --version`
+      placeholder: "1.0.0"
+    validations:
+      required: true
+      
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Windows
+        - Linux
+    validations:
+      required: true
+      
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other relevant information (error messages, stack traces, etc.)

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,57 @@
+name: ✨ Feature Request
+description: Suggest a new feature for RedScript
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for your feature idea! Please describe it below.
+        
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this feature solve?
+      placeholder: I'm always frustrated when...
+    validations:
+      required: true
+      
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like RedScript to solve this?
+      placeholder: |
+        I'd like a syntax like:
+        ```rs
+        // example code
+        ```
+    validations:
+      required: true
+      
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative solutions or workarounds you've considered?
+      
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      options:
+        - Language Feature
+        - Builtin Function
+        - Standard Library
+        - CLI / Tooling
+        - VSCode Extension
+        - Documentation
+        - Other
+    validations:
+      required: true
+      
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other context, examples, or screenshots

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,34 +1,26 @@
-## What does this PR do?
+## Description
 
-<!-- Brief description -->
+<!-- What does this PR do? -->
 
-## Type of change
+## Type of Change
 
-- [ ] Bug fix
-- [ ] New language feature
-- [ ] New builtin / stdlib
-- [ ] Optimizer improvement
-- [ ] Tooling / CLI
-- [ ] Docs
+- [ ] 🐛 Bug fix
+- [ ] ✨ New feature
+- [ ] 📝 Documentation
+- [ ] ♻️ Refactor
+- [ ] 🧪 Tests
 
-## Checklist
-
-- [ ] `npm run build` passes
-- [ ] `npm test` passes (all existing tests green)
-- [ ] New tests added for new behavior
-- [ ] If adding a builtin: added to `docs/LANGUAGE_REFERENCE.md` and wiki Builtins page
-- [ ] If changing syntax: updated `docs/LANGUAGE_REFERENCE.md`
+## Related Issues
 
-## Test coverage
+<!-- Link related issues: Fixes #123 -->
 
-<!-- Which test file(s) cover this change? -->
+## Checklist
 
-## Example
+- [ ] `npm run build` passes
+- [ ] `npm test` passes
+- [ ] Tests added for new features
+- [ ] Documentation updated (if applicable)
 
-```rs
-// Show a RedScript snippet demonstrating the new feature
-```
+## Screenshots / Examples
 
-```mcfunction
-# Show the expected compiled output
-```
+<!-- If applicable, show before/after or example output -->

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+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
+
+#### Language Features
+- Variables with type inference: `let x = 5;`
+- Functions with typed parameters and return types
+- Control flow: `if`/`else`, `while`, `for i in 0..10`
+- `foreach` for entity iteration
+- Structs and Enums
+- Lambda expressions: `(x: int) => x * 2`
+- NBT structured parameters
+- `@load` decorator for datapack initialization
+- Global variables (compile to scoreboard fake players)
+- `#mc_name` syntax for bare Minecraft identifiers
+- Match expressions with pattern matching
+
+#### Builtins (34+)
+- Player: `say`, `tell`, `title`, `actionbar`, `give`, `kill`, `tp`, `effect`
+- Scoreboard: `scoreboard_get`, `scoreboard_set`, `scoreboard_add`
+- World: `setblock`, `fill`, `summon`, `weather`, `time_set`, `gamerule`
+- Data: `data_get`, `data_merge`
+- Runtime Sets: `set_new`, `set_add`, `set_contains`, `set_remove`
+- And more...
+
+#### Standard Library
+- `math.mcrs` - `abs`, `min`, `max`, `clamp`, `sign`
+- `player.mcrs` - `heal`, `feed`, `teleport_spawn`
+- `cooldown.mcrs` - Cooldown management
+- `timer.mcrs` - Timer utilities
+- `combat.mcrs` - Combat helpers
+- `mobs.mcrs` - Mob spawning utilities
+- `sets.mcrs` - Set operations
+- `strings.mcrs` - String formatting
+
+#### CLI
+- `redscript compile` - Compile to datapack
+- `redscript watch` - Watch mode with hot reload
+- `redscript check` - Type checking
+- `redscript fmt` - Code formatter
+- `redscript repl` - Interactive REPL
+- Output targets: datapack, cmdblock, structure
+
+#### Tooling
+- VSCode Extension (v0.8.2) with syntax highlighting, autocomplete, go-to-definition, rename
+- Online IDE: https://redscript-ide.pages.dev
+- Documentation: https://redscript-docs.pages.dev
+- Paper plugin for integration testing
+
+#### Optimizer
+- Dead code elimination
+- Constant folding
+- Inline simple functions
+- Remove redundant scoreboard operations

package/CONTRIBUTING.md

@@ -0,0 +1,140 @@
+# Contributing to RedScript
+
+Thanks for your interest in contributing to RedScript! 🎮
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- npm or pnpm
+
+### Setup
+
+```bash
+git clone https://github.com/bkmashiro/redscript.git
+cd redscript
+npm install
+npm run build
+npm test
+```
+
+### Project Structure
+
+```
+redscript/
+├── src/
+│   ├── parser/         # Lexer & Parser (grammar → AST)
+│   ├── lowering/       # AST → mcfunction code generation
+│   ├── cli.ts          # CLI entry point
+│   ├── stdlib/         # Standard library (.mcrs files)
+│   ├── examples/       # Example datapacks
+│   └── __tests__/      # Jest tests
+├── redscript-vscode/   # VSCode extension
+└── docs/               # Documentation
+```
+
+## Development Workflow
+
+### Building
+
+```bash
+npm run build    # Compile TypeScript
+npm run watch    # Watch mode
+```
+
+### Testing
+
+```bash
+npm test         # Run all tests
+npm test -- --watch  # Watch mode
+npm test -- -t "foreach"  # Run specific test
+```
+
+### Code Style
+
+- TypeScript with strict mode
+- No semicolons (handled by prettier)
+- 2-space indentation
+
+## Making Changes
+
+### Adding a New Builtin Function
+
+1. Add to `BUILTINS` map in `src/lowering/index.ts`:
+
+```typescript
+my_builtin: ([arg1, arg2]) => `my command ${arg1} ${arg2}`,
+```
+
+2. For complex builtins (returning values), add special handling in `lowerCall()`.
+
+3. Add tests in `src/__tests__/`:
+
+```typescript
+it('compiles my_builtin', () => {
+  const source = `fn test() { my_builtin("a", "b"); }`
+  const files = compile(source)
+  expect(getFunction(files, 'test')).toContain('my command a b')
+})
+```
+
+4. Add documentation in docs.
+
+### Adding Language Features
+
+1. Update grammar in `src/parser/` (lexer + parser)
+2. Add AST types if needed
+3. Update lowering in `src/lowering/`
+4. Add comprehensive tests
+5. Update VSCode extension syntax highlighting
+
+### Stdlib Contributions
+
+Add utility functions to `src/stdlib/`:
+
+```mcrs
+// src/stdlib/my_utils.mcrs
+
+/// Useful helper function
+fn my_helper(target: selector) {
+    // implementation
+}
+```
+
+## Pull Request Process
+
+1. Fork the repo
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make changes with tests
+4. Run `npm run build && npm test`
+5. Commit with clear message: `feat: add X` / `fix: resolve Y`
+6. Push and open PR
+
+### Commit Convention
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation
+- `test:` Tests
+- `refactor:` Code refactoring
+- `chore:` Maintenance
+
+## Testing on Real Server
+
+For integration testing with a real Minecraft server:
+
+1. Set up Paper 1.21.4 server with [testharness plugin](https://github.com/bkmashiro/redscript-testharness)
+2. Run: `npm run test:mc`
+
+See [Testing Guide](https://redscript-docs.pages.dev/en/guide/testing) for details.
+
+## Need Help?
+
+- Open an issue for bugs or feature requests
+- Check existing issues before creating new ones
+- Join discussions in GitHub Discussions
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/README.md

@@ -7,11 +7,16 @@
 Write clean game logic. RedScript handles the scoreboard spaghetti.
 
 [![CI](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-510%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
 [![npm](https://img.shields.io/npm/v/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
+[![npm downloads](https://img.shields.io/npm/dm/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
+[![VSCode](https://img.shields.io/badge/VSCode-Extension-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=bkmashiro.redscript-vscode)
+[![Online IDE](https://img.shields.io/badge/Try-Online%20IDE-orange)](https://redscript-ide.pages.dev)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
-[![tests](https://img.shields.io/badge/tests-423%20passing-brightgreen)](./src/__tests__)
 
-[中文版](./README.zh.md) · [Wiki](https://github.com/bkmashiro/redscript/wiki) · [Quick Start](#quick-start)
+[中文版](./README.zh.md) · [Quick Start](#quick-start) · [Docs](https://redscript-docs.pages.dev) · [Contributing](./CONTRIBUTING.md)
+
+### 🚀 [Try it online — no install needed!](https://redscript-ide.pages.dev)
 
 </div>
 
@@ -24,8 +29,8 @@ You want to make a Minecraft mini-game. You need a countdown timer, kill counter
 With RedScript, it's this:
 
 ```rs
-// pvp_game.rs
-import "stdlib/player.rs"
+// pvp_game.mcrs
+import "stdlib/player.mcrs"
 
 const GAME_TIME: int = 300;
 
@@ -67,20 +72,24 @@ One file. Compiles to a ready-to-use datapack in seconds.
 
 ### Quick Start
 
-#### Install
+#### Option 1: Online IDE (No Install)
 
-```bash
-npm install -g redscript
-```
+**[→ redscript-ide.pages.dev](https://redscript-ide.pages.dev)** — Write code, see output instantly.
+
+#### Option 2: VSCode Extension
+
+1. Install [RedScript for VSCode](https://marketplace.visualstudio.com/items?itemName=bkmashiro.redscript-vscode)
+2. Get syntax highlighting, auto-complete, hover docs, and more
 
-#### Compile
+#### Option 3: CLI
 
 ```bash
-redscript compile pvp_game.rs -o ./my-datapack
+npm install -g redscript-mc
+redscript compile game.mcrs -o ./my-datapack
 ```
 
 ```
-✓ Compiled pvp_game.rs
+✓ Compiled pvp_game.mcrs
   Namespace : pvp_game
   Functions : 7
   Commands  : 34  →  28  (optimizer: −18%)
@@ -230,11 +239,11 @@ redscript validate <file>      Validate MC commands
 ### Standard Library
 
 ```rs
-import "stdlib/math.rs"       // abs, min, max, clamp
-import "stdlib/player.rs"     // is_alive, in_range, get_health
-import "stdlib/timer.rs"      // start_timer, tick_timer, has_elapsed
-import "stdlib/cooldown.rs"   // set_cooldown, check_cooldown
-import "stdlib/mobs.rs"       // ZOMBIE, SKELETON, CREEPER, ... (60+ constants)
+import "stdlib/math.mcrs"       // abs, min, max, clamp
+import "stdlib/player.mcrs"     // is_alive, in_range, get_health
+import "stdlib/timer.mcrs"      // start_timer, tick_timer, has_elapsed
+import "stdlib/cooldown.mcrs"   // set_cooldown, check_cooldown
+import "stdlib/mobs.mcrs"       // ZOMBIE, SKELETON, CREEPER, ... (60+ constants)
 ```
 
 ---
@@ -244,10 +253,10 @@ import "stdlib/mobs.rs"       // ZOMBIE, SKELETON, CREEPER, ... (60+ constants)
 | | |
 |---|---|
 | 📖 [Language Reference](docs/LANGUAGE_REFERENCE.md) | Full syntax & type system |
-| 🔧 [Builtins](https://github.com/bkmashiro/redscript/wiki/Builtins) | All 34+ MC builtin functions |
-| ⚡ [Optimizer](https://github.com/bkmashiro/redscript/wiki/Optimizer) | How the optimizer works |
+| 🔧 [Builtins](https://redscript-docs.pages.dev/Builtins) | All 34+ MC builtin functions |
+| ⚡ [Optimizer](https://redscript-docs.pages.dev/Optimizer) | How the optimizer works |
 | 🧱 [Structure Target](docs/STRUCTURE_TARGET.md) | Compile to NBT command block structures |
-| 🧪 [Integration Testing](https://github.com/bkmashiro/redscript/wiki/Integration-Testing) | Test against a real Paper server |
+| 🧪 [Integration Testing](https://redscript-docs.pages.dev/Integration-Testing) | Test against a real Paper server |
 | 🏗 [Implementation Guide](docs/IMPLEMENTATION_GUIDE.md) | Compiler internals |
 
 ---

package/README.zh.md

@@ -7,11 +7,16 @@
 写干净的游戏逻辑，把记分板的面条代码交给 RedScript 处理。
 
 [![CI](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-510%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
 [![npm](https://img.shields.io/npm/v/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
+[![npm downloads](https://img.shields.io/npm/dm/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
+[![VSCode](https://img.shields.io/badge/VSCode-插件-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=bkmashiro.redscript-vscode)
+[![在线 IDE](https://img.shields.io/badge/试用-在线IDE-orange)](https://redscript-ide.pages.dev)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
-[![tests](https://img.shields.io/badge/tests-423%20passing-brightgreen)](./src/__tests__)
 
-[English](./README.md) · [Wiki](https://github.com/bkmashiro/redscript/wiki) · [快速开始](#快速开始)
+[English](./README.md) · [快速开始](#快速开始) · [文档](https://redscript-docs.pages.dev) · [贡献指南](./CONTRIBUTING.md)
+
+### 🚀 [在线试用 — 无需安装！](https://redscript-ide.pages.dev)
 
 </div>
 
@@ -24,8 +29,8 @@
 用 RedScript，就是这样：
 
 ```rs
-// pvp_game.rs
-import "stdlib/player.rs"
+// pvp_game.mcrs
+import "stdlib/player.mcrs"
 
 const GAME_TIME: int = 300;
 
@@ -67,20 +72,24 @@ fn on_kill() {
 
 ### 快速开始
 
-#### 安装
+#### 方式 1：在线 IDE（无需安装）
 
-```bash
-npm install -g redscript
-```
+**[→ redscript-ide.pages.dev](https://redscript-ide.pages.dev)** — 写代码，实时看输出。
+
+#### 方式 2：VSCode 插件
+
+1. 安装 [RedScript for VSCode](https://marketplace.visualstudio.com/items?itemName=bkmashiro.redscript-vscode)
+2. 获得语法高亮、自动补全、悬停文档等功能
 
-#### 编译
+#### 方式 3：命令行
 
 ```bash
-redscript compile pvp_game.rs -o ./my-datapack
+npm install -g redscript-mc
+redscript compile game.mcrs -o ./my-datapack
 ```
 
 ```
-✓ 已编译 pvp_game.rs
+✓ 已编译 pvp_game.mcrs
   命名空间 : pvp_game
   函数数量  : 7
   命令数量  : 34  →  28  (优化器节省了 18%)
@@ -230,11 +239,11 @@ redscript validate <file>      验证 MC 命令语法
 ### 标准库
 
 ```rs
-import "stdlib/math.rs"       // abs, min, max, clamp
-import "stdlib/player.rs"     // is_alive, in_range, get_health
-import "stdlib/timer.rs"      // start_timer, tick_timer, has_elapsed
-import "stdlib/cooldown.rs"   // set_cooldown, check_cooldown
-import "stdlib/mobs.rs"       // ZOMBIE, SKELETON, CREEPER ... (60+ 实体常量)
+import "stdlib/math.mcrs"       // abs, min, max, clamp
+import "stdlib/player.mcrs"     // is_alive, in_range, get_health
+import "stdlib/timer.mcrs"      // start_timer, tick_timer, has_elapsed
+import "stdlib/cooldown.mcrs"   // set_cooldown, check_cooldown
+import "stdlib/mobs.mcrs"       // ZOMBIE, SKELETON, CREEPER ... (60+ 实体常量)
 ```
 
 ---
@@ -244,10 +253,10 @@ import "stdlib/mobs.rs"       // ZOMBIE, SKELETON, CREEPER ... (60+ 实体常量
 | | |
 |---|---|
 | 📖 [语言参考](docs/LANGUAGE_REFERENCE.md) | 完整语法与类型系统 |
-| 🔧 [内置函数](https://github.com/bkmashiro/redscript/wiki/Builtins) | 所有 34+ MC 内置函数 |
-| ⚡ [优化器](https://github.com/bkmashiro/redscript/wiki/Optimizer) | 各优化 Pass 说明 |
+| 🔧 [内置函数](https://redscript-docs.pages.dev/Builtins) | 所有 34+ MC 内置函数 |
+| ⚡ [优化器](https://redscript-docs.pages.dev/Optimizer) | 各优化 Pass 说明 |
 | 🧱 [结构体目标](docs/STRUCTURE_TARGET.md) | 编译到 NBT 命令方块结构体 |
-| 🧪 [集成测试](https://github.com/bkmashiro/redscript/wiki/Integration-Testing) | 在真实 Paper 服务器上测试 |
+| 🧪 [集成测试](https://redscript-docs.pages.dev/Integration-Testing) | 在真实 Paper 服务器上测试 |
 | 🏗 [实现指南](docs/IMPLEMENTATION_GUIDE.md) | 编译器内部原理 |
 
 ---