create-genshin-ts 0.1.0

package/README.md

@@ -0,0 +1,9 @@
+# create-genshin-ts
+
+Scaffold a Genshin-TS project.
+
+## Usage
+
+```bash
+npm create genshin-ts
+```

package/bin/create-genshin-ts.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import readline from 'node:readline'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const args = process.argv.slice(2)
+const flags = new Set(args.filter((arg) => arg.startsWith('--')))
+const nameArg = args.find((arg) => !arg.startsWith('--')) ?? ''
+const force = flags.has('--force')
+
+const toPackageName = (input) => {
+  const base = input.trim().toLowerCase()
+  const sanitized = base
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-._]/g, '-')
+    .replace(/^-+/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^[_\.]+/g, '')
+  return sanitized || 'gsts-project'
+}
+
+const prompt = async (question) => {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  })
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close()
+      resolve(answer)
+    })
+  })
+}
+
+const resolveTargetDir = async () => {
+  if (nameArg) return nameArg
+  const answer = await prompt('Project name: ')
+  return answer.trim()
+}
+
+const replacePlaceholders = (content, values) => {
+  return content
+    .replace(/__PROJECT_NAME__/g, values.projectName)
+    .replace(/__PACKAGE_NAME__/g, values.packageName)
+}
+
+const copyDir = async (sourceDir, targetDir, values) => {
+  await fs.mkdir(targetDir, { recursive: true })
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true })
+  for (const entry of entries) {
+    const srcPath = path.join(sourceDir, entry.name)
+    const targetName = entry.name === '_gitignore' ? '.gitignore' : entry.name
+    const destPath = path.join(targetDir, targetName)
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath, values)
+    } else {
+      const raw = await fs.readFile(srcPath, 'utf8')
+      const content = replacePlaceholders(raw, values)
+      await fs.writeFile(destPath, content, 'utf8')
+    }
+  }
+}
+
+const run = async () => {
+  const projectName = await resolveTargetDir()
+  if (!projectName) {
+    console.error('Project name is required.')
+    process.exit(1)
+  }
+
+  const targetDir = path.resolve(process.cwd(), projectName)
+  try {
+    const stat = await fs.stat(targetDir)
+    if (stat.isDirectory()) {
+      const existing = await fs.readdir(targetDir)
+      if (existing.length > 0 && !force) {
+        console.error('Target directory is not empty. Use --force to overwrite.')
+        process.exit(1)
+      }
+    }
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err
+  }
+
+  const values = {
+    projectName,
+    packageName: toPackageName(path.basename(projectName))
+  }
+
+  const templateDir = path.resolve(__dirname, '../templates/start')
+  await copyDir(templateDir, targetDir, values)
+
+  console.log(`\nCreated ${values.projectName}`)
+  console.log('\nNext steps:')
+  console.log(`  cd ${values.projectName}`)
+  console.log('  npm install')
+  console.log('  npm run dev')
+}
+
+run().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "create-genshin-ts",
+  "version": "0.1.0",
+  "description": "Create a Genshin-TS project",
+  "type": "module",
+  "bin": {
+    "create-genshin-ts": "bin/create-genshin-ts.mjs"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md"
+  ]
+}

package/templates/start/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true

package/templates/start/.prettierrc.js

@@ -0,0 +1,12 @@
+export default {
+  singleQuote: true,
+  semi: false,
+  printWidth: 100,
+  trailingComma: 'none',
+  endOfLine: 'lf',
+  tabWidth: 2,
+  importOrder: ['', '<BUILTIN_MODULES>', '', '<THIRD_PARTY_MODULES>', '', '^[./]'],
+  importOrderParserPlugins: ['typescript', 'jsx', 'decorators-legacy'],
+  importOrderTypeScriptVersion: '5.0.0',
+  plugins: ['@ianvs/prettier-plugin-sort-imports']
+}

package/templates/start/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
+}

package/templates/start/.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+  "editor.formatOnSave": true,
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "search.exclude": {
+    "package-lock.json": true
+  },
+  "files.eol": "\n"
+}

