acdream/docs/research/acclient_architecture_map.md

AC Client — Complete Architecture Map

Sources used:

• docs/research/acclient_function_map.md — 70+ decompiled function addresses
• docs/research/acclient_animation_pseudocode.md — full animation system pseudocode
• docs/research/2026-04-12-movement-deep-dive.md — movement cross-reference
• references/ACE/Source/ACE.Server/Physics/ — ACE's C# physics port (read directly)

---

System Overview (dependency graph)

PhysicsEngine
  └─ iterates PhysicsObj list → update_object()

PhysicsObj (root entity)
  ├─ Position             (ObjCellID + AFrame)
  ├─ CurCell              (ObjCell ptr)
  ├─ CurLandblock         (Landblock ptr)
  ├─ PartArray            (skeleton + animation)
  │    ├─ Setup           (geometry: GfxObj parts, spheres, BSP)
  │    ├─ Sequence        (animation playback state machine)
  │    └─ MotionTableManager (transition resolver)
  ├─ MovementManager
  │    ├─ MotionInterp    (raw→interpreted motion state machine)
  │    └─ MoveToManager   (pathfinding / move-to target)
  ├─ PositionManager      (sticky/constraint)
  ├─ WeenieObject         (game-logic bridge — callbacks into WorldObject)
  ├─ Children / Parent    (attachment hierarchy)
  └─ ShadowObjects        (multi-cell presence)

Cell hierarchy (ObjCell subtypes):
  ObjCell (abstract base)
  ├─ SortCell             (has a BuildingObj for building collision)
  │   └─ LandCell         (outdoor cell: 2 terrain polygons, water)
  └─ EnvCell              (indoor/dungeon cell: portals, static objs, visibility list)

Terrain hierarchy:
  LandblockStruct         (raw height/terrain arrays, polygon list, SWtoNEcut flags)
  └─ Landblock            (8x8 grid of LandCells, static object list)
      └─ LandCell[64]     (per-cell collision polygon pair)

---

1. PhysicsObj — Root Physics Entity

ACE file: PhysicsObj.cs Decompiled: chunk_00510000.c, chunk_00500000.c — base at 0x510000

Data owned

Field	Type	Decompiled offset	Purpose
ID	uint	—	Object identity (GUID)
Position	Position	—	ObjCellID + AFrame (origin + quaternion)
CurCell	ObjCell	—	Current home cell
CurLandblock	Landblock	—	Current landblock
State	PhysicsState	+0xA8	Bitmask: Static, Hidden, Gravity, Ethereal, HasPhysicsBSP, Missile, Frozen...
TransientState	TransientStateFlags	+0xAC	Contact, OnWalkable, Sliding, Active, CheckEthereal...
Elasticity	float	+0xB0	Bounce coefficient
UpdateTime	double	+0xD8	LastUpdateTime for delta accumulation
Velocity	Vector3	+0xE0/E4/E8	World-space velocity (m/s)
Acceleration	Vector3	+0xEC/F0/F4	World-space acceleration (gravity = -9.8 Z when Gravity flag set)
Omega	Vector3	+0xF8/FC/100	Angular velocity
WeenieObject	ptr	+0x12C	Callback bridge into game logic
ContactPlane	Plane	—	Ground contact plane from last collision
SlidingNormal	Vector3	—	Surface normal during slide
CachedVelocity	Vector3	—	Velocity between position samples (for rendering)
PartArray	PartArray	—	Skeleton and animation state
MovementManager	MovementManager	—	Owns MotionInterp + MoveToManager
Children / Parent	ChildList / PhysicsObj	—	Attachment tree
ShadowObjects	Dict<uint, ShadowObj>	—	Per-cell presence records
CollisionTable	Dict<uint, CollisionRecord>	—	Active obj-obj collision records
Scale	float	—	Uniform scale factor

Behavior (key methods)

