Develop

.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

.vitepress/config.ts

@@ -193,11 +193,12 @@ export default defineConfig({
             },
             {
               text: 'Tilemap Editor',
-              collapsed: true,
+              collapsed: false,
               items: [
                 { text: 'Overview', link: '/tools/tilemap-editor/overview' },
                 { text: 'Quick start', link: '/tools/tilemap-editor/quick-start' },
                 { text: 'Installation', link: '/tools/tilemap-editor/installation' },
+                { text: 'License & Activation', link: '/tools/tilemap-editor/license-and-activation' },
                 { text: 'Usage guide', link: '/tools/tilemap-editor/usage-guide' },
                 { text: 'Advanced guide', link: '/tools/tilemap-editor/advanced-guide' },
                 { text: 'Technical reference', link: '/tools/tilemap-editor/technical-reference' },

api/generated/audio/DefaultAudioScheduler.md

@@ -30,6 +30,19 @@ For platforms with a dedicated audio task (e.g., FreeRTOS on ESP32),
 
 ### `void init(AudioBackend* backend, int sampleRate, const pixelroot32::platforms::PlatformCapabilities& caps, int blockSize = 256)`
 
+**Description:**
+
+Initializes the underlying ApuCore.
+
+**Parameters:**
+
+- `backend`: Unused: generation is driven by the caller of
+       generateSamples(), so no backend handle is needed.
+- `sampleRate`: Output sample rate forwarded to ApuCore.
+- `caps`: Unused: no thread/core pinning happens here.
+- `blockSize`: Unused: the caller chooses the buffer length on
+       every generateSamples() call.
+
 ### `void submitCommand(const AudioCommand& cmd)`
 
 **Description:**
@@ -44,13 +57,13 @@ Enqueues a command to the ApuCore. @param cmd The command to submit.
 
 **Description:**
 
-Marks scheduler as running. Starts audio generation context.
+Resumes sample generation after stop(). Generation starts enabled.
 
 ### `void stop()`
 
 **Description:**
 
-Marks scheduler as stopped. Silences all voices.
+Halts generation: generateSamples() outputs silence until start().
 
 ### `bool isIndependent() const`
 

api/generated/index.md

@@ -4,22 +4,12 @@ Auto-generated API documentation from C++ header files.
 
 ## Audio
 
-- [ApuCore](./audio/ApuCore.md) — Shared NES-style APU core used by every AudioScheduler.
 - [AudioBackend](./audio/AudioBackend.md) — Abstract interface for platform-specific audio drivers.
-- [AudioChannel](./audio/AudioChannel.md) — Represents the internal state of a single audio channel.
-- [AudioCommand](./audio/AudioCommand.md) — Internal command to communicate between game and audio threads.
-- [AudioCommandQueue](./audio/AudioCommandQueue.md) — Single-Producer Single-Consumer (SPSC) lock-free ring buffer for AudioCommands.
 - [AudioConfig](./audio/AudioConfig.md) — Configuration for the Audio subsystem.
 - [AudioEngine](./audio/AudioEngine.md) — Facade class for the NES-style audio subsystem.
-- [AudioEvent](./audio/AudioEvent.md) — A fire-and-forget sound event triggered by the game.
 - [AudioScheduler](./audio/AudioScheduler.md) — Abstract interface for the audio execution context.
 - [DefaultAudioScheduler](./audio/DefaultAudioScheduler.md) — Backend-driven scheduler used on platforms without a dedicated audio task.
-- [EnvelopeState](./audio/EnvelopeState.md) — Holds ADSR envelope state for a single voice.
-- [InstrumentPreset](./audio/InstrumentPreset.md) — Defines instrument characteristics for playback.
-- [LfoState](./audio/LfoState.md) — Holds LFO (Low-Frequency Oscillator) state for pitch or volume modulation.
-- [MusicNote](./audio/MusicNote.md) — Represents a single note in a melody.
 - [MusicPlayer](./audio/MusicPlayer.md) — Simple sequencer to play MusicTracks using the AudioEngine.
-- [SfxBreakpoint](./audio/SfxBreakpoint.md) — Timed automation point for SFX duty steps or pitch envelope.
 
 ## Core
 

examples/demos.md

@@ -26,7 +26,7 @@ The engine revision for each example is defined in `**lib_deps**` inside that ex
 - [flappy_bird](./flappy_bird) — [source code](https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Game-Engine/tree/main/examples/flappy_bird)
 - [hello_world](./hello_world) — [source code](https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Game-Engine/tree/main/examples/hello_world)
 - [metroidvania](./metroidvania) — [source code](https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Game-Engine/tree/main/examples/metroidvania)
-- [music_demo](./music_demo) — [source code](https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Game-Engine/tree/main/examples/music_demo)
+- [music-demo](./music-demo) — [source code](https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Game-Engine/tree/main/examples/music-demo)
 - [physics](./physics) — [source code](https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Game-Engine/tree/main/examples/physics)
 - [snake](./snake) — [source code](https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Game-Engine/tree/main/examples/snake)
 - [space_invaders](./space_invaders) — [source code](https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Game-Engine/tree/main/examples/space_invaders)

examples/music-demo.md

@@ -28,43 +28,43 @@ See **`platformio.ini`** for **`native`** and **`esp32dev`**.
 
 ## Melody assets (`src/assets/`)
 
-Tracks are split per theme; shared beat constants and demo-only **`InstrumentPreset`** overrides live in **`common_melodies.h`**:
+Melodies are **generated by the PixelRoot32 Tool Suite** from their **`.pr32music`** sources. Each asset is self-contained: it carries its own **`LIB_*`** `InstrumentPreset` definitions, beat constants (`S`/`E`/`Q`/`H`/`W`), and a **four-part** `MusicTrack` arrangement:
 
-| File | Role |
-|------|------|
-| [`common_melodies.h`](src/assets/common_melodies.h) | Beat fractions (`S`/`E`/`Q`/…), `kDemoArcadeLeadWave` / `kDemoAdventureLeadWave`, **`DEMO_SNES_LEAD_TIGHT`** / **`DEMO_SNES_BASS_STAC`** (tighter ADSR for SNES-style arranging), **`ARP_STEP`** |
-| [`classic_arcade_melody.h`](src/assets/classic_arcade_melody.h) | **Melody 1** — Classic Arcade (`sClassicArcadeTrack`) |
-| [`adventure_melody.h`](src/assets/adventure_melody.h) | **Melody 2** — Adventure (`sAdventureTrack`) |
-| [`action_melody.h`](src/assets/action_melody.h) | **Melody 3** — Action (`sActionTrack`) |
-| [`arpeggio_melody.h`](src/assets/arpeggio_melody.h) | **Melody 4** — Em arpeggio demo (`sArpDemoTrack`) |
+| File | UI button | Role |
+|------|-----------|------|
+| [`blaster_ridge.h`](src/assets/blaster_ridge.h) | **Blaster Ridge** | `musicdemo::blaster_ridge::kTrack` — fast action theme |
+| [`coinleaf_grove.h`](src/assets/coinleaf_grove.h) | **Coinleaf Grove** | `musicdemo::coinleaf_grove::kTrack` — light adventure theme |
+| [`lightworld_march.h`](src/assets/lightworld_march.h) | **Lightworld March** | `musicdemo::lightworld_march::kTrack` — heroic march |
+| [`moonwell_hymn.h`](src/assets/moonwell_hymn.h) | **Moonwell Hymn** | `musicdemo::moonwell_hymn::kTrack` — dreamy hymn |
 
-Each full arrangement uses **`MusicTrack`** layering: **main** + optional **`secondVoice`**, **`thirdVoice`**, and **`percussion`**, flattened by `MusicPlayer` into the global voice pool (**`ApuCore::MAX_VOICES`** = 8). The headers comment on keeping harmony/percussion notes relatively short so **SFX** can share the pool without constant stealing.
+Each `.h` has a companion **`.h.pr32music`** sidecar (name, BPM, patterns) used to generate it.
+
+Each arrangement layers **main** lead + **`secondVoice`** (bass) + **`thirdVoice`** (harmony) + **`percussion`**, mapped by `MusicPlayer` to ApuCore music slots **0–3** (SFX keeps slots **4–7**). The per-track `LIB_*` presets are tuned so loops stay full after beat-accurate gates.
 
 ## Melodies (UI labels vs. engine)
 
 | UI button | BPM (see `MusicDemoScene::playMelody`) | Loop length (beats) | Layers (summary) |
 |-----------|----------------------------------------|---------------------|------------------|
-| **Melody 1** | 140 | 32 | **SAW** lead (`kDemoArcadeLeadWave`), bass (`DEMO_SNES_BASS_STAC`), pulse harmony stabs, noise drums (two groove blocks + fill) |
-| **Melody 2** | 125 | 64 | **SINE** lead (`kDemoAdventureLeadWave`), bass, harmony, drums (extended **A \| B \| A′ \| C**-style material) |
-| **Melody 3** | 160 | 32 | **PULSE** lead via **`DEMO_SNES_LEAD_TIGHT`** (16th-style arpeggio macros), matching bass, sparse harmony hits, dense 16th-hat drums + break |
-| **Melody 4 + ARP voice** | 145 | 32 | **SAW** lead (`kDemoArcadeLeadWave`), **`secondVoice`**: fast Em arpeggio (`INSTR_TRIANGLE_LEAD`, **`WaveType::SINE`** on the sub-track), **`thirdVoice`**: bass, **same drum grid as Melody 1** for a stable loop |
+| **Blaster Ridge** | 168 | 32 | **SAW** lead (`LIB_SAW_EDGE`/`BRIGHT`/`RAZOR`), **SAW** growl bass (`LIB_SAW_GROWL_BASS`), **PULSE** harmony hits (`LIB_PULSE_HERO_BRASS`), noise drums with clap / crash / tom / zap fills |
+| **Coinleaf Grove** | 152 | 32 | **PULSE** lead (`LIB_PULSE_BRIGHT`/`SPARK`/`THIN`), **TRIANGLE** thump bass (`LIB_TRIANGLE_THUMP`), pulse harmony, noise drums with clap and open-hat accents |
+| **Lightworld March** | 128 | 32 | **PULSE** lead (`LIB_PULSE_BRIGHT`), **TRIANGLE** thump bass, pulse hero-brass / warm-pad harmony, noise drums with crash, tom fills and open hats |
+| **Moonwell Hymn** | 104 | 32 | **SINE** flute lead (`LIB_SINE_FLUTE`, bell/glass accents), **TRIANGLE** sub bass (`LIB_TRIANGLE_SUB_BASS`), sine dream/air-pad harmony, noise drums with ride, crash, soft snare and open hats |
 
 ## Features
 
-- **10 engine instrument presets** (one-shot tests) — Lead Square, Harmony Square, Bass Triangle, Kick, Snare, Hi-hat, Triangle Lead, Triangle Pad, Pulse Pad, Pulse Bass
-- **4 multi-part demo tracks** — layered loops with distinct BPM and form (see table above)
-- **Melody 4** — full **four-part** demo: lead + arpeggiated **`secondVoice`** + bass + percussion (not just lead + arp)
+- **10 engine instrument presets** (one-shot tests) — Pulse Lead, Pulse Harmony, Triangle Bass, Pulse Bass, Triangle Lead, Triangle Pad, Pulse Pad, Kick, Snare, Hi-hat
+- **4 four-part demo tracks** — each layers lead + bass (`secondVoice`) + harmony (`thirdVoice`) + percussion, generated from tool-suite `.pr32music` assets with distinct BPM and texture (see table above)
 - **Audio Lab menu** — **pulse frequency sweep** (Phase A), **SINE / SAW chord** one-shots (Phase B), and **master bitcrush** cycling via `AudioEngine::setMasterBitcrush`
 - **UI-based sound testing** — play individual instrument sounds on demand
-- **Modular audio architecture** — demonstrates `InstrumentPreset`, per-demo preset tweaks, melody sequencing, `AudioEvent` sweep fields, and audio scheduling
+- **Modular audio architecture** — demonstrates `InstrumentPreset`, per-asset `LIB_*` preset tuning, melody sequencing, `AudioEvent` sweep fields, and audio scheduling
 
 ## Documentation links
 
-- [Audio API](/api/audio)
-- [Music player guide](/guide/music-player-guide.md)
-- [Input API](/api/input)
-- [UI API](/api/ui)
-- [Core — Scene](/api/core)
+- [Audio API](../../docs/api/audio.md)
+- [Music player guide](../../docs/guide/music-player-guide.md)
+- [Input API](../../docs/api/input.md)
+- [UI API](../../docs/api/ui.md)
+- [Core — Scene](../../docs/api/core.md)
 
 ## Build
 

examples/music_demo.md

@@ -28,35 +28,35 @@ See **`platformio.ini`** for **`native`** and **`esp32dev`**.
 
 ## Melody assets (`src/assets/`)
 
-Tracks are split per theme; shared beat constants and demo-only **`InstrumentPreset`** overrides live in **`common_melodies.h`**:
+Melodies are **generated by the PixelRoot32 Tool Suite** from their **`.pr32music`** sources. Each asset is self-contained: it carries its own **`LIB_*`** `InstrumentPreset` definitions, beat constants (`S`/`E`/`Q`/`H`/`W`), and a **four-part** `MusicTrack` arrangement:
 
-| File | Role |
-|------|------|
-| [`common_melodies.h`](src/assets/common_melodies.h) | Beat fractions (`S`/`E`/`Q`/…), wave aliases, demo **`InstrumentPreset`** overrides (`DEMO_MELODY_LEAD`, `DEMO_HARMONY`, `DEMO_DRUM_*`, `DEMO_SNES_*`, `DEMO_ARP_VOICE`) retuned for beat-accurate gates under ApuCore 4+4 |
-| [`classic_arcade_melody.h`](src/assets/classic_arcade_melody.h) | **Melody 1** — Classic Arcade (`sClassicArcadeTrack`) |
-| [`adventure_melody.h`](src/assets/adventure_melody.h) | **Melody 2** — Adventure (`sAdventureTrack`) |
-| [`action_melody.h`](src/assets/action_melody.h) | **Melody 3** — Action (`sActionTrack`) |
-| [`arpeggio_melody.h`](src/assets/arpeggio_melody.h) | **Melody 4** — Em arpeggio demo (`sArpDemoTrack`) |
+| File | UI button | Role |
+|------|-----------|------|
+| [`blaster_ridge.h`](src/assets/blaster_ridge.h) | **Blaster Ridge** | `musicdemo::blaster_ridge::kTrack` — fast action theme |
+| [`coinleaf_grove.h`](src/assets/coinleaf_grove.h) | **Coinleaf Grove** | `musicdemo::coinleaf_grove::kTrack` — light adventure theme |
+| [`lightworld_march.h`](src/assets/lightworld_march.h) | **Lightworld March** | `musicdemo::lightworld_march::kTrack` — heroic march |
+| [`moonwell_hymn.h`](src/assets/moonwell_hymn.h) | **Moonwell Hymn** | `musicdemo::moonwell_hymn::kTrack` — dreamy hymn |
 
-Each full arrangement uses **`MusicTrack`** layering: **main** + optional **`secondVoice`**, **`thirdVoice`**, and **`percussion`**, mapped by `MusicPlayer` to ApuCore music slots **0–3** (SFX keeps slots **4–7**). Demo presets in **`common_melodies.h`** add level and tail so loops stay full after beat-accurate gates.
+Each `.h` has a companion **`.h.pr32music`** sidecar (name, BPM, patterns) used to generate it.
+
+Each arrangement layers **main** lead + **`secondVoice`** (bass) + **`thirdVoice`** (harmony) + **`percussion`**, mapped by `MusicPlayer` to ApuCore music slots **0–3** (SFX keeps slots **4–7**). The per-track `LIB_*` presets are tuned so loops stay full after beat-accurate gates.
 
 ## Melodies (UI labels vs. engine)
 
 | UI button | BPM (see `MusicDemoScene::playMelody`) | Loop length (beats) | Layers (summary) |
 |-----------|----------------------------------------|---------------------|------------------|
-| **Melody 1** | 140 | 32 | **SAW** lead (`kDemoArcadeLeadWave`), bass (`DEMO_SNES_BASS_STAC`), pulse harmony stabs, noise drums (two groove blocks + fill) |
-| **Melody 2** | 125 | 64 | **SINE** lead (`kDemoAdventureLeadWave`), bass, harmony, drums (extended **A \| B \| A′ \| C**-style material) |
-| **Melody 3** | 160 | 32 | **PULSE** lead via **`DEMO_SNES_LEAD_TIGHT`** (16th-style arpeggio macros), matching bass, sparse harmony hits, dense 16th-hat drums + break |
-| **Melody 4 + ARP voice** | 145 | 32 | **SAW** lead (`kDemoArcadeLeadWave`), **`secondVoice`**: fast Em arpeggio (`INSTR_TRIANGLE_LEAD`, **`WaveType::SINE`** on the sub-track), **`thirdVoice`**: bass, **same drum grid as Melody 1** for a stable loop |
+| **Blaster Ridge** | 168 | 32 | **SAW** lead (`LIB_SAW_EDGE`/`BRIGHT`/`RAZOR`), **SAW** growl bass (`LIB_SAW_GROWL_BASS`), **PULSE** harmony hits (`LIB_PULSE_HERO_BRASS`), noise drums with clap / crash / tom / zap fills |
+| **Coinleaf Grove** | 152 | 32 | **PULSE** lead (`LIB_PULSE_BRIGHT`/`SPARK`/`THIN`), **TRIANGLE** thump bass (`LIB_TRIANGLE_THUMP`), pulse harmony, noise drums with clap and open-hat accents |
+| **Lightworld March** | 128 | 32 | **PULSE** lead (`LIB_PULSE_BRIGHT`), **TRIANGLE** thump bass, pulse hero-brass / warm-pad harmony, noise drums with crash, tom fills and open hats |
+| **Moonwell Hymn** | 104 | 32 | **SINE** flute lead (`LIB_SINE_FLUTE`, bell/glass accents), **TRIANGLE** sub bass (`LIB_TRIANGLE_SUB_BASS`), sine dream/air-pad harmony, noise drums with ride, crash, soft snare and open hats |
 
 ## Features
 
-- **10 engine instrument presets** (one-shot tests) — Lead Square, Harmony Square, Bass Triangle, Kick, Snare, Hi-hat, Triangle Lead, Triangle Pad, Pulse Pad, Pulse Bass
-- **4 multi-part demo tracks** — layered loops with distinct BPM and form (see table above)
-- **Melody 4** — full **four-part** demo: lead + arpeggiated **`secondVoice`** + bass + percussion (not just lead + arp)
+- **10 engine instrument presets** (one-shot tests) — Pulse Lead, Pulse Harmony, Triangle Bass, Pulse Bass, Triangle Lead, Triangle Pad, Pulse Pad, Kick, Snare, Hi-hat
+- **4 four-part demo tracks** — each layers lead + bass (`secondVoice`) + harmony (`thirdVoice`) + percussion, generated from tool-suite `.pr32music` assets with distinct BPM and texture (see table above)
 - **Audio Lab menu** — **pulse frequency sweep** (Phase A), **SINE / SAW chord** one-shots (Phase B), and **master bitcrush** cycling via `AudioEngine::setMasterBitcrush`
 - **UI-based sound testing** — play individual instrument sounds on demand
-- **Modular audio architecture** — demonstrates `InstrumentPreset`, per-demo preset tweaks, melody sequencing, `AudioEvent` sweep fields, and audio scheduling
+- **Modular audio architecture** — demonstrates `InstrumentPreset`, per-asset `LIB_*` preset tuning, melody sequencing, `AudioEvent` sweep fields, and audio scheduling
 
 ## Documentation links
 

tools/index.md

@@ -6,7 +6,12 @@ PixelRoot32 ships optional **workflow tools** alongside the open-source engine.
 
 ## Sprite Compiler (free)
 
-Converts **PNG** images into **C headers** with sprite data (layered 1bpp, 2bpp, 4bpp, grid selection, GUI + CLI).
+Converts **PNG** images into **C headers** with sprite data (layered 1bpp, 2bpp, 4bpp, grid selection).
+
+**Two ways to use it:**
+
+- **Tool Suite (recommended)**: Integrated as a native GUI module inside the Tool Suite. The actual compilation uses an external `pr32-sprite-compiler` CLI (bundled with the Tool Suite or available on `PATH`).
+- **Standalone CLI**: Open-source Python repo (`python main.py …`) — ideal for CI scripts and build-automation without the full Tool Suite.
 
 - [Overview](/tools/sprite-compiler/overview)
 - [Installation](/tools/sprite-compiler/installation)
@@ -25,7 +30,7 @@ The **Tool Suite** adds advanced editor modules. Licensing and downloads are han
 
 ### Tilemap Editor (module 1)
 
-Coming soon - visual editor for multi-layer tilemaps, tilesets, animations, attributes, and **C++ export** aligned with the engine.
+Available - visual editor for multi-layer tilemaps, tilesets, animations, attributes, and **C++ export** aligned with the engine. Ships as a native desktop app (C++17 / SDL2 / ImGui) inside the Tool Suite.
 
 - [Overview](/tools/tilemap-editor/overview)
 - [Quick start](/tools/tilemap-editor/quick-start)
@@ -36,7 +41,11 @@ Coming soon - visual editor for multi-layer tilemaps, tilesets, animations, attr
 
 ### Music Editor (module 2)
 
-Upcoming - tracker-style music authoring for PixelRoot32.
+Upcoming - pattern-based tracker with multi-channel support for PixelRoot32 APU (planned).
+
+### SFX Editor (module 3)
+
+Upcoming - sound effect synthesis editor for the PR32 APU SFX pipeline (planned).
 
 ---
 
@@ -45,7 +54,8 @@ Upcoming - tracker-style music authoring for PixelRoot32.
 | Tool | Type | Status |
 |------|------|--------|
 | Sprite Compiler | Free / standalone | Available |
-| Tilemap Editor | Premium (suite) | Coming soon |
+| Tilemap Editor | Premium (suite) | Available |
 | Music Editor | Premium (suite) | Upcoming |
+| SFX Editor | Premium (suite) | Upcoming |
 
-**Engine docs:** [Graphics Techniques](../guide/graphics-techniques.md) · [Rendering](../guide/rendering.md) · [Tile animation (architecture)](../architecture/tile-animation.md)
+**Engine docs:** [Graphics Techniques](../guide/graphics-techniques) · [Rendering](../guide/rendering) · [Tile animation (architecture)](../architecture/tile-animation)