Commit Graph
31 Commits
Author SHA1 Message Date
Brues 33a8000579 feat(model): scene:GetActorsInRadius, the nearest-unit collector's test
scene:GetActorsInRadius(x, y, z, radius) returns a table of the scene's
actors near a point, nearest first. It applies the test of the 1.12.1
client's nearest-unit collector (0x00494200, the enumeration callback
behind TargetNearestEnemy and its kin) to the scene's own actor list:

- A unit counts only when its scene node is drawn (0x006704C0: node not
  null and +0x94 clear). The scene's counterpart is a shown actor with
  a model; scene info actors without one (scene 4's "unwrapped",
  "wrapped", "player-rider") do not count.
- The distance is the squared difference of the two positions in all
  three axes, kept when it is not more than the squared radius
  (0x0049435B..0x0049436B: fcompp, test ah,0x41).
- The list is sorted by squared distance ascending, as the collector's
  compare (0x00494450) orders entries of one kind; ties keep creation
  order (stable sort).

Pure reads of the actor vector and positions; no engine call, no state
change.
2026-11-10 12:37:20 -06:00
Brues c8f9c23fa4 feat(model): scene:GetCursorRay, the world frame's pick ray
The world frame builds its pick ray in ScreenPointToRay (0x004813B0,
called by PickAtCursor 0x00481190): the cursor's fractions across and
up its rect, then UnprojectScreenPoint (0x007AD2C0), which reads the
device view and projection, builds the frustum corners and interpolates
the near and far planes, then the camera's eye added to both points
because the view leaves it out.

The scene does the same with the transforms it paints with: the cursor's
fractions across the paint's viewport (the frame's rect clamped to the
screen), CameraTransforms (the camera's CameraSetDeviceTransforms
0x007ADA40, fitted to the view insets) under SavedTransforms,
UnprojectScreenPoint, then the scene camera's eye. It returns the two
points in scene coordinates, or nothing when the cursor is off the
picture or the frame is hidden.

The world traces that ray with class 0x1000114, whose WMO face mask
(0x006A3839) is 0x84, the mask TraceSegment uses by default, and which
skips doodads as TraceSegment does. So GetCursorRay into TraceSegment is
the world's point pick on a scene.

CursorClip becomes CursorFraction (0 to 1) so both pick paths share it;
GetActorAtCursor maps the fractions into clip space itself, the same
arithmetic as before. Offsets.h gains FUN_UNPROJECT_SCREEN_POINT and
gx/Device.h a wrapper for it.
2026-11-10 12:27:43 -06:00
Brues be3c8a0a42 refactor(model): call the engine's math and read its constants live
The ModelScene mover and contact sweep carried their own copies of engine
code and data. They now use the client's.

Constants: every float the transcribed mover reads from 1.12.1's .rdata
(and the two fall-speed caps in .data, the 2pi the static initializer
fills at 0x00CF5D00) is an Offsets.h entry read where it is used, through
Game::Live<T>. Each value was checked against WoW.exe's bytes. The pooled
floats other modules already named for one use (0x00801360, 0x008026BC,
0x008029D4, 0x00803568, 0x008022CC, 0x00801620, 0x0080306C, 0x00801628)
are renamed by value, since the mover reads them too.

Leaf math: the pure geometry helpers the mover calls are now called, not
copied: DotVector3 0x00602630, PlaneFromTriangle 0x00637480,
PlaneDistanceAlongRay 0x006329E0, ClipPolygonByPlane(s/Except) 0x006318C0
/ 0x00631870 / 0x00632980, IntersectThreePlanes 0x00634FC0 and
PointToLineDistanceSquared 0x00634F40. Each is __fastcall with callee
cleanup and reads only its arguments and .rdata (Ghidra). Two stay
transcribed: FindNearestTriangleEdge 0x00634DA0 reads the client's facet
list at 0x00C4E534, and SelectBevelContactNormal 0x00636610 reads an
unwritten stack slot as an index when three bevels have no odd one out.

Wrappers: engine calls that several files cast themselves get one typed
home: M2.h (key-bone animation state, sequence info, base transform,
scene draw, model lights, the IsXAnimation tests, whose death test is
__stdcall and the rest __fastcall), gx/Matrix.h (the 0x007BxXXX matrix
helpers), gx/Device.h (render-state journal, state setters, transform
stacks, clear), Frame::Layout (DDC/NDC conversion), Texture::DeviceTexture,
Xml::ReadColor and Frame::Subclass's slot types.
2026-11-10 01:38:43 -06:00
Brues 248249c089 feat(model): ModelScene draws the world's sky behind its WMO
A scene with a WMO backdrop now clears its frame and draws its sky as
DrawWorldScene (0x00681070) does before its terrain and map objects:

- No interior group holds the camera and the camera is dry: clear to
  black (mask 3), then DrawSky (0x006D4940). The pass draws the stars,
  the sun disc, the white moon, moon02, the gradient dome, the clouds
  and the skybox slots, in the depth range [0.975, 0.98] of the device
  viewport, around the eye. The scene's view has no translation, as the
  world's has none, so the same pass fits.
- An interior group holds the camera: clear to the drawn fog's colour
  (light state +0x80) and draw no sky. Under liquid outside: the zone
  fog's colour.

The pass draws the world's sky objects, which BuildLightTable
(0x006D2260, from 0x006D4530 each world frame) makes from the world's
camera and light. The scene makes the light-derived parts again, as the
build makes them, then puts the world's back:

- the light state's heading (+0x30) from the scene camera's forward:
  atan2(y, x), or atan2(z, x) when x*x + y*y is not above the double
  0.0001 (0x00811658), plus the float 2pi (0x0080295C) below 0;
- for a backdrop in a map, that map's light at the scene camera
  (BuildMapLight, as the outdoor water already takes it) in the live
  table (0x00CE9C0C), with no screen tint (+0x44, the player's) and the
  override and slots (+0x54..+0x6B) cleared;
- the dome's colours (ColourSkyDome 0x006D0F50, 5 x columns + 2 at
  [0x00CE99A0+0x14]);
- colour band 9 (record +0x20) into the sun disc and white moon
  (0x00CE9858, +0x0C, 0x20 apart);
