aiturk-hermes-ide/optional-skills/creative/unreal-mcp/references/scene-craft.md

Unreal MCP — Scene-Craft Cheat Sheet

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.

Units & Conventions (bedrock — memorize)

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.

Human-scale reference (sanity-check every layout against these)

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.

Content Paths

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.

Lighting — physically based values

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.

Sun (DirectionalLight, lux)

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.

Sky light

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).

Local lights (point/spot/rect)

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.

Color temperature vocabulary (Kelvin)

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".

Exposure (PostProcessVolume — the #1 "why is it black/white" knob)

Auto-exposure fights deterministic lighting reads. For agent-driven work, prefer manual exposure in a PPV:

1. Spawn/locate a PostProcessVolume, set Infinite Extent (Unbound) = true.
2. Metering Mode = Manual, then set Exposure Compensation ≈ 0 and EV100 to the scene value:

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.

Global illumination & reflections

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.

Fog & atmosphere

• SkyAtmosphere for a physically-plausible sky (sun disk, horizon gradient); pairs with directional light "Atmosphere Sun Light = true".
• ExponentialHeightFog: density default 0.02. ≈ Practical ranges: 0.005–0.015 subtle depth cue · 0.02–0.05 moody/morning · 0.05–0.2 heavy. Enable Volumetric Fog on it for light shafts through it; then dial per-light "Volumetric Scattering Intensity" (1–10) on the key lights.
• VolumetricCloud for real sky clouds (exterior only; costs GPU).
• Night sky: drop fog density, add faint cool fill (skylight at low intensity) so shadows aren't pure black.

Mood recipes (compact)

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)

Camera & framing (CineCameraActor)

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

• Filmback: default 16:9 digital film (≈23.76 × 13.365 mm) is fine; leave it.
• Focus: Manual focus distance = distance camera→subject in cm; shallow DoF needs long lens + wide aperture + subject far from background.
• Placement: eye-level ≈ 155–170 cm for neutral shots; below ≈ 100 cm = heroic/imposing; high angle = diminishing. Keep the horizon off dead-center; put subjects on thirds. Slight camera pitch (−2° to −8°) usually beats perfectly level for interiors.
• Aspect/eye candy: enable camera's "Constrain Aspect Ratio" for clean letterboxed stills.

Capture & render

• Viewport screenshot: console HighResShot 1 (viewport res), HighResShot 2 (2×), or HighResShot 3840x2160. Output: <Project>/Saved/Screenshots/<Platform>/. Filenames auto-increment (HighresScreenshot00000.png).
• To frame from a camera: pilot/possess the CineCamera (or set viewport to its view) before HighResShot; verify by screenshotting first at 1×.
• Movie Render Queue (MRQ) is the quality path for finals/sequences: needs a Level Sequence with the camera bound (Camera Cut track); renders PNG/EXR sequences or stills at arbitrary resolution with anti-aliasing temporal sample counts. First render after opening a project stalls on shader compilation — warn the user, don't declare it hung.
• Judge results by looking: read the file back and vision_analyze every capture against the brief.

Editor Python quick reference

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).