@deepblend/dsh-blender-provider-local 0.2.19 → 0.3.0

package/python/deepblend_scene.py

@@ -29,12 +29,20 @@ Runs inside Blender's embedded interpreter; ``bpy`` is available at call time.
 
 import json
 import math
+import hashlib
 import os
+import re
 
 import bpy
 from mathutils import Vector
 
 from deepblend_util import ActionError, Guard, as_text, error_text, report_progress, warning
+from deepblend_asset_bundle import verify_asset_bundle, verify_unbundled_gltf_asset, verify_unbundled_obj_asset
+from deepblend_geometry import create_lathe, create_curve, apply_model_modifiers
+from deepblend_images import build_image_maps, build_environment, pack_imported_material_images, check_scene_image_budget
+from deepblend_parts import isolated_import_names, stamp_imported_parts, apply_material_bindings
+from deepblend_anisotropy import build_anisotropy, validate_anisotropy_material, validate_anisotropy_usage, validate_native_material_usage
+from deepblend_images import validate_image_uv_usage
 
 #: SceneSpec engine key -> Blender render engine identifier.
 BLENDER_ENGINE_BY_KEY = {
@@ -65,6 +73,8 @@ PRINCIPLED_SOCKETS = {
     "emissionStrength": ["Emission Strength"],
     "coatWeight": ["Coat Weight", "Clearcoat"],
     "transmissionWeight": ["Transmission Weight", "Transmission"],
+    "anisotropic": ["Anisotropic"],
+    "anisotropicRotation": ["Anisotropic Rotation"],
 }
 
 #: Layer-weight socket name for the Mix Shader node.
@@ -122,7 +132,7 @@ def reset_scene():
     return bpy.context.scene
 
 
-def build_world(scene, spec):
+def build_world(scene, spec, options=None):
     """Apply the SceneSpec's `world` block, or the documented default.
 
     The background a viewer sees behind the product is the World, and until this
@@ -155,7 +165,13 @@ def build_world(scene, spec):
         if background is not None:
             background.inputs[0].default_value = color
             background.inputs[1].default_value = strength
-            return {"declared": declared is not None, "color": list(color), "strength": strength}
+            report = {"declared": declared is not None, "color": list(color), "strength": strength}
+            if declared and declared.get('environment'):
+                image = build_environment(world, background, declared['environment'],
+                                          {asset['id']: asset for asset in spec.get('assets') or []},
+                                          (options or {}).get('project_root'))
+                report['environment'] = {**declared['environment'], 'image': image}
+            return report
     raise ActionError(
         "BLENDER_SCRIPT_ERROR",
         "the scene world has no addressable Background node, so the declared world "
@@ -326,9 +342,8 @@ def _shade_smooth(obj):
 def create_generator(name, spec):
     """Create the mesh for one ``generator`` entity and return the object.
 
-    Every shape is built through a ``bpy.ops.mesh.primitive_*_add`` call so the
-    mesh is Blender's own primitive rather than hand-built vertex data, and every
-    call can be replayed to produce the same topology.
+    Primitive operators and deterministic profile meshes can be replayed to
+    produce the same topology from the same specification.
     """
     shape = spec.get("shape")
     size = float(spec.get("size", 2.0))
@@ -341,9 +356,6 @@ def create_generator(name, spec):
         bpy.ops.mesh.primitive_cube_add(size=size)
     elif shape == "rounded_box":
         bpy.ops.mesh.primitive_cube_add(size=size)
-        bevel = spec.get("bevel") or {}
-        if bevel:
-            _apply_bevel(bpy.context.active_object, bevel)
     elif shape == "uv_sphere":
         bpy.ops.mesh.primitive_uv_sphere_add(radius=radius, segments=segments, ring_count=ring_count)
     elif shape == "cylinder":
@@ -359,16 +371,27 @@ def create_generator(name, spec):
             major_segments=segments,
             minor_segments=ring_count,
         )
+    elif shape == "lathe":
+        create_lathe(name, spec)
+    elif shape == "curve":
+        create_curve(name, spec)
+    elif shape == "handled_cup":
+        from deepblend_vessel import create_handled_cup
+        create_handled_cup(name, spec)
     else:
         raise ActionError(
             "BLENDER_SCRIPT_ERROR",
             'unknown generator shape "%s"' % (shape,),
-            {"supported": ["cube", "rounded_box", "uv_sphere", "cylinder", "cone", "plane", "torus"]},
+            {"supported": ["cube", "rounded_box", "uv_sphere", "cylinder", "cone", "plane", "torus", "lathe", "curve", "handled_cup"]},
         )
 
     obj = bpy.context.active_object
     if obj is None:
         raise ActionError("BLENDER_SCRIPT_ERROR", 'primitive for shape "%s" produced no object' % (shape,))
+    # Bevel is a generator property, not a rounded_box-only option. Silently
+    # ignoring it on cylinders removes the edge highlights product shots need.
+    if spec.get("bevel"):
+        _apply_bevel(obj, spec["bevel"])
     obj.name = name
     obj.data.name = "%s_mesh" % (name,)
     return obj
@@ -384,23 +407,56 @@ def import_asset_into_scene(name, asset_path, asset_type, guard):
     format's add-on — is classified as the format being unavailable rather than as
     a generic script error, because the two need different fixes.
     """
-    before = set(bpy.data.objects.keys())
+    before = set(bpy.data.objects)
 
     if asset_type in ("glb", "gltf"):
-        call = lambda: bpy.ops.import_scene.gltf(filepath=asset_path)  # noqa: E731
+        from deepblend_gltf_import import import_gltf
+        call = lambda: import_gltf(asset_path)  # noqa: E731
     elif asset_type == "fbx":
         call = lambda: bpy.ops.import_scene.fbx(filepath=asset_path)  # noqa: E731
     elif asset_type == "obj":
-        call = lambda: bpy.ops.wm.obj_import(filepath=asset_path)  # noqa: E731
+        from deepblend_obj_import import import_obj
+        call = lambda: import_obj(asset_path)  # noqa: E731
     elif asset_type == "usd":
         call = lambda: bpy.ops.wm.usd_import(filepath=asset_path)  # noqa: E731
     elif asset_type == "blend":
-        call = lambda: bpy.ops.wm.append(filename=asset_path)  # noqa: E731
+        def call():
+            # Read datablocks without opening the file or executing registered
+            # text scripts. One scene identifies its real members and excludes
+            # orphan object datablocks; an object-only library is also supported.
+            with bpy.data.libraries.load(asset_path, link=False) as (source, destination):
+                if len(source.scenes) > 1:
+                    raise ValueError('.blend assets currently require at most one scene')
+                has_scene = bool(source.scenes)
+                if has_scene:
+                    destination.scenes = list(source.scenes)
+                else:
+                    destination.objects = list(source.objects)
+            source_scene = destination.scenes[0] if has_scene else None
+            imported_objects = list(source_scene.objects) if source_scene else [obj for obj in destination.objects if obj is not None]
+            if any(obj.instance_type == 'COLLECTION' for obj in imported_objects):
+                raise ValueError('.blend collection instances are not supported; realize them before importing')
+            if source_scene is not None:
+                if len(source_scene.view_layers) > 1:
+                    raise ValueError('.blend multiple view layers are not supported')
+                def hidden_collection(layer):
+                    return (layer.exclude or layer.hide_viewport or layer.collection.hide_render or layer.collection.hide_viewport
+                            or any(hidden_collection(child) for child in layer.children))
+                if any(hidden_collection(layer.layer_collection) for layer in source_scene.view_layers):
+                    raise ValueError('.blend collection or view-layer visibility overrides are not supported; use object visibility')
+            for obj in imported_objects:
+                bpy.context.scene.collection.objects.link(obj)
+            if source_scene is not None:
+                bpy.data.scenes.remove(source_scene)
+            return imported_objects
     else:
         raise ActionError("ASSET_FORMAT_UNAVAILABLE", 'unsupported asset type "%s"' % (asset_type,))
 
     try:
-        call()
+        with isolated_import_names(name):
+            loaded = call()
+            imported = loaded if asset_type == 'blend' else [obj for obj in bpy.data.objects if obj not in before]
+            stamp_imported_parts(imported)
     except Exception as exc:
         raise ActionError(
             "ASSET_FORMAT_UNAVAILABLE",
@@ -408,7 +464,6 @@ def import_asset_into_scene(name, asset_path, asset_type, guard):
             {"assetPath": asset_path, "assetType": asset_type},
         )
 
-    imported = [bpy.data.objects[key] for key in bpy.data.objects.keys() if key not in before]
     if not imported:
         raise ActionError(
             "ASSET_MISSING",
@@ -416,16 +471,27 @@ def import_asset_into_scene(name, asset_path, asset_type, guard):
             {"assetPath": asset_path},
         )
 
-    root = imported[0]
-    root.name = name
-    for obj in imported[1:]:
-        obj.parent = root
+    if asset_type in ('obj', 'gltf', 'glb'):
+        pack_imported_material_images(imported)
+
+    # The SceneSpec transform belongs to an instance container. Choosing the
+    # first imported object as the root overwrites its authored transform and
+    # flattening every parent destroys assemblies, rigs and nested transforms.
+    bpy.context.view_layer.update()
+    imported_set = set(imported)
+    root = bpy.data.objects.new(name, None)
+    bpy.context.scene.collection.objects.link(root)
+    for obj in imported:
+        if obj.parent not in imported_set:
+            world = obj.matrix_world.copy()
+            obj.parent = root
+            obj.matrix_world = world
     guard.note(
         "SCENE_ASSET_IMPORTED",
         'entity "%s" imported %d object(s) from %s' % (name, len(imported), asset_path),
         {"assetPath": asset_path, "objectCount": len(imported)},
     )
-    return imported
+    return [root, *imported]
 
 
 # ---------------------------------------------------------------------------
@@ -532,8 +598,8 @@ def _build_texture_graph(material, principled, texture, guard, material_id):
 
     A material carrying only scalar parameters shades as one flat colour, which is
     why paper, wood and glazed ceramic all read as the same plastic. This builds the
-    relief and variation that tells them apart, in OBJECT space so the pattern
-    travels with the object and no image has to be ingested.
+    relief and variation that tells them apart. Object space is the legacy
+    default; UV space follows an authored surface layout without an image.
 
     Every socket is looked up by name and every stage is optional: a build missing
     one node degrades to a plainer material and says so, rather than failing the
@@ -563,12 +629,19 @@ def _build_texture_graph(material, principled, texture, guard, material_id):
         )
         return
 
