TH1/AGENTS.md

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.
• 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.
• 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.
• .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:

Tools/GraphifyPostCommit.ps1

• To reinstall the local git hook after cloning or moving the repository:

Tools/InstallGraphifyHook.ps1

• To test what the hook would do without rebuilding:

Tools/GraphifyPostCommit.ps1 -DryRun

Verification

• For most Unity C# changes, run:

dotnet build Unity/Assembly-CSharp.csproj --no-restore

• For editor tooling, config windows, localization editor, OSS editor, or generated editor integration, also run:

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.