andodeki/makepad
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
makepad/libs/render/ENTITY_LIGHTS.md
Admin d2130e6550 libs: model, mesh_edit, csg, scene, sim, render, xr 
Squash of 25 work commits (Sep 1–12):
  237da90  render: the sprite lane hands the screen draw back the way it found it
  895b9a7  particles: an emitter can ride a body's own frame
  914471f  ai-hub: a feed session whose last socket left ends on its idle timeout; skin: parent, skinned centroid and a nodes-only rig for retargets
  3fcccf3  sim: the whole world is implicitly editable, and one seam says where the ground is
  5692fab  sim: the landform world proves itself — walker through the tunnel included
  f4af6df  sim: terrain knows who changed it — a plan layer over player history
  adbb078  render: a water volume can be physics without a picture
  c17480f  render: a non-rigid body may carry its own orientation
  acad401  sim: an agent with no route holds and retries instead of walking into the wall
  22b2bf9  sim + chat: the composed world surface takes a map floor; the chat gets plan tools
  faf8112  web path: the tessellator's lap timer, the trace span and the fusion cycle timer have no clock on the web
  d3472eb  tsdf: the clock-taking XR helpers are native-only — the browser has no depth camera and no Instant
  4946c9e  sim + render: a repaint is not a world edit — colour and glow restyles never rebake the lightmap
  4317f58  sim + render + chat: walk decks as a surface, the filmed body is no obstruction, the brief never asks
  9791279  render: support rigged models and custom materials across viewers
  3ce2792  sim: use deck geometry for collision and sensing
  c8b79ff  Add portable PBR, rig and soft-body authoring support
  108d423  Add transactional polygon modeling and editable asset documents
  38f4d3b  Refine editable modeling and firm yarn character behavior
  08a2637  sim: add entity-owned lights and vehicle headlights
  00d96a7  render: add clustered lights, local shadows and incremental GI
  cf916af  render: import glTF asset extensions and wire clustered GI
  c6d2cca  model: cut transaction memory and raise capacity limits
  41af47a  raytrace: add a CPU probe-ray BVH budget example
  c963d0a  libs: the game sim splits into makepad-scene and makepad-soft-body; render, model, fab and the asset importer retarget

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-15 13:40:31 +02:00

4.1 KiB
Raw Permalink Blame History

Entity lights

Sandbox Splash can attach named point lights and spotlights to any entity:

let car = game.car({pos: vec3(0, 1, 0)})
game.headlights(car, true)
game.light(car, {
    name: "headlight_left"
    kind: "spot"
    pos: vec3(-0.7, 0.1, -2.1)
    dir: vec3(0, -0.08, -1)
    color: #fff0d1
    intensity: 4
    range: 30
    inner_angle: 12
    outer_angle: 25
    shadows: true
})
game.headlights(car, false)
game.light_remove(car, "headlight_left")

game.light(owner, options) upserts one name, preserving omitted settings. The default name is light; default kind is point. It returns false and logs invalid data, without replacing the previous fixture. game.light_remove returns whether it removed one. game.headlights installs/toggles headlight_left and headlight_right without resetting custom tuning. Both game.car and game.racecar install enabled headlights by default; headlights: false creates them disabled.

Position is body-local and follows entity scale. Direction follows the visible entity rotation (including rigid-body pitch/roll), not scale. Forward is -Z. Range is world units and does not scale. Cone angles are half-angles in degrees; require 0 <= inner <= outer and 0.5 <= outer <= 85. Color is linear RGB in 0..1; intensity is a nonnegative artistic multiplier, not lumens/candelas. Intensity is limited to 10000 and range to 0.05..10000. Names are 1..64 bytes; there are at most 16 authored lights per entity.

Shadow casters include the owner: position the emitter outside its solid mesh. This is surface lighting and occlusion, not a volumetric beam/fog effect.

Lights live in Entity::lights, clone and disappear with their owner, and are transformed every frame. Hidden physics bodies may own visible fixtures. There is no geometry rebuild or light bake on a light edit. Authored values replicate reliably in protocol version 7; movement uses the existing entity pose stream. Every peer must run the same protocol version. This does not add new rigid-body orientation fields to the network protocol.

Named model/bone sockets are not part of this API. Use body-local offsets; imported model emitters are a separate modeling API.

Local shadows

In clustered mode, shadows: true requests realtime occlusion. Shadows are off by default for generic lights and on for the headlight helper. The renderer draws a depth atlas before the forward pass, including static models, primitives, terrain/voxels, moving models/parts and skinned casters. Transparent light transmission and alpha-cutout shadow silhouettes are not implemented; dynamic primitive casters retain the existing box approximation.

renderer.set_local_shadow_config(makepad_render::LocalShadowConfig {
    max_faces: 2,
    resolution: 256,
});

Default budget: eight 512px faces. Limits: 0..16 faces, 128..1024px per face (rounded up to a power of two). A spotlight uses one face; a point uses six. The allocator prioritizes active lights by brightness/range/distance to the camera. Allocation is all-or-nothing per light; an excluded shadow request is omitted, not changed into a wall-leaking unshadowed light. This can cause popping at the budget boundary. RenderStats::clustered.shadows reports selected lights, faces, omitted requests, caster draws and CPU encoding time, not GPU duration.

Use a small spotlight budget on constrained devices; no Quest GPU performance claim is implied by these defaults. Sun CSM remains independent. The legacy MAKEPAD_CLUSTERED=off path does not support these local shadow/cone semantics.

Verification fixture

After a release sandbox build, launch from the checkout root:

SANDBOX_WORLD=clustered MAKEPAD_CLUSTER_DEMO_HEADLIGHTS=1 \
  ./apps/sandbox/target/release/makepad-sandbox --remote

A moving body carries two lights toward a freestanding blocker and a rear wall. MAKEPAD_CLUSTER_DEMO_FREEZE=1 pins the body for comparison; MAKEPAD_HEADLIGHT_UNSHADOWED=1 removes the two shadow requests for an A/B run. MAKEPAD_HEADLIGHT_POINT=1 adds a blue, six-face point light. MAKEPAD_HEADLIGHT_SHADOW_FACES=N overrides the atlas budget in this fixture. Finish owned test instances through their printed /gq endpoint.