Method	Address	What it does
update_object()	0x515020	Per-frame entry: computes deltaTime, calls UpdateObjectInternal in fixed-step loop (MaxQuantum slices)
UpdateObjectInternal(quantum)	—	Calls UpdatePositionInternal → transition() → SetPositionInternal. Also calls PartArray.HandleMovement, MovementManager.UseTime, PositionManager.UseTime
UpdatePositionInternal(quantum)	0x513730	Calls PartArray.Update (animation frame advance) → PositionManager.AdjustOffset → builds newFrame → calls UpdatePhysicsInternal
UpdatePhysicsInternal(quantum)	0x5111D0	Euler: pos += vel*dt + 0.5*accel*dt²; applies friction; clamps max velocity (50.0)
calc_acceleration()	0x511420	Sets gravity (-9.8 Z) when Gravity flag set
set_velocity()	0x511EC0	Stores velocity, clamps to MaxVelocity
set_local_velocity()	0x511FA0	Body→world transform then set_velocity
set_on_walkable()	0x511DE0	Sets/clears OnWalkable transient flag
report_collision_start()	0x511560	Fires WeenieObj.HandleEnvironmentCollision
report_collision_end()	0x513AC0	Fires WeenieObj.HandleCollisionEnd
handle_obj_collision()	0x513B60	Obj-obj dispatch → WeenieObj.HandleCollisionStart or HandleMissileCollision
handle_collision()	0x515280	Elasticity bounce response
update_animation()	—	Animation-only update path (for entities that animate but don't move)
UpdateAnimationInternal(quantum)	0x5111D0 area	PartArray.Update(quantum) → set_frame() → PartArray.HandleMovement()
DestroyObject()	—	leave_cell → remove_shadows_from_cells → leave_world → exit_world
DoMotion(motion, params)	—	Routes through MovementManager.PerformMovement
DoInterpretedMotion(motion, params)	—	Routes through PartArray.DoInterpretedMotion

Dependencies

• Calls INTO: PartArray, MovementManager, PositionManager, WeenieObject (vtable callbacks), ObjCell (via transition), Transition
• Called BY: PhysicsEngine.update() (top-level loop)

---

2. PartArray — Skeleton + Animation Frame State

ACE file: PartArray.cs Decompiled: (embedded within CPhysicsObj chunk)

Data owned

Field	Type	Purpose
State	uint	Bitmask (HasPhysicsBSP = 0x10000)
Owner	PhysicsObj	Back-pointer
Sequence	Sequence	Animation playback state machine
MotionTableManager	MotionTableManager	Transition resolver (wraps MotionTable)
Setup	Setup	Dat resource: GfxObj parts, sphere collision shapes, BSP
NumParts	int	Part count
Parts	List<PhysicsPart>	Individual mesh parts (each has a Position)
Scale	Vector3	Part-level scale
LastAnimFrame	AnimationFrame	Most recently computed pose

Behavior

Method	What it does
CreateMesh(owner, setupDID)	Factory: loads Setup from dat, creates parts, sets placement frame 0x65
CreateSetup(owner, setupDID, createParts)	Full creature setup factory
Update(quantum, ref offsetFrame)	Calls Sequence.Update(quantum, ref offsetFrame) — advances animation, accumulates velocity
SetFrame(frame)	Applies AFrame to all Parts
HandleMovement()	Calls MotionTableManager.CheckForCompletedMotions()
DoInterpretedMotion(motion, params)	Routes into MotionTableManager.DoInterpretedMotion
AddPartsShadow(cell, count)	Registers all parts into a shadow cell (multi-cell presence)
AnimationDone(success)	Notifies MotionTableManager that a one-shot completed

Three PartArray creation factories

1. CreateMesh — simple static mesh (no animation MotionTableManager)
2. CreateParticle — particle emitter (special Setup, no skeleton)
3. CreateSetup — full creature (has MotionTableManager + Sequence)

---

3. Sequence — Animation Playback State Machine

ACE file: Animation/Sequence.cs Decompiled struct: chunk_00520000.c (FUN_00526110, FUN_005261D0, FUN_00525EB0)

Data owned

Sequence {
  AnimList           LinkedList<AnimSequenceNode>  // pending animation queue
  FirstCyclic        LinkedListNode<AnimSequenceNode>  // marks start of looping section
  CurrAnim           LinkedListNode<AnimSequenceNode>  // currently playing node
  Velocity           Vector3    // accumulated linear velocity from animation
  Omega              Vector3    // accumulated angular velocity
  HookObj            PhysicsObj // entity to fire events on
  FrameNumber        float      // current fractional frame position
  PlacementFrame     AnimationFrame  // static pose when no animation active
  PlacementFrameID   int
  IsTrivial          bool       // optimization: skip update if idle
}

Decompiled layout (raw offsets in AnimNode / Sequence structs):

Sequence +0x04  = listHead     (AnimNode* front)
Sequence +0x08  = listTail     (AnimNode* back)
Sequence +0x0C  = current      (currently playing ptr)
Sequence +0x10..0x24 = linearVelocity + angularVelocity (3+3 floats)
Sequence +0x28  = hasCallback
Sequence +0x30  = framePosition (double)
Sequence +0x38  = activeNode
Sequence +0x3C  = overrideFrame

AnimSequenceNode (ACE) / AnimNode (decompiled)

AnimNode (28 bytes = 0x1C) {
  vtable*      // AnimData vtable
  next*        // forward link in doubly-linked list
  prev*        // backward link
  frameCount   // total frames in this animation
  speedScale   // playback speed multiplier (negative = reverse)
  startFrame   // inclusive start (swap with endFrame when speedScale < 0)
  endFrame     // inclusive end
}

Behavior (key methods)

Method	Address	What it does
Update(quantum, ref offsetFrame)	—	Calls update_internal(frameRate, ...)
update_internal(frameRate, ...)	0x5261D0	Core per-frame loop: advance framePosition by rate*dt; fire frame-trigger events; call advance_to_next_animation on boundary
advance_to_next_animation(...)	0x525EB0	Pops exhausted node; loads next; seeds new framePosition from GetStartFramePosition
AppendAnimation(node)	0x526110	Push AnimNode onto pending list tail
GetCurrAnimFrame()	—	Returns CurrAnim.get_part_frame(frameNumber) or PlacementFrame
clear_animations()	—	Empties AnimList, resets CurrAnim
clear_physics()	—	Zeros Velocity + Omega
is_first_cyclic()	—	True if at or before the FirstCyclic marker (idle check)
CombinePhysics(vel, omega)	—	Adds to Velocity + Omega accumulators

Frame position arithmetic

• Forward (speedScale > 0): framePosition advances from startFrame toward endFrame+1
• Reverse (speedScale < 0): framePosition advances from endFrame+1-epsilon toward startFrame
• Boundary: when floor(framePosition) > endFrame (forward) or < startFrame (reverse), node is exhausted; advance_to_next_animation is called with remaining time
• Events: at each whole-frame crossing, frame-trigger events fire (FireApproachEvent forward, FireLeaveEvent reverse)

---

4. MotionInterp — Motion State Machine

ACE file: Animation/MotionInterp.cs Decompiled: chunk_00520000.c (FUN_00528xxx, FUN_005293xx)

Data owned

Field	Type	Decompiled offset
WeenieObj	WeenieObject	+0x04
PhysicsObj	PhysicsObj	+0x08
RawState	RawMotionState	+0x14 — wire format: ForwardCmd, SidestepCmd, TurnCmd, speeds, HoldKey
InterpretedState	InterpretedMotionState	+0x44 — resolved state after interpretation
CurrentSpeedFactor	float	—
StandingLongJump	bool	+0x70
JumpExtent	float	+0x74
MyRunRate	float	+0x7C
PendingMotions	LinkedList<MotionNode>	—

Constants

BackwardsFactor   = 0.65
MaxSidestepRate   = 3.0
RunAnimSpeed      = 4.0
RunTurnFactor     = 1.5
SidestepAnimSpeed = 1.25
SidestepFactor    = 0.5
WalkAnimSpeed     = 3.12

Behavior

Method	Address	What it does
PerformMovement(mvs)	0x529A90	Top-level dispatch (switch on MovementType 1-5)
DoMotion(motion, params)	0x529930	Raw motion command → adjust_motion → DoInterpretedMotion
DoInterpretedMotion(motion, params)	0x528F70	Core: contact_allows_move check → PhysicsObj.DoInterpretedMotion → add_to_queue → InterpretedState.ApplyMotion
StopInterpretedMotion(motion, params)	0x529080	Stop specific interpreted motion
StopMotion(motion, params)	0x529140	Stop specific raw motion
StopCompletely()	0x528A50	Reset to Ready/idle, clear all pending
adjust_motion(motion, speed, holdKey)	0x5287F0	Apply speed adjustments for run/walk/strafe
apply_raw_movement()	0x5293F0	Convert RawMotionState → InterpretedMotionState
apply_current_movement()	0x529210	Set physics velocity from InterpretedState
get_state_velocity(motion)	0x528960	Compute velocity for current motion (calls WeenieObj.InqRunRate)
contact_allows_move(motion)	0x528DD0	Slope angle check: can we move in this direction given terrain normal?
jump(params)	0x529390	Initiate jump sequence
jump_is_allowed(extent)	0x528EC0	Full jump permission check
get_leave_ground_velocity()	0x528CD0	Compute 3D launch vector
LeaveGround()	0x529710	Called when becoming airborne; resets jump state
HitGround()	0x5296D0	Landing handler; fires WeenieObj landing callbacks

Motion command bit flags (from PerformMovement — 0x523400)

Bit 31 set  (int < 0):       STANCE CHANGE — transition to new stance/style
Bit 30 set  (0x40000000):    CYCLE MOTION  — looping (Walk, Run, TurnLeft...)
Bit 28 set  (0x10000000):    LINKED MOTION — one-shot that links back to cycle
Bit 29 set  (0x20000000):    SUBSTATE ANIM — play a substate override

---

5. MotionTable / MotionTableManager — Animation Data + Transition Resolution

ACE files: Animation/MotionTable.cs, Animation/MotionTableManager (implicit in PartArray) Decompiled: chunk_00520000.c (FUN_00521770, FUN_005231D0, FUN_005232B0, FUN_00523000, FUN_00523400)

MotionTable data (loaded from dat resource 0x09xxxxxx)

MotionTable {
  ID            uint
  DefaultStyle  uint            // default stance (e.g. NonCombat)
  StyleDefaults Dict<style, defaultSubstate>
  Cycles        Dict<(style<<16)|substate, MotionData>
  Modifiers     Dict<motionId, MotionData>
  Links         Dict<style, Dict<substate, MotionData>>
}

Each MotionData (= TransitionLink in decompiled) contains:

• animId — dat animation resource to play
• speedScale — playback speed multiplier
• startFrame, endFrame, frameCount
• Linear/angular velocity of the animation
• Chain of AnimNode entries (for multi-step transitions)

Transition lookup — FindBestTransition (0x5232B0)

1. Direct lookup: (fromStyle<<16 | substate) → (toStyle or substate)
2. Speed-sensitive variant: same but uses exact speed matching
3. Fallback via defaultMotionId
4. Fallback via defaultTransMap

The composite hash key encodes both states in a single uint, looked up via LookupTransitionNode (0x5231D0).

PerformMovement dispatch — FUN_00523400

1. Look up current animation ID for current state
2. Guard: already in this cycle? Early-out.
3. Branch on motion command type (stance/cycle/linked/substate):
   STANCE CHANGE:
     a. Find exit-substate transition → AddAnimationsToSequence
     b. Find enter-new-stance transition → AddAnimationsToSequence
     c. Update currentState
   CYCLE MOTION:
     a. Find exit-current-cycle transition (one-shot)
     b. Find enter-new-cycle transition (sets FirstCyclic marker)
     c. AddAnimationsToSequence for both
   LINKED MOTION:
     a. Find link animation
     b. Append after current FirstCyclic marker
   SUBSTATE ANIM:
     a. Find substate animation
     b. Append with override flag

AddAnimationsToSequence (0x523000):

• Applies linear/angular velocity from the TransitionLink to the Sequence
• Iterates the chain of AnimNode entries
• For each: BuildTempAnimNode → Sequence.AppendAnimation

---

6. Transition — Collision / Movement Resolution

ACE file: Animation/Transition.cs (note: namespace is Animation not Collision) Decompiled: chunk_00530000.c (FUN_005384E0, FUN_005387C0, FUN_00538180)

Data owned

Transition {
  ObjectInfo    ObjectInfo     // what's moving (state flags: IsPlayer, IsViewer, Ethereal...)
  SpherePath    SpherePath     // the swept sphere path from old→new position
  CollisionInfo CollisionInfo  // accumulates contact plane, sliding normal, hit objects
  CellArray     CellArray      // cells the sphere path passes through
}

SpherePath tracks:

• GlobalSphere[] — world-space sphere(s) representing the object's collision volume
• CheckPos — current position being tested
• CurPos — resolved valid position
• CurCell — resolved cell
• StepDown — flag for step-down terrain contact
• PlacementAllowsSliding — whether sliding is allowed

CollisionInfo tracks:

• ContactPlane — ground/wall plane
• SlidingNormal — lateral deflection normal
• CollidedWithEnvironment — hit static geo
• AddObject(obj, state) — record object collision

Key collision methods

Method	Address	What it does
FindValidPosition()	—	Main loop: sweep sphere through cells, test polygon collision
find_collisions()	0x5387C0	Iterates CellArray, calls cell.FindCollisions on each
collide_with_point()	0x538180	Point collision handler
AdjustOffset(offset)	—	Projects movement vector along contact/sliding planes
Sphere.slide_sphere()	0x538EB0	Slide along a surface
Sphere.land_on_sphere()	0x538F50	Step down to surface
Polygon.sphere_intersects_poly()	0x539500	Sphere-polygon contact test
Polygon.find_walkable_collision()	0x53A040	Returns edge normal for walkable surface
Polygon.find_time_of_collision()	0x539BA0/0x539DF0	Ray-plane-polygon t (sphere/cylinder variants)

Transition outcomes

TransitionState {
  Invalid  = 0  // bad input
  OK       = 1  // no collision / passthrough
  Collided = 2  // hit solid surface
  Adjusted = 3  // position corrected (slide/step)
  Slid     = 4  // sliding along surface
}

---

7. LandCell / EnvCell / SortCell — Cell Management

Class hierarchy

ObjCell (abstract base)
  ID, WaterType, Pos, ObjectList, ShadowObjectList
  ClipPlanes, VisibleCells, VoyeurTable
  → AddObject / RemoveObject
  → abstract FindCollisions(Transition)
  → abstract find_transit_cells(...)

SortCell : ObjCell
  Building  (BuildingObj — handles building collision + transit cell lookup)
  → FindCollisions: delegates to Building.find_building_collisions

LandCell : SortCell
  Polygons   List<Polygon>  // always exactly 2 (the two terrain triangles)
  InView     bool
  → FindCollisions: FindEnvCollisions (terrain polygon) → base (building) → FindObjCollisions
  → FindEnvCollisions: find_terrain_poly → ValidateWalkable

EnvCell : ObjCell
  CellStructure    CellStruct    // geometry from Environment dat
  Portals          List<CellPortal>
  StaticObjectIDs  List<uint>
  StaticObjectFrames List<AFrame>
  StaticObjects    List<PhysicsObj>
  VisibleCellIDs   List<ushort>
  VisibleCells     Dict<uint, EnvCell>
  Flags            EnvCellFlags
  SeenOutside      bool
  → PostInit: build_visible_cells + init_static_objects
  → FindCollisions: CellStruct BSP collision

ObjCell key fields

ID          uint    // cell ID: high 16 = landblock (0xXXYY), low 16 = cell index
                    //   outdoor: 0x0001..0x0040 (64 outdoor cells per LB)
                    //   indoor:  0x0100..0xFFFD (EnvCell IDs)
Pos         Position  // cell's own origin frame
ObjectList  List<PhysicsObj>  // entities currently in this cell

Cell ID conventions

outdoor cell: (blockX << 24) | (blockY << 16) | cellIndex   where cellIndex = 0x0001..0x0040
indoor cell:  (blockX << 24) | (blockY << 16) | cellIndex   where cellIndex = 0x0100..0xFFFD
special:      0xFFFF = "lost" / no cell

---

8. CLandBlock / CLandBlockStruct — Terrain

ACE file: Common/LandblockStruct.cs, Common/Landblock.cs Decompiled: chunk_00530000.c (0x530690, 0x531780, 0x531D10, 0x532A50, 0x532EB0, 0x532D10)

LandblockStruct (raw terrain data)

LandblockStruct {
  ID             uint
  TransDir       LandDefs.Direction
  SideVertexCount, SidePolyCount, SideCellCount  int
  WaterType      LandDefs.WaterType
  Height         List<byte>    // 9×9 = 81 height values (0..127 → 0..63.5 meters)
  Terrain        List<ushort>  // 8×8 = 64 terrain type codes (palCode)
  VertexArray    VertexArray   // computed vertices (9×9 = 81 positions)
  Polygons       List<Polygon> // computed polygons (8×8×2 = 128 triangles)
  SWtoNEcut      List<bool>    // per-cell split direction (64 entries)
  LandCells      ConcurrentDict<int, ObjCell>  // 64 outdoor cells
}

Key algorithms (decompiled addresses):

Method	Address	What it does
IsSWtoNECut(x, y)	0x531D10	Inner split test with 0xCCAC033 constants
ConstructPolygons()	0x532A50	Outer 8×8 loop using FSplitNESW formula
GetCellRotation / ConstructUVs	0x532EB0	PalCode computation for UV rotation
unpack()	0x532D10	Deserialize from dat stream
get_packed_size()	0x531F10	Returns 0xF4 (244 bytes)
AdjustPlanes()	0x532440	Normal accumulation + lighting
CalcCellWater()	0x532290	Water depth check

CRITICAL — terrain split formula:

The CORRECT render formula (from AC2D, confirmed by ACME ClientReference.cs):

bool FSplitNESW(DWORD x, DWORD y) {
    DWORD dw = x * y * 0x0CCAC033 - x * 0x421BE3BD + y * 0x6C1AC587 - 0x519B8F25;
    return (dw & 0x80000000) != 0;
}
// x = blockX * 8 + cellX (GLOBAL cell coordinates)
// y = blockY * 8 + cellY
// true = NE/SW split (SW corner → NE corner diagonal)

Landblock (manager)

Landblock {
  // manages the 8×8 grid of outdoor LandCells
  // static object list (from LandBlockInfo dat)
  // links to neighbor landblocks for cross-boundary movement
}

Key methods (decompiled):

Method	Address	What it does
Init / constructor	0x530690	Initialize landblock fields
release_all()	0x5307E0	Free all resources
init_static_objs()	0x531780	Load static objects from LandBlockInfo dat
release_visible_cells()	0x531000	Free cell data
grab_visible_cells()	0x5301E0	BFS neighbor expansion
add_server_object()	0x530650	Add entity to landblock

---

9. Position / ObjCell — Coordinate System

ACE file: Common/Position.cs

Position

Position {
  ObjCellID  uint     // which cell this position is in
  Frame      AFrame   // origin (Vector3) + orientation (Quaternion)
}

AFrame

AFrame {
  Origin      Vector3     // landblock-local XYZ (meters within landblock = 192×192m area)
  Orientation Quaternion  // WXYZ quaternion
  
  LocalToGlobal(pt)   // rotate point by orientation, add origin
  GlobalToLocal(pt)   // inverse: subtract origin, inverse-rotate
  Combine(a, b)       // concatenate two frames
  GRotate(omega*dt)   // apply angular velocity
}

Coordinate conventions

Landblock size:       192 meters × 192 meters (8×8 cells, each 24m × 24m)
Height range:         0..127 height units → 0..63.5 meters (scale × 0.5)
Cell terrain polygon: each cell has 2 triangles (SW or NE split)
Global origin:        (0,0) = SW corner of landblock grid
AC heading:           0 = facing west (-X), PI/2 = north (+Y), PI = east (+X)
Gravity:              Z-down, gravity = -9.8 m/s²

LandDefs (coordinate utilities) (0x5AAA30 area)

Method	Address	What it does
get_vars()	0x5AAA30	Set 8 coordinate constants
get_outside_lcoord()	0x5AABB0	Cell ID → world coord
AdjustToOutside()	0x5AAC70	Normalize position to outdoor coords
get_block_dir()	0x5AAB50	Quadrant → Direction enum

---

10. WeenieObject — Game Logic Bridge

ACE file: Common/WeenieObject.cs

Data owned

WeenieObject {
  ID                uint
  UpdateTime        double
  WorldObjectInfo   WorldObjectInfo   // weak reference to WorldObject
  IsMonster         bool
  IsCombatPet       bool
  Faction1Bits      FactionBits
  PlayerKillerStatus PlayerKillerStatus
}

Vtable callbacks (called FROM physics INTO game logic)

Vtable offset	ACE method	Called from physics when...
+0x30	InqJumpVelocity(extent)	Computing jump Z velocity
+0x34	InqRunRate()	Computing movement speed for entity
+0x3C	CanJump(extent)	Checking if jump is permitted
+0x4C	HandleCollisionEnd(obj)	Object collision ended
+0x50	HandleCollisionStart(obj)	Object collision started
+0x54	HandleMissileCollision(obj)	Missile hit entity
+0x58	HandleEnvironmentCollision(normal)	Hit static geometry

Key predicates

IsPlayer()    — ID in 0x50000001..0x5FFFFFFF
IsCreature()  — has creature WorldObject
IsMonster     — creature and not combat pet
IsPK()        — PlayerKillerStatus == PK

---

Per-Frame Update Order

Client entity update (static/NPC — update_animation path)

1. PhysicsEngine.update()
   └─ for each active PhysicsObj:
      └─ update_animation()
         ├─ compute deltaTime = now - UpdateTime
         ├─ while deltaTime > MaxQuantum (0.034s):
         │   └─ UpdateAnimationInternal(MaxQuantum)
         │       ├─ PartArray.Update(quantum, ref newFrame)
         │       │   └─ Sequence.update_internal(frameRate, ...)
         │       │       ├─ advance framePosition by rate*dt
         │       │       ├─ fire frame-trigger events
         │       │       └─ advance_to_next_animation on boundary
         │       ├─ set_frame(newFrame)          // update all parts' positions
         │       └─ PartArray.HandleMovement()   // check completed motions
         └─ UpdateTime = now

Moving entity update (player — update_object path)

1. PhysicsEngine.update()
   └─ for each active PhysicsObj:
      └─ update_object()
         ├─ compute deltaTime
         ├─ while deltaTime > MaxQuantum:
         │   └─ UpdateObjectInternal(quantum)
         │       ├─ UpdatePositionInternal(quantum, ref newFrame)
         │       │   ├─ PartArray.Update(quantum, ref offsetFrame)    // animation → root motion
         │       │   ├─ PositionManager.AdjustOffset(offsetFrame)     // sticky/constraint
         │       │   ├─ build newFrame = Combine(Position.Frame, offsetFrame)
         │       │   └─ UpdatePhysicsInternal(quantum, ref newFrame)  // Euler integration
         │       │       ├─ pos += vel*dt + 0.5*accel*dt²
         │       │       ├─ calc_friction
         │       │       └─ vel += accel*dt
         │       ├─ transition(oldPos, newPos)                        // collision resolve
         │       │   ├─ build SpherePath (swept sphere)
         │       │   ├─ find_transit_cells → CellArray
         │       │   ├─ for each cell: cell.FindCollisions(transition)
         │       │   │   ├─ LandCell: terrain polygon test → ValidateWalkable
         │       │   │   ├─ SortCell/BuildingObj: building BSP test
         │       │   │   └─ ObjCell: obj-obj collision
         │       │   └─ AdjustOffset → clamp to contact/sliding planes
         │       ├─ SetPositionInternal(transit)                      // apply resolved pos
         │       │   ├─ change_cell if needed
         │       │   └─ update ShadowObjects
         │       ├─ MovementManager.UseTime()                         // motion interp tick
         │       │   └─ MotionInterp.apply_current_movement()
         │       │       └─ set_local_velocity from InterpretedState
         │       ├─ PartArray.HandleMovement()                        // completed motion check
         │       ├─ PositionManager.UseTime()
         │       ├─ DetectionManager.CheckDetection()                 (server only)
         │       └─ TargetManager.HandleTargetting()                  (server only)
         └─ UpdateTime = now

2. Rendering (acdream-specific, AFTER physics):
   └─ For each PhysicsObj:
       ├─ PartArray.Sequence.GetCurrAnimFrame()  // get current pose
       ├─ apply bone transforms
       └─ submit to GPU

Animation-only entities (static NPCs, breathing creatures)

Use update_animation instead of update_object. Same inner loop but:

• No physics integration (no velocity/gravity)
• No collision testing
• No cell change detection

---

Entity Lifecycle

Creation (from CreateObject network message)

1. Network receives CreateObject (opcode 0xF745) 
2. Parse PhysicsDesc → position, state flags, scale, motion table ID
3. Parse WeenieDesc → name, type, weenie class
4. PhysicsObj.Create()
   ├─ PartArray.CreateSetup(owner, setupDID)   // load Setup dat resource
   │   ├─ load GfxObj parts (mesh + textures)
   │   ├─ load sphere/cylsphere collision shapes
   │   └─ set MotionTableManager (loads MotionTable dat resource)
   ├─ set_initial_frame(position.Frame)
   ├─ enter_cell(position)                     // attach to ObjCell
   │   ├─ CurCell = cell
   │   └─ cell.AddObject(this)
   ├─ make_moveable() if not static            // allocate MovementManager
   │   └─ MovementManager.Init(this, weenieObj)
   │       └─ MotionInterp.Init(this, weenieObj)
   ├─ set_default_script() if HasDefaultScript
   ├─ set_default_animation() if HasDefaultAnimation
   └─ StartTimer()                             // seed UpdateTime

Per-frame updates (see above)

Motion state change (from UpdateMotion / local input)

Client input / network:
  DoMotion(motion, params)
    └─ MovementManager.PerformMovement(RawCommand, motion, params)
        └─ MotionInterp.DoMotion(motion, params)
            ├─ adjust_motion (speed, hold key)
            ├─ DoInterpretedMotion(interpretedMotion, params)
            │   ├─ contact_allows_move check
            │   ├─ PhysicsObj.DoInterpretedMotion()
            │   │   └─ PartArray.DoInterpretedMotion()
            │   │       └─ MotionTableManager.GetObjectSequence()
            │   │           └─ MotionTable.get_link() → AddAnimationsToSequence()
            │   │               └─ Sequence.AppendAnimation(animNode)
            │   ├─ add_to_queue(contextID, motion, jump_error)
            │   └─ InterpretedState.ApplyMotion(motion, params)
            └─ RawState.ApplyMotion(motion, params)

Position update (from server UpdatePosition / AutonomousPosition)

Network: UpdatePosition (0xF748) or AutonomousPosition
  → SetPosition(newPos, SetPositionFlags)
      ├─ Validate cell ID
      ├─ AdjustPosition → find correct ObjCell
      ├─ ForceIntoCell or transition()
      └─ update_position()
          ├─ set all part positions
          └─ sync ShadowObjects

Cell transition (crossing landblock/cell boundary)

During transition():
  if transit.SpherePath.CurCell != CurCell:
    change_cell(newCell)
      ├─ oldCell.RemoveObject(this)
      ├─ CurCell = newCell
      ├─ newCell.AddObject(this)
      └─ (if crossing landblock boundary)
          ├─ CurLandblock.remove_entity(this)
          └─ newLandblock.add_entity(this)
    calc_cross_cells()   // update ShadowObjects for multi-cell presence

Destruction (from DeleteObject / leave world)

DestroyObject()
  ├─ leave_cell(false)    // cell.RemoveObject + clear ShadowObjects
  ├─ remove_shadows_from_cells()
  ├─ leave_world()        // notify landblock
  ├─ exit_world()         // notify ObjMaint
  └─ ObjMaint.DestroyObject()

---

System Dependency Matrix

System	Calls Into	Called By
PhysicsEngine	PhysicsObj.update_object / update_animation	Server tick loop
PhysicsObj	PartArray, MovementManager, PositionManager, WeenieObject, Transition, ObjCell	PhysicsEngine
PartArray	Sequence, MotionTableManager, Setup	PhysicsObj
Sequence	AnimSequenceNode (dat AnimData), frame trigger hooks	PartArray, MotionTableManager
MotionTableManager	MotionTable, Sequence.AppendAnimation	PartArray, MotionInterp
MotionTable	dat loader (DatLoader.FileTypes.MotionTable)	MotionTableManager
MotionInterp	PhysicsObj.DoInterpretedMotion, WeenieObject.InqRunRate	MovementManager
MovementManager	MotionInterp, MoveToManager	PhysicsObj
WeenieObject	WorldObject (game logic layer)	PhysicsObj (callbacks)
Transition	ObjCell.FindCollisions, Polygon, Sphere	PhysicsObj.UpdateObjectInternal
ObjCell/LandCell	Polygon, LandblockStruct	Transition, PhysicsObj.enter_cell
EnvCell	CellStruct (BSP), Portal list, static PhysicsObjs	Transition, Landblock
LandblockStruct	Polygon, VertexArray, LandDefs	LandCell, Landblock
LandDefs	(math utilities only)	LandblockStruct, Position, ObjCell
Position	AFrame	PhysicsObj, ObjCell, Transition

---

acdream Implementation Notes

What acdream currently has vs. what it needs

System	Status	Gap
Position / AFrame	Complete	None known
LandblockStruct	Complete (render side)	Split formula may still use physics formula — verify against AC2D formula
Terrain Z sampling	Broken	Needs per-triangle barycentric (not bilinear) using AC2D FSplitNESW formula
Sequence	Integrated (AnimationSequencer)	Need to verify boundary handling matches decompiled update_internal
MotionTable	Integrated (SetCycle)	Need to verify transition chain building (AddAnimationsToSequence)
MotionInterp	Not ported	Need to port DoMotion/DoInterpretedMotion → SetCycle/SetLinkedMotion call chain
Transition / Collision	Partially ported (CollisionPrimitives, PhysicsBody)	Not yet wired into per-frame update_object
Cell management	LandCell / EnvCell exist	No runtime cell transition logic
WeenieObject callbacks	Not ported	Server handles this; client side is game state queries only
Physics integration	Not done	Euler integration + gravity missing from client
Movement deduplication	Broken	Sends MoveToState every frame instead of on state change
AutonomousPosition	Missing	Not sent
Sequence counters	Zeroed	Must extract from CreateObject and echo back

Priority for B.3 / next phase

1. MotionInterp port — DoMotion → apply_current_movement → set_local_velocity: this is what drives physics velocity from animation state
2. Terrain FSplitNESW fix — swap to AC2D render formula, add per-triangle Z sampling
3. update_object per-frame loop — wire Transition into position update (already have CollisionPrimitives)
4. Cell transition — change_cell / calc_cross_cells when moving between cells
5. MoveToState deduplication — send once per state change, not per frame
6. AutonomousPosition heartbeat — every 1 second
7. Sequence counters — extract from CreateObject messages