120 lines
10 KiB
Markdown
120 lines
10 KiB
Markdown
# TH1 Codex Guide
|
|
|
|
This repository is a Unity 2022.3 LTS / ET Framework turn-based strategy game. The main playable client lives under `Unity/Assets/Scripts`, with supporting config, tools, backend notes, and generated analysis in the repository root.
|
|
|
|
## First Reads
|
|
|
|
- For architecture questions, read the `MD/GameMDFramework/00-*` overview document and the relevant subsystem document before editing.
|
|
- For broad code navigation or unfamiliar subsystem discovery, optionally consult `Unity/graphify-out/GRAPH_REPORT.md` for Unity code and `graphify-out/GRAPH_REPORT.md` for whole-repository context. Treat Graphify as a secondary macro index; prefer `rg`, subsystem docs, and the relevant `.codex/skills` for ordinary bug fixes and focused edits.
|
|
- If a task touches action execution, networking, localization, online errors, backend upload, or CrashSight reports, use the matching `.codex/skills/th1-*` skill first.
|
|
- For severe incidents, postmortems, root-cause attribution, or requests to maintain an incident log, use `.codex/skills/th1-serious-incident` and update `MD/SeriousIncidentLog/index.md`.
|
|
- For repeated defects, problems the user says happened again, or requests to 根治 / add to 癌症清单, use `.codex/skills/th1-chronic-issue` and update `MD/ChronicIssueList/index.md` before treating the issue as fixed.
|
|
- For broad TH1 Unity/code/resource/build changes, use `.codex/skills/th1-base` first, then layer the narrower business skill on top.
|
|
- Claude-era context remains in `.claude/` and `Unity/Assets/Scripts/CLAUDE.md`; treat it as historical source material, not the active entrypoint.
|
|
|
|
## Project Shape
|
|
|
|
- `Unity/Assets/Scripts/TH1_Core`: shared managers such as `EventManager`, `UIManager`, and `PresentationManager`.
|
|
- `Unity/Assets/Scripts/TH1_Data`: runtime data models including `MapData`, `PlayerData`, `UnitData`, `GridData`, and `NetData`.
|
|
- `Unity/Assets/Scripts/TH1_Logic`: gameplay rules, actions, skills, AI, Steam networking, editor tools, and game entrypoints.
|
|
- `Unity/Assets/Scripts/TH1_UI`: View/Controller UI architecture and UI resource registration.
|
|
- `Unity/Assets/Scripts/TH1_Renderer`: map, grid, city, unit, projectile, and effect renderers.
|
|
- `Unity/Assets/Scripts/TH1_Config`: generated Excel config classes plus partial extensions.
|
|
- `Unity/Assets/Scripts/BTNodeCanvas`: NodeCanvas AI behavior tree nodes.
|
|
- `MD/GameMDFramework`: human-maintained architecture documentation by subsystem.
|
|
|
|
## Development Rules
|
|
|
|
- Any code involving obfuscation, compatibility, or MemoryPack must not be modified without repeated explicit confirmation from the user before doing related work.
|
|
- TH1 civilization/force identity has two numeric layers and they must never be conflated: `CivEnum`/`ForceEnum` are 1-based runtime enums with `Common = 0`, while `CivId`/`ForceId` in DataAssets, YAML, `PlayerData.PlayerCivId`, `PlayerData.PlayerForceId`, and map slots are 0-based `uint` table ids. Always convert through `Table.Instance.TransCivEnumToCivId` / `TransCivIdToCivEnum` and `TransForceEnumToForceId` / `TransForceIdToForceEnum`, or use existing `PlayerCivId` / `PlayerForceId` when ids are required. Never copy enum numeric values into id fields. In current TH1 data, Hakurei/Reimu is `CivEnum.Norway = 5` and `ForceEnum.Reimu = 5`, therefore `CivId = 4` and `ForceId = 4`; `CivId = 5` / `ForceId = 5` is a different empire. Do not pass `CivEnum.Common` / `ForceEnum.Common` into enum-to-id conversion unless the callee explicitly handles the underflow; use explicit `0u` only when an API truly expects common table ids.
|
|
- Keep authoritative gameplay mutations inside the action flow when possible: construct `CommonActionParams`, validate with `CheckCan`, and execute through `ActionLogicBase.CompleteExecute`.
|
|
- Do not make UI-only, AI-only, or network-receiver-only data mutations that bypass the shared action layer unless the existing design for that subsystem already does so.
|
|
- For multiplayer-safe logic, avoid `UnityEngine.Random`, wall-clock time, unordered iteration, and direct `Main.MapData` assumptions inside simulated or synchronized execution paths.
|
|
- For Excel-backed keys such as `UnitFullType`, `SkillType` level pairs, resources, terrain, and tech atoms, inspect the actual config rows before coding. Do not infer current data from similar entries.
|
|
- Game-facing non-debug text must not be hardcoded in code. Add or reuse fields in the appropriate DataAssets/data tables, then read them through the existing data/table and localization path.
|
|
- Do not modify export-flow outputs such as `Unity/Assets/Resources/Export/*`, `Tools/Multilingual.xlsx`, or `Tools/MultilingualTxt.txt` unless the user explicitly asks for export/import workflow changes. These files are produced by the user's manual export process.
|
|
- For multilingual translation, keep target-language text close to the Chinese source length where practical. Preserve meaning first, but prefer concise game UI wording; trim only explanatory redundancy when a common in-game localization style allows it. Do not delete core differentiating terms just to shorten text: `房间名称` must preserve the `Name` meaning (`Room Name`, not `Room`), and `玩家席位` must preserve the player/slot distinction (`Player Slots`, not just `Slots`) unless the UI context independently supplies that missing meaning. Treat short UI status labels as labels, not explanatory sentences: for example, translate `密码房间` as `Private` / `鍵付き` / `잠금방`, not `Password-Protected Room` / `パスワード付きルーム` / `비밀번호 방`.
|
|
- Unity `.meta` files are part of source control and must be preserved when assets move or are created.
|
|
- Generated files should only be edited through the project generator or documented editor workflow.
|
|
|
|
## Codex Skills And Agents
|
|
|
|
- Prefer `.codex/skills` for current project-specific workflows:
|
|
- `th1-base`: baseline Unity engineering rules for assembly boundaries, HybridCLR hotfix, YooAsset/AB, MemoryPack/AOT serialization, generated config, and build/package verification.
|
|
- `th1-action-logic`: action execution, AI action flow, turn actions, and action-triggered skills.
|
|
- `th1-network-sync`: Steam lobby, P2P, multiplayer save/recovery, action sync, and deterministic network behavior.
|
|
- `th1-multilingual`: localization import/export, active text scanning, duplicate IDs, and translation diagnostics.
|
|
- `th1-server-backend`: Aliyun Function Compute, OSS/STS upload, collect data, and backend debugging.
|
|
- `th1-online-debug`: production/obfuscated stack decoding and online issue tracing.
|
|
- `th1-crashsight-daily`: daily CrashSight triage and report generation.
|
|
- `th1-chronic-issue`: recurring defect workflow for the long-term 癌症清单 and root-cause guardrails.
|
|
- `.agents/skills` contains migrated Claude-era reference skills, including `graphify`, `th1-architecture`, `th1-ui-patterns`, `th1-config-guide`, `th1-ai-nodes`, and `th1-anim-scope`.
|
|
- `.codex/agents` contains migrated specialist agent profiles. Use them as role guidance for large investigations, but keep the final integration decisions in this main workspace.
|
|
|
|
## Graphify
|
|
|
|
- There are two graphify scopes:
|
|
- Root `graphify-out/`: whole repository overview.
|
|
- `Unity/graphify-out/`: Unity client code overview.
|
|
- Graphify is useful for macro navigation, cross-subsystem exploration, and onboarding a fresh agent into unfamiliar code. It is not the default source of truth for small edits, dependency safety, config inspection, or code review findings.
|
|
- Graphify input scope is narrowed by `.graphifyignore` and `Unity/.graphifyignore` to keep generated code, Unity packages, export data, art/resource assets, and previous graph outputs out of the graph.
|
|
- Large graphify files such as `graph.json`, `cache/`, `converted/`, and `obsidian/` are intentionally ignored. Commit only lightweight reports and metadata such as `GRAPH_REPORT.md`, `manifest.json`, and `cost.json`.
|
|
- Graphify post-commit refresh is opt-in because full rebuilds are expensive on this repository. Set `GRAPHIFY_POST_COMMIT=1` in the shell before committing if you want the local post-commit hook to refresh graphs in the background.
|
|
- The post-commit script only reacts to narrowed graph-worthy paths such as `Unity/Assets/Scripts/*`, selected repo tools, Graphify config files, and architecture docs. Architecture doc edits mark `graphify-out/needs_update` for a manual semantic update instead of running LLM extraction automatically.
|
|
- To run the hook manually:
|
|
|
|
```powershell
|
|
Tools/GraphifyPostCommit.ps1
|
|
```
|
|
|
|
- To run an opt-in local post-commit refresh for one commit:
|
|
|
|
```powershell
|
|
$env:GRAPHIFY_POST_COMMIT = "1"
|
|
git commit
|
|
Remove-Item Env:\GRAPHIFY_POST_COMMIT
|
|
```
|
|
|
|
- To reinstall the local git hook after cloning or moving the repository:
|
|
|
|
```powershell
|
|
Tools/InstallGraphifyHook.ps1
|
|
```
|
|
|
|
- To test what the hook would do without rebuilding:
|
|
|
|
```powershell
|
|
Tools/GraphifyPostCommit.ps1 -DryRun
|
|
```
|
|
|
|
## Codex Auto Commit
|
|
|
|
- The repository owner has requested proactive Codex commits. For TH1 work, a verified commit is part of the default finish criteria.
|
|
- Before ending a code, data, docs, resource, or tool change, Codex must inspect `git status`, group safe commit-worthy changes, run the relevant verification, stage only that group, and create a commit.
|
|
- Do not wait for a separate commit request when a coherent verified group is ready. Leave files uncommitted only for a concrete blocker such as failed verification, unrelated user changes mixed into the same files, protected build artifacts, missing high-risk confirmation, or an explicit user instruction not to commit.
|
|
- If any files remain uncommitted, Codex must state exactly which category remains and why.
|
|
|
|
## Verification
|
|
|
|
- For most Unity hotfix/runtime C# changes, run:
|
|
|
|
```powershell
|
|
dotnet build Unity/TH1.Hotfix.csproj --no-restore
|
|
```
|
|
|
|
- For AOT bootstrap or platform-shell changes, also run:
|
|
|
|
```powershell
|
|
dotnet build Unity/TH1.AOT.csproj --no-restore
|
|
```
|
|
|
|
- For editor tooling, config windows, localization editor, OSS editor, or generated editor integration, also run the relevant editor assembly:
|
|
|
|
```powershell
|
|
dotnet build Unity/TH1.Editor.csproj --no-restore
|
|
dotnet build Unity/TH1.Logic.Editor.csproj --no-restore
|
|
dotnet build Unity/TH1.Steam.Editor.csproj --no-restore
|
|
```
|
|
|
|
- Some behavior still requires Unity Editor validation, especially UI prefabs, animation sequencing, Steam networking, save/load, replay/spectator, and AI behavior tree changes.
|