-    coord = nodes.new("ShaderNodeTexCoord")
+    mode = texture.get("coordinates", "object")
+    if mode not in ("object", "uv") or ("uvMap" in texture and
+            (mode != "uv" or not isinstance(texture['uvMap'], str) or not texture['uvMap'].strip())):
+        raise ActionError("SCENE_VALIDATION_FAILED", "procedural uvMap requires UV coordinates",
+                          {"materialId": material_id})
+    coord = nodes.new("ShaderNodeUVMap" if mode == "uv" else "ShaderNodeTexCoord")
+    if mode == "uv":
+        coord.uv_map = texture.get("uvMap", "")
     coord.location = (-1080, -240)
     mapping = nodes.new("ShaderNodeMapping")
     mapping.location = (-900, -240)
     pattern.location = (-700, -240)
-    links.new(coord.outputs["Object"], mapping.inputs["Vector"])
+    links.new(coord.outputs["UV" if mode == "uv" else "Object"], mapping.inputs["Vector"])
     links.new(mapping.outputs["Vector"], pattern.inputs["Vector"])
 
     stretch = texture.get("stretch") or [1.0, 1.0, 1.0]
@@ -659,12 +732,16 @@ def _build_texture_graph(material, principled, texture, guard, material_id):
         links.new(multiply.outputs["Vector"], base_socket)
 
 
