From 3e9e69a6cd9212b5cfd956c0a36b9dc07ab88cf7 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Wed, 28 Jan 2026 08:51:49 +0100
Subject: feat(assets): Implement basic asset packing system

Introduces a new asset management system to embed binary assets directly into the demo executable.

- Creates the  directory for asset definition and an  descriptor file.

- Implements  to generate  (with  enum and  declaration) and  (with placeholder data).

- Integrates  into CMake build, making  depend on the generated asset files.

- Adds minimal integration in  and documentation in .

This addresses Task 9 (compact in-line and off-line asset system).
---
 HOWTO.md | 45 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 3 deletions(-)

(limited to 'HOWTO.md')

diff --git a/HOWTO.md b/HOWTO.md
index 5716524..1f2560c 100644
--- a/HOWTO.md
+++ b/HOWTO.md
@@ -119,8 +119,47 @@ The executable will be located at `build/specview`.
 ./build/specview path/to/input.spec
 ```
 
-## References and links
+### Asset Management System
 
-drum-kit: https://drive.google.com/file/d/13tc7XjkMg-tigvje5qpp6XazK-VcOjoc/view
-(got from https://www.reddit.com/r/Drumkits/)
+This system allows embedding binary assets directly into the demo executable.
 
+#### Defining Assets
+
+Assets are defined in `assets/final/assets.txt`. Each line specifies:
+*   `ASSET_NAME`: The identifier for the asset in C++ (e.g., `SAMPLE_142`).
+*   `filename.ext`: The path to the asset file (relative to `assets/final/`).
+*   `NONE`: Compression type (currently only `NONE` is supported).
+*   `"Description"`: An optional description.
+
+Example `assets/final/assets.txt` entry:
+```
+SAMPLE_142, sample_142.spec, NONE, "A drum kick sample"
+```
+
+#### Building with Assets
+
+The `asset_packer` tool processes `assets/final/assets.txt` and generates two files:
+*   `build/src/assets.h`: Contains the `AssetId` enum and `GetAsset` function declaration.
+*   `build/src/assets_data.cc`: Contains the binary data for each asset.
+
+These files are automatically generated as part of the normal build process when `demo64k` is built. To trigger generation, simply run:
+
+```bash
+cmake -S . -B build
+cmake --build build
+```
+
+#### Accessing Assets in Code
+
+Include `assets.h` and use the `GetAsset` function:
+
+```cpp
+#include "assets.h"
+
+// ...
+size_t asset_size;
+const uint8_t* my_asset = GetAsset(AssetId::ASSET_SAMPLE_142, &asset_size);
+// ...
+// For lazy decompression (scaffolding only):
+// DropAsset(AssetId::ASSET_SAMPLE_142, my_asset);
+```
-- 
cgit v1.2.3