Hugging Face's logo

Spaces:
th3w33knd
/
reVCDOS
Running

App Files Community
reVCDOS / README.md
Avitesh Murmu
Emoji Vice City
d22890f
preview code
|
raw
history blame contribute delete
20.1 kB
metadata
title: ReVCDOS
emoji: 👑💵🚗🔫🌴🏖️🌆🌴
colorFrom: purple
colorTo: pink
sdk: docker
pinned: false
license: mit

reVCDOS - HTML5 Port

Open In Colab

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.

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

Quick Start

Installation Tutorial:

  1. Windows 11 + Python/FastAPI: Youtube
  2. Windows 11 + Apache Server/XAMPP: Youtube

  1. Clone the repository:

    git clone --depth 1 https://github.com/Th3w33knd/reVCDOS
cd reVCDOS

  2. Download Assets:

    These files contain copyrighted materials. You must own the original game to use them legally.

    Important: Extract them so your folder structure looks exactly like this:

    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 -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"
    • Linux & macOS:
      curl -fsSL https://pixi.sh/install.sh | bash

  4. Start the game:

    • Online Mode (Recommended):

      pixi run online

      Checks local files first. If missing, downloads from CDN and caches them.

    • Offline Mode (Strict):

      pixi run offline

      Uses ONLY local files. No network connection. Useful if you have all assets downloaded.

    • Cheat Mode:

      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 for dependency management and task running.

  1. Install Pixi: Follow the instructions at 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:

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

To configure server options via environment variables:

# 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:
pip install -r requirements.txt
  1. Start the server:
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:

# 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:
    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.

# 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.

# 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.

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.

# 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.

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, @caiiiycuk, @SerGen)

Deobfuscated by: @Lolendor

Russian translation: GamesVoice

Some more files were required for being Fully Local: 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.