OpenUT99-Plus
Unreal Engine 1, rebuilt from scratch
Loading...
Searching...
No Matches
Script objects and bytecode

Reader: tools/uscript.py. Covers Class, State, Function, Struct, Enum, Const, TextBuffer and every *Property declaration.

Verified (uobjects.py --sweep <UT99_DIR>): all of them byte-exact across the retail install, including 3,300 class objects, 20,052 functions and every function's bytecode (decoded token by token to exactly its declared in-memory size). Token meanings follow public UE1 documentation; byte-exact decoding of all 1.58 million tokens is the evidence that the operand layout below is right, not that each token's semantics are.

Strings anywhere in packages: compact-index length including the NUL; a negative length means UTF-16LE characters (seen in third-party cache packages).

Common prefixes

Non-class script objects start with the tagged property list (normally just None), then the fields below. Class objects (export class 0) start directly with the Struct fields.

Part Fields
Field super (object ref), next (object ref)
Struct Field + script text (object ref, a TextBuffer), children (object ref, first member), friendly name (name), line i32, text position i32, script size u32 (in-memory bytes), bytecode
State Struct + probe mask u64, ignore mask u64, label table offset u16 (in-memory offset of the first label entry, just after the 0x0C token; 0xFFFF = none), state flags u32 (0x2 = auto)
Class State + class flags u32, GUID (16 bytes), dependencies (compact count × (class ref, deep u32, script text CRC u32)), package imports (compact count × object ref), within (object ref), config name (name), default properties (tagged list)

Other script objects

Class Layout after the property list
Function Struct + native index u16, operator precedence u8, function flags u32, rep offset u16 if flags & 0x40 (net). Version 64+ only; no retail function is older
Const Field + value (string)
Enum Field + compact count × name
TextBuffer pos u32, top u32, text (string)
*Property Field + array dim u16, element size u16, property flags u32, category (name), rep offset u16 if flags & 0x20 (net), then type refs: Byte → enum; Object → class; Class → class, meta class; Struct → struct; Array → inner property; Map → key, value; FixedArray → inner + count u32 (unverified: none in retail)

Bytecode

The header's script size counts memory, where object references and names take 4 bytes; on disk they are compact indices, so the reader must decode every expression and count memory size until it matches. Operands per token:

Token Name Operands
0x00, 0x01, 0x02 local / instance / default variable object ref
0x04 return expr
0x05 switch u8 size, expr
0x06 jump u16
0x07 jump if not u16, expr
0x08 stop —
0x09 assert u16 line, expr
0x0A case u16 next (0xFFFF = default), expr unless default
0x0B nothing —
0x0C label table (name, u32 offset)… until name None
0x0D, 0x0E goto label, eat string expr
0x0F, 0x14 let, let bool expr, expr
0x10, 0x1A dyn array element, array element expr, expr
0x11 new 4 exprs
0x12, 0x19 class context, context expr, u16 skip, u8 size, expr
0x13, 0x2E meta cast, dynamic cast class ref, expr
0x16 end of function parameters —
0x17 self —
0x18 skip u16, expr
0x1B, 0x38 virtual call, global call name, params… 0x16
0x1C final call function ref, params… 0x16
0x1D, 0x1E int, float const 4 bytes
0x1F string const NUL-terminated bytes
0x20, 0x21 object, name const object ref / name
0x22, 0x23 rotator, vector const 12 bytes
0x24, 0x2C byte const, int const byte u8
0x25–0x28, 0x2A 0, 1, true, false, none —
0x29 native parm object ref
0x2D bool variable expr
0x2F iterator expr, u16
0x30, 0x31 iterator pop / next —
0x32, 0x33 struct ==, != struct ref, expr, expr
0x34 unicode string const u16 chars until 0
0x36 struct member property ref, expr
0x39–0x5F primitive conversions expr
0x60–0x6F extended native call u8 (index = (token − 0x60) × 256 + u8), params… 0x16
0x70–0xFF native call (index = token) params… 0x16

Execution (VM)

Engine: engine/vm.* (ADR 0006). A function is loaded into its in-memory form (references and names widened to 4-byte ints), so jump, case and skip offsets index it directly. All 20,052 retail functions and 996 states load; 27 of the 50,236 parameters and locals have types the VM does not hold yet (dynamic arrays, maps).

