Core-Game contributor guide
Scope and workflow
- This is a public Unity game template. Keep source, documentation, settings, and dependencies usable without private repositories, credentials, or hosted services.
- Preserve unrelated edits. Inspect the diff before editing or committing; stage explicit paths. Commit, push, tagging, and publishing need explicit user authorization. Use this repository’s public contributor identity.
- Read
README.md for setup and validation commands. Keep contributor constraints here and the adjacent CLAUDE.md as exactly @AGENTS.md followed by LF.
- Prefer existing Unity and package capabilities. Remove obsolete owners when replacing a system; do not edit package caches or introduce speculative framework layers.
Architecture and asset safety
- Target Unity
6000.6.6f1, URP, .NET Standard 2.1, and C# 9. Use explicit block namespaces; no file-scoped namespaces or global usings.
- Keep startup usable offline and telemetry disabled until explicitly configured and consented. Save on pause and focus loss without treating them as permanent shutdown.
Main owns composition and application lifetime. Keep game rules in Logic, state transitions in StateMachines, mutations in Commands, presentation in Presenters, and communication in Messages.- Resolve dependencies at composition boundaries and inject concrete constructor dependencies. Do not retain an installer or add new global service locators, singletons, or static events.
- GameData owns configuration and data primitives; Services owns persistence, messaging, commands, and asset loading. Reuse Statechart and UI Service for flow and presenters.
- Runtime code must not reference
UnityEditor. Put tooling in Editor/ and Editor-only assemblies. Declare direct asmdef references for types consumed through other packages’ APIs.
- Preserve asset GUIDs, serialized field names, enum values, Addressables addresses, and assembly-qualified presenter bindings. Check scenes, prefabs, config assets, and saved data before renaming or deleting. Use explicit migrations for incompatible changes.
- Unity creates
.meta files. Commit them with assets and retain them on moves; never manufacture GUIDs. Do not modify authored configuration assets at runtime.
- Keep reflection-created save types and their serialized members preserved for IL2CPP in
Assets/Src/link.xml; an Editor test cannot prove managed stripping compatibility.
- Preserve persistence keys and stored type names. Test loading existing data when changing serialization, defaults, save ownership, or assembly names; keep a recoverable copy before destructive migration.
Coding standards
- Read
Docs/CODING_STANDARDS.md before writing or reviewing source, tests or tools. It owns code shape, naming, documentation and member ordering; .editorconfig owns mechanical formatting and IDE diagnostics.
- Review the complete touched type, not just the diff. Preserve serialized layout and generated-source ownership when applying the standards.
Validation and documentation
- Run
Tools/validate.sh static for repository checks, then compile and run relevant EditMode/PlayMode tests for code changes. Serialize Unity processes for this project and never stop an Editor belonging to another project.
- Tests assert observable behavior and costly invariants. Use
Behavior_Condition_ExpectedResult names; avoid reflection on private state, redundant implementation-mirroring tests, and unexplained skipped tests.
- Compilation, automated tests, Addressables builds, player builds, browser behavior, rendering, and device execution are separate evidence. Inspect result artifacts and report
Pass, Fail, Blocked, or Not run; never infer runtime correctness from a successful process exit.
- Inspect the visible result for UI or rendering changes. Android builds and iOS exports do not prove signed installation, device execution, or store readiness.
- Keep the README focused on onboarding, architecture ownership, dependencies, and executable commands. Update it when those contracts change; omit copied package APIs and dated validation claims.