- the skybox slots (0x006D2C79): each {LightSkybox id, weight} pair at
  record +0x78 with an id, a weight above 0 and an id below the
  LightSkybox count (0x00CE9DB4) interns its row's path (InternSkybox
  0x006D4640) into slot +0x5C, weight +0x64. A null row, which the
  engine would read through, is skipped.

The pass runs only while the sky flag (+0x198) is set and the dome has
its colours, so a scene at the glue screen keeps a plain clear. World
stack 8 is identity around the pass and the render states are pushed.

The camera claim (ClaimCameraMapObject 0x006821F0) now runs for every
WMO, not only for those with their own fog. The world claims the camera
whatever the fog, and its liquid probe reads the claim.

Not done: the cloud texture stays the world's, because the world builds
it a band at a time from its own light. From inside, the world also
draws the sky when its portal walk (WalkPortals 0x006B41C0) reaches an
exterior group; the scene does not. The sun and moon glares (0x006D48C0)
are not drawn.
2026-11-09 16:49:40 -06:00
Brues 25292427d6 feat(model): ModelScene doodads are solid to moving actors
A scene's WMO doodads now block the mover and SweepCollider as the
world's doodads block a character.

The facet query follows the world gather for a map object
(GatherMapObjectFacets 0x006AAAB0) over the scene's one WMO: the
placement's box (CMapObj::GetBoundingBox 0x006A4420 through the
placement) must touch the query box; then the group faces as before;
then each group, in index order as CreateGroupDefs (0x00695960) links
them, whose MOGI bounds through the placement touch the box gives its
doodads by GatherDoodadFacets' rules (0x006ABC40): each doodad once per
query (the s_mapQueryId stamp, advanced by GatherWorldFacets 0x006AA8B0),
its collision box (+0x14C) tested closed. A group not yet parsed or a
doodad whose model file has not loaded fails the query, as in the
client, and the facets gathered so far stay in the list.

The doodad's facets transcribe CM2Model::GatherCollisionFacets
(0x007137C0) into our own code, so the client's facet list and the
model's vertex caches are not touched: the M2 collision mesh (shared
data +0xF0 to +0x100) through the doodad's matrix (0x007BCA80, the same
arithmetic as our 0x007BCC60 transform), a triangle kept unless all
three vertices lie past one face of the box, its plane from the mesh
normal turned by the matrix rows normalized above 2^-22, d = -n.v0.

A doodad's bounds now follow SetDoodadDefBounds (0x006952A0) and are set
when its model file loads (0x007103D0 with 0, 0, as the pending-def
finish 0x00698C50 sets the def's loaded bit): the sphere and the
collision box (0x00713700) through TransformBox (0x006DC540). A shared
doodad sits in each of its groups' lists, as CreateGroupDoodadDef
(0x00694E90) returns the existing def.
2026-11-09 16:10:57 -06:00
Brues 7e7f6f0bf6 feat(model): ModelScene SweepCollider on the client's contact sweep
scene:SweepCollider(feetX, feetY, feetZ, radius, height, moveX, moveY,
moveZ) sweeps a body to its first contact with the scene's WMO and
returns where its feet stop and the normal of the facet it met. It is a
ClassicAPI extension.

The sweep is the client mover's own, transcribed in SceneContact.cpp
one function at a time: CMovement::SweepVolume 0x00632BA0, with the
volume's planes and vertices (0x00631440, 0x00631BE0), the polygon clip
and its 1/720 band (0x006318C0, 0x00631870, 0x00632980), the swept face
prisms (0x00632460, 0x00632F80, PlaneFromTriangle 0x00637480), the
contact distance (0x006329E0, 0x00632830), the nearest facet per face
(0x00632700), the bevel faces and the band rule (0x00632280), and the
facet gather with its cached box (0x00631E70). The arithmetic keeps the
client's 53-bit sums, float stores and operand order, so a body meets a
face where the client's mover would. The body is the client's volume:
a square box over a downward point at the feet, sides at 61.6 degrees.

The facets come from the same WMO box query as the decals (CollectBox,
TestMapObjectBox 0x006AD330, class 0x100111), read out of the facet
batches up to each batch's triangle count (+0x16, the loop bound of the
facet emitter 0x00671CC0). Each facet is built as that emitter builds
it on its SSE path: the vertices through the batch matrix, the normal
(v1 - v0) x (v2 - v0) scaled by rsqrtss, d = -n.v0. So a face blocks
only from its front, as in the world.

Safety: nothing here calls or patches the client's mover. Its facet
lists (0x00C4E52C, 0x00C4E564) and cached box (0x00C4E5A0) are never
read or written; the sweep keeps its own list and box per call. The
swimmer and hover branches of 0x00632BA0 are not taken, since a scene
body has neither flag.
2026-11-09 14:08:39 -06:00
Brues a6b5982b64 feat(model): ModelScene GetLiquidAtPoint
scene:GetLiquidAtPoint(x, y, z) returns the liquid of the scene's WMO at
a point, its type (0 water, 1 ocean, 2 magma, 3 slime) and the height of
its surface, found the way the world finds a unit's. The group is the one
whose face lies nearest below the point, the probe AttachEntityToGround
(0x006A8A20) runs from a unit; CMapObjGroup::LiquidHeight (0x006B9F10)
then answers at the point in WMO space. It reads the MLIQ tile under the
point and answers only below the surface (water 0.01 above it); a group
whose MOGP liquid word is set answers that type everywhere with FLT_MAX,
returned as a nil surface. The type is masked with 3, as the camera's fog
reads the same answer, and the surface goes back to scene space through
the placement.

With it a scene can run the client's swim decision (0x006030C0): swim
once the surface stands more than 0.75 of the collision height over the
feet, stop below that less 1/36 yard.
2026-11-09 13:23:25 -06:00
Brues 398b773fc4 feat(model): ModelScene TraceSegment camera face set
TraceSegment takes an optional camera flag that traces the faces the
world's camera collides with. The camera solver (0x0050E570) traces with
class 0x100171, whose mask builder (0x006A3839) gives face mask 0x82:
detail faces block it and the no-camera-collision faces (MOPY 0x02) do
not, where the line-of-sight set (0x84) is the other way round. The flag
passes mask 2 to CMapObjGroup::IntersectSegment (0x006B92B0) in place of
4; the call ORs in the visited bit.

