8.4 KiB
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_*.pyregressions:tools/extractors/sound_bank.py,tests/test_actor_contact.py. - Keep shell entry points under
scripts/, using descriptive hyphenated names such asscripts/test-window-transitions.sh.
Functions:
- Use PascalCase C# methods (
ReadVelocity,GenericWall) as insrc/GamePort/Game/OriginalNormalContacts.cs. - Use snake_case Python functions (
export_sound_bank,validate_output) as intools/extractors/sound_bank.pyandtools/extractors/omt.py. - Name Python test methods
test_<behavior>;tests/test_extractors.pynames invalid-input cases explicitly.
Variables:
- Use camelCase C# parameters and locals, with explicit role names such as
headingUnits,oldHeading,carriedPlayerinsrc/GamePort/Game/OriginalNormalContacts.csandsrc/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_OPERANDSintests/test_actor_contact.py).
Types:
- Use PascalCase C# classes/records and
I-prefixed interfaces, exemplified byOriginalNormalContactsandIOriginalNormalBodyinsrc/GamePort/Game/OriginalNormalContacts.cs. - Python uses PascalCase classes and frozen dataclasses for resource identity (
Reader,Entry,FormatErrorintools/extractors/omt.py).
Code Style
Formatting:
- No tracked formatter or
.editorconfigis 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.csprojenables 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 intests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj.
Import Organization
Order:
- C# explicit
Systemnamespaces precede project namespaces insrc/GamePort/Program.csandtests/GamePort.ActorContactTests/Program.cs. - Group runtime dependencies by namespace; implicit usings supply common base namespaces (
GamePort.csproj). - 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.Gameand 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.cscatches 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
PASSmessages and throw on failure (tests/GamePort.ActorContactTests/Program.cs). - Persist verification scope and limitations in
docs/progress.md,docs/compatibility.mdand 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.mdanddocs/checkpoint/actor-normal-contacts.mdmake 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.csremains 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 (
IOriginalNormalBodyinsrc/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 insrc/GamePort/Game/, SDL interop insrc/GamePort/Platform/Sdl.cs, and presentation insrc/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 inAGENTS.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