Behaviour Evidence
Function children lists parameters in declaration order, then the return value, then locals. Flags: 0x80 parameter, 0x10 optional, 0x100 out, 0x200 skip, 0x400 return value retail declarations, e.g. Core.Object.AddAdd_PreInt, Engine.TestInfo.SubTestOptionalOut
Native index → function: each native declaration in Core / Engine carries its index; its export name (Add_IntInt, InStr) names the operation, so natives are implemented by name 152 indexed natives in Core
0x18 skip (right operand of &&, \|\|, parameters flagged skip): the u16 counts the operand and the closing 0x16; when the left side decides, execution resumes after the call retail TestInfo.TestContinueWhile: size 10 = 9-byte operand + 0x16
0x05 switch evaluates the cases in turn (0x0A: u16 offset of the next case, 0xFFFF = default) and resumes at the first match; a case reached by falling through skips its value TestInfo.TestSwitch logs its success
Omitted optional parameters are 0x0B (or missing before 0x16) and start as zero TestInfo.TestOptionalOut logs its success
Objects: instance (0x01) and default (0x02) variables name the property declaration; a class's defaults are its super's plus its own tagged list (all 1,604 retail classes build them) TestInfo.TestStatic asserts default.xnum == 777
Context 0x19 / class context 0x12: object expr, u16 skip, u8 size, expr. The inner variable or call uses the context object; arguments and array indices are evaluated with the caller's self. A None context skips u16 bytes (counted after the size byte) and yields zero TestInfo.TestNullContext; synthetic test
Array element 0x1A: index first, then the array (any variable, also inside a context) retail TestInfo.TestX bytes; TestInfo.temp
Static array dimension is a u16; retail goes up to 16,384 (udemo.DemoPlaybackSpec.HideActors) sweep over all property declarations
States: a State's super is its parent state (extends, or the same-named state of the super class); flag 0x2 marks auto state. Calls (0x1B) look in the current state and its parents first, then the class chain; 0x38 (global) skips the state retail TestInfo states (CCAA extends AA → super AA); source of Fan2, Chest (auto state)
Label table entries: name (u32 in memory) + code offset u32, ended by a name whose text is None (packages hold several None names) all 996 retail states: every table offset follows a 0x0C
Actor.LatentFloat holds what is left of a latent Sleep: bots read markedItem.LatentFloat to decide whether to camp for a respawning item (at 0, every sleeping item looks about to respawn) Bot state Roaming source
Function flag 0x8 = latent (Sleep, FinishAnim, MoveTo...): state code stops at the call and continues after it on a later tick Engine native declarations
ForEach 0x2F: iterator native call (flag 0x4, e.g. AllActors 0x405), u16 offset of the loop's 0x30 pop. 0x31 returns to the body while items remain, else falls through; continue is 0x31 + a jump to the 0x30 retail TestInfo.TestContinueForEach bytes; its log matches its source
Object's native variables Class and Name are kept by the engine: scripts compare Item.Class == Class (inventory pickup queries); left at None, every pickup query answers "already have it" bots picked up nothing until they were filled
ForEach iterator natives may write several out parameters per item (TraceActors: actor, hit location, hit normal) Pawn.TraceShot source
Classes defined only in C++ (Core.Class, Engine.Sound) are imported but have no export anywhere map sweep: 292 such references
GotoState: EndState in the old state, BeginState in the new one, code from the label (default Begin) of the state or its nearest parent state with labels; 'Auto' picks the auto state public documentation; order unverified
Conversions 0x39–0x59 (e.g. 0x53 int → string, 0x55 float → string) public UE1 documentation; 0x55 with 6 decimals and the others' text formats are unverified

Retail checks (build/ut_script <UT99_DIR> Package.Class.Function [args]): Engine.Console.FormatFloat 1.2345 → "1.23", Botpack.TournamentScoreBoard.TwoDigitString 5 → "05", and Engine.TestInfo TestContinueWhile, TestContinueDoUntil, TestContinueFor, TestSwitch, TestOptionalOut run to the end with every assert passing and the log their source text predicts; so do TestStatic, TestQ, TestStructBools, TestX, TestNullContext, TestLimitor and PostBeginPlay. TestInfo.Tick runs until GetPropertyText (not implemented).

State sweep (ut_script <UT99_DIR> --states): all 1,604 classes spawn; 453 enter an auto state; none stops on an error.

World (map play)

