# AGENTS.md

## Project identity

Single-file x86 assembly (MASM32) Windows console casino game with retro 2.5D raycaster engine. Source: `poker.asm` (~8500 lines). Python scripts are offline tools for asset generation and previewing animations — not part of the game runtime itself.

The game runtime must remain assembly-only: rendering, gameplay, animation,
input, networking, and any future platform ports must be implemented in
assembly. Do not add a C/C++ core, a second non-assembly game implementation,
or a compiler fallback that substitutes one for the MASM executable.
Offline asset generators and tests are not the game runtime. The existing
C# packaging utilities must not be described as assembly code.

User-approved exception (2026-10-21): the fortune teller may use a bundled,
offline C++ neural inference worker based on llama.cpp. This exception is only
for model inference and text generation. The game, UI, card selection, rendering,
input and gameplay remain assembly-only. Do not add a cloud API, Ollama install
requirement or runtime model downloader. Ship the model with the distribution.

## Directory Structure

- **Root**: Core MASM32 game (`poker.asm`, `casino3d.inc`, `casino3d_data.inc`, `font8x8.inc`, `build.bat`, `poker.exe`).
- **`dist/`**: Compiled desktop distribution launchers (`Assembler Casino.exe`, `Uninstall Assembler Casino.exe`).
- **`build/`**: C# source code for launchers and installers.
- **`tools/`**: Internal developer tooling and pipelines:
  - `tools/previews/`: Terminal ANSI animation and 3D engine previews (`preview_intro.bat`, `preview_hakari.bat`, `preview_dbd_hook.bat`, `preview_casino3d.bat`).
  - `tools/generators/`: Offline asset compilers, math lookup tables, and assembly generators.
  - `tools/tests/`: Render simulation (`simulate_render.py`), release smoke checks, and achievement popup helpers.
- **`assets/`**: Media files (audio `.wav`, ANSI `.ans`, textures `.bin`, icons).
- **`docs/`**: Documentation, cheat codes, ideas backlog, and technical guides.
- **`backups/`**: Historical archives and pre-feature checkpoints.

## Build

- **Assembler**: `ml /c /coff /Cp /nologo poker.asm`
- **Link**: `link /SUBSYSTEM:CONSOLE /RELEASE /VERSION:4.0 /LIBPATH:"<MASM32>\lib" poker.obj kernel32.lib winmm.lib user32.lib ws2_32.lib gdi32.lib`
- **IDE project**: `poker.wap` (Pelles C/Windows)
- **Libraries**: `kernel32.lib`, `winmm.lib`, `user32.lib`, `ws2_32.lib`, `gdi32.lib`
- **Build script**: `build.bat` (uses MASM32 from `D:\MASM32\masm32` or MSVC BuildTools)

Requires MASM32 toolchain or MSVC BuildTools (`ml.exe`, `link.exe`).

## Encoding

- Source strings, `dealer_phrases.txt`: **CP1251** (Windows-1251). Do not re-save as UTF-8.
- `.ans` animation files: ANSI escape codes + CP1251, frames separated by form feed (`\f`, 0x0C).
- Preview scripts run `chcp 65001` before printing.

## Assets

| File | Purpose |
|------|---------|
| `assets/animations/casino_intro.ans` | Animated intro (skippable with Enter, loops at `@@LOOP@@` marker) |
| `assets/animations/hakari_dance.ans` | Animated dance on jackpot win |
| `assets/animations/dbd_hook.ans` | Dead by Daylight hook skill-check mini-game animation |
| `assets/data/dealer_phrases.txt` | CP1251, each line prefixed `W|` (win), `L|` (loss), `D|` (draw) |
| `assets/textures/casino3d-hd.bin` | Packed 48 slots (128×128 BGRA) 3D raycaster textures |

## Workflow

- **Git remote**: `https://git.silverstone.crazedns.ru/Billi_Bob/KAZIK.git` (branch `main`).
- Backups in `backups/` follow: `poker_before_<feature>_<YYYYMMDD_HHMMSS>.{asm,exe}`
- **No tests**. Manually verify by running `poker.exe`.
- Preview animations: `tools/previews/preview_hakari.bat` / `tools/previews/preview_intro.bat` (or `python tools/previews/preview_hakari.py` directly).

## Games (menu)

1=21/Blackjack, 2=Poker, 3=CloverPit (slots 5×3), 4=Russian Roulette, 5=Skulls & cups, 6=Coin, 7=Dice, 8=Roulette, 9=Slot machine, 10=Durak, 11=Training, 12=Observer AI vs AI, 0=Exit

Cheat codes: `MONEYRAIN`, `SEVENS`, `WINNEXT`, `GODMODE`, `FAIRPLAY`, `GOAL`, `RESETBANK`, `EASYAI`/`NORMALAI`/`HARDAI`, `JACKPOT`, `HIGHROLLER`, `DOUBLECASH`, `ONEBUCK` (entered at main menu).