# ASSEMBLER CASINO (KAZIK) 🎰

A retro casino gaming suite powered by a high-performance **pure x86 assembly (MASM32)** engine featuring an interactive **2.5D retro Raycaster 3D Hall** (DOOM / Wolfenstein style) and a catalog of classic and underground gambling games.

The game runtime is assembly-only. This repository has one game core, built
from MASM sources; no C/C++ game port or non-assembly fallback is supported.
Native Linux/macOS versions are not available. Any future native platform
port must also use assembly. Python scripts are offline development tools,
and the existing C# launcher/installer are separate packaging utilities.

## First setup: offline fortune AI

After cloning or copying this repository, double-click
**`download_fortune_model.bat`** in the repository root. It downloads about 2.5 GB
into `ai/models/`, resumes interrupted downloads where supported, tries a backup
source, and verifies the exact size and SHA-256 before installation. Keep at
least 3 GB free. Windows PowerShell and `curl.exe` are required (included with
current Windows 10/11); Python, Git LFS and administrator access are not required.

Then launch `dist/Assembler Casino.exe` or `poker.exe`. Model setup is a separate,
manual step; the game never downloads anything and works offline afterward.
Running setup again verifies existing weights without downloading them again.
Complete offline release ZIPs already contain the model and need no download.
See [Fortune AI](docs/FORTUNE_AI.md) for details and hardware notes.

## Hell Expedition

The large hell painting opposite the first-floor bar opens an assembly-native FPS expedition:
Freedoom enemies and weapons, a blue-key gate, two secrets, lava and a final
boss, accompanied by the existing Mick Gordon soundtrack. First clear awards
$6,660; death/retry preserves the casino bank. See
[controls, assets and verification](docs/HELL_EXPEDITION.md).

## Native Entrance And Character Scenes

The graphical startup now fades from Eblan Games into a first-person opening:
eyes opening beneath a cloudy rainy sky, smoking in an alley, discarding the
cigarette, walking and turning through a separate city map, then meeting the
guards and choosing a local profile before entering the walkable hall.
The sequence resets on every launch; the intro advances automatically.
Sidorovich operates the native
card-back shop. New character sheets contain 32 guard poses and 24 merchant
poses, with separate actions rather than a single repeated idle animation.
Dealer-hand poses are synchronized with native poker/blackjack card movement.

New street, guards, merchant, furniture and table art use a detailed retro
pixel-art direction and nearest-neighbor sampling, not the rejected realistic
palace facade. Converting every legacy
asset and terminal game is still in progress; multiplayer card tables are not
implemented by adding decorative opponents. See [Graphical Scenes](docs/GRAPHICAL_SCENES.md)
for the implemented scope, asset pipeline and remaining gameplay work.

Verify the production ASM logic and framebuffer snapshots with:

```powershell
tools/tests/test_casino_actions.ps1
python tools/tests/check_arrival_frames.py
python tools/tests/check_card_table_frames.py
```

---

## 🏛️ Architecture Overview

The repository contains one assembly game runtime and separate development
and packaging tools:

```text
MASM sources --> ml.exe / link.exe --> poker.exe
assets/ ----------------------------> native game data
tools/ -----------------------------> offline asset generation and tests
build/ / dist/ ---------------------> existing launcher and installer
```

1. **MASM32 Core Game Engine (Root)**
   - **`poker.asm`**: Main game binary (~8,500+ lines of hand-crafted x86 assembly). Contains game logic, cheat engine, socket networking, profile save system, and sound triggers.
   - **`casino3d.inc` / `casino3d_data.inc`**: Software 2.5D Raycaster engine rendering a 32×32 grand casino hall at 640×480 with DDA wall casting, depth-sorted sprite objects, and interactive tables.
   - **`font8x8.inc`**: CP1251 1-bit monochrome 8×8 bitmap font table for high-speed HUD rendering directly to the Win32 GDI frame buffer.

2. **Desktop Distribution & Launcher (`build/` & `dist/`)**
   - **`build/`**: C# source code for the launcher (`AssemblerCasinoLauncher.cs`), setup GUI (`PokerGameSetupGui.cs`), and uninstaller.
   - **`dist/`**: Ready-to-run compiled desktop executables (`Assembler Casino.exe`, `Uninstall Assembler Casino.exe`).

3. **Offline Development Tooling (`tools/`)**
   - **`tools/previews/`**: Terminal ANSI animation players (`preview_intro.py`, `preview_hakari.py`, `preview_dbd_hook.py`) and 3D preview runner.
   - **`tools/generators/`**: Texture pack scripts (`build_graphics_assets.py`), math table generators (`generate_math_and_map.py`), font rasterizer (`generate_font.py`).
   - **`tools/tests/`**: Software raycaster simulator (`simulate_render.py`), release integrity checks (`release_smoke_check.ps1`), achievement popup modal (`achievement_popup.bat`).

4. **Assets & Documentation (`assets/`, `docs/`, `backups/`)**
   - **`assets/`**: High-resolution textures, sprites, audio samples (`.wav`), and ANSI cinematics (`.ans`).
   - **`docs/`**: Design specifications, cheat sheet, networking guides, and engine render previews.
   - **`backups/`**: Historical milestones and archived releases.

