문서 추가: 레거시 엔진 아키텍처에 대한 상세 설명 및 관련 정보 추가

2025-12-26 19:51:17 +00:00
parent a0fd36765f
commit 21e7c8ddff
13 changed files with 661 additions and 0 deletions
@@ -0,0 +1,48 @@
+# Legacy City Data and Helpers
+
+This document describes how city data is defined and accessed in the legacy
+engine. References include `legacy/hwe/sammo/CityConstBase.php`,
+`legacy/hwe/sammo/CityInitialDetail.php`, and `legacy/hwe/sammo/CityHelper.php`.
+
+## City Constants (CityConst)
+
+`CityConstBase` defines default city data and lookup helpers:
+
+- `CityConstBase::$initCity` includes:
+  - id, name, level, population, agri/comm/secu/def/wall,
+    region, coordinates, and path connections.
+- Region and level maps convert labels to numeric codes.
+- `CityConstBase::byID()` and `byName()` return `CityInitialDetail` objects.
+
+During scenario build, the engine generates `d_setting/CityConst.php` from the
+scenario map file, replacing or extending these defaults.
+
+## CityInitialDetail
+
+`CityInitialDetail` is a plain data object containing the initial
+static attributes for each city:
+
+- `id`, `name`, `level`, `population`
+- `agriculture`, `commerce`, `security`, `defence`, `wall`
+- `region`, `posX`, `posY`, `path` (adjacent city ids)
+
+## CityHelper Cache
+
+`CityHelper` caches live DB city rows for fast lookup:
+
+- `getAllCities()` returns a map keyed by city id.
+- `getAllNationCities($nationID)` returns all cities for a nation.
+- `getCityByName()` resolves a name to a DB row (with a warning if missing).
+
+Cache invalidation is manual via `CityHelper::flushCache()`.
+
+## Path Connectivity
+
+City connectivity (used for supply and movement) is defined by the
+`path` list in `CityConst` and referenced by systems like
+`UpdateCitySupply` to traverse same-nation city graphs.
+
+## Open Questions / Follow-ups
+
+- Scenario-specific map files (`legacy/hwe/scenario/map/*.php`) override city
+  data; document per-map deltas when needed.