With it an orbit camera can do the solver's boom sweep: trace from the
target toward the eye and stop 1/9 yard (0x00808A04) short of the hit.
2026-11-09 13:07:14 -06:00
Brues aed68f24b8 feat(model): ModelScene TraceSegment and a sound listener actor
scene:TraceSegment(start, end) returns the first face of the scene's WMO
on a segment: the hit point, the face's unit normal turned toward the
start, and the fraction. It is the scene's per-group trace (Nearest,
TraceMapObjectsNearest 0x006A8840 over the one WMO) with face mask 4,
which CMapObjGroup::IntersectSegment (0x006B92B0) widens to 0x84: every
face but the detail faces, the set the world's line of sight and the mover
test (class 0x100111 builds the same mask). The normal is crossed from the
hit triangle as CMapObj::IntersectSegment (0x006A37B0) reads it: facet
batch 0's first three indices into its vertices, read right after the
group's call, then turned into scene space by the placement. Only loaded
groups answer. The class word moves to Offsets.h as WORLD_TRACE_CLASS_LOS,
which LineOfSight.cpp used as a local constant.

scene:SetSoundListenerActor(actor) hears the scene's sounds at an actor.
The world's listener (0x00482EA0) stands at the unit the player drives
while SoundListenerAtCharacter is on: its position raised by scale times
box height (+0x90 * +0xBC), facing the unit's facing with z 0, up
(0, 0, 1); otherwise at the camera. The scene mirrors both branches, with
the listener actor in place of the unit and the scene camera in place of
the world's.
2026-11-09 12:49:03 -06:00
Brues 316bb0dc95 feat(model): ModelScene outdoor WMO water takes its map's light
A 1.12.1 WMO's exterior water colours its vertices from the world's light
table: the deep river colour (colour band 17, table +0x40) in
DrawGroupLiquid's exterior arm, and the river alphas (LightParams columns
5 and 6, +0x68 / +0x6C) that BuildGroupDepthRamp (0x006B6B60) ramps
between. BuildLightTable (0x006D2260) makes that table each frame at the
camera from the current map's light list (0x006D6170: the map's Light
rows, slot 0 the one at the origin, else Light id 1): slot 0 gathered at
the half-minute of the day (GatherLightRecord 0x006D64D0 on the
LightParams of reference 0, or 1 under water), then each area light the
eye is inside of blended in farthest first by its falloff
(BlendAreaLights 0x006D2D00, OverblendLightRecord 0x006D30E0); in magma
LightParams 7, in slime 6. A scene's WMO showed the player's zone.

The backdrop now knows its map: SetWorldModelByMapID's, or a new
optional mapID argument to SetWorldModel. With one, the scene builds
that map's table at its own camera through the engine's gather and blend
(the storm blend, which follows the player's weather, is left out) and
puts its three water fields into the world's table only while its
liquids draw, then puts the world's back.
2026-11-09 11:51:32 -06:00
Brues 8ff1549b83 feat(model): ModelScene WMO light eases and lights spell models
An actor's light in the scene's WMO now changes the way a 1.12.1 unit's
entity light does. AnimateMapEntityLight (0x0069E770) moves each byte of
the ambient toward its target by max(1, trunc(2.0 x dt x 255)) per tick.
It moves the intensity, which scales the directional light in
ApplyMapLighting (0x006A7300), by 3.3333 x dt. The bake
(BakeMapEntityGroupLight 0x0069E4C0) writes the ambient target, not the
ambient. The target intensity is 1.0 indoors and 2.5 (0x00810A68) on an
exterior group. A new node starts at 1.0 with the day ambient
(0x00670DB0). Outside, with no channel moving, the ambient follows the
day's. World::Settle now takes the frame's elapsed time and eases each
tick, and places the node again only when the model moved.

A missile in flight gets its own entity light node, as the world gives
one (CreateLightObjectB 0x00671010 from 0x0061E655, placed by
AttachEntityToGround). Impact models left behind get one too. Each model
releases its callback back to the frame's before the light goes.

LightChildren now copies the parent model's own lighting callback pair
(+0x3BC / +0x3C0), so a nocked arrow and a stuck missile are lit like
the actor that holds them, not with the frame's flat light.
2026-11-09 11:51:32 -06:00
Brues 4294a2bbfa feat(model): ModelScene WMO fog follows the camera into liquid
The camera fog now asks the liquid around the camera as the world does.

CameraEnvironment (0x006809C0) probes at the camera's x and y and the
lowest z of the camera and the four near corners of its frustum (a
corner at or below the lowest, or NaN, replaces it); with the claim it
asks LiquidHeight (0x006B9F10) of the claim's first group in model
space, the type starting as 0xF. The scene keeps the drop below the eye
from the frustum volume its WMO draw builds.

BuildSceneFog (0x006CEE30) picks the target from it: water or ocean
take the underwater sub-record (+0x24); magma with fog flag 0x100 and
slime with 0x10 take it too and make the zone fog the target; magma or
slime without the flag take the zone fog as the target. GetCameraInteriorFog
now blends both sub-records and keeps the flags of record 0 or of the
nearest candidate. With the camera in liquid the paint draws the WMO's
liquids after the translucent models, as the frame does (0x004836D6).

Not mirrored: the zone fog the camera's liquid makes the target changes
only the WMO, its doodads and the indoor actors, not every model; a
scene has no terrain, so outside the WMO the camera is always dry.
2026-11-09 11:51:31 -06:00
Brues 6f6beca9c7 feat(model): ModelScene WMO group liquid and camera fog
A scene's WMO now draws the liquids of its groups and fogs as the world
fogs a WMO around its camera.

Liquid: the world's group liquid pass (DrawGroupLiquidPass 0x00684CD0)
sets matrix 8 to the placement moved by the camera, commits a lighting
record with fog and calls DrawMapObjectGroupLiquid (0x006B4060). The
scene does the same for each parsed group with flag 0x1000, after its
opaque list and before its translucent one, as the world draws the pass
between its model lists. The engine's drawer gives the animated frames
(0x0068AAC0), the magma scroll and, with BuildGroupDepthRamp (0x006B6B60)
first, the water's depth ramp. A group whose first liquid type is past 8
is not drawn: type 0xF asks GetLiquidFrame for a frame past its table.
The parity flag is 1, the value every group gets from outside the portal
walk (RunGroupCallback 0x006B4160), so all tiles draw.

Camera fog: each scene update traces 1760 down from the scene's camera
as ClaimCameraMapObject (0x006821F0) traces from the world's: the nearest
floor of the groups, then CrossPortals (0x006A3F80) with the fraction
1.05, and no claim for a group whose MOGI flags have 0x8.
GetCameraInteriorFog (0x0069DE20) is mirrored for the claim (it reads the
world camera's globals): record 0 blended with the first group's
candidate fogs, farthest first, by the engine's LightFalloff (0x0069E1C0)
and LerpFogRecord (0x0069EFD0). BuildSceneFog (0x006CEE30) gives the
rest: the target's end is capped at the far clip, the weight moves 0.25
a second (0x008115B0) toward 1 while the camera is over an interior
group and toward 0 otherwise, and the drawn fog is the scene's fog
moved toward the target by it. The WMO, its interior doodads and the
interior actors take the drawn fog (ApplyMapObjectFog 0x006C31E0). This
replaces the fixed record 0 fog. The first update takes the weight as
it stands; the camera's own liquid is not asked.
2026-11-09 11:51:31 -06:00
Brues e309f6d32e feat(model): ModelScene shadows and footsteps on the WMO floor
Actors in a WMO scene now stand on the WMO the way 1.12.1 places a unit.
A unit's world entity is made with factory flags 0 (CGObject_C::CreateNode
0x00613E10 -> 0x00670DB0), so it lacks +0x90 bit 0x2000 (flag bit 3,
0x00670E9C) and ReattachEntity 0x006A86D0 sends it to AttachEntityToGround
0x006A8A20, not PlaceEntity 0x006A8C10 (game objects), which the actor
light mirrored before. Place now follows the unit's path: the probe starts
at the model's collision box centre through its matrix (UpdateNode
0x00613F80, GetCollisionBox 0x00713700) and finds the nearest group face
1000 yards down, else up past the sphere (TraceMapObjectsNearest 0x006A8840:
SegmentHitsGroupBox 0x006A47E0, IntersectSegment 0x006B92B0 mask 4). Only
that group links the actor and adds its MOLT lights. SetEntityLightFlags
picks the sun or interior, TraceGroupFace 0x006A2600 finds the face and
GetFaceTerrainType 0x006A26C0 its material's terrain type.

