optional-skills/creative/unreal-mcp/references/scene-craft.md
The numbers and conventions that make a scene read as good instead of merely present. Sources: physical/photographic standards (stable), UE conventions (stable), and practical ranges from production use (marked ≈). UE-version-specific defaults drift; when a live schema or editor value disagrees with this sheet, trust the editor and patch the sheet.
| Thing | Convention |
|---|---|
| Distance | 1 Unreal Unit = 1 cm |
| Axes | Z-up, X-forward, Y-right (left-handed) |
| Rotation | Rotator in degrees: Roll (around X), Pitch (around Y), Yaw (around Z) |
| Color | Linear RGBA, each channel 0–1 (FLinearColor) |
| Light color | Prefer use_temperature + Kelvin over tinting RGB |
| Scale | Multiplier per axis (1,1,1 = authored size) |
Directional-light aiming: the ROTATION points the light. Pitch −90° = sun straight overhead (noon); pitch −5° to −15° = sun grazing the horizon (golden hour); yaw picks the compass direction the light travels toward.
| Reference | Size (cm) |
|---|---|
| Eye height (standing) | 160–175 |
| Door | 200–210 tall × 80–90 wide |
| Ceiling, residential | 240–300 |
| One building storey | 300–400 |
| Counter/desk height | 75–110 |
| Chair seat | 45 |
| Stair riser / tread | ≈18 / ≈28 |
| UE default mannequin | ≈180 tall |
| Car | ≈450 long × 180 wide × 145 tall |
If a "house" door comes out 400 cm tall, the scene reads as toy/giant. Always place one human-scale object early as a yardstick.
| Root | Meaning |
|---|---|
/Game/... | Project content (Content/ folder) |
/Engine/... | Engine-shipped content, present in every project |
/Script/Module.Class | Native classes (e.g. /Script/Engine.PointLight) |
Long package name form: /Game/Props/SM_Chair.SM_Chair (package.object).
Always-available engine primitives (great for blocking before real assets):
/Engine/BasicShapes/Cube.Cube (100×100×100 cm at scale 1)
/Engine/BasicShapes/Sphere.Sphere (100 cm diameter)
/Engine/BasicShapes/Cylinder.Cylinder (100 cm ⌀ × 100 cm)
/Engine/BasicShapes/Cone.Cone
/Engine/BasicShapes/Plane.Plane (100×100 cm, single-sided)
Their default material is plain grey; assign a MaterialInstance for anything
presentational. If the project has Starter Content, useful packs live under
/Game/StarterContent/ (Props, Materials like M_Basic_Wall, M_Wood_Pine,
M_Metal_Steel, Particles). Query before assuming Starter Content exists.
Common actor classes for spawning: StaticMeshActor, PointLight,
SpotLight, RectLight, DirectionalLight, SkyLight,
ExponentialHeightFog, SkyAtmosphere, VolumetricCloud,
PostProcessVolume, CameraActor, CineCameraActor, PlayerStart.
UE5 lights default to physical units (directional in lux, point/spot in candela or lumens, exposure in EV100). Use real-world values; they compose correctly with exposure instead of fighting it.
Calibration check first (live-verified): template levels often ship a
sun at intensity: 10 with auto-exposure tuned around it — physical lux
values below will blow such a scene to white. Read the existing sun's
intensity; if it's single/double digits, scale moods RELATIVE to it (noon =
template value, golden hour ≈ 0.5–0.7×, overcast ≈ 0.3×, night ≈ 0.01×)
and rely on temperature + pitch for the mood. The absolute table applies
when you own the whole exposure chain (manual EV100 + physical values
everywhere):
| Condition | Intensity (lux) | Pitch | Temperature |
|---|---|---|---|
| Noon, clear | 75,000–120,000 | −60° to −90° | 5,500–6,000 K |
| Afternoon | 40,000–75,000 | −30° to −50° | 5,000–5,500 K |
| Golden hour | 5,000–20,000 | −5° to −15° | 2,800–3,500 K |
| Overcast | 5,000–20,000 (soft) | −45° ± | 6,500–7,500 K |
| Blue hour / dusk | 10–100 | −2° to +5° | 8,000–12,000 K |
| Full-moon night | 0.05–0.3 | −30° to −60° | 4,000–4,500 K (cool-blue read comes from exposure + grade) |
Overcast: also drop directional shadow contrast (soften via larger source angle) and let the sky light dominate.
One SkyLight per level, Real-Time Capture (SLS Captured Scene) when using SkyAtmosphere — it then tracks the sun automatically. Don't stack multiple sky lights; don't leave a stale static capture after big lighting changes (recapture if not real-time).
Rules of thumb in lumens (candela ≈ lumens/(4π) for a point light):
| Source | Lumens |
|---|---|
| Candle flame | 10–15 (≈1,850 K) |
| 40 W incandescent equiv. | 450 (2,700 K) |
| 60 W equiv. | 800 (2,700–3,000 K) |
| 100 W equiv. | 1,600 (3,000 K) |
| Bright ceiling fixture | 2,000–4,000 (3,000–4,000 K) |
| Fluorescent tube / office | 2,500–5,000 (4,000–5,000 K) |
| Streetlight (sodium) | 5,000–15,000 (≈2,000 K, orange) |
| Car headlight | 1,000–1,500 each (4,300–6,000 K) |
| Campfire | 100–300, flicker (1,700–2,000 K) |
Spot cone: inner 20–35°, outer 40–60° for a natural falloff. Attenuation radius: keep tight (a few hundred cm for practicals) — giant radii cost performance and flatten the scene. Cast-shadow off for pure fill lights.
1,700–1,900 match/candle · 2,700 warm bulb · 3,200 tungsten studio · 3,500 golden hour · 4,300 moonlight-read · 5,600 daylight/flash · 6,500 overcast · 7,500–10,000 shade/blue hour. Warm subject + cool ambient (or inverse) is the cheapest way to make a shot read "lit" instead of "flat".
Auto-exposure fights deterministic lighting reads. For agent-driven work, prefer manual exposure in a PPV:
| Scene | EV100 |
|---|---|
| Bright sun exterior | 14–16 |
| Overcast exterior | 11–13 |
| Golden hour | 10–12 |
| Bright interior (day, windows) | 7–9 |
| Dim practical-lit interior | 4–6 |
| Street at night | 2–4 |
| Moonlit exterior | −2 to 0 |
If you keep auto-exposure instead (Metering: Auto Histogram), clamp it: Min/Max EV100 within ±2 of the target so it can't swim. Symptom table: scene renders black with lights present → EV100 too high for the light levels; blown white → EV100 too low.
UE5 defaults: Lumen GI + Lumen reflections, no lightmass bake needed — lighting is live; just keep "Allow Static Lighting" defaults alone. Critical: Lumen GI only considers lights with Movable mobility. Spawned lights can default to Stationary/Static and then contribute nothing to GI — set Mobility = Movable explicitly on every light you place, and check mobility first when "GI isn't working". Metal/mirror surfaces read correctly only with something to reflect: give the scene a sky and surroundings before judging materials.
| Mood | Sun/Key | Sky | Fog | EV100 | Grade notes |
|---|---|---|---|---|---|
| Crisp noon | 100k lux, pitch −70°, 5,800 K | Real-time capture | 0.005 | 15 | Neutral |
| Golden hour | 10k lux, pitch −8°, 3,200 K | Real-time capture | 0.02 + volumetric | 11 | Warm key, long shadows: rotate yaw for rim/side light |
| Overcast | 10k lux soft, 7,000 K | Dominant | 0.01 | 12 | Low contrast, saturation carries color |
| Night, moonlit | 0.25 lux, 4,300 K + practicals ≈800 lm 2,700 K | Very low | 0.015 | −1 to 1 | Cool ambient vs warm practicals |
| Horror interior | No sun; 1–2 practicals, hard shadows | Minimal | 0.03–0.06 volumetric | 4–5 | Single motivated key, deep blacks |
| Sci-fi corridor | Rect lights 2,000 lm 6,500–8,000 K + colored accents | None | 0.02 volumetric | 6 | Complementary accent pair (cyan/orange) |
Use CineCameraActor (not plain Camera) for anything presentational — it has real filmback/lens/DoF controls.
| Intent | Focal length | Aperture |
|---|---|---|
| Establishing / interior wide | 18–28 mm | f/5.6–8 |
| Neutral "human eye" | 35–50 mm | f/4 |
| Portrait / subject isolation | 85–135 mm | f/1.4–2.8 |
| Compression (stacked background) | 100–200 mm | f/2.8–5.6 |
HighResShot 1 (viewport res),
HighResShot 2 (2×), or HighResShot 3840x2160. Output:
<Project>/Saved/Screenshots/<Platform>/. Filenames auto-increment
(HighresScreenshot00000.png).vision_analyze every
capture against the brief.Custom toolsets and any shipped Python-execution tool speak the unreal
module. Canonical entry points (verify names against the live editor —
Epic migrates libraries to subsystems over time):
import unreal
# Actors (EditorActorSubsystem supersedes EditorLevelLibrary for these)
eas = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
actors = eas.get_all_level_actors()
actor = eas.spawn_actor_from_class(unreal.PointLight, unreal.Vector(0, 0, 200))
mesh_a = eas.spawn_actor_from_object(
unreal.EditorAssetLibrary.load_asset("/Engine/BasicShapes/Cube.Cube"),
unreal.Vector(0, 0, 50))
actor.set_actor_label("Key Light")
actor.set_actor_location(unreal.Vector(100, 0, 250), False, True)
actor.set_actor_rotation(unreal.Rotator(0, -30, 45), True) # roll, pitch, yaw
eas.destroy_actor(actor)
# Assets
unreal.EditorAssetLibrary.does_asset_exist("/Game/Props/SM_Chair")
unreal.EditorAssetLibrary.list_assets("/Game/Props", recursive=True)
unreal.EditorAssetLibrary.save_directory("/Game", only_if_is_dirty=True)
# Level save
les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
les.save_current_level()
# Undo-friendly mutation
with unreal.ScopedEditorTransaction("Agent: dress set") as trans:
... # property edits inside are one undo step
# Import (FBX/textures)
task = unreal.AssetImportTask()
task.filename = "/abs/path/model.fbx"
task.destination_path = "/Game/Imported"
task.automated = True # suppresses the import dialog — critical for MCP
task.save = True
unreal.AssetToolsHelpers.get_asset_tools().import_asset_tasks([task])
# Editor property access works on anything reflected
light_comp = actor.get_component_by_class(unreal.PointLightComponent)
light_comp.set_editor_property("intensity", 800.0)
light_comp.set_editor_property("use_temperature", True)
light_comp.set_editor_property("temperature", 2700.0)
set_editor_property/get_editor_property with snake_case names is the
universal fallback when a dedicated setter doesn't exist — property names
match what the Details panel shows (spaces removed).