# 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*