ra2.exe README

The project's README from github.com/rust-alert/ra2.exe. As one markdown file: README.md.

ra2

跨平台 GUI 引擎，用于在玩家自备的《命令与征服：红色警戒 2》、《尤里的复仇》以及心灵终结 3（Mental Omega 3）数据上运行自有逻辑。

本仓库是 现代化重写：产品入口为 npm 包 @game-gpt/red-alert2（CLI ra2 launch --path），经 N-API 拉起原生窗口实现 ra-desktop；对局由 ra-engine 推进，呈现走现代 GPU API（桌面常见 DX12 / Vulkan / Metal；浏览器目标走 WebGL2 方向的 ra-wasm）。不是 DirectDraw 兼容层， 不是向原版 game.exe / gamemd.exe 注入。

仓库 不包含原版 MIX / INI / 音频 / 地图等资源文件。运行前请自行准备合法取得的游戏安装目录。

从安装启动与配置开始，再往下看开发构建与架构：准备数据与配置 → 安装 / 构建运行 → 理解游戏如何执行 → 再看以 ra-engine 为重心的分层与各 crate 文档。

安装与启动

npm i -g @game-gpt/red-alert2
# 合集盘 / 同时有 game.exe 与 gamemd.exe 时必须显式指定版本，否则可能落到 YR 资源链
ra2 launch --path "C:/Games/RA2" --edition ra2
ra2 launch --path "C:/Games/YR" --edition yr

--path 指向含零售 MIX/INI 的安装根目录。壳层 UI 当前以 RA2 资源链对照为主；混装安装请始终加 --edition ra2。

准备游戏数据与配置

也可在工作目录放置 RustAlert.toml，用于分辨率、显示与其它启动选项。模板见 RustAlert.toml.example。 若启动时尚无该文件，程序会自动生成一份默认配置以便持久化。CLI --path 优先于其中的 ra2_dir。

# 仅当未用 CLI --path、且工作目录不在游戏安装根内时需要显式写出
ra2_dir = "C:/path/to/your/ra2"
edition = "ra2"
键 说明
ra2_dir / game_dir 含零售 MIX、INI 的游戏目录；CLI --path 覆盖此项
edition ra2 或 yr（另支持若干别名，见 ra-types）；省略则按目录特征自动探测

若目录同时具备原版与尤里的复仇特征，自动探测会报歧义，此时须显式写明 edition（或 CLI --edition）。配置由 toml_edit 读写（可保留注释）。

开发构建

工具链以根目录 rust-toolchain.toml 为准（ nightly，含 rustfmt / clippy）。JS 侧用 pnpm workspace。

pnpm install
pnpm run build
pnpm exec ra2 --help

# 对局与资源相关回归
cargo test -p ra-assets -p ra-map -p ra-engine -p ra-testing

# 资源查证：用 extract / unpack，不要再写一次性 Rust 探针
pnpm exec ra2 extract --path "C:/Games/RA2" --edition ra2 --out ./tmp/extract --decode-shp -- sdtp.shp title.pcx
pnpm exec ra2 unpack --path "C:/Games/RA2" --edition ra2 --out ./tmp/unpack
pnpm exec ra2 unpack --path "C:/Games/RA2" --edition ra2 --out ./tmp/unpack --names-file ./extra_names.txt

# 仅调试原生壳（非资源探针）：需 RustAlert.toml 或默认目录
cargo run -p ra-desktop --example launch

pnpm run lint
pnpm run fmt

浏览器路径：ra-wasm → @game-gpt/red-alert2-unknown-wasm32，再由 @game-gpt/red-alert2 的 ./wasm 面整合。当前导出为占位符号，画布与资源加载尚未接线；构建与现状见该 crate README。

Release 配置（工作区 Cargo.toml）启用较高优化、LTO、符号剥离与 panic = "abort"，适合分发原生插件；日常开发用默认 debug 即可。

游戏如何执行

桌面经 @game-gpt/red-alert2 → ra-napi → ra-desktop；浏览器经同一 host 的 ./wasm 面 → ra-wasm（当前占位）。两条壳层都把对局权威状态交给 ra-engine：装载配置与内容后打开会话，每帧提交命令、pump 固定 tick，再取 RenderSnapshot 交给 ra-renderer。细节见 projects/bindings/ra-desktop/readme.md 与 projects/engine/ra-engine/readme.md。

