122 lines
8.4 KiB
Markdown
122 lines
8.4 KiB
Markdown
---
|
|
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_<behavior>`; `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<byte> 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# `/// <summary>` 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*
|