Development

How to contribute: branches, the project's rules, where findings are recorded, and how commits are written (as of 2026-11-10).

Branches and workflow

• develop is the working branch; master is the main branch. CI (.github/workflows/cna-ci.yml) builds and tests on pushes and pull requests to either; changes that touch only web/ (this website) are ignored by it.
• One discrete task per commit, with the checks that apply run first (Testing & QA, "Which checks for which change"). Stage by path, so unrelated working-tree changes stay out of your commit.
• A fix for a reproduced defect comes with a regression test where one is possible. Do not restructure a working system "while you are there".
• Before changing gameplay, read what the original does (the sibling repository mobile-eggbert, mostly Decor.cpp) and search the ledgers below: the same difference may already have been analysed.
• A change that alters the verified state, a supported build, a known limitation or the open work is reflected in CURRENT.md, the project's status document. plan.md, NEXT.md and handoff.md are historical or working logs.

The rules

These are the project owner's rules (from CURRENT.md, AGENTS.md and docs/handbook/01-overview.md). Most defects in the history came from breaking one of them.

1. Every gameplay feature traces to confirmed Mobile Eggbert behaviour. Where a 2D rule has no unique 3D reading, pick a small reading and record it as an intentional 3D adaptation (plans/audit/mechanics_3d_decisions.md, rows M3D-NNNN).
2. The original is a read-only reference. Its C++ source is the authority for numbers and timing. Do not copy its code, tables, enum values or byte layouts without approval; a standing approval (2026-10-25) covers small data tables needed for fidelity, with the source cited in a comment.
3. Reuse approved media by their existing paths (Content/). A new copied asset set needs approval.
4. Never renumber IDs: Def::ObjectType, block (icon) numbers and sound channels are stored in world files and encode reference data.
5. Worlds are hand-authored true 3D designs. The original's 2D maps give identity, theme, mechanics and difficulty, nothing else: no conversion, extrusion, tracing or side-view "2.5D" (tried and rejected on 2026-10-25).
6. Models and animations come from the original Ray Dream sources whenever they can be recovered; effects (explosions, sparks, glows) may stay billboards.
7. The in-game 3D world editor is the one approved exception: its UX may be invented, but it must not add gameplay.

Repository boundaries

• The sibling repositories (cna, cna-engine, easy-gl, sharp-runtime, meta-gl, mobile-eggbert) are not modified from here unless a task is explicitly scoped to them. A defect found there is written down as an upstream bug (below); a bug in cna-engine that blocks the game is fixed in cna-engine, with a test, rather than worked around here.
• InteractionSystem stays free of controller, camera and graphics dependencies; it reports events and requests (InteractionSystem).
• The engine-independent model (include/GalaxyEggbert/, src/GalaxyEggbert/Worlds/) has no CNA or cna-engine includes.
• No backend-specific branches in game logic. Reuse existing engine-independent code and its tests before re-deriving math or reference behaviour (missing.md records cases where that was missed).

Ledgers: plans/audit/

The fidelity audit (plans/GALAXY_EGGBERT_FIDELITY_AUDIT.md) compares Galaxy with the original row by row. Its tables are the project's memory of what was found and why: read them before re-deriving a difference, add to them when you find one. Cite an id in code comments and commit subjects when it helps the next reader.

Other tables there include gameplay_use_cases.csv, render_representation.csv, asset_sources.csv, test_coverage.csv, target_reach.md and release_audit.md. Status vocabulary: UNREVIEWED, CONFIRMED_MATCH, INTENTIONAL_3D_ADAPTATION, REPRODUCED_DEFECT, FIXED_AND_VERIFIED, BLOCKED, NOT_APPLICABLE; only evidence moves a row. The generators in tools/audit/ have a --check mode that reports a stale table. Older code comments also cite task ids of plan.md (E3D-MIG-, BB3D-, INFRA-, TEST-, EDITOR-...).

Bugs in sibling repositories: upstream_bugs.md

A defect found in CNA, cna-engine, easy-gl, sharp-runtime or a data repository goes at the end of upstream_bugs.md as the next UB-NNN, in English: repository, file and line, the date and how it was found; the problem, a minimal reproduction and the suggested fix; the workaround used here, if any; and the status. When it is fixed upstream, the entry stays, the fixing commit is added, and the workaround is removed only after re-verifying. As of 2026-11-10 the file holds UB-001 to UB-010, all marked fixed upstream (UB-005 in cna-engine, the others in CNA).

CI checks out the siblings at pinned revisions. After verifying a build against newer siblings, python3 tools/ci_pin_siblings.py updates the pins (--check reports drift without writing).

Commit messages

The history uses conventional subjects, type(scope): subject, in English, usually under about 95 characters, with a body for anything non-obvious. Types by frequency (2026-11-10): docs, feat, fix, test, then far fewer refactor, tools, build, perf, ci, chore. Common scopes: worlds, render, gameplay, editor, terrain, camera, audio, blupi, qa, cheats, golden, audit. Some recent commits use a plain Area: subject form instead (Android: own package id, installs beside mobile-eggbert).

Put the ledger id in the subject when the change closes or advances a row. Real examples:

fix(cheats): BD-0081 match reference ghost behavior
feat(worlds): LV-0078 world 199 rebuilt as a journey of twelve places (A to L)
perf(terrain): a crumbling clay bridge patches the model cells instead of rebuilding the world (OR-0074)
test(golden): re-baselined after the ball cubes' tops (6 px at a treasure door's plate edge)

The body says what the original does, what Galaxy did before, what changed, and how it was verified (ctest result, golden frames and trace, which playthroughs). Re-baselined golden files are committed on their own with the reason. Read git log --oneline -30 before writing yours.