# NVGT Coding Patterns

Use these patterns for clean, separated, reusable NVGT code.

## 1. Module Boundaries

- Keep game-specific orchestration separate from reusable helpers.
- Put reusable helpers into dedicated library modules (e.g., `libstorm-nvgt/`).
- Keep adapters thin:
Project modules should configure and call reusable modules, not duplicate internals.

## 2. Naming and Simplicity

- Prefer snake_case for functions/methods.
- Prefer camelCase for variables.
- Keep APIs narrow: small setup functions + one runtime function.
- Avoid hidden globals unless they model subsystem state intentionally.

## 3. Loop Safety

- In long-running menu/game loops, keep `wait(5);`.
- Use per-loop tick callbacks for background tasks (volume keys, timers, notifications).
- Keep menu navigation behavior explicit (wrap on/off, exit keys, select keys).

## 4. Accessibility-First UI

- Prefer screen reader output and NVGT UI primitives (`form`, `virtual_dialogs`, `menu`) over external speech daemons.
- Ensure keyboard navigation has no traps.
- Keep labels complete and unambiguous.

## 5. Audio Conventions

- Use deterministic sound path conventions:
`sounds/menu/...`, `sounds/notify...`.
- Prefer extension fallback helpers (`.ogg`, then `.wav`) when building reusable modules.
- Guard optional sounds with existence checks.

## 6. Verify, Then Generalize

- Before extracting a helper, verify behavior from:
docs -> include wrapper -> C++ binding.
- Extract only stable behavior shared by multiple projects.
- Leave highly game-loop-specific logic in the project.