kawagiri/TH1
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
TH1/AGENTS.md

9.3 KiB
Raw Blame History

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.
  • 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:
Tools/GraphifyPostCommit.ps1
  • To run an opt-in local post-commit refresh for one commit:
$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:
Tools/InstallGraphifyHook.ps1
  • To test what the hook would do without rebuilding:
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:
dotnet build Unity/TH1.Hotfix.csproj --no-restore
  • For AOT bootstrap or platform-shell changes, also run:
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:
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.