Footsteps and the death thud use that terrain type when the scene has no
SetGroundTerrain (the unit's +0xC60).

SetShadowShown on a WMO scene lays the blob as the world's decal.
DrawBlobShadow 0x006D7920 is mirrored up to DrawDecal: the box from 5/3 of
the height below the feet to 1 above it (0xCEA610 / 0xCEA60C, ThirdOf
0x006D6E50), the texture matrix, white with the model's alpha, depth
function 1 when shadowBias is 0. DrawDecal's world reads are replaced:
BuildDecalTransforms 0x006D6FA0 runs in its absolute mode, because the
other mode reads the world camera (null at the glue screen), and is moved
to the eye. DrawDecalBatches 0x006D7480 is mirrored with the WMO's own
facets (TestMapObjectBox 0x006AD330 -> CollectBoxFacets 0x006A3B10, mask
0x2F0122) and the engine's vertex, index and draw calls
(0x006D7810, 0x006D78A0, 0x0058A830). A scene without a WMO keeps the flat
quad.

The engine's queries take a map object def but read only its placement
(+0x94), inverse (+0xD4) and object (+0x118); the backdrop keeps a block
with those three.

actor:StopSpellVisual() (an extension) interrupts the casts still being
prepared, the drop a new cast already did (0x0060D1C0 stops the old
spell's kits). Without it a precast that ended after a death played its
cast animation over the death.
2026-11-09 11:51:30 -06:00
Brues 3cbef80a2b feat(model): ModelScene actors take the WMO's light
An actor standing in the scene's WMO is lit the way the world lights a
unit standing in it, instead of by the scene light alone.

Placement (World::Settle, from the scene's update) mirrors PlaceEntity
(0x006A8C10). LinkEntityToMapObject (0x006A8ED0): the model's bounds
through its base matrix give the world box and its centre (SyncLightNode
0x006717D0); the box goes into WMO space (TransformBox 0x006DC540) and is
tested against the WMO (BoxOverlaps 0x006A4670) and each group
(BoxOverlapsGroup 0x006A4830, GetLoadedGroup, GroupBoxAnyHit 0x006A3EE0 or
GroupSegmentAnyHit 0x006A3F10). In each non-exterior group,
TraceGroupMasked (0x006A3A40, mask 0x20) probes 1000 yards down from the
centre (0x008022CC), else 1000 up; t is shared, so the nearest face of all
groups wins, and its point is taken along the down probe as the engine
takes it. SetEntityLightFlags (0x006A87F0): no face, or a group with flag
0x40, means the sun. Else BakeGroupLight's face path (0x006A8410):
SampleGroupColor (0x006A4DC0) reads the face's MOCV colour and
SplitLightColor splits it (directional floor 0xA8, ambient cap 0x60); a
day face blends both toward the sun by the colour's alpha. Every linked
group adds its MOLT lights through AddMapLight (GatherMapObjectLights
0x006A79C0), so torches light the actors near them. The actor is placed
again when its translation moved a squared 0.001 or more (0x00801360),
when its model changed, or when a new group of the WMO was made.

The light (World::ActorLight, the actor model's new lighting callback)
mirrors ApplyMapLighting (0x006A7300): an interior actor gets the WMO fog,
the ambient bytes and the directional bytes along the fixed indoor
direction (0x00CA816C, blended toward the sun's by a day face); a sun-lit
one the frame's light and fog; both then their map lights. The scene light
is the sun throughout. Without a WMO the callback is the frame's own, as
before.

The doodads' map lights move to a per-group list on the backdrop, shared
with the actors, and the interior light slots to one helper.

Not mirrored: AnimateMapEntityLight's ramp (0x0069E770), so the light
changes at once. A model with an M2 parent is not placed.
2026-11-09 11:51:30 -06:00
Brues 800d90d386 feat(model): ModelScene WMO doodads and positional scene sounds
A WMO backdrop now shows its doodads the way the world builds them, and
every sound a scene plays is heard from the scene's camera at its distance.

Doodads (model/SceneWorld.cpp). Each parsed group makes its doodads as
CreateGroupDoodads (0x00695AA0) does: the group's MODR indices, kept when
FindDoodadSet (0x006A4FB0) gives set 0 or the instance's set; a doodad two
groups list is one def, sun-lit when any of them is exterior. Each def
mirrors CreateGroupDoodadDef (0x00694E90) and CreateDoodadModel
(0x00695100): the MODD record's translate / quaternion / scale matrix
times the placement, SplitLightColor (0x006A77E0) into the ambient and
directional bytes, the model from the MODN name, SetBaseTransform, the
engine's own done callback (0x006951B0) and PlayAnimation(-1, 0, -1, ...).

Lighting mirrors AddLights (0x006A8050): an exterior doodad takes the
frame's sun (the frame light callback 0x0076D680); an interior one its
ambient bytes and its directional bytes along the fixed direction at
0x00CA816C, then the group's MOLT point lights built as CreateGroupLights
(0x00695C00) and AddMapLight (0x006A7AC0) build them. An interior doodad
in a WMO with more than one MFOG takes MFOG[0], else the scene's fog.

Each frame mirrors DrawDoodadModels (0x00683F80): the world shows every
doodad it draws again (SetAnimated + SetVisible), faded by its sphere
(SetDoodadDefBounds 0x006952A0, CM2Model::GetBoundingSphere 0x00713680)
and the camera's ground distance, with the radius classes, fade ends and
ranges read live from 0x00810188..0x008101A8 and the large end capped by
the far clip.

Doodad sounds are opt-in, scene:SetPlayWorldModelSounds(enabled) /
GetPlayWorldModelSounds (a ClassicAPI extension, off by default): the
$DSO / $DSL / $DSE events of DoodadModelEvent (0x006951E0) through
PlaySoundAt (0x00458870) and the world's loop emitters (0x00461D80 add,
0x00462000 move, 0x00461F80 remove). The emitter pump runs only in the
world, so they play only there. A hidden scene (CSimpleFrame::Hide,
0x0076AD50) drops its loops.

Positional scene sounds (model/SceneSound.cpp). The engine has one
listener, placed by the world camera. A scene point is played where it
lies from the scene camera, its offsets along the camera's forward, up
and side laid along the listener's, read back through
FSOUND_3D_Listener_GetAttributes (0x007FDB50) in the engine's axes. The
engine then applies the row's cutoff, minimum distance and panning as for
a unit that far away. Sound::Play gains the world's 3D players:
PlayKitIDAt (0x0045CF00, RET 0x18, NULL past the cutoff), PlayKitLoopedAt
(0x004589A0) and Move (Sound::SetPosition 0x007A5B10), all owned so
StopSound stops them.

The actors use it: spell kit sounds at the actor, the missile's loop
following the missile (re-mapped each paint) and stopped when the scene
hides, and the animation sounds of SetPlayAnimationSounds at the actor.
actor:PlaySound(soundKitID) is a ClassicAPI extension: a SoundKitID once at
the actor, returning willPlay, soundHandle as PlaySound does.
2026-11-09 11:51:30 -06:00
Brues 81ffc12766 feat(model): ModelScene WMO backdrops (SetWorldModel)
A ClassicAPI extension: scene:SetWorldModel(path [, x, y, z [, yaw
[, doodadSet]]]), scene:SetWorldModelByMapID(mapID) and
scene:ClearWorldModel() show a WMO around the scene's actors. Both
setters return whether a WMO is shown; a set that fails clears it.
ModelSceneActor:SetModelByPath refuses .wmo paths, which only the scene
shows.

The map object is the world's own. CMapObj::Get (0x006A3230) loads it
into the engine's cache with one reference ours, released by CountDown
(0x006A33F0). Each paint keeps every group alive for 30 s (group
+0x15C) and queues LoadGroup (0x006A4A30) for a group that is neither
parsed (+0x164) nor being read (+0x160), so a group the world frame has
freed comes back. The pools, shaders and cache come from
CMap::Initialize at client start, so a WMO also shows at the glue
screen.

The engine's reader ends the program when a file does not open
(CMap::SafeOpen) and parses the root's chunks in a fixed order without
reading their tags. A root is refused unless MVER and the 16 chunks from
MOHD to MFOG are in that order inside the file, it has at most 384
groups, and each group file opens.

The paint draws the WMO after the animate pass, the way
DrawMapObjectPass (0x00684840) draws one instance:

- render states pushed; world stack 8 = placement x Translate(-eye);
- the frustum stack pushed (0x00682380), a volume of the scene's view
  stored on it (BuildFrustumCorners 0x005C43B0 over the device view
  moved by -eye and the device projection, planes by 0x00686640), then
  moved into the object's space with the inverse placement
  (0x00682ED0), which the drawers cull each batch against;
- a lighting record at the object's bounding sphere
  (M2LightingInitialize 0x0071BC30, the scene's M2 lights for that point
  by 0x0070A0F0, the scene light as the sun by 0x0071BF90, then the fog),
  committed at the eye with fog by 0x0071C730;
- each parsed group: the portal vertex fade once (0x006C43D0), then the
  interior (0x006B5190) or exterior (0x006B4F10) drawer, called directly,
  because the world sets its drawer pointers only in its own frame.

Fog: the world fogs a WMO's insides with its MFOG records only for a WMO
with more than one record (0x0069DE20). With no candidate the fog is
record 0, its end capped at the far clip and its start that record's
fraction of the end. Other WMOs take the scene's own fog, staged with
the scene light by the frame's light callback (0x0076D680).

The drawers read two world globals. The group fog flag (0x00CA7F00)
would replace the fog with the light state's interior fog, so it is 0
while the scene draws. Window materials write the sun's colours through
the sun pointer (0x00C89EF0), which is NULL at the glue screen, so while
the scene draws it points at a copy of the scene light.

SetWorldModelByMapID reads the map's directory from Map.dbc, then the
WDT's MPHD, MAIN, MWMO and MODF. Only a map whose WDT holds one WMO and
no terrain has an answer. The placement is the world's own for a WDT
object: translate (-pos[2], -pos[0], pos[1]), then rotate z by
rot[1] + pi, y by rot[0] and x by rot[2] (degrees by 0x007FFAAC), with
the record's doodad set. Scene positions then are the map's positions,
so a creature's spawn point places its actor in the room.

Not drawn yet: the doodads, the room's light on the actors, liquids and
the camera's fog inside the WMO.
2026-11-09 11:51:30 -06:00
Brues b2c7d63085 feat(model): ModelSceneActor SetShadowShown blob shadows
A ClassicAPI extension, off by default: actor:SetShadowShown(shown) /
IsShadowShown() put the world's blob shadow under the actor.

The shadow is 1.12's own (DrawBlobShadow 0x006D7920, reached from the
entity draw through 0x006D78F0): drawn only while shadowLOD
(0x0086F5B4) is 1 and the model is ready; the bounds of sequence (0, 0),
skipped when the x or y extent is under the range epsilon, clamped to
+-5 and multiplied by the length of the base transform's row 0
(GetBaseTransform 0x00710600); the four corners turned by the base
rotation and moved by the base translation. The texture is the one the
unit setup loads (Textures\ShadowBlob.blp, handle 0x00CE9DFC, device
object through 0x0044ACF0), with the decal's states: blend 4
(DST_COLOR / ZERO), lighting, fog and depth write off, combiner preset 5,
and the colour white with the model's alpha (GetAlpha 0x00710CA0;
0x004A2C10 packs that byte on top).

The world lays the shadow onto the ground's batches with a decal
(0x006D7330). A scene has no ground, so the paint draws the turned box
itself as a flat triangle strip on the plane of the base translation,
after the animate pass and before the draw passes, so every model draws
over the shadows. Culling is off, as for the engine's lightning quad
(0x007AFCB0). The decal's height fade and its shadowBias depth test
EQUAL are not drawn: both exist to match real ground. A model hung on
another casts none.
2026-11-09 11:51:30 -06:00
Brues b48ffe42fb feat(model): ModelScene GetActorAtCursor and OnActorEnter/OnActorLeave
A ClassicAPI extension: scene:GetActorAtCursor() returns the shown actor
under the cursor, and the scene scripts OnActorEnter / OnActorLeave
(self, actor) run when that actor changes while the scene is the mouse
focus.

The pick is the world's own object pick (0x00480A50) on the scene's M2
scene, not a bounding-box test: EnableRayHits (0x007089B0), then
CM2Model::SetHitTestMode(model, 1, 0, actor) (0x00713CB0, ret 0xC) on
each shown actor's model and its children (held items, kit effects), as
0x00480D90 does for a unit; a child that is another actor's model (a
seated rider) is left to that actor. M2SceneRayHit (0x007089C0, ret 0x10,
retry 1 as the world passes) skins each instance animated in the latest
collect on the CPU and returns the value of the nearest triangle. The
ray empties the hit list on every call.

The ray is in view space, where the collect leaves the instance
matrices: the cursor (UI context +0x1118, NDC) in the paint's viewport
(the frame's rect clamped to the screen), unprojected through the
paint's own projection at view depth near and far. The paint's camera
leg is now CameraTransforms, shared with the pick, so view insets and
translation move the pick with the picture. CCamera::SetDeviceTransforms
(0x007AC640) reads only the rect's aspect, so the clamped viewport is
the space the cursor maps into.

The hover runs from the scene's update walk, only while one of the two
scripts is set (Frame::ExtraScripts cells) and the scene is the mouse
focus (UI context +0x7C).
2026-11-09 11:51:30 -06:00
Brues 708226a929 feat(model): ModelSceneActor animation event sounds
ClassicAPI extensions: actor:SetPlayAnimationSounds(enabled) and
scene:SetGroundTerrain([terrainTypeID]), each with its getter.

Each actor model now gets the engine's event callback
(CM2Model::SetEventCallback, 0x007133A0), as a unit's model does
(0x00607800). model/SceneEvents.cpp sorts the events by their
four-character tag, as the unit dispatcher CGUnit_C::OnModelEvent
(0x005FFBD0) does. It receives the $CSL, $CSR and $CST missile
releases, which moved there from SceneSpell.cpp. When the actor opts
in, it also plays the sounds that a unit plays. They come from the
CreatureSoundData of the display: its own row, else its model data's,
as GetSoundData (0x0060AFB0) picks it.

- $FD1 to $FD4: the fidgets at +0x38 (0x006232C0).
- $FDX: the stand vocal at +0x20, with the world's 41-in-101 chance
  and a 10 s limit shared by all actors. It never plays for the
  active player's copy (0x006236B0, 0x00623490).
- $WNG and $WGG: the wing flap at +0x2C and the glide at +0x30. The
  dispatcher plays them as vocal kinds 7 and 10, through slot 34
  (push 7 / push 0xA, call [eax+0x88]).
- $FSD: the engine's GetFootstepSound (0x00458450), by the scene's
  ground terrain, with FootstepSounds on.
- $DTH: the dry thud from the engine's death-thud table (0x00C4E0F4),
  by size class (GetUnitSoundSize 0x00625500) and the ground.
- $CSD: the event's own SoundEntries id, with EmoteSounds on.
- $TRD: the precast sound (SpellVisual +0x38) of a PlaySpellVisual
  that is still preparing (0x0062FAA0).

The sounds are off by default, so stock scenes such as the dressing
room stay silent. They play in 2D through the by-ID player. A scene
without a ground terrain has no footsteps and no death thud. $CSS,
$CAH and $AH0 to $AH3 play nothing: they present a pending swing
(0x006247D0), and an actor never swings at anything. The unit's
display ID is kept on the actor so that its sound data can be found.
2026-11-09 11:51:29 -06:00
Brues d22d10316b docs(model): Project3DPointTo2D ignores the view insets and translation
The ModelScene paint frames the camera over the view rect (the frame's
rect less its insets, moved by its translation), and Project3DPointTo2D
frames it over the whole rect. That looked like a gap, so retail was
probed: a 400x200 scene with its camera at (-10, 0, 0) projected the
origin to (142.22, 71.11) plainly, with SetViewInsets(100, 0, 0, 0) and
with SetViewTranslation(50, 0). The comment above Project now records
this, so the whole-rect framing stays.
2026-11-09 11:51:27 -06:00
Brues b08d2fe813 refactor(frame): one wrapper for the layout sub-object's calls
Every region and frame carries a layout sub-object at +0x24 (4.3.4's
CLayoutFrame; OFF_REGION_ANCHOR, OFF_FRAME_LAYOUT_SUBOBJECT for a frame),
and three engine calls on it were wrapped by hand in sixteen files, each
with its own typedef and often its own AnchorOf / LayoutOf / FrameOf
helper:

- CLayoutFrame::GetRect (FUN_REGION_GET_RECT, 0x00768320), the
  {bottom, left, top, right} rect, false before layout;
- IsResizePending (FUN_REGION_LAYOUT_DIRTY, 0x00768310);
- CLayoutFrame::Resize (FUN_LAYOUT_RESIZE, 0x007680E0), 1 to lay out now,
  0 to mark for the layout pass.

frame/Layout.h now holds them, taking the region or frame itself, with
Of and OwnerOf for the sub-object and back, and GetResolvedRect for the
read the edge getters make (Script GetLeft 0x007A1A19: a pending resize
run now, then the rect). Frame::Subclass::FrameOfLayout is replaced by
OwnerOf.
2026-11-09 11:51:27 -06:00
Brues f0f784bd70 refactor(gx): one save and restore of the device transforms
The draws that leave the UI pass's transforms saved and restored the
device projection, view and viewport by hand, each with its own
typedefs: the ModelScene paint (as SimpleModelDraw 0x0076D240 does), the
portrait bake, ClipChildren's ScrollFrame-shaped draw (0x00787220), and
the ModelScene projection, which reads the camera's matrices back.
AlphaGradient read the projection and viewport the same way, and the
scene and the bake each wrapped CameraSetDeviceTransforms
(FUN_CAMERA_SET_DEVICE_TRANSFORMS, 0x007ADA40).

gx/Device.h now wraps FUN_GX_GET/SET_PROJECTION, FUN_GX_GET/SET_VIEW and
FUN_GX_GET/SET_VIEWPORT, and Gx::SavedTransforms saves all three for a
scope and restores them at its end. Model::Camera::SetDeviceTransforms
wraps the camera call. Only AlphaGradient's hooks on the two setters
still name the addresses.

The projection now also puts back the viewport, unchanged. The bake
reads and disables fog just before it saves the transforms; the restore
order is the same as before.
2026-11-09 11:51:27 -06:00
Brues 627c86f5ba refactor(model): share the ModelScene argument checks
Scene.cpp and SceneActor.cpp each had NumberArgs and FloatArg, the same
loop that raises the engine's "Usage: <owner>:<usage>" error when an
argument is not a number, with the frame and actor arguments in a
different order.

One NumberArgs, which takes the owner's display name, and one FloatArg
are now declared in model/Scene.h and used by both files.
2026-11-09 11:51:27 -06:00
Brues b644567cf9 refactor(frame): one wrapper for each draw-layer invalidate
CSimpleFrame::NotifyLayerChanged (FUN_FRAME_NOTIFY_LAYER_CHANGED,
0x0076A990, __thiscall (frame, layer)) was wrapped by hand in Cooldown,
ModelScene and ClipChildren, and CScriptRegion::NotifyLayerChanged
(FUN_REGION_NOTIFY_LAYER_CHANGED, 0x0077FDF0, __thiscall (region)) in the
inline-texture pool and the texture wrap. Each file carried its own
typedef for the same engine call.

frame/LayerChange.h now holds the two: NotifyFrame and NotifyRegion. All
five files call them.
2026-11-09 11:51:27 -06:00
Brues 891ef4f1e6 refactor(frame): share the frame-class plumbing in Frame::Subclass
Cooldown and ModelScene each carried their own copy of the parts every
frame class this DLL adds needs: a type id, IsA, IsObjectType,
GetObjectType, GetScriptMethod, the deleting destructor and its layout
thunk, the vtable build, and a factory body that allocates the block with
SMemAlloc (FUN_STORM_SMEM_ALLOC, zero-filled), runs the engine class's
constructor and installs the vtables. The copies had already drifted:
Cooldown compared type names with _stricmp, ModelScene with Storm's
SStrCmpI.

Frame::Subclass::Class now holds a class's name, the engine class it
extends (vtable, layout vtable, constructor), its size and a function that
releases its own fields, plus its type id, method hash and vtable copies.
Templates on that object give the shared overrides, BuildVTables, New and
RegisterFactory (FUN_FRAMEXML_REGISTER_FACTORY). Both classes now answer
IsObjectType through Game::StrCmpI and take CSimpleFrame's script resolver
(+0x0C), which Cooldown's copied vtable already held.
2026-11-09 11:51:27 -06:00
Brues b30735ecf9 fix(model): end one-shot actor animations, drop a replaced one's end
M2SceneAdvance (0x007074D8) updates only the models on the scene's animate
list, and that update (CM2Model::Update, 0x00719370) is what queues a
sequence's end callback; the paint's animate pass then empties the list.
Actors put their models on the list after the scene frame's clock had
advanced, so no actor model was ever updated: a looping animation still
played (its pose comes from the scene clock), but a one-shot one such as
AttackUnarmed stopped on its last frame and OnAnimFinished never ran. The
scene's update now links every ready actor model (Link) before the clock
runs, the order the Model frame's own clock (0x0076D7F0) uses.

A new animation also drops an end still pending for the one it replaces.
The engine reports a replaced play to the done callback as reason 1, which
the actor ignores; an end queued in the same advance reached the actor as
if the new animation had ended. Two actors whose animations ended in one
advance then saw OnAnimFinished for the animation the other's script had
just given them.
2026-11-09 11:51:26 -06:00
Brues 8bb6055e05 feat(model): frame a scene's picture with view insets and translation
SetViewInsets(left, right, top, bottom) and SetViewTranslation(x, y), with
their getters and the XML <ViewInsets left right top bottom> child, frame
the camera's picture inside the ModelScene. Both are in the frame's own
units, with y up.

The paint gives the camera's CameraSetDeviceTransforms (0x007ADA40) the
frame's rect less the insets and moved by the translation, converted to
layout units with PixelToInternal(length * effective scale). The camera
takes its aspect from that rect, as it does from the frame's. The device
projection is then read back (0x0058B090), scaled and shifted in clip space
so that the view rect lands where it lies in the frame, and set again
(0x0058B040). The viewport stays the frame's rect, so drawing still stops
at the frame's edges, and negative insets let the view reach past them.

Project3DPointTo2D keeps projecting over the frame's rect and ignores both
settings, which is what retail does.
2026-11-09 11:51:26 -06:00
Brues e7918018a2 feat(model): project scene points to the frame, store overlapped models
The ModelScene mixin calls two scene methods the frame did not have: OnLoad
calls SetAllowOverlappedModels(true) for StoreModelSceneMixinTemplate, and
Transform3DPointTo2D calls Project3DPointTo2D.

Project3DPointTo2D runs the point through the matrices the paint draws with.
It saves the device projection and view (0x0058B090 / 0x0058B0B0), runs
CameraSetDeviceTransforms (0x007ADA40) over the frame's rect, reads both back
and restores them. The view looks from the origin, so the point goes in
relative to the camera eye. The matrices are row-vector, and the perspective
matrix (0x005C3CC0) puts 1 at m11, so w' is the view depth. A |w'| under
0.001 projects nothing, the rule of the engine's own projector (0x005C4F30).

The result is in the frame's units times its effective scale, from the
bottom-left of the frame, as InternalToPixel gives the rect's extent. A point
behind the camera still projects. Depth is 1 at the near clip and 0 at the
far clip, by distance along the camera's forward axis.

SetAllowOverlappedModels stores its flag (default false). 1.12 draws a model
frame whatever overlaps it, so the flag has nothing to gate.
2026-11-09 11:51:26 -06:00
Brues 640ebd0ab0 feat(model): run retail's ModelScene Lua on the scene frame
Retail's camera registry, camera base, orbit camera, scene mixin and
actor mixin come over verbatim, with their XML templates, so a scene
built with SetFromModelSceneID frames, scales and orbits its actors the
way retail's does. What they need from the client:

Actor templates. 1.12's XML loader registers every virtual top-level
node whatever its tag, so <Actor name="ModelSceneActorTemplate"> is a
template that Xml::Template finds. CreateActor(name, template) loads it
the way an animation group loads its own: the whole inherits chain's
mixins first, then each node from the base up, then OnLoad. The
parentKey, parentArray, <Scripts> and <KeyValues> readers move out of
the animation loader so both use them.

Scene state. Light setters write the frame's M2Light through the
engine's own setters (M2LightSetType 0x0071B620, SetDirection
0x0071B6A0, SetPosition 0x0071B650, SetEnabled 0x0071B780). Fog uses
the Model frame's fields (+0x3A4..+0x3B0), stored as Model's own
SetFogColor, SetFogNear, SetFogFar and ClearFog store them, and starts
at retail's values. The draw layer goes through the engine's layer-name
functions (0x006F18B0, 0x006F1900) and marks both layers changed.
SetPaused keeps the frame update but skips Model's M2SceneAdvance. The
XML loader adds drawLayer, fogNear, fogFar and <FogColor> after the
frame's own loader.

Actor state. A blend operation for PlayAnimation. Spell visual kits use
the routine behind PlayerModel:ApplySpellVisualKit, which now takes a
model instead of a pane; the actor applies a kit once its model loads
and takes the effects off when the kit changes. 1.12 has no animation
kits, so PlayAnimationKit and StopAnimationKit change nothing.

GetCursorDelta, which the orbit camera drags with, samples the top's
cursor (+0x1118) once a frame at the head of the UI render callback and
converts it the way GetCursorPosition (0x0048B820) does, so the delta is
the difference of two GetCursorPosition values. C_PlayerInfo.
GetAlternateFormInfo answers false, false: 1.12 has no alternate forms.
2026-11-09 11:51:25 -06:00
Brues be21ff50f6 feat(model): add the ModelScene frame type and C_ModelInfo
ModelScene is a 3D stage of model actors with its own camera. 1.12.1's
Model frame is already one: every Model frame owns an M2 scene and a
clock, and its paint (SimpleModelDraw 0x0076D240) animates and draws the
whole scene, each unattached model with its own placement matrix. The
stock frame only ever places one model.

So a ModelScene is a CSimpleModel: the Model factory's allocation plus
our fields, CSimpleModel's constructor (0x0076C8E0), then copies of its
two vtables with the Model half hidden from Lua. Lookup goes to our
method hash and then CSimpleFrame's, the type answers ModelScene, Frame
and Region but not Model, and Model's script names and XML loader give
way to the Frame ones. The layer emit queues our paint on ARTWORK. The
paint repeats SimpleModelDraw call for call: save the device transforms,
project through the frame's camera over its rect, clamp the viewport,
clear depth, place each actor where slot 0x98 would place the one
model, animate the scene from the camera eye, draw passes 0 and 1, and
restore.

The camera is a CCamera made and installed the way the PlayerModel
pane makes its fallback camera (CameraCreate 0x007AC930,
SimpleModelInstallCamera 0x0076CE80). Eye and target come from the
position and forward axis. The yaw and roll properties are solved so
that the view's up vector equals the requested one. The default light is
set the way PlayerModel's constructor sets its own.

An actor is a script object holding one model in the frame's scene. It
is lit through the frame's light callback, placed with
CM2Model::SetBaseTransformTRS (0x00710650), and polled for load and
dressing from the frame's update, never from the paint. A display with
an Extra record is dressed through the engine compositor. The bounding
boxes come from GetSequenceInfo (0x00711A20) and GetBoundingBox
(0x00713640).

C_ModelInfo's getters read the rows of scenes 4, 44 and 596, embedded
from the retail 12.1.7 exports. The four active-scene functions do
nothing, as retail's own documentation says, and live in Compat.lua.

The same calls on Turtle and on retail draw the same picture (scene
4's camera on the Brown Horse, centred on Z, scaled by retail's
normalization).

Frame::Subclass now holds the vtable copy and the per-class method
hash, which Cooldown uses too. Model::DisplayInfo::CreateDisplayModel
builds a display's model for both portraits and actors.
2026-11-09 11:51:25 -06:00