README.md

---
title: ReVCDOS
emoji: 👑💵🚗🔫🌴🏖️🌆🌴
colorFrom: purple
colorTo: pink
sdk: docker
pinned: false
license: mit
---

reVCDOS - HTML5 Port

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/13GFRIxTwVbixv0Vup9MSVXnB4SLmA3G7?usp=sharing)

> **Fast Start:** Run the server in one click using Google Colab. Click the badge above, run the cell, and use the **"Launch Game"** button. The tunnel password will be copied automatically — just paste it on the page that opens.

Web-based port running in browser via WebAssembly.

You can check which files I made changes in commit section. Only for *educational* purpose only

## History & Restoration

This project is a community effort to preserve the incredible HTML5 port.

*   **The Ban**: Takedown for the original web port, shutting down the official servers and CDNs.
*   **Deobfuscation**: The source code was deobfuscated to allow for self-hosting and study.
*   **WebAssembly Magic**: Unlike standard PC mods, this port runs entirely in the browser using WebAssembly. It streams assets on-the-fly, making it playable on almost any device with a browser and keyboard, without installation.
*   **Restoring Functionality**: After the shutdown, the game would hang on a black screen because it couldn't fetch core data files (`.wasm`, `.data`) or assets from the dead CDNs. This repository solves that by:
    1.  Providing a server that serves these critical files locally.
    2.  Implementing a caching system to download and save surviving assets.
    3.  Removing dependencies on the defunct infrastructure.

> [!NOTE]
> We still do not have the source code for the files in `vcbr` (the compiled WebAssembly modules), which contain the core logic of the game. This project wraps and serves those existing binaries.