package/templates/start/AGENTS.md

@@ -0,0 +1,48 @@
+# Repository Guidelines
+
+This template bootstraps a Genshin-TS project. Maintain it with user workflow and compile outputs in mind.
+
+## Read First
+- `README.md`: full usage flow, constraints, and global function cheat sheet.
+
+## Layout
+- `src/main.ts`: default entry example
+- `gsts.config.ts`: compile config (entries/outDir/inject)
+- `dist/`: build outputs (generated)
+- `README.md`: user guide
+- `CLAUDE.md`: AI rules
+
+## Typical Workflow
+1. Update the NodeGraph ID in `src/main.ts`
+2. Add `inject` in `gsts.config.ts` when needed
+3. Run `npm run dev` for incremental compile
+
+## Coding and Maintenance Rules
+- 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`.
+- Avoid Promise/async/recursion/JSON/Object in graph scope.
+- Conditions must be `boolean`; use `bool(...)` when needed.
+- Use `bigint` for integer ops; avoid modulo/bitwise on `number`.
+- `while(true)` is capped; use timers or explicit counters.
+- Empty arrays must have inferable element types.
+- Logging: use `print(str(...))` or `console.log(x)` (single argument).
+- Use type helpers when needed: `int/float/str/bool/vec3/configId/prefabId/entity`.
+
+## Node Graph Variables
+- Declare with `g.server({ variables: { ... } })`.
+- Read/write via `f.get` / `f.set`, keep types aligned.
+
+## Debugging Outputs
+- `.gs.ts`: verify compiled node calls
+- `.json`: verify connections and types
+- `.gia`: final injectable output
+
+## Common Scripts
+- `npm run dev`
+- `npm run build`
+- `npm run maps`
+- `npm run backup`
+
+## Reference Definitions
+- Search function/event comments in `node_modules/genshin-ts/dist/src/definitions/`.

package/templates/start/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+This file guides AI to write/modify code and docs in this template. Focus on a compileable, injectable, and verifiable user workflow.
+
+## Read First
+- `README.md`: complete usage flow, constraints, and global function cheat sheet.
+
+## Compilation Flow (Debugging)
+1. TS -> `.gs.ts` (node function call form)
+2. `.gs.ts` -> IR `.json` (nodes and connections)
+3. IR -> `.gia` (injectable output)
+
+If something is wrong, compare `.gs.ts` and `.json` first.
+
+## Scope and Principles
+- 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.
+
+## Scope Rules (Critical)
+- Top-level scope: OK to use npm/local files for precompute; do not call `g.server` or `gsts` runtime APIs here.
+- Node graph scope (`g.server().on(...)` / `gstsServer*`): only a supported TS subset.
+  - Common APIs have type hints (events, entities, Math/Vector3, etc).
+  - If string concat/native objects fail, move to top-level precompute.
+
+## gstsServer Constraints
+- Only top-level `gstsServer*` functions are recognized.
+- Params must be identifiers (no destructuring/default/rest).
+- Only a single trailing `return <expr>` is allowed.
+- Calls only inside `g.server().on(...)` or another `gstsServer*`.
+
+## Syntax and Type Guidance
+- Conditions must be `boolean`; use `bool(...)` if needed.
+- `number` is float, `bigint` is int; use `bigint` for integer ops.
+- Lists/dicts must be homogeneous; mixed types will fail.
+- Empty arrays may not infer a type; add a typed placeholder.
+- `dict(...)` is read-only; use graph variables for mutable dicts (`f.get` / `f.set`).
+- `Object.*` / `JSON.*` are usually unsupported in graph scope; precompute or use `raw(...)` (compiler ignores, JS semantics).
+- No Promise/async/await or recursion (errors or ESLint warnings).
+- `while(true)` is capped; use timers or explicit counters.
+
+## Timers
+- Use `setTimeout` / `setInterval` (milliseconds).
+- Compiler builds timer pools; override with `// @gsts:timerPool=4`.
+- `setInterval` <= 100ms triggers a performance warning.
+- Timer callbacks support by-value captures; dict captures are not supported.
+
+## Global Function Preferences
+- Logging: prefer `print(str(...))` or `console.log(x)` (single argument only).
+- Type helpers: `int/float/str/bool/vec3/configId/prefabId/guid/faction/entity`.
+- Collections: `list('int', [...])`, `dict(...)` (read-only).
+- Unity-style APIs: `Math` / `Mathf` / `Vector3` / `Random` / `GameObject`.
+- Global entities: `player(1)` / `stage` / `level` / `self`.
+
+## Variables and Language Hints
+- `g.server({ variables: { ... } })` declares graph variables with typed `f.get` / `f.set`.
+- `g.server({ lang: 'zh' })` enables Chinese event names and function aliases.
+
+## Common Commands
+- `npm run dev`: incremental compile (auto inject if configured)
+- `npm run build`: full compile
+- `npm run maps`: list maps
+
+## Look Up Function/Event Notes
+- Search `node_modules/genshin-ts/dist/src/definitions/` with keywords.
+- Chinese and English alias keywords are supported.

