KAZIK/README.md

253 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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).
## Basement Activities
In the main hall, approach the basement door and press **E**; walk through the
opened doorway. A side passage on the left leads to a separate underworld
club with Semyon, rat races and the heist planning table. Sidorovich's workshop
stays in the original room. Approach each object and press **E** when its prompt
appears. The bar remains in the main hall; press **E** at the counter and use
**1–6** for drinks (**7** recruits the bartender). The controls and current
implementation status are listed in
[Underworld and the Grand Heist](docs/HEIST_AND_UNDERWORLD.md).
The optional heist prototype targets a rival owners' headquarters on a separate first-person
map. Choose stealth or assault at the planning table (**5**), ride there in
the crew's vehicle, breach the strongroom and extract with the loot. The return
trip restores the original casino position; the reward is paid only after
extraction. See [mission route and controls](docs/HEIST_HQ.md).
The generated v2 art is in `assets/sprites/hall/underworld-portraits-v2.png`,
`underworld-world-v2.png` and `rat-race-v2.png`. The game loads the corresponding
ANM1 packs from `assets/animations/hall/`. Repack these approved atlases with
`python tools/generators/pack_underworld_v2.py`; prompts are recorded in
`assets/sprites/hall/prompts-underworld-v2.json`. The old v1 sheets are retained
as historical sources. Loans, recruited crew and the one-time heist reward are
saved per profile in a `.underworld` sidecar. `build.bat` also updates the
launcher and `bin/poker.exe`, so the launcher uses the freshly built game.
## Native Entrance And Character Scenes
The graphical startup runs a Russian content disclaimer, a Full HD Eblan Games
studio ident rendered offline in Blender, and a short explanation of games and
exploration. In the 16-second studio film a cassette reel takes up slack tape on a repair
bench. A can rolls over the desk edge and its lower rim trips a
floor switch. A mechanical relay snaps open. On the dark CRT a point of light
stretches into a scan line and draws the EG studio signature. Watch `assets/cinematics/masters/Eblan-Games-v8.mp4`. The export tools can also write a ProRes master for use in other games.
The playable opening follows with
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.
Enter/Space advances one startup page; Escape skips to the opening scene.
After profile admission and entry into the hall, a centred cyberpunk briefing
unfolds from a point and types version 4.0, game information and controls.
The jukebox starts on entry at 50% volume, with normal positional attenuation.
Enter completes the text, then closes it; Escape closes immediately. Movement
is blocked while the briefing is open. See [startup and briefing](docs/STARTUP_PRESENTATION.md).
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`), modern setup wizard (`build/installer/PokerGameSetup.csproj`), and uninstaller (`UninstallAssemblerCasino.cs`).
- **`dist/`**: Ready-to-run compiled desktop executables (`Assembler Casino.exe`, `Uninstall Assembler Casino.exe`).
- **`PokerGameSetup.exe`**: Self-extracting setup package bundling full game payload, offline fortune AI model (2.5 GB), desktop shortcuts, and modern dark-themed wizard UI.
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.
### 3. Desktop Installer (`PokerGameSetup.exe`)
Prerequisites: .NET Framework 4.8 / .NET SDK (`dotnet`), Python 3.
To build the full installer with offline neural model embedded (~3.36 GB):
```bash
python tools/build_setup.py
```
To build lightweight installer without neural weights (~860 MB):
```bash
python tools/build_setup.py --no-model
```
---
## 🔤 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. |