-def build_material(spec, guard):
+def build_material(spec, guard, assets=None, project_root=None):
     """Create one Blender material from a SceneSpec material entry."""
     material_id = spec["id"]
     shader = spec.get("shader", "principled")
     parameters = spec.get("parameters") or {}
 
+    if shader == 'emission' and (spec.get('texture') or {}).get('coordinates') == 'uv':
+        raise ActionError('SCENE_VALIDATION_FAILED', 'UV procedural texture requires a principled or glass material',
+                          {'materialId': material_id})
+
     material = bpy.data.materials.new(name="%s%s" % (MATERIAL_PREFIX, material_id))
     # A material has `use_nodes` enabled by default in 5.x and arrives with a
     # Principled BSDF already wired to the output. Setting it again only emits a
@@ -698,15 +775,18 @@ def build_material(spec, guard):
 
         for key, value in parameters.items():
             _set_socket(principled, key, value, guard, material_id)
+        build_anisotropy(material, principled, spec)
 
         # After the scalars, so the pattern varies around the authored values
         # rather than replacing them.
         texture = spec.get("texture")
         if isinstance(texture, dict):
             _build_texture_graph(material, principled, texture, guard, material_id)
+        if spec.get('images'):
+            build_image_maps(material, principled, spec['images'], assets or {}, project_root)
 
     alpha = parameters.get("alpha")
-    if isinstance(alpha, (int, float)) and float(alpha) < 1.0:
+    if (isinstance(alpha, (int, float)) and float(alpha) < 1.0) or 'alpha' in (spec.get('images') or {}):
         # Non-opaque alpha needs an explicit blend mode, or the viewport and the
         # render disagree about whether the surface is see-through.
         try:
@@ -1486,7 +1566,7 @@ def skin_entity(obj, armature_obj, armature_id, guard):
     return True
 
 
-def build_rigid_bodies(spec, entity_objects, guard, cloth_entities=None, soft_entities=None):
+def build_rigid_bodies(spec, entity_objects, guard, cloth_entities=None, soft_entities=None, fluid_entities=None):
     """Give the entities their physics, and BAKE the result into the checkpoint.
 
     WHY THE COMPILE BAKES: a rigid body that has not been baked is a SETTING, not a motion — Blender
@@ -1501,6 +1581,10 @@ def build_rigid_bodies(spec, entity_objects, guard, cloth_entities=None, soft_en
     """
     cloth_entities = cloth_entities or {}
     soft_entities = soft_entities or {}
+    fluid_entities = fluid_entities or {}
+    # ONLY THE DOMAINS HAVE A READING: the flows are what pours in, and what the caller wants to know is
+    # how much liquid there is, which is a property of the domain.
+    fluid_domains = {key: value for key, value in fluid_entities.items() if value.get("role") == "domain"}
     settings = spec.get("simulation") or {}
     scene = bpy.context.scene
     if "gravity" in settings:
@@ -1545,7 +1629,7 @@ def build_rigid_bodies(spec, entity_objects, guard, cloth_entities=None, soft_en
             obj.rigid_body.friction = float(entry["friction"])
         bodies[entity["id"]] = entry
 
-    if not bodies and not cloth_entities and not soft_entities:
+    if not bodies and not cloth_entities and not soft_entities and not fluid_entities:
         return {}
 
     # A SCENE WITH CLOTH AND NO RIGID BODIES STILL HAS CACHES TO BAKE. MEASURED: the first version
@@ -1571,6 +1655,11 @@ def build_rigid_bodies(spec, entity_objects, guard, cloth_entities=None, soft_en
     for entity_id, entry in soft_entities.items():
         build_soft_body(entry, entity_objects[entity_id], guard)
 
+    # FLUIDS ARE BUILT BEFORE THE BAKE TOO, for the same reason as everything else: `bake_all` walks the
+    # caches that exist, and a modifier created afterwards has no cache to walk.
+    for entity_id, entry in fluid_entities.items():
+        build_fluid(entry, entity_objects[entity_id], guard)
+
     reading = {}
     first_frame = int((spec.get("project") or {}).get("frameStart", 1))
     last_frame = int((spec.get("project") or {}).get("frameEnd", first_frame))
@@ -1586,9 +1675,28 @@ def build_rigid_bodies(spec, entity_objects, guard, cloth_entities=None, soft_en
                 "message": "the simulation could not be baked: %s" % (error_text(exc),),
             })
 
+    # THE FLUID BAKE IS A DIFFERENT OPERATOR FROM THE POINT CACHES, and this is the second measurement
+    # carried over from the last round: `ptcache.bake_all` bakes cloth and soft bodies, while a fluid
+    # domain needs `fluid.bake_all` — and THAT operator reads the CONTEXT, so the domain has to be the
+    # active object or it refuses with "Invalid domain" (the first carried measurement).
+    if fluid_domains:
+        for entity_id in fluid_domains:
+            bpy.context.view_layer.objects.active = entity_objects[entity_id]
+            try:
+                bpy.ops.fluid.bake_all()
+            except Exception as exc:
+                guard.warnings.append({
+                    "code": "FLUID_BAKE_FAILED",
+                    "message": 'the fluid domain "%s" could not be baked: %s' % (entity_id, error_text(exc)),
+                })
+            break
+
     for entity_id in soft_entities:
         reading[entity_id] = {"kind": "soft-body", **deform_reading(entity_objects[entity_id], first_frame, last_frame)}
 
+    # AFTER THE BAKE, because the liquid only exists once the mesh cache has been written.
+    reading.update(fluid_reading(fluid_domains, entity_objects, first_frame, last_frame, guard))
+
     for entity_id in cloth_entities:
         # INTO THE SAME READING as the rigid bodies: one report of what the physics did, whatever the
         # mechanism, because a caller asking "what happened in this scene" should not have to know which
@@ -1738,6 +1846,100 @@ def build_soft_body(entry, obj, guard):
     return obj
 
 
+DOMAIN_TYPE_BY_NAME = {"liquid": "LIQUID", "gas": "GAS"}
+FLOW_TYPE_BY_NAME = {"liquid": "LIQUID", "smoke": "SMOKE", "fire": "FIRE", "both": "BOTH"}
+
+
+def build_fluid(entry, obj, guard):
+    """Give one object its part in a fluid simulation.
+
+    THE ROLE IS THE WHOLE REASON THIS IS ONE FIELD RATHER THAN A FLAG: a fluid is at least two entities —
+    a domain, which is the volume the liquid lives in, and something inside it that emits. There is no
+    such thing as a single entity that is a fluid.
+
+    AND THE DOMAIN TYPE IS THE POINT OF THIS SLICE. MEASURED, and it is why the product's default is
+    `liquid` rather than Blender's `gas`: a LIQUID inflow into a GAS domain produces NOTHING — the bake
+    reports success, both caches report baked, and the domain's evaluated mesh is its own cube. Nothing
+    in that chain says "you chose the wrong domain type", which is exactly the kind of silence this
+    product is built to avoid.
+    """
+    role = entry.get("role")
+    modifier = obj.modifiers.new(name="DeepBlendFluid", type="FLUID")
+    if role == "domain":
+        modifier.fluid_type = "DOMAIN"
+        settings = modifier.domain_settings
+        settings.domain_type = DOMAIN_TYPE_BY_NAME.get(entry.get("domainType", "liquid"), "LIQUID")
+        settings.resolution_max = int(entry.get("resolution", 32))
+        # THE SURFACE HAS TO BE ASKED FOR. `use_mesh` defaults to true and the mesh cache is baked by
+        # `fluid.bake_all`, but a build that turns either off gets a domain with no liquid surface and no
+        # indication that anything is missing, so both are set explicitly rather than inherited.
+        settings.use_mesh = True
+    elif role in ("inflow", "outflow"):
+        modifier.fluid_type = "FLOW"
+        settings = modifier.flow_settings
+        settings.flow_type = FLOW_TYPE_BY_NAME.get(entry.get("flowType", "liquid"), "LIQUID")
+        settings.flow_behavior = "INFLOW" if role == "inflow" else "OUTFLOW"
+    else:
+        raise ActionError(
+            "SCENE_SPEC_INVALID",
+            'fluid entity "%s" has role "%s"; expected domain, inflow or outflow'
+            % (obj.get("deepblend_id"), role),
+        )
+    return obj
+
+
+def fluid_reading(domain_entries, entity_objects, first_frame, last_frame, guard):
+    """How much liquid there is, read as the DOMAIN's evaluated mesh against its own cube.
+
+    THE RATIO IS THE READING, for the same measured reason as the subdivision check: a count says nothing
+    on its own, because a domain with no liquid still evaluates to its own eight-vertex cube. Comparing
+    the evaluated mesh against the mesh the object was built with is what tells "there is liquid in here"
+    apart from "there is a box here".
+    """
+    scene = bpy.context.scene
+    reading = {}
+    for entity_id in domain_entries:
+        obj = entity_objects[entity_id]
+        entry = {}
+        for label, frame in (("firstFrame", first_frame), ("lastFrame", last_frame)):
+            scene.frame_set(frame)
+            bpy.context.view_layer.update()
+            depsgraph = bpy.context.evaluated_depsgraph_get()
+            evaluated = obj.evaluated_get(depsgraph)
+            mesh = evaluated.to_mesh()
+            entry[label + "Vertices"] = len(mesh.vertices)
+            evaluated.to_mesh_clear()
+        entry["sourceVertices"] = len(obj.data.vertices)
+        settings = obj.modifiers["DeepBlendFluid"].domain_settings
+        entry["domainType"] = settings.domain_type
+        entry["meshCacheBaked"] = bool(settings.has_cache_baked_mesh)
+        entry["dataCacheBaked"] = bool(settings.has_cache_baked_data)
+        entry["resolution"] = settings.resolution_max
+        entry["useMesh"] = bool(settings.use_mesh)
+        flows = [other for other in obj.users_scene[0].objects
+                 if other.modifiers.get("DeepBlendFluid") is not None
+                 and other.modifiers["DeepBlendFluid"].fluid_type == "FLOW"]
+        entry["flows"] = [(other.name, other.modifiers["DeepBlendFluid"].flow_settings.flow_behavior,
+                           len(other.data.vertices) if other.type == "MESH" else 0) for other in flows]
+        # A DOMAIN THAT PRODUCED NO LIQUID IS A WARNING, NOT A SILENCE. Every signal along the way says
+        # it worked — the bake returns, both caches report baked, the domain type is what was asked for —
+        # and the evaluated mesh is still the domain's own box. MEASURED, and it is the reason this
+        # product's `domainType` default is `liquid` rather than Blender's `gas`; a build that asks for
+        # something else, or whose inflow is finer than the grid, lands here and should be told.
+        if entry["lastFrameVertices"] <= entry["sourceVertices"]:
+            guard.warnings.append({
+                "code": "FLUID_NO_LIQUID",
+                "message": 'fluid domain "%s" baked but its evaluated mesh is still the domain itself '
+                           "(%d vertices against %d), so no liquid was produced — check that the domain "
+                           "type matches what the flows emit, and that its resolution is fine enough for "
+                           "them to be seen"
+                           % (entity_id, entry["lastFrameVertices"], entry["sourceVertices"]),
+                "detail": {key: entry[key] for key in ("domainType", "resolution", "flows") if key in entry},
+            })
+        reading[entity_id] = {"kind": "fluid", **entry}
+    return reading
+
+
 def build_scene(spec, options, guard):
     """Compile a SceneSpec into a live Blender scene.
 
@@ -1747,24 +1949,48 @@ def build_scene(spec, options, guard):
     Returns a report describing what was built. Raises ``ActionError`` on any
     failure that must not be silently tolerated.
     """
-    report_progress("reset_scene", 5)
-    scene = reset_scene()
-
-    report_progress("build_world", 10)
-    world_report = build_world(scene, spec)
-
-    report_progress("configure_scene", 12)
     profile_name = options.get("profile") or "preview"
-    profiles = spec.get("renderProfiles") or {}
-    profile = profiles.get(profile_name)
-    if profile is None:
-        profile = profiles.get("preview")
+    profile = (spec.get("renderProfiles") or {}).get(profile_name)
     if profile is None:
         raise ActionError(
             "RENDER_PROFILE_MISSING",
-            'the SceneSpec defines no render profile named "%s" and no "preview" profile' % (profile_name,),
+            'the SceneSpec defines no render profile named "%s"' % (profile_name,),
         )
 
+    # Check pinned source bytes again at the actual compile boundary. This also
+    # protects lazy checkpoint rebuilds, which do not pass through asset.add.
+    for asset in spec.get("assets") or []:
+        verify_asset_bundle(options.get("project_root") or "", asset)
+        addressed = re.fullmatch(r"assets/raw/([a-f0-9]{64})\.[a-z0-9]+", asset.get("path", ""))
+        declared = addressed.group(1) if addressed else asset.get("sha256")
+        if not declared:
+            verify_unbundled_gltf_asset(options.get("project_root") or "", asset)
+            verify_unbundled_obj_asset(options.get("project_root") or "", asset)
+            continue
+        asset_path = os.path.join(options.get("project_root") or "", asset.get("path", ""))
+        digest = hashlib.sha256()
+        try:
+            with open(asset_path, "rb") as source:
+                for chunk in iter(lambda: source.read(64 * 1024), b""):
+                    digest.update(chunk)
+        except OSError as error:
+            raise ActionError("ASSET_MISSING", 'cannot read pinned asset "%s": %s' % (asset.get("id"), error))
+        actual = digest.hexdigest()
+        if actual != declared or (asset.get("sha256") and asset["sha256"] != declared):
+            raise ActionError("ASSET_HASH_MISMATCH", 'asset "%s" changed since its revision was declared' % asset.get("id"),
+                              {"assetId": asset.get("id"), "declared": declared, "actual": actual})
+
+        verify_unbundled_gltf_asset(options.get("project_root") or "", asset)
+        verify_unbundled_obj_asset(options.get("project_root") or "", asset)
+
+    check_scene_image_budget(spec, options.get('project_root'))
+    report_progress("reset_scene", 5)
+    scene = reset_scene()
+
+    report_progress("build_world", 10)
+    world_report = build_world(scene, spec, options)
+
+    report_progress("configure_scene", 12)
     requested_engine = profile.get("engine", "cycles")
     engine, downgrade = resolve_engine(requested_engine, guard)
     try:
@@ -1780,8 +2006,10 @@ def build_scene(spec, options, guard):
     # Materials first: entities reference them by id during construction.
     report_progress("build_materials", 20)
     materials = {}
+    assets = {asset["id"]: asset for asset in spec.get("assets") or []}
     for entry in spec.get("materials") or []:
-        materials[entry["id"]] = build_material(entry, guard)
+        validate_anisotropy_material(entry, spec.get('animationTracks') or [])
+        materials[entry["id"]] = build_material(entry, guard, assets, options.get('project_root'))
     default_material = build_default_material(guard)
 
     assets = {asset["id"]: asset for asset in spec.get("assets") or []}
@@ -1795,6 +2023,9 @@ def build_scene(spec, options, guard):
 
     report_progress("build_entities", 35)
     entity_objects = {}
+    entity_meshes = {}
+    native_material_surfaces = []
+    simulation_objects = {}
     entity_positions = {}
     for entity in spec.get("entities") or []:
         entity_id = entity["id"]
@@ -1833,14 +2064,18 @@ def build_scene(spec, options, guard):
         apply_transform(root, entity.get("transform") or {})
         apply_visibility(root, visible)
         for obj in objects:
-            apply_visibility(obj, visible)
+            # The instance wrapper follows the entity flag. A visible asset keeps
+            # each source object's hidden helpers; explicit false hides all of it.
+            if entity.get('type') != 'asset-instance' or not visible:
+                apply_visibility(obj, visible)
 
         material_id = entity.get("materialId")
-        if material_id is None and entity.get("type") != "empty":
+        preserve_materials = entity.get("type") == "asset-instance" and material_id is None
+        if material_id is None and entity.get("type") not in ("empty", "asset-instance"):
             material_id = "default"
             materials.setdefault("default", default_material)
         material = materials.get(material_id)
-        if material is None:
+        if material is None and not preserve_materials and entity.get("type") != "empty":
             raise ActionError(
                 "SCENE_VALIDATION_FAILED",
                 'entity "%s" references material "%s", which was not built' % (entity_id, material_id),
@@ -1848,17 +2083,72 @@ def build_scene(spec, options, guard):
         for obj in objects:
             if not hasattr(obj.data, "materials"):
                 continue
-            obj.data.materials.clear()
-            obj.data.materials.append(material)
-            if entity.get("generator", {}).get("shape") in ("uv_sphere", "cylinder", "cone", "torus"):
+            if not preserve_materials and not entity.get("materialBindings"):
+                obj.data.materials.clear()
+                obj.data.materials.append(material)
+                # Whole-asset override has one slot; imported face indices may
+                # still refer to several slots from the original asset.
+                for polygon in getattr(obj.data, "polygons", []):
+                    polygon.material_index = 0
+            generator = entity.get("generator", {})
+            if generator.get("bevel") or generator.get("shape") in ("uv_sphere", "cylinder", "cone", "torus", "lathe", "curve", "handled_cup"):
                 _shade_smooth(obj)
 
+        if entity.get("materialBindings"):
+            apply_material_bindings(entity, objects, materials)
+
         for obj in objects:
             obj["deepblend_id"] = entity_id
             obj["deepblend_kind"] = "entity"
         entity_objects[entity_id] = root
+        meshes = [obj for obj in objects if obj.type == "MESH"]
+        entity_meshes[entity_id] = meshes
+        native_material_surfaces.extend(obj for obj in objects if obj.type in ('CURVE', 'SURFACE', 'FONT', 'META'))
+        if any(entity.get(field) is not None for field in ("rigidBody", "cloth", "softBody", "fluid")):
+            if len(meshes) != 1:
+                raise ActionError(
+                    "SCENE_SPEC_INVALID",
+                    'entity "%s" needs exactly one mesh for entity-level physics; found %d. '
+                    "Declare separately simulated parts as separate entities." % (entity_id, len(meshes)),
+                )
+            simulation_objects[entity_id] = meshes[0]
         entity_positions[entity_id] = [float(root.location[0]), float(root.location[1]), float(root.location[2])]
 
+    apply_model_modifiers(spec.get("entities") or [], entity_meshes)
+    scene['deepblend_requires_cycles'] = False
+    for entry in spec.get('materials') or []:
+        for surface in native_material_surfaces:
+            if validate_native_material_usage(entry, materials[entry['id']], surface, scene.render.engine,
+                                              spec.get('animationTracks') or [], bpy.context.evaluated_depsgraph_get()):
+                scene['deepblend_requires_cycles'] = True
+        for entity_id, meshes in entity_meshes.items():
+            for mesh in meshes:
+                if (entry.get('texture') or {}).get('coordinates') == 'uv':
+                    if validate_native_material_usage(entry, materials[entry['id']], mesh, scene.render.engine,
+                                                      spec.get('animationTracks') or [], bpy.context.evaluated_depsgraph_get()):
+                        scene['deepblend_requires_cycles'] = True
+                    continue
+                used_slots = {polygon.material_index for polygon in mesh.data.polygons}
+                if not any(slot.material == materials[entry['id']] and index in used_slots
+                           for index, slot in enumerate(mesh.material_slots)):
+                    continue
+                if validate_anisotropy_usage(entry, mesh, scene.render.engine, spec.get('animationTracks') or []):
+                    scene['deepblend_requires_cycles'] = True
+                validate_image_uv_usage(entry, mesh, mesh.data.uv_layers)
+    for entity in spec.get("entities") or []:
+        generator = entity.get("generator") or {}
+        if entity.get("modifiers") and entity.get("type") == "generator" and (
+            generator.get("bevel") or any(entry["type"] == "bevel" for entry in entity["modifiers"])
+            or generator.get("shape") in ("uv_sphere", "cylinder", "cone", "torus", "lathe", "curve", "handled_cup")
+        ):
+            for mesh in entity_meshes[entity["id"]]:
+                hidden = mesh.hide_viewport
+                mesh.hide_viewport = False
+                try:
+                    _shade_smooth(mesh)
+                finally:
+                    mesh.hide_viewport = hidden
+
     report_progress("build_lights", 55)
     for light in spec.get("lights") or []:
         obj = build_light(light)
@@ -1941,7 +2231,23 @@ def build_scene(spec, options, guard):
                 'entity "%s" declares a soft body but has no object to simulate' % (entity["id"],),
             )
         soft_entities[entity["id"]] = entry
-    simulation_reading = build_rigid_bodies(spec, entity_objects, guard, cloth_entities, soft_entities)
+    fluid_entities = {}
+    for entity in spec.get("entities") or []:
+        entry = entity.get("fluid")
+        if entry is None:
+            continue
+        if entity_objects.get(entity["id"]) is None:
+            raise ActionError(
+                "SCENE_SPEC_INVALID",
+                'entity "%s" declares a fluid role but has no object to give it to' % (entity["id"],),
+            )
+        fluid_entities[entity["id"]] = entry
+    if len([entry for entry in fluid_entities.values() if entry.get("role") == "domain"]) == 0 and fluid_entities:
+        raise ActionError(
+            "SCENE_SPEC_INVALID",
+            "the scene declares fluid objects but no domain, so the liquid would have nowhere to be",
+        )
+    simulation_reading = build_rigid_bodies(spec, simulation_objects, guard, cloth_entities, soft_entities, fluid_entities)
 
     report_progress("configure_render", 85)
     render_config = configure_scene(scene, spec, profile, guard)
@@ -1974,7 +2280,18 @@ def build_scene(spec, options, guard):
                 'entity "%s" is skinned to armature "%s", which the same SceneSpec does not declare'
                 % (entity["id"], armature_id),
             )
