# Project map

## Reference client (40250)

- Root: `MT_40250_SOURCE`, else `reference_root` in `audit/manifest.json` — on this machine
  `../40250/Server Client TMP4/ClientVS22/source` relative to the repo (quote it: the path has spaces).
- Active sources: the `ClCompile`/`ClInclude` items in `../vs_files/*/*.vcxproj`; files not listed
  there are not product code.
- Many `UserInterface/` files contain CP949 bytes in comments: use `grep -a` / `grep -arn`, or plain
  grep silently reports no match.
- Python UI and game scripts: `../../Client/Eternexus/root/*.py` relative to the reference root
  (90 files; identical to the shipped `Client/pack/root.epk`), window layouts in
  `../../Client/Eternexus/uiscript/uiscript/`, locale data in `../../Client/Eternexus/locale_*/`.
  **`assets/root` in this repo is a different (m2dev) version** with material differences
  (e.g. `uitarget.py` button table); never use it as the 40250 reference.
- Server source (for protocol questions only, not client behavior): `../40250/Server Client TMP4/Server/metin2`.

| Library | Lines | Content |
| --- | ---: | --- |
| `UserInterface` | 64.7k | network stream + phases, `CPythonPlayer`, `CInstanceBase`, managers, Python modules |
| `EterLib` | 48.7k | device/render state, camera, input/IME, net stream, resources, collision primitives |
| `GameLib` | 30.7k | `CActorInstance` (motion, battle, attach, events), flying objects, map/terrain, race data |
| `EterBase` | 6.3k | utilities, timer, CRC, file |
| `EffectLib` | 6.1k | effect/particle instances |
| `EterGrnLib` | 5.9k | Granny models, motion, LOD |
| `EterPack` | 3.4k | pack format |
| `MilesLib` | 2.3k | audio |
| `EterLocale` | 1.1k | codepages, locale strings |
| `PRTerrainLib` | 1.0k | terrain texture/height data |

## Current client

- GDScript runtime: `project/` (entry `project/app_flow.gd`, world `project/game_scene.gd`); UI in `project/ui/`.
- Native extension: `extension/src/` (network in `extension/src/net/`, classic 40250 protocol in `extension/src/net/classic/`).
- Format readers: `formats/`; Granny: `libgr2/`; assets/tables: `assets/`; Granny oracle: `oracle/`; tools: `tools/`.

### Target layout

- `extension/src/port/<Lib>/<File>.{h,cpp}` — mirror of each 40250 `logic` unit (see SKILL.md
  "Code layout"). Does not exist yet; the first ported unit creates it and adds it to
  `extension/CMakeLists.txt`.
- `extension/src/platform/` — adapter interfaces named after the 40250 platform classes they replace.
- The files in the table below are **migration sources**: when a unit is ported, its logic moves out
  of them into the mirror file.

### Legacy counterparts (migration sources)

| 40250 | Current |
| --- | --- |
| `CPythonNetworkStream*` phases, `CAccountConnector` | `extension/src/net/classic/classic_session.cpp`, `classic_stream.cpp`, `classic_parser.cpp` |
| packet structs / `CMainPacketHeaderMap` | `extension/src/net/classic/wire_classic.h` |
| `EterLib/NetStream.cpp` sequence + cipher | `extension/src/net/classic/sequence_table.h`, `classic_cipher.cpp` |
| `CPythonCharacterManager`, `CInstanceBase` state from packets | `extension/src/net/entity_store.cpp`, `project/net_world.gd` |
| `CPythonPlayer` input/move (`PythonPlayerInput*.cpp`), main `CInstanceBase` movement | `project/player_controller.gd` |
| `PythonPlayerEventHandler.cpp` (OnMove/OnMoving/OnWaiting/OnStop -> `SendCharacterStatePacket`) | `project/net_play.gd` |
| `CPythonPlayer` skill use | `project/player_skill.gd` |
| `CFlyingObject*` | `project/fly_object.gd` |
| `EterLib/Camera.cpp` + `PythonApplicationCamera` | `project/game_camera.gd` |
| `ui*.py` windows | `project/ui/*_ui.gd` (ported from the wrong `assets/root`; replaced by the python layer) |

### Removed non-counterparts

The 106 `project/*_system.gd` files that only their own `test_*_parity.gd` loaded were deleted on
2026-09-22 (commit `a989b8f1`). Do not recreate them; port the real 40250 code path instead.

## Existing evidence (historical)

- `docs/CLIENT-GAP.md`, `docs/CLIENT-PARITY-AUDIT-AND-FIX-GUIDE.md`, `docs/CLIENT-40250-PORT.md`,
  `docs/PARITY-GAP.md`: background only; trust the port-map, not their status text.
- `oracle/run-diff-suite.sh`: Granny numerical comparison suite.

## Verification commands

```bash
godot --headless --path project --script <test>.gd          # most project tests
cmake --build build -j8 && ctest --test-dir build --output-on-failure -j4
```

`build/` (Debug) is the configured tree; it also writes `project/bin/libmtgodot.*.dylib`, so rebuild
before running Godot tests after pulling native changes (a stale dylib shows up as "method not
found" parse errors). `build-debug/` is a stale tree from another checkout; do not use it.
Always finish with `git diff --check`.