package/templates/start/README.md

@@ -0,0 +1,248 @@
+# __PROJECT_NAME__
+
+This is a Genshin-TS project template. You can write logic in TypeScript, compile it into a node graph, and inject it into a map.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+Docs: `https://gsts.moe`
+
+## Project Layout
+
+- `src/main.ts`: entry example (`g.server(...).on(...)`)
+- `gsts.config.ts`: compile/output configuration
+- `dist/`: build outputs (`.gs.ts` / `.json` / `.gia`)
+- `CLAUDE.md` / `AGENTS.md`: AI collaboration notes (read first)
+
+## Injection Config Example (Optional)
+
+```ts
+import type { GstsConfig } from 'genshin-ts'
+
+const config: GstsConfig = {
+  compileRoot: '.',
+  entries: ['./src'],
+  outDir: './dist',
+  inject: {
+    gameRegion: 'China',
+    playerId: 1,
+    mapId: 1073741849,
+    nodeGraphId: 1073741825
+  }
+}
+
+export default config
+```
+
+Notes:
+- `npm run maps` lists recently saved maps to help locate `mapId`.
+- Fill `gameRegion` / `playerId` when you have multiple regions/accounts.
+- Injection automatically creates backups for rollback.
+
+## Entry and Event Style
+
+```ts
+import { g } from 'genshin-ts/runtime/core'
+
+g.server({ id: 1073741825 }).on('whenEntityIsCreated', (_evt, f) => {
+  const p = player(1)
+  f.printString(str(p.guid))
+})
+```
+
+Key points:
+- `id` is the target NodeGraph ID; entries with the same ID are merged.
+- Event names use string literals (Chinese aliases are supported).
+- `f` is the node graph function entry; use it for output and variables.
+- You can chain multiple events: `g.server(...).on(...).onSignal(...)`.
+
+## g.server Options (Injection Safety)
+
+Common options:
+- `id`: target NodeGraph ID (injection must match this ID).
+- `name`: graph display name; defaults to entry filename.
+- `prefix`: auto add `_GSTS_` prefix (default true).
+- `type`: graph type (default server/entity).
+- `variables`: declare graph variables and enable `f.get` / `f.set`.
+- `lang`: set `'zh'` to enable Chinese event names and function aliases.
+
+Injection safety rules:
+- The target `id` must exist in the map.
+- The target graph must be empty or its name must start with `_GSTS`, otherwise injection is blocked.
+- If you know what you are doing, set `inject.skipSafeCheck = true` in `gsts.config.ts`.
+- After creating a new graph, you must save the map for the injector to detect the `id`.
+- Recommended: create and save a batch of graphs first, then compile/inject once.
+
+## gsts.config Optimize Options (Enabled by Default)
+
+`gsts.config.ts` uses `options.optimize` with all defaults on:
+- `precompileExpression`: precompute literal-only expressions.
+- `removeUnusedNodes`: remove unused exec/data nodes.
+- `timerPool`: name pool size for `setTimeout` / `setInterval`.
+- `timerDispatchAggregate`: aggregate timer dispatch to reduce complexity.
+
+Disable an option temporarily if you need to debug or compare graphs.
+
+## Typical Usage and Constraints (AI Must Read)
+
+### Scope Split
+
+- **Top-level scope (compile-time)**: OK to read files, use npm libs, precompute data; do not call `g.server` or `gsts` runtime APIs here.
+- **Node graph scope (runtime)**: only a supported TS subset; logic is compiled into node graphs.
+
+### Control Flow and Returns
+
+- `if/while/switch` conditions must be `boolean`; use `bool(...)` if needed.
+- `gstsServer*` functions allow only a **single trailing `return <expr>`**.
+- Recursion, `async/await`, and Promise are not supported in node graph scope.
+- `while(true)` is limited by a loop cap; use timers or explicit counters instead.
+- `!` and ternary require boolean conditions.
+
+### Numbers and Types
+
+- `number` is **float**; `bigint` is **int**.
+- Use `bigint` for modulo/bitwise operations.
+- Lists/dicts must be homogeneous; mixed types will fail.
+- Empty arrays may not infer a type; add a typed placeholder or use `list(...)`.
+- Prefer explicit helpers: `int`, `float`, `vec3`, `configId`, `prefabId`, `entity`, etc.
+- `dict(...)` creates a read-only dict; use graph variables for mutable dicts.
+- Use `let` to force a local variable node; `const` may be optimized into direct wiring.
+
+### Global Functions and Variables Cheat Sheet (Preferred for AI)
+
+Logging and debug:
+- `print(str(...))`: most stable logging.
+- `console.log(x)`: **single argument only**, auto-rewritten to `print(str(...))`.
+- `f.printString(...)`: explicit node call for strict graph alignment.
+
+Type helpers:
+- `bool(...)` / `int(...)` / `float(...)` / `str(...)`
+- `vec3(...)` / `guid(...)` / `prefabId(...)` / `configId(...)` / `faction(...)` / `entity(...)`
+- `list('int', items)`: explicit list typing (critical for empty arrays).
+- `dict(...)`: read-only dict.
+- `raw(...)`: compiler ignores it; JS native semantics apply.
+
+Entities and scene:
+- `player(1)`: player entity (starts from 1).
+- `stage` / `level`: stage entity aliases.
+- `self`: current graph entity.
+- `GameObject.Find(...)` / `FindWithTag(...)` / `FindByPrefabId(...)`
+
+Math and vectors:
+- `Math.*`: compiled to node graph equivalents in server scope.
+- `Mathf.*` / `Vector3.*` / `Random.*`: Unity-style APIs.
+
+Signals and events:
+- `send('signalName')` with `g.server().onSignal(...)`.
+
+Timers:
+- `setTimeout` / `setInterval` / `clearTimeout` / `clearInterval`.
+
+Common methods:
+- Many array/string methods (`map`/`filter`/`find`/`length`) are supported; rely on type hints.
+
+### Node Graph Variables (Writable)
+
+```ts
+g.server({
+  id: 1073741825,
+  variables: { counter: 0n },
+  lang: 'zh'
+}).on('whenEntityIsCreated', (_evt, f) => {
+  const v = f.get('counter')
+  f.set('counter', v + 1n)
+})
+```
+
+Notes:
+- `variables` defines graph variables and enables typed `f.get` / `f.set`.
+- Entity variables are type declarations only (use `entity(0)`).
+- `entity(0)` can also be used as a placeholder to keep entity params empty in the editor.
+
+### Timers
+
+- Use `setTimeout` / `setInterval` (milliseconds).
+- The compiler builds timer name pools to avoid name collisions.
+- Use `// @gsts:timerPool=4` to override pool size (advanced).
+- `setInterval` <= 100ms triggers a performance warning.
+- Timer callbacks support value-based captures; dict captures are not supported.
+
+### Native JS Object Limits
+
+- `Object.*` and `JSON.*` are typically not supported in node graph scope.
+- Move them to top-level precompute, or use `raw(...)`.
+- If string concatenation fails, precompute at top-level or use `str(...)`.
+
+## Reusable Functions (gstsServer)
+
+```ts
+function gstsServerSum(a: bigint, b: bigint) {
+  const total = a + b
+  return total
+}
+
+g.server({ id: 1073741825 }).on('whenEntityIsCreated', (_evt, f) => {
+  const v = gstsServerSum(1n, 2n)
+  f.printString(str(v))
+})
+```
+
+Rules:
+- Must be top-level; params must be identifiers (no destructuring/default/rest).
+- Only a trailing single `return` is allowed.
+- Calls only allowed inside `g.server().on(...)` or another `gstsServer*`.
+- Inside `gstsServer*`, you can use `gsts.f` directly (no need to pass `f`).
+
+## Multi-Entry and Merging
+
+- `entries` in `gsts.config.ts` determines which files compile.
+- Each entry builds a graph; same ID entries are merged.
+- In dev mode, dependency changes recompile affected entries.
+
+## Outputs and Debugging
+
+- `.gs.ts`: expanded node function calls for semantic checking.
+- `.json`: IR for node connections and type checks.
+- `.gia`: final graph output for inject/import.
+
+## Compile-Time Execution Notes
+
+- The compiler scans all entries and compiles `g.server().on(...)` points.
+- Top-level code may execute once or multiple times (incremental builds, multi-entry).
+- Be careful with file I/O or randomness in top-level scope.
+- To temporarily disable a graph injection, set `id` to a non-existent value.
+- Top-level scope is suitable for file loading, precompute, or procedural generation.
+- `stage.set` can be used as a global variable (runtime).
+
+## Scripts
+
+- `npm run build`: full compile
+- `npm run dev`: incremental compile (auto inject if configured)
+- `npm run maps`: list recent maps
+- `npm run backup`: open backup directory
+- `npm run typecheck`: TypeScript type check
+- `npm run lint`: ESLint
+
+Notes:
+- The project includes custom ESLint rules; run `npm run lint` often to catch hidden constraints.
+- `npm run typecheck` helps catch type issues before compile errors.
+- `npm run dev` runs `gsts dev` watch mode only.
+- After injection, reload the map to see changes.
+- Use a temporary empty map to quickly swap and reload.
+- Saving the map before reload can overwrite injected content; re-inject if needed.
+
+## FAQ
+
+- `npm run maps` is empty: save the map in the editor once, then retry.
+- Injection failed: verify `mapId` / `nodeGraphId` and graph type.
+- Type errors: check `.value` usage and pin type alignment first.
+
+## Looking Up Function Notes (AI Friendly)
+
+When type hints are not enough, search in `node_modules/genshin-ts`:
+- Node functions and event definitions: `node_modules/genshin-ts/dist/src/definitions/`
+- Use keywords (event name, function name, Chinese alias) to locate comments and params.

