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,fx,sequences (default: all)
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_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_EXPOSURE_OFFSET extra EV added to the computed manual exposure (calibration)
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,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"))
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"))
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)
log(f"textures {min(i + 64, len(todo))}/{len(todo)} ({time.time() - t:.0f}s)")
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)
# ------------------------------------------------------------------ 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 % 16 == 15 or i == len(todo) - 1:
flush(a)
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():
path = f"{DEST}/Materials/M_AnyBaked"
if EAL.does_asset_exist(path):
return EAL.load_asset(path)
m = AT.create_asset("M_AnyBaked", 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
MEL.recompile_material(m)
EAL.save_loaded_asset(m, False)
return m
def master_glass():
path = f"{DEST}/Materials/M_AnyGlass"
if EAL.does_asset_exist(path):
return EAL.load_asset(path)
m = AT.create_asset("M_AnyGlass", f"{DEST}/Materials", unreal.Material, unreal.MaterialFactoryNew())
m.set_editor_property("blend_mode", unreal.BlendMode.BLEND_TRANSLUCENT)
m.set_editor_property("translucency_lighting_mode", unreal.TranslucencyLightingMode.TLM_SURFACE_PER_PIXEL_LIGHTING)
m.set_editor_property("two_sided", True)
c = MEL.create_material_expression(m, unreal.MaterialExpressionVectorParameter, -500, 0)
c.set_editor_property("parameter_name", "Color")
c.set_editor_property("default_value", unreal.LinearColor(1, 1, 1, 1))
r = MEL.create_material_expression(m, unreal.MaterialExpressionScalarParameter, -500, 200)
r.set_editor_property("parameter_name", "Roughness")
r.set_editor_property("default_value", 0.05)
o = MEL.create_material_expression(m, unreal.MaterialExpressionScalarParameter, -500, 350)
o.set_editor_property("parameter_name", "Opacity")
o.set_editor_property("default_value", 0.25)
MEL.connect_material_property(c, "", unreal.MaterialProperty.MP_BASE_COLOR)
MEL.connect_material_property(r, "", unreal.MaterialProperty.MP_ROUGHNESS)
MEL.connect_material_property(o, "", unreal.MaterialProperty.MP_OPACITY)
MEL.recompile_material(m)
EAL.save_loaded_asset(m, False)
return m
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
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()
for a in ASSETS:
sm = find_mesh(a)
if sm is None:
continue
m = mi("MI_" + a["asset"], baked)
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)
c = g["color"]
MEL.set_material_instance_vector_parameter_value(gm, "Color", unreal.LinearColor(c[0], c[1], c[2], 1))
MEL.set_material_instance_scalar_parameter_value(gm, "Roughness", g["roughness"])
EAL.save_loaded_asset(gm, False)
mats.append(gm)
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
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"])
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 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
b = v["bounds_ue"]
lf = eas.spawn_actor_from_class(unreal.LocalFogVolume, V(b["center"]), unreal.Rotator(0, 0, 0))
lf.set_actor_label("LFV_" + name)
lf.set_folder_path("Volumes")
# A local fog volume is a sphere of radius GetBaseVolumeSize() = 500 cm at scale 1, and the proxy collapses the
# scale to the max axis (LocalFogVolumeSceneProxy.cpp): scale uniformly to the box's largest half-extent.
r_cm = max(b["extent"])
lf.set_actor_scale3d(unreal.Vector(1, 1, 1) * (r_cm / 500.0))
lc = lf.get_component_by_class(unreal.LocalFogVolumeComponent)
dens = max(v["density"])
emit = max(v["emission"])
# RadialFogExtinction is the optical depth straight through the centre (unit-sphere integral): sigma x 2r.
lc.set_editor_property("radial_fog_extinction", dens * 2 * r_cm / 100.0)
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"]
lc.set_editor_property("radial_fog_extinction", max(dens, 0.01) * 2 * r_cm / 100.0)
# fog_emissive is luminance: emission per metre x 683 (lm/W, as for every other emitter).
lc.set_editor_property("fog_emissive", unreal.LinearColor(ec[0] * emit * 683, ec[1] * emit * 683, ec[2] * emit * 683, 1))
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", min(1.0, ff["vignette_angle_rad"] / (math.pi / 4) * 0.45))
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)
ppv.settings = s
REPORT["exposure_bias"] = bias
# Player start at the first hero camera for standalone perf runs.
hero = next((c for c in scene["cameras"] if c["name"] == "cam_street"), scene["cameras"][0] if scene["cameras"] else None)
if hero:
ps = eas.spawn_actor_from_class(unreal.PlayerStart, V(hero["loc"]), rot_fu(hero["forward"], [0, 0, 1]))
ps.set_actor_label("PlayerStart_" + hero["name"])
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"])}
# ------------------------------------------------------------------ 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")]
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["id"] 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}")
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_flicker(seq, eas, fps)
EAL.save_loaded_asset(seq, False)
# 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 = scene["grade"].get("resolution", [1920, 804])
# Engine warm-up must also cover the longest effect pre-roll (NIAGARA.md �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", [])])
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 = True
out.custom_start_frame, out.custom_end_frame = 0, (CLIP_FRAMES if name == "MRQ_Clip" else 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, "sequences": stage_sequences}[st]()
REPORT["total_s"] = round(time.time() - T0)
json.dump(REPORT, open(os.path.join(EXPORT, "build_report.json"), "w"), indent=1)
log("done", json.dumps(REPORT)[:2000])