Implement i18n audit/localization cleanup and sync libstorm submodule
This commit is contained in:
Storm Dragon
@@ -0,0 +1,44 @@
|
||||
# API Verification Workflow
|
||||
|
||||
Use this order whenever a user asks NVGT API behavior, signatures, or edge cases.
|
||||
|
||||
## Step 1: Locate candidate APIs in docs
|
||||
|
||||
1. Search `doc/src/references/` for the symbol.
|
||||
2. If the symbol looks include-specific, search `doc/src/references/include/`.
|
||||
3. If built-in, search `doc/src/references/builtin/`.
|
||||
4. If plugin-related, search `doc/src/references/plugin/`.
|
||||
|
||||
## Step 2: Confirm scripted helper behavior
|
||||
|
||||
Search `release/include/` for wrappers and defaults.
|
||||
|
||||
Why:
|
||||
- Includes often add defaults, convenience behavior, and compatibility layers not visible in short reference pages.
|
||||
|
||||
## Step 3: Confirm engine truth in C++
|
||||
|
||||
When still ambiguous, inspect `src/*.cpp` bindings:
|
||||
|
||||
- Search registration calls:
|
||||
`RegisterGlobalFunction`, `RegisterObjectMethod`, `RegisterObjectProperty`, `RegisterFuncdef`.
|
||||
- Verify exact exposed signatures and overloads.
|
||||
- Read nearby implementation for side effects and constraints.
|
||||
|
||||
## Step 4: Produce answer/change with evidence
|
||||
|
||||
- Cite the exact file(s) used for verification.
|
||||
- Prefer concise behavior statements over speculation.
|
||||
- Mark inferred behavior explicitly when not directly declared.
|
||||
|
||||
## Quick Commands
|
||||
|
||||
```bash
|
||||
# Broad symbol search across NVGT docs/includes/source
|
||||
python3 skills/nvgt-engine-dev/scripts/nvgt_lookup.py "screen_reader_speak" --root ./nvgt-git
|
||||
```
|
||||
|
||||
```bash
|
||||
# Direct C++ binding verification
|
||||
rg -n "RegisterGlobalFunction|RegisterObjectMethod|screen_reader_speak" nvgt-git/src
|
||||
```
|
||||
@@ -0,0 +1,43 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,43 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,41 @@
|
||||
# Project Profile
|
||||
|
||||
Use this profile when project-specific guidance is missing.
|
||||
If the repo has `AGENTS.md` or equivalent, that file overrides this profile.
|
||||
|
||||
## Default Engineering Style
|
||||
|
||||
- Prefer clean separation of concerns.
|
||||
- Keep reusable logic in standalone modules.
|
||||
- Keep adapters/wrappers thin and obvious.
|
||||
- Favor simple, direct control flow over clever abstractions.
|
||||
|
||||
## Naming Defaults
|
||||
|
||||
- Functions/methods: `snake_case`
|
||||
- Variables: `camelCase`
|
||||
- Classes/types: `PascalCase`
|
||||
|
||||
## Accessibility Defaults
|
||||
|
||||
- Prefer NVGT accessibility APIs and native screen-reader paths.
|
||||
- Avoid unnecessary visual-only coupling in interaction flows.
|
||||
- Ensure keyboard navigation is complete and trap-free.
|
||||
|
||||
## Audio/UI Defaults
|
||||
|
||||
- Use stable folder conventions for project-owned assets.
|
||||
- Keep menu and notification sounds configurable by path.
|
||||
- Support `.ogg` first and allow `.wav` fallback where practical.
|
||||
|
||||
## Refactor Rules
|
||||
|
||||
- Extract only behavior used across multiple modules/projects.
|
||||
- Do not extract heavily game-loop-specific orchestration.
|
||||
- Preserve behavior first; optimize structure second.
|
||||
|
||||
## Delivery Expectations
|
||||
|
||||
- Provide concise decisions with concrete file references.
|
||||
- Explicitly state assumptions when source evidence is incomplete.
|
||||
- Prefer incremental, verifiable changes over large rewrites.
|
||||
@@ -0,0 +1,35 @@
|
||||
# NVGT Regression Checklist
|
||||
|
||||
Run this checklist after meaningful NVGT changes.
|
||||
|
||||
## API/Source Verification
|
||||
- Verified changed API assumptions against NVGT primary sources.
|
||||
- For uncertain behavior, confirmed bindings in `<nvgt-root>/src/`.
|
||||
|
||||
## Compile
|
||||
- Project compile command succeeds.
|
||||
- No new compile warnings/errors introduced.
|
||||
|
||||
## Input/Navigation
|
||||
- Keyboard navigation works end-to-end.
|
||||
- Escape/close paths work from each UI/menu path.
|
||||
- No keyboard traps.
|
||||
|
||||
## Screen Reader
|
||||
- New/changed controls announce meaningful labels.
|
||||
- Important events are announced consistently.
|
||||
- History/notification key paths still function if present.
|
||||
|
||||
## Audio
|
||||
- Required sound paths resolve correctly.
|
||||
- Missing optional sounds fail gracefully.
|
||||
- Long-running loops do not leak/dangle sound handles.
|
||||
|
||||
## Data Safety
|
||||
- File read/write failure paths are handled.
|
||||
- Save/load or serialization paths preserve prior behavior.
|
||||
- No accidental destructive behavior in migrations.
|
||||
|
||||
## Reuse Boundary
|
||||
- Generic vs project-specific code separation is clear.
|
||||
- Extracted modules have minimal coupling.
|
||||
@@ -0,0 +1,73 @@
|
||||
# NVGT Repo Map
|
||||
|
||||
Use this map to choose the fastest authoritative source in `nvgt-git`.
|
||||
|
||||
## 1. Documentation First
|
||||
|
||||
- `doc/src/manual/`
|
||||
Practical tutorials, project workflows, and conceptual guidance.
|
||||
Start here for process questions (build, compile/distribute, debugging scripts, concurrency/subscripting tutorials).
|
||||
|
||||
- `doc/src/references/`
|
||||
API entry points.
|
||||
Use this when you need object/function names and category-level API navigation.
|
||||
|
||||
- `doc/src/references/builtin/`
|
||||
Built-in script API categories:
|
||||
`Audio`, `Filesystem`, `User Interface`, `Text-To-Speech`, `Concurrency`, etc.
|
||||
|
||||
- `doc/src/references/include/`
|
||||
Bundled include APIs (`form.nvgt`, `menu.nvgt`, `sound_pool.nvgt`, `music.nvgt`, etc.).
|
||||
|
||||
- `doc/src/references/plugin/`
|
||||
Plugin APIs (`git2nvgt`, `nvgt_curl`, `nvgt_sqlite`, `systemd_notify`).
|
||||
|
||||
## 2. Bundled Script Includes
|
||||
|
||||
- `release/include/`
|
||||
Reference implementation of bundled `.nvgt` includes shipped with NVGT.
|
||||
Use this to verify behavior details not obvious in docs.
|
||||
|
||||
Key files:
|
||||
- `release/include/form.nvgt`
|
||||
- `release/include/menu.nvgt`
|
||||
- `release/include/sound_pool.nvgt`
|
||||
- `release/include/virtual_dialogs.nvgt`
|
||||
- `release/include/music.nvgt`
|
||||
- `release/include/speech.nvgt`
|
||||
- `release/include/bgt_dynamic_menu.nvgt`
|
||||
|
||||
## 3. Engine Binding Source (Truth Layer)
|
||||
|
||||
- `src/*.cpp`
|
||||
C++ registration and implementation of script-facing APIs.
|
||||
Use this when docs and includes do not fully answer behavior/signature questions.
|
||||
|
||||
High-value files:
|
||||
- `src/nvgt.cpp`
|
||||
CLI modes/options (`-c`, `-d`, include dirs, platform flags, settings).
|
||||
- `src/scriptstuff.cpp`
|
||||
Script module/function APIs, profiling/debug hooks, call stack support.
|
||||
- `src/tts.cpp`
|
||||
Screen reader + TTS object registration.
|
||||
- `src/sound.cpp`, `src/sound_nodes.cpp`, `src/sound_service.cpp`
|
||||
Sound and audio subsystem behavior.
|
||||
- `src/input.cpp`, `src/UI.cpp`
|
||||
Keyboard/window/UI interaction behavior.
|
||||
- `src/filesystem.cpp`, `src/datastreams.cpp`, `src/serialize.cpp`
|
||||
File/stream/serialization behavior.
|
||||
|
||||
## 4. Samples
|
||||
|
||||
- `extra/samples/`
|
||||
Small scripts demonstrating typical usage.
|
||||
Use to confirm common idioms before inventing new patterns.
|
||||
|
||||
## 5. Build and Packaging
|
||||
|
||||
- `readme.md`
|
||||
Engine build prerequisites and SCons usage.
|
||||
- `doc/src/manual/compiling your project for distribution.md`
|
||||
Compile + bundle guidance.
|
||||
- `build/`, `install/`, `release/`
|
||||
Build scripts and packaging infrastructure.
|
||||
Reference in New Issue
Block a user