Repository navigation
Home
Tki_sor edited this page Sep 15, 2026
·
7 revisions
中文 · English
现代、极速、优雅的 Minecraft 脚本魔改引擎
NekoJS 是一个基于 NeoForge 和 GraalVM/GraalJS 构建的 Minecraft JavaScript 脚本运行时。它面向整合包作者和模组开发者，目标是在 Minecraft 中提供接近现代前端工程化的脚本开发体验。
本 Wiki 按读者角色组织：
- 脚本作者：从 快速开始 入门，继续阅读 脚本基础、全局绑定 和 事件参考。
- 整合包作者：重点阅读 配方系统、注册新内容、模块系统 和 TypeScript 与 JSX。
- 插件开发者：从 插件开发 开始，配合 类型适配器、事件扩展 和 注解体系。
- 项目贡献者：阅读 项目架构、Probe 类型生成 和 构建系统。
| 特性 | 说明 |
|---|---|
| GraalVM 强力驱动 | 拥抱最新 ECMAScript 标准，告别老旧的 Rhino/Nashorn，享受现代 JS 语法和 GraalJS 运行时能力。 |
| TypeScript & JSX 本体支持 | 内置 .ts 可擦除 TypeScript 前端和轻量 .jsx/.tsx classic runtime lowering，无需额外编译步骤。 |
| 原生 ESM 运行时 | 支持 import/export、live binding、循环依赖、top-level await、import.meta、动态 import()、ESM/CJS 互操作。 |
| Node.js 兼容 API | 内置 fs、path、buffer、process、timers、util、events、assert、os、test 等核心模块 shim。 |
| IDE 智能提示 |
/nekojs probe 一键生成 TypeScript/Python 类型声明（.neko_probe/），无需外部 ProbeJS mod 即可获得补全。 |
| 服务端热重载 |
/nekojs reload 热重载服务端脚本；NeoForge 与 Cleanroom 均支持配方热重载（详见 命令）。 |
| 多平台 | 同时支持 NeoForge 26.1 / 26.2 / 1.21.1，Fabric 26.1 正在移植；Cleanroom 1.12.2（Forge）在独立的 legacy 分支维护。 |
- 安装前置 mod Graal（25.1.3.7 或更高）和 NekoJS，启动游戏。
- 在游戏根目录下会自动生成
nekojs/文件夹。 - 在
nekojs/server_scripts/里新建hello.js：
// server_scripts/hello.js
ServerEvents.started(event => {
console.info('NekoJS 已就绪！')
})- 进入世界，或执行
/nekojs reload，看到日志输出即可。
完整流程见 快速开始。
- 我想写脚本魔改整合包：从 快速开始 开始，然后翻 全局绑定 和 事件参考。
- 我想改配方：参见 配方系统。
- 我想注册新物品/方块/实体：参见 注册新内容。
- 我想用 TS 或拆分多文件模块：参见 TypeScript 与 JSX、模块系统。
- 我遇到报错了：参见 常见问题。
- 我想给 NekoJS 写插件 mod：参见 插件开发。
- 我想了解内部架构：参见 项目架构。
| 平台 | MC 版本 | 加载器 | Java |
|---|---|---|---|
| NeoForge 26.1 | 26.1.2 | NeoForge 26.1.2-beta | 25 |
| NeoForge 26.2 | 26.2.0 | NeoForge 26.2.0-beta | 25 |
| NeoForge 1.21.1 | 1.21.1 | NeoForge 21.1.x | 21 |
| Cleanroom 1.12.2 | 1.12.2 | Cleanroom（Forge）0.5.14-alpha | 25 |
绝大多数脚本 API 跨平台一致；少数 1.12.2 因 API 差异略有不同，文中会标注。Cleanroom 1.12.2 在独立的 legacy 分支维护，与上面三个 NeoForge 版本不在同一个代码库里。
Fabric 26.1 还在移植中，暂无发布版本。运行前置 Graal 需要 25.1.3.7 或更高。