---
description: Wolfenstein VB project context -- hardware constraints, build system, VRAM layout, asset pipeline
alwaysApply: true
---

# Wolfenstein VB -- Virtual Boy Homebrew Doom Clone

C project targeting the NEC V810 CPU via `v810-gcc` and the `libgccvb` library.

## Build System

- **IDE**: VBDE (`C:\vbde\VBDE.exe`). Build is triggered through the GUI.
- **Command-line build**: Run VBDE's build script so the build uses msys bash and Unix `find` (otherwise ROM can be 0 kB). From project root: `C:\vbde\system\batch\build.bat c:\vbde\my_projects\WolfensteinVB\src\WolfensteinVB` (or the equivalent path to `src\WolfensteinVB`). Do not add a project-root Makefile—that would switch to "custom makefile" and still require msys.
- **Compiler**: `C:\vbde\system\msys32\v810\v810-win32\bin\v810-gcc.exe`
- **Source root**: `src/WolfensteinVB/` -- the IDE auto-discovers every `.c` file in the tree.
- **Include paths**: `C:\vbde\libs\libgccvb`, plus `functions/`, `assets/languages/`, `.` relative to source root.
- **Output**: `src/WolfensteinVB/build/output.vb`
- **After making any code/asset change**: Bump `GAME_VERSION` in `src/WolfensteinVB/components/titleScreen.c`, then run the compile command: `C:\vbde\system\batch\build.bat c:\vbde\my_projects\WolfensteinVB\src\WolfensteinVB` so the user can RELOAD ROM in the emulator.

## Display Constraints

- 384x224 pixels, monochrome red, 4 brightness levels (0=black/transparent, 1=dark, 2=medium, 3=bright).
- Tile-based: all graphics are 8x8 pixel tiles in VB 2bpp format (16 bytes per tile, stored as 4 little-endian u32 words). Each row is 2 bytes: lo bit-plane then hi bit-plane, pixel 0 at MSB (bit 7).
- BGMap entries are u16: bits 0-10 = char index, bit 12 = V-flip, bit 13 = H-flip, bits 14-15 = palette.
- 14 BGMaps (0-13). Worlds 31 down to 17 (WRLD_END). Affine worlds need dedicated BGMap + param table.

## VRAM Layout (2048 character slots, each 16 bytes)

| Region | Chars | Count | Defined in |
|---|---|---|---|
| HUD | 0-107 | 108 | `doomgfx.c` (hardcoded) |
| Face (shared) | 108-119 | 12 | `face_sprites.h` FACE_CHAR_START |
| Weapon red+blk (shared) | 120-461 | 342 | shotgun/rocket `_sprites.h` |
| *Free* | 462-543 | 82 | |
| Weapons fist/pistol | 544-763 | 220 | `doomgfx.h` WEAPON_CHAR_START |
| Particles | 764-982 | 219 | `particle_sprites.h` |
| Enemies (5x64) | 983-1302 | 320 | `doomgfx.h` ZOMBIE_CHAR_START |
| Pickups (2x12) | 1303-1326 | 24 | `pickup.h` PICKUP_CHAR_START |
| Wall textures | 1327-1966 | 640 | `wall_textures.h` WALL_TEX_CHAR_START |
| Transitions | 1967-2036 | 70 | `wall_textures.h` TRANS_TEX_CHAR_START |
| **Free** | 2037-2047 | **11** | |

Weapon tiles are shared: only one weapon is active at a time. Fist (213) and pistol (119) share chars 544+. Shotgun (342) / Rocket launcher (197) use the red+black region at chars 120+. Verify total stays under 2048.

## World Allocation (31 down to 17)

| World | Purpose | BGMap |
|---|---|---|
| 31 | Stage | 1 |
| 30-26 | Enemies 0-4 | 3-7 |
| 25-24 | Pickups 0-1 | 8-9 |
| 23 | Particles/Projectiles | 0 |
| 22 | Weapon black | LAYER_WEAPON_BLACK |
| 21 | Weapon | LAYER_WEAPON |
| 20-18 | UI layers | LAYER_UI_BLACK, LAYER_UI, LAYER_UI+1 |
| 17 | WRLD_END | -- |

## Asset Pipeline

Python scripts at project root convert PNGs to C arrays with VB 2bpp tile data:
- `graphics/prepare_doom_faces.py` -- face sprites with dithering and edge detection
- `graphics/prepare_wall_textures.py` -- algorithmic geometric wall patterns (8-col)
- `graphics/prepare_particles.py` -- bullet puff + shotgun group sprites
- `graphics/prepare_shotgun_sprites.py` -- first-person shotgun weapon frames
- `graphics/prepare_shotgun_pickup.py` -- shotgun pickup item sprite
- `graphics/prepare_rocket_sprites.py` -- first-person rocket launcher weapon frames
- `graphics/prepare_rocket_projectile.py` -- directional rocket projectile sprites (5 views)
- `graphics/prepare_rocket_pickup.py` -- rocket launcher pickup sprite
- `audio/prepare_doom_sfx.py` -- convert Doom WAVs to 4-bit packed VB PCM audio
- `graphics/make_into_4_colors_2/grit_all_frames.py` -- enemy sprite conversion (Imp, Demon)

All generated files go into `src/WolfensteinVB/assets/images/`. Tile arrays use `const unsigned int ... __attribute__((aligned(4)))`. Map arrays use `const unsigned short ... __attribute__((aligned(4)))`.

## Version Bump

- **Every time you make any code or asset change** in the project, bump the title screen version so the user can see which build is loaded. In `src/WolfensteinVB/components/titleScreen.c`, increment `GAME_VERSION` (e.g. `"v0.3"` → `"v0.4"`). Bump once per request/session that includes edits, not per individual file.

## Coding Conventions

- Standard includes: `<libgccvb.h>`, `<mem.h>`. Use `copymem()` for memory copies.
- No stdlib (no malloc, printf, etc.). All tile/map data must be `const` and aligned.
- Hardware registers accessed via `WA[]`, `WAM[]`, `VIP_REGS[]`, `BGMap()` macros from libgccvb.
- Fixed-point math (8.8 or 23.9) for positions and angles. Angles are 0-1023 (10-bit, CW, 0=north).