Photoreal Blender scenes from a one-paragraph brief, built by AI agents: image→3D props on fal, scripted layout, lighting, camera and grade.
Python
"""Rebuild an AnyScene export (export_blend.py -> scene.json + GLBs + baked textures) as an Unreal level.
Headless (no editor window), from a shell:
UnrealEditor-Cmd.exe <project>.uproject -run=pythonscript -script="<path>/build_level.py" -unattended -nosplash -nop4
Configuration comes from environment variables (the pythonscript commandlet does not pass script args reliably):
ANYSCENE_EXPORT export folder holding scene.json (required)
ANYSCENE_DEST content root, default /Game/AnyScene/HK
ANYSCENE_LEVEL level name, default L_HK
ANYSCENE_STAGES comma list of: textures,meshes,materials,level,spawn,fx,sequences (default: all; "lighttex" is part of
textures: gobo images and IES profiles)
ANYSCENE_ONLY comma list of asset names to (re)import (testing)
ANYSCENE_NANITE_TRIS Nanite on for meshes above this triangle count (default 2000; glass meshes never)
ANYSCENE_MESH_BATCH Interchange imports in flight per wait (default 16; lower it when memory is tight)
ANYSCENE_EXPOSURE_OFFSET extra EV added to the computed manual exposure (calibration)
ANYSCENE_COLLIDE_MIN_CM props smaller than this (largest dimension, cm) get no collision (default 25)
ANYSCENE_PLAYERSTART "keep" = the spawn stage leaves an existing PlayerStart alone (collision only)
ANYSCENE_HERO PlayerStart camera (alias ANYSCENE_HERO_CAM); default the .blend's active camera, then cam_street
ANYSCENE_LOOK JSON {"pp": {...}, "light": {...}} overriding the real-time look settings (LOOK below)
ANYSCENE_FX_TYPES Niagara effect types to place (default "steam,fire,rain"; "all" = every classified type, see NIAGARA.md)
ANYSCENE_FX_OVERRIDES optional JSON {fx id | "type:<type>": {UserParam: value}} applied on top of scene.json fx params
(look-match tuning; TOGGLE.md "overrides.json")
ANYSCENE_CLIP_FRAMES length of the MRQ_Clip config and of every camera sequence (default 96 = 4 s at 24 fps)
ANYSCENE_DOLLY "camA>camB:frames[:name]" (or "camA>fwd150:frames") ;-separated: extra moving-camera sequences
ANYSCENE_MRQ_RES WxH for the MRQ configs (default the scene's render resolution)
ANYSCENE_MRQ_OUT MRQ output folder (default <export>/../compare/mrq)
ANYSCENE_REPORT build report path (default <export>/build_report.json)
Assets that already exist are reused (delete the folder to force a reimport). The level is rebuilt from scratch.
"""
import json
import math
import os
import time
import unreal
import warnings
warnings.simplefilter("ignore", DeprecationWarning) # UE turns deprecated-property warnings into exceptions
EXPORT = os.environ.get("ANYSCENE_EXPORT", "")
DEST = os.environ.get("ANYSCENE_DEST", "/Game/AnyScene/HK")
LEVEL = os.environ.get("ANYSCENE_LEVEL", "L_HK")
STAGES = os.environ.get("ANYSCENE_STAGES", "textures,meshes,materials,level,spawn,fx,sequences").split(",")
ONLY = set(x for x in os.environ.get("ANYSCENE_ONLY", "").split(",") if x)
NANITE_TRIS = int(os.environ.get("ANYSCENE_NANITE_TRIS", "2000"))
MESH_BATCH = int(os.environ.get("ANYSCENE_MESH_BATCH", "16")) # Interchange imports in flight per wait (memory)
EXPO_OFF = float(os.environ.get("ANYSCENE_EXPOSURE_OFFSET", "0"))
FX_OVR = json.load(open(os.environ["ANYSCENE_FX_OVERRIDES"])) if os.environ.get("ANYSCENE_FX_OVERRIDES") else {}
CLIP_FRAMES = int(os.environ.get("ANYSCENE_CLIP_FRAMES", "96"))
# Niagara effect types the fx stage places (light flicker is always keyed). Steam, fire (round-2 pack) and rain are
# verified in renders; drips, dust, sparks, smoke and fountain stay opt-in until a scene verifies them ("all" = every
# type). See CHANGELOG.md "Fx: fire and rain on by default".
FX_TYPES = set(x for x in os.environ.get("ANYSCENE_FX_TYPES", "steam,fire,rain").split(",") if x)
# Real-time look settings written into every level (grade post-process volume and lights), so they travel with the
# level into any project. ANYSCENE_LOOK='{"pp": {...}, "light": {...}}' overrides single keys (calibration runs).
LOOK = {
"pp": {
# Mirror-quality Lumen reflections on the front glass layer (otherwise only the blurry radiance cache).
"lumen_front_layer_translucency_reflections": True,
# Tight interiors: small props (cups, bottles, stools) get Lumen cards and occlude GI; fewer final gather
# leaks and less noise in corners. Defaults are 1.0.
"lumen_scene_detail": 2.0,
"lumen_final_gather_quality": 2.0,
},
"light": {},
# Glass (master_glass / glass_params): share of (IOR - 1) used as screen-space refraction on solid glass, and
# the translucency pass ("before_dof" | "after_dof").
"glass": {"refraction_scale": 0.35, "pass": "before_dof"},
}
# Blender AgX looks (datafiles/colormanagement/config.ocio): GradingPrimary, log style, contrast around middle grey
# + saturation. UE's ColorContrast is the same operation (pow(x / 0.18, c) in scene linear, before the tone curve).
# UE's default filmic curve already matches AgX *High Contrast* (fitted on a grey ramp, -5..+2.5 stops: best UE
# contrast 0.99, rms 2/255), so each look maps to contrast c_look / 1.4 (Base 0.71, Medium High 0.86, Very High 1.12;
# every fit within ~2/255). Base Contrast scenes were rendered ~40% too contrasty before.
AGX_LOOKS = {"Very High Contrast": (1.57, 0.9), "High Contrast": (1.4, 0.95), "Medium High Contrast": (1.2, 1.0),
"Base Contrast": (1.0, 1.0), "None": (1.0, 1.0), "Medium Low Contrast": (0.9, 1.05),
"Low Contrast": (0.8, 1.1), "Very Low Contrast": (0.7, 1.15)}
UE_FILMIC_AGX_CONTRAST = 1.4
for _k, _v in json.loads(os.environ.get("ANYSCENE_LOOK", "{}")).items():
LOOK[_k].update(_v)
EAL = unreal.EditorAssetLibrary
MEL = unreal.MaterialEditingLibrary
AT = unreal.AssetToolsHelpers.get_asset_tools()
T0 = time.time()
REPORT = {"warnings": [], "timings": {}}
KEEP = []
def log(*a):
unreal.log_warning("ANYSCENE " + " ".join(str(x) for x in a))
def warn(msg):
REPORT["warnings"].append(msg)
log("WARN", msg)
scene = json.load(open(os.path.join(EXPORT, "scene.json"), encoding="utf-8"))
ASSETS = [a for a in scene["assets"] if not ONLY or a["asset"] in ONLY]
# ------------------------------------------------------------------ textures
def tex_path(name):
return f"{DEST}/Tex/{name}"
def import_files(files, dest):
tasks = []
for f in files:
t = unreal.AssetImportTask()
t.filename = f
t.destination_path = dest
t.automated = True
t.save = False
t.replace_existing = True
tasks.append(t)
if tasks:
AT.import_asset_tasks(tasks)
return tasks
def stage_textures():
t = time.time()
todo = []
for a in ASSETS:
for ch, rel in a.get("tex", {}).items():
n = os.path.splitext(os.path.basename(rel))[0]
if not EAL.does_asset_exist(tex_path(n)):
todo.append((os.path.join(EXPORT, rel), ch, n))
lut = scene["grade"].get("ffmpeg", {}).get("lut")
extra = []
if lut and not EAL.does_asset_exist(tex_path("lut_grade")):
extra.append(os.path.join(EXPORT, lut))
sky = (scene.get("world") or {}).get("equirect_exr")
if sky and not EAL.does_asset_exist(tex_path("sky")):
extra.append(os.path.join(EXPORT, sky))
log(f"textures: importing {len(todo)} (+{len(extra)} extra)")
for i in range(0, len(todo), 64):
chunk = todo[i:i + 64]
import_files([f for f, _, _ in chunk], f"{DEST}/Tex")
for f, ch, n in chunk:
tx = EAL.load_asset(tex_path(n))
if tx is None:
warn(f"texture import failed {f}")
continue
if ch == "orm":
tx.set_editor_property("srgb", False)
tx.set_editor_property("compression_settings", unreal.TextureCompressionSettings.TC_MASKS)
elif ch == "normal":
tx.set_editor_property("srgb", False)
tx.set_editor_property("compression_settings", unreal.TextureCompressionSettings.TC_NORMALMAP)
tx.set_editor_property("flip_green_channel", True) # Blender bakes OpenGL (+Y) normals
else:
tx.set_editor_property("srgb", True)
EAL.save_loaded_asset(tx, False)
# 4K bakes: without a GC per chunk the commandlet held every imported texture and ran out of memory
# (~550 of 796 on a 32 GB box shared with other editors).
unreal.SystemLibrary.collect_garbage()
log(f"textures {min(i + 64, len(todo))}/{len(todo)} ({time.time() - t:.0f}s)")
# A crash inside a chunk leaves imported textures without their settings: re-check the linear channels.
fixed = 0
lin = [(ch, tex_path(os.path.splitext(os.path.basename(rel))[0])) for a in ASSETS for ch, rel in a.get("tex", {}).items() if ch in ("orm", "normal")]
for k, (ch, p) in enumerate(lin):
d = unreal.EditorAssetLibrary.find_asset_data(p)
if not d.is_valid():
continue
tx = d.get_asset()
if tx and tx.get_editor_property("srgb"):
tx.set_editor_property("srgb", False)
tx.set_editor_property("compression_settings", unreal.TextureCompressionSettings.TC_MASKS if ch == "orm" else unreal.TextureCompressionSettings.TC_NORMALMAP)
if ch == "normal":
tx.set_editor_property("flip_green_channel", True)
EAL.save_loaded_asset(tx, False)
fixed += 1
if k % 64 == 63:
unreal.SystemLibrary.collect_garbage()
if fixed:
log(f"textures: fixed settings on {fixed} linear textures")
stage_light_textures()
if extra:
import_files(extra, f"{DEST}/Tex")
l = EAL.load_asset(tex_path("lut_grade"))
if l:
l.set_editor_property("lod_group", unreal.TextureGroup.TEXTUREGROUP_COLOR_LOOKUP_TABLE)
l.set_editor_property("compression_settings", unreal.TextureCompressionSettings.TC_VECTOR_DISPLACEMENTMAP)
l.set_editor_property("srgb", False)
l.set_editor_property("mip_gen_settings", unreal.TextureMipGenSettings.TMGS_NO_MIPMAPS)
EAL.save_loaded_asset(l, False)
s = EAL.load_asset(tex_path("sky"))
if s:
EAL.save_loaded_asset(s, False)
REPORT["timings"]["textures_s"] = round(time.time() - t)
def gobo_tex_path(rel):
return f"{DEST}/Gobo/{os.path.splitext(os.path.basename(rel.replace(chr(92), '/')))[0]}"
def ies_path(rel):
return f"{DEST}/IES/{os.path.splitext(os.path.basename(rel.replace(chr(92), '/')))[0]}"
def stage_light_textures():
"""Gobo images (linear grayscale, wrapping) and IES profiles (TextureLightProfile) referenced by the lights."""
gobos, ies = {}, {}
for L in scene["lights"]:
for lay in (L.get("gobo_fx") or {}).get("layers", []):
gobos[gobo_tex_path(lay["image"])] = lay
if L.get("ies_file"):
ies[ies_path(L["ies_file"])] = L["ies_file"]
todo = [os.path.join(EXPORT, lay["image"]) for p, lay in gobos.items() if not EAL.does_asset_exist(p)]
if todo:
import_files(todo, f"{DEST}/Gobo")
for p, lay in gobos.items():
tx = EAL.load_asset(p)
if tx is None:
warn(f"gobo import failed {lay['image']}")
continue
lin = lay.get("colorspace", "Non-Color") in ("Non-Color", "Linear Rec.709", "Raw")
tx.set_editor_property("srgb", not lin)
tx.set_editor_property("compression_settings", unreal.TextureCompressionSettings.TC_GRAYSCALE)
wrap = unreal.TextureAddress.TA_WRAP if lay.get("extension", "REPEAT") == "REPEAT" else unreal.TextureAddress.TA_CLAMP
tx.set_editor_property("address_x", wrap)
tx.set_editor_property("address_y", wrap)
tx.set_editor_property("lod_group", unreal.TextureGroup.TEXTUREGROUP_EFFECTS)
EAL.save_loaded_asset(tx, False)
todo = [os.path.join(EXPORT, f) for p, f in ies.items() if not EAL.does_asset_exist(p)]
if todo:
import_files(todo, f"{DEST}/IES")
for p, f in ies.items():
prof = EAL.load_asset(p) if EAL.does_asset_exist(p) else None
if prof is None:
warn(f"IES import failed {f}")
continue
EAL.save_loaded_asset(prof, False) # import tasks run with save=False
log(f"light textures: {len(gobos)} gobo images, {len(ies)} IES profiles")
# ------------------------------------------------------------------ meshes
def mesh_folder(a):
return f"{DEST}/Meshes/{a['asset']}"
def find_mesh(a):
for p in EAL.list_assets(mesh_folder(a), recursive=True, include_folder=False):
d = unreal.EditorAssetLibrary.find_asset_data(p)
if d.asset_class_path.asset_name == "StaticMesh":
return EAL.load_asset(p)
return None
def pipeline_for(a):
p = unreal.InterchangeGenericAssetsPipeline()
mp = p.get_editor_property("mesh_pipeline")
mp.set_editor_property("import_static_meshes", True)
mp.set_editor_property("import_skeletal_meshes", False)
mp.set_editor_property("build_nanite", a["tris"] > NANITE_TRIS and not a.get("glass"))
mp.set_editor_property("generate_lightmap_u_vs", False)
try:
mp.set_editor_property("collision", False)
except Exception:
pass
mat = p.get_editor_property("material_pipeline")
mat.set_editor_property("import_materials", False)
try:
tp = mat.get_editor_property("texture_pipeline")
tp.set_editor_property("import_textures", False)
except Exception as ex: # noqa: BLE001
log("texture pipeline", ex)
cm = p.get_editor_property("common_meshes_properties")
cm.set_editor_property("recompute_normals", False)
cm.set_editor_property("recompute_tangents", False)
cm.set_editor_property("use_mikk_t_space", True)
cm.set_editor_property("remove_degenerates", False)
return p
def stage_meshes():
t = time.time()
im = unreal.InterchangeManager.get_interchange_manager_scripted()
todo = [a for a in ASSETS if find_mesh(a) is None]
log(f"meshes: importing {len(todo)} of {len(ASSETS)}")
def queue(a):
src = im.create_source_data(os.path.join(EXPORT, a["glb"]))
prm = unreal.ImportAssetParameters()
prm.is_automated = True
prm.replace_existing = True
pipe = pipeline_for(a)
KEEP.append(pipe) # soft path to a transient pipeline: keep it alive until the import is done
prm.override_pipelines = [unreal.SoftObjectPath(pipe.get_path_name())]
im.import_asset(mesh_folder(a), src, prm)
def flush(last):
# UE 5.8 commandlet: the import queued last before wait_until_all_tasks_done() logs "start importing" and
# never completes (1 in 16 meshes went missing). Queue the last asset a second time as a sacrificial
# sentinel so the real import of it completes.
queue(last)
im.wait_until_all_tasks_done(True)
for i, a in enumerate(todo):
queue(a)
if i % MESH_BATCH == MESH_BATCH - 1 or i == len(todo) - 1:
flush(a)
unreal.SystemLibrary.collect_garbage()
log(f"meshes {i + 1}/{len(todo)} ({time.time() - t:.0f}s)")
for attempt in range(2):
miss = [a for a in ASSETS if find_mesh(a) is None]
if not miss:
break
log(f"meshes: retry {len(miss)} missing (pass {attempt + 1})")
for a in miss:
queue(a)
flush(miss[-1])
# Orientation check against the exporter's expected local bounds.
checks = []
for a in ASSETS[:40]:
sm = find_mesh(a)
if sm is None:
warn(f"mesh missing after import: {a['asset']}")
continue
bb = sm.get_bounding_box()
got = [bb.min.x, bb.min.y, bb.min.z, bb.max.x, bb.max.y, bb.max.z]
exp = a["check_bounds"]["min"] + a["check_bounds"]["max"]
exp = [min(exp[0], exp[3]), min(exp[1], exp[4]), min(exp[2], exp[5]), max(exp[0], exp[3]), max(exp[1], exp[4]), max(exp[2], exp[5])]
err = max(abs(g - e) for g, e in zip(got, exp))
checks.append(err)
if err > 2.0:
warn(f"bounds mismatch {a['asset']}: got {[round(x, 1) for x in got]} expected {[round(x, 1) for x in exp]}")
REPORT["orientation_max_err_cm"] = max(checks) if checks else None
for a in ASSETS:
sm = find_mesh(a)
if sm:
EAL.save_loaded_asset(sm, False)
REPORT["timings"]["meshes_s"] = round(time.time() - t)
# ------------------------------------------------------------------ materials
def master_baked(masked=False):
"""M_AnyBaked (opaque) or M_AnyBakedMasked: same graph, opacity mask = ORM.R (baked Principled Alpha)."""
name = "M_AnyBakedMasked" if masked else "M_AnyBaked"
path = f"{DEST}/Materials/{name}"
if EAL.does_asset_exist(path):
return EAL.load_asset(path)
m = AT.create_asset(name, f"{DEST}/Materials", unreal.Material, unreal.MaterialFactoryNew())
def tex(name, x, y, default, stype):
n = MEL.create_material_expression(m, unreal.MaterialExpressionTextureSampleParameter2D, x, y)
n.set_editor_property("parameter_name", name)
n.set_editor_property("texture", unreal.load_asset(default))
n.set_editor_property("sampler_type", stype)
return n
m.set_editor_property("used_with_nanite", True)
bc = tex("BaseColor", -600, -200, "/Engine/EngineResources/WhiteSquareTexture", unreal.MaterialSamplerType.SAMPLERTYPE_COLOR)
# The ORM default must itself be a linear TC_MASKS texture: an sRGB default (WhiteSquareTexture) fails the
# master's compile ("Sampler type is Masks, should be Color") and every instance silently falls back to the
# default grid material, while Nanite meshes using it vanish.
orm_default = next((tex_path(os.path.splitext(os.path.basename(a["tex"]["orm"]))[0]) for a in scene["assets"]
if a.get("tex", {}).get("orm") and EAL.does_asset_exist(tex_path(os.path.splitext(os.path.basename(a["tex"]["orm"]))[0]))), None)
orm = tex("ORM", -600, 50, orm_default or "/Engine/EngineResources/WhiteSquareTexture", unreal.MaterialSamplerType.SAMPLERTYPE_MASKS)
nrm = tex("Normal", -600, 300, "/Engine/EngineMaterials/DefaultNormal", unreal.MaterialSamplerType.SAMPLERTYPE_NORMAL)
em = tex("Emissive", -600, 550, "/Engine/EngineResources/Black", unreal.MaterialSamplerType.SAMPLERTYPE_COLOR)
es = MEL.create_material_expression(m, unreal.MaterialExpressionScalarParameter, -600, 800)
es.set_editor_property("parameter_name", "EmissiveScale")
es.set_editor_property("default_value", 0.0)
mul = MEL.create_material_expression(m, unreal.MaterialExpressionMultiply, -250, 600)
MEL.connect_material_expressions(em, "RGB", mul, "A")
MEL.connect_material_expressions(es, "", mul, "B")
MEL.connect_material_property(bc, "RGB", unreal.MaterialProperty.MP_BASE_COLOR)
MEL.connect_material_property(orm, "G", unreal.MaterialProperty.MP_ROUGHNESS)
MEL.connect_material_property(orm, "B", unreal.MaterialProperty.MP_METALLIC)
MEL.connect_material_property(nrm, "RGB", unreal.MaterialProperty.MP_NORMAL)
MEL.connect_material_property(mul, "", unreal.MaterialProperty.MP_EMISSIVE_COLOR)
m.set_editor_property("two_sided", True) # generated props and single planes (signs, facades) are often open
if masked:
m.set_editor_property("blend_mode", unreal.BlendMode.BLEND_MASKED)
# (MaterialExpressionDitherTemporalAA is not exposed to Python in 5.8: plain clip.)
m.set_editor_property("opacity_mask_clip_value", 0.33)
MEL.connect_material_property(orm, "R", unreal.MaterialProperty.MP_OPACITY_MASK)
MEL.recompile_material(m)
EAL.save_loaded_asset(m, False)
return m
def master_asset(name, version=1):
"""Get or create a master material. Returns (material, build): build is True when the graph must be (re)made.
A master whose AnySceneVersion tag is older than `version` is rebuilt in place (all expressions deleted), so
the instances and meshes that reference it keep working; untagged masters count as version 1."""
path = f"{DEST}/Materials/{name}"
if EAL.does_asset_exist(path):
m = EAL.load_asset(path)
if int(EAL.get_metadata_tag(m, "AnySceneVersion") or 1) >= version:
return m, False
MEL.delete_all_material_expressions(m)
log(f"{name}: rebuilding master in place (v{version})")
else:
m = AT.create_asset(name, f"{DEST}/Materials", unreal.Material, unreal.MaterialFactoryNew())
EAL.set_metadata_tag(m, "AnySceneVersion", str(version))
return m, True
GLASS_VERSION = 2 # bump when the graph changes: older masters are rebuilt in place
def master_glass():
"""Thin-translucent glass (legacy shading, no Substrate needed): a Fresnel-weighted specular layer (lit, with
Lumen front-layer reflections) over a coloured transmittance that tints what is behind it, like Cycles'
transmission. The old diffuse-lit translucent master read as milky plastic: white glass took light like paint.
Transmittance colour per pass (Blender glass colour); thicker at grazing angles (1/NoV)
Specular F0 / 0.08 from the IOR (0.5 at IOR 1.5)
Roughness Blender roughness; Lumen blurs the reflection, the background stays sharp (no transmission blur)
Opacity frost layer coverage: 0 for clear glass, up to ~0.35 for rough glass (FrostColor, diffuse-lit)
Refraction IOR for solid glass (water glasses, bottles, domes); 1 = none for thin panes and windows"""
m, build = master_asset("M_AnyGlass", GLASS_VERSION)
if not build:
return m
m.set_editor_property("blend_mode", unreal.BlendMode.BLEND_TRANSLUCENT)
m.set_editor_property("shading_model", unreal.MaterialShadingModel.MSM_THIN_TRANSLUCENT)
# Thin translucency requires "Surface ForwardShading", which is TLM_SURFACE_PER_PIXEL_LIGHTING in Python
# (TLM_SURFACE is "Surface TranslucencyVolume": the master then fails to compile and renders as the grey default).
m.set_editor_property("translucency_lighting_mode", unreal.TranslucencyLightingMode.TLM_SURFACE_PER_PIXEL_LIGHTING)
m.set_editor_property("two_sided", True)
m.set_editor_property("refraction_method", unreal.RefractionMode.RM_INDEX_OF_REFRACTION)
# Before DOF (the 5.8 default is after): glass in a defocused plane blurs with what is behind it (macro shots).
tpass = {"before_dof": unreal.MaterialTranslucencyPass.MTP_BEFORE_DOF, "after_dof": unreal.MaterialTranslucencyPass.MTP_AFTER_DOF}
for k, v in (("allow_front_layer_translucency", True), ("translucency_pass", tpass[LOOK["glass"]["pass"]])):
try:
m.set_editor_property(k, v)
except Exception as ex: # noqa: BLE001
warn(f"M_AnyGlass: {k}: {ex}")
def p(cls, name, v, y):
n = MEL.create_material_expression(m, cls, -500, y)
n.set_editor_property("parameter_name", name)
n.set_editor_property("default_value", v)
return n
tr = p(unreal.MaterialExpressionVectorParameter, "Transmittance", unreal.LinearColor(1, 1, 1, 1), 0)
fc = p(unreal.MaterialExpressionVectorParameter, "FrostColor", unreal.LinearColor(0.8, 0.8, 0.8, 1), -200)
r = p(unreal.MaterialExpressionScalarParameter, "Roughness", 0.02, 200)
sp = p(unreal.MaterialExpressionScalarParameter, "Specular", 0.5, 300)
o = p(unreal.MaterialExpressionScalarParameter, "Opacity", 0.0, 400)
rf = p(unreal.MaterialExpressionScalarParameter, "Refraction", 1.0, 500)
MEL.connect_material_property(fc, "", unreal.MaterialProperty.MP_BASE_COLOR)
MEL.connect_material_property(r, "", unreal.MaterialProperty.MP_ROUGHNESS)
MEL.connect_material_property(sp, "", unreal.MaterialProperty.MP_SPECULAR)
MEL.connect_material_property(o, "", unreal.MaterialProperty.MP_OPACITY)
MEL.connect_material_property(rf, "", unreal.MaterialProperty.MP_REFRACTION)
out = MEL.create_material_expression(m, unreal.MaterialExpressionThinTranslucentMaterialOutput, -100, 0)
MEL.connect_material_expressions(tr, "", out, "TransmittanceColor")
MEL.recompile_material(m)
EAL.save_loaded_asset(m, False)
return m
def glass_params(a, g):
"""M_AnyGlass instance values for one Blender glass slot (see master_glass)."""
b = a.get("check_bounds")
thin = b is not None and min(abs(b["max"][i] - b["min"][i]) for i in range(3)) < 2.5 # panes, windows, doors
ior = g.get("ior", 1.5)
rough = g["roughness"]
return {"Transmittance": g["color"][:3], "FrostColor": [0.8 * x for x in g["color"][:3]],
"Roughness": max(rough, 0.02),
"Specular": min(1.0, ((ior - 1) / (ior + 1)) ** 2 / 0.08),
"Opacity": min(0.35, max(0.0, 0.7 * (rough - 0.05))),
# Refraction in IOR mode bends the screen-space background by the surface normal; full strength smears
# whole cups, a third of (IOR - 1) keeps the edge darkening/bending that makes solid glass read as glass.
"Refraction": 1.0 if thin else 1.0 + (ior - 1.0) * LOOK["glass"]["refraction_scale"], "thin": thin}
def master_sky():
"""Unlit sky dome: equirect texture looked up by view direction (Blender world, +Y at the image centre)."""
path = f"{DEST}/Materials/M_AnySky"
if EAL.does_asset_exist(path):
return EAL.load_asset(path)
m = AT.create_asset("M_AnySky", f"{DEST}/Materials", unreal.Material, unreal.MaterialFactoryNew())
m.set_editor_property("shading_model", unreal.MaterialShadingModel.MSM_UNLIT)
# IsSky: the real-time sky light capture only sees sky-flagged materials, and without it the editor/-game
# build stamps "YOUR SCENE CONTAINS A SKYDOME MESH WITH A SKY MATERIAL..." over every uncovered pixel.
m.set_editor_property("is_sky", True)
m.set_editor_property("two_sided", True)
cv = MEL.create_material_expression(m, unreal.MaterialExpressionCameraVectorWS, -900, 0)
cu = MEL.create_material_expression(m, unreal.MaterialExpressionCustom, -650, 0)
cu.set_editor_property("code", "float3 d = -normalize(V); float3 b = float3(d.x, -d.y, d.z);\n"
"float u = atan2(b.y, -b.x) / (2*3.14159265) + 0.5; float v = acos(clamp(b.z,-1,1)) / 3.14159265;\n"
"return float2(frac(u + 0.25), v);")
cu.set_editor_property("output_type", unreal.CustomMaterialOutputType.CMOT_FLOAT2)
ci = unreal.CustomInput()
ci.set_editor_property("input_name", "V")
cu.set_editor_property("inputs", [ci])
MEL.connect_material_expressions(cv, "", cu, "V")
tx = MEL.create_material_expression(m, unreal.MaterialExpressionTextureSampleParameter2D, -350, 0)
tx.set_editor_property("parameter_name", "Sky")
sky = EAL.load_asset(tex_path("sky"))
if sky:
tx.set_editor_property("texture", sky)
tx.set_editor_property("sampler_type", unreal.MaterialSamplerType.SAMPLERTYPE_LINEAR_COLOR)
MEL.connect_material_expressions(cu, "", tx, "UVs")
sc = MEL.create_material_expression(m, unreal.MaterialExpressionScalarParameter, -350, 250)
sc.set_editor_property("parameter_name", "Scale")
sc.set_editor_property("default_value", 683.0)
mul = MEL.create_material_expression(m, unreal.MaterialExpressionMultiply, -100, 50)
MEL.connect_material_expressions(tx, "RGB", mul, "A")
MEL.connect_material_expressions(sc, "", mul, "B")
MEL.connect_material_property(mul, "", unreal.MaterialProperty.MP_EMISSIVE_COLOR)
MEL.recompile_material(m)
EAL.save_loaded_asset(m, False)
return m
GOBO_CH = ("LocX", "LocY", "Rot", "ScaleX", "ScaleY")
GOBO_KEYS = {"LocX": "loc_x", "LocY": "loc_y", "Rot": "rot", "ScaleX": "scale_x", "ScaleY": "scale_y"}
def mpc_time():
"""Material parameter collection holding the gobo clock: GoboUseSeq = 0 -> real time (Time node + per-light
TimeOffset); 1 -> GoboTime, keyed by the level sequences so MRQ frames land on the exact Blender frame."""
path = f"{DEST}/Materials/MPC_AnyTime"
if EAL.does_asset_exist(path):
return EAL.load_asset(path)
m = AT.create_asset("MPC_AnyTime", f"{DEST}/Materials", unreal.MaterialParameterCollection, unreal.MaterialParameterCollectionFactoryNew())
ps = []
for n in ("GoboTime", "GoboUseSeq"):
p = unreal.CollectionScalarParameter()
p.set_editor_property("parameter_name", n)
p.set_editor_property("default_value", 0.0)
ps.append(p)
m.set_editor_property("scalar_parameters", ps)
EAL.save_loaded_asset(m, False)
return m
def master_gobo():
"""Light-function master for projected-texture (gobo) spots, matching Blender's TexCoord-Normal x/z, y/z
projector: two texture layers, each with Mapping location / Z rotation / scale animated as
c0 + v t + A1 sin(2 pi f1 t + p1) + A2 sin(2 pi f2 t + p2) (per channel: vector params <L>_<Ch> = (c0, v, A1, f1)
and <L>_<Ch>P = (p1, A2, f2, p2)), combined as Gain * (WA a + WB b + Bias)^Gamma, divided by Peak (light
functions are clamped to 0..1; the light's intensity carries the peak)."""
path = f"{DEST}/Materials/M_AnyGobo"
if EAL.does_asset_exist(path):
return EAL.load_asset(path)
m = AT.create_asset("M_AnyGobo", f"{DEST}/Materials", unreal.Material, unreal.MaterialFactoryNew())
m.set_editor_property("material_domain", unreal.MaterialDomain.MD_LIGHT_FUNCTION)
mpc = mpc_time()
gobo_default = next((EAL.load_asset(gobo_tex_path(lay["image"])) for L in scene["lights"]
for lay in (L.get("gobo_fx") or {}).get("layers", []) if EAL.does_asset_exist(gobo_tex_path(lay["image"]))), None)
if gobo_default is None:
warn("M_AnyGobo: no imported gobo texture to use as the sampler default")
def scalar(name, v, x, y):
n = MEL.create_material_expression(m, unreal.MaterialExpressionScalarParameter, x, y)
n.set_editor_property("parameter_name", name)
n.set_editor_property("default_value", v)
return n
def vec(name, v, x, y):
n = MEL.create_material_expression(m, unreal.MaterialExpressionVectorParameter, x, y)
n.set_editor_property("parameter_name", name)
n.set_editor_property("default_value", unreal.LinearColor(*v))
return n
# Clock: lerp(Time + TimeOffset, GoboTime, GoboUseSeq)
tm = MEL.create_material_expression(m, unreal.MaterialExpressionTime, -2400, -600)
toff = scalar("TimeOffset", 0.0, -2400, -500)
add = MEL.create_material_expression(m, unreal.MaterialExpressionAdd, -2200, -560)
MEL.connect_material_expressions(tm, "", add, "A")
MEL.connect_material_expressions(toff, "", add, "B")
cps = []
for i, n in enumerate(("GoboTime", "GoboUseSeq")):
c = MEL.create_material_expression(m, unreal.MaterialExpressionCollectionParameter, -2400, -400 + 100 * i)
c.set_editor_property("collection", mpc)
c.set_editor_property("parameter_name", n)
cps.append(c)
lt = MEL.create_material_expression(m, unreal.MaterialExpressionLinearInterpolate, -2000, -500)
MEL.connect_material_expressions(add, "", lt, "A")
MEL.connect_material_expressions(cps[0], "", lt, "B")
MEL.connect_material_expressions(cps[1], "", lt, "Alpha")
uv = MEL.create_material_expression(m, unreal.MaterialExpressionTextureCoordinate, -2400, -800)
tan = scalar("TanOuter", 0.8391, -2400, -700)
def ch(c):
return (f"({c}.x + {c}.y*T + {c}.z*sin(6.2831853*{c}.w*T + {c}P.x) + {c}P.y*sin(6.2831853*{c}P.z*T + {c}P.w))")
code = ("float2 p = (UV * 2.0 - 1.0) * Tan;\n"
"float2 d = float2(-p.y, -p.x); // Blender light-local (x/z, y/z)\n"
f"float lx = {ch('LocX')}; float ly = {ch('LocY')}; float r = {ch('Rot')};\n"
f"float2 s = d * float2({ch('ScaleX')}, {ch('ScaleY')});\n"
"float c = cos(r); float sn = sin(r);\n"
"float2 q = float2(s.x * c - s.y * sn, s.x * sn + s.y * c) + float2(lx, ly);\n"
"return float2(q.x, -q.y); // Blender image v runs bottom-up")
samples = []
defaults = {"LocX": (0, 0, 0, 0), "LocY": (0, 0, 0, 0), "Rot": (0, 0, 0, 0), "ScaleX": (1, 0, 0, 0), "ScaleY": (1, 0, 0, 0)}
camv = MEL.create_material_expression(m, unreal.MaterialExpressionCameraVectorWS, -2400, 300)
lfs = scalar("LFScale", 1024.0, -2400, 400)
srad = scalar("SourceRadius", 0.0, -2400, 500)
pbias = scalar("PenumbraBias", -1.0, -2400, 600)
for li, L in enumerate(("A", "B")):
y0 = li * 1400
cu = MEL.create_material_expression(m, unreal.MaterialExpressionCustom, -1500, y0)
cu.set_editor_property("code", code)
cu.set_editor_property("output_type", unreal.CustomMaterialOutputType.CMOT_FLOAT2)
cu.set_editor_property("description", f"GoboUV_{L}")
names = ["UV", "Tan", "T"] + [n for c in GOBO_CH for n in (c, c + "P")]
ins = []
for n in names:
ci = unreal.CustomInput()
ci.set_editor_property("input_name", n)
ins.append(ci)
cu.set_editor_property("inputs", ins)
MEL.connect_material_expressions(uv, "", cu, "UV")
MEL.connect_material_expressions(tan, "", cu, "Tan")
MEL.connect_material_expressions(lt, "", cu, "T")
vecs = {}
for k, c in enumerate(GOBO_CH):
a = vec(f"{L}_{c}", defaults[c], -1900, y0 + k * 220)
b = vec(f"{L}_{c}P", (0, 0, 0, 0), -1900, y0 + k * 220 + 110)
MEL.connect_material_expressions(a, "RGBA", cu, c)
MEL.connect_material_expressions(b, "RGBA", cu, c + "P")
vecs[c] = a
# Penumbra: Cycles evaluates the gobo from every point of the light's disk, so the pattern blurs by the
# angle SourceRadius / distance (tan units), times the mapping scale in texture space. Light functions are
# point-projected; pick the mip whose texel matches that blur. CameraVector in a light function is the
# light-space vector divided by LightFunctionScale (LightFunctionPixelShader.usf).
mipc = MEL.create_material_expression(m, unreal.MaterialExpressionCustom, -1500, y0 + 1150)
# Blur radius R texels = s * r / d * TexSize. A disk of radius R is roughly a Gaussian of sigma R/2, which
# mip log2(R) - 1 (bilinear) approximates; PenumbraBias (default -1) is the look-match knob.
mipc.set_editor_property("code", "float d = length(LV) * LFScale; if (d < 1.0) return 0.0;\n"
"float s = max(abs(SX.x), abs(SY.x));\n"
"return clamp(log2(max(s * SourceRadius / d * TexSize, 1.0)) + Bias, 0.0, 8.0);")
mipc.set_editor_property("output_type", unreal.CustomMaterialOutputType.CMOT_FLOAT1)
mipc.set_editor_property("description", f"GoboPenumbraMip_{L}")
ins = []
for n in ("LV", "LFScale", "SourceRadius", "TexSize", "SX", "SY", "Bias"):
ci = unreal.CustomInput()
ci.set_editor_property("input_name", n)
ins.append(ci)
mipc.set_editor_property("inputs", ins)
MEL.connect_material_expressions(camv, "", mipc, "LV")
MEL.connect_material_expressions(lfs, "", mipc, "LFScale")
MEL.connect_material_expressions(srad, "", mipc, "SourceRadius")
MEL.connect_material_expressions(scalar(f"TexSize{L}", 2048.0, -1900, y0 + 1250), "", mipc, "TexSize")
MEL.connect_material_expressions(vecs["ScaleX"], "RGBA", mipc, "SX")
MEL.connect_material_expressions(vecs["ScaleY"], "RGBA", mipc, "SY")
MEL.connect_material_expressions(pbias, "", mipc, "Bias")
tx = MEL.create_material_expression(m, unreal.MaterialExpressionTextureSampleParameter2D, -1100, y0)
tx.set_editor_property("parameter_name", f"Tex{L}")
tx.set_editor_property("mip_value_mode", unreal.TextureMipValueMode.TMVM_MIP_LEVEL)
if not MEL.connect_material_expressions(mipc, "", tx, "Level"): # pin is "Level" in TMVM_MIP_LEVEL mode
warn("M_AnyGobo: could not connect the penumbra mip")
# The default must match the sampler type (linear grayscale), or the master fails to compile and every
# light function silently does nothing (same trap as the ORM default in M_AnyBaked).
tx.set_editor_property("texture", gobo_default)
tx.set_editor_property("sampler_type", unreal.MaterialSamplerType.SAMPLERTYPE_LINEAR_GRAYSCALE)
MEL.connect_material_expressions(cu, "", tx, "UVs")
w = scalar(f"W{L}", 0.5, -1100, y0 + 250)
mul = MEL.create_material_expression(m, unreal.MaterialExpressionMultiply, -800, y0)
MEL.connect_material_expressions(tx, "R", mul, "A")
MEL.connect_material_expressions(w, "", mul, "B")
samples.append(mul)
cu = MEL.create_material_expression(m, unreal.MaterialExpressionCustom, -500, 0)
cu.set_editor_property("code", "return saturate(Gain * pow(max(A + B + Bias, 0.0), Gamma) * InvPeak);")
cu.set_editor_property("output_type", unreal.CustomMaterialOutputType.CMOT_FLOAT1)
cu.set_editor_property("description", "GoboCombine")
ins = []
for n in ("A", "B", "Bias", "Gamma", "Gain", "InvPeak"):
ci = unreal.CustomInput()
ci.set_editor_property("input_name", n)
ins.append(ci)
cu.set_editor_property("inputs", ins)
MEL.connect_material_expressions(samples[0], "", cu, "A")
MEL.connect_material_expressions(samples[1], "", cu, "B")
for n, v, yy in (("Bias", 0.0, 300), ("Gamma", 1.0, 400), ("Gain", 1.0, 500), ("InvPeak", 1.0, 600)):
MEL.connect_material_expressions(scalar(n, v, -800, yy), "", cu, n)
MEL.connect_material_property(cu, "", unreal.MaterialProperty.MP_EMISSIVE_COLOR)
MEL.recompile_material(m)
EAL.save_loaded_asset(m, False)
return m
def gobo_mi(L):
"""Material instance of M_AnyGobo for one light's gobo_fx entry."""
g = L["gobo_fx"]
m = mi("MI_Gobo_" + L["name"], master_gobo())
lays = g["layers"][:2]
if len(g["layers"]) > 2:
warn(f"{L['name']}: {len(g['layers'])} gobo layers, master takes 2")
if g.get("coord") != "normal_projective":
warn(f"{L['name']}: gobo coordinates '{g.get('coord')}' approximated as the Normal x/z, y/z projector")
fps = g.get("fps", 24.0)
MEL.set_material_instance_scalar_parameter_value(m, "TanOuter", math.tan(math.radians(L["outer_cone"])))
MEL.set_material_instance_scalar_parameter_value(m, "TimeOffset", scene.get("frame", 0) / fps)
cb = g["combine"]
w = list(cb["weights"][:2]) + [0.0] * (2 - len(lays))
for li, Ln in enumerate(("A", "B")):
lay = lays[min(li, len(lays) - 1)]
tx = EAL.load_asset(gobo_tex_path(lay["image"]))
if tx:
MEL.set_material_instance_texture_parameter_value(m, f"Tex{Ln}", tx)
MEL.set_material_instance_scalar_parameter_value(m, f"W{Ln}", w[li] if li < len(lays) else 0.0)
mp = lay.get("mapping") or {}
for c in GOBO_CH:
e = mp.get(GOBO_KEYS[c]) or {"c0": 1.0 if c.startswith("Scale") else 0.0, "v": 0.0, "sines": []}
s = (e.get("sines") or []) + [[0.0, 0.0, 0.0]] * 2
MEL.set_material_instance_vector_parameter_value(m, f"{Ln}_{c}", unreal.LinearColor(e["c0"], e["v"], s[0][0], s[0][1]))
MEL.set_material_instance_vector_parameter_value(m, f"{Ln}_{c}P", unreal.LinearColor(s[0][2], s[1][0], s[1][1], s[1][2]))
MEL.set_material_instance_scalar_parameter_value(m, "Bias", cb["bias"])
MEL.set_material_instance_scalar_parameter_value(m, "Gamma", cb["gamma"])
MEL.set_material_instance_scalar_parameter_value(m, "Gain", cb["gain"])
MEL.set_material_instance_scalar_parameter_value(m, "InvPeak", 1.0 / max(g["peak"], 1e-6))
MEL.set_material_instance_scalar_parameter_value(m, "SourceRadius", L.get("source_radius", 0.0))
MEL.set_material_instance_scalar_parameter_value(m, "LFScale", 1024.0)
for li, Ln in enumerate(("A", "B")):
lay = lays[min(li, len(lays) - 1)]
MEL.set_material_instance_scalar_parameter_value(m, f"TexSize{Ln}", float(max(lay.get("size") or [2048])))
EAL.save_loaded_asset(m, False)
return m
def mi(name, parent):
path = f"{DEST}/Materials/MI/{name}"
if EAL.does_asset_exist(path):
return EAL.load_asset(path)
f = unreal.MaterialInstanceConstantFactoryNew()
m = AT.create_asset(name, f"{DEST}/Materials/MI", unreal.MaterialInstanceConstant, f)
MEL.set_material_instance_parent(m, parent)
return m
def stage_materials():
t = time.time()
baked, glass = master_baked(), master_glass()
masked = master_baked(masked=True) if any(a.get("alpha") for a in ASSETS) else None
for a in ASSETS:
sm = find_mesh(a)
if sm is None:
continue
m = mi("MI_" + a["asset"], masked if a.get("alpha") else baked)
MEL.set_material_instance_parent(m, masked if a.get("alpha") else baked) # existing MI: reparent
for ch, pname in (("base", "BaseColor"), ("orm", "ORM"), ("normal", "Normal"), ("emit", "Emissive")):
rel = a.get("tex", {}).get(ch)
if rel:
tx = EAL.load_asset(tex_path(os.path.splitext(os.path.basename(rel))[0]))
if tx:
MEL.set_material_instance_texture_parameter_value(m, pname, tx)
if a.get("emissive"):
MEL.set_material_instance_scalar_parameter_value(m, "EmissiveScale", a["emissive_scale"] * scene["lm_per_w"])
EAL.save_loaded_asset(m, False)
mats = [m]
for k, g in enumerate(a.get("glass", [])):
gm = mi(f"MI_{a['asset']}_glass{k}", glass)
MEL.set_material_instance_parent(gm, glass)
gp = glass_params(a, g)
for pn in ("Transmittance", "FrostColor"):
c = gp[pn]
MEL.set_material_instance_vector_parameter_value(gm, pn, unreal.LinearColor(c[0], c[1], c[2], 1))
for pn in ("Roughness", "Specular", "Opacity", "Refraction"):
MEL.set_material_instance_scalar_parameter_value(gm, pn, gp[pn])
REPORT.setdefault("glass", {})[f"{a['asset']}_glass{k}"] = {k2: (round(v, 3) if isinstance(v, float) else v)
for k2, v in gp.items() if k2 in ("thin", "Opacity", "Refraction", "Roughness")}
EAL.save_loaded_asset(gm, False)
mats.append(gm)
if a.get("sections"):
# The GLB keeps only the materials its faces use (an all-glass pane has just the glass section).
mats = [mats[min(s, len(mats) - 1)] for s in a["sections"]]
elif len(a.get("glass", [])) >= len(a.get("slots", [])) > 0:
# Exports from before "sections": a glass-only mesh lost its unused BAKED slot 0 in the GLB, so its
# only sections are glass.
mats = mats[1:]
n = sm.get_num_sections(0)
for i in range(n):
sm.set_material(i, mats[min(i, len(mats) - 1)])
if n != len(mats):
warn(f"{a['asset']}: {n} sections vs {len(mats)} materials")
EAL.save_loaded_asset(sm, False)
REPORT["timings"]["materials_s"] = round(time.time() - t)
# ------------------------------------------------------------------ level
def V(v):
return unreal.Vector(v[0], v[1], v[2])
def rot_fu(f, u):
return unreal.MathLibrary.make_rot_from_xz(V(f), V(u))
def spawn_mesh(eas, sm, loc, rot):
"""spawn_actor_from_object returns None in the pythonscript commandlet (no actor factory); spawn by class."""
act = eas.spawn_actor_from_class(unreal.StaticMeshActor, loc, rot)
act.static_mesh_component.set_static_mesh(sm)
return act
LFV_BASE_CM = 500.0 # ULocalFogVolumeComponent::GetBaseVolumeSize()
def lfv_tiles(b, max_aspect=1.5):
"""Cover a box (center, half-extent cm) with spheres: one sphere of radius max(half-extent) when the box is
roughly cubic, else a row of spheres of radius = the smaller of the two larger half-extents along the long axis
(a long flat box must not become one giant ball). Returns [(center, radius_cm)]."""
e = list(b["extent"])
c = list(b["center"])
order = sorted(range(3), key=lambda i: -e[i])
big, mid = e[order[0]], e[order[1]]
if big <= max_aspect * mid:
return [(c, max(e))]
r = mid
n = max(1, math.ceil(big / r))
out = []
for k in range(n):
p = list(c)
p[order[0]] = c[order[0]] - big + r + (2 * big - 2 * r) * (k / max(n - 1, 1))
out.append((p, r))
return out
def vignette_intensity(angle, w, h):
"""UE vignette intensity matching ffmpeg's vignette=angle (finish.sh). ffmpeg multiplies the display-encoded
frame by cos(angle * d / dmax)^4; UE multiplies scene linear by 1 / (1 + I^2 r^2)^2 before the tone curve, where
a display factor f is about f^1.41 in linear (UE filmic: 1.64x display code per stop around middle grey).
Least-squares fit over the frame (the old linear guess, 0.45 at PI/4, was about 40% too weak)."""
a = h / w
s = math.sqrt(2) / math.sqrt(1 + a * a)
pts = []
for j in range(20):
for i in range(40):
px, py = (i + 0.5) / 20 - 1, (j + 0.5) / 10 - 1
dn = math.hypot(px * w / 2, py * h / 2) / math.hypot(w / 2, h / 2)
pts.append(((px * s) ** 2 + (py * a * s) ** 2, max(math.cos(angle * dn), 0) ** 4))
pts = [(r2, f ** 1.41) for r2, f in pts]
return min((sum((1 / (1 + I * I * r2) ** 2 - t) ** 2 for r2, t in pts), I) for I in (k * 0.005 for k in range(300)))[1]
def stage_level():
t = time.time()
les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
eas = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
lpath = f"{DEST}/{LEVEL}"
# delete_asset on a map silently fails in the commandlet: remove the .umap file itself (nothing has loaded it yet).
umap = os.path.join(unreal.Paths.convert_relative_path_to_full(unreal.Paths.project_content_dir()),
lpath[len("/Game/"):] + ".umap")
if os.path.exists(umap):
os.remove(umap)
unreal.AssetRegistryHelpers.get_asset_registry().scan_files_synchronous([umap], True)
if not les.new_level(lpath):
raise RuntimeError(f"new_level failed for {lpath}")
by = {a["asset"]: a for a in scene["assets"]}
meshes = {}
n = 0
for p in scene["placements"]:
a = by.get(p["asset"])
if a is None:
continue
if p["asset"] not in meshes:
meshes[p["asset"]] = find_mesh(a)
sm = meshes[p["asset"]]
if sm is None:
continue
q = p["quat"]
rot = unreal.Quat(q[0], q[1], q[2], q[3]).rotator()
act = spawn_mesh(eas, sm, V(p["loc"]), rot)
act.set_actor_scale3d(V(p["scale"]))
act.set_actor_label(p["name"])
act.set_folder_path("Meshes")
c = act.static_mesh_component
c.set_editor_property("cast_shadow", p.get("shadow", True))
if not p.get("camera_visible", True):
c.set_editor_property("visible_in_ray_tracing", True)
c.set_editor_property("hidden_in_game", True)
n += 1
log(f"level: {n} mesh actors")
# Lights.
nl = 0
for L in scene["lights"]:
loc = V(L["loc"])
rot = rot_fu(L["forward"], L["up"])
if L["type"] == "POINT":
act = eas.spawn_actor_from_class(unreal.PointLight, loc, rot)
elif L["type"] == "SPOT":
act = eas.spawn_actor_from_class(unreal.SpotLight, loc, rot)
elif L["type"] == "AREA":
act = eas.spawn_actor_from_class(unreal.RectLight, loc, rot)
elif L["type"] == "SUN":
act = eas.spawn_actor_from_class(unreal.DirectionalLight, loc, rot)
else:
warn(f"light type {L['type']} skipped ({L['name']})")
continue
act.set_actor_label(L["name"])
act.set_folder_path("Lights")
c = act.light_component
c.set_editor_property("mobility", unreal.ComponentMobility.MOVABLE)
c.set_light_color(unreal.LinearColor(*L["color"], 1.0), True)
if L["type"] == "SUN":
c.set_editor_property("intensity", L["lux"])
c.set_editor_property("light_source_angle", L.get("angle_deg", 0.5))
else:
c.set_editor_property("intensity_units", unreal.LightUnits.CANDELAS)
c.set_editor_property("intensity", L["candela"])
c.set_editor_property("attenuation_radius", L["attenuation_radius"])
if L["type"] in ("POINT", "SPOT"):
c.set_editor_property("source_radius", L["source_radius"])
c.set_editor_property("soft_source_radius", 0.0)
if L["type"] == "SPOT":
c.set_editor_property("outer_cone_angle", L["outer_cone"])
c.set_editor_property("inner_cone_angle", L["inner_cone"])
if L["type"] == "AREA":
c.set_editor_property("source_width", max(L["width"], 1.0))
c.set_editor_property("source_height", max(L["height"], 1.0))
spread = L.get("spread_deg", 180)
c.set_editor_property("barn_door_angle", min(spread / 2, 88.0))
c.set_editor_property("barn_door_length", 0.0 if spread >= 179 else 20.0)
c.set_editor_property("cast_shadows", L["cast_shadows"])
c.set_editor_property("specular_scale", L["specular"])
c.set_editor_property("diffuse_scale", L["diffuse"])
c.set_editor_property("volumetric_scattering_intensity", L["volume"])
for k, v in LOOK["light"].items():
c.set_editor_property(k, v)
if L.get("gobo_fx") and L["type"] == "SPOT":
# Light functions are clamped to 0..1: the material divides the pattern by its peak, the light carries it.
g = L["gobo_fx"]
c.set_editor_property("intensity", L["candela"] * g["peak"])
c.set_editor_property("light_function_material", gobo_mi(L))
c.set_editor_property("light_function_scale", unreal.Vector(1024, 1024, 1024)) # uniform: x/z ratio intact
c.set_editor_property("light_function_fade_distance", 1.0e6)
ec = g.get("emission_color") or [1, 1, 1]
if max(ec) > 0 and any(abs(x - 1) > 1e-3 for x in ec):
col = [a * b for a, b in zip(L["color"], ec)]
mx = max(col)
c.set_light_color(unreal.LinearColor(*(x / mx for x in col), 1.0), True)
c.set_editor_property("intensity", L["candela"] * g["peak"] * mx)
REPORT.setdefault("gobos", {})[L["name"]] = {"peak": g["peak"], "mean": g.get("mean"), "layers": len(g["layers"])}
elif L.get("gobo_fx"):
warn(f"{L['name']}: gobo on a {L['type']} light not converted (spot only)")
if L.get("ies_file"):
prof = EAL.load_asset(ies_path(L["ies_file"]))
if prof:
c.set_editor_property("ies_texture", prof)
# Cycles' IES node normalises the profile and the light power carries the brightness: keep candela.
c.set_editor_property("use_ies_brightness", False)
else:
warn(f"{L['name']}: IES profile {L['ies_file']} not imported")
nl += 1
log(f"level: {nl} lights")
# Cameras.
for C in scene["cameras"]:
act = eas.spawn_actor_from_class(unreal.CineCameraActor, V(C["loc"]), rot_fu(C["forward"], C["up"]))
act.set_actor_label(C["name"])
act.set_folder_path("Cameras")
cc = act.get_cine_camera_component()
fb = cc.get_editor_property("filmback")
fb.set_editor_property("sensor_width", C["sensor_width_mm"])
fb.set_editor_property("sensor_height", C["sensor_height_mm"])
cc.set_editor_property("filmback", fb)
cc.set_editor_property("current_focal_length", C["lens_mm"])
cc.set_editor_property("current_aperture", C["dof"]["fstop"] if C["dof"]["enabled"] else 22.0)
fs = cc.get_editor_property("focus_settings")
fs.set_editor_property("focus_method", unreal.CameraFocusMethod.MANUAL if C["dof"]["enabled"] else unreal.CameraFocusMethod.DISABLE)
fs.set_editor_property("manual_focus_distance", C["dof"]["focus_cm"])
cc.set_editor_property("focus_settings", fs)
if C.get("exposure"): # per-camera exposure offset on top of the grade's manual exposure
pp = cc.get_editor_property("post_process_settings")
pp.set_editor_property("override_auto_exposure_bias", True)
pp.set_editor_property("auto_exposure_bias", scene["grade"]["exposure"] + C["exposure"] - math.log2(scene["lm_per_w"]) + EXPO_OFF)
cc.set_editor_property("post_process_settings", pp)
if any(abs(s) > 1e-4 for s in C["shift"]):
warn(f"{C['name']}: lens shift {C['shift']} has no CineCamera equivalent")
# Sky dome + sky light.
w = scene.get("world") or {}
sky_mat = master_sky() if EAL.does_asset_exist(tex_path("sky")) else None
if sky_mat:
dome = spawn_mesh(eas, unreal.load_asset("/Engine/EngineMeshes/Sphere"), unreal.Vector(0, 0, 0), unreal.Rotator(0, 0, 0))
dome.set_actor_scale3d(unreal.Vector(4000, 4000, 4000))
dome.set_actor_label("SkyDome")
dome.static_mesh_component.set_material(0, sky_mat)
dome.static_mesh_component.set_editor_property("cast_shadow", False)
sl = eas.spawn_actor_from_class(unreal.SkyLight, unreal.Vector(0, 0, 500), unreal.Rotator(0, 0, 0))
sl.set_actor_label("SkyLight")
slc = sl.get_component_by_class(unreal.SkyLightComponent)
slc.set_editor_property("mobility", unreal.ComponentMobility.MOVABLE)
slc.set_editor_property("real_time_capture", True)
slc.set_editor_property("source_type", unreal.SkyLightSourceType.SLS_CAPTURED_SCENE)
slc.set_editor_property("intensity", 1.0)
# Fog: the largest low-density volume becomes the height fog; the rest become local fog volumes.
vols = scene.get("volumes", {})
haze = max(vols.items(), key=lambda kv: kv[1]["bounds_ue"]["extent"][0] * kv[1]["bounds_ue"]["extent"][1], default=(None, None))
fog = eas.spawn_actor_from_class(unreal.ExponentialHeightFog, unreal.Vector(0, 0, 0), unreal.Rotator(0, 0, 0))
fog.set_actor_label("HeightFog")
fc = fog.component
if haze[1]:
h = haze[1]
d = [max(x, 1e-6) for x in h["density"]]
z0 = h["bounds_m"]["lo"][2]
z1 = h["bounds_m"]["hi"][2]
zs = [z0 + f * (z1 - z0) for f in h["levels"]]
k = math.log(d[0] / d[-1]) / max(zs[-1] - zs[0], 0.1) # per metre
fog.set_actor_location(unreal.Vector(0, 0, zs[0] * 100), False, False)
# UE height fog: extinction per cm = FogDensity / 1000 -> per metre FogDensity / 10; falloff per cm = F / 1000.
fc.set_editor_property("fog_density", d[0] * 10.0)
fc.set_editor_property("fog_height_falloff", k * 10.0)
fc.set_editor_property("enable_volumetric_fog", True)
fc.set_editor_property("volumetric_fog_scattering_distribution", min(h["anisotropy"], 0.9))
al = h["albedo"]
fc.set_editor_property("volumetric_fog_albedo", unreal.Color(r=int(al[0] * 255), g=int(al[1] * 255), b=int(al[2] * 255), a=255))
mr = w.get("mean_radiance", [0.02, 0.02, 0.03])
fc.set_editor_property("fog_inscattering_luminance", unreal.LinearColor(mr[0] * 683, mr[1] * 683, mr[2] * 683, 1))
REPORT["haze"] = {"source": haze[0], "fog_density": d[0] * 10, "falloff": k * 10}
for name, v in vols.items():
if name == haze[0] or v.get("claimed_by_fx"):
continue # effects (flames, plumes) are Niagara now: an LFV can neither move nor take their shape
for k, (ctr, r_cm) in enumerate(lfv_tiles(v["bounds_ue"])):
lf = eas.spawn_actor_from_class(unreal.LocalFogVolume, V(ctr), unreal.Rotator(0, 0, 0))
lf.set_actor_label(f"LFV_{name}" + (f"_{k}" if k else ""))
lf.set_folder_path("Volumes")
# LocalFogVolume: base radius 500 cm (GetBaseVolumeSize), the proxy turns the scale into a sphere from
# the max axis (LocalFogVolumeSceneProxy.cpp:34), so scale uniformly to the wanted radius.
sc_ = r_cm / LFV_BASE_CM
lf.set_actor_scale3d(unreal.Vector(sc_, sc_, sc_))
lc = lf.get_component_by_class(unreal.LocalFogVolumeComponent)
dens = max(v["density"]) # Blender density = extinction per metre
emit = max(v["emission"])
path_m = 2.0 * r_cm / 100.0
# RadialFogExtinction is the optical depth straight through the centre (LocalFogVolumeCommon.ush),
# independent of size: sigma (1/m) x path length (m).
tau = max(dens * path_m, 1e-3) # emissive-only volumes still need a little medium (coverage > 0)
lc.set_editor_property("radial_fog_extinction", tau)
lc.set_editor_property("height_fog_extinction", 0.0)
al = v["albedo"]
lc.set_editor_property("fog_albedo", unreal.LinearColor(al[0], al[1], al[2], 1))
lc.set_editor_property("fog_phase_g", min(v["anisotropy"], 0.9))
if emit > 0 and v.get("emission_color"):
ec = v["emission_color"]
# UE adds FogEmissive x coverage (1 - e^-tau) (LocalFogVolumeCommon.ush). Cycles through the centre:
# 683 x emit x (1 - e^-(sigma p)) / sigma nits (683 x emit x p when sigma -> 0). Match the two.
lc_nits = 683 * emit * ((1 - math.exp(-dens * path_m)) / dens if dens > 1e-6 else path_m)
E = lc_nits / (1 - math.exp(-tau))
lc.set_editor_property("fog_emissive", unreal.LinearColor(ec[0] * E, ec[1] * E, ec[2] * E, 1))
REPORT.setdefault("local_fog", []).append({"volume": name, "radius_cm": round(r_cm, 1), "scale": round(sc_, 4),
"radial_fog_extinction": round(dens * path_m, 5)})
if v.get("animated"):
warn(f"volume {name}: animated procedural density baked to a static local fog volume")
# Post-process (grade).
g = scene["grade"]
ppv = eas.spawn_actor_from_class(unreal.PostProcessVolume, unreal.Vector(0, 0, 0), unreal.Rotator(0, 0, 0))
ppv.set_actor_label("Grade")
ppv.set_editor_property("unbound", True)
s = ppv.settings
def ov(k, v):
s.set_editor_property("override_" + k, True)
s.set_editor_property(k, v)
ov("auto_exposure_method", unreal.AutoExposureMethod.AEM_MANUAL)
ov("auto_exposure_apply_physical_camera_exposure", False)
bias = g["exposure"] - math.log2(scene["lm_per_w"]) + EXPO_OFF
ov("auto_exposure_bias", bias)
glare = next((n for n in g.get("compositor", []) if "Glare" in n["type"]), None)
if glare:
ov("bloom_intensity", float(glare["inputs"].get("Strength", 0.35)))
ov("bloom_threshold", -1.0)
ff = g.get("ffmpeg") or {}
if "vignette_angle_rad" in ff:
ov("vignette_intensity", vignette_intensity(ff["vignette_angle_rad"], *g.get("resolution", [1920, 804])))
if "chromatic_px" in ff:
ov("scene_fringe_intensity", 0.6)
if "grain_strength" in ff:
ov("film_grain_intensity", ff["grain_strength"] / 100.0)
lut = EAL.load_asset(tex_path("lut_grade"))
if lut:
ov("color_grading_lut", lut)
ov("color_grading_intensity", 1.0)
ov("motion_blur_amount", 0.0)
look = g.get("look") or "None"
agx = AGX_LOOKS.get(look.split(" - ", 1)[-1]) if g.get("view_transform") == "AgX" else None
if agx:
c = agx[0] / UE_FILMIC_AGX_CONTRAST
ov("color_contrast", unreal.Vector4(c, c, c, 1.0))
ov("color_saturation", unreal.Vector4(agx[1], agx[1], agx[1], 1.0))
REPORT["look"] = {"view": f"AgX / {look}", "ue_contrast": round(c, 3), "saturation": agx[1]}
else:
warn(f"view transform {g.get('view_transform')!r} / look {look!r}: no tone match (UE filmic as is)")
for k, v in LOOK["pp"].items():
if isinstance(v, str) and "." in v: # enum from JSON, e.g. "LumenRayLightingModeOverride.HIT_LIGHTING"
en, mem = v.split(".", 1)
v = getattr(getattr(unreal, en), mem)
ov(k, v)
ppv.settings = s
REPORT["exposure_bias"] = bias
# Collision and the PlayerStart are the "spawn" stage (it needs the saved level and cooked collision).
if not les.save_current_level():
unreal.EditorLoadingAndSavingUtils.save_map(unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world(), lpath)
REPORT["timings"]["level_s"] = round(time.time() - t)
REPORT["actors"] = {"meshes": n, "lights": nl, "cameras": len(scene["cameras"])}
def key_gobo_time(seq, n_frames, frame0=None):
"""Drive MPC_AnyTime from the sequence: GoboUseSeq = 1 and GoboTime = (Blender frame0 + f) / fps keyed on every
frame, so MRQ frame f shows the gobo state of Blender frame frame0 + f (temporal sub-samples interpolate)."""
if not any(L.get("gobo_fx") for L in scene["lights"]):
return
mpc = mpc_time()
fps = scene["grade"].get("fps", 24)
frame0 = scene.get("frame", 0) if frame0 is None else frame0
try:
tr = seq.add_track(unreal.MovieSceneMaterialParameterCollectionTrack)
except Exception:
tr = seq.add_master_track(unreal.MovieSceneMaterialParameterCollectionTrack)
tr.set_editor_property("mpc", mpc)
sec = tr.add_section()
sec.set_range(0, n_frames)
tick = seq.get_tick_resolution()
tpf = tick.numerator / tick.denominator / fps
lin = unreal.MovieSceneKeyInterpolation.LINEAR
sec.add_scalar_parameter_key("GoboUseSeq", unreal.FrameNumber(0), 1.0, lin)
for f in range(n_frames + 1):
sec.add_scalar_parameter_key("GoboTime", unreal.FrameNumber(round(f * tpf)), (frame0 + f) / fps, lin)
def make_dolly(spec, eas, fps):
"""ANYSCENE_DOLLY="camA>camB:frames[:name]": a CineCamera moving linearly from camera A's transform to camera
B's (lens from A) over N frames, as SEQ_<name> for an MRQ clip."""
a, rest = spec.split(">", 1)
parts = rest.split(":")
b, n = parts[0], int(parts[1]) if len(parts) > 1 else 96
name = parts[2] if len(parts) > 2 else f"dolly_{a}"
ca = next((C for C in scene["cameras"] if C["name"] == a), None)
if b.startswith("fwd") and ca is not None: # "camA>fwd150": push in 150 cm along camera A's view axis
d = float(b[3:])
cb = dict(ca, loc=[ca["loc"][i] + ca["forward"][i] * d for i in range(3)])
else:
cb = next((C for C in scene["cameras"] if C["name"] == b), None)
if ca is None or cb is None:
warn(f"dolly {spec}: camera missing")
return
old = next((x for x in eas.get_all_level_actors() if x.get_actor_label() == name), None)
if old:
eas.destroy_actor(old)
ra, rb = rot_fu(ca["forward"], ca["up"]), rot_fu(cb["forward"], cb["up"])
act = eas.spawn_actor_from_class(unreal.CineCameraActor, V(ca["loc"]), ra)
act.set_actor_label(name)
act.set_folder_path("Cameras")
cc = act.get_cine_camera_component()
fb = cc.get_editor_property("filmback")
fb.set_editor_property("sensor_width", ca["sensor_width_mm"])
fb.set_editor_property("sensor_height", ca["sensor_height_mm"])
cc.set_editor_property("filmback", fb)
cc.set_editor_property("current_focal_length", ca["lens_mm"])
cc.set_editor_property("current_aperture", 22.0)
fs = cc.get_editor_property("focus_settings")
fs.set_editor_property("focus_method", unreal.CameraFocusMethod.DISABLE)
cc.set_editor_property("focus_settings", fs)
sp = f"{DEST}/Sequences/SEQ_{name}"
if EAL.does_asset_exist(sp):
EAL.delete_asset(sp)
seq = AT.create_asset(f"SEQ_{name}", f"{DEST}/Sequences", unreal.LevelSequence, unreal.LevelSequenceFactoryNew())
seq.set_display_rate(unreal.FrameRate(fps, 1))
seq.set_playback_start(0)
seq.set_playback_end(n)
bnd = seq.add_possessable(act)
tt = bnd.add_track(unreal.MovieScene3DTransformTrack)
ts = tt.add_section()
ts.set_range(0, n)
chs = ts.get_all_channels()
lin = unreal.MovieSceneKeyInterpolation.LINEAR
def unwrap(x, y):
while y - x > 180:
y -= 360
while y - x < -180:
y += 360
return y
va = [ca["loc"][0], ca["loc"][1], ca["loc"][2], ra.roll, ra.pitch, ra.yaw]
vb = [cb["loc"][0], cb["loc"][1], cb["loc"][2], unwrap(ra.roll, rb.roll), unwrap(ra.pitch, rb.pitch), unwrap(ra.yaw, rb.yaw)]
for i in range(6):
chs[i].add_key(unreal.FrameNumber(0), va[i], interpolation=lin)
chs[i].add_key(unreal.FrameNumber(n), vb[i], interpolation=lin)
for i in range(6, 9):
chs[i].add_key(unreal.FrameNumber(0), 1.0)
try:
ct = seq.add_track(unreal.MovieSceneCameraCutTrack)
except Exception:
ct = seq.add_master_track(unreal.MovieSceneCameraCutTrack)
cs = ct.add_section()
cs.set_range(0, n)
cs.set_camera_binding_id(seq.get_binding_id(bnd) if hasattr(seq, "get_binding_id") else unreal.MovieSceneSequenceExtensions.get_binding_id(seq, bnd))
key_gobo_time(seq, n)
EAL.save_loaded_asset(seq, False)
unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).save_current_level()
log(f"dolly {name}: {a} -> {b}, {n} frames")
# ------------------------------------------------------------------ effects (NIAGARA.md §2)
def fx_params(fx):
p = dict(fx.get("params", {}))
for key in ("type:" + fx["type"], fx["id"]):
p.update(FX_OVR.get(key, {}))
return p
def place_fx(eas, fx, systems):
path = fx["template"]
if path not in systems:
systems[path] = unreal.load_asset(path)
if systems[path] is None:
warn(f"fx template missing: {path}")
sysasset = systems[path]
if sysasset is None:
return None
t = fx["transform"]
act = eas.spawn_actor_from_class(unreal.NiagaraActor, V(t["loc"]), unreal.Quat(*t["quat"]).rotator())
act.set_actor_label("FX_" + fx["id"])
act.set_folder_path("FX")
nc = act.get_editor_property("niagara_component")
nc.set_asset(sysasset, True) # 1. asset first: set_asset resets overrides
params, types = fx_params(fx), fx.get("param_types", {})
for k, v in params.items(): # 2. typed user parameters
ty = types.get(k, "float")
if ty == "float":
nc.set_variable_float(k, float(v))
elif ty == "int":
nc.set_variable_int(k, int(v))
elif ty == "bool":
nc.set_variable_bool(k, bool(v))
elif ty == "vec3":
nc.set_variable_vec3(k, V(v))
elif ty == "pos":
nc.set_variable_position(k, V(v))
elif ty == "color":
nc.set_variable_linear_color(k, unreal.LinearColor(v[0], v[1], v[2], v[3] if len(v) > 3 else 1.0))
nc.set_random_seed_offset(int(fx["seed"]) & 0x7FFFFFFF) # 3. determinism
bl = fx.get("bounds_local") or {"min": [-e for e in fx["bounds_ue"]["extent"]], "max": fx["bounds_ue"]["extent"]}
nc.set_system_fixed_bounds(unreal.Box(V(bl["min"]), V(bl["max"]))) # 4. fixed bounds, local space
fps = fx["time"].get("fps", 24)
ticks = int(math.ceil(fx["time"]["preroll_s"] * fps))
nc.set_editor_property("override_warmup_settings", True) # 5. pre-roll to steady state on activation
nc.set_editor_property("warmup_tick_delta", 1.0 / fps)
nc.set_editor_property("warmup_tick_count", ticks)
try:
nc.set_editor_property("allow_scalability", False) # cinematic: never culled by an effect type
except Exception:
pass
# 6. verify: a wrong name or type is a silent no-op, so read every parameter back.
getters = {"float": nc.get_variable_float, "int": nc.get_variable_int, "bool": nc.get_variable_bool,
"vec3": nc.get_variable_vec3, "pos": nc.get_variable_position, "color": nc.get_variable_color}
bad = []
for k in params:
try:
r = getters[types.get(k, "float")](k)
ok = r[1] if isinstance(r, tuple) else r is not None
except Exception:
ok = False
if not ok:
bad.append(k)
rec = {"id": fx["id"], "type": fx["type"], "template": path, "params_set": len(params), "params_invalid": bad,
"bounds": [list(bl["min"]), list(bl["max"])], "bounds_readback": str(nc.get_system_fixed_bounds())[:200],
"warmup_ticks": ticks, "seed": int(fx["seed"]) & 0x7FFFFFFF,
"overrides": {k: v for k, v in params.items() if fx.get("params", {}).get(k) != v}}
if bad:
REPORT.setdefault("errors", []).append(f"{fx['id']}: user params not on {path}: {bad}")
log("ERROR", fx["id"], "invalid params", bad)
REPORT.setdefault("fx", []).append(rec)
return act
def stage_fx():
t = time.time()
fxs = [f for f in scene.get("fx", []) if f.get("technique") in ("niagara", "niagara_flipbook") and f.get("template")
and ("all" in FX_TYPES or f["type"] in FX_TYPES)]
if not fxs:
log("fx: nothing to place (ANYSCENE_FX_TYPES=" + ",".join(sorted(FX_TYPES)) + ")")
return
if not EAL.does_directory_exist("/Game/AnySceneFX"):
warn("fx: /Game/AnySceneFX is not in this project (build it with fx_pack.py or copy it in); no effects placed")
return
les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
eas = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
les.load_level(f"{DEST}/{LEVEL}")
for a in eas.get_all_level_actors(): # rerunnable on its own: drop the previous pass's effects
if a.get_actor_label().startswith("FX_"):
eas.destroy_actor(a)
systems = {}
n = sum(1 for fx in fxs if place_fx(eas, fx, systems))
skipped = [f.get("id", f.get("name")) for f in scene.get("fx", []) if f not in fxs]
if skipped:
warn(f"fx not placed (technique not handled here): {skipped}")
if not les.save_current_level():
unreal.EditorLoadingAndSavingUtils.save_map(unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world(), f"{DEST}/{LEVEL}")
log(f"fx: {n} niagara actors")
REPORT["timings"]["fx_s"] = round(time.time() - t)
def key_flicker(seq, eas, fps):
"""Light flicker sampled by the exporter (fx[].flicker): a float track on the light component's intensity."""
lights = {a.get_actor_label(): a for a in eas.get_all_level_actors() if isinstance(a, unreal.Light)}
for fx in scene.get("fx", []):
fl = fx.get("flicker")
if not fl or fl["target"] not in lights:
continue
lc = lights[fl["target"]].light_component
base = lc.get_editor_property("intensity")
try:
b = seq.add_possessable(lc)
tr = b.add_track(unreal.MovieSceneFloatTrack)
tr.set_property_name_and_path("Intensity", "Intensity")
sec = tr.add_section()
sec.set_range(0, len(fl["values"]))
ch = sec.get_all_channels()[0]
for i, v in enumerate(fl["values"]):
ch.add_key(unreal.FrameNumber(i), base * v)
REPORT.setdefault("flicker", []).append({"light": fl["target"], "keys": len(fl["values"])})
except Exception as e:
warn(f"flicker track on {fl['target']} failed: {e}")
# ------------------------------------------------------------------ spawn (collision + PlayerStart)
COLLIDE_MIN_CM = float(os.environ.get("ANYSCENE_COLLIDE_MIN_CM", "25")) # smaller props get no collision
def hero_camera():
"""ANYSCENE_HERO (or ANYSCENE_HERO_CAM), else the .blend's active camera (scene.json "active_camera"), else
cam_street, else the first camera."""
want = [os.environ.get("ANYSCENE_HERO") or os.environ.get("ANYSCENE_HERO_CAM"), scene.get("active_camera"), "cam_street"]
return next((c for w in want if w for c in scene["cameras"] if c["name"] == w), scene["cameras"][0] if scene["cameras"] else None)
def stage_spawn():
"""Make a built level walkable in PIE / -game. Rerunnable on its own (ANYSCENE_STAGES=spawn) on any level built
from this export, e.g. after the level was copied into another project.
Collision: meshes are imported without collision primitives, so the pawn fell through every floor. Set
geometry gets complex-as-simple collision (exact, nothing to generate); props smaller than
ANYSCENE_COLLIDE_MIN_CM, glass-only meshes, alpha-cut decals and the sky dome get NoCollision.
PlayerStart: exactly one per level, on the floor under the hero camera (line trace) + 92 cm, with the camera's
yaw, nudged up to 6 m sideways (staying at floor level) until the default pawn (35 cm sphere) overlaps nothing. (It used to sit at the camera's
height, in the air or inside a prop, and some levels had none, so the pawn spawned at the origin.)"""
t = time.time()
les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
eas = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
lpath = f"{DEST}/{LEVEL}"
les.load_level(lpath)
by = {a["asset"]: a for a in scene["assets"]}
by_label = {p["name"]: p["asset"] for p in scene["placements"]}
done, on, off = set(), 0, 0
for act in eas.get_all_level_actors():
if not isinstance(act, unreal.StaticMeshActor):
continue
c = act.static_mesh_component
sm = c.static_mesh
if sm is None:
continue
a = by.get(by_label.get(act.get_actor_label(), "")) or by.get(sm.get_name())
_, ext = act.get_actor_bounds(False)
size = 2 * max(ext.x, ext.y, ext.z)
if (a is None or size < COLLIDE_MIN_CM or (a.get("glass") and not a.get("tex")) or a.get("alpha")):
c.set_collision_profile_name("NoCollision")
off += 1
continue
if sm.get_path_name() not in done:
done.add(sm.get_path_name())
bs = sm.get_editor_property("body_setup")
if bs is None:
warn(f"{sm.get_name()}: no body setup, no collision")
else:
bs.set_editor_property("collision_trace_flag", unreal.CollisionTraceFlag.CTF_USE_COMPLEX_AS_SIMPLE)
EAL.save_loaded_asset(sm, False)
c.set_collision_profile_name("BlockAll")
on += 1
log(f"spawn: collision on {on} actors ({len(done)} meshes), none on {off}")
rec = {"collision_actors": on, "collision_meshes": len(done), "no_collision_actors": off}
starts = [a for a in eas.get_all_level_actors() if isinstance(a, unreal.PlayerStart)]
hero = hero_camera()
if starts and os.environ.get("ANYSCENE_PLAYERSTART") == "keep": # a hand-placed start stays
hero = None
rec["player_start_kept"] = [a.get_actor_label() for a in starts]
else:
for a in starts:
eas.destroy_actor(a)
if hero:
world = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world()
yaw = rot_fu(hero["forward"], [0, 0, 1]).yaw
cam = V(hero["loc"])
vis = unreal.TraceTypeQuery.TRACE_TYPE_QUERY1 # Visibility
def floor_at(x, y):
hit = unreal.SystemLibrary.line_trace_single(world, unreal.Vector(x, y, cam.z), unreal.Vector(x, y, cam.z - 3000),
vis, True, [], unreal.DrawDebugTrace.NONE, True)
h = hit.to_tuple() if hit is not None else None
return h[4].z if h and h[0] else None # (blocking_hit, initial_overlap, time, distance, location, ...)
def free(p):
# The pawn GameModeBase spawns (DefaultPawn) is a 35 cm sphere; a full 88 cm character capsule fails in
# tight sets like the ramen aisle (hanging lamps, wall shelves at head height).
hit = unreal.SystemLibrary.sphere_trace_single(world, p, p + unreal.Vector(0, 0, 1), 36.0, vis, True, [],
unreal.DrawDebugTrace.NONE, True)
h = hit.to_tuple() if hit is not None else None
if h and h[0] and len(rec.setdefault("blocked_by", [])) < 3:
rec["blocked_by"].append([h[9].get_actor_label() if h[9] else None, round(h[4].z), bool(h[1])])
return not (h and h[0])
# Rings around the camera; the floor is the lowest surface found within 6 m (a trace from eye height can
# land on a stool or a counter), and only spots at floor level count.
cands = []
for r in range(0, 630, 30):
for k in range(1 if r == 0 else 24):
ang = 2 * math.pi * k / 24
x, y = cam.x + r * math.cos(ang), cam.y + r * math.sin(ang)
z = floor_at(x, y)
if z is not None:
cands.append((r, x, y, z))
best = None
if cands:
z0 = min(c[3] for c in cands)
low = [c for c in cands if c[3] <= z0 + 20]
rec["floor"] = {"z": round(z0, 1), "samples": len(cands), "at_floor": len(low),
"heights": sorted({round(c[3]) for c in cands})[:12]}
for r, x, y, z in low:
if free(unreal.Vector(x, y, z + 92.0)):
best = (unreal.Vector(x, y, z + 92.0), r)
break
if best is None:
z = floor_at(cam.x, cam.y)
best = (unreal.Vector(cam.x, cam.y, z + 92.0 if z is not None else cam.z), None)
warn(f"spawn: no free spot within 6 m of {hero['name']}" + ("" if z is not None else ", and no floor under it"))
ps = eas.spawn_actor_from_class(unreal.PlayerStart, best[0], unreal.Rotator(0, 0, yaw))
ps.set_actor_label("PlayerStart_" + hero["name"])
rec.update({"player_start": [round(best[0].x, 1), round(best[0].y, 1), round(best[0].z, 1)], "yaw": round(yaw, 1),
"camera": hero["name"], "camera_z": round(cam.z, 1), "nudge_cm": best[1]})
log("spawn:", json.dumps(rec))
REPORT["spawn"] = rec
if not les.save_current_level():
unreal.EditorLoadingAndSavingUtils.save_map(unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world(), lpath)
REPORT["timings"]["spawn_s"] = round(time.time() - t)
def stage_sequences():
"""One single-shot LevelSequence per scene camera (camera cut bound to the CineCameraActor) plus a saved MRQ
primary config, so a still or clip renders headless with:
UnrealEditor-Cmd <uproject> <map> -game -LevelSequence=<SEQ> -MoviePipelineConfig=<CFG> -RenderOffscreen ..."""
t = time.time()
les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
eas = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
lpath = f"{DEST}/{LEVEL}"
les.load_level(lpath)
fps = scene["grade"].get("fps", 24)
for C in scene["cameras"]:
cam = next((a for a in eas.get_all_level_actors() if a.get_actor_label() == C["name"]), None)
if cam is None:
continue
sp = f"{DEST}/Sequences/SEQ_{C['name']}"
if EAL.does_asset_exist(sp):
EAL.delete_asset(sp)
seq = AT.create_asset(f"SEQ_{C['name']}", f"{DEST}/Sequences", unreal.LevelSequence, unreal.LevelSequenceFactoryNew())
seq.set_display_rate(unreal.FrameRate(fps, 1))
seq.set_playback_start(0)
seq.set_playback_end(max(48, CLIP_FRAMES))
b = seq.add_possessable(cam)
try:
track = seq.add_track(unreal.MovieSceneCameraCutTrack)
except Exception:
track = seq.add_master_track(unreal.MovieSceneCameraCutTrack)
sec = track.add_section()
sec.set_range(0, max(48, CLIP_FRAMES))
bid = unreal.MovieSceneObjectBindingID()
bid = seq.get_binding_id(b) if hasattr(seq, "get_binding_id") else unreal.MovieSceneSequenceExtensions.get_binding_id(seq, b)
sec.set_camera_binding_id(bid)
key_gobo_time(seq, 48)
key_flicker(seq, eas, fps)
EAL.save_loaded_asset(seq, False)
for spec in [s for s in os.environ.get("ANYSCENE_DOLLY", "").split(";") if s]:
make_dolly(spec, eas, fps)
# MRQ configs: MRQ_Still = deferred + PNG (UE tone curve + grade LUT); MRQ_Linear = EXR with the tone curve off
# (scene-linear, already exposed) so Blender's AgX view transform can be applied to the Unreal lighting.
res = [int(x) for x in os.environ["ANYSCENE_MRQ_RES"].split("x")] if os.environ.get("ANYSCENE_MRQ_RES") else scene["grade"].get("resolution", [1920, 804])
# MRQ_Clip = MRQ_Still over the sequence's whole playback range (dolly clips).
# Engine warm-up must also cover the longest effect pre-roll (NIAGARA.md section 2.4), on top of the component warm-up.
warm = max([64] + [int(math.ceil(f["time"]["preroll_s"] * fps * 1.5)) for f in scene.get("fx", [])
if "time" in f and ("all" in FX_TYPES or f.get("type") in FX_TYPES)])
for name, linear in (("MRQ_Still", False), ("MRQ_Linear", True), ("MRQ_Clip", False)):
cp = f"{DEST}/MRQ/{name}"
if EAL.does_asset_exist(cp):
EAL.delete_asset(cp)
cfg = AT.create_asset(name, f"{DEST}/MRQ", unreal.MoviePipelinePrimaryConfig, None)
if cfg is None:
warn("could not create MoviePipelinePrimaryConfig asset")
continue
cfg.find_or_add_setting_by_class(unreal.MoviePipelineDeferredPassBase)
if linear:
cfg.find_or_add_setting_by_class(unreal.MoviePipelineImageSequenceOutput_EXR)
col = cfg.find_or_add_setting_by_class(unreal.MoviePipelineColorSetting)
col.set_editor_property("disable_tone_curve", True)
else:
cfg.find_or_add_setting_by_class(unreal.MoviePipelineImageSequenceOutput_PNG)
cfg.find_or_add_setting_by_class(unreal.MoviePipelineGameOverrideSetting)
out = cfg.find_or_add_setting_by_class(unreal.MoviePipelineOutputSetting)
out.output_directory = unreal.DirectoryPath(os.environ.get("ANYSCENE_MRQ_OUT", os.path.join(EXPORT, "..", "compare", "mrq")).replace("\\", "/"))
out.file_name_format = "{sequence_name}" + ("_linear" if linear else "") + ".{frame_number}"
out.output_resolution = unreal.IntPoint(res[0], res[1])
out.use_custom_playback_range = name != "MRQ_Clip"
out.custom_start_frame, out.custom_end_frame = 0, 1
aa = cfg.find_or_add_setting_by_class(unreal.MoviePipelineAntiAliasingSetting)
aa.override_anti_aliasing = True
aa.anti_aliasing_method = unreal.AntiAliasingMethod.AAM_TSR
aa.temporal_sample_count = 8
aa.engine_warm_up_count = warm
aa.use_camera_cut_for_warm_up = False
aa.render_warm_up_frames = True
EAL.save_loaded_asset(cfg, False)
REPORT["timings"]["sequences_s"] = round(time.time() - t)
for st in STAGES:
log("stage", st)
{"textures": stage_textures, "meshes": stage_meshes, "materials": stage_materials, "level": stage_level,
"fx": stage_fx, "spawn": stage_spawn, "sequences": stage_sequences}[st]()
REPORT["total_s"] = round(time.time() - T0)
json.dump(REPORT, open(os.environ.get("ANYSCENE_REPORT") or os.path.join(EXPORT, "build_report.json"), "w"), indent=1)
log("done", json.dumps(REPORT)[:2000])