---

## 📁 Repository Directory Structure

```
├── poker.asm                    # Primary MASM32 assembly source
├── casino3d.inc                 # 2.5D retro 3D raycaster engine implementation
├── casino3d_data.inc            # 3D engine math tables (sin/cos) & casino hall grid
├── font8x8.inc                  # 8x8 CP1251 bitmap font data
├── poker.wap                    # Pelles C / Windows project definition
├── build.bat                    # One-click build script for MASM32 core
├── poker.exe                    # Compiled game binary
├── AGENTS.md                    # Engineering guidelines and agent instructions
├── README.md                    # Project documentation (this file)
├── LICENSE                      # Project license
├── .gitignore                   # Git ignore patterns
│
├── assets/                      # Game assets
│   ├── animations/              # ANSI animations (casino_intro.ans, hakari_dance.ans, dbd_hook.ans)
│   ├── audio/                   # Sound effects (.wav) for cards, roulette, coins, win/loss
│   ├── data/                    # Dealer dialogues and text tables (CP1251)
│   ├── icons/                   # Game icon assets (.ico, .png)
│   ├── music/                   # Background tracks
│   ├── sprites/                 # Source sprite sheets & cabaret animations
│   └── textures/                # Packed 128x128 BGRA texture binaries (casino3d-hd.bin)
│
├── backups/                     # Preserved backups and legacy archives
│
├── build/                       # Launcher and setup source code (C# .NET)
│   ├── AssemblerCasinoLauncher.cs
│   ├── PokerGameSetupGui.cs
│   └── UninstallAssemblerCasino.cs
│
├── dist/                        # Compiled desktop distribution binaries
│   ├── Assembler Casino.exe
│   └── Uninstall Assembler Casino.exe
│
├── docs/                        # Project documentation, guides, and plans
│   ├── intro_code_draft.txt     # Opening sequence drafts
│   ├── render_view.png          # Simulated frame render of the 3D casino hall
│   ├── ИДЕИ.txt                 # Game ideas and development backlog
│   ├── ЧИТКОДЫ.txt              # Complete list of cheat codes
│   └── *.txt                    # Release notes, security guidelines, networking
│
└── tools/                       # Developer tooling & offline asset pipeline
    ├── README.md                # Documentation for tools
    ├── previews/                # Animation & 3D preview scripts (.py, .bat)
    ├── generators/              # Asset packers, math & font generators (.py)
    └── tests/                   # Software render simulator & test scripts (.py, .ps1, .bat)
```

---

## 🛠️ Build Instructions

### 1. MASM32 Game Binary (`poker.exe`)

Prerequisites: MASM32 SDK (`ml.exe`, `link.exe`) installed in `D:\MASM32\masm32`, `C:\masm32`, or Visual Studio MSVC BuildTools.

Simply run:
```bat
build.bat
```
This will assemble `poker.asm` with MASM, link against `kernel32`, `winmm`, `user32`, `ws2_32`, `gdi32`, and produce `poker.exe`.

### 2. Running Previews and Simulators

- **Hakari Jackpot Dance Preview**:
  ```bat
  tools\previews\preview_hakari.bat
  ```
- **Casino Intro Animation Preview**:
  ```bat
  tools\previews\preview_intro.bat
  ```
- **3D Engine Software Simulation**:
  ```bash
  python tools/tests/simulate_render.py
  ```
  Generates `docs/render_view.png` showing the 3D raycaster view with sprites.

---

## 🔤 Character Encoding Standard

- **Game source & strings (`poker.asm`, `assets/data/dealer_phrases.txt`)**: **CP1251 (Windows-1251)**. Never save as UTF-8.
- **ANSI animations (`.ans`)**: CP1251 encoding with ANSI escape codes and form feed (`\f`, `0x0C`) frame delimiters. Preview runners execute `chcp 65001` before playback.

---

## 🎮 Games & Features

| # | Game | Description |
|---|------|-------------|
| 1 | **21 / Blackjack** | Classic card game against the dealer with hit/stand mechanics. |
| 2 | **Poker** | Texas Hold'em with AI opponents, betting rounds, and pot calculations. |
| 3 | **CloverPit** | 5×3 video slots with custom bonus features and payouts. |
| 4 | **Russian Roulette** | High-stakes survival with revolver chamber simulation. |
| 5 | **Skulls & Cups** | Thimblerig shell game testing perception and luck. |
| 6 | **Coin Flip** | Double or nothing coin toss. |
| 7 | **Dice / Craps** | Classic dice rolling wagering. |
| 8 | **Roulette** | European roulette wheel with single and range bets. |
| 9 | **Classic Slots** | 3-reel 777 fruit machine. |
| 10 | **Durak** | Traditional Russian card game with trump cards and defense logic. |
| 11 | **Training** | Practice arena with infinite balance. |
| 12 | **Observer (AI vs AI)** | Watch autonomous agents play against each other. |
| 3D | **Grand Casino Hall** | Real-time 2.5D raycaster environment to explore and walk up to tables. |