Last updated: 2026-11-15. Phase: A (package loading) complete on retail data: every export byte-exact. B (C++ engine): textured BSP viewer, all retail maps load and render. C (gameplay) in progress: the retail game runs in our UnrealScript VM, bots play Deathmatch on every map, and one human player can join and play (ut_mapview --player); no HUD, sound or first-person weapon.
AGENTS.md agent entry point
LICENSE AGPL-3.0
README.md
CMakeLists.txt C++17 engine build (library ut, ut_dump, ut_script, test_engine)
engine/
upkg.{h,cpp} packages + tagged properties (port of tools/upkg.py, uprops.py)
config.{h,cpp} .ini parsing
vfs.{h,cpp} package lookup (Paths, cache)
packages.{h,cpp} loaded packages, cross-package references
texture.{h,cpp} Palette + P8 Texture -> RGBA
level.{h,cpp} Model (BSP), Level, surface triangles
script.{h,cpp} bytecode walker, class defaults
mesh.{h,cpp} LodMesh
vm.{h,cpp} UnrealScript VM (functions, interpreter, natives)
collision.{h,cpp} BSP solidity and swept-box traces
world.{h,cpp} map actors in the VM, play start, ticks, timers, physics, touching, animation, Actor natives
world_ai.cpp walking, path network, routes, latent moves (AI natives)
world_mover.cpp movers: brush collision, keyframe interpolation, bases, encroachment
world_player.cpp the local player: Login, input into PlayerPawn, its view
play_view.{h,cpp} live actors of a running world as triangles each frame (animated meshes, mover brushes)
lighting.{h,cpp} lightmap luxels, shadow bits, light colours, atlas
scene.{h,cpp} map -> texture batches, lightmap atlas, sky, mesh actors, player starts
render.{h,cpp} OpenGL 3.3 renderer (library ut_render)
png.{h,cpp} PNG encoder for screenshots
mapview.cpp ut_mapview: free-fly viewer, --shot, --check, --play
ut_dump.cpp summary / property counts / --deps
ut_script.cpp run a script function / auto state / map; --states, --maps sweeps
test_engine.cpp unit tests on synthetic data (ctest)
docs/ specs, ADRs, roadmap, AI layer (index: docs/README.md)
tools/
upkg.py Unreal package reader (header, names, imports, exports)
uprops.py tagged properties (generic object data)
utex.py Palette, Texture (mips, PNG preview)
usound.py Sound, Music (embedded WAV / IT / S3M / XM)
ufont.py Font (pages, glyph rectangles, 469 remap)
uscript.py Class, State, Function, Struct, Enum, Const, TextBuffer, *Property, bytecode
umodel.py Polys, Model (BSP, surfaces, lightmaps, zones), Level
umesh.py Mesh, LodMesh, SkeletalMesh, Animation (OBJ export)
uobjects.py dispatcher + sweep over all exports (exact / leftover / error / noreader)
uini.py .ini parsing, package lookup, --deps
compare_engine.py C++ vs Python on every package of an install
check_docs.py documentation checker
probe/ our UnrealScript probe (OUProbe) + calibrate.py: measures the original on calibration maps (ADR 0008)
test_*.py unit tests on synthetic data
| Subsystem | State |
| Package container | done, verified on all 396 retail packages |
| Tagged properties | done, verified on all 273,585 non-class exports |
| Palette, Texture, ScriptedTexture | done, byte-exact on all retail objects |
| FireTexture, WetTexture, WaveTexture, IceTexture | done (data); animation not decoded |
| Sound, Music | done, byte-exact |
| Font | done, byte-exact |
| Script objects and bytecode | done, byte-exact (token semantics from public docs) |
| Polys, Model, Level | done, byte-exact; indices and lightmap sizes cross-checked |
| Mesh, LodMesh, SkeletalMesh, Animation | done, byte-exact; LodMesh frame checked visually |
| Engine (C++) | ini + package lookup (0 missing dependencies); package, property, Model, class-default and LodMesh readers agree with Python on all 396 packages (compare_engine.py compares counts and end offsets per object, not every value); level viewer: textured BSP, baked lightmaps (colour model uncalibrated), sky zones, mesh actors (frame 0, full bright); all 83 maps load; ut_mapview MAP --play runs the match in the view (bots animated, movers moving, live actors full bright) |
| UnrealScript VM (C++) | functions load (all 20,052 retail); objects with class defaults (all 1,604 retail classes), instance / default variables, contexts (None skipped with a warning), structs, static arrays, casts; states (dispatch through the state, labels, GotoState, auto state, latent Sleep, tick); control flow, script and native calls, out / optional parameters, ≈ 140 operator, string and math natives; 13 retail TestInfo self-tests pass; --states sweep: every class enters its auto state, none stops on an error. No iterators or engine natives yet |
| World (C++) | all 83 maps load their actors, start DeathMatchPlus and run with no script error (--maps); timers, ForEach iterators, pawn list, spawn / destroy; physics against the BSP (falling, projectile, flying, rotating, walking with step-up) and BSP traces; touching; animation timing; bots spawn, roam the path network, pick up items, see and fight each other (instant-hit weapons through actor traces), die, score and respawn; a human player joins through Login and plays through the retail PlayerPawn script (world_player.cpp: input variables, PlayerInput / PlayerTick, PlayerCalcView); actors block each other (Bump); no sound |
| Network | not started |
python3 -m unittest discover -s tools # all tests
cmake -S . -B build && cmake --build build && ctest --test-dir build # engine build + tests
python3 tools/compare_engine.py <UT99_DIR> build/ut_dump # C++ vs Python, must say "0 differ"
build/ut_dump --deps <UT99_DIR> # must say "0 missing dependencies" (same as uini.py --deps)
build/ut_mapview <UT99_DIR> --check # every map loads: "83 maps, 0 errors"
build/ut_script <UT99_DIR> Engine.TestInfo.TestSwitch # run a script function: return value, out parameters, log
build/ut_script <UT99_DIR> --states # phase C meter: auto state of every class, missing natives ranked
build/ut_script <UT99_DIR> --run Package.Class [TICKS] # spawn, auto state, tick its state code
build/ut_script <UT99_DIR> --map MAP[?Key=Value...] [SECONDS [--player]] # play a map's script (options go to InitGame, e.g. ?mutator=Pkg.Class): errors and log ranked; UTVM_LOG=1 prints every log line; --player: a player plays a fixed 20 s, one line (moved, yaw kept while strafing, ammo, deaths, respawned)
build/ut_script <UT99_DIR> --maps [SECONDS] # every map: "0 failed", no errors, pawns travelled; inside solid (listed with the map): BioAmmo / UT_invisibility (map data), at most a few small dropped items or a lift rider
build/ut_mapview <UT99_DIR> MAP [--shot out/x.png] [--at x y z yaw pitch] [--lightmap out/lm.png] # drag to look, arrows, WASD fly
build/ut_mapview <UT99_DIR> MAP --play [--time S --follow --shot out/x.png] # the match running; F follows a bot
build/ut_mapview <UT99_DIR> MAP --player [--mouse-free] [--time S --shot out/x.png] # play the match (WASD, mouse, buttons fire, Space, Ctrl, 1-0); with --shot the scripted run's view
mkdir -p build && doxygen docs/Doxyfile # docs site into build/site/html (theme: clone doxygen-awesome-css v2.5.0 into docs/site/awesome, see .github/workflows/pages.yml)
python3 tools/check_docs.py # doc checks
python3 tools/probe/calibrate.py MAPGEN_DIR steps|ramps|air|slide|entry|ledge|wall|reach [--angles A,B] [--ours build/ut_script] # the original (and ours): steps / slopes a walking pawn gets over, air control, sliding, walking into steep slopes, jumping ledges, sidestepping walls, pointReachable limits (setup: DEVELOPMENT_GUIDE)
python3 tools/upkg.py FILE [--names|--imports|--exports]
python3 tools/uprops.py FILE OBJECT # properties of one export
python3 tools/uprops.py --sweep <UT99_DIR> # parse every export, counts per class
python3 tools/uobjects.py --sweep <UT99_DIR> # phase A progress: classes not yet byte-exact
python3 tools/uobjects.py FILE OBJECT # decode one export
python3 tools/utex.py FILE TEXTURE --png out/x.png # P8 preview
python3 tools/usound.py FILE OBJECT --out out/x.wav # embedded file
python3 tools/uscript.py --tokens <UT99_DIR> # bytecode token histogram
python3 tools/umesh.py FILE LODMESH --obj out/x.obj [FRAME]