--- last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 last_mapped_at: 2026-11-12 --- # Coding Conventions **Analysis Date:** 2026-11-12 ## Naming Patterns **Files:** - Use PascalCase C# filenames matching the principal type: `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`. - Use snake_case Python modules and `test_*.py` regressions: `tools/extractors/sound_bank.py`, `tests/test_actor_contact.py`. - Keep shell entry points under `scripts/`, using descriptive hyphenated names such as `scripts/test-window-transitions.sh`. **Functions:** - Use PascalCase C# methods (`ReadVelocity`, `GenericWall`) as in `src/GamePort/Game/OriginalNormalContacts.cs`. - Use snake_case Python functions (`export_sound_bank`, `validate_output`) as in `tools/extractors/sound_bank.py` and `tools/extractors/omt.py`. - Name Python test methods `test_`; `tests/test_extractors.py` names invalid-input cases explicitly. **Variables:** - Use camelCase C# parameters and locals, with explicit role names such as `headingUnits`, `oldHeading`, `carriedPlayer` in `src/GamePort/Game/OriginalNormalContacts.cs` and `src/GamePort/Program.cs`. - Private C# fields do not uniformly use underscore prefixes; match the surrounding module (`src/GamePort/Assets/GamLevel.cs`). - Python locals use snake_case; module constants use uppercase (`ROOT`, `ORIGINAL`, `CALLBACK_OPERANDS` in `tests/test_actor_contact.py`). **Types:** - Use PascalCase C# classes/records and `I`-prefixed interfaces, exemplified by `OriginalNormalContacts` and `IOriginalNormalBody` in `src/GamePort/Game/OriginalNormalContacts.cs`. - Python uses PascalCase classes and frozen dataclasses for resource identity (`Reader`, `Entry`, `FormatError` in `tools/extractors/omt.py`). ## Code Style **Formatting:** - No tracked formatter or `.editorconfig` is detected in the mapped repository. Follow each file's existing style rather than assuming an enforced formatter (`GamePort.csproj`, `src/GamePort/Assets/GamLevel.cs`). - C# generally uses four spaces, file-scoped namespaces and braces on separate lines; short guards and expression-bodied helpers are common. Some numerical modules and console tests use compact spacing (`src/GamePort/Game/OriginalNormalContacts.cs`, `tests/GamePort.JimmyGroundTests/Program.cs`). - Python uses four spaces, type annotations where useful, and compact reader helpers; quotation style varies (`tools/extractors/omt.py`, `tools/extractors/sound_bank.py`). **Linting:** - Dedicated C#/Python lint configurations are Not detected. `GamePort.csproj` enables nullable references, implicit usings and unsafe blocks; it does not declare warnings-as-errors or a separate analyzer package. - Preserve explicit compile globs and shader copy rules in `GamePort.csproj`; test projects can compile production source directly, as in `tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`. ## Import Organization **Order:** 1. C# explicit `System` namespaces precede project namespaces in `src/GamePort/Program.cs` and `tests/GamePort.ActorContactTests/Program.cs`. 2. Group runtime dependencies by namespace; implicit usings supply common base namespaces (`GamePort.csproj`). 3. Python standard library imports precede local tool imports. Tests insert the relevant tools directory into `sys.path` (`tests/test_extractors.py`, `tests/test_actor_contact.py`). **Path Aliases:** - No frontend-style aliases are applicable. Use `GamePort.Assets`, `GamePort.Game` and related C# namespaces; Python tool imports resolve from explicit local paths (`src/GamePort/Program.cs`, `tests/test_actor_contact.py`). ## Error Handling **Patterns:** - Fail malformed assets with contextual format exceptions, including offsets. Do not silently truncate or accept trailing bytes (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/omt.py`). - Reject unsupported recovered behavior explicitly with `NotSupportedException`; validate nonfinite values separately with argument exceptions (`src/GamePort/Game/OriginalNormalContacts.cs`). - Keep entry-point failure reporting centralized: `src/GamePort/Program.cs` catches exceptions, writes to stderr and returns status 1. - Resolve original asset names case-insensitively after direct lookup, reject `.`/`..`, and reject missing/ambiguous matches (`src/GamePort/Assets/AssetPath.cs`). - Reject extraction output overlapping originals; preserve source hashes and archive identities in generated metadata (`tools/extractors/sound_bank.py`). Representative bounded C# reader from `src/GamePort/Assets/GamLevel.cs`: ```csharp public ReadOnlySpan Take(int length) { if (length < 0 || length > Remaining) throw new InvalidDataException($"Truncated GAM at {Offset:x}"); var result = data.Slice(Offset, length); Offset += length; return result; } public uint U32() => BinaryPrimitives.ReadUInt32BigEndian(Take(4)); ``` ## Logging **Framework:** Console output, with explicit application diagnostics; no hosted logging service is detected (`src/GamePort/Program.cs`, `src/GamePort/Application/DebugDiagnostics.cs`). **Patterns:** - Report fatal errors to `Console.Error`; expose inspection/smoke commands and readback paths through CLI options (`src/GamePort/Program.cs`). - Tests print descriptive `PASS` messages and throw on failure (`tests/GamePort.ActorContactTests/Program.cs`). - Persist verification scope and limitations in `docs/progress.md`, `docs/compatibility.md` and subsystem reports; console success alone does not establish whole-game equivalence. ## Comments **When to Comment:** - Explain original addresses, ownership, sampled field order and excluded behavior rather than restating arithmetic (`src/GamePort/Game/OriginalNormalContacts.cs`). - Preserve concrete resource semantics: effect IDs are archive identities, and encoded audio preservation is separate from decoder support (`tools/extractors/sound_bank.py`). - Keep recovered contracts distinct from approximations and runtime admission; `AGENTS.md` and `docs/checkpoint/actor-normal-contacts.md` make these evidence boundaries explicit. **XML documentation / Python docstrings:** - Use C# `/// ` for bounded public contracts and interfaces (`src/GamePort/Game/OriginalNormalContacts.cs`). - Use Python module/class docstrings for recovery purpose and failure semantics (`tools/extractors/omt.py`). JSDoc/TSDoc is Not applicable. ## Function Design **Size:** - Prefer focused components such as the ceiling/reflection helpers in `src/GamePort/Game/OriginalNormalContacts.cs`; no numerical line-count rule is detected. `src/GamePort/Program.cs` remains a substantial orchestration entry point. **Parameters:** - Use explicit vectors, typed state and named flags rather than hidden scene state in recovered algorithms (`src/GamePort/Game/OriginalNormalContacts.cs`, `tests/GamePort.JimmyGroundTests/Program.cs`). - Inject actor-owned accessors through interfaces where read order matters; do not cache values across callbacks without evidence (`IOriginalNormalBody` in `src/GamePort/Game/OriginalNormalContacts.cs`). - Keep bounded readers over spans/bytes and explicitly choose endianness (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/omt.py`). **Return Values:** - Return parsed records, typed state, or explicit metadata; throw for malformed/unsupported input (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/sound_bank.py`). - Preserve float-store boundaries and intentional double intermediates in recovered math. Do not simplify formulas or clamp source values without evidence (`src/GamePort/Game/OriginalNormalContacts.cs`, `docs/checkpoint/dynamic-reclip.md`). ## Module Design **Exports:** - Keep asset decoding in `src/GamePort/Assets/`, recovered algorithms in `src/GamePort/Game/`, SDL interop in `src/GamePort/Platform/Sdl.cs`, and presentation in `src/GamePort/Application/`. - Python tools expose importable parser/export functions as well as CLI-oriented modules (`tools/extractors/omt.py`, `tools/extractors/sound_bank.py`). - Use `using`/disposal and explicit native ownership at runtime boundaries (`src/GamePort/Program.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`); follow the project requirement in `AGENTS.md`. **Barrel Files:** - Not detected / Not applicable. C# namespaces and project compile includes provide organization (`GamePort.csproj`). - Project-local agent skill constraints: the configured agent-skill query is empty; the applicable project constraints are in `AGENTS.md`. --- *Convention analysis: 2026-11-12*