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
这是什么？一个跨平台引擎，能在你自己合法拥有的游戏数据上运行《命令与征服：红色警戒2》（以及《尤里的复仇》和 Mental Omega 3 模组），它用 Rust 重写，采用现代渲染技术取代了原来的 DirectDraw 引擎。
这是一个新游戏，还是只是给原版 exe 打的图形补丁？都不是：它是完整的引擎重实现。它不是 DirectDraw 兼容层，也不会向原版的 game.exe/gamemd.exe 注入代码；它加载你的正版游戏资源，由它自己来模拟和渲染游戏。
具体怎么启动它？安装 npm 包 '@game-gpt/red-alert2' 并运行它的 CLI，用 --path 指向包含正版 MIX/INI 文件的游戏安装文件夹，例如 'ra2 launch --path '。
我需要自己提供原版游戏文件吗？需要。这个仓库不附带任何游戏资源（没有 MIX、INI、音频或地图）——你必须自己提供合法获得的红色警戒2/尤里的复仇安装目录。
现在真的能在浏览器里玩吗？还不能。浏览器路径（ra-wasm）目前只导出占位符号——画布渲染和资源加载都还没接上，所以目前只有桌面路径可用。
它支持哪些游戏或模组？红色警戒2、尤里的复仇和 Mental Omega 3 模组，各自由专门的适配器 crate（ra-adaptor-ra2、ra-adaptor-yuri、ra-adaptor-phobos）处理，把该版本的资源和规则映射到共享引擎上。
为什么我需要手动传 --edition？如果你的安装目录同时带有红色警戒2和尤里的复仇的特征，自动检测就会变得不明确，你必须通过配置或 --edition 命令行参数显式指定版本（ra2 或 yr）。
什么渲染技术取代了旧的 DirectDraw 渲染器？在桌面上，它通过 ra-renderer 面向 DX12、Vulkan 或 Metal 等现代 GPU API；浏览器目标则通过尚未完成的 ra-wasm 绑定走向 WebGL2。
代码库是怎么组织的？它是一个包含许多 crate 的 Rust workspace（ra-engine 负责权威的游戏 tick 模拟，ra-renderer 负责绘制快照，ra-desktop/ra-napi 负责原生窗口，ra-wasm 负责浏览器，另有适配器/地图/资源等 crate），每个 crate 都有自己的 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