docs: map existing codebase

2026-11-10 04:24:30 +08:00 · 2026-09-07 16:22:05 +08:00
1 parent 7eeab32134
commit e439200e4a
@@ -0,0 +1,217 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-09-07
+
+## Directory Layout
+
+```
+mota-ts/
+├── src/                    # Game entry code (@user/main): entry points + content data
+│   ├── main.ts             # Render/client entry
+│   ├── data.ts             # Data entry (replay verification, runs in Node)
+│   ├── App.vue             # Vue UI root (legacy UI stack)
+│   ├── data.ts             # (data-end entry)
+│   ├── styles.less         # Global styles
+│   ├── content/            # New JSONC game content (core/enemy/item/tile/maps)
+│   ├── types/              # Generated + declared typings (source/, declaration/)
+│   └── package.json        # name: @user/main
+├── packages/               # Core engine monorepo (@motajs/*)
+│   ├── common/             # utils, logger, hook, dirtyTracker
+│   ├── legacy-common/      # Patch system, legacy EventEmitter, utils
+│   ├── types/              # shared types (enemy, utils)
+│   ├── client/             # re-export of client-base
+│   ├── client-base/        # glUtils, keyCodes, types (KeyCode)
+│   ├── system/             # action (hotkey/keyboard) + ui (UIController/GameUI)
+│   ├── render/             # WebGL/Canvas MotaRenderer + assets + style
+│   ├── render-vue/         # custom Vue renderer over IRenderItem
+│   ├── animate/            # excitation/animation
+│   ├── audio/              # audio context, decoders, bgm/effect/sound
+│   ├── loader/             # LoadTask, progress, stream
+│   ├── legacy-client/      # re-export of legacy-system + legacy-ui
+│   ├── legacy-system/      # keyboard.vue, storage
+│   └── legacy-ui/          # Vue components/panels/presets/tools/ui
+├── packages-user/          # User game code monorepo (@user/*)
+│   ├── entry-client/       # composition root (render): createGame()
+│   ├── entry-data/         # composition root (data): Mota registry, createData()
+│   ├── client-base/        # render system layer: load/ + material/
+│   ├── client-modules/     # render impl layer: render/ + action/ + fallback/
+│   ├── data-common/        # data L0: common/ event/ replay/ save/ store/
+│   ├── data-base/          # data L1: game/ map/ hero/ enemy/ flag/ load/
+│   ├── data-system/        # data L2: combat/ + trigger/
+│   ├── data-state/         # data L3: CoreState singleton + enemy/hero/legacy
+│   ├── data-fallback/      # patch legacy globals onto new state
+│   ├── legacy-plugin-client/  # dev hot reload
+│   └── legacy-plugin-data/    # legacy plugins: shop/replay/fiveLayer/hook
+├── public/                 # Legacy mota-js sample content + editor assets
+│   ├── main.js             # legacy mota-js runtime (core/main globals)
+│   ├── editor.html         # legacy editor
+│   ├── project/            # data.js/enemys.js/events.js/items.js/maps.js + assets
+│   ├── libs/               # thirdparty libs (lz-string, lodash, localforage…)
+│   ├── extensions/         # legacy extensions
+│   ├── _server/            # editor server config
+│   └── _docs/              # editor-embedded docs
+├── script/                 # Build/dev tooling (tsx scripts)
+│   ├── dev.ts              # Vite + Express + WS dev servers
+│   ├── build-game.ts       # full game build → dist.zip
+│   ├── build-lib.ts        # library build for packages + packages-user
+│   ├── build-packages.ts   # library build for packages only
+│   ├── build-resource.ts   # resource splitting/compression
+│   ├── declare.ts          # regenerate src/types/source/*.d.ts from public/project/*.js
+│   ├── pack-template.ts    # pack the template/ directory
+│   ├── lines.ts            # line-count utility
+│   ├── special.ts / types.ts / utils.ts
+│   └── template/           # legacy template runtime (main.js, data.js, 启动服务.exe)
+├── template/               # Copy of a fresh template project (for pack:template)
+├── docs/                   # Vitepress documentation site
+├── .planning/              # GSD planning state (config.json, graphs/, codebase/)
+├── graphify-out/           # Knowledge-graph output (manifest, graph.json/html)
+├── _bundle/                # Dev rollup output (ignored)
+├── index.html              # HTML entry (canvas + Vue root + legacy scripts)
+├── vite.config.ts          # Vite config + @motajs/@user path aliases
+├── tsconfig.json           # TS project config + path aliases
+├── tsconfig.node.json      # Node-side TS config
+├── eslint.config.js        # ESLint flat config
+├── pnpm-workspace.yaml     # workspace: packages/*, packages-user/*, src/
+├── package.json            # root scripts + shared deps
+└── dev.md                  # Project dev conventions/architecture doc (read first)
+```
+
+## Directory Purposes
+
+**`src/`:**
+- Purpose: The game entry point and game content. Package name `@user/main`.
+- Contains: `main.ts` (client entry), `data.ts` (data entry), `App.vue`, `styles.less`, `content/` (JSONC data), `types/` (typings).
+- Key files: `src/main.ts`, `src/data.ts`, `src/App.vue`, `src/package.json`.
+
+**`packages/` (core engine, `@motajs/*`):**
+- Purpose: The reusable engine core — utilities, render system, audio, animation, input/UI systems, loader, and the legacy bridge.
+- Contains: one directory per package, each with `src/` and its own `package.json`.
+- Key files: `packages/render/src/core/render.ts`, `packages/system/src/action/hotkey.ts`, `packages/legacy-common/src/patch.ts`.
+
+**`packages-user/` (user code, `@user/*`):**
+- Purpose: The game-specific implementation layered over the engine — data end (L0–L3) and render end (system + impl), plus composition roots.
+- Contains: one directory per package; each `src/` mirrors its layer's responsibility.
+- Key files: `packages-user/entry-data/src/mota.ts`, `packages-user/data-state/src/core.ts`, `packages-user/client-modules/src/index.ts`.
+
+**`public/`:**
+- Purpose: The legacy mota-js sample game content and runtime, plus editor assets. Not TypeScript — these are the uncompiled game files the engine loads.
+- Contains: `main.js` (legacy runtime), `project/` (data, enemys, events, items, maps, floors, images, sounds, bgms, autotiles, tilesets, materials, animates), `libs/thirdparty/`, `extensions/`, `_server/`, `_docs/`, `editor.html`, `styles.css`, `logo.png`.
+- Key files: `public/main.js`, `public/project/data.js`, `public/project/maps.js`.
+
+**`script/`:**
+- Purpose: Build/dev tooling run via `tsx` (`pnpm dev`, `pnpm build:game`, `pnpm declare`, …).
+- Contains: `dev.ts` (dev servers + hot reload), `build-game.ts` (game packaging), `build-resource.ts` (asset splitting), `declare.ts` (type generation), `pack-template.ts`, and helpers.
+- Key files: `script/dev.ts`, `script/build-game.ts`, `script/declare.ts`.
+
+**`docs/`:**
+- Purpose: Vitepress documentation site (`docs:dev` / `docs:build`), including API docs per package, dev guides, and logger error-code reference.
+- Contains: `.vitepress/`, `api/`, `dev/`, `guide/`, `logger/`.
+
+**`template/`:**
+- Purpose: A standalone copy of a fresh template project, packaged by `script/pack-template.ts` (`pnpm pack:template`).
+- Contains: its own `src/`, `script/`, `vite.config.ts`, `package.json`, etc.
+
+**`.planning/`:**
+- Purpose: GSD workflow state — `config.json` (workflow toggles), `graphs/` (project knowledge graph), `codebase/` (these analysis docs). Do not hand-edit during normal development.
+
+## Key File Locations
+
+**Entry Points:**
+- `src/main.ts`: Render/client entry — `createGame()` + Vue mount.
+- `src/data.ts`: Data entry — replay verification, Node-only.
+- `index.html`: HTML shell — canvas `#render-main`, Vue `#root`, legacy scripts.
+- `packages-user/entry-client/src/create.ts`: Client composition (`createGame`).
+- `packages-user/entry-data/src/mota.ts`: Module registry (`Mota`, `r`, `rf`).
+
+**Configuration:**
+- `vite.config.ts`: Vite + auto-generated `@motajs/*`/`@user/*` aliases (from `packages/*/src` and `packages-user/*/src`).
+- `tsconfig.json`: path aliases `@motajs/*` → `./packages/*/src`, `@user/*` → `./packages-user/*/src`.
+- `pnpm-workspace.yaml`: workspace globs.
+- `package.json`: root scripts (`dev`, `build:game`, `build:lib`, `build:packages`, `declare`, `check:circular`, `lint:*`).
+- `eslint.config.js`, `.prettierrc`, `.madgerc`.
+
+**Core Logic:**
+- `packages-user/data-state/src/core.ts`: `CoreState` (data-end composition).
+- `packages-user/data-base/src/game.ts`: `loading`, `hook`, `gameListener`.
+- `packages-user/data-common/src/save/system.ts`: `SaveSystem` (Dexie persistence).
+- `packages-user/data-common/src/replay/system.ts`: `ReplaySystem`.
+- `packages/render/src/core/render.ts`: `MotaRenderer`.
+- `packages/system/src/action/hotkey.ts`: `Hotkey` (input).
+
+**Testing:**
+- Root `package.json` defines `pnpm test` → `vitest`. (See `TESTING.md` for details; not the focus of this doc.)
+
+## Naming Conventions
+
+Conventions are defined in `dev.md` (authoritative) and escalated in `.agents/code.md`.
+
+**Files:**
+- Code files: **camelCase** (e.g. `mapStore.ts`, `hotkey.ts`, `build-game.ts`).
+- Markdown folders/files: **kebab-case** (e.g. `docs/dev/`, `my-notes.md`).
+- One class per file; multiple trivial implementations of the same interface in one file only after confirmation (`.agents/code.md` #6).
+
+**Directories:**
+- Package directories: lowercase single word (e.g. `client-modules`, `legacy-ui`), kebab-case for multi-word.
+- Source subfolders group by feature/domain (e.g. `render/map/`, `data-state/enemy/`), not by modifier type.
+
+**Identifiers (from `dev.md`):**
+- Variables, members, general constants, methods, functions: **camelCase**.
+- Classes, interfaces, type aliases, namespaces, generics, enums, comments: **PascalCase**.
+- Immutable constants: **UPPER_SNAKE_CASE** (e.g. `MAX_COUNT`); acronyms all-caps (`HTTP`, `URI`).
+- Interfaces meant to be `implements`-ed: **prefixed with `I`** (e.g. `IGameMap`, `IEnemyManager`, `ICoreState`).
+- HTML/CSS `id`/`class`: **kebab-case**.
+- No underscore naming; private members/methods do **not** start with underscore.
+
+## Where to Add New Code
+
+**New engine feature (core, reusable):**
+- Implementation: `packages/<package>/src/` under the appropriate package (e.g. render primitives in `packages/render/src/core/`).
+- Export it from the package `index.ts` (e.g. `packages/render/src/index.ts`).
+- Update `packages/<package>/package.json` dependencies if it now depends on another `@motajs/*` package.
+
+**New user/game feature:**
+- Data logic → `packages-user/data-system/src/` (Layer 2) or extend `packages-user/data-state/src/` (Layer 3).
+- Saveable data structures → `packages-user/data-base/src/` (Layer 1).
+- Shared/utility interfaces → `packages-user/data-common/src/` (Layer 0).
+- Rendering/UI → `packages-user/client-modules/src/render/` (impl layer) or `packages-user/client-base/src/` (system layer).
+- Register new modules in `packages-user/entry-data/src/create.ts` and/or `packages-user/entry-client/src/create.ts` so they are available via `Mota`.
+
+**New content (game data):**
+- New JSONC content: `src/content/` (e.g. `src/content/item.jsonc`, `src/content/maps/`).
+- Legacy content editing: `public/project/` (regenerate types with `pnpm declare`).
+
+**Utilities:**
+- Generic shared helpers → `packages/common/src/utils/` (or `packages/common/src/` for `logger`/`hook`).
+- Legacy compatibility helpers → `packages/legacy-common/src/`.
+
+**Tests:**
+- Co-located or under a `test`/`__tests__` folder as the existing `vitest` config expects; run with `pnpm test`.
+
+**Documentation:**
+- API docs → `docs/api/` (one folder per package is generated); dev guides → `docs/dev/`; error codes → `docs/logger/`.
+
+## Special Directories
+
+**`node_modules/` (workspace + per-package):**
+- Purpose: pnpm-installed dependencies; per-package `node_modules/@motajs/*` and `@user/*` are symlinks to sibling workspace packages.
+- Generated: Yes. Committed: No.
+
+**`_bundle/`:**
+- Purpose: Dev rollup output produced by `script/dev.ts` (`getEsmFile`).
+- Generated: Yes. Committed: No.
+
+**`_temp/` / `dist/` / `dist.zip`:**
+- Purpose: Build intermediates (`_temp/`) and game output (`dist/`, `dist.zip`) from `script/build-game.ts`.
+- Generated: Yes. Committed: No.
+
+**`.planning/`:**
+- Purpose: GSD workflow state (config, graphs, codebase docs).
+- Generated: Partly (by GSD commands). Committed: Yes (config and docs are committed by GSD).
+
+**`graphify-out/`:**
+- Purpose: Knowledge-graph build output (`graph.json`, `graph.html`, `manifest.json`).
+- Generated: Yes. Committed: Varies (check `.gitignore`).
+
+---
+
+*Structure analysis: 2026-09-07*