SDL3CPlusPlus

SDL3 + Vulkan demo app with Lua-driven runtime configuration, audio playback, and a small GUI sample.

Overview

• Renders a spinning cube with Vulkan via SDL3.
• Lua scripts control behavior under scripts/.
• JSON runtime configs live in config/.
• Optional helpers for audio asset generation and workflow diagnostics.

Prerequisites

• Python 3 for helper scripts.
• Conan for dependency resolution.
• CMake and a C++ compiler.
• Ninja (default generator) or Visual Studio 2022 on Windows.
• Vulkan runtime/driver to run the demo.

Quick start

1. python scripts/dev_commands.py dependencies
2. python scripts/dev_commands.py configure
3. python scripts/dev_commands.py build
4. If you used Conan, load the runtime env vars:
   • Linux/macOS: source build/conanrun.sh
   • Windows (cmd.exe): build\conanrun.bat
5. python scripts/dev_commands.py run

Build helper commands

• python scripts/dev_commands.py configure uses Ninja by default (Ninja+MSVC on Windows) and writes to build-ninja/build-ninja-msvc; override with --generator and --build-dir.
• python scripts/dev_commands.py build runs cmake --build for that folder (use --build-dir and --target as needed).
• python scripts/dev_commands.py msvc-quick runs vcvarsall.bat plus a build command (Windows only).
• Prefix any subcommand with --dry-run to print the shell command without executing it.

Running

• Default build dir: build-ninja on Linux/macOS, build-ninja-msvc on Windows.
• python scripts/dev_commands.py run --build-dir <path> to run from a custom build directory.
• python scripts/dev_commands.py run --target spinning_cube to launch another executable.
• python scripts/dev_commands.py run -- --json-file-in config/gui_runtime.json to pass app flags (use -- before app args).

JSON config examples

• python scripts/dev_commands.py run -- --json-file-in config/seed_runtime.json
• python scripts/dev_commands.py run -- --json-file-in config/soundboard_runtime.json
• python scripts/dev_commands.py run -- --json-file-in config/gui_runtime.json

Runtime configuration

• sdl3_app --json-file-in <path> loads JSON configs (script path, window size, lua_debug, etc.).
• sdl3_app --create-seed-json config/seed_runtime.json writes a starter file assuming scripts/cube_logic.lua sits beside the binary.
• sdl3_app --set-default-json [path] stores or overrides the runtime JSON; Windows writes %APPDATA%/sdl3cpp, other OSes use $XDG_CONFIG_HOME/sdl3cpp/default_runtime.json (fallback ~/.config/sdl3cpp).

GUI demo

scripts/gui_demo.lua paints the Lua GUI framework on top of the Vulkan scene. Launch it as python scripts/dev_commands.py run -- --json-file-in config/gui_runtime.json or register that config via sdl3_app --set-default-json.

Audio assets

Install the dependencies that power scripts/generate_audio_assets.py:

• python -m pip install --user numpy soundfile pedalboard piper-tts

Before translating phrases, download a Piper voice (the script defaults to en_US-lessac-medium):

python -m piper.download_voices en_US-lessac-medium --download-dir scripts/assets/audio/tts/voices

Running the generator recreates procedural effects under scripts/assets/audio/sfx/ and voice clips under scripts/assets/audio/tts/. Use --force to rebuild every file and --skip-sfx / --skip-tts if you only need one subset; add --verbose to see the internal logging as the files are created. Override the voice files with --piper-voice-model <path> and (optionally) --piper-voice-config <path> if you downloaded a different voice or location. Pass --download-voice to have the script invoke piper.download_voices automatically before rendering (requires piper-tts and network access).

GitHub Actions workflow diagnostics

• python -m pip install pyyaml installs the YAML dependency for the workflow analyzer.
• python scripts/workflow_doctor.py [--workflows-dir .github/workflows] inspects workflows for missing permissions, floating action references, and other reproducibility/security hints.