Skip to main content
Use this reference when a change spans UI, settings, policy, runtime behavior, .akr packs, commands, HUD, or tests. It defines where new code must reside to ensure contributor changes remain focused.

​
Feature Flow

Most feature work crosses these layers:

​
Primary Files

​
Adding A Feature

Start from behavior, not from the UI label.
  1. Decide whether the feature is a toggle, button, numeric toggle, radio/dropdown mode, checkbox list, or read-only label.
  2. Add settings only for state that must persist.
  3. Keep transient runtime state in session or a focused service.
  4. Add an AkronFeatureKind only if runtime policy checks or attempt tracking need a reusable policy unit.
  5. Add the FeatureDefinition and any UI-only label or suboption classifications.
  6. Add the overlay row with the control type that matches the interaction.
  7. Gate runtime behavior with TryUse when the behavior should record use.
  8. Use CanUse when code only needs to decide whether a surface should render or be available.
  9. Add tests for classification, defaults, clamps, archive shape, or non-trivial behavior.
  10. Update docs when visible behavior, policy, file locations, debug commands, or .akr contracts change.

​
Overlay Boundaries

Keep Source/Overlay/AkronOverlay.cs focused on overlay orchestration. Use existing row helpers before adding UI machinery. Configuration changes should not activate a feature by themselves. A dropdown mode, numeric value, or checkbox inside a tooltip updates configuration only. The parent row decides whether that configuration is active. Use focused overlay partials for feature families: Source/Overlay/akron-overlay-popup-controls.cs is a containment boundary for the current option-popup catalog. When a popup grows into a full editor, browser, or feature-family surface, move that family into a smaller focused partial instead of growing the catalog further.

​
Module And Runtime Boundaries

Keep Source/Module/AkronModule.cs focused on lifecycle and hook orchestration. If a feature family needs several helpers around one visual or runtime concept, put those helpers in a focused partial and call into it from the hook.

​
Settings Boundaries

Keep the main settings file focused on persisted properties, menu entries, formatting, and clamp helpers. Defaults should be opt-in for anything that changes gameplay, reveals hidden information, changes proof assumptions, or adds an overlay. Tests should lock those defaults. For numeric settings:
  • Add a clamp helper when the value comes from user input or setup import.
  • Use invariant-culture parsing for command and debug paths.
  • Keep the row label as on/off when the feature has an enabled state.
  • Put numeric configuration in the option menu.

​
Save, HUD, And Inspector Boundaries

Keep Source/SaveLoad/AkronSaveLoad.cs focused on save/load orchestration and native restore sequencing. Keep Source/Hud/AkronHudRenderer.cs as the high-level HUD orchestration surface. Hitbox viewer entity selection, last-death marker state, player trail capture, and render orchestration belong in Source/Tools/akron-entity-inspector.cs. Exact-pixel, circle-run, grid-outline, and outline sample geometry helpers belong in Source/Tools/akron-entity-inspector-raster-geometry.cs. Custom HUD label rendering, template formatting, obstruction handling, and layout belong in Source/Hud/akron-custom-hud-labels.cs. Default label construction, cloning, active label mutation, preset insertion, and .akr label-pack import/export belong in Source/Hud/akron-custom-hud-label-catalog.cs.

​
Command Boundaries

DebugRC and file-backed automation commands should route into the same runtime helpers as the overlay. Keep Source/Commands/akron-commands.cs for shared command plumbing. Put focused command families in Source/Commands/akron-*-commands.cs files:

​
Review Traps

Before finishing a feature, check for these common mistakes:
  • A tooltip setting activates behavior without the parent toggle being on.
  • A button was implemented as a toggle.
  • A Cheat suboption inherits a clean parent badge.
  • A runtime draw check records feature use merely because a menu is open.
  • A persisted setting was added to AkronModuleSettings but not to setup capture/apply.
  • A new .akr payload accepts extra ZIP entries or missing manifests.
  • A docs update changed policy wording but the registry/tests still say something else.