iw4L README

The project's README from github.com/vladtrc/iw4L. As one markdown file: README.md.

IW4L

IW4L is a Call of Duty runtime written from scratch in Rust, on bevy and wgpu. Point it at a copy of MW2 you already own and it loads that install's data into its own engine.

The on-disk layouts came out of reverse engineering the original binaries and reading public technical references.

This whole project is written by an LLM.

Status

No releases yet: you build it from this tree. Nothing here is stable either — the API, the config format, caches and the wire protocol all change between commits, so everyone in a session needs to be on the same one. Expect bugs and desyncs.

The network side is for arranged playtests among people who already agreed to play; it has never been vetted for lobbies full of strangers. IW4L sends nothing home, and diagnostic files sit on your disk until you attach them to a report.

Architecture

assets MW2 zones read natively; MW3 and Black Ops land in the same asset_iw4 IR.
shaders Retail D3D9 SM3 tokens translated to WGSL, so no DirectX at runtime.
rendering One sorted drawsurf list; only the tess emitters fork per surface type.
physics Fixed 17 ms step on its own accumulator. Framerate changes nothing about how a body falls.
simulation One TickInput → sim::step → Snapshot funnel for server, prediction and replay.
network Custom p2p wire over UDP: deltas, reliability, reconciliation. A QUIC master only introduces peers.
platforms Linux, macOS (Metal) and a portable Windows build.

Retail protocols, the original ABI and patched executables are out of scope. IW4L clients talk to IW4L clients.

Game data

IW4L_GAMES points at the folder holding your game trees. No assets ship in this repository or in any release, and IW4L is unaffiliated with the rights holders of the original games.

Those trees are read only. IW4L never patches them, swaps files in them or writes anything back; caches, settings, demos and logs land in iw4l-artifacts/ next to the IW4L binary.

Build and run

System packages first: docs/BUILD.md (Fedora / Debian / Arch — compiler, ALSA, udev, X11/Wayland headers; macOS — Xcode command line tools).

cp .env.example .env          # IW4L_GAMES — folder containing the game trees
make map mp_boneyard          # run a map
make map mp_boneyard CMDS='spawn 0; wait 2s; quit'
make help                     # every recipe

Live runs use [profile.play], a development build with optimizations turned on. PROFILE=release builds the real release binary. docs/WINDOWS.md covers Windows.

Documentation

Implementation notes live under docs/, one short file per area. Start at docs/INDEX.md.

file about
docs/BUILD.md system packages per distro, macOS, Windows cross prerequisites
docs/RUN.md running the game, console scripts, commands and traps
docs/PERF.md Perfetto tracing and performance analysis
docs/RENDER.md rendering pipeline
docs/MAP-LOAD.md map loading and asset installation
docs/ENTITIES.md simulation data flow and entity taxonomy
docs/SIM-STEP.md simulation step architecture
docs/ANIM.md animation system
docs/WINDOWS.md portable Windows build
docs/DEPLOY.md release, publishing and deployment
docs/MASTER.md running your own master server

Contributing and support

A personal, experimental project. Bug reports are welcome and get no promised fix date. CONTRIBUTING.md says what a useful report contains and how changes get reviewed; security reports go to SECURITY.md.

Acknowledgements

IW4L ships none of the code below. It was read against all of it.

License

IW4L is licensed under the Apache License 2.0, and NOTICE holds the copyright notices, the licences of the projects above and the bundled fonts. That licence covers IW4L's own source code. Call of Duty, Modern Warfare, Black Ops and the related assets, trademarks and intellectual property belong to their respective owners.

iw4L (vladtrc/iw4L)

Searching Database…

1.1K ·GitHub
这是什么?IW4L 是一个用 Rust 基于 Bevy 和 wgpu 从零编写的使命召唤运行时。你把它指向你已拥有的现有 Modern Warfare 2 安装,它会利用逆向工程得到的磁盘数据格式,把该游戏的数据加载进自己独立的引擎。
这是零售版游戏的模组,还是一个全新的引擎?它是一个从零编写的引擎/运行时,不是应用到原始二进制文件上的补丁。它读取 MW2 的资产文件,但独立地重新实现了渲染、模拟和网络;零售协议、原始 ABI 和打过补丁的可执行文件都被明确排除在范围之外。
怎么构建并运行它?安装 docs/BUILD.md 中列出的系统软件包(Linux 上是编译器、ALSA、udev、X11/Wayland 头文件;macOS 上是 Xcode 命令行工具),日常运行用 profile.play 开发配置构建,发行版二进制文件则用 PROFILE=release。docs/WINDOWS.md 介绍了便携版 Windows 构建。
使用它必须已经拥有 Modern Warfare 2 吗?是的——把 IW4LGAMES 变量指向你现有的 MW2(或 MW3/Black Ops)安装所在的文件夹。IW4L 本身不附带任何游戏资产,而且它只读取这些文件,从不回写。
它稳定到可以正常游玩了吗?不能——目前还没有任何发行版,API、配置格式、缓存和网络协议在提交之间都会变化,所以所有人必须使用同一个构建。网络代码只用于事先约定好的内部联机测试,尚未用于公开大厅。
它能在哪些平台上运行?Linux、macOS(通过 wgpu 使用 Metal)以及一个便携版 Windows 构建。
它会自行向网络发送数据吗?不会——IW4L 不上报任何数据。诊断文件和缓存会留在你的磁盘上,除非你选择把它们附到错误报告中。
多人联网是怎么实现的?IW4L 使用自定义的点对点 UDP 线上协议,带有自己的增量压缩、可靠性和状态协调机制。基于 QUIC 的主服务器只负责帮各个节点互相发现,不转发游戏流量。
没有 DirectX 的情况下,原游戏的着色器怎么处理?零售版 D3D9 Shader Model 3 的着色器标记会被提前转换为 WGSL,因此运行时渲染完全不需要 DirectX。
这个项目实际上是谁写的?整个代码库由一个 LLM 编写,其构建过程包括用 Ghidra 对原始二进制文件进行逆向工程,并交叉参考 OpenAssetTools、IW4x 和 KisakCOD 等公开项目。
它能加载哪些游戏的资产?MW2 的区域文件可原生读取,MW3 和 Black Ops 的资产则会被转换为相同的内部 assetiw4 中间表示。
What are similar projects?benilla, luanti, ebiten, egui, engine, muguet, tidewater, SkyCraft
Creator
vladtrc
Size
10.5 MB
Stars
1.1K
Updated
CommitOct 16
Age
1mo
Commits · 90 Days