Engine: engine/world.*, engine/world_ai.cpp, engine/world_mover.cpp. A map's actors become instances (class defaults, then the actor's own tagged properties); Level points at the first actor, the LevelInfo; editor Camera actors are dropped (they are PlayerPawns that never get ready, and would hold the match start). The game class (LevelInfo.DefaultGameType, else [Engine.Engine] DefaultGame) is spawned without events and set as Level.Game; then play begins, the game gets InitGame (what it spawns from here on gets its play events at once), then the map's actors and the game get PreBeginPlay, BeginPlay, PostBeginPlay, SetInitialState, phase by phase. Each tick: Level.TimeSeconds, Tick, timers, physics, Region (zone from the BSP leaf; on a change the old zone gets ActorLeaving, the actor ZoneChange while its region still names the old zone, then the new zone ActorEntered; pawns also FootRegion / HeadRegion with FootZoneChange / HeadZoneChange; a just-spawned actor's first region is set silently; PainTime counts down to PainTimer, which hurts pawns in pain zones such as slime; order unverified, checked by the scripts: Deck16's slime and Morpheus' VacuumZone now kill), animation, touching, sight (SeePlayer / EnemyNotVisible every 0.2 s: SightRadius, PeripheralVision, line of sight), state code. This order is unverified; the evidence is that the retail scripts then run cleanly: DMMutator needs its PostBeginPlay before the map's actors call CheckReplacement, and the GameReplicationInfo spawned in GameInfo.PreBeginPlay destroys itself unless Level.Game is already set.

