draugnorak/skills/nvgt-engine-dev/references/common-playbooks.md

Common Playbooks

Use these when implementing frequent NVGT tasks.

1. Extract Reusable Module

1. Identify stable API boundary.
2. Move generic code to library module.
3. Leave game-specific data flow in project wrapper.
4. Add minimal setup hooks (callbacks/path settings).
5. Compile-check immediately.

2. Build Menu Subsystem

1. Choose engine primitive (menu, audio_form, or custom loop).
2. Define navigation keys and wrap behavior explicitly.
3. Add menu sounds by configurable path.
4. Add optional tick callback for background updates.
5. Verify keyboard-only operation and escape paths.

3. Build Notification Subsystem

1. Implement queue and bounded history.
2. Add key navigation for older/newer/latest entries.
3. Keep playback delay configurable.
4. Route speech through project-selected speak callback.
5. Verify behavior with and without notification sound files.

4. Build File/Docs Viewer

1. Keep viewer/editor generic.
2. Add project wrapper for labels/path conventions.
3. Ensure read-only mode is truly non-destructive.
4. Add optional save path for edit mode only.
5. Verify open failure and save failure speech paths.

5. Add Global Volume Controls

1. Centralize min/max/step and current dB.
2. Add key handler (PageUp/PageDown by default).
3. Support callback to apply volume in project audio layer.
4. Announce volume as percent for accessibility.
5. Verify no-op behavior at bounds.