package/templates/start/README_ZH.md

@@ -0,0 +1,262 @@
+# __PROJECT_NAME__
+
+这是一个基于 genshin-ts 的千星奇遇项目模板。你可以用 TypeScript 写逻辑，编译为节点图并注入到地图。
+
+## 快速开始
+
+```bash
+npm install
+npm run dev
+```
+
+文档站：`https://gsts.moe`
+
+## 项目结构
+
+- `src/main.ts`：入口示例（`g.server(...).on(...)`）
+- `gsts.config.ts`：编译与输出配置
+- `dist/`：编译产物（`.gs.ts` / `.json` / `.gia`）
+- `CLAUDE.md` / `AGENTS.md`：AI 协作指引（建议先读）
+
+## 注入配置示例（可选）
+
+```ts
+import type { GstsConfig } from 'genshin-ts'
+
+const config: GstsConfig = {
+  compileRoot: '.',
+  entries: ['./src'],
+  outDir: './dist',
+  inject: {
+    gameRegion: 'China',
+    playerId: 1,
+    mapId: 1073741849,
+    nodeGraphId: 1073741825
+  }
+}
+
+export default config
+```
+
+提示：
+
+- `npm run maps` 可列出最近保存的地图，帮助确定 `mapId`。
+- 多账号/多服务器时填写 `gameRegion` / `playerId` 以定位地图目录。
+- 注入会自动做备份，便于回滚。
+
+## 入口与事件写法
+
+```ts
+import { g } from 'genshin-ts/runtime/core'
+
+g.server({ id: 1073741825 }).on('whenEntityIsCreated', (_evt, f) => {
+  const p = player(1)
+  f.printString(str(p.guid))
+})
+```
+
+要点：
+
+- `id` 是目标节点图 ID；同 ID 的多个入口会自动合并到同一图。
+- 事件名使用字符串字面量（支持中英文名称）。
+- 回调参数中 `f` 是节点图函数入口，优先用它做输出、变量操作等。
+- 可链式注册多个事件：`g.server(...).on(...).onSignal(...)`。
+
+## g.server 参数说明（与注入安全相关）
+
+常用参数：
+
+- `id`：目标节点图 ID（注入必须匹配该 ID）。
+- `name`：节点图显示名称；未指定时默认使用入口文件名。
+- `prefix`：是否自动添加 `_GSTS_` 前缀（默认 true）。
+- `type`：节点图类型（默认 server/entity）。
+- `variables`：声明节点图变量并启用 `f.get` / `f.set`。
+- `lang`：`'zh'` 时启用中文事件名与中文函数别名。
+
+注入安全检查要点：
+
+- 目标 `id` 必须在地图里存在对应节点图。
+- 目标节点图需要是 **空图** 或 **名称以 `_GSTS` 开头**，否则注入会被拦截。
+- 若你明确知道自己在做什么，可在 `gsts.config.ts` 中设置 `inject.skipSafeCheck = true` 跳过检查。
+- 新建节点图后必须 **保存地图**，注入器才能识别该 `id`。
+- 建议先创建好一批节点图并保存，再一次性编译注入；否则可能出现“注入 -> 新建 -> 保存”导致注入内容被覆盖的问题。
+
+## gsts.config 优化配置（默认启用）
+
+`gsts.config.ts` 的 `options.optimize` 默认全开，常见项：
+- `precompileExpression`：预编译纯字面量表达式，减少运行期节点计算。
+- `removeUnusedNodes`：清理未接入事件或未被使用的节点。
+- `timerPool`：控制 `setTimeout` / `setInterval` 的定时器名称池大小。
+- `timerDispatchAggregate`：合并定时器事件分发，减少图复杂度。
+
+如需调试或对比节点图，可临时关闭单项优化。
+
+## 典型用法与限制（AI 必看）
+
+### 作用域划分
+
+- **顶层作用域（编译期）**：可以读取文件、使用 npm 库、做预计算，但不要调用 `g.server` 或 `gsts` 相关 API。
+- **节点图作用域（运行期）**：仅支持可编译的 TS 子集，语义会转换为节点图。
+
+### 控制流与返回值
+
+- `if/while/switch` 条件必须是 `boolean`，需要时用 `bool(...)` 转换。
+- `gstsServer*` 函数只允许 **末尾单一 `return <expr>`**，不能在分支或循环里 `return`。
+- 递归、`async/await`、Promise 在节点图作用域内不支持（会报错或被 ESLint 提示）。
+- `while(true)` 会受循环上限影响，建议改用定时器或显式计数。
+- `!`/三目运算需要布尔条件，避免对非 bool 取反。
+
+### 数值与类型
+
+- `number` 会视为 **float**，`bigint` 会视为 **int**。
+- 取余、位运算等整数运算请使用 `bigint`。
+- 列表/字典元素类型必须一致，混合类型会报错。
+- 空数组可能无法推断类型，建议先放一个同类型占位值。
+- 建议使用辅助函数明确类型：`int`、`float`、`vec3`、`configId`、`prefabId`、`entity` 等。
+- `dict(...)` 用于创建只读字典；需要可写字典时请改用节点图变量（`f.get` / `f.set`）。
+- 需要强制生成节点图局部变量时，用 `let` 声明；`const` 可能会被优化为直接连线。
+
+### 全局函数与变量速查（建议 AI 优先使用）
+
+日志与调试：
+
+- `print(str(...))`：最稳定的日志输出方式。
+- `console.log(x)`：仅支持 **单一参数**，会自动转成 `print(str(...))`。
+- `f.printString(...)`：显式节点调用，适合需要严格对齐节点图时使用。
+
+类型与构造：
+
+- `bool(...)` / `int(...)` / `float(...)` / `str(...)`：显式类型转换。
+- `vec3(...)` / `guid(...)` / `prefabId(...)` / `configId(...)` / `faction(...)` / `entity(...)`：常用类型构造。
+- `list('int', items)`：显式声明列表类型（空数组时尤为重要）。
+- `dict(...)`：声明只读字典（节点图变量字典需用 `f.get` / `f.set`）。
+- `raw(...)`：编译器不处理，按 JS 原生语义执行（仅在必要时使用）。
+
+实体与场景：
+
+- `player(1)`：获取玩家实体（从 1 开始）。
+- `stage` / `level`：关卡实体别名。
+- `self`：当前节点图关联实体。
+- `GameObject.Find(...)` / `FindWithTag(...)` / `FindByPrefabId(...)`：实体查询。
+
+数学与向量：
+
+- `Math.*`：会编译为节点图等价实现（server 作用域内）。
+- `Mathf.*` / `Vector3.*` / `Random.*`：Unity 风格 API。
+
+信号与事件：
+
+- `send('signalName')` 发送信号，配合 `g.server().onSignal(...)` 监听。
+
+定时器：
+
+- `setTimeout` / `setInterval` / `clearTimeout` / `clearInterval`。
+
+常用方法支持：
+
+- 数组/字符串的常用方法（`map`/`filter`/`find`/`length` 等）有编译支持，以类型提示为准。
+
+### 节点图变量（可写变量）
+
+```ts
+g.server({
+  id: 1073741825,
+  variables: { counter: 0n },
+  lang: 'zh'
+}).on('whenEntityIsCreated', (_evt, f) => {
+  const v = f.get('counter')
+  f.set('counter', v + 1n)
+})
+```
+
+提示：
+
+- `variables` 会生成节点图变量，并提供类型化的 `f.get` / `f.set`。
+- 实体类型变量通常只用于声明类型（常用 `entity(0)` 作为占位）。
+- `entity(0)` 也可用于部分节点调用的实体参数占位，让编辑器中该参数保持为空。
+
+### 定时器
+
+- 直接使用 `setTimeout` / `setInterval`（单位为毫秒）。
+- 编译器会自动生成定时器池以避免同名冲突。
+- 可用注释 `// @gsts:timerPool=4` 覆盖池大小（高阶用法）。
+- `setInterval` 间隔过小（<=100ms）会有性能警告。
+- 定时器回调支持闭包捕获（按值），但不支持捕获字典类型。
+
+### JS 原生对象的限制
+
+- `Object.*`、`JSON.*` 等原生对象在节点图作用域内通常不可编译。
+- 若必须使用，请在顶层预处理，或用 `raw(...)` 让编译器忽略该表达式。
+- 字符串拼接若报错，建议在顶层预计算或用 `str(...)` 显式转换。
+
+## 复用函数（gstsServer）
+
+```ts
+function gstsServerSum(a: bigint, b: bigint) {
+  const total = a + b
+  return total
+}
+
+g.server({ id: 1073741825 }).on('whenEntityIsCreated', (_evt, f) => {
+  const v = gstsServerSum(1n, 2n)
+  f.printString(str(v))
+})
+```
+
+规则：
+
+- 必须是顶层声明，参数只能是标识符（不支持解构/默认值/rest）。
+- 只允许末尾单一 `return`，且调用必须发生在 `g.server().on(...)` 或另一个 `gstsServer*` 中。
+- 在 `gstsServer*` 内可直接使用 `gsts.f` 访问节点图 API（不强制传 `f` 参数）。
+
+## 多入口与合并
+
+- `gsts.config.ts` 的 `entries` 决定哪些文件被编译。
+- 每个入口文件默认生成一个节点图；同 ID 会自动合并。
+- 增量编译下，依赖变更会触发相关入口重编译。
+
+## 输出与调试
+
+- `.gs.ts`：TS 被展开成节点函数调用的中间文件，便于定位语义差异。
+- `.json`：节点图 IR，用来排查连接和类型匹配问题。
+- `.gia`：最终节点图产物，可注入或手动导入。
+
+## 编译执行注意事项
+
+- 编译器会扫描所有入口文件并找到 `g.server().on(...)` 入口进行编译。
+- 顶层代码会在编译期执行一次或多次（例如增量编译/多入口场景）。
+- 若顶层代码涉及本地文件读写或随机数，请注意副作用与一致性问题。
+- 需要临时禁用某个节点图注入时，可把 `id` 设置为一个不存在的值。
+- 顶层作用域适合做本地文件读取/预计算/程序化生成（例如伪随机场景）。
+- `stage.set` 可当作全局变量使用（节点图运行期）。
+
+## Scripts
+
+- `npm run build`：完整编译
+- `npm run dev`：增量编译（配置 inject 后会自动注入）
+- `npm run maps`：列出最近编辑的地图
+- `npm run backup`：打开注入备份目录
+- `npm run typecheck`：TypeScript 类型检查
+- `npm run lint`：ESLint
+
+补充说明：
+
+- 本项目内置定制化 ESLint 规则，能提示编译器的隐含约束，建议经常运行 `npm run lint`。
+- `npm run typecheck` 可提前发现类型不匹配问题，避免编译期报错。
+- `npm run dev` 实际调用的是 `gsts dev`，仅进入监控变更的编译模式。
+- 注入后需要重新加载地图，节点图变更才会生效。
+- 可准备一个临时空地图，注入后快速切换以触发重载。
+- 注入后如果在加载前使用编辑器保存地图，注入内容会被覆盖，需要重新注入。
+
+## 常见问题
+
+- `npm run maps` 为空：先在编辑器里保存一次地图，再重试。
+- 注入失败：检查 `mapId` / `nodeGraphId` 是否正确，图类型是否匹配。
+- 类型报错：优先检查 `.value` 的使用与引脚类型是否一致。
+
+## 需要查函数说明时（AI 可用）
+
+当类型提示不足时，可以直接在 `node_modules/genshin-ts` 中搜索函数/事件注释：
+
+- 节点函数与事件定义：`node_modules/genshin-ts/dist/src/definitions/`
+- 建议用关键词搜索（事件名、函数名、中文别名）定位注释与参数说明。

