genshin-ts

Genshin-TS

Introduction

Genshin-TS (gsts) is a toolchain for building Miliastra Wonderland projects in TypeScript. It focuses on a code-first experience with controllable node-graph semantics, supporting compilation, injection, debugging, optimization, parallel builds, and incremental builds.

https://github.com/user-attachments/assets/0f2ec8af-c753-4c54-940c-8147ec856635

Quick Start

npm create genshin-ts@latest

If the Windows execution policy prevents scripts from running, replace npm with npm.cmd in all commands.

genshin-ts includes a TypeScript plugin for more advanced TypeScript support enhancements. It is optional (disabling it does not affect functionality and developer experience), but recommended. See: https://gsts.moe/doc/quick-start/install.html#typescript-plugin

Then in the template:

npm install
npm run dev

For detailed usage and constraints, see the template guide and docs:

• create-genshin-ts/templates/_shared/README.md
• https://gsts.moe

Highlights

• TS -> NodeGraph compilation: event entry points, control flow, reusable functions.
• TS -> Lua compilation: write client control scripts with g.clientControlScript, built and injected alongside node graphs; see the guide.
• Full type hints with Chinese/English aliases: events, functions, APIs, entity subtypes.
• g.server(...).on(...) chaining, multi-entry merge by identical ID.
• gstsServer* function compilation (reusable logic, controlled returns).
• JS-style timers: setTimeout / setInterval + closure capture + name pools + dispatch aggregation.
• Compile-time optimizations: constant precompute, dead node removal, local variable reuse.
• Readable IR JSON for debugging and further processing.
• CLI toolchain: incremental builds, injection safety checks, map discovery, auto backups.
• Custom ESLint rules to surface semantic constraints early.
• Built-in prefab/resource ID support.

Compilation Pipeline and Outputs

Pipeline:

1. TS -> .gs.ts (node function call form)
2. .gs.ts -> IR .json (nodes and connections)
3. IR -> .gia (injectable output)

Outputs are written to dist/ by default. .gs.ts and .json are the primary debugging entry points.

Key Optimizations

Enabled by default (can be disabled in gsts.config.ts):

• precompileExpression: precompute literal-only expressions.
• removeUnusedNodes: remove unused exec/data nodes.
• timerPool: timer name pools to avoid collisions.
• timerDispatchAggregate: aggregate timer dispatch to reduce graph complexity.

How to Use

• Template: npm create genshin-ts@latest (recommended; TypeScript plugin guidance: https://gsts.moe/doc/quick-start/install.html#typescript-plugin)
• As a dependency: npm i genshin-ts and call compiler/injector APIs in your project
• Global CLI: npm install -g genshin-ts, then use gsts for compile/inject

Constraints (Overview)

• Only a supported TS subset (no Promise/async/recursion).
• Conditions must be boolean.
• gstsServer* allows only a single trailing return.
• console.log supports only one argument (rewritten to print(str(...))).
• Native Object.* / JSON.* are generally unavailable in node-graph scope.

See the template guide for the full list and best practices.

Detailed Usage & AI Guidance

• Template guide: create-genshin-ts/templates/_shared/README.md
• AI guidance: create-genshin-ts/templates/_shared/CLAUDE.md / create-genshin-ts/templates/_shared/AGENTS.md
• Function/event notes: node_modules/genshin-ts/dist/src/definitions/

TODO (Some items may be dropped based on feasibility; in no particular order)

• Improve documentation site
• Struct definitions with parameter passing (generic parameter type hints)
• Auto-detect node graph limit overflow (3000)
• g.scene() programmatic scene definition support
• Auto variable mounting support
• Node graph JSON visual previewer
• Programmatic struct and global timer definitions
• More // @gsts: decorator optimization flags, e.g., local precompile toggle
• await delay support? (highly uncertain)
• GIA to TypeScript conversion support
• npm library development template
• Generate JS source maps for better error tracing
• Fix cross-file duplicate ID level cache issues
• JSX component development abstraction
• Expand examples
• Simplify {} style 3D vector array inference
• VFX, sound, and other resource IDs

Special Thanks

• https://github.com/Wu-Yijun/Genshin-Impact-Miliastra-Wonderland-Code-Node-Editor-Pack

• Before discovering this project, I spent nearly a month reversing GIA/GIL; their approach was more complete. I integrated it as a third-party module and merged some of my reverse-engineered data.

• The work is excellent and MIT-licensed. Please consider supporting the project as well.