Translation updates and submodule sync

This commit is contained in:
Storm Dragon
2026-02-28 01:03:26 -05:00
parent 8a429d8c2d
commit 671d6b7898
102 changed files with 14288 additions and 3692 deletions
+66
View File
@@ -0,0 +1,66 @@
---
name: nvgt-engine-dev
description: Build, debug, refactor, and document NVGT (.nvgt) projects using authoritative NVGT engine sources. Use when tasks involve NVGT API usage, include/module selection, behavior verification against engine internals, migration from BGT-style patterns, menu/audio/UI architecture, or extracting reusable NVGT utilities.
---
# NVGT Engine Dev
Use this skill to resolve NVGT questions from primary sources and produce clean, modular, reusable NVGT code.
## Core Rules
- Verify API behavior with NVGT primary sources, not memory.
- Prefer docs first, then include implementation, then C++ bindings when behavior is unclear.
- Keep code simple, separated by concern, and reusable across projects.
- Keep accessibility first: rely on screen-reader APIs and keyboard-safe flows.
## Workflow
1. Locate the NVGT source tree.
Default path is `~/git/nvgt`.
If missing, ask for `--root` override before making API claims.
2. Read `references/repo-map.md`.
Use it to pick the right source tier quickly.
3. Run lookup before coding.
Use `scripts/nvgt_lookup.py` for symbol-level discovery across docs/includes/bindings.
For signature-focused evidence, run `scripts/nvgt_api_report.py`.
4. Verify uncertain behavior in C++ bindings.
Read files under `<nvgt-root>/src/` where `RegisterGlobalFunction`, `RegisterObjectMethod`, or related registration calls are made.
5. Implement with modular boundaries.
Split generic utilities from game-specific logic.
6. Compile-check.
For Draugnorak-style projects, run `./nvgt -c draugnorak.nvgt` after changes.
## Lookup Command
```bash
python3 skills/nvgt-engine-dev/scripts/nvgt_lookup.py "symbol_or_phrase"
```
Use `--root /path/to/nvgt` only when NVGT is not at `~/git/nvgt`.
## API Report Command
```bash
python3 skills/nvgt-engine-dev/scripts/nvgt_api_report.py "symbol_name"
```
Use this report when you need signature/binding evidence before answering or coding.
Use `--section` to narrow:
- `docs`
- `include-docs`
- `builtin-docs`
- `plugin-docs`
- `release-includes`
- `bindings`
- `samples`
## References
- Read `references/project-profile.md` first when repo-specific style rules are absent.
- Read `references/repo-map.md` first for where things live in NVGT.
- Read `references/api-verification-workflow.md` when API behavior/signatures are uncertain.
- Read `references/nvgt-coding-patterns.md` when designing modules, menus, notifications, file viewers, and reusable libraries.
- Read `references/common-playbooks.md` for common implementation patterns.
- Run through `references/regression-checklist.md` before finalizing non-trivial NVGT changes.
## Delivery Style
- Give direct, actionable answers.
- Show file-level references for where behavior was verified.
- Prefer minimal wrappers around engine primitives before adding abstraction.
@@ -0,0 +1,4 @@
interface:
display_name: "NVGT Engine Dev"
short_description: "Use NVGT docs/source for clean modular scripting."
default_prompt: "Use NVGT authoritative docs, includes, and engine source to verify API behavior, design clean module boundaries, and implement accessible .nvgt game code."
@@ -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.
+96
View File
@@ -0,0 +1,96 @@
#!/usr/bin/env python3
"""Generate a signature-focused NVGT API evidence report for a symbol."""
from __future__ import annotations
import argparse
import re
import shutil
import subprocess
import sys
from pathlib import Path
def discover_nvgt_root(explicit_root: str) -> Path | None:
if explicit_root:
root = Path(explicit_root).expanduser().resolve()
return root if root.exists() else None
default_root = Path.home() / "git" / "nvgt"
default_resolved = default_root.expanduser().resolve()
if default_resolved.exists():
return default_resolved
return None
def run_rg(pattern: str, paths: list[Path], max_count: int) -> str:
existing = [str(path) for path in paths if path.exists()]
if not existing:
return ""
cmd = [
"rg",
"-n",
"--hidden",
"--no-ignore",
"--max-count",
str(max_count),
pattern,
*existing,
]
proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
if proc.returncode in (0, 1):
return proc.stdout.strip()
raise RuntimeError(proc.stderr.strip() or "ripgrep failed")
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(description="Create an NVGT API evidence report for a symbol.")
parser.add_argument("symbol", help="Function/object/symbol to inspect")
parser.add_argument("--root", default="", help="Path to NVGT root (default: ~/git/nvgt)")
parser.add_argument("--max-count", type=int, default=25, help="Max matches per section (default: 25)")
return parser.parse_args()
def main() -> int:
if shutil.which("rg") is None:
print("Error: ripgrep (rg) is required.", file=sys.stderr)
return 2
args = parse_args()
nvgt_root = discover_nvgt_root(args.root)
if nvgt_root is None:
print("Error: NVGT root not found at ~/git/nvgt. Pass --root to override.", file=sys.stderr)
return 2
escaped_symbol = re.escape(args.symbol)
docs_pattern = rf"\b{escaped_symbol}\b"
include_pattern = docs_pattern
bindings_pattern = rf"Register(GlobalFunction|ObjectMethod|ObjectProperty|Funcdef).*\b{escaped_symbol}\b"
sample_pattern = docs_pattern
sections = [
("docs-references", docs_pattern, [nvgt_root / "doc/src/references"]),
("include-wrappers", include_pattern, [nvgt_root / "release/include"]),
("bindings-signatures", bindings_pattern, [nvgt_root / "src"]),
("samples", sample_pattern, [nvgt_root / "extra/samples"]),
]
any_match = False
print(f"NVGT root: {nvgt_root}")
print(f"Symbol: {args.symbol}")
for title, pattern, paths in sections:
output = run_rg(pattern, paths, args.max_count)
if output:
any_match = True
print(f"\n== {title} ==")
print(output)
if not any_match:
print("\nNo matches found in evidence sections.")
return 1
return 0
if __name__ == "__main__":
raise SystemExit(main())
+120
View File
@@ -0,0 +1,120 @@
#!/usr/bin/env python3
"""Search NVGT docs/includes/bindings in one command."""
from __future__ import annotations
import argparse
import shutil
import subprocess
import sys
from pathlib import Path
SECTIONS = {
"docs": ("doc/src",),
"include-docs": ("doc/src/references/include",),
"builtin-docs": ("doc/src/references/builtin",),
"plugin-docs": ("doc/src/references/plugin",),
"release-includes": ("release/include",),
"bindings": ("src",),
"samples": ("extra/samples",),
}
def run_rg(query: str, roots: list[Path], max_count: int) -> tuple[int, str]:
existing = [str(p) for p in roots if p.exists()]
if not existing:
return 0, ""
cmd = [
"rg",
"-n",
"--hidden",
"--no-ignore",
"--max-count",
str(max_count),
query,
*existing,
]
proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
# ripgrep exits 1 when no matches; that is not an error for this tool.
if proc.returncode in (0, 1):
return proc.returncode, proc.stdout.strip()
raise RuntimeError(proc.stderr.strip() or "ripgrep failed")
def resolve_roots(nvgt_root: Path, section: str | None) -> list[tuple[str, list[Path]]]:
if section:
rels = SECTIONS[section]
return [(section, [nvgt_root / rel for rel in rels])]
groups: list[tuple[str, list[Path]]] = []
for key, rels in SECTIONS.items():
groups.append((key, [nvgt_root / rel for rel in rels]))
return groups
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(description="Search NVGT docs/includes/source quickly.")
parser.add_argument("query", help="Symbol or text to search for")
parser.add_argument(
"--root",
default="",
help="Path to NVGT repository root (auto-discovered if omitted)",
)
parser.add_argument(
"--section",
choices=sorted(SECTIONS.keys()),
help="Limit search to one section",
)
parser.add_argument(
"--max-count",
type=int,
default=50,
help="Maximum matches per section (default: 50)",
)
return parser.parse_args()
def discover_nvgt_root(explicit_root: str) -> Path | None:
if explicit_root:
root = Path(explicit_root).expanduser().resolve()
return root if root.exists() else None
default_root = Path.home() / "git" / "nvgt"
default_resolved = default_root.expanduser().resolve()
if default_resolved.exists():
return default_resolved
return None
def main() -> int:
if shutil.which("rg") is None:
print("Error: ripgrep (rg) is required.", file=sys.stderr)
return 2
args = parse_args()
nvgt_root = discover_nvgt_root(args.root)
if nvgt_root is None:
print(
"Error: NVGT root not found at ~/git/nvgt. Pass --root to override.",
file=sys.stderr,
)
return 2
groups = resolve_roots(nvgt_root, args.section)
any_match = False
for title, roots in groups:
code, output = run_rg(args.query, roots, args.max_count)
if code == 0 and output:
any_match = True
print(f"\n== {title} ==")
print(output)
if not any_match:
print("No matches found.")
return 1
return 0
if __name__ == "__main__":
raise SystemExit(main())