package/templates/start/_gitignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+out
+*.log
+.env
+.DS_Store
+*.gia
+.idea

package/templates/start/eslint.config.mjs

@@ -0,0 +1 @@
+export { default } from 'genshin-ts/configs/eslint/full.mjs'

package/templates/start/gsts.config.ts

@@ -0,0 +1,9 @@
+import type { GstsConfig } from 'genshin-ts'
+
+const config: GstsConfig = {
+  compileRoot: '.',
+  entries: ['./src'],
+  outDir: './dist'
+}
+
+export default config

package/templates/start/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "build": "gsts",
+    "dev": "gsts dev",
+    "maps": "gsts maps",
+    "backup": "gsts open backup"
+  },
+  "dependencies": {
+    "genshin-ts": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@ianvs/prettier-plugin-sort-imports": "^4.3.1",
+    "@typescript-eslint/eslint-plugin": "^8.47.0",
+    "@typescript-eslint/parser": "^8.47.0",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/start/src/main.ts

@@ -0,0 +1,7 @@
+import { g } from 'genshin-ts/runtime/core'
+
+g.server({
+  id: 1073741825
+}).on('whenEntityIsCreated', (_evt, f) => {
+  console.log('hello world')
+})

package/templates/start/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "genshin-ts/tsconfig/base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist",
+    "typeRoots": ["./node_modules/genshin-ts/types", "./node_modules/@types"],
+    "types": ["gsts", "node"]
+  },
+  "include": ["src", "gsts.config.ts"]
+}