Map sweep (ut_script <UT99_DIR> --maps 20): all 83 maps load, start DeathMatchPlus, add their bots, and run 20 s with no script error. 289 bots spawn, roam the path network (reach specs), pick up items by touching them, fall off ledges and land; they travel 1,764 units each on average (often stuck, see debt). No bot ends inside solid except one that spawns there (CTF-Coret's misplaced start). Physics: falling (zone gravity, terminal velocity, Landed on a normal with z ≥ 0.7, HitWall and slide otherwise), projectile, flying, rotating, a minimal walking; Trace, FastTrace, Move, SetLocation use the BSP (level.md). Combat runs on the retail scripts: bots see each other, attack, fire (instant-hit weapons through TraceShot → TraceActors, a ray against collision cylinders), take damage, die, score and respawn. Animation follows the mesh's sequences (AnimRate = rate × sequence rate / frames, finish at AnimLast = 1 − 1/frames, AnimEnd; public documentation, unverified). Movers run on the retail Mover script: the engine's part is PHYS_MovingBrush (9): InterpolateTo sets OldPos, PhysAlpha 0, PhysRate = 1 / seconds and bInterpolating; each tick the brush goes from OldPos toward BasePos + KeyPos[KeyNum] (rotation likewise), linearly or, for MV_GlideByTime, along 3t² − 2t³ (unverified curve); at the end bInterpolating clears and InterpolateEnd chains the keys; FinishInterpolation waits for it. Brushes block traces and moves (level.md). Walking sets Base to the mover stood on, else the LevelInfo on BSP floors (the bot script tests Base == Level), None when falling, with Detach / Attach / BaseChange and StandingCount; actors standing on a moving brush ride along; a blocking actor the brush would overlap gets EncroachingOn (true stops it). Walking into a mover sends Bump both ways and HitWall to the walker, where bots ask HandleDoor. Routes call the next step's SpecialHandling(Pawn) (bCanDoSpecial): LiftCenter sends a bot to wait at its exit, the lift's StandOpenTimed opens when the bot stands on it, FinishNotify → StopWaiting sends it on. Retail check: in DM-Deck16][ a bot placed at the bottom exit waits, rides the lift 532 units up and walks off at the top. Actors block each other when both collide with actors and each blocks the other's kind (bBlockPlayers toward a bIsPlayer pawn, else bBlockActors; unverified, inferred from the retail defaults: pawns block pawns, projectiles touch them); a blocked move sends Bump both ways. Still placeholders (see debt.md): combat aiming, sound.

Not yet: new, dynamic arrays, binary struct defaults (other than Vector / Rotator), state ignores, engine natives (actors, spawning, timers).

Numbers (retail System/*.u)

Measure Value
Classes 1,604
Functions 9,156 (383 flagged native, 241 with a native index)
Bytecode 1,533,034 bytes in memory
Tokens decoded (all packages) 1,577,527, 202 distinct values; 162,601 native calls ≥ 0x70, 20,511 extended native calls

Open

  • Semantics of each native function beyond the operators, string and math functions implemented in engine/vm.cpp.
  • Flag bit names (function, property, class, state flags).

Measured in the original

With our probe (ADR 0008; tools/probe/calibrate.py), on the 469f-rc5 Linux dedicated server, maps built with ut99-mapgen (floor z = 0; OU-Steps: lanes of steps 16–40 high, floor and step tops checked solid / empty in its BSP). A ProbePawn (radius 17, height 39, GroundSpeed 400) falls to the floor, then walks with a latent MoveTo 1,500 units ahead:

  • A walking pawn rests with its centre 43.8 above the floor: 4.8 above CollisionHeight (on step tops likewise: 59.7 on a 16 step).
  • It climbs steps up to 29 high, not 30 (heights tried: 16, 24, 28, 29, 30, 31, 32, 40). Our reading, not measured: a step of 25 counted from the 4.8 hover gives 29.8.
  • A non-player pawn whose Tick sets Acceleration does not move: velocity stays 0. Bots move through latent moves.
  • Map OU-Ramps (true slopes, 192 units long): it walks up 45.5° (floor normal z 0.7009), not 45.7° (0.6984); angles tried 30–60 and 44.5, 45, 45.3, 45.5, 45.7, 46. The walkable-floor limit is normal z 0.7 (45.57°), as the engine uses.
  • On a slope it cannot walk it still gets about 120 units up (45.7°: from 43.8 to 166.3; 60°: to 134.5) before it stops.
  • On a slope its centre stays about 21.8 above the surface under it (45°: 4.8 hover + 17, the radius): the cylinder collides with the BSP as a box, in the original as in ours.
  • Walking into a slope too steep to walk (45.7°, 46°), the original turns to falling (Physics 2) with its velocity along the slope (246, 245 a tick later), slides up while gravity slows it, stops (about 161–172 high, varying between runs) and slides back. Measured along that slide (46°, ticks of 0.056 s): right after the switch its speed along the slope is 347 (ours: 278), and it slows by 414 units/s² along the slope, split evenly between vx and vz (ours: about 683, the full zone gravity projected on the slope). 347 and 414 give the 104 units it rises.
  • Map OU-Air (calibrate.py air): a ProbeFaller spawned 1,800 up falls while a latent MoveTo pulls toward a point ahead, with AirControl 0, 0.05, 0.2, 0.35, 0.6, 1. It gets no horizontal acceleration at all while falling (vx 0 until it lands, then 400 walking), whatever its AirControl; gravity is 950 (vz −418.7 after 0.44 s). Ours gives the same. So air control (from a latent move) is not what makes the slide above differ. A latent move does not steer a falling pawn; air control does exist from the Acceleration a walk left (OU-Ledge below).
  • Map OU-Slide (calibrate.py slide): a ProbeDropper (no latent move) dropped on slopes too steep to walk (46, 50, 60, 70, 80°) slides down along the slope with a steady acceleration of 462, 516, 659, 799, 908 units/s² (median per-tick gain, ticks of 0.0553 s): the fraction 0.677, 0.710, 0.802, 0.897, 0.971 of all gravity along the slope (950 sin θ). It fits 1 / (1 + nz²), nz = cos θ the normal's z, within 0.003 at every angle; the mechanism behind it is not known. The engine applies that fraction while sliding; ours now gives 461, 515, 658, 799, 908.
  • Walking into a too-steep slope, the original keeps its walking velocity (400) for the tick of the switch to falling and starts the slide at 347 along the slope (46°); ours projects at once and starts at 278, so it gets to about 100 where the original gets to 171. Two simple rules (keep the speed; velocity from the displacement) do not fit; not modelled.
  • Map OU-Entry (calibrate.py entry: ProbePawns with GroundSpeed from WalkNNN PathNode tags walk into slopes 300 high). Speed along a 46° slope on the first falling tick, entering at 100 / 200 / 300 / 400 / 600: 54.6, 151.3, 259.7, 370.2, 586.2 (a projection would give 69.5 … 416.8); at 400 into 55°, 65°, 70°, 74°: 355.5, 271.4, 219.1, 170.6. Its direction is not along the slope (33° to 56° from horizontal on the 46° slope, depending on the entry speed): no simple rule found.
  • Walking into a face steeper than about 75° is a wall: no switch to falling, the pawn stays at the foot (75.5°, 76°, 78°, 80°). The limit moves between runs (one run: falls at 74.5°, not 75°; another: at 75°, not 75.5°); the engine uses normal z 0.263 (74.75°).
  • Our engine on these lanes, before the fixes below: at 75–80° it climbed the face to the top (the 4.8 hover was applied over the face the floor probe touched, lifting it every tick) and at 74.5° and 80° it stayed falling forever, wedged between floor and face. Now: a wall at 75° and steeper, stopped at the foot like the original (x 240.3 vs 238.9); at 74–74.5° it slides up a little and lands.
  • Map OU-Ledge (calibrate.py ledge): ProbePawns with bCanJump walk toward a goal on top of a ledge (box) 32–80 high (UpNNN PathNode tags raise the MoveTo goal). The original never jumps by itself. A walking pawn blocked by a wall gets HitWall (BSP walls too), as a bot does; there the probe calls PickWallAdjust, which returns True up to a 77 ledge (72.2 above its feet), False at 78 and up, and False while falling. The limit does not depend on JumpZ (UpNNNJMMM tags: 250, 325 and 400 all jump 77, not 78; at 250 it jumps 64–77 ledges it cannot clear and falls back). With CollisionHeight 50 (C17_50 tag suffix) it is still 77, not 78: a fixed height above the floor, not 2 × CollisionHeight.
  • Map OU-Wall (calibrate.py wall): a wall 200 high and 32 thick across the lane, the goal behind it. PickWallAdjust then adjusts sideways. Walls 40–46 wide (centred on the lane) give True, leaving the pawn's x and Destination 50 to its left (−y when facing +x) and 25 up (68.8 from 43.8); 48 wide and up give False. With the wall off to one side (46 wide, centre ±20) it picks the free side. With radius 25 (C25_39) the goal moves 66 aside, so the offset is 2 × radius + 16. Walls up to 66 wide pass, 70 not. Read as the box having to clear a distance to the side: 40–41 at radius 17, 58–60 at radius 25; the engine fits 2.25 × radius + 1.75 (unverified at other radii). Velocity and physics stay unchanged. Against a block 40 high (40 or 200 wide), where both would fit, it jumps (falling, Destination unchanged): the jump comes first. Ours (2026-11-14) gives the same in all nine lanes.
  • Map OU-Reach (calibrate.py reach, ProbeReacher, tags ReachX_Z_J, DZ for a point below): pointReachable for a point 400 ahead at standing height, on top of a block or on the floor below the pawn's platform. Without bCanJump (the Pawn default) it reaches climbs up to 29 (30 not: the step) and drops up to 24 (25 not). With it: climbs up to 52 (53 not; the jump's apex is 325² / 1900 = 55.6) and drops up to 118 (119 not). The limits do not follow JumpZ: with 250 and 400 (tag J above 1 sets it) it is still 52 up and 118 down; at 250 it even accepts a 40 climb its jump cannot clear. Bots play with bCanJump on and JumpZ 357.5 (seen in our VM). Measured with CollisionHeight 39 only. Ours (2026-11-14) gives the same in all twelve lanes. When True, it leaves the pawn falling with Velocity = GroundSpeed (400) toward Destination and JumpZ (325) up. The first falling tick starts from the step-up height (rest 43.8 + 25), and every lane leaves the floor at z 85.263 = 68.8 + 0.0551 × (325 + 272.66) / 2: falling moves by the tick's mean velocity (a drop from rest falls 52.36 / 2 × dt in its first tick). The wall takes the horizontal speed down to about 44; it then grows 5.6 per tick, 102 units/s² = AirControl 0.05 × AccelRate 2048: the walk's Acceleration stays while falling and air control applies it. Top z 124.3 in every jumping lane. Ours (2026-11-14): same jump / no-jump split, top 120–124.
  • Our engine running the same probe (--ours, 2026-11-14): steps identical (rest 43.9, climbs 29, not 30); walkable ramps identical to 0.2 since the trace uses leaf hulls (level.md; before, past a crest ours rose about 30 units too high). On the too-steep slopes ours slides up the same way; with the slide rule below it reaches about 100, not 171: its slide starts slower (see below).