-        skin_entity(obj, armature_obj, armature_id, guard)
+        meshes = entity_meshes[entity["id"]]
+        if not meshes:
+            raise ActionError("SCENE_SPEC_INVALID", 'entity "%s" has no mesh to skin' % entity["id"])
+        for mesh in meshes:
+            previous_parent = mesh.parent
+            previous_world = mesh.matrix_world.copy()
+            skin_entity(mesh, armature_obj, armature_id, guard)
+            if entity.get("type") == "asset-instance":
+                # Automatic weights also reparents the mesh. Keep the authored
+                # assembly and instance transform; the armature modifier deforms it.
+                mesh.parent = previous_parent
+                mesh.matrix_world = previous_world
         skinned_entities[entity["id"]] = entity
 
     return {
@@ -1994,7 +2311,7 @@ def build_scene(spec, options, guard):
                 # THE GROUPS COME FROM THE OBJECT, not from the spec entry: what the file asked for is
                 # the relationship, and what Blender produced is the weights. Reading the latter back is
                 # the whole point — an entity bound with no groups renders as a static object.
-                "vertexGroups": sorted(group.name for group in entity_objects[key].vertex_groups),
+                "vertexGroups": sorted({group.name for mesh in entity_meshes[key] for group in mesh.vertex_groups}),
             }
             for key, entry in skinned_entities.items()
         },
