libstorm-nvgt/README.md

libstorm-nvgt

Reusable NVGT helpers for Storm projects.

Modules

• multikey.nvgt: Helper functions for handling multiple equivalent keys.
• file_viewer.nvgt: Accessible text/file viewer and optional editor.
• text_reader_compat.nvgt: Optional aliases (text_reader*) for legacy code.
• ui.nvgt: Dialog wrappers with optional main-window restoration.
• speech_history.nvgt: speak_with_history() wrapper plus comma/period history navigation.
• notifications.nvgt: Queued notifications with history and optional sound playback.
• menu_helpers.nvgt: Simple menu runner + filter helpers with sounds/menu defaults.
• audio_paths.nvgt: Shared .ogg / .wav audio path resolution helper.
• learn_sounds.nvgt: Reusable learn-sounds browser with project-level exclusion/description hooks.
• docs_browser.nvgt: Reusable document discovery/opening helpers for menus.
• dict_utils.nvgt: Typed dictionary access helpers.
• save_utils.nvgt: Generic save file I/O and AES helpers.
• name_sanitize.nvgt: Name normalization and safe filename builders.
• crash_logger.nvgt: Timestamped logging and unhandled exception logging helpers.
• volume_controls.nvgt: Reusable global volume key handling and sound handle cleanup.

Usage

#include "libstorm-nvgt/multikey.nvgt"
#include "libstorm-nvgt/file_viewer.nvgt"
#include "libstorm-nvgt/text_reader_compat.nvgt" // Optional legacy aliases
#include "libstorm-nvgt/ui.nvgt"
#include "libstorm-nvgt/speech_history.nvgt"
#include "libstorm-nvgt/notifications.nvgt"
#include "libstorm-nvgt/menu_helpers.nvgt"
#include "libstorm-nvgt/learn_sounds.nvgt"
#include "libstorm-nvgt/docs_browser.nvgt"
#include "libstorm-nvgt/dict_utils.nvgt"
#include "libstorm-nvgt/save_utils.nvgt"
#include "libstorm-nvgt/name_sanitize.nvgt"
#include "libstorm-nvgt/crash_logger.nvgt"
#include "libstorm-nvgt/volume_controls.nvgt"

multikey Example

array<int> jumpKeys = {KEY_UP, KEY_W, KEY_SPACE};
array<int> runKeys = {KEY_LCTRL, KEY_RCTRL};

if (check_key_down(runKeys)) {
    moveInterval = 100;
}

if (check_key_down(jumpKeys) && !isJumping) {
    isJumping = true;
}

ui Example

ui_set_default_window_title("My Game");
string playerName = ui_input_box("New Game", "Enter your name", "");
if (ui_question("Confirm", "Start with this name?") == 1) {
    ui_info_box("New Game", "Ready", "Starting game now.");
}

menu_helpers Examples

string[] options = {"New Game", "Load Game", "Exit"};
int selected = menu_run_simple("Main menu.", options, true, 0, "sounds/menu");
if (selected == 2 || selected == -1) {
    exit();
}

// Prefix filtering helper usage in custom loops.
string filterText = "";
int[] filteredIndices;
string[] filteredOptions;
int selection = 0;

menu_apply_prefix_filter(filterText, options, filteredIndices, filteredOptions);
bool changed = menu_update_prefix_filter(filterText, options, filteredIndices, filteredOptions, selection);

file_viewer Example

file_viewer_file("README.txt", "Readme", true);

speech_history + notifications Example

#include "libstorm-nvgt/speech_history.nvgt"
#include "libstorm-nvgt/notifications.nvgt"

void speak_notification_with_history(const string &in message, bool interrupt) {
    speak_with_history(message, interrupt);
}

void boot() {
    notifications_set_sound_path("sounds/notify");
    notifications_set_speak_callback(speak_notification_with_history);
    speak_with_history("Game loaded.", true);
}

void game_loop_tick() {
    notifications_update();
    notifications_check_keys();
    check_speech_history_keys();
}

void on_event() {
    notifications_enqueue("A resident has returned.");
}

learn_sounds Example (Project Override File)

// In your project root, create excluded_sounds.nvgt:
void configure_project_learn_sounds() {
    learn_sounds_reset_configuration();
    learn_sounds_add_skip_entry("sounds/menu/");
    learn_sounds_add_description("sounds/actions/falling.ogg", "Lowers in pitch as the fall progresses.");
}

// In your game module:
#include "libstorm-nvgt/learn_sounds.nvgt"
#include "excluded_sounds.nvgt"
#include "libstorm-nvgt/speech_history.nvgt"

void learn_sounds_bridge_speak(const string &in message, bool interrupt) {
    speak_with_history(message, interrupt);
}

void configure_and_run_learn_sounds() {
    learn_sounds_set_speak_callback(learn_sounds_bridge_speak);
    learn_sounds_set_menu_sound_dir("sounds/menu");
    learn_sounds_set_root_dir("sounds");
    configure_project_learn_sounds();
    learn_sounds_run_menu();
}

save_utils + name_sanitize Example

string filename = build_filename_from_name("Thora", ".dat", 40, "character");
save_encrypted_file(filename, serialize(saveData), "my_game_save_key");

dict_utils + crash_logger Example

double dayNumber = dict_get_number(saveData, "time_current_day", 1);
if (has_exception()) {
    log_unhandled_exception_to_file("crash.log", "load_game");
}

volume_controls Example

void on_volume_applied(float volumeDb) {
    sound_master_volume = volumeDb;
}

void init_audio() {
    volume_controls_set_apply_callback(on_volume_applied);
    volume_controls_configure(-60.0f, 0.0f, 3.0f, 0.0f);
}

void tick() {
    volume_controls_handle_keys(KEY_PAGEDOWN, KEY_PAGEUP, true);
}