Models Puppets and Lighting

Models, puppets and lighting

The 3D side of the scene engine: .mdl models, perspective cameras and depth, puppet warp, skinning and morph targets, scene lights, shadows, planar reflections, bloom and HDR, fog and volumetrics. The evidence and plans are in docs/models-plan.md and docs/lighting-plan.md.

3D models

Feature	Status and where
.mdl parsing	Meshes (MDLV), skeletons (MDLS), animations (MDLA), morph data (MDMP) and the other chunks, across the versions in use (Scene/Format/Model, MDLParseTests)
Model objects	Every model object draws at its place in the object loop, culled by its bounding sphere (SceneModelBuilder, SceneModelRenderer); script clones draw too
Materials	WE's model shaders (generic4 and others) through the translator, with engine combos and pass state (ModelMaterialPlan)
Skinning, animation layers, root motion	Models posed while visible, g_Bones at WE's rounded BONECOUNT, the script layer API, root motion (SceneRootMotion)
Morph targets	Morph textures, up to 11 active targets, MDLA morph tracks, setBlendShapeWeight (SceneMorphTargets)
Attachments	On models and puppets, through their hierarchies

Perspective scenes

• general.orthogonalprojection decides orthographic or perspective; missing, null and zero sizes are perspective (1920×1080).
• SceneCamera: reversed-Z, right-handed, WE's defaults and fov clamp. Camera layers with their paths, scene camera paths and camerafade.
• WE's 4×4 transform hierarchy with origin.z and scale.z.
• A depth buffer with WE's reversed depth; each draw sets its depth and cull state. Draw order follows transparentsorting/customsortorder.
• 2D images and text in a perspective scene draw through the camera; fullscreen layers stay in screen space.

Puppet warp

• Puppet rigs from .mdl: the mesh draws the layer's image through WE's combos, posed by its animation layers every visible frame (ScenePuppet, ScenePuppetAnimator).
• Bone physics: spring and rigid bones, gravity, limits and impulses, checked frame by frame against a WE capture of an editor-made rope.
• Attachments: a layer attached to a rig bone draws from it.
• The script API: animation layers, bones, attachments.

Lighting

Package	What it does
Light format and values	Point, spot, tube and directional lights decoded; fields are live (scripts, timelines) (SceneLight, SceneLightValues)
LightingV1	WE's generated lighting code and the LIGHTS_* combos (LightingV1Require, SceneEngineCombos+Lighting)
Light packer	Packs the frame's lights into WE's budget (SceneLightPacker, SceneFrameLighting)
Lit image layers	Layers whose material sets LIGHTING or REFLECTION draw through their material with the packed lights, including the prelit path
Light cookies	SceneLightCookie

Shadows

• _rt_shadowAtlas with WE's shelf packer, growth and map sizes (SceneShadowAtlas).
• Spot, point (cube) and cascaded directional shadow views with WE's snap and bias behaviour (SceneShadowViews, SceneShadowPass).
• Casters draw their [PASS] shadow variants; lit models, images and volumes read the atlas.
• Quality comes from the Shadows setting (Disabled…Ultra, default Medium) in Settings › Performance.

Reflections

• _rt_MipMappedFrameBuffer and the Reflections setting: a REFLECTION layer draws through its material.
• Planar _rt_Reflection (ScenePlanarReflection): a mirrored pass drawing models, images, texts and particle systems.

Bloom, HDR and display HDR

• WE's LDR bloom chain: its own four util passes (SceneBloomChain).
• With bloom, hdr and post-processing Ultra, a scene draws into float targets with HDR=1 and blooms through WE's HDR mip chain (SceneHDRChain).
• Ultra (Display HDR) on a display with EDR headroom outputs WE's display-HDR combine as EDR (SceneDisplayOutput, DisplayHDRSupport).

Fog and volumetrics

• Distance and height fog from the scene's settings (SceneFogSettings, fog combos).
• Volumetric point and spot lights through WE's util passes (SceneVolumetrics, SceneVolumetricLight); quality from the Volumetrics setting; 3D scenes read the scene's depth.

Verification

These areas were checked against WE's own shipped shaders, the binary's behaviour (described in the plans, not reproduced here) and WE capture projects (the "MG" and "GP" ground truths). Tests include ModelLibraryRenderTests, ModelGroundTruthLibraryTests, MDLLibrarySweepTests, ModelMaterialSweepTests, ScenePuppetReferenceTests, ScenePlanarReflectionObjectTests, SceneDisplayOutputTests and LightingFrameBenchmarkTests. See Testing and WE-fidelity principles.

Open points

• Earlier gaps are now handled: clear, ambient and skylight colours are applied (g_LightAmbientColor, g_LightSkylightColor, SceneFrameLighting), lit particles read the shadow atlas, and a particle system's perspective flag draws it through a perspective camera in an orthographic scene.

See Roadmap and known issues.

User guide: Scene wallpapers