create-genshin-ts 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-genshin-ts",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Create a Genshin-TS project",
   "type": "module",
   "author": "josStorer <josstorer@outlook.com> (https://github.com/josStorer)",

package/templates/start/AGENTS.md

@@ -4,6 +4,9 @@ This template bootstraps a Genshin-TS project. Maintain it with user workflow an
 
 ## Read First
 - `README.md`: full usage flow, constraints, and global function cheat sheet.
+- `README_ZH.md`: Chinese template guide and terminology reference when working in Chinese.
+- `docs/EDITOR_BOUNDARIES.md`: English decision rules for code-vs-editor responsibilities.
+- `docs/EDITOR_BOUNDARIES_ZH.md`: Chinese boundary rules and preferred editor terminology.
 
 ## Layout
 - `src/main.ts`: default entry example
@@ -17,7 +20,11 @@ This template bootstraps a Genshin-TS project. Maintain it with user workflow an
 2. Add `inject` in `gsts.config.ts` when needed
 3. Run `npm run dev` for incremental compile
 
-## Coding and Maintenance Rules
+## Hard Rules
+- Prefer implementing gameplay logic in code, but do not assume editor-authored resources already exist.
+- Separate every substantial feature into `code changes` and `editor setup required`.
+- Call out blockers clearly when a requested feature needs editor work first.
+- When responding in Chinese, prefer the wording and domain terms from `README_ZH.md` and `docs/EDITOR_BOUNDARIES_ZH.md`.
 - Update `entries` when adding new entry files.
 - Entry events use `g.server({ id }).on(...)`; same ID entries merge automatically.
 - `gstsServer*` must be top-level and only allow a single trailing `return`.

package/templates/start/CLAUDE.md

@@ -4,6 +4,9 @@ This file guides AI to write/modify code and docs in this template. Focus on a c
 
 ## Read First
 - `README.md`: complete usage flow, constraints, and global function cheat sheet.
+- `README_ZH.md`: Chinese template guide and terminology reference when working in Chinese.
+- `docs/EDITOR_BOUNDARIES.md`: English decision rules for code-vs-editor responsibilities.
+- `docs/EDITOR_BOUNDARIES_ZH.md`: Chinese decision rules and preferred editor terminology.
 
 ## Compilation Flow (Debugging)
 1. TS -> `.gs.ts` (node function call form)
@@ -16,6 +19,8 @@ If something is wrong, compare `.gs.ts` and `.json` first.
 - Focus on user-facing steps; explain why when needed.
 - Provide alternatives for edge semantics (e.g., explicit conversions).
 - Do not edit `dist/` outputs by hand.
+- Prefer code for runtime logic, but explicitly list editor-authored prerequisites whenever a feature depends on them.
+- Do not infer editor capabilities from API names alone when local editor references are available.
 
 ## Scope Rules (Critical)
 - Top-level scope: OK to use npm/local files for precompute; do not call `g.server` or `gsts` runtime APIs here.
@@ -56,6 +61,16 @@ If something is wrong, compare `.gs.ts` and `.json` first.
 - `g.server({ variables: { ... } })` declares graph variables with typed `f.get` / `f.set`.
 - `g.server({ lang: 'zh' })` enables Chinese event names and function aliases.
 
+## Hard Rules
+- For any non-trivial feature, state:
+  - what can be implemented in code now
+  - what still requires manual editor setup
+- Components are editor-authored unless verified otherwise.
+- Normal timers can be created in node graphs; global timers must be defined in the editor first.
+- Prefab creation uses existing authored prefab resources; it does not replace asset authoring.
+- Shop, currency, backpack, UI layout/control groups, signal definitions, text bubbles, minimap markers, and ability units usually require editor setup first.
+- When responding in Chinese, prefer the terminology used in `README_ZH.md` and `docs/EDITOR_BOUNDARIES_ZH.md`.
+
 ## Common Commands
 - `npm run dev`: incremental compile (auto inject if configured)
 - `npm run build`: full compile
@@ -64,3 +79,4 @@ If something is wrong, compare `.gs.ts` and `.json` first.
 ## Look Up Function/Event Notes
 - Search `node_modules/genshin-ts/dist/src/definitions/` with keywords.
 - Chinese and English alias keywords are supported.