@@ -2002,10 +2319,58 @@ def build_scene(spec, options, guard):
     }
 
 
+def _uv_map_facts(mesh, source):
+    """Names and finite coordinates are inventory, not an overlap/unwrap verdict."""
+    return [{'name': layer.name, 'activeRender': bool(layer.active_render),
+             'loopCount': len(layer.data),
+             'finite': all(math.isfinite(value) for loop in layer.data for value in loop.uv),
+             'source': source}
+            for layer in mesh.uv_layers]
+
+
+def _render_collection_members(layer, inherited_excluded=False, members=None):
+    """An object can have several collection paths; one render-enabled path suffices."""
+    members = set() if members is None else members
+    excluded = inherited_excluded or layer.exclude or layer.collection.hide_render
+    if not excluded:
+        members.update(layer.collection.objects)
+    for child in layer.children:
+        _render_collection_members(child, excluded, members)
+    return members
+
+
+def _object_world_bounds(obj, depsgraph):
+    """Conservative world AABB of an evaluated mesh; wrappers have no geometry.
+
+    Bounds use the evaluated local bounding box transformed by matrix_world.
+    They include the object hierarchy and modifiers, but are not a tight vertex
+    hull or a claim that every enclosed pixel is visible to the camera.
+    """
+    if obj.type != 'MESH':
+        return None
+    evaluated = obj.evaluated_get(depsgraph)
+    if not evaluated.data.vertices:
+        return None
+    local = [tuple(corner) for corner in evaluated.bound_box]
+    if not local or all(corner == (-1.0, -1.0, -1.0) for corner in local):
+        return None
+    corners = [evaluated.matrix_world @ Vector(corner) for corner in local]
+    if not all(math.isfinite(value) for corner in corners for value in corner):
+        return None
+    return {'min': [min(float(corner[axis]) for corner in corners) for axis in range(3)],
+            'max': [max(float(corner[axis]) for corner in corners) for axis in range(3)]}
+
+
 def describe_objects():
     """Inventory of every object in the scene, for validation and golden checks."""
     entries = []