**Stability Test**: Watch the server in action here: [reVCDOS Server Stability Test](https://www.youtube.com/watch?v=C8nK81N4iBs)

## Quick Start

**Installation Tutorial**:

1. Windows 11 + Python/FastAPI: [Youtube](https://youtu.be/AEvh2ok-nvs?si=ibyGHrfqiBgYT39c)
2. Windows 11 + Apache Server/XAMPP: [Youtube](https://youtu.be/tgctRLYOxSg?si=wo8DgCqUSYDfLPhN)

---

1.  **Clone the repository**:
    ```bash
    git clone --depth 1 https://github.com/Th3w33knd/reVCDOS
    cd reVCDOS
    ```

2.  **Download Assets**:
    > [!WARNING]
    > These files contain copyrighted materials. You must own the original game to use them legally.

    *   **vcbr** (Core Data): [Download](https://gofile.io/d/ceuXTa) (or [Older Version](https://gofile.io/d/U63PZO))
    *   **vcsky** (Assets): [Download](https://gofile.io/d/9QsvMn)

    **Important**: Extract them so your folder structure looks exactly like this:
    ```text
    reVCDOS/
    ├── vcbr/
    │   ├── vc-sky-en-v6.data
    │   ├── vc-sky-en-v6.wasm
    │   ├── vc-sky-ru-v6.data
    │   └── vc-sky-ru-v6.wasm
    ├── vcsky/
    │   ├── sha256sums.txt
    │   ├── fetched/
    │   │   ├── audio/      <-- From download
    │   │   ├── data/       <-- From download
    │   │   └── ...
    │   └── ...
    ├── server.py
    └── ...
    ```

3.  **Install Pixi** (if not already installed):
    *   **Windows (PowerShell)**:
        ```powershell
        powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"
        ```
    *   **Linux & macOS**:
        ```bash
        curl -fsSL https://pixi.sh/install.sh | bash
        ```

4.  **Start the game**:
    *   **Online Mode** (Recommended):
        ```bash
        pixi run online
        ```
        *Checks local files first. If missing, downloads from CDN and caches them.*

    *   **Offline Mode** (Strict):
        ```bash
        pixi run offline
        ```
        *Uses ONLY local files. No network connection. Useful if you have all assets downloaded.*

    *   **Cheat Mode**:
        ```bash
        pixi run cheat
        ```

5.  **Play**: Open the link shown in the terminal (usually `http://localhost:8000`). If you used `pixi run cheat`, the browser should open automatically.

## Requirements

- Docker or Python 3.8+ or PHP 8.0+
- Dependencies from `requirements.txt`
- **Pixi** (Recommended for package management)

## Game Modes

The server supports different modes to suit your setup:

### 1. Online Mode (Recommended)
**Command:** `pixi run online`

*   **Behavior**: "Smart Caching". The server checks your local `vcsky/` folder first.
    *   **If file exists**: Serves it locally (Fast, Offline-capable).
    *   **If file missing**: Downloads it from the CDN and saves it to `vcsky/` for future use.
*   **Best for**: Most users. It ensures you can play immediately even if you haven't manually downloaded every single asset.

### 2. Offline Mode (Strict)
**Command:** `pixi run offline`

*   **Behavior**: "Strict Local". The server serves **ONLY** files present in your `vcsky/` and `vcbr/` folders.
    *   **If file missing**: Returns a 404 Error. No network requests are made.
*   **Best for**: Users who have manually downloaded the full asset packs and want to ensure no background network activity. Ideal for air-gapped or fully offline setups.

### 3. Cheat Mode
**Command:** `pixi run cheat`

*   **Behavior**: **Online Mode + Cheats + Auto-open**.
    *   Starts the server in Online Mode (Smart Caching).
    *   Automatically opens your default web browser.
    *   Enables the built-in cheat engine.
*   **How to use**: Once the game loads, press **F3** to open the cheat menu (Memory Scanner, Noclip, etc.).
*   **Best for**: Jumping straight into the action with cheats enabled.

## Setup & Running

### Option 1: Using Pixi (Recommended)

This project uses [Pixi](https://pixi.sh/) for dependency management and task running.

1.  **Install Pixi**: Follow the instructions at [pixi.sh](https://pixi.sh/).
2.  **Run a task**:
    *   `pixi run online` - Smart caching (download if missing).
    *   `pixi run offline` - Strict local files only.
    *   `pixi run cheat` - Online mode + cheats enabled + auto-open browser.

### Option 2: Using Docker
The easiest way to get started is using Docker Compose:

```bash
PACKED=https://folder.morgen.monster/revcdos.bin docker compose up -d --build
```

To configure server options via environment variables:

```bash
# Set port, enable auth and custom saves
IN_PORT=3000 AUTH_LOGIN=admin AUTH_PASSWORD=secret CUSTOM_SAVES=1 docker compose up -d --build
```

| Environment Variable | Description |
|---------------------|-------------|
| `OUT_HOST` | External host (default: 0.0.0.0) |
| `OUT_PORT` | External port (default: 8000) |
| `IN_PORT` | Internal container port (default: 8000) |
| `AUTH_LOGIN` | HTTP Basic Auth username |
| `AUTH_PASSWORD` | HTTP Basic Auth password |
| `CUSTOM_SAVES` | Enable local saves (set to `1`) |
| `VCSKY_LOCAL` | Serve vcsky from local directory (set to `1`, or path like `/data/vcsky`) |
| `VCBR_LOCAL` | Serve vcbr from local directory (set to `1`, or path like `/data/vcbr`) |
| `VCSKY_URL` | Custom vcsky proxy URL |
| `VCBR_URL` | Custom vcbr proxy URL |
| `VCSKY_CACHE` | Cache vcsky files locally while proxying (set to `1`) |
| `VCBR_CACHE` | Cache vcbr files locally while proxying (set to `1`) |
| `PACKED` | Serve from packed archive (filename or URL, e.g., `revcdos.bin`) |
| `UNPACKED` | Unpack archive to local folders (filename or URL, auto-sets vcsky/vcbr paths) |
| `PACK` | Pack a folder and serve from resulting archive (folder path or MD5 hash) |

### Option 3: Local Installation (Manual)

1. Install Python dependencies:
```bash
pip install -r requirements.txt
```

2. Start the server:
```bash
python server.py --vcsky_local --vcbr_local --custom_saves
```

Server starts at `http://localhost:8000`

### Option 4: Shared Hosting on PHP (No installation)

If you want to run the game from a hosted environment with `PHP 8.0` or above, just copy the contents of this repo to your desired hosting.
By default the `index.php` and `.htaccess` will get the job done.

## Server Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--port` | int | 8000 | Server port |
| `--custom_saves` | flag | disabled | Enable local save files (saves router) |
| `--login` | string | none | HTTP Basic Auth username |
| `--password` | string | none | HTTP Basic Auth password |
| `--vcsky_local` | flag | disabled | Serve vcsky from local `vcsky/` directory (Strict Local) |
| `--vcbr_local` | flag | disabled | Serve vcbr from local `vcbr/` directory (Strict Local) |
| `--vcsky_url` | string | `https://cdn.dos.zone/vcsky/` | Custom vcsky proxy URL |
| `--vcbr_url` | string | `https://br.cdn.dos.zone/vcsky/` | Custom vcbr proxy URL |
| `--vcsky_cache` | flag | enabled | Cache vcsky files locally while proxying (Smart Cache) |
| `--vcbr_cache` | flag | enabled | Cache vcbr files locally while proxying (Smart Cache) |
| `--cheats` | flag | disabled | Enable cheats in URL |
| `--open` | flag | disabled | Open browser on start |

**Examples:**
```bash
# Start on custom port
python server.py --port 3000

# Enable local saves (Recommended)
python server.py --custom_saves

# Enable HTTP Basic Authentication
python server.py --login admin --password secret123

# Use local vcsky and vcbr files
python server.py --vcsky_local --vcbr_local

# Cache files locally while proxying (hybrid mode)
python server.py --vcsky_cache --vcbr_cache
```

## URL Parameters

| Parameter | Values | Description |
|-----------|--------|-------------|
| `lang` | `en`, `ru` | Game language |
| `cheats` | `1` | Enable cheat menu (F3) |
| `request_original_game` | `1` | Request original game files before play |
| `fullscreen` | `0` | Disable auto-fullscreen |
| `max_fps` | `1-240` | Limit frame rate (e.g., `60` for 60 FPS) |
| `configurable` | `1` | Show configuration UI before play button |

**Examples:**
- `http://localhost:8000/?lang=ru` - Russian version
- `http://localhost:8000/?lang=en&cheats=1` - English + cheats

## Project Structure

```
├── server.py           # FastAPI proxy/caching server
├── pixi.toml           # Pixi project configuration
├── requirements.txt    # Python dependencies
├── revcdos.bin         # Packed archive (optional)
├── additions/          # Server extensions
│   ├── auth.py         # HTTP Basic Auth middleware
│   ├── cache.py        # Proxy caching and brotli decompression
│   ├── packed.py       # Packed archive serving module
│   └── saves.py        # Local saves router
├── utils/              # Utility modules
│   ├── packer_brotli.py # Archive packer with brotli compression
│   └── downloader_brotli.py # Archive packer with brotli compression
├── unpacked/           # Auto-created by --unpacked flag
│   └── {md5_hash}/     # Unpacked files organized by source hash
│       ├── vcsky/      # Decompressed game assets
│       └── vcbr/       # Brotli-compressed binaries
├── dist/               # Game client files
│   ├── index.html      # Main page
│   ├── game.js         # Game loader (updated with ownership check)
│   ├── index.js        # Module loader
│   ├── GamepadEmulator.js  # Touch controls
│   ├── idbfs.js        # IndexedDB filesystem
│   ├── jsdos-cloud-sdk.js  # Cloud saves (DOS Zone)
│   ├── jsdos-cloud-sdk-local.js  # Local saves (--custom_saves)
│   └── modules/        # WASM modules
├── vcbr/               # Core game data (REQUIRED LOCALLY)
│   ├── vc-sky-en-v6.data
│   ├── vc-sky-en-v6.wasm
│   ├── vc-sky-ru-v6.data
│   └── vc-sky-ru-v6.wasm
└── vcsky/              # Additional assets (Cached locally on demand)
    ├── sha256sums.txt
    └── fetched/        # Downloaded assets
        ├── data/
        ├── audio/
        ├── models/
        └── anim/
```

## Features

- 🎮 Gamepad emulation for touch devices
- ☁️ Cloud saves via js-dos key
- 💾 Local saves (with `--custom_saves` flag)
- 🌍 English/Russian language support
- 🔧 Built-in cheat engine (memory scanner, cheats)
- 📱 Mobile touch controls
- 🔒 **Original Game Verification**: You must provide an original game file to verify ownership and play the full version.

## Local Saves

When local saves are enabled (`--custom_saves` flag), enter any 5-character identifier in the "js-dos key" input field on the start page. This identifier will be used to store your saves in the `saves/` directory on the server.

Example: Enter `mykey` or `12345` - saves will be stored as `mykey_vcsky.saves` or `12345_vcsky.saves`.

## Controls (Touch)

Touch controls appear automatically on mobile devices. Virtual joysticks for movement and camera, context-sensitive action buttons.

## Cheats

Enable with `?cheats=1`, press **F3** to open menu:
- Memory scanner (find/edit values)
- All classic cheats
- AirBreak (noclip mode)

## Remote Access (Tailscale / LAN)

The server is configured to listen on `0.0.0.0`, meaning it accepts connections from other devices on your network (LAN or VPN like Tailscale).

### 1. Connecting
Simply use your host computer's IP address and the port (default 8000).
*   **LAN**: `http://192.168.1.x:8000`
*   **Tailscale**: `http://100.x.y.z:8000`

### 2. "Secure Context" Issues (Browser Blocking)
Modern browsers restrict high-performance features (like `SharedArrayBuffer`, required by this game) to **Secure Contexts** (HTTPS or localhost). Connecting via a plain HTTP IP address (like `http://100.x.y.z:8000`) may cause the game to hang or crash.

#### Solution A: Tailscale Serve (Recommended)
Use Tailscale's built-in HTTPS feature to create a secure tunnel.
1.  Run the game server: `pixi run online`
2.  In a separate terminal, run:
    ```bash
    tailscale serve https:443 / http://127.0.0.1:8000
    ```
3.  Open the provided HTTPS URL (e.g., `https://your-pc.tailnet.ts.net`) on your remote device.

#### Solution B: Browser Flag (Workaround)
Force your browser to treat the insecure IP as secure.
1.  On the **client device** (e.g., your phone or laptop), open Chrome/Edge.
2.  Go to `chrome://flags/#unsafely-treat-insecure-origin-as-secure`.
3.  Enable the flag and enter your server's full URL (e.g., `http://100.100.10.10:8000`).
4.  Relaunch the browser.

## Deploying reVCDOS on Android (Termux) via TUR Wheels

### 1. Summary & Problem History
We are deploying the `reVCDOS` (WebAssembly) server on Android.
*   **The Issue:** The dependency `pydantic-core` requires Rust compilation. Compiling natively on Android fails due to memory limits (`LLVM ERROR: out of memory`) and toolchain incompatibilities (`cargo-xwin` errors).
*   **The Fix:** We bypass compilation entirely by forcing `pip` to download **pre-compiled binaries (wheels)** from the Termux User Repository (TUR).
*   **Network Requirement:** A **VPN** is required because some ISPs block the TUR repository, causing `SSL connect errors`.

---

### 2. Prerequisites
1.  **Android Device** with Termux (F-Droid version).
2.  **VPN Active:** Essential to prevent connection errors to the custom repository.
3.  **Game Files:** `vcbr` and `vcsky` folders extracted in `/sdcard/Download`.

---

### 3. Deployment Protocol

#### Phase 1: Environment Initialization
Update the system and install base tools.
```bash
# Update system
pkg update && pkg upgrade -y

# Install Python, Git, and SSL tools
pkg install python git openssl-tool -y

# Grant storage access (Tap 'Allow' on screen)
termux-setup-storage
```

### Phase 2: The "Binary-Only" Injection (VPN Required)
*Objective: Force pip to find a pre-compiled version of Pydantic that matches the available Pydantic-Core in the Termux repository, bypassing all compilation.*

**⚠️ CRITICAL:** Ensure your **VPN is ON** for this step to avoid connection errors with the custom repository.

```bash
# 1. Install Pydantic (and automatically resolve Pydantic-Core binary)
# We use --only-binary=:all: to prevent pip from trying to compile newer, unsupported versions.
pip install --extra-index-url https://termux-user-repository.github.io/pypi/ --only-binary=:all: pydantic

# 2. Install the remaining web server dependencies
# (Standard pip install is fine here as these are pure Python or standard packages)
pip install fastapi uvicorn httpx python-multipart brotli
```

#### Phase 3: Project Setup
Clone the game server code.
```bash
cd $HOME
rm -rf reVCDOS # Clear previous attempts
git clone --depth 1 https://github.com/Th3w33knd/reVCDOS
cd reVCDOS
pip install -r requirements.txt
```

#### Phase 4: Asset Injection (Manual)
Import the game assets from internal storage.
```bash
# Copy Core Data (vcbr) - The game logic
cp -r /sdcard/Download/vcbr ./

# Copy Assets (vcsky) - Audio and textures (Optional)
cp -r /sdcard/Download/vcsky ./
```

#### Phase 5: Server Execution
Run the server in offline/local mode to ensure it uses the files we just copied.
```bash
python server.py --vcsky_local --vcbr_local --custom_saves
```

---

### 4. Known Error States & Fixes

| Symptom | Cause | Fix |
| :--- | :--- | :--- |
| `SSL connect error` / `No matching distribution` | ISP blocking TUR Repo | **Turn on VPN** and retry Phase 2. |
| `Linker command failed` / `Aborted` | Pip tried to compile source | Ensure you used `--only-binary=:all:` in Phase 2. |
| `Could not find version for maturin` | Maturin isn't in TUR | **Ignore it.** We don't need `maturin` when using binaries. Remove it from the install command. |
| Black Screen in Browser | Missing Game Files | Re-run Phase 4. Ensure `vcbr` folder contains `.wasm` files. |

---

### 5. Final Success State
*   Server is running in Termux.
*   User opens Chrome to `http://localhost:8000`.
*   Game loads without compilation errors.

## License

MIT. Do what you want (but credit the port authors and me). Not affiliated with Rockstar Games.

---

**Authors:** DOS Zone ([@specialist003](https://github.com/okhmanyuk-ev), [@caiiiycuk](https://www.youtube.com/caiiiycuk), [@SerGen](https://t.me/ser_var))

**Deobfuscated by**: [@Lolendor](https://github.com/Lolendor)

**Russian translation:** [GamesVoice](https://www.gamesvoice.ru/)

**Some more files were required for being Fully Local:** [Th3w33knd](https://github.com/Th3w33knd)

## Support me

If you find this project useful:

- **TON / USDT (TON)**  `UQAyBchGEKi9NnNQ3AKMQMuO-SGEhMIAKFAbkwwrsiOPj9Gy`

## Changelog

### v1.2.2 - Documentation Updates
*   **Guide**: Added detailed guide for deploying on Android via Termux.
*   **Docs**: Updated project description to be more generic.

### v1.2.1 - Post-Merge Fixes
*   **Fix**: Resolved `SyntaxError` in `game.js` by restoring missing IIFE wrapper.
*   **Fix**: Resolved `ReferenceError` in `index.js` by exposing `currentLanguage` to global scope.
*   **Fix**: Resolved `server.py` 500 Error by defining missing arguments and global variables.
*   **Dependency**: Added `aiofiles` to `pixi.toml` and `requirements.txt`.

### v1.2.0 - Upstream Sync & Fixes
*   **Upstream Merge**: Merged latest changes from `Lolendor/reVCDOS` (Google Colab support, license, graphics updates).
*   **Bug Fix**: Fixed `server.py` startup issue preventing the server from running.
*   **Conflict Resolution**: Preserved local preferences (Offline Mode, Cheats) during merge.

### v1.1.0 - Tailscale & Localization Update
*   **Remote Access**: Server now binds to 0.0.0.0 to allow connections from LAN and Tailscale.
*   **Documentation**: Added guide for connecting via Tailscale/LAN and handling Secure Contexts.
*   **Localization**: Fixed Russian text in the main menu (Subscribe for news and releases).
*   **Credits**: Added comprehensive credits for Deobfuscation, Translation, and Offline Support.

### v1.0.0 - Initial Enhancements
*   **Offline Mode**: Game assets are cached locally for offline play.
*   **Cheats**: Added cheat menu (F3) and support for classic cheats.
*   **Smart Caching**: Optimized asset loading strategy.