+- If local editor reference docs are available in the workspace, use them as the preferred source for editor-side behavior.

package/templates/start/README.md

@@ -16,6 +16,8 @@ Docs: `https://gsts.moe`
 - `src/main.ts`: entry example (`g.server(...).on(...)`)
 - `gsts.config.ts`: compile/output configuration
 - `dist/`: build outputs (`.gs.ts` / `.json` / `.gia`)
+- `docs/EDITOR_BOUNDARIES.md`: English code-vs-editor responsibility guide
+- `docs/EDITOR_BOUNDARIES_ZH.md`: Chinese code-vs-editor responsibility guide and terminology reference
 - `CLAUDE.md` / `AGENTS.md`: AI collaboration notes (read first)
 
 ## Injection Config Example (Optional)
@@ -43,6 +45,22 @@ Notes:
 - Fill `gameRegion` / `playerId` when you have multiple regions/accounts.
 - Injection automatically creates backups for rollback.
 
+## Editor Boundary
+
+This template is intentionally code-first, but many capabilities in Miliastra / Genshin UGC still require editor-authored setup.
+
+Language entry:
+- Use this file together with `docs/EDITOR_BOUNDARIES.md` when working in English.
+- When working in Chinese, switch to `README_ZH.md` and `docs/EDITOR_BOUNDARIES_ZH.md` so terminology stays consistent.
+
+- Use code for runtime rules: gameplay flow, state machines, wave logic, economy, validation, spawning, settlement, and signal orchestration.
+- Use the editor for authored resources and configuration: prefabs, components, paths, UI layouts/control groups, signals, global timers, shops, currencies, ability units, text bubbles, minimap markers, and audio assets.
+- Before proposing or implementing a feature, check `docs/EDITOR_BOUNDARIES.md` and explicitly separate:
+  - code changes
+  - editor setup still required
+- If local editor reference docs are available in the workspace, prefer them as the local source of truth for editor-side behavior.
+- When working in Chinese, prefer `README_ZH.md` and `docs/EDITOR_BOUNDARIES_ZH.md` so domain terms stay idiomatic.
+
 ## Entry and Event Style
 
 ```ts

package/templates/start/README_ZH.md

@@ -16,6 +16,8 @@ npm run dev
 - `src/main.ts`：入口示例（`g.server(...).on(...)`）
 - `gsts.config.ts`：编译与输出配置
 - `dist/`：编译产物（`.gs.ts` / `.json` / `.gia`）
+- `docs/EDITOR_BOUNDARIES.md`：英文版代码与编辑器职责边界说明
+- `docs/EDITOR_BOUNDARIES_ZH.md`：中文版代码与编辑器职责边界说明与术语参考
 - `CLAUDE.md` / `AGENTS.md`：AI 协作指引（建议先读）
 
 ## 注入配置示例（可选）
@@ -44,6 +46,22 @@ export default config
 - 多账号/多服务器时填写 `gameRegion` / `playerId` 以定位地图目录。
 - 注入会自动做备份，便于回滚。
 
+## 编辑器边界
+
+这个模板默认采用“代码优先”的开发方式，但千星奇域 / Genshin UGC 中仍有不少能力必须先由编辑器手动配置。
+
+语言入口：
+- 以中文协作时，优先阅读本文件与 `docs/EDITOR_BOUNDARIES_ZH.md`。
+- 若以英文协作，则切换到 `README.md` 与 `docs/EDITOR_BOUNDARIES.md`。
+
+- 代码优先负责运行时规则：玩法流程、状态机、波次逻辑、经济结算、校验、刷怪、结算、信号编排。
+- 编辑器负责资源与配置：元件、组件、路径、界面布局/控件组、信号、全局计时器、商店、货币、能力单元、文本气泡、小地图标识、音频资源等。
+- 在设计或实现功能前，先查看 `docs/EDITOR_BOUNDARIES_ZH.md`，并明确区分：
+  - 代码改动
+  - 仍需手动完成的编辑器配置
+- 若工作区中存在本地编辑器参考文档，优先以其为准，不要只根据 API 名称猜测编辑器能力。
+- 若以中文进行开发沟通，优先沿用本文件与 `docs/EDITOR_BOUNDARIES_ZH.md` 中的术语，避免临时翻译导致表达不地道。
+
 ## 入口与事件写法
 
 ```ts