+    depsgraph = bpy.context.evaluated_depsgraph_get()
+    frame = int(bpy.context.scene.frame_current)
+    render_members = _render_collection_members(bpy.context.view_layer.layer_collection)
     for obj in bpy.data.objects:
+        # Disabled viewport objects can retain stale evaluated transforms. Do
+        # not present that cache as a measured world bound or evaluated UV set.
+        evaluation_available = obj.type == 'MESH' and obj.visible_get(view_layer=bpy.context.view_layer)
         entry = {
             "name": obj.name,
             "type": obj.type,
@@ -2015,12 +2380,43 @@ def describe_objects():
             "rotationEuler": [round(float(value), 6) for value in obj.rotation_euler],
             "scale": [round(float(value), 6) for value in obj.scale],
             "visible": not (obj.hide_render or obj.hide_viewport),
+            # Render eligibility only: viewport hiding is a different flag, and
+            # this does not test occlusion, clipping, alpha or material output.
+            "renderVisible": obj in render_members and not obj.hide_render and obj.visible_camera,
+            "worldBounds": _object_world_bounds(obj, depsgraph) if evaluation_available else None,
+            "boundsFrame": frame,
             "parent": obj.parent.name if obj.parent is not None else None,
         }
         if obj.type == "MESH":
             entry["vertexCount"] = len(obj.data.vertices)
             entry["polygonCount"] = len(obj.data.polygons)
