88 lines
6.3 KiB
Markdown
88 lines
6.3 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 code navigation, read `Unity/graphify-out/GRAPH_REPORT.md` for Unity code and `graphify-out/GRAPH_REPORT.md` for whole-repository context.
|
|
- If a task touches action execution, networking, localization, online errors, backend upload, or CrashSight reports, use the matching `.codex/skills/th1-*` skill first.
|
|
- 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.
|
|
- 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-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.
|
|
- `.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.
|
|
- 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`.
|
|
- After code changes, the git `post-commit` hook runs `Tools/GraphifyPostCommit.ps1` in the background to refresh code graphs without LLM cost.
|
|
- To run the hook manually:
|
|
|
|
```powershell
|
|
Tools/GraphifyPostCommit.ps1
|
|
```
|
|
|
|
- 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
|
|
```
|
|
|
|
## Verification
|
|
|
|
- For most Unity C# changes, run:
|
|
|
|
```powershell
|
|
dotnet build Unity/Assembly-CSharp.csproj --no-restore
|
|
```
|
|
|
|
- For editor tooling, config windows, localization editor, OSS editor, or generated editor integration, also run:
|
|
|
|
```powershell
|
|
dotnet build Unity/Assembly-CSharp-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.
|