package/templates/start/docs/EDITOR_BOUNDARIES.md

@@ -0,0 +1,60 @@
+# Editor Boundaries
+
+This template is code-first, but not editor-free. AI should prefer implementing gameplay rules in code while clearly separating runtime logic from editor-authored resources and configuration.
+
+Language note:
+- Use this file when working in English.
+- When working in Chinese, prefer `docs/EDITOR_BOUNDARIES_ZH.md` so editor and gameplay terminology stays idiomatic.
+
+## Core Rule
+- Prefer code for runtime logic: state machines, timers, wave flow, economy, validation, spawning, destruction, settlement, and signal-driven orchestration.
+- Do not assume editor resources already exist. If a feature depends on editor-authored assets, components, templates, or IDs, call that out explicitly.
+- Do not describe editor capabilities from guesswork. If local editor references exist, check them first.
+
+## What Must Be Done In The Editor
+- Scene and map setup: terrain, spawn points, revive points, navigation, placed entities, layout, decoration.
+- Node graph containers and injection targets: the target NodeGraph must already exist and be saved in the map.
+- Prefabs / prefab groups / assets: buildings, enemies, drops, effects, UI assets, audio assets, icons.
+- Component attachment and base configuration: components can be configured in the editor and used by code, but are not created dynamically at runtime.
+- Paths, patrols, and baked navigation-related content.
+- UI layout, UI control groups, interaction buttons, timer controls, scoreboard controls.
+- Signal definitions in the sandbox signal manager.
+- Global timer definitions in the global timer manager.
+- Shop templates, currency definitions, backpack templates, and shop components.
+- Ability units, combat presets, and other battle-side authored data.
+- Text bubbles, minimap markers, sound-effect players, nameplates, and similar presentation resources.
+
+## What Should Usually Be Implemented In Code
+- Game phases and state transitions.
+- Build / occupy / unlock logic.
+- Economy calculations, rewards, prices, and production cycles.
+- Wave scheduling, spawn sequencing, and alive-count tracking.
+- Runtime prefab creation, removal, and settlement triggers.
+- UI visibility switching, control-group activation, and button event handling.
+- Signal routing and cross-entity coordination.
+
+## Critical Boundary Notes
+- Components are editor-authored. Runtime logic may toggle or modify some component behavior, but should not assume components can be added or removed during play.
+- Normal timers can be created directly in node graphs.
+- Global timers must be defined in the editor first; code only references them by name.
+- `createPrefab` / `createPrefabGroup` create authored prefab resources at runtime; they do not create new editor assets.
+- Shop flow is not "open from nothing". It requires editor-authored currency, shop templates, backpack support, and a shop component.
+- If using standard attack flow, authored ability units are required. If those are missing, code may need a simpler fallback such as direct HP loss.
+
+## AI Working Rules
+- For any feature request, separate the answer into:
+  - code changes
+  - editor setup still required
+- If blocked by missing editor setup, say exactly what is missing instead of silently assuming it exists.
+- When proposing a design, choose the most code-driven approach that still respects editor boundaries.
+- If local editor reference docs are available in the workspace, prefer them as the factual source for editor behavior before making claims.
+- When responding in Chinese, prefer the terminology used by the Chinese docs rather than ad hoc English-to-Chinese translation.
+
+## Suggested Response Pattern
+- First state what can be implemented in code now.
+- Then list the minimum editor configuration required.
+- Then note any assumptions about IDs, templates, authored components, or assets.
+
+## Optional Reference
+- For broader editor-side documentation and terminology, you may consult [Miliastra-knowledge](https://github.com/1475505/Miliastra-knowledge).
+- If local editor docs exist in the workspace, prefer those as the primary source of truth. This repository is supplemental, not a template dependency.

package/templates/start/docs/EDITOR_BOUNDARIES_ZH.md

@@ -0,0 +1,60 @@
+# 编辑器边界
+
+这个模板采用“代码优先”的开发方式，但并不意味着可以脱离编辑器独立完成全部功能。AI 应优先用代码实现玩法逻辑，同时清晰区分运行时逻辑与编辑器预先制作的资源和配置。
+
+语言说明：
+- 以中文协作时，优先阅读本文件。
+- 若以英文协作，可配合 `docs/EDITOR_BOUNDARIES.md` 使用。
+
+## 核心原则
+- 优先用代码处理运行时逻辑：状态机、定时器、波次流程、经济结算、校验、创生/销毁、结算和信号编排。
+- 不要假设编辑器资源一定已经存在。若某项功能依赖编辑器内预先制作的资源、组件、模板或 ID，必须明确指出。
+- 不要仅根据 API 名称猜测编辑器能力；若工作区存在本地编辑器参考文档，应先查证。
+
+## 必须在编辑器中完成的内容
+- 场景与地图设置：地形、出生点、复苏点、导航、实体摆放、布局、装饰。
+- 节点图容器与注入目标：目标 NodeGraph 必须先在地图中创建并保存。
+- 元件 / 元件组 / 资产：建筑、敌人、掉落物、特效、UI 资源、音频资源、图标。
+- 组件挂载与基础配置：组件需要先在编辑器里挂到实体或元件上，代码只能使用或调整已有组件。
+- 路径、巡逻以及需要烘焙/预处理的导航相关内容。
+- 界面布局、界面控件组、交互按钮、计时器控件、计分板控件。
+- 千星沙箱中的信号定义。
+- 全局计时器管理器中的全局计时器定义。
+- 商店模板、货币定义、背包模板、商店组件。
+- 能力单元、战斗预设及其他战斗侧预配置数据。
+- 文本气泡、小地图标识、音效播放器、铭牌等表现资源。
+
+## 通常更适合在代码中实现的内容
+- 游戏阶段与状态切换。
+- 建造 / 占位 / 解锁逻辑。
+- 经济计算、奖励、价格、生产周期。
+- 波次调度、刷怪顺序、存活数量统计。
+- 运行时创建元件、移除实体、触发结算。
+- UI 显隐切换、控件组激活、按钮事件响应。
+- 信号收发与多实体协作。
+
+## 关键边界说明
+- 组件属于编辑器预配置内容。运行时代码可以切换或修改部分组件行为，但不应假设可以在局内动态添加或删除组件。
+- 普通定时器可以直接在节点图中创建。
+- 全局计时器必须先在编辑器中定义，代码只能按名称引用。
+- `createPrefab` / `createPrefabGroup` 是在运行时创生已经制作好的元件资源，不是动态创建新的编辑器资产。
+- 商店不是“空开”。要能正常使用，必须先有货币、商店模板、背包支持和商店组件。
+- 若走标准攻击链路，则需要先在编辑器中配置能力单元；若缺失这些预设，代码可能需要退回到更简单的直接扣血方案。
+
+## AI 工作规则
+- 对任何功能需求，都应显式拆成：
+  - 代码改动
+  - 仍需手动完成的编辑器配置
+- 若受限于缺少编辑器配置，不要默认其存在；应明确指出缺了什么。
+- 做设计时，优先选择“尽量由代码驱动、但不越过编辑器边界”的方案。
+- 若工作区内有本地编辑器参考文档，优先以其为准，再对编辑器行为做判断。
+- 若用中文回答，应优先沿用中文文档中的官方或社区常用术语，不要临时直译英文术语。
+
+## 建议回答格式
+- 先说明哪些部分现在就可以用代码实现。
+- 再列出最小编辑器配置清单。
+- 最后说明对 ID、模板、预挂组件、资源等的假设。
+
+## 可选参考
+- 如需查阅更完整的编辑器侧资料与术语，可参考 [Miliastra-knowledge](https://github.com/1475505/Miliastra-knowledge)。
+- 若工作区内已有本地编辑器文档，优先以本地文档为准；该仓库仅作为补充参考，不是模板依赖。