template/.planning/codebase/STACK.md

Technology Stack

Analysis Date: 2026-09-07

Languages

Primary:

• TypeScript 6.0.3 - All engine/package source, build scripts, and docs config (monorepo packages/, packages-user/, src/, script/, docs/)
• Vue 3 SFC (Single File Components) - Client UI (*.vue in packages-user/client-modules/, src/App.vue)

Secondary:

• JavaScript (legacy runtime) - The legacy H5 runtime layer under public/libs/*.js and game content public/project/*.js (data.js, enemys.js, events.js, floors, maps, etc.)
• Less - Stylesheets (src/styles.less, javascriptEnabled: true in Vite config)
• CSS - Editor/assets styles (public/styles.css, public/_server/**)

Runtime

Environment:

• Node.js ^20.0.0 || >=22.0.0 (per dev.md)
• Browsers supporting ESNext; production build targets Chrome >= 56, Firefox >= 51, Edge >= 79, Safari >= 15, Opera >= 43 via @vitejs/plugin-legacy (script/build-game.ts)

Package Manager:

• pnpm >= 10.0.0 (per dev.md)
• Lockfile: pnpm-lock.yaml (present)
• Workspace: pnpm-workspace.yaml — globs packages/*, packages-user/*, and src/; onlyBuiltDependencies: core-js, esbuild, ttf2woff2, vue-demi

Frameworks

Core:

• Vue ^3.5.29 - UI framework for the client render side (src/main.ts, src/App.vue)
• Vite ^7.3.1 - Dev server and production bundler (vite.config.ts, script/dev.ts, script/build-game.ts)
• Ant Design Vue ^3.2.20 + @ant-design/icons-vue ^6.1.0 - UI component library (bundled as manual chunk antdv)

Rendering (custom, in-repo):

• WebGL2 - Hand-written render engine in packages/render/src/core/gl2.ts, assets/composer.ts (no external rendering framework)
• gl-matrix ^3.4.4 - Matrix/vector math for WebGL (packages/render/src/core/transform.ts, core/item.ts)
• maxrects-packer ^2.7.3 - Texture atlas packing (packages/render/src/assets/composer.ts, streamComposer.ts)

Audio:

• Web Audio API (AudioContext) via packages/audio/src/context.ts with wasm decoders:
  • @wasm-audio-decoders/ogg-vorbis ^0.1.20
  • ogg-opus-decoder ^1.7.3
  • opus-decoder ^0.7.11
  • codec-parser ^2.5.0 (codec stream parsing in packages/audio/src/source.ts)

Testing:

• Vitest ^4.0.18 - Test runner (package.json script "test": "vitest")

Docs:

• VitePress ^1.6.4 - Documentation site (docs/.vitepress/config.ts, output to public/_docs)
• Mermaid ^11.12.3 + vitepress-plugin-mermaid ^2.0.17 + markdown-it-mathjax3 ^4.3.2

Build/Dev:

• Rollup ^4.59.0 (+ @rollup/plugin-* family) - Programmatic bundling in build scripts
• @babel/core ^7.29.0 / @babel/preset-env ^7.29.0 / @babel/cli ^7.28.6 - Post-build script minification (script/build-game.ts)
• vue-tsc ^2.2.12 - Type checking for .vue files
• tsx ^4.21.0 - Execute TypeScript build/dev scripts
• fontmin ^2.0.3 - CJK font subsetting at build time (script/build-game.ts)
• Express ^5.2.1 - Local editor/dev HTTP server (script/dev.ts)
• ws ^8.19.0 - WebSocket server for hot reload (script/dev.ts)
• chokidar ^3.6.0 - File watching (script/dev.ts)
• archiver ^7.0.1 + compressing ^1.10.4 - Zip packaging (script/build-game.ts)
• madge ^8.0.0 - Circular dependency check ("check:circular" script)

Key Dependencies

Critical:

• dexie ^4.4.2 - IndexedDB wrapper for game saves (packages-user/data-common/src/save/system.ts)
• lz-string ^1.5.0 - Save compression (packages-user/client-modules/src/render/utils/saves.ts, packages/legacy-ui/src/utils.ts)
• jszip ^3.10.1 - Zip handling (packages/loader/)
• axios ^1.13.6 - HTTP client (script/special.ts, packages/legacy-ui/src/utils.ts)
• lodash-es ^4.17.23 - Utility functions (used widely across packages)
• eventemitter3 ^5.0.4 - Event emitter
• mutate-animate ^1.4.2 - Animation tweening (packages/legacy-ui/src/utils.ts)
• anon-tokyo 0.0.0-alpha.0 - "high performance interpreter" (declared dependency; no import found in packages//src//packages-user/ source)
• chart.js ^4.5.1 - Charts (declared; not detected in source, likely editor-facing)

Infrastructure:

• fs-extra ^11.3.4, glob ^11.1.0 - File system utilities in build scripts
• less ^4.5.1, postcss-preset-env ^9.6.0 - CSS preprocessing

Configuration

Environment:

• No .env / .env.* files present — the project does not use runtime environment variables.
• import.meta.env.BASE_URL is used for asset path prefixing (packages/loader/src/task.ts, packages/legacy-ui/src/utils.ts). Vite base is set to ./ (vite.config.ts).
• Editor config: public/_server/config.json (gitignored; auto-generated as {} by ensureConfig() in script/dev.ts).

Build:

• tsconfig.json — strict, moduleResolution: "bundler", jsx: "preserve" (jsxImportSource: "vue"), path aliases @motajs/* → packages/*/src and @user/* → packages-user/*/src.
• tsconfig.node.json — covers vite.config.ts, script/, and docs/.vitepress/*.
• vite.config.ts — dynamic aliases generated from packages/*/src and packages-user/*/src; Less javascriptEnabled; postcss-preset-env.
• .prettierrc — tabWidth: 4, singleQuote, semi, trailingComma: "none", endOfLine: "crlf".
• eslint.config.js — flat config combining @eslint/js, typescript-eslint, eslint-plugin-vue, eslint-plugin-react, eslint-plugin-prettier.
• .madgerc — madge config for circular-dependency detection (.ts/.tsx, skips type imports).

Platform Requirements

Development:

• Node.js 20/22+, pnpm 10+, VSCode (recommended extensions: dbaeumer.vscode-eslint, esbenp.prettier-vscode, vue.volar, slevesque.shader, tobermory.es6-string-html in .vscode/extensions.json).
• Run pnpm dev (Vite on 5173 + Express editor server on 3000) or pnpm test.

Production:

• Static HTML5 game: pnpm build:game produces dist/ (deployable static bundle) and dist.zip.
• Deployment target: GitHub Pages via .github/workflows/page.yml (builds dist folder to gh-pages branch).
• The data layer (src/data.ts) is built separately as an IIFE bundle (data.process.js) usable for replay verification in Node.

---

Stack analysis: 2026-09-07