diff --git a/README.md b/README.md index 12a36b2..44a8313 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,54 @@ # SDL3CPlusPlus -Minimal SDL3 + Vulkan spinning cube demo. +SDL3 + Vulkan demo app with Lua-driven runtime configuration, audio playback, and a small GUI sample. -## Cheat sheet +## 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. -### Dependencies -- `python scripts/dev_commands.py dependencies` installs the Conan graph in `build`. +## 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. -### Configure & build -- `python scripts/dev_commands.py configure` defaults to Ninja+MSVC on Windows or plain Ninja on Linux/macOS, writing into the matching `build-ninja-msvc`/`build-ninja` folder with the `Release` build type; override the generator or build directory with `--generator` / `--build-dir` if you need something else. -- `python scripts/dev_commands.py build` runs `cmake --build` in the same folder (change `--build-dir` to match a different configure directory). -- `python scripts/dev_commands.py msvc-quick` (Windows only) runs the VC vars + Ninja build alias; pass `--bat-path` to target a different Visual Studio installation. -- `python scripts/dev_commands.py run` launches `sdl3_app` (use `--target` to run another executable and `--args` to forward CLI arguments). -- Prefix any subcommand with `--dry-run` to print the alias-driven shell command without executing it. +## 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` -### Run -- `python scripts/dev_commands.py run [--build-dir ...]` (source `build/conanrun.sh` / `build\conanrun.bat` first if the Conan runtime exports env vars). +## 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. -### Audio assets +## Running +- Default build dir: `build-ninja` on Linux/macOS, `build-ninja-msvc` on Windows. +- `python scripts/dev_commands.py run --build-dir ` 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 ` 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` @@ -28,14 +60,6 @@ python -m piper.download_voices en_US-lessac-medium --download-dir scripts/asset 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 ` and (optionally) `--piper-voice-config ` 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 +## 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. - -## Runtime configuration -1. `sdl3_app --json-file-in ` loads JSON configs (script path, window size, `lua_debug`, etc.). -2. `sdl3_app --create-seed-json config/seed_runtime.json` writes a starter file assuming `scripts/cube_logic.lua` sits beside the binary. -3. `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 `./build/sdl3_app --json-file-in config/gui_runtime.json` or register that config via `sdl3_app --set-default-json`.