# Tools & Utilities Directory (`tools/`)

This directory contains internal utilities, asset generators, preview helpers, and test scripts used during development.

> **Note:** The shipped game is a standalone native x86 binary with zero Python or external runtime dependencies. All Python and PowerShell scripts here are strictly offline development tools.

---

## Directory Structure

```
tools/
├── previews/     # Interactive preview launchers for animations and 3D engine
├── generators/   # Offline asset generators, math tables, and code builders
└── tests/        # Test scripts, render simulators, and release checks
```

---

## 1. Previews (`tools/previews/`)

Interactive terminal and audio previews for animations and graphical components:

| Tool | Language | Purpose & Usage |
|------|----------|-----------------|
| `preview_hakari.py`<br>`preview_hakari.bat` | Python / Batch | Plays the animated ANSI jackpot dance (`assets/animations/hakari_dance.ans`) synchronized with audio (`assets/audio/hakari_dance.wav`). Run via double-clicking `preview_hakari.bat` or `python tools/previews/preview_hakari.py`. |
| `preview_intro.py`<br>`preview_intro.bat` | Python / Batch | Plays the casino opening ANSI animation (`assets/animations/casino_intro.ans`) with support for Enter key skipping and `@@LOOP@@` frame looping. Run via `preview_intro.bat` or `python tools/previews/preview_intro.py`. |
| `preview_dbd_hook.py`<br>`preview_dbd_hook.bat` | Python / Batch + PowerShell | Previews the Dead by Daylight hook skill-check mini-game animation (`assets/animations/dbd_hook.ans`). Controlled by `runtime/dbd_hook.stop` and animation profile settings. Run via `preview_dbd_hook.bat`. |
| `preview_casino3d.bat` | Batch | Convenience launcher that switches to root and starts `poker.exe` in 3D DOOM/Wolfenstein retro view mode. |

---

## 2. Generators (`tools/generators/`)

Offline build tools that process raw images, generate lookup tables, and compose assembly code:

| Tool | Language | Purpose & Usage |
|------|----------|-----------------|
| `build_graphics_assets.py` | Python (Pillow) | Packs sprite sheets and texture atlases into 48 slots of 128×128 32-bit BGRA format, producing `assets/textures/casino3d-hd.bin`. Usage: `python tools/generators/build_graphics_assets.py`. |
| `build_casino_assets.py` | Python (Pillow) | Compiles source textures and sprite images into the legacy `assets/textures/casino3d.bin` binary. |
| `generate_font.py` | Python (Pillow) | Renders Consolas/Arial fonts for all 256 CP1251 characters into an 8×8 1-bit monochrome bitmap table, saved to `font8x8.inc`. Usage: `python tools/generators/generate_font.py`. |
| `generate_math_and_map.py` | Python | Computes 512-angle fixed-point (16.16) Sine and Cosine tables and the 32×32 casino hall floor plan, saving them to `casino3d_data.inc`. Usage: `python tools/generators/generate_math_and_map.py`. |
| `build_all_3d.py` | Python | Offline assembly file generator that synthesizes the complete `casino3d.inc` raycaster engine in CP1251. |
| `generate_unified_casino3d.py` | Python | Alternative unified generator for `casino3d.inc` with full sprite definitions and game interaction hooks. |
| `generate_casino3d.py`<br>`build_engine.py`<br>`make_casino3d.py` | Python | Lightweight orchestration scripts for triggering `casino3d.inc` regeneration in CP1251 encoding. |
| `patch_poker_asm.py` | Python | Helper utility to patch `poker.asm` with 3D engine hooks, player save anchors, and mutex management. |

---

## 3. Tests & Verification (`tools/tests/`)

Verification scripts, simulation harnesses, and runtime helpers:

| Tool | Language | Purpose & Usage |
|------|----------|-----------------|
| `simulate_render.py` | Python (Pillow) | Software CPU simulation of the 3D raycaster renderer. Reads `casino3d_data.inc` and texture binary, performs DDA raycasting, depth-sorting of 28 casino sprites, and saves the rendered view to `docs/render_view.png`. Usage: `python tools/tests/simulate_render.py`. |
| `release_smoke_check.ps1` | PowerShell | Automated smoke test for release readiness: verifies file presence, launcher SHA-256 hashes, CP1251 source markers, and absence of deprecated assets. Usage: `powershell -File tools/tests/release_smoke_check.ps1`. |
| `build_graphics.ps1` | PowerShell | Builds the Windows subsystem executable `build/graphics/poker.exe` using MASM32/MSVC toolchain. Usage: `powershell -File tools/tests/build_graphics.ps1`. |
| `achievement_popup.bat` | Batch (CP1251) | Standalone console achievement notification popup called by `poker.exe`. Reads achievement text from `runtime/achievement.txt` and renders a decorative banner with rarity colors (COMMON, RARE, EPIC, LEGENDARY). |