# 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.