Files
2026-11-12 11:06:58 -05:00

8.4 KiB

last_mapped_commit, last_mapped_at
last_mapped_commit last_mapped_at
bdca29d3aa 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:

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