Kurenai Studio
PinK 的升级版:项目管理、资源编译、预览、构建在同一产品里。
Agents install only kurenai — no PinK / separate cocos-cli.
The trimmed cocos runtime lives in this repo asvendor/cocos-core.
One-liner (for agents)
Paste only this; everything else is in the linked doc:
Download and follow https://raw.githubusercontent.com/kurenai-studio/kurenai/main/docs/getting-started.md (Kurenai / Creator 4.0).
If the repo is already cloned: Read kurenai/docs/getting-started.md and follow it exactly.
Longer Chinese prompt (same rules):
自学并只用最新 kurenai(https://github.com/kurenai-studio/kurenai:clone 后 Node.js 22+ 下 `npm install && npm link`;不要单独安装完整 cocos-cli / PinK)开发 Cocos 游戏:`kurenai init`(3D 用 `--3d`)→ `host start` → 按项目 `AGENTS.md` 只改 `assets/game/` 与 `assets/resources/`,用 `import` / `asset info` / `logs` / `context` 闭环,`.meta` 由引擎生成、不要手写;`.prefab` / `.mtl` 可以直接手写,但 prefab 里不挂脚本组件,行为写在 TS 里用 `addComponent` 挂上;交付时再 `kurenai publish --platform web-desktop`。
入口:docs/getting-started.md · docs/rendering.md · docs/安装方法.md · docs/简单使用方法.md
Product shape
kurenai
├─ CLI / inspector / templates (agent 面)
└─ vendor/cocos-core (裁剪后的运行时:asset-db + preview + web build)
四个核心能力在一起:项目管理 · 资源编译 · 预览 · 构建。
Agent writes files under assets/ (prefabs, materials, TypeScript views)
→ host watcher → asset-db refresh (.meta, import, compile)
→ live reload refreshes the preview
→ agent imports assets and reads uuids / errors through `kurenai import` / `asset info` / `logs`
Prefabs describe structure and look and carry no scripts; code loads them by
path and attaches behaviour with addComponent(View).bind(root). .meta files
are always written by the engine. The rules agents follow live in
templates/shared/AGENTS.md, copied into every
new project.
Related tools (do not mix)
| Tool | Engine | Repo |
|---|---|---|
| Kurenai | Creator 4.0 (this package) | preview + publish |
| Enji | Creator 3.8 | kurenai-studio/enji — preview/edit, no publish, 3.8 .meta caps |
| Akane | — | reserved name, unassigned |
Do not run kurenai on a 3.8 project (risk of 4.0-oriented meta / publish). Use Enji instead.
TODO
- Creator 3.8 工作流:独立仓库 Enji(不进本仓)
- 按 Enji 的裁法重切 vendor:
scripts/slim-vendor.mjs(工作树约 515 MB,原先约 1.4 GB;Enji 约 505 MB。多留 Web 构建器与引擎源码) - 从 Enji 回灌:报错对回、3D 模板、
docs/rendering.md、--3d、getting-started - 预览缓存:保留 editor(Node 预加载)+ web(浏览器);相同文件硬链,只占一份
- Creator 2.x:暂缓,不做 2.x 升级工具(Akane 名称保留)
- 核心构建包拆出:引擎源码 / 首次 publish 的 engine
npm install按需下,开发包再靠近 500 MB - 优化构建:包括自动资源优化等
Pieces
bin/kurenai.mjs— the CLI (see below).bin/kurenai-cocos-host.mjs— one long-lived process per project. Loads the bundledvendor/cocos-coreruntime, starts game preview, watchesassets/(or polls withWATCH_POLL=1) and exposes/__kurenai/status,/__kurenai/refresh,/__kurenai/assetand/__kurenai/logs. Advertises itself in<project>/temp/kurenai-host.json.vendor/cocos-core/— trimmed like Enji (asset-db, preview, web builders, engine sources for publish). Refresh withnpm run vendor:slim.npm install/postinstallinstalls its JS deps (pure JS, no native addons).src/preview/controller.ts— starts the host (or attaches to one the CLI started) and putsPreviewBridgein front of it.src/preview/bridge.ts— reverse proxy that injects the inspector and keeps every preview request on the bridge origin.src/project/control.ts— project detection, template initialization, selection context and publish (web-desktop/web-mobile).src/inspector-runtime/— browser runtime for scene tree, selection and 2D hit testing.templates/—base-ai(2D) andbase-ai-3dproject templates plus thesharedlayer (Boot entry, helpers,AGENTS.md).
Requirements
- Node.js 22+ (22 / 24 both fine for the current portable stack: image ops are pure JS
portable-sharp/ jimp; no Node-ABIgl/sharpaddons) - No native binaries: audio/video duration is read in pure JS (wav / mp3 / aac / ogg / mp4),
kit addunzips in pure JS. Works the same on macOS, Windows and Linux. - 默认路径不需要 PinK / 完整 cocos-cli
Optional override for tests only: KURENAI_COCOS_CLI_ROOT pointing at a custom tree.
Install notes
kurenai host startwaits up to 600s by default for first-time engine import. Use--timeout <seconds>orKURENAI_HOST_READY_TIMEOUT_MS. On timeout the host is left running — poll withkurenai host status.- If a killed host left locks, restart clears
temp/programming/**/*.lock. Manual recovery: stop host, deletetemp/(and if neededlibrary/), thenhost startagain. kurenai publishtype-checksassets/with the vendored TypeScript and fails on type errors;kurenai checkruns the same check in about a second.
Install
Not published to npm; install from GitHub:
git clone https://github.com/kurenai-studio/kurenai.git
cd kurenai
npm install # also prepares vendor/cocos-core deps
npm link # optional: puts `kurenai` on PATH
lib/ is committed, so no build step is needed to use the CLI. First
npm install may take a few minutes (runtime dependencies).
CLI
kurenai init ./my-game --template base-ai-3d
cd my-game
kurenai host start # background preview host; prints the preview URL
# kurenai host start --timeout 1200 # wait up to 20 minutes for first import
kurenai host status # poll readiness if start wait expired
kurenai import assets/resources/materials/red.mtl # import + uuid / sub-assets
kurenai asset info assets/resources/materials/red.mtl # read existing .meta only
kurenai kit add ks-survivor-kit # kit folder, zip or Kura pack id -> assets/resources/kits/<kit>/
kurenai check # type-check assets/ (preview does not)
kurenai logs --errors # errors since the last good preview boot (--all: older too)
kurenai context # project state + AGENTS.md
kurenai publish --platform web-desktop --release --out ./dist
kurenai host stop
Commands that need the host start it when it is not running. Output is JSON.
publish may warn if tsc is not on PATH; the web build can still succeed.
Puzzle demo (M2 acceptance)
From a clean clone, node scripts/run-puzzle.mjs creates a temp 2D project
(base-ai), writes a generated assets/resources/images/puzzle.png, a
script-free PuzzleTile prefab, and MainView / PuzzleTileView (3×3 slice
swap until the picture is restored). It runs kurenai asset info on the image
and prefab (prints uuids), then starts the preview host.
Manual check after the host starts: open the printed previewUrl, tap one tile
then another to swap slices; when all nine are in the correct order the status
line shows Complete!
Options: --dir <path> for a fixed project directory, --no-host to skip the
host, --cleanup to remove the temp project (and stop the host) when finished.
Host benchmark (RSS / ready time)
node scripts/bench-host.mjs initializes a temp project (default
base-ai-3d), runs kurenai host start, prints JSON with wall time to
ready and host process RSS (via ps), then stops the host. Uses the bundled
vendor/cocos-core runtime. Pass --concurrent to start two hosts on ports
7460/7461; --cleanup removes temp dirs.
Library
import { ProjectControl } from "@kurenai-studio/kurenai";
const control = new ProjectControl({ scene: "db://assets/main.scene" });
await control.initialize("/path/to/new-game", "base-ai-3d");
const preview = await control.startPreview("/path/to/new-game");
console.log(preview.url); // bridge URL with the inspector injected
await control.publish("/path/to/new-game", { platform: "web-desktop" });
await control.stopServer(); // stops the bridges and any hosts it started
Development
npm install
npm run check
Maintainer refresh of the bundled runtime (from a full install source):
npm run vendor:cocos
CI runs npm run check on pull requests to main (see .github/workflows/check.yml).
Agent swarm
Parallel workers claim GitHub issues labeled swarm:available. Claim, branch, PR, and
manager review rules live in docs/SWARM.md.
Limitations
- In Docker (bind-mounted project dirs), set
WATCH_POLL=1on the host; seedocs/docker-watch-poll.md. - Canvas picking targets 2D
UITransformbounds; 3D raycasting is not implemented. - Materials created from code can only use
builtin-unlit; write.mtlfiles for lit materials. - Publishing supports
web-desktopandweb-mobile. - Each preview host is a full runtime process (~ hundreds of MB RSS); use
node scripts/bench-host.mjson your machine for repeatable numbers.
License
Kurenai Studio source is MIT licensed. The bundled vendor/cocos-core tree
(Cocos / cocos-cli derived runtime) remains under its upstream licenses.
No comments yet. Be the first to write one.