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

2025-12-26 19:51:17 +00:00
parent a0fd36765f
commit 21e7c8ddff
13 changed files with 661 additions and 0 deletions
@@ -0,0 +1,53 @@
+# Legacy Constraint System
+
+This document describes the constraint framework used to validate command
+preconditions. References include `legacy/hwe/sammo/Constraint/Constraint.php`
+and `legacy/hwe/sammo/Constraint/ConstraintHelper.php`.
+
+## Core Concepts
+
+Constraints are reusable predicate classes that validate a command’s inputs and
+state. They are built per-command and executed in order:
+
+- Each constraint extends `Constraint` and implements `test()`.
+- `Constraint::testAll()` iterates a list of constraints and returns the first
+  failure `[constraintName, reason]` or `null` for success.
+- `BaseCommand::hasFullConditionMet()` uses these to decide command validity.
+
+## Required Input Flags
+
+Constraints declare required inputs using bit flags:
+
+- `REQ_GENERAL`, `REQ_CITY`, `REQ_NATION`
+- `REQ_DEST_GENERAL`, `REQ_DEST_CITY`, `REQ_DEST_NATION`
+- `REQ_ARG` with typed sub-flags:
+  - `REQ_STRING_ARG`, `REQ_INT_ARG`, `REQ_NUMERIC_ARG`, `REQ_BOOLEAN_ARG`,
+    `REQ_ARRAY_ARG`, `REQ_BACKED_ENUM_ARG`
+
+`Constraint::checkInputValues()` enforces these expectations and throws if
+inputs are missing or malformed.
+
+## Constraint Helper DSL
+
+`ConstraintHelper` provides factory-style helpers used in command definitions:
+
+- Examples: `AllowWar()`, `NearCity($distance)`, `ReqGeneralGold($amount)`,
+  `NotOccupiedDestCity()`, `AllowDiplomacyStatus(...)`, etc.
+- These helpers return `[ConstraintName, arg]` tuples consumed by
+  `Constraint::testAll()`.
+
+## Common Constraint Classes
+
+Constraints are organized by domain:
+
+- **Diplomacy**: `AllowDiplomacyStatus`, `AllowDiplomacyBetweenStatus`.
+- **Nation/City**: `OccupiedCity`, `NotCapital`, `RemainCityCapacity`.
+- **General**: `ReqGeneralCrew`, `ReqGeneralGold`, `MustBeTroopLeader`.
+- **Routing**: `HasRoute`, `HasRouteWithEnemy`.
+
+Each constraint sets a failure reason string used by UI and logs.
+
+## Open Questions / Follow-ups
+
+- Some constraints rely on `env` values (`turnterm`, `year`, etc.); document
+  each command’s exact `env` payload when porting.