-            entry["materialNames"] = [material.name for material in obj.data.materials if material is not None]
+            entry["materialNames"] = [slot.material.name for slot in obj.material_slots if slot.material is not None]
+            entry['uvMaps'] = _uv_map_facts(obj.data, 'mesh-data')
+            if evaluation_available:
+                evaluated = obj.evaluated_get(depsgraph)
+                try:
+                    surface = evaluated.to_mesh(preserve_all_data_layers=True, depsgraph=depsgraph)
+                    entry['evaluatedUvMaps'] = _uv_map_facts(surface, 'evaluated-mesh') if surface else []
+                finally:
+                    evaluated.to_mesh_clear()
+                if entry['worldBounds'] is None:
+                    entry['boundsUnavailable'] = 'empty-or-invalid-bounds'
+            else:
+                entry['boundsUnavailable'] = 'viewport-disabled'
+                entry['evaluatedUvMaps'] = None
+                entry['evaluatedUvMapsUnavailable'] = 'viewport-disabled'
+            if obj.get('deepblend_part_id'):
+                entry['partId'] = obj['deepblend_part_id']
+                entry['parentPartId'] = obj.get('deepblend_parent_part_id') or None
+                entry['sourceMaterialSlots'] = json.loads(obj.get('deepblend_source_material_slots', '[]'))
+                used_slots = {}
+                for polygon in obj.data.polygons:
+                    used_slots[polygon.material_index] = used_slots.get(polygon.material_index, 0) + 1
+                entry['materialSlots'] = [
+                    {'index': index, 'materialName': slot.material.name if slot.material else None,
+                     'materialId': slot.material.get('deepblend_id') if slot.material else None,
+                     'usedPolygonCount': used_slots.get(index, 0)}
+                    for index, slot in enumerate(obj.material_slots)]
         if obj.type == "LIGHT":
             entry["lightType"] = obj.data.type
             entry["energy"] = round(float(obj.data.energy), 6)