draugnorak/skills/nvgt-engine-dev/references/repo-map.md

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.