281 lines
12 KiB
Markdown
281 lines
12 KiB
Markdown
# 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):
|
||
|
||
```python
|
||
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).
|