kurenai

Kurenai Studio

PinK 的升级版：项目管理、资源编译、预览、构建在同一产品里。

Agents install only kurenai — no PinK / separate cocos-cli.
The trimmed cocos runtime lives in this repo as vendor/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)

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 bundled vendor/cocos-core runtime, starts game preview, watches assets/ (or polls with WATCH_POLL=1) and exposes /__kurenai/status, /__kurenai/refresh, /__kurenai/asset and /__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 with npm run vendor:slim. npm install / postinstall installs its JS deps (pure JS, no native addons).
• src/preview/controller.ts — starts the host (or attaches to one the CLI started) and puts PreviewBridge in 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) and base-ai-3d project templates plus the shared layer (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-ABI gl / sharp addons)
• No native binaries: audio/video duration is read in pure JS (wav / mp3 / aac / ogg / mp4), kit add unzips 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 start waits up to 600s by default for first-time engine import. Use --timeout <seconds> or KURENAI_HOST_READY_TIMEOUT_MS. On timeout the host is left running — poll with kurenai host status.
• If a killed host left locks, restart clears temp/programming/**/*.lock. Manual recovery: stop host, delete temp/ (and if needed library/), then host start again.
• kurenai publish type-checks assets/ with the vendored TypeScript and fails on type errors; kurenai check runs 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=1 on the host; see docs/docker-watch-poll.md.
• Canvas picking targets 2D UITransform bounds; 3D raycasting is not implemented.
• Materials created from code can only use builtin-unlit; write .mtl files for lit materials.
• Publishing supports web-desktop and web-mobile.
• Each preview host is a full runtime process (~ hundreds of MB RSS); use node scripts/bench-host.mjs on 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.