sequenceDiagram
    participant User as 用户
    participant Host as "@game-gpt/red-alert2"
    participant Napi as ra-napi
    participant Cfg as ra-config
    participant Desk as ra-desktop
    participant Ad as ra-adaptor
    participant Map as ra-map
    participant Eng as ra-engine
    participant Ren as ra-renderer
    User ->> Host: ra2 launch --path
    Host ->> Napi: 加载原生插件
    Napi ->> Desk: run
    Desk ->> Cfg: 合并桌面设置（含 CLI 覆盖）
    Cfg -->> Desk: 游戏目录 / edition
    Desk ->> Ad: 识别安装并组合适配能力
    Ad -->> Desk: 资源链与规则投影
    Desk ->> Map: 解析启动地图 / 剧院 / 通行
    Desk ->> Eng: 打开遭遇战对局
    Desk ->> Ren: 附着窗口与预览
    loop 每帧
        Desk ->> Eng: 提交命令并 pump 固定 tick
        Eng -->> Desk: 权威状态已推进
        Desk ->> Eng: snapshot
        Eng -->> Desk: RenderSnapshot
        Desk ->> Ren: draw_frame
    end

原版与尤里的复仇共用同一套引擎与呈现流水线；差异集中在 adaptor 资源表以及玩家目录里的数据内容。

架构总览（重心：ra-engine）

对局权威状态与固定 tick 推进集中在 ra-engine。npm 包 @game-gpt/red-alert2 同时依赖原生绑定 ra-napi 与浏览器绑定 ra-wasm；壳层负责配置、目录与事件循环；渲染只消费引擎导出的快照；测试经同一命令与 tick 路径回归。

flowchart TB
    subgraph shells["壳层 / 绑定"]
        host["@game-gpt/red-alert2<br/>CLI / Node / 浏览器面"]
        napi["ra-napi"]
        desktop["ra-desktop<br/>窗口 / 输入 / 事件循环"]
        wasm["ra-wasm<br/>Wasm 绑定"]
    end

    subgraph present["呈现"]
        renderer["ra-renderer"]
    end

    subgraph runtime["对局运行时 · 重心"]
        engine["ra-engine"]
        ecs["ra-ecs"]
    end

    subgraph content["内容投影"]
        map["ra-map"]
        adaptor["ra-adaptor 及具体适配器"]
    end

    subgraph formats["格式与配置"]
        assets["ra-assets"]
        config["ra-config"]
    end

    types["ra-types<br/>含 RuntimeDefinitions"]
    net["ra-net"]
    testing["ra-testing"]
    host --> napi
    host --> wasm
    napi --> desktop
    desktop --> config
    desktop --> renderer
    desktop --> engine
    desktop --> map
    desktop --> assets
    desktop --> adaptor
    wasm -.-> renderer
    wasm -.-> engine
    renderer --> engine
    engine -.-> ecs
    engine --> map
    engine --> adaptor
    map --> assets
    adaptor --> assets
    assets --> types
    config --> types
    adaptor --> types
    ecs --> types
    engine --> types
    renderer --> types
    net --> types
    testing --> engine

ra-engine 内部按 runtime / state / spatial / gameplay / lifecycle / presentation / persistence 划分，详见引擎 README。

虚线表示下游尚未完全接线：ra-wasm → 引擎 / 渲染仍是占位；ra-ecs 已存在但尚未被 ra-engine 依赖。ra-testing 只服务测试，不被产品 crate 默认依赖。

Crate / 包依赖关系（简化）

flowchart LR
    types[ra-types]
    ecs[ra-ecs]
    ra2a[ra-adaptor-ra2]
    yra[ra-adaptor-yuri]
    phobos[ra-adaptor-phobos]
    ad[ra-adaptor]
    as[ra-assets]
    cf[ra-config]
    mp[ra-map]
    eng[ra-engine]
    re[ra-renderer]
    de[ra-desktop]
    napi[ra-napi]
    host["@game-gpt/red-alert2"]
    we[ra-wasm]
    te[ra-testing]
    net[ra-net]
    ra2a --> types
    yra --> types
    phobos --> types
    ecs --> types
    ad --> types
    ad --> as
    ad --> ra2a
    ad --> yra
    ad --> phobos
    as --> types
    cf --> types
    mp --> types
    mp --> as
    eng --> types
    eng --> ad
    eng --> mp
    eng --> as
    eng --> net
    re --> types
    re --> eng
    de --> ad
    de --> cf
    de --> as
    de --> mp
    de --> eng
    de --> re
    de --> net
    napi --> de
    napi --> cf
    host --> napi
    host --> we
    we -.-> types
    we -.-> eng
    we -.-> re
    te --> eng

仓库布局

ra2.exe/                 工作区根（本 README）
├── Cargo.toml           Rust workspace；默认成员 ra-desktop
├── package.json         pnpm workspace 根
├── rust-toolchain.toml  nightly
├── License.md           Apache-2.0
├── scripts/             构建 / 发布脚本
└── projects/
    ├── engine/          ra-types … ra-renderer / ra-net
    ├── adapters/        ra-adaptor*
    ├── bindings/        ra-napi · ra-desktop · ra-wasm
    ├── tooling/         ra-testing（后续 ra-modder）
    ├── hosts/           red-alert2（@game-gpt/red-alert2）
    ├── platforms/       native / wasm 平台包
    └── sites/           homepage / playground

每个 crate 目录下有独立 readme.md，说明该包职责与现状。建议先读 ra-engine 与 ra-desktop，再按启动链路下钻 adaptor / map / assets / renderer。

Crate / 包一览

包 / Crate 作用 文档
@game-gpt/red-alert2 CLI + Node API + 浏览器面 README
ra-napi N-API 绑定（供 host 加载） —
ra-desktop 原生窗口 / 输入 / 事件循环（仅供 ra-napi） readme
ra-wasm Wasm 绑定（占位） readme
ra-types 基类型 + 冻结 RuntimeDefinitions（全体层共同语言） readme
ra-ecs 通用实体/组件存储与结构变更（无 RTS 语义） readme
ra-assets Westwood 格式与 INI 派生表 readme
ra-config 配置来源合并与诊断 readme
ra-map 地图 / 剧院 / 通行与预览装配 readme
ra-adaptor 版本探测、组合适配、资源链与规则投影 readme
ra-adaptor-ra2 原版资源表 readme
ra-adaptor-yuri 尤里的复仇资源表 readme
ra-adaptor-phobos Phobos / MO 布局资源表 readme
ra-engine 一局对局：命令、固定 tick、权威状态、呈现快照 readme
ra-net 联机协议无关基础类型（Beta 接入点） readme
ra-testing headless 夹具与 GUI 自动化计划（非运行时） readme
ra-renderer 呈现（只消费引擎快照） readme

设计要点

许可与数据

ra2.exe (rust-alert/ra2.exe)

Searching Database…

317 ·GitHub
Ra2.exe
What is this?A cross-platform engine that runs Command & Conquer: Red Alert 2 (plus Yuri's Revenge and the Mental Omega 3 mod) on your own legally-owned game data, rewritten in Rust with modern rendering instead of the original DirectDraw engine.
Is this a new game, or just a graphics patch for the original exe?Neither: it's a full engine reimplementation. It is not a DirectDraw compatibility layer and does not inject code into the original game.exe/gamemd.exe; it loads your retail assets and simulates/renders the game itself.
How do I actually launch it?Install the npm package '@game-gpt/red-alert2' and run its CLI, pointing --path at your game installation folder that contains the retail MIX/INI files, e.g. 'ra2 launch --path '.
Do I need to provide the original game files myself?Yes. The repo ships no game assets at all (no MIX, INI, audio, or maps) — you must supply a legally obtained RA2/Yuri's Revenge installation directory yourself.
Can I actually play this in a browser already?Not yet. The browser path (ra-wasm) currently only exports placeholder symbols — the canvas rendering and asset loading are not wired up yet, so only the desktop path is functional today.
Which games or mods does it support?Red Alert 2, Yuri's Revenge, and the Mental Omega 3 mod, each handled by their own adaptor crate (ra-adaptor-ra2, ra-adaptor-yuri, ra-adaptor-phobos) that maps the version's assets and rules onto the shared engine.
Why would I need to pass --edition manually?If your install directory has characteristics of both RA2 and Yuri's Revenge, auto-detection becomes ambiguous and you have to explicitly set the edition (ra2 or yr) via config or the --edition CLI flag.
What rendering tech replaces the old DirectDraw renderer?On desktop it targets modern GPU APIs like DX12, Vulkan, or Metal through ra-renderer; the browser target is heading toward WebGL2 via the still-unfinished ra-wasm binding.
How is the codebase structured?It's a Rust workspace of many crates (ra-engine for authoritative game-tick simulation, ra-renderer for drawing snapshots, ra-desktop/ra-napi for native windowing, ra-wasm for the browser, plus adaptor/map/asset crates), each with its own readme.
What are similar projects?OpenRA, CnC_Remastered_Collection, filmcraft, gpuix, bgfx, fframes, ps2-web-recomp, raylib
Which topics is it in?game-ai, webassembly, game-engine, metal, vulkan, game-development, wasm, rust, gpu, npm, desktop-app, apache-2.0
Creator
rust-alert
Size
5.8 MB
Stars
317
Updated
CommitAug 12
Age
1mo
Commits · 90 Days