# How To

Quick reference for common tasks.

---

## Building

### Workspace Selection
```bash
# Main demo (default)
cmake -S . -B build -DDEMO_WORKSPACE=main
cmake --build build -j4
./build/demo64k

# Test demo
cmake -S . -B build_test -DDEMO_WORKSPACE=test
cmake --build build_test -j4
./build_test/test_demo
```

### Debug Build
```bash
cmake -S . -B build
cmake --build build -j4
./build/demo64k
```
Options: `--fullscreen`, `--resolution WxH`, `--seek TIME`, `--hot-reload`

### Production Builds
```bash
# Size-optimized (development)
cmake -B build -DDEMO_SIZE_OPT=ON && cmake --build build -j4

# 64k target (full checks, no debug)
cmake -B build -DDEMO_STRIP_ALL=ON && cmake --build build -j4

# Final release (no checks, absolute minimum)
./scripts/build_final.sh
```

### Developer Build
```bash
cmake -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON
cmake --build build -j4
```

### Headless Testing
```bash
cmake -B build_headless -DDEMO_HEADLESS=ON && cmake --build build_headless -j4
./build_headless/demo64k --headless --duration 30
```
See `doc/HEADLESS_MODE.md`.

### Size Measurement
```bash
./scripts/measure_size.sh
```
Measures demo vs external library size. See `doc/SIZE_MEASUREMENT.md`.

---

## Testing

```bash
cmake -B build -DDEMO_BUILD_TESTS=ON
cmake --build build -j4
cd build && ctest
```

---

## Timeline

Edit `workspaces/main/timeline.seq`:
```text
SEQUENCE 0.0 0
  EFFECT HeptagonEffect 0.0 60.0 0
```
Rebuild to apply. See `doc/SEQUENCE.md`.

---

## Audio

```cpp
#include "audio/audio_engine.h"

audio_init();
static AudioEngine g_audio_engine;
g_audio_engine.init();
g_audio_engine.update(music_time);
g_audio_engine.shutdown();
audio_shutdown();
```
See `doc/TRACKER.md` for music system.

---

## Assets

Edit `workspaces/main/assets.txt`, then rebuild:
```bash
cmake --build build -j4
```
See `doc/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`.

---

## Additional Documentation

- **Build System:** `doc/BUILD.md` - Multi-platform, size optimization
- **Tools:** `doc/TOOLS_REFERENCE.md` - spectool, coverage, Windows cross-compile
- **Shaders:** `doc/SEQUENCE.md` - Timeline format, shader parameters
- **3D:** `doc/3D.md` - Hybrid rendering, scene format
- **Hot Reload:** `doc/HOT_RELOAD.md` - Debug file watching