62 lines
5 KiB
Markdown
62 lines
5 KiB
Markdown
# 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. |
|
||
| `generate_rich_minigames.py` | Python | Patches `casino3d.inc` with rich, custom 2.5D graphics and fixed audio for Coin, Craps, and Skulls. |
|
||
| `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 |
|
||
|------|----------|-----------------|
|
||
| `test_minigames_render.py` | Python (Pillow) | Visual simulation test suite that rasterizes 2.5D minigame UI frames and saves PNG previews to `docs/previews_minigames/`. Usage: `python tools/tests/test_minigames_render.py`. |
|
||
| `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). |
|
||
|