A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(import): restore scene materials, animation and native effects
yhhd47de974e271
diff --git a/pipeline/bridges/godot/README.md b/pipeline/bridges/godot/README.mdnew file mode 100644index 000000000..9a8c15d1d--- /dev/null+++ b/pipeline/bridges/godot/README.md@@ -0,0 +1,78 @@+# Godot scene capability bridge++This bridge exports scene data for Estella's normal glTF import pipeline. It+does not embed a second runtime or translate GDScript. Generated scenes and+third-party assets belong in a separate validation project, outside this repo.++Tested with Godot 4.7.2 and the complete Godot demo Platformer 3D scene. Run a+trusted source project in headless mode, with absolute paths for output:++```powershell+$env:ESTELLA_SOURCE_SCENE = 'res://game.tscn'+$env:ESTELLA_SCENE_OUT = 'E:\validation\PlatformerNative.glb'+godot --headless --path E:\source-project --script E:\Estella\pipeline\bridges\godot\export_scene.gd+```++Import the resulting GLB through the editor's `import_assets` MCP tool or the+pipeline's standard model importer. The adjacent `.bridge.json` and the MCP+import result report unsupported features. Keep those diagnostics with the+validation result. The bridge strips scripts before adding the instantiated+scene to the tree; loading/instantiation can still execute resource or script+initializers, so this is not an untrusted-project sandbox.++## Representation++- GridMap cells retain their authored render transforms and collision shapes.+ Repeated geometry uses the standard importer geometry sharing path.+- `KHR_materials_unlit`, alpha cutoff/blending, textures,+ `KHR_node_visibility`, and visibility animation pointers use native materials,+ `NodeVisibility` and timeline property tracks.+- `OMI_physics_shape` / `OMI_physics_body` become `RigidBody3D`,+ `CompoundCollider3D`, and static `MeshCollider3D`. A compound region stays one+ primitive body plus, when needed, one detailed static triangle body. Local+ shape rotation, offsets, mass, and model placement scale are preserved.+- Billboard CPUParticles3D become native `ParticleEmitter` plus+ `ParticleModelUnits`. The latter applies model placement scale to authored+ size, speed and gravity once. It updates when scale or authored values change.+ Textures, bursts, size curves and color gradients use existing native paths.+- Coin `emitting` keys use timeline particle events, so replay resets and starts+ the native emitter. They do not run source scripts or method tracks.++## Bounded bridge metadata++The JSON under `extras.estella` is a narrow data schema, not arbitrary component+deserialization. A node may contain `billboard` (0 or 1), validated `rigidBody`+settings (`fixedRotation`, `continuousCollision`, `gravityScale`,+`linearDamping`, `angularDamping`), or `particle` with `emitter`, model `units`,+and an optional glTF texture index. Materials accept additive `blendMode: 1`.+Animations may contain `particles: [{ node, events: [{ time, action }] }]`,+where action is `play`, `stop` or `reset`. Timeline events target imported node+paths. Invalid entries are skipped with warnings; particle counts and array+sizes are bounded. Root `extras.estella.warnings` carries source conversion+diagnostics into the normal import result.++## Current boundaries++- Gameplay, source signals, scripts, method tracks, enemy AI, and Godot's+ character controller logic need an Estella implementation. The validation+ project's controls demonstrate engine capabilities, not a full game port.+- WorldEnvironment, proximity fade and source-specific shaders/postprocessing+ need native setup. Current procedural gradient baking covers the linear and+ radial modes used by this sample; source render output is not pixel-identical.+- Local particle simulation, arbitrary mesh particles, directed velocity/spread,+ and some Godot emission shapes are not faithfully mapped. Sphere particles+ currently use the engine's radial velocity. Relevant source differences are+ reported by the bridge.+- Moving/sensor concave mesh compounds are rejected with diagnostics. Partial+ angular locks need a richer rigid-body schema. Rotated primitives under a+ nonuniform placement scale must be baked; unsupported placement is rejected.+- Particle event dispatch works through both `TimelinePlayer` and the active+ animator timeline motion. Blends follow the animator's existing event selection;+ a fading predecessor cannot fire effects. Other native event-track kinds and+ nested sequence motions still need animator-specific coverage.++Regression coverage lives in pipeline `gltf-scene-semantics` and+`model-geometry-sharing`, SDK visibility/particle/timeline/physics tests, both+physics backend smoke suites, and the native transform traversal test. Keep+editor image, interaction, and performance evidence in the external validation+report; passing importer tests alone does not prove device acceptance.diff --git a/pipeline/bridges/godot/export_scene.gd b/pipeline/bridges/godot/export_scene.gdnew file mode 100644index 000000000..8bf6754df--- /dev/null+++ b/pipeline/bridges/godot/export_scene.gd@@ -0,0 +1,247 @@+# Headless Godot 4 scene bridge. Scripts are stripped before the scene enters the tree.+# ESTELLA_SOURCE_SCENE=res://game.tscn ESTELLA_SCENE_OUT=absolute.glb+extends SceneTree+var issues: Array = []+var particle_rows: Array = []+var animation_rows: Array = []+var texture_cache = {}+var packed_textures = {}+var texture_images = {}+func _initialize():+ call_deferred("run")+func strip(n: Node):+ n.set_script(null)+ for c in n.get_children(): strip(c)+func vector(v: Vector3): return {"x":v.x,"y":v.y,"z":v.z}+func color(c: Color): return {"r":c.r,"g":c.g,"b":c.b,"a":c.a}+func bake_gradient(tex: GradientTexture2D):+ var image = Image.create_empty(tex.width,tex.height,false,Image.FORMAT_RGBA8)+ var delta = tex.fill_to-tex.fill_from+ var length = max(delta.length(),0.000001)+ for y in tex.height:+ for x in tex.width:+ var uv = Vector2(float(x)/max(tex.width-1,1),float(y)/max(tex.height-1,1))-tex.fill_from+ var t = uv.dot(delta)/(length*length) if tex.fill == 0 else uv.length()/length+ if tex.repeat == 1: t = fposmod(t,1.0)+ elif tex.repeat == 2: t = 1.0-abs(fposmod(t,2.0)-1.0)+ image.set_pixel(x,y,tex.gradient.sample(clamp(t,0.0,1.0)))+ return image+func portable_material(m):+ if not m is BaseMaterial3D or m.albedo_texture == null: return+ var tex = m.albedo_texture+ if tex is GradientTexture2D or tex is GradientTexture1D:+ var id = tex.get_instance_id()+ if not texture_cache.has(id):+ var source_image = bake_gradient(tex) if tex is GradientTexture2D else tex.get_image()+ texture_cache[id] = ImageTexture.create_from_image(source_image)+ texture_images[texture_cache[id].get_instance_id()] = source_image+ m.albedo_texture = texture_cache[id]+func prepare_materials(n: Node):+ if n is MeshInstance3D and n.mesh:+ for i in n.mesh.get_surface_count(): portable_material(n.get_active_material(i))+ for c in n.get_children(): prepare_materials(c)+func pack_texture(tex, doc):+ var id = tex.get_instance_id()+ if packed_textures.has(id): return packed_textures[id]+ var image = texture_images.get(id) if texture_images.has(id) else tex.get_image()+ if image == null: return -1+ if image.is_compressed(): image.decompress()+ if not doc.has("images"): doc.images = []+ if not doc.has("textures"): doc.textures = []+ if not doc.has("samplers"): doc.samplers = []+ var sampler = doc.samplers.size()+ doc.samplers.append({"wrapS":33071,"wrapT":33071,"magFilter":9729,"minFilter":9729})+ var image_index = doc.images.size()+ doc.images.append({"mimeType":"image/png","uri":"data:image/png;base64,"+Marshalls.raw_to_base64(image.save_png_to_buffer())})+ var index = doc.textures.size()+ doc.textures.append({"source":image_index,"sampler":sampler})+ packed_textures[id] = index+ return index+func expand(n: Node):+ for c in n.get_children(): expand(c)+ if not n is GridMap: return+ var holder = StaticBody3D.new()+ holder.name = str(n.name) + "_Expanded"+ holder.transform = n.transform+ n.get_parent().add_child(holder)+ # get_meshes retains Godot's centering and per-item mesh transforms exactly.+ var meshes = n.get_meshes()+ for i in range(0, meshes.size(), 2):+ var item = MeshInstance3D.new()+ item.name = "Cell_%d" % (i / 2)+ item.transform = meshes[i]+ item.mesh = meshes[i+1]+ holder.add_child(item)+ for cell in n.get_used_cells():+ var id = n.get_cell_item(cell)+ var at = Transform3D(n.get_cell_item_basis(cell), n.map_to_local(cell))+ var shapes = n.mesh_library.get_item_shapes(id)+ for i in range(0, shapes.size(), 2):+ var shape = CollisionShape3D.new()+ shape.name = "Collision_%d" % holder.get_child_count()+ shape.shape = shapes[i]+ shape.transform = at * shapes[i+1]+ holder.add_child(shape)+ n.get_parent().remove_child(n)+ n.free()+func primitive(shape):+ if shape is SphereShape3D: return {"type":"sphere","sphere":{"radius":shape.radius}}+ if shape is BoxShape3D: return {"type":"box","box":{"size":[shape.size.x,shape.size.y,shape.size.z]}}+ if shape is CapsuleShape3D: return {"type":"capsule","capsule":{"radius":shape.radius,"height":shape.height}}+ return null+func particles(n: CPUParticles3D, doc):+ if not n.mesh is PlaneMesh and not n.mesh is QuadMesh:+ issues.append(str(n.get_path()) + ": mesh particles need a mesh renderer bridge")+ return null+ if n.local_coords: issues.append(str(n.get_path()) + ": local particle motion mapped to world simulation")+ if n.emission_shape not in [0,1,2,3]:+ issues.append(str(n.get_path()) + ": unsupported emission shape")+ return null+ var size = max(n.mesh.size.x,n.mesh.size.y)+ var tint = n.color+ var material = n.mesh.material+ if material is BaseMaterial3D: tint *= material.albedo_color.srgb_to_linear()+ var start = color(tint)+ var emitter = {"maxParticles":n.amount,"rate":0.0 if n.one_shot and n.explosiveness == 1 else n.amount/n.lifetime,+ "duration":n.lifetime,"lifetimeMin":n.lifetime*(1.0-n.lifetime_randomness),"lifetimeMax":n.lifetime,+ "looping":not n.one_shot,"playOnStart":n.emitting,"simulationSpace":0,"renderMode":0,+ "shape":4 if n.emission_shape in [1,2] else 2 if n.emission_shape == 3 else 0,+ "shapeRadius":n.emission_sphere_radius,"shapeSize":vector(n.emission_box_extents*2),+ "startColor":start,"endColor":start,"enabled":true,"blendMode":1 if material is BaseMaterial3D and material.blend_mode == 1 else 0}+ if n.one_shot and n.explosiveness == 1: emitter.bursts = [{"time":0,"count":n.amount}]+ if n.color_ramp:+ var stops = []+ for i in n.color_ramp.get_point_count(): stops.append({"t":n.color_ramp.get_offset(i),"color":color(n.color_ramp.get_color(i)*tint)})+ emitter.colorGradient = {"stops":stops}+ if n.scale_amount_curve:+ var keys = []+ for i in range(17): keys.append({"time":i/16.0,"value":n.scale_amount_curve.sample(i/16.0),"interpolation":"linear"})+ emitter.sizeCurve = {"keys":keys}+ var units = {"startSizeMin":size*n.scale_amount_min,"startSizeMax":size*n.scale_amount_max,+ "endSizeMin":size*n.scale_amount_min,"endSizeMax":size*n.scale_amount_max,+ "speedMin":n.initial_velocity_min,"speedMax":n.initial_velocity_max,"gravity":vector(n.gravity)}+ if n.emission_shape in [1,2] and n.spread < 180:+ issues.append(str(n.get_path()) + ": sphere emission uses native radial velocity; authored direction/spread differs")+ var result = {"emitter":emitter,"units":units}+ if material is BaseMaterial3D and material.albedo_texture: result.texture = pack_texture(material.albedo_texture,doc)+ return result+func patch_nodes(scene, state, doc):+ var shapes = doc.get("extensions",{}).get("OMI_physics_shape",{}).get("shapes",[])+ for i in doc.nodes.size():+ var n = state.get_scene_node(i)+ if not is_instance_valid(n): continue+ var row = doc.nodes[i]+ if n is Node3D and not n.visible:+ if not row.has("extensions"): row.extensions = {}+ row.extensions.KHR_node_visibility = {"visible":false}+ if n is RigidBody3D:+ if not row.has("extras"): row.extras = {}+ row.extras["estella"] = {"rigidBody":{"fixedRotation":n.axis_lock_angular_x and n.axis_lock_angular_y and n.axis_lock_angular_z,+ "gravityScale":n.gravity_scale,"linearDamping":n.linear_damp,"angularDamping":n.angular_damp,"continuousCollision":n.continuous_cd}}+ if (n.axis_lock_angular_x or n.axis_lock_angular_y or n.axis_lock_angular_z) and not row.extras.estella.rigidBody.fixedRotation:+ issues.append(str(n.get_path())+": partial angular locks are not represented by fixedRotation")+ if n is StaticBody3D:+ if not row.has("extensions"): row.extensions = {}+ if not row.extensions.has("OMI_physics_body"): row.extensions.OMI_physics_body = {}+ row.extensions.OMI_physics_body.motion = {"type":"static"}+ if n is CollisionShape3D and n.get_parent() is Area3D:+ var shape = primitive(n.shape)+ if shape != null:+ if not row.has("extensions"): row.extensions = {}+ row.extensions.OMI_physics_body = {"trigger":{"shape":shapes.size()}}+ shapes.append(shape)+ else: issues.append(str(n.get_path())+": unsupported area shape")+ if n is MeshInstance3D and row.has("mesh") and n.mesh:+ for j in min(n.mesh.get_surface_count(),doc.meshes[row.mesh].primitives.size()):+ var mat = n.get_active_material(j)+ var prim = doc.meshes[row.mesh].primitives[j]+ if mat is BaseMaterial3D and prim.has("material"):+ var exported_mat = doc.materials[prim.material]+ if mat.albedo_texture and not exported_mat.pbrMetallicRoughness.has("baseColorTexture"):+ var tex_index = pack_texture(mat.albedo_texture,doc)+ if tex_index >= 0: exported_mat.pbrMetallicRoughness.baseColorTexture = {"index":tex_index}+ if mat.blend_mode == 1: exported_mat["extras"] = {"estella":{"blendMode":1}}+ if mat.billboard_mode in [1,2]: row["extras"] = {"estella":{"billboard":0 if mat.billboard_mode == 1 else 1}}+ if n is CPUParticles3D:+ var data = particles(n,doc)+ if data != null:+ row["extras"] = {"estella":{"particle":data}}+ particle_rows.append(i)+ if n is WorldEnvironment: issues.append("WorldEnvironment requires native lighting/postprocess setup")+ # Godot's GLTFAnimation retains its source AnimationPlayer path/name in additional data.+ for animation in doc.get("animations",[]):+ var tracks = []+ var targets = {}+ for channel in animation.get("channels",[]):+ var target = channel.get("target",{})+ var pointer = target.get("extensions",{}).get("KHR_animation_pointer",{}).get("pointer","")+ if pointer.begins_with("/nodes/"): targets[int(pointer.split("/")[2])] = true+ elif target.has("node"): targets[int(target.node)] = true+ for index in targets:+ var target_node = state.get_scene_node(index)+ if not is_instance_valid(target_node): continue+ var owner_node = target_node.get_parent()+ if not is_instance_valid(owner_node): continue+ for player in owner_node.get_children():+ if not player is AnimationPlayer: continue+ for clip in player.get_animation_list():+ # Exported clip names are uniquified (take, take2, ...); match via target visibility track.+ if not str(animation.name).begins_with(str(clip)): continue+ var a = player.get_animation(clip)+ var matches = false+ for t in a.get_track_count():+ var path = str(a.track_get_path(t))+ if path.ends_with(":visible") and player.get_node(player.root_node).get_node_or_null(NodePath(path.get_slice(":",0))) == target_node: matches = true+ if not matches: continue+ for t in a.get_track_count():+ var path = str(a.track_get_path(t))+ if not path.ends_with(":emitting"): continue+ var particle_node = player.get_node(player.root_node).get_node_or_null(NodePath(path.get_slice(":",0)))+ var node_index = state.get_node_index(particle_node)+ if node_index < 0: continue+ var events = []+ for k in a.track_get_key_count(t): events.append({"time":a.track_get_key_time(t,k),"action":"play" if a.track_get_key_value(t,k) else "stop"})+ var row_track = {"node":node_index,"events":events}+ if row_track not in tracks: tracks.append(row_track)+ if not tracks.is_empty():+ animation["extras"] = {"estella":{"particles":tracks}}+ animation_rows.append(animation.name)+ if not doc.has("extensions"): doc.extensions = {}+ doc.extensions.OMI_physics_shape = {"shapes":shapes}+ for ext in ["KHR_node_visibility","OMI_physics_shape","OMI_physics_body"]:+ if ext not in doc.extensionsUsed: doc.extensionsUsed.append(ext)+func run():+ var source = OS.get_environment("ESTELLA_SOURCE_SCENE")+ if source.is_empty(): source = "res://game.tscn"+ var output = OS.get_environment("ESTELLA_SCENE_OUT")+ if output.is_empty(): push_error("ESTELLA_SCENE_OUT is required"); quit(1); return+ var scene = load(source).instantiate()+ strip(scene)+ scene.process_mode = Node.PROCESS_MODE_DISABLED+ root.add_child(scene)+ expand(scene)+ prepare_materials(scene)+ var exporter = GLTFDocument.new()+ var state = GLTFState.new()+ var err = exporter.append_from_scene(scene,state)+ if err != OK: quit(err); return+ var glb = exporter.generate_buffer(state)+ var json_length = glb.decode_u32(12)+ var doc = JSON.parse_string(glb.slice(20,20+json_length).get_string_from_utf8())+ patch_nodes(scene,state,doc)+ doc["extras"] = {"estella":{"warnings":issues}}+ var json = JSON.stringify(doc).to_utf8_buffer()+ while json.size()%4: json.append(32)+ var tail = glb.slice(20+json_length)+ var result = PackedByteArray()+ result.resize(20)+ result.encode_u32(0,0x46546C67); result.encode_u32(4,2); result.encode_u32(8,20+json.size()+tail.size())+ result.encode_u32(12,json.size()); result.encode_u32(16,0x4E4F534A)+ result.append_array(json); result.append_array(tail)+ DirAccess.make_dir_recursive_absolute(output.get_base_dir())+ FileAccess.open(output,FileAccess.WRITE).store_buffer(result)+ var report = {"source":source,"nodes":doc.nodes.size(),"particle_emitters":particle_rows.size(),"particle_animations":animation_rows.size(),"warnings":issues}+ FileAccess.open(output+".bridge.json",FileAccess.WRITE).store_string(JSON.stringify(report," "))+ print(JSON.stringify(report))+ scene.free()+ quit()diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.tsindex 57bf11c10..0a77b12d2 100644--- a/pipeline/src/assets/gltfImport.ts+++ b/pipeline/src/assets/gltfImport.ts@@ -16,6 +16,8 @@ import { MESH_MAX_BONES, MeshChannel, MeshChannelType, packChannels,import { MeshoptDecoder } from 'meshoptimizer/decoder';import { generateTangents } from './meshTangents';import { readSpringBones } from './springBoneSource';+import { readGltfPhysics } from './gltfPhysics';+import { readGltfParticle } from './gltfParticles';import {ANIMATED_PATHS, alignQuaternionSigns, animationProductName, disambiguateNodes,nodeChildPaths, nodeNameFor, samplerKeyframes, timelineDocument,@@ -101,6 +103,7 @@ function readCamera(camera: NonNullable<GltfJson['cameras']>[number] | undefined}interface GltfJson {+ extras?: { estella?: { warnings?: string[] } };accessors?: {bufferView?: number; byteOffset?: number; componentType: number; count: number;type: string; normalized?: boolean; min?: number[]; max?: number[];@@ -154,7 +157,7 @@ interface GltfJson {/** Overrides the mesh's own starting weights for this instance of it. */weights?: number[];camera?: number;- extensions?: { KHR_lights_punctual?: { light?: number } };+ extensions?: { KHR_lights_punctual?: { light?: number }; KHR_node_visibility?: { visible?: boolean } };extras?: unknown;}[];cameras?: {@@ -166,7 +169,9 @@ interface GltfJson {skins?: { name?: string; joints: number[]; inverseBindMatrices?: number; skeleton?: number }[];animations?: {name?: string;- channels: { sampler: number; target: { node?: number; path: string } }[];+ extras?: { estella?: { particles?: { node: number; events: { time: number; action: string }[] }[] } };+ channels: { sampler: number; target: { node?: number; path: string;+ extensions?: { KHR_animation_pointer?: { pointer?: string } } } }[];samplers: { input: number; output: number; interpolation?: string }[];}[];scenes?: { nodes?: number[] }[];@@ -596,6 +601,16 @@ function readMaterial(ctx: MaterialContext, textureCache: Map<number, ImportedImconst texture = pbr.baseColorTexture? readTexture(ctx, textureCache, pbr.baseColorTexture, label) : null;+ // PBR properties are only fallbacks on an unlit material. Reading them as+ // shading would change the authored style and upload textures never sampled.+ if (src.extensions?.KHR_materials_unlit !== undefined) return {+ index, name: src.name ?? `material_${index}`, unlit: true,+ ...((src.extras as any)?.estella?.blendMode === 1 ? { blendMode: 1 } : {}),+ baseColor: [factor[0] ?? 1, factor[1] ?? 1, factor[2] ?? 1, factor[3] ?? 1],+ opaque: (src.alphaMode ?? 'OPAQUE') !== 'BLEND', cullBackfaces: src.doubleSided !== true,+ ...(texture ? { baseColorTexture: texture } : {}),+ ...(src.alphaMode === 'MASK' ? { alphaCutoff: src.alphaCutoff ?? 0.5 } : {}),+ };const normal = src.normalTexture? readTexture(ctx, textureCache, src.normalTexture, label) : null;const emissiveMap = src.emissiveTexture@@ -659,6 +674,7 @@ function readMaterial(ctx: MaterialContext, textureCache: Map<number, ImportedIm/** The extensions that say something about SHADING and are read into the Model shader's layers. */const SHADING_EXTENSIONS = new Set([+ 'KHR_materials_unlit','KHR_materials_emissive_strength', 'KHR_materials_clearcoat', 'KHR_materials_sheen', 'KHR_materials_anisotropy','KHR_materials_ior', 'KHR_materials_specular', 'KHR_materials_transmission', 'KHR_materials_volume','KHR_materials_diffuse_transmission', 'KHR_materials_iridescence',@@ -819,6 +835,9 @@ function readNodes(json: GltfJson, meshIndexOf: Map<string, number>,: readLight(json.extensions?.KHR_lights_punctual?.lights?.[lightIndex], warnings, name);const camera = node.camera === undefined ? undefined : readCamera(json.cameras?.[node.camera]);return { index, name, ...nodeTrs(node), meshes, children,+ particle: readGltfParticle(node.extras, name, warnings),+ ...([0,1].includes((node.extras as any)?.estella?.billboard) ? { billboard: (node.extras as any).estella.billboard } : {}),+ ...(node.extensions?.KHR_node_visibility ? { visibility: node.extensions.KHR_node_visibility.visible !== false } : {}),...(light ? { light } : {}), ...(camera ? { camera } : {}), ...(spring.get(index) ?? {}) };};@@ -977,11 +996,21 @@ function readAnimations(json: GltfJson, src: GltfBytes, nodes: ImportedNode[],let drivesSkin = false;for (const channel of animation.channels ?? []) {- const target = channel.target?.node;- const kind = channel.target?.path ?? '';+ let target = channel.target?.node;+ let kind = channel.target?.path ?? '';+ const pointer = channel.target?.extensions?.KHR_animation_pointer?.pointer;+ if (kind === 'pointer') {+ const match = pointer?.match(/^\/nodes\/(\d+)\/(translation|rotation|scale|weights|extensions\/KHR_node_visibility\/visible)$/);+ if (!match) {+ warnings.push(`${name}: animation pointer "${pointer ?? '(missing)'}" is not imported`);+ continue;+ }+ target = Number(match[1]);+ kind = match[2] === 'extensions/KHR_node_visibility/visible' ? 'visibility' : match[2]!;+ }const spec = ANIMATED_PATHS[kind];if (target === undefined || !paths.has(target)) continue;- if (!spec && kind !== 'weights') {+ if (!spec && kind !== 'weights' && kind !== 'visibility') {warnings.push(`${name}: "${kind}" channels are not imported`);continue;}@@ -991,6 +1020,20 @@ function readAnimations(json: GltfJson, src: GltfBytes, nodes: ImportedNode[],const label = nodeNameFor(nodes, target);const interpolation = INTERPOLATION[sampler.interpolation ?? 'LINEAR'] ?? 'linear';+ if (kind === 'visibility') {+ const times = readAccessor(src, sampler.input), values = readAccessor(src, sampler.output);+ if (!times.length || values.length !== times.length) {+ warnings.push(`${name}: visibility sampler must contain one scalar per key`);+ continue;+ }+ const node = findNode(nodes, target)!;+ node.visibility ??= true;+ byNode.set(`NodeVisibility ${path}`, { node: label, childPath: path, component: 'NodeVisibility',+ channels: new Map([['visible', samplerKeyframes(times, values, 1, 'step')[0]!]]) });+ duration = Math.max(duration, times[times.length - 1] ?? 0);+ continue;+ }+// A weights channel drives the SHAPE of whatever that node draws, and// one node may draw several primitives — each with its own targets and// its own entity. The channel is one statement about all of them.@@ -1025,7 +1068,27 @@ function readAnimations(json: GltfJson, src: GltfBytes, nodes: ImportedNode[],byNode.set(`Transform ${path}`, entry);}- if (byNode.size === 0) {+ const bridgeTracks = animation.extras?.estella?.particles ?? [];+ if (!Array.isArray(bridgeTracks) || bridgeTracks.length > 16384)+ warnings.push(`${name}: invalid estella particle tracks; tracks skipped`);+ const particleTracks = (Array.isArray(bridgeTracks) && bridgeTracks.length <= 16384 ? bridgeTracks : []).flatMap(track => {+ if (!track || !Number.isInteger(track.node) || !Array.isArray(track.events) || track.events.length > 4096) {+ warnings.push(`${name}: invalid estella particle track; track skipped`);+ return [];+ }+ const node = findNode(nodes, track.node), path = paths.get(track.node);+ if (!node?.particle || path === undefined) {+ warnings.push(`${name}: particle track target ${track.node} has no imported emitter`);+ return [];+ }+ const events = track.events.filter(e => e && Number.isFinite(e.time) && e.time >= 0 && ['play','stop','reset'].includes(e.action))+ .map(e => ({ time: e.time, action: e.action }));+ if (events.length !== track.events.length) warnings.push(`${name}: invalid particle events were skipped`);+ if (!events.length) return [];+ for (const e of events) duration = Math.max(duration, e.time);+ return [{ type: 'particle', name: node.name, childPath: path, events }];+ });+ if (byNode.size === 0 && !particleTracks.length) {warnings.push(`${name}: no channel targets a node this import produced`);continue;}@@ -1036,10 +1099,9 @@ function readAnimations(json: GltfJson, src: GltfBytes, nodes: ImportedNode[],warnings.push(`${name}: animates a node that carries a skin, whose own transform is`+ ' ignored (glTF requires it) — this channel moves nothing. Animate its joints.');}- out.push({- name: animationProductName(stem, name),- document: timelineDocument(duration, byNode),- });+ const document = timelineDocument(duration, byNode);+ (document.tracks as unknown[]).push(...particleTracks);+ out.push({ name: animationProductName(stem, name), document });}return out;}@@ -1073,6 +1135,7 @@ export async function importGltfMeshes(json = JSON.parse(new TextDecoder().decode(bytes)) as GltfJson;}+ for (const note of json.extras?.estella?.warnings ?? []) if (typeof note === 'string') warnings.push('Scene bridge: ' + note);const externalFiles: string[] = [];const noteExternal = (uri: string): void => {const decoded = decodeURIComponent(uri);@@ -1350,6 +1413,15 @@ export async function importGltfMeshes(warnings.push('no triangle geometry found');}const nodes = readNodes(json, meshIndexOf, warnings);+ const particleTextures = new Map<number, ImportedImageRef | null>();+ const bindParticle = (node: ImportedNode) => {+ const texture = (json.nodes?.[node.index]?.extras as any)?.estella?.particle?.texture;+ if (node.particle && Number.isInteger(texture) && texture >= 0)+ node.particle.texture = readTexture({ src, json, stem, textures, warnings }, particleTextures, { index: texture }, node.name) ?? undefined;+ node.children.forEach(bindParticle);+ };+ nodes.forEach(bindParticle);+ readGltfPhysics(json, nodes, meshes, meshIndexOf, stem, warnings);return {meshes, textures, externalFiles, nodes, warnings,animations: readAnimations(json, src, nodes, meshes, stem, warnings),diff --git a/pipeline/src/assets/gltfParticles.ts b/pipeline/src/assets/gltfParticles.tsnew file mode 100644index 000000000..7df2f4945--- /dev/null+++ b/pipeline/src/assets/gltfParticles.ts@@ -0,0 +1,50 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import type { ImportedNode } from './modelImport';++/** Bounded, data-only bridge schema; extras never instantiate arbitrary components or code. */+export function readGltfParticle(extras: unknown, name: string, warnings: string[]): ImportedNode['particle'] {+ const raw = (extras as any)?.estella?.particle;+ if (!raw) return undefined;+ const emitter: Record<string, unknown> = {}, units: Record<string, unknown> = {};+ const fail = () => { warnings.push(name + ': invalid estella particle data; emitter skipped'); return undefined; };+ if (!raw.emitter || !raw.units || typeof raw.emitter !== 'object' || typeof raw.units !== 'object') return fail();+ for (const key of ['maxParticles', 'rate', 'duration', 'lifetimeMin', 'lifetimeMax', 'shape', 'shapeRadius', 'renderMode', 'blendMode']) {+ const v = raw.emitter[key];+ if (!Number.isFinite(v) || v < 0) return fail();+ emitter[key] = v;+ }+ if (!Number.isInteger(emitter.maxParticles) || Number(emitter.maxParticles) < 1 || Number(emitter.maxParticles) > 16384+ || ![0,1,2,3,4,5].includes(Number(emitter.shape)) || ![0,1].includes(Number(emitter.renderMode))+ || !Number.isInteger(emitter.blendMode) || Number(emitter.blendMode) > 9) return fail();+ if (Number(emitter.lifetimeMax) < Number(emitter.lifetimeMin) || Number(emitter.lifetimeMax) <= 0) return fail();+ for (const key of ['looping', 'playOnStart', 'enabled']) emitter[key] = raw.emitter[key] === true;+ emitter.simulationSpace = 0;+ const vector = (v: any, keys: string[]) => v && keys.every(k => Number.isFinite(v[k]));+ for (const [key, keys] of [['shapeSize', ['x','y','z']], ['startColor',['r','g','b','a']], ['endColor',['r','g','b','a']]] as const) {+ if (!vector(raw.emitter[key], [...keys])) return fail();+ emitter[key] = Object.fromEntries(keys.map(k => [k, raw.emitter[key][k]]));+ }+ for (const key of ['startSizeMin','startSizeMax','endSizeMin','endSizeMax','speedMin','speedMax']) {+ if (!Number.isFinite(raw.units[key]) || raw.units[key] < 0) return fail();+ units[key] = raw.units[key];+ }+ if (!vector(raw.units.gravity, ['x','y','z'])) return fail();+ units.gravity = { x: raw.units.gravity.x, y: raw.units.gravity.y, z: raw.units.gravity.z };+ if (Array.isArray(raw.emitter.bursts)) {+ if (raw.emitter.bursts.length > 256 || !raw.emitter.bursts.every((b: any) => b && Number.isFinite(b.time) && b.time >= 0+ && Number.isInteger(b.count) && b.count >= 0 && b.count <= Number(emitter.maxParticles))) return fail();+ emitter.bursts = raw.emitter.bursts.map((b: any) => ({ time: b.time, count: b.count }));+ }+ if (raw.emitter.sizeCurve) {+ const keys = raw.emitter.sizeCurve.keys;+ if (!Array.isArray(keys) || keys.length > 256 || !keys.every((k: any) => k && Number.isFinite(k.time) && k.time >= 0 && k.time <= 1 && Number.isFinite(k.value) && k.value >= 0)) return fail();+ emitter.sizeCurve = { keys: keys.map((k: any) => ({ time: k.time, value: k.value, interpolation: 'linear' })) };+ }+ if (raw.emitter.colorGradient) {+ const stops = raw.emitter.colorGradient.stops;+ if (!Array.isArray(stops) || stops.length > 256 || !stops.every((s: any) => s && Number.isFinite(s.t) && s.t >= 0 && s.t <= 1 && vector(s.color,['r','g','b','a']))) return fail();+ emitter.colorGradient = { stops: stops.map((s: any) => ({ t: s.t, color: { r:s.color.r,g:s.color.g,b:s.color.b,a:s.color.a } })) };+ }+ return { emitter, units };+}diff --git a/pipeline/src/assets/gltfPhysics.ts b/pipeline/src/assets/gltfPhysics.tsnew file mode 100644index 000000000..d5498683a--- /dev/null+++ b/pipeline/src/assets/gltfPhysics.ts@@ -0,0 +1,139 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { MeshChannel, MeshChannelType, packChannels, q, type Vec3, type Quat } from 'esengine';+import type { ImportedMesh, ImportedNode, Trs } from './modelImport';+import type { CompoundColliderPart3D } from 'esengine';++interface BodySource {+ motion?: { type?: string; mass?: number; [key: string]: unknown };+ collider?: { shape?: number };+ trigger?: { shape?: number; nodes?: number[] } | null;+}+interface PhysicsSource {+ nodes?: { extensions?: Record<string, unknown>; extras?: unknown }[];+ extensions?: Record<string, unknown>;+}+const IDENTITY: Trs = { translation: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] };+const vector = (a: readonly number[]): Vec3 => ({ x: a[0]!, y: a[1]!, z: a[2]! });+const rotation = (a: readonly number[]): Quat => ({ x: a[0]!, y: a[1]!, z: a[2]!, w: a[3]! });+function compose(a: Trs, b: Trs): Trs {+ const p = q.rotate(rotation(a.rotation), vector(b.translation.map((v, i) => v * a.scale[i]!)));+ const r = q.mul(rotation(a.rotation), rotation(b.rotation));+ return { translation: [a.translation[0] + p.x, a.translation[1] + p.y, a.translation[2] + p.z],+ rotation: [r.x, r.y, r.z, r.w], scale: [a.scale[0] * b.scale[0], a.scale[1] * b.scale[1], a.scale[2] * b.scale[2]] };+}++/** OMI geometry stays in model-local units; CompoundCollider3D applies placement scale once. */+export function readGltfPhysics(source: PhysicsSource, nodes: ImportedNode[], meshes: ImportedMesh[],+ meshIndexOf: ReadonlyMap<string, number>, stem: string, warnings: string[]): void {+ const shapes = (source.extensions?.OMI_physics_shape as { shapes?: Record<string, any>[] } | undefined)?.shapes ?? [];+ const meshParts = new Map<ImportedNode, { mesh: ImportedMesh; trs: Trs }[]>();+ const owners = new Set<ImportedNode>();+ const groupedTriggers = new Map<ImportedNode, Set<number>>();+ const visit = (node: ImportedNode, inherited: ImportedNode | undefined, relative: Trs): void => {+ const body = source.nodes?.[node.index]?.extensions?.OMI_physics_body as BodySource | undefined;+ let owner = inherited, trs = compose(relative, node);+ // A trigger is its own non-solid body; a child motion starts an independent body.+ const trigger = body?.trigger;+ if (body?.motion || (trigger && !groupedTriggers.get(inherited!)?.has(node.index) && (trigger.shape !== undefined || trigger.nodes?.length)) || (!owner && body?.collider)) {+ owner = node; trs = IDENTITY;+ const kind = body?.motion?.type ?? (trigger && inherited ? 'kinematic' : 'static');+ if (!['static', 'kinematic', 'dynamic'].includes(kind)) warnings.push(`${node.name}: unsupported OMI motion "${kind}"; using static`);+ const mass = body?.motion?.mass ?? 1;+ node.physics = { bodyType: kind === 'dynamic' ? 2 : kind === 'kinematic' ? 1 : 0,+ mass: Number.isFinite(mass) && mass > 0 ? mass : 1, isSensor: !!trigger, parts: [] };+ const authored = (source.nodes?.[node.index]?.extras as any)?.estella?.rigidBody;+ if (authored && typeof authored === 'object') {+ const settings: Record<string, unknown> = {};+ for (const key of ['fixedRotation', 'continuousCollision']) if (typeof authored[key] === 'boolean') settings[key] = authored[key];+ for (const key of ['gravityScale', 'linearDamping', 'angularDamping'])+ if (Number.isFinite(authored[key]) && authored[key] >= 0) settings[key] = authored[key];+ node.physics.settings = settings;+ }+ owners.add(node);+ if (trigger?.nodes) groupedTriggers.set(node, new Set(trigger.nodes));+ for (const key of Object.keys(body?.motion ?? {})) {+ if (key !== 'type' && key !== 'mass') warnings.push(`${node.name}: OMI motion ${key} is not imported`);+ }+ }+ const shapeIndex = trigger?.shape ?? body?.collider?.shape;+ if (shapeIndex !== undefined && owner?.physics) {+ const shape = shapes[shapeIndex];+ const reject = (reason: string) => warnings.push(`${node.name}: OMI collision ${reason}`);+ if (!shape) reject(`shape ${shapeIndex} is missing`);+ else {+ const sx = Math.abs(trs.scale[0]), sy = Math.abs(trs.scale[1]), sz = Math.abs(trs.scale[2]);+ const base = { position: vector(trs.translation), rotation: rotation(trs.rotation) };+ let part: CompoundColliderPart3D | undefined;+ if (shape.type === 'box') {+ const size = shape.box?.size ?? [1, 1, 1];+ if (Array.isArray(size) && size.length === 3 && size.every(v => Number.isFinite(v) && v > 0)) {+ part = { ...base, kind: 'box', halfExtents: { x: size[0] * sx / 2, y: size[1] * sy / 2, z: size[2] * sz / 2 } };+ } else reject('box size must contain three positive numbers');+ } else if (shape.type === 'sphere' || shape.type === 'capsule') {+ const radius = shape[shape.type]?.radius ?? .5, height = shape.capsule?.height ?? 2;+ if (!Number.isFinite(radius) || radius <= 0 || (shape.type === 'capsule' && (!Number.isFinite(height) || height < radius * 2))) {+ reject('radius / capsule height is invalid');+ } else part = shape.type === 'sphere'+ ? { ...base, kind: 'sphere', radius: radius * Math.max(sx, sy, sz) }+ : { ...base, kind: 'capsule', radius: radius * Math.max(sx, sz), halfHeight: (height / 2 - radius) * sy };+ } else if (shape.type === 'convex' || shape.type === 'trimesh') {+ if (owner.physics.bodyType !== 0 || owner.physics.isSensor) reject(`${shape.type} in a moving or sensor compound is not supported`);+ else {+ const index = shape[shape.type]?.mesh;+ const parts = meshParts.get(owner) ?? [];+ let added = 0;+ for (let primitive = 0; meshIndexOf.has(`${index}_${primitive}`); primitive++) {+ const mesh = meshes[meshIndexOf.get(`${index}_${primitive}`)!];+ if (mesh) { parts.push({ mesh, trs }); added++; }+ }+ if (!added) reject(`mesh ${index} is missing`);+ meshParts.set(owner, parts);+ }+ } else reject(`shape type "${shape.type}" is not supported`);+ if (part) owner.physics.parts.push(part);+ }+ } else if (body && Object.hasOwn(body, 'trigger') && trigger === null) {+ warnings.push(`${node.name}: OMI trigger has no shape (the source exporter wrote null)`);+ }+ for (const child of node.children) visit(child, owner, trs);+ };+ for (const node of nodes) visit(node, undefined, IDENTITY);++ // A static region's detailed collision meshes are one triangle body. This+ // avoids thousands of solver bodies for GridMap cells and keeps authored faces.+ for (const [owner, pieces] of meshParts) {+ if (!pieces.length) continue;+ const positions: number[] = [], indices: number[] = [];+ for (const { mesh, trs } of pieces) {+ const channel = mesh.data.channels.find(c => c.semantic === MeshChannel.Position && c.type === MeshChannelType.Float32);+ if (!channel) continue;+ const data = new DataView(mesh.data.vertices.buffer, mesh.data.vertices.byteOffset, mesh.data.vertices.byteLength);+ const start = positions.length / 3;+ for (let i = 0; i < mesh.vertexCount; i++) {+ const at = i * mesh.data.vertexStride + channel.offset;+ const p = q.rotate(rotation(trs.rotation), { x: data.getFloat32(at, true) * trs.scale[0],+ y: data.getFloat32(at + 4, true) * trs.scale[1], z: data.getFloat32(at + 8, true) * trs.scale[2] });+ positions.push(p.x + trs.translation[0], p.y + trs.translation[1], p.z + trs.translation[2]);+ }+ const mirror = trs.scale[0] * trs.scale[1] * trs.scale[2] < 0;+ for (let i = 0; i < mesh.data.indices.length; i += 3) {+ indices.push(start + mesh.data.indices[i]!, start + mesh.data.indices[i + (mirror ? 2 : 1)]!, start + mesh.data.indices[i + (mirror ? 1 : 2)]!);+ }+ }+ if (!indices.length) continue;+ const packed = packChannels([{ semantic: MeshChannel.Position, type: MeshChannelType.Float32, components: 3 }]);+ const min: [number, number, number] = [Infinity, Infinity, Infinity], max: [number, number, number] = [-Infinity, -Infinity, -Infinity];+ positions.forEach((v, i) => { const a = i % 3; min[a] = Math.min(min[a]!, v); max[a] = Math.max(max[a]!, v); });+ const vertices = new Float32Array(positions);+ owner.physics!.triangleMesh = meshes.length;+ meshes.push({ name: `${stem}_collision_${owner.index}`, vertexCount: positions.length / 3, triangleCount: indices.length / 3,+ data: { ...packed, vertices: new Uint8Array(vertices.buffer), indices: new Uint32Array(indices), vertexCount: positions.length / 3, aabbMin: min, aabbMax: max } });+ }+ for (const owner of owners) {+ if (!owner.physics!.parts.length && owner.physics!.triangleMesh === undefined) {+ warnings.push(`${owner.name}: no supported collision shape belongs to this body`);+ delete owner.physics;+ }+ }+}diff --git a/pipeline/src/assets/importModelFile.ts b/pipeline/src/assets/importModelFile.tsindex a4d1807c1..ac2bb506a 100644--- a/pipeline/src/assets/importModelFile.ts+++ b/pipeline/src/assets/importModelFile.ts@@ -10,13 +10,14 @@*/import { copyFile, mkdir, writeFile } from 'node:fs/promises';import { existsSync, readFileSync } from 'node:fs';+import { createHash } from 'node:crypto';import path from 'node:path';import { isInsideRoot, resolveInside } from '../fs/pathSandbox';import { adoptOrphan } from './assetMeta';import {encodeImportedMesh, assembleModelPrefab, materialProducts, applyLightmapUV, importedImageSettings,generateLods, lodName, encodeGeneratedLod, orderHairTriangles,- type ImportedNode, type SpecularMapReading,+ type ImportedMesh, type ImportedNode, type SpecularMapReading,} from './modelImport';import { modelStem, readModelSource } from './readModelSource';@@ -213,14 +214,39 @@ export async function importModelFile(opts: ImportModelOptions): Promise<Importe}const meshFiles: string[] = [];+ const meshNames = new Map<ImportedMesh, string>();+ const geometryProducts = new Map<string, string>();for (const mesh of meshes) {- meshFiles.push(await write(`${mesh.name}.esmesh`, encodeImportedMesh(mesh)));- for (const [i, lod] of (mesh.lods ?? []).entries()) {- await write(`${lodName(mesh, i + 1)}.esmesh`, encodeGeneratedLod(lod));+ const bytes = encodeImportedMesh(mesh);+ const levels = (mesh.lods ?? []).map(encodeGeneratedLod);+ // Exporters can repeat a mesh definition for every placed grid cell. Distinct+ // paths give identical geometry distinct GPU handles and prevent instancing.+ // Compare the complete encoded geometry (UVs, skin/morph data and every LOD),+ // not its name, bounds or vertex count. Per-instance bindings stay on the node.+ const hash = createHash('sha256');+ for (const part of [bytes, ...levels]) {+ const length = Buffer.allocUnsafe(4);+ length.writeUInt32LE(part.byteLength);+ hash.update(length).update(part);+ }+ const signature = hash.digest('hex');+ const previous = geometryProducts.get(signature);+ const name = previous ?? mesh.name;+ geometryProducts.set(signature, name);+ meshNames.set(mesh, name);+ meshFiles.push(destDir ? `${destDir}/${name}.esmesh` : `${name}.esmesh`);+ // Keep old standalone references and UUIDs working when reimporting a model+ // first imported before sharing was supported. New imports write only the+ // canonical product; the prefab always references it, including its LODs.+ if (previous === undefined || existsSync(path.join(absDir, `${mesh.name}.esmesh`))) {+ await write(`${mesh.name}.esmesh`, bytes);+ for (const [i, lodBytes] of levels.entries()) {+ await write(`${lodName(mesh, i + 1)}.esmesh`, lodBytes);+ }}}for (const texture of textures) await write(texture.name, texture.bytes);- const refs = { prefix: destDir ? `${destDir}/` : '', external, characters, springBones };+ const refs = { prefix: destDir ? `${destDir}/` : '', external, characters, springBones, meshNames };for (const material of materialProducts(meshes, stem, refs)) {await write(`${material.name}.esmaterial`, `${JSON.stringify(material.data, null, 2)}\n`);}diff --git a/pipeline/src/assets/modelImport.ts b/pipeline/src/assets/modelImport.tsindex 0608e3957..899850cfb 100644--- a/pipeline/src/assets/modelImport.ts+++ b/pipeline/src/assets/modelImport.ts@@ -18,6 +18,7 @@ import {} from 'esengine';import { canSimplify, simplifyMesh, type SimplifierFlag } from './meshSimplify';import { SPARSE_LIGHTMAP_UV, OVERLAPPING_LIGHTMAP_UV } from '../../../sdk/src/lightmap/atlas';+import type { CompoundColliderPart3D } from 'esengine';/** One primitive's worth of geometry, named for the file it will be written to. */export interface ImportedMesh {@@ -70,6 +71,9 @@ export interface ImportedMaterial {name: string;/** The tint multiplied into the vertex colors. */baseColor: [number, number, number, number];+ /** KHR_materials_unlit: base colour and alpha only, independent of lighting. */+ unlit?: boolean;+ blendMode?: BlendMode;baseColorTexture?: ImportedImageRef;/** Tangent-space normal map, read against the mesh's own tangent frame where it has one (see meshTangents.ts). */normalTexture?: ImportedImageRef;@@ -167,6 +171,12 @@ export interface ImportedNode {light?: ImportedLight;/** A camera the node carries, looking along its local -Z with +Y up. */camera?: ImportedCamera;+ /** Hierarchical visual visibility, independent of simulation and cameras. */+ visibility?: boolean;+ particle?: { emitter: Record<string, unknown>; units: Record<string, unknown>; texture?: ImportedImageRef };+ billboard?: 0 | 1;+ physics?: { bodyType: 0 | 1 | 2; mass: number; isSensor: boolean;+ parts: CompoundColliderPart3D[]; triangleMesh?: number; settings?: Record<string, unknown> };/** This node is the root of a spring chain: the bones below it are the strand. Lengths are the model's metres. */springBone?: ImportedSpringBone;/** Colliders this node hosts, each an entity of its own below it so one bone can carry several. */@@ -502,7 +512,7 @@ export interface LodOptions {}/** The file a mesh's level `n` is written to, by product name (no extension). */-export function lodName(mesh: ImportedMesh, level: number): string {+export function lodName(mesh: Pick<ImportedMesh, 'name'>, level: number): string {return `${mesh.name}_lod${level}`;}@@ -551,6 +561,8 @@ export function encodeImportedMesh(mesh: ImportedMesh): Uint8Array {export interface ProductRefs {/** Prepended to every product name, e.g. `assets/models/` — the project-relative dir. */prefix?: string;+ /** Canonical geometry product stems. Nodes, materials, skin bindings and animation paths keep their own identity. */+ meshNames?: ReadonlyMap<ImportedMesh, string>;/** An external image uri (relative to the source) → the ref a component carries. */external?: (uri: string) => string;/** Give a skin, hair or eye material the engine's character shader instead of the Model shader (see {@link characterShading}). */@@ -617,7 +629,7 @@ const MATERIAL_LAYER_PROPERTIES: readonly [keyof ImportedMaterial, string][] = [* glTF defaults both factors to 1, so most materials do.*/function needsMaterial(material: ImportedMaterial | undefined): material is ImportedMaterial {- return !!material && !!(material.normalTexture || material.emissive || material.emissiveTexture+ return !!material && !!(material.unlit || material.normalTexture || material.emissive || material.emissiveTexture|| material.occlusionTexture || material.alphaCutoff || material.metallicRoughnessTexture|| (material.metallic ?? 0) !== 0 || (material.roughness ?? 1) !== 1|| MATERIAL_LAYER_PROPERTIES.some(([field]) => material[field] !== undefined));@@ -819,6 +831,20 @@ export function materialProducts(meshes: ImportedMesh[], stem: string,const material = mesh.material;if (!material || !hasProduct(material, refs) || seen.has(material.index)) continue;seen.add(material.index);+ if (material.unlit) {+ out.push({+ name: materialName(stem, material),+ data: {+ version: MATERIAL_FORMAT_VERSION, type: 'material', shader: 'builtin:sprite-unlit',+ blendMode: material.blendMode ?? (material.opaque ? BlendMode.None : BlendMode.Normal),+ depthTest: true, depthWrite: material.opaque,+ cull: material.cullBackfaces ? CullMode.Back : CullMode.None,+ properties: { u_alphaCutoff: material.alphaCutoff ?? 0 },+ },+ images: [],+ });+ continue;+ }const shading = refs.characters ? characterShading(material) : undefined;const images: ImportedImageRef[] = [];@@ -876,8 +902,9 @@ function lodComponent(mesh: ImportedMesh, refs: ProductRefs): ComponentData[] {if (!mesh.lods || mesh.lods.length === 0) return [];const prefix = refs.prefix ?? '';const data: Record<string, unknown> = {};+ const product = { name: refs.meshNames?.get(mesh) ?? mesh.name };mesh.lods.forEach((lod, i) => {- data[`lod${i + 1}`] = `${prefix}${lodName(mesh, i + 1)}.esmesh`;+ data[`lod${i + 1}`] = `${prefix}${lodName(product, i + 1)}.esmesh`;data[`lod${i + 1}Size`] = lod.size;});return [{ type: 'LODGroup', data }];@@ -899,11 +926,11 @@ function meshComponent(mesh: ImportedMesh, stem: string, refs: ProductRefs): Comconst normalMap = !material && hasNormals && mesh.material?.normalTexture? imageRef(mesh.material.normalTexture, refs) : null;return { type: 'MeshRenderer', data: {- mesh: `${prefix}${mesh.name}.esmesh`,+ mesh: `${prefix}${refs.meshNames?.get(mesh) ?? mesh.name}.esmesh`,// Geometry that carries normals was authored to be shaded, so the product// says so. Written rather than assumed: `lit` is a field a user can turn// off, and an import that left it out would be one the engine had to guess.- ...(hasNormals ? { lit: true } : {}),+ ...(mesh.material?.unlit ? { lit: false } : hasNormals ? { lit: true } : {}),...(texture ? { texture } : {}),...(normalMap ? { normalMap } : {}),...(material ? { material } : {}),@@ -1093,8 +1120,29 @@ export function assembleModelPrefab(name: string, meshes: ImportedMesh[],transformComponent(node, rootScale), ...own,...(node.light ? [lightComponent(node.light)] : []),...(node.camera ? [cameraComponent(node.camera)] : []),+ ...(node.visibility !== undefined ? [{ type: 'NodeVisibility', data: { visible: node.visibility } }] : []),]);entities.push(self);+ if (node.billboard !== undefined) self.components.push({ type: 'Billboard', data: { mode: node.billboard, enabled: true } });+ if (node.particle) self.components.push({ type: 'ParticleEmitter', data: { ...node.particle.emitter,+ ...(node.particle.texture ? { texture: imageRef(node.particle.texture, options.refs ?? {}) } : {}) } },+ { type: 'ParticleModelUnits', data: node.particle.units });+ if (node.physics) {+ const physics = node.physics;+ if (physics.parts.length) self.components.push(+ { type: 'RigidBody3D', data: { bodyType: physics.bodyType, ...physics.settings } },+ { type: 'CompoundCollider3D', data: { parts: physics.parts, mass: physics.mass, isSensor: physics.isSensor, enabled: true } },+ );+ if (physics.triangleMesh !== undefined) {+ const mesh = meshes[physics.triangleMesh]!;+ const collisionId = `${id}_collision`;+ self.children.push(collisionId);+ entities.push(entity(collisionId, `${node.name}_Collision`, id, [transformComponent(),+ { type: 'RigidBody3D', data: { bodyType: 0 } },+ { type: 'MeshCollider3D', data: { mesh: `${refs.prefix ?? ''}${refs.meshNames?.get(mesh) ?? mesh.name}.esmesh`, enabled: true } },+ ]));+ }+ }if (refs.springBones) addExplicitSpringBones(node, self, entities, options.scale ?? 1);if (own.length === 0) {drawn.forEach((mesh, i) => {diff --git a/pipeline/tests/gltf-scene-semantics.test.ts b/pipeline/tests/gltf-scene-semantics.test.tsnew file mode 100644index 000000000..671b7ff36--- /dev/null+++ b/pipeline/tests/gltf-scene-semantics.test.ts@@ -0,0 +1,153 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { importGltfMeshes } from '../src/assets/gltfImport';+import { assembleModelPrefab, materialProducts } from '../src/assets/modelImport';+import { plainTriangle } from './fixtures/gltfFixtures.mjs';++function doc() {+ const source = JSON.parse(new TextDecoder().decode(plainTriangle()));+ source.materials = [{ pbrMetallicRoughness: { baseColorFactor: [.2, .4, .6, .8] } }];+ source.meshes[0].primitives[0].material = 0;+ source.nodes = [{ name: 'Root', children: [1] }, { name: 'Object', mesh: 0 }];+ source.scenes = [{ nodes: [0] }]; source.scene = 0;+ return source;+}+function animation(source: any, pointer: string, values: number[] = [1, 0]) {+ const time = new Float32Array([0, 1]), data = new Float32Array(values);+ const bytes = Buffer.concat([Buffer.from(time.buffer), Buffer.from(data.buffer)]);+ const buffer = source.buffers.length, view = source.bufferViews.length, accessor = source.accessors.length;+ source.buffers.push({ byteLength: bytes.length, uri: 'data:application/octet-stream;base64,' + bytes.toString('base64') });+ source.bufferViews.push({ buffer, byteLength: time.byteLength }, { buffer, byteOffset: time.byteLength, byteLength: data.byteLength });+ source.accessors.push({ bufferView: view, componentType: 5126, count: 2, type: 'SCALAR' },+ { bufferView: view + 1, componentType: 5126, count: values.length, type: 'SCALAR' });+ source.animations = [{ name: 'Toggle', channels: [{ sampler: 0, target: { path: 'pointer', extensions: { KHR_animation_pointer: { pointer } } } }],+ samplers: [{ input: accessor, output: accessor + 1, interpolation: 'STEP' }] }];+}+const read = (source: any) => importGltfMeshes(new TextEncoder().encode(JSON.stringify(source)), 'scene');++describe('glTF scene semantics', () => {+ it.each(['OPAQUE', 'MASK', 'BLEND'])('imports unlit %s without applying PBR fallbacks', async alphaMode => {+ const source = doc();+ source.materials[0] = { ...source.materials[0], name: 'skin', alphaMode, alphaCutoff: .35, doubleSided: true,+ emissiveFactor: [1, 0, 0], extensions: { KHR_materials_unlit: {}, KHR_materials_transmission: { transmissionFactor: 1 } } };+ const imported = await read(source), products = materialProducts(imported.meshes, 'scene', { characters: true });+ expect(imported.warnings).not.toContainEqual(expect.stringContaining('KHR_materials_unlit not imported'));+ expect(products[0].data).toMatchObject({ shader: 'builtin:sprite-unlit', depthTest: true, depthWrite: alphaMode !== 'BLEND',+ properties: { u_alphaCutoff: alphaMode === 'MASK' ? .35 : 0 } });+ expect(products[0].data.properties).not.toHaveProperty('u_emissive');+ const prefab = assembleModelPrefab('scene', imported.meshes, { nodes: imported.nodes, refs: { characters: true } });+ expect(prefab.entities.flatMap(e => e.components).find(c => c.type === 'MeshRenderer')?.data)+ .toMatchObject({ lit: false, color: { r: .2, g: .4, b: .6, a: .8 }, material: 'scene_m0.esmaterial' });+ });++ it('keeps initial hidden state and visibility pointer keys on a native subtree gate', async () => {+ const source = doc();+ source.nodes[0].extensions = { KHR_node_visibility: { visible: false } };+ animation(source, '/nodes/1/extensions/KHR_node_visibility/visible');+ const imported = await read(source);+ expect(imported.animations).toHaveLength(1);+ expect(imported.animations![0].document.tracks).toMatchObject([{ component: 'NodeVisibility', childPath: 'Object',+ channels: [{ property: 'visible', keyframes: [{ time: 0, value: 1, interpolation: 'step' }, { time: 1, value: 0, interpolation: 'step' }] }] }]);+ const prefab = assembleModelPrefab('scene', imported.meshes, { nodes: imported.nodes });+ expect(prefab.entities[0].components).toContainEqual({ type: 'NodeVisibility', data: { visible: false } });+ expect(prefab.entities[1].components).toContainEqual({ type: 'NodeVisibility', data: { visible: true } });+ });++ it('reports unsupported pointer paths and malformed visibility samplers explicitly', async () => {+ const source = doc(); animation(source, '/nodes/1/extras/unknown');+ expect((await read(source)).warnings).toContainEqual(expect.stringContaining('/nodes/1/extras/unknown'));+ const invalid = doc(); animation(invalid, '/nodes/1/extensions/KHR_node_visibility/visible', [1]);+ expect((await read(invalid)).warnings).toContainEqual(expect.stringContaining('one scalar per key'));+ });+});++describe('glTF OMI physics', () => {+ it('preserves one dynamic body, mass and rotated offset primitives', async () => {+ const source = doc();+ source.extensions = { OMI_physics_shape: { shapes: [{ type: 'box', box: { size: [2,4,6] } }, { type:'capsule',capsule:{radius:.4,height:2.1} }] } };+ source.nodes = [{ name:'Body',children:[1,2],extensions:{OMI_physics_body:{motion:{type:'dynamic',mass:12}}} },+ { name:'Box',translation:[2,3,4],rotation:[0,0,Math.SQRT1_2,Math.SQRT1_2],extensions:{OMI_physics_body:{collider:{shape:0}}} },+ { name:'Capsule',extensions:{OMI_physics_body:{collider:{shape:1}}} }];+ source.nodes[0].extras = { estella: { rigidBody: { fixedRotation: true, continuousCollision: true, linearDamping: .2, angularDamping: -2 } } };+ const imported = await read(source), physics = imported.nodes[0].physics!;+ expect(physics).toMatchObject({ bodyType:2,mass:12,isSensor:false });+ expect(physics.parts).toHaveLength(2);+ expect(physics.parts[0]).toMatchObject({ kind:'box',halfExtents:{x:1,y:2,z:3},position:{x:2,y:3,z:4},rotation:{z:Math.SQRT1_2} });+ expect(physics.parts[1].halfHeight).toBeCloseTo(.65);+ const prefab = assembleModelPrefab('scene', imported.meshes, { nodes: imported.nodes });+ expect(prefab.entities.flatMap(e=>e.components).filter(c=>c.type==='RigidBody3D')).toHaveLength(1);+ const rigid = prefab.entities[0].components.find(c=>c.type==='RigidBody3D')!.data;+ expect(rigid).toMatchObject({ fixedRotation: true, continuousCollision: true, linearDamping: .2 });+ expect(rigid.angularDamping).not.toBe(-2);+ });+ it('keeps a compound trigger as one sensor and reports missing source shapes', async () => {+ const source = doc(); source.extensions={OMI_physics_shape:{shapes:[{type:'sphere',sphere:{radius:.4}}]}};+ source.nodes[0].extensions={OMI_physics_body:{trigger:{nodes:[1]}}};+ source.nodes[1].extensions={OMI_physics_body:{trigger:{shape:0}}};+ const imported=await read(source);+ expect(imported.nodes[0].physics).toMatchObject({isSensor:true,parts:[{kind:'sphere',radius:.4}]});+ expect(imported.nodes[0].children[0].physics).toBeUndefined();+ source.nodes[1].extensions.OMI_physics_body.trigger=null;+ expect((await read(source)).warnings).toContainEqual(expect.stringContaining('source exporter wrote null'));+ });+ it('merges static authored collision triangles with their local transforms', async () => {+ const source=doc();source.extensions={OMI_physics_shape:{shapes:[{type:'trimesh',trimesh:{mesh:0}}]}};+ source.nodes[0].extensions={OMI_physics_body:{motion:{type:'static'}}};+ source.nodes[1].translation=[3,4,5];source.nodes[1].extensions={OMI_physics_body:{collider:{shape:0}}};+ const imported=await read(source), index=imported.nodes[0].physics!.triangleMesh!;+ expect(index).toBe(1);expect(imported.meshes[index].data.vertexCount).toBe(3);+ expect(imported.meshes[index].data.aabbMin).toEqual([3,4,5]);+ const prefab=assembleModelPrefab('scene',imported.meshes,{nodes:imported.nodes});+ expect(prefab.entities.flatMap(e=>e.components).filter(c=>c.type==='MeshCollider3D')).toHaveLength(1);+ });+});++function particle() {+ return {+ emitter: { maxParticles: 16, rate: 0, duration: .3, lifetimeMin: .4, lifetimeMax: .6,+ shape: 1, shapeRadius: .1, renderMode: 1, blendMode: 1, enabled: true, looping: false, playOnStart: false,+ shapeSize: { x: 1, y: 1, z: 1 }, startColor: { r: 1, g: .5, b: 0, a: 1 }, endColor: { r: 1, g: .5, b: 0, a: 0 },+ bursts: [{ time: 0, count: 16 }] },+ units: { startSizeMin: .2, startSizeMax: .3, endSizeMin: 0, endSizeMax: 0,+ speedMin: 1, speedMax: 2, gravity: { x: 0, y: -1, z: 0 } }, texture: 0,+ };+}++describe('data-only scene bridge', () => {+ it('imports textured native emitters, particle-only clips and additive billboards', async () => {+ const source = doc();+ source.images = [{ uri: 'data:image/png;base64,iVBORw0KGgo=' }]; source.textures = [{ source: 0 }];+ source.nodes[1].extras = { estella: { particle: particle(), billboard: 0 } };+ source.materials[0].extensions = { KHR_materials_unlit: {} };+ source.materials[0].extras = { estella: { blendMode: 1 } }; source.materials[0].alphaMode = 'BLEND';+ source.animations = [{ name: 'burst', channels: [], samplers: [], extras: { estella: {+ particles: [{ node: 1, events: [{ time: 0, action: 'play' }, { time: .5, action: 'stop' }] }],+ } } }];+ const imported = await read(source);+ expect(imported.animations![0].document).toMatchObject({ duration: .5,+ tracks: [{ type: 'particle', childPath: 'Object', events: [{ time: 0, action: 'play' }, { time: .5, action: 'stop' }] }] });+ const prefab = assembleModelPrefab('scene', imported.meshes, { nodes: imported.nodes, refs: { prefix: 'assets/fx/' } });+ const components = prefab.entities[1].components;+ expect(components).toContainEqual({ type: 'Billboard', data: { mode: 0, enabled: true } });+ expect(components.find(c=>c.type==='ParticleEmitter')!.data).toMatchObject({ maxParticles: 16, texture: expect.stringContaining('scene_') });+ expect(components.find(c=>c.type==='ParticleModelUnits')!.data).toMatchObject({ startSizeMin: .2, speedMax: 2 });+ expect(materialProducts(imported.meshes,'scene')[0].data.blendMode).toBe(1);+ });+ it('skips malformed bridge input with diagnostics instead of aborting geometry import', async () => {+ const source = doc(); source.nodes[1].extras = { estella: { particle: particle() } };+ source.nodes[1].extras.estella.particle.emitter.bursts = [null];+ source.animations = [{ name: 'bad', channels: [], samplers: [], extras: { estella: { particles: {} } } }];+ const imported = await read(source);+ expect(imported.meshes).toHaveLength(1);+ expect(imported.nodes[0].children[0].particle).toBeUndefined();+ expect(imported.warnings).toContainEqual(expect.stringContaining('invalid estella particle data'));+ expect(imported.warnings).toContainEqual(expect.stringContaining('invalid estella particle tracks'));+ source.nodes[1].extras.estella.particle = particle();+ source.animations[0].extras.estella.particles = [{ node: 1, events: [null, { time: 0, action: 'play' }] }, null];+ const recovered = await read(source);+ expect(recovered.animations).toHaveLength(1);+ expect(recovered.warnings).toContainEqual(expect.stringContaining('invalid particle events'));+ expect(recovered.warnings).toContainEqual(expect.stringContaining('invalid estella particle track'));+ });+});diff --git a/pipeline/tests/model-geometry-sharing.test.ts b/pipeline/tests/model-geometry-sharing.test.tsnew file mode 100644index 000000000..e494fca92--- /dev/null+++ b/pipeline/tests/model-geometry-sharing.test.ts@@ -0,0 +1,113 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { afterEach, describe, expect, it } from 'vitest';+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { importModelFile } from '../src/assets/importModelFile';+import { plainTriangle } from './fixtures/gltfFixtures.mjs';++const roots: string[] = [];+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); });+const json = (file: string) => JSON.parse(readFileSync(file, 'utf8'));+const renderers = (prefab: any) => prefab.entities.flatMap((e: any) => e.components.filter((c: any) => c.type === 'MeshRenderer'));++function fixture() {+ const doc = JSON.parse(new TextDecoder().decode(plainTriangle()));+ doc.materials = [+ { pbrMetallicRoughness: { baseColorFactor: [1, 0, 0, 1], metallicFactor: 0 } },+ { pbrMetallicRoughness: { baseColorFactor: [0, 0, 1, 1], metallicFactor: 0 } },+ ];+ const primitive = doc.meshes[0].primitives[0];+ doc.meshes = Array.from({ length: 32 }, (_, i) => ({ name: `Cell${i}`, primitives: [{ ...primitive, material: i % 2 }] }));+ doc.nodes = doc.meshes.map((_: unknown, i: number) => ({ name: `Placed${i}`, mesh: i, translation: [i * 3, 0, 0] }));+ doc.scenes = [{ nodes: doc.nodes.map((_: unknown, i: number) => i) }];+ doc.scene = 0;+ return doc;+}++async function importDoc(doc: any, settings = {}) {+ const root = mkdtempSync(path.join(tmpdir(), 'estella-shared-geometry-')); roots.push(root);+ const source = path.join(root, 'cells.gltf');+ writeFileSync(source, JSON.stringify(doc));+ const options = { root, destDir: 'assets', absSource: source, settings };+ const result = await importModelFile(options);+ return { root, source, options, result, prefab: json(path.join(root, result.prefab!)) };+}++describe('model geometry sharing', () => {+ it('loads repeated geometry once while preserving every node, transform and material', async () => {+ const { root, result, prefab, options } = await importDoc(fixture());+ const drawn = renderers(prefab);+ expect(drawn).toHaveLength(32);+ expect(new Set(drawn.map((c: any) => c.data.mesh)).size).toBe(1);+ expect(result.products.filter(p => p.endsWith('.esmesh'))).toHaveLength(1);+ expect(drawn[0].data.color).toEqual({ r: 1, g: 0, b: 0, a: 1 });+ expect(drawn[1].data.color).toEqual({ r: 0, g: 0, b: 1, a: 1 });+ expect(prefab.entities.find((e: any) => e.name === 'Placed31').components[0].data.position.x).toBe(93);+ expect(result.nodeMeshes.get('Placed31')).toEqual(result.nodeMeshes.get('Placed0'));+ const mesh = path.join(root, drawn[0].data.mesh), uuid = json(mesh + '.meta').uuid;+ const again = await importModelFile(options);+ expect(json(mesh + '.meta').uuid).toBe(uuid);+ expect(json(path.join(root, again.prefab!))).toEqual(prefab);+ });++ it('does not share equal-sized meshes with different UV data', async () => {+ const doc = fixture(), uv = new Float32Array([.5, .5, 1, .5, .5, 1]);+ doc.buffers.push({ byteLength: uv.byteLength, uri: 'data:application/octet-stream;base64,' + Buffer.from(uv.buffer).toString('base64') });+ doc.bufferViews.push({ buffer: 1, byteLength: uv.byteLength });+ doc.accessors.push({ bufferView: 3, componentType: 5126, count: 3, type: 'VEC2' });+ doc.meshes[31].primitives[0].attributes = { POSITION: 0, TEXCOORD_0: 3 };+ const { result, prefab } = await importDoc(doc);+ expect(result.products.filter(p => p.endsWith('.esmesh'))).toHaveLength(2);+ const drawn = renderers(prefab);+ expect(drawn[31].data.mesh).not.toBe(drawn[0].data.mesh);+ });++ it('updates a legacy duplicate product without changing its UUID or using it in the new prefab', async () => {+ const { root, options, prefab } = await importDoc(fixture());+ const canonical = renderers(prefab)[0].data.mesh;+ const alias = path.join(root, 'assets/cells_1_0.esmesh');+ writeFileSync(alias, 'stale geometry');+ writeFileSync(alias + '.meta', JSON.stringify({ uuid: 'legacy-mesh-id', type: 'mesh', importer: {} }));+ const result = await importModelFile(options);+ expect(readFileSync(alias)).toEqual(readFileSync(path.join(root, canonical)));+ expect(json(alias + '.meta').uuid).toBe('legacy-mesh-id');+ expect(new Set(renderers(json(path.join(root, result.prefab!))).map((c: any) => c.data.mesh)).size).toBe(1);+ });++ it('shares skinned geometry without sharing the actors joint entities', async () => {+ const doc = fixture();+ const joints = new Uint8Array(12), weights = new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]);+ const bytes = Buffer.concat([Buffer.from(joints.buffer), Buffer.from(weights.buffer)]);+ doc.buffers.push({ byteLength: bytes.length, uri: 'data:application/octet-stream;base64,' + bytes.toString('base64') });+ doc.bufferViews.push({ buffer: 1, byteLength: joints.byteLength }, { buffer: 1, byteOffset: joints.byteLength, byteLength: weights.byteLength });+ doc.accessors.push({ bufferView: 3, componentType: 5121, count: 3, type: 'VEC4' }, { bufferView: 4, componentType: 5126, count: 3, type: 'VEC4' });+ doc.meshes = doc.meshes.slice(0, 2);+ for (const m of doc.meshes) m.primitives[0].attributes = { POSITION: 0, TEXCOORD_0: 1, JOINTS_0: 3, WEIGHTS_0: 4 };+ doc.nodes = [{ name: 'ActorA', mesh: 0, skin: 0 }, { name: 'ActorB', mesh: 1, skin: 1 }, { name: 'BoneA' }, { name: 'BoneB' }];+ doc.skins = [{ joints: [2] }, { joints: [3] }]; doc.scenes[0].nodes = [0, 1, 2, 3];+ const { result, prefab } = await importDoc(doc);+ expect(result.products.filter(p => p.endsWith('.esmesh'))).toHaveLength(1);+ const skins = prefab.entities.flatMap((e: any) => e.components.filter((c: any) => c.type === 'MeshSkin'));+ expect(skins.map((c: any) => c.data.joints)).toEqual([['n2'], ['n3']]);+ });++ it('shares generated LOD products and keeps every LOD reference resolvable', async () => {+ const doc = fixture(), positions: number[] = [], indices: number[] = [];+ for (let y = 0; y <= 8; y++) for (let x = 0; x <= 8; x++) positions.push(x, y, Math.sin(x) * .01);+ for (let y = 0; y < 8; y++) for (let x = 0; x < 8; x++) { const i = y * 9 + x; indices.push(i, i + 1, i + 9, i + 1, i + 10, i + 9); }+ const pos = new Float32Array(positions), idx = new Uint16Array(indices);+ const bytes = Buffer.concat([Buffer.from(pos.buffer), Buffer.from(idx.buffer)]);+ doc.buffers = [{ byteLength: bytes.length, uri: 'data:application/octet-stream;base64,' + bytes.toString('base64') }];+ doc.bufferViews = [{ buffer: 0, byteLength: pos.byteLength }, { buffer: 0, byteOffset: pos.byteLength, byteLength: idx.byteLength }];+ doc.accessors = [{ bufferView: 0, componentType: 5126, count: pos.length / 3, type: 'VEC3' }, { bufferView: 1, componentType: 5123, count: idx.length, type: 'SCALAR' }];+ doc.meshes = doc.meshes.slice(0, 2).map((m: any) => ({ ...m, primitives: [{ attributes: { POSITION: 0 }, indices: 1 }] }));+ doc.nodes = doc.nodes.slice(0, 2); doc.scenes[0].nodes = [0, 1];+ const { root, prefab } = await importDoc(doc, { lodLevels: 2, lodMinTriangles: 1 });+ const groups = prefab.entities.flatMap((e: any) => e.components.filter((c: any) => c.type === 'LODGroup'));+ expect(groups).toHaveLength(2);+ expect(groups[0].data).toEqual(groups[1].data);+ for (const key of ['lod1', 'lod2']) { expect(groups[0].data[key]).toBeTruthy(); expect(readFileSync(path.join(root, groups[0].data[key])).length).toBeGreaterThan(0); }+ });+});diff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.tsindex df4ec3e4f..54129bd6a 100644--- a/sdk/src/animation/Animator.ts+++ b/sdk/src/animation/Animator.ts@@ -896,7 +896,7 @@ export class AnimatorControllerAPI {const span: MotionSpan = {from: lrt.prevTime, to: lrt.time, inclusiveStart: lrt.entered,};- if (motion && events) this.emitEvents(ctx, entity, motion, span, events);+ if (motion) this.emitEvents(ctx, entity, motion, span, events);if (index === 0) {this.publishRootMotion(world, entity, ctx, motion, span, drivesRoot, travel);}@@ -941,13 +941,13 @@ export class AnimatorControllerAPI {*/private emitEvents(ctx: MotionContext, entity: Entity,- motion: AnimatorMotion, span: MotionSpan, events: AnimatorEventSink,+ motion: AnimatorMotion, span: MotionSpan, events?: AnimatorEventSink,): void {const crossed = this.eventScratch_;crossed.length = 0;ctx.events(motion, span, crossed);for (const e of crossed) {- events.send({ entity, name: e.name, value: e.value, text: e.text });+ events?.send({ entity, name: e.name, value: e.value, text: e.text });}}diff --git a/sdk/src/animation/motion.ts b/sdk/src/animation/motion.tsindex bf4f34ed2..d65c435ee 100644--- a/sdk/src/animation/motion.ts+++ b/sdk/src/animation/motion.ts@@ -211,6 +211,9 @@ export interface MotionDriver<M extends AnimatorMotion = AnimatorMotion> {* clip declares them. Wrapping belongs here for the same reason sampling does:* only the driver knows how long its clip runs and whether it repeats, and a* caller differencing two absolute times cannot tell a loop from a rewind.+ * This is also the active motion's native-effect dispatch point. It runs even+ * without a custom event sink, only for the selected motion (never its fading+ * predecessor). Sampling poses must stay free of those side effects.*/events?(ctx: MotionContext, motion: M, span: MotionSpan, out: MotionEvent[]): void;/**diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 77f1b0673..f02360387 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -306,6 +306,8 @@ export {} from './scene/sceneStreaming';export { sceneManagerPlugin } from './scene/scenePlugin';+export { NodeVisibility } from './scene/nodeVisibility';+export { CompoundCollider3D, type CompoundCollider3DData, type CompoundColliderPart3D } from './physics3d/CompoundCollider3D';// =============================================================================// World Residency@@ -1017,3 +1019,5 @@ export {} from './ai/fsm/Blackboard';export type { CompareOp, BlackboardGuard } from './ai/fsm/types';++export { ParticleModelUnits } from './particle/ParticleModelUnits';diff --git a/sdk/src/particle/ParticleModelUnits.ts b/sdk/src/particle/ParticleModelUnits.tsnew file mode 100644index 000000000..3c32a9d8b--- /dev/null+++ b/sdk/src/particle/ParticleModelUnits.ts@@ -0,0 +1,34 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { defineComponent, ParticleEmitter, Transform } from '../ecs/component';+import type { World } from '../ecs/world';+import type { Vec3 } from '../types';++/** Imported world-space particles: geometry follows Transform, lengths and forces use model units here. */+export const ParticleModelUnits = defineComponent('ParticleModelUnits', {+ startSizeMin: 1, startSizeMax: 1, endSizeMin: 1, endSizeMax: 1,+ speedMin: 0, speedMax: 0, gravity: { x: 0, y: 0, z: 0 } as Vec3,+});+export class ParticleModelUnitState {+ private snapshots = new Map<number, readonly number[]>();+ update(world: World): void {+ const live = new Set<number>();+ for (const entity of world.queryEntities([ParticleModelUnits, ParticleEmitter, Transform])) {+ live.add(entity);+ const s = world.get(entity, Transform).worldScale;+ const scale = Math.max(Math.abs(s.x), Math.abs(s.y), Math.abs(s.z));+ const units = world.get(entity, ParticleModelUnits);+ const snapshot = [scale, units.startSizeMin, units.startSizeMax, units.endSizeMin, units.endSizeMax,+ units.speedMin, units.speedMax, units.gravity.x, units.gravity.y, units.gravity.z];+ const previous = this.snapshots.get(entity);+ if (previous && snapshot.every((v, i) => v === previous[i])) continue;+ this.snapshots.set(entity, snapshot);+ const emitter = world.get(entity, ParticleEmitter);+ for (const key of ['startSizeMin', 'startSizeMax', 'endSizeMin', 'endSizeMax', 'speedMin', 'speedMax'] as const)+ emitter[key] = units[key] * scale;+ emitter.gravity = { x: units.gravity.x * scale, y: units.gravity.y * scale, z: units.gravity.z * scale };+ world.set(entity, ParticleEmitter, emitter);+ }+ for (const entity of this.snapshots.keys()) if (!live.has(entity)) this.snapshots.delete(entity);+ }+}diff --git a/sdk/src/particle/ParticlePlugin.ts b/sdk/src/particle/ParticlePlugin.tsindex faa3ee671..b396725e6 100644--- a/sdk/src/particle/ParticlePlugin.ts+++ b/sdk/src/particle/ParticlePlugin.ts@@ -8,6 +8,7 @@ import { fxPreviewOrPlayMode } from '../ecs/env';import type { CppRegistry } from '../wasm';import { engineApi } from '../ecs/bridge/engineApi';import { registerSceneComponentCodec } from '../scene/scene';+import { ParticleModelUnitState } from './ParticleModelUnits';import { Particle, ParticleAPI } from './ParticleAPI';import { particleQueryResolver } from './ParticleCollisionBridge';import { ParticleCollisionEvent, type ParticleCollisionEventPayload } from './collision';@@ -39,6 +40,7 @@ export class ParticlePlugin implements Plugin {// the resource, and every call through it no-ops.const engine = engineApi(app) ?? {};const registry = app.world.getCppRegistry() as CppRegistry;+ const modelUnits = new ParticleModelUnitState();const api = new ParticleAPI(engine, registry, particleQueryResolver(app));app.insertResource(Particle, api);this.overlay_ = `particle-collision:${++overlayId}`;@@ -97,6 +99,8 @@ export class ParticlePlugin implements Plugin {app.addSystemToSchedule(Schedule.Update, defineSystem([Res(Time), Res(Particle), EventWriter(ParticleCollisionEvent)],(time: TimeData, particle: ParticleAPI, events: EventWriterInstance<ParticleCollisionEventPayload>) => {+ app.world.ensureTransformsComposed();+ modelUnits.update(app.world);particle.update(time.delta);for (const hit of particle.collisionEvents) events.send(hit);},diff --git a/sdk/src/render/builtinShaders.ts b/sdk/src/render/builtinShaders.tsindex 0bbeb8662..67b13db58 100644--- a/sdk/src/render/builtinShaders.ts+++ b/sdk/src/render/builtinShaders.ts@@ -53,6 +53,8 @@ const SPRITE_UNLIT = `#pragma shader "Sprite Unlit"#pragma version 300 es#pragma domain Unlit#pragma param u_tint color default(1,1,1,1)+#pragma param u_alphaCutoff float default(0) range(0,1) ui(slider)+#pragma coverage u_alphaCutoff#pragma fragmentprecision mediump float;@@ -66,6 +68,7 @@ out vec4 fragColor;void main() {fragColor = texture(u_textures[0], v_texCoord) * v_color * u_tint;+ if (fragColor.a < u_alphaCutoff) discard;}#pragma end@@ -74,7 +77,9 @@ void main() {// Taken before any branch: a derivative needs every fragment of its quad.let duvx = dpdx(v.v_texCoord);let duvy = dpdy(v.v_texCoord);- return textureSampleGrad(t0, s0, v.v_texCoord, duvx, duvy) * v.v_color * mc.u_tint;+ let color = textureSampleGrad(t0, s0, v.v_texCoord, duvx, duvy) * v.v_color * mc.u_tint;+ if (color.a < mc.u_alphaCutoff) { discard; }+ return color;}#pragma end`;diff --git a/sdk/src/scene/nodeVisibility.ts b/sdk/src/scene/nodeVisibility.tsnew file mode 100644index 000000000..f8bb44750--- /dev/null+++ b/sdk/src/scene/nodeVisibility.ts@@ -0,0 +1,82 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { Children, defineComponent, renderableComponents, type RenderableComponentDef } from '../ecs/component';+import type { World } from '../ecs/world';+import type { Entity } from '../types';++/** An authored visual gate on a subtree. Cameras, physics and gameplay stay active. */+export const NodeVisibility = defineComponent('NodeVisibility', { visible: true }, { animatableFields: ['visible'] });++type Masked = { def: RenderableComponentDef; value: unknown };+const states = new WeakMap<World, NodeVisibilityState>();++/** Preserve authored renderer flags when saving a world with a hidden subtree. */+export function exportNodeVisibility(world: World, entity: Entity, component: string, data: Record<string, unknown>): void {+ const masked = states.get(world)?.masked.get(entity)?.find(row => row.def._name === component);+ if (masked) data[masked.def.renderableField] = masked.value;+}++/** No hierarchy walk or renderer write when the gates and scene structure are unchanged. */+export class NodeVisibilityState {+ readonly masked = new Map<Entity, Masked[]>();+ private gates = new Map<Entity, boolean>();+ private version = -1;++ update(world: World): void {+ states.set(world, this);+ const controls = world.getEntitiesWithComponents([NodeVisibility]);+ if (controls.length === 0 && this.masked.size === 0 && this.gates.size === 0) return;+ const version = world.getWorldVersion();+ let changed = version !== this.version || controls.length !== this.gates.size;+ const next = new Map<Entity, boolean>();+ for (const entity of controls) {+ const visible = !!world.get(entity, NodeVisibility).visible;+ next.set(entity, visible);+ if (this.gates.get(entity) !== visible) changed = true;+ }+ if (changed) {+ const hidden = new Set<Entity>();+ const stack = [...next].filter(([, visible]) => !visible).map(([entity]) => entity);+ while (stack.length) {+ const entity = stack.pop()!;+ if (hidden.has(entity) || !world.valid(entity)) continue;+ hidden.add(entity);+ if (world.has(entity, Children)) stack.push(...world.get(entity, Children).entities);+ }+ for (const [entity, rows] of this.masked) {+ if (hidden.has(entity)) continue;+ if (world.valid(entity)) for (const row of rows) {+ if (!world.has(entity, row.def)) continue;+ const data = world.get(entity, row.def) as Record<string, unknown>;+ data[row.def.renderableField] = row.value;+ world.set(entity, row.def, data);+ }+ this.masked.delete(entity);+ }+ const renderers = renderableComponents();+ for (const entity of hidden) {+ const rows = this.masked.get(entity) ?? [];+ for (const def of renderers) {+ if (!world.has(entity, def) || rows.some(row => row.def === def)) continue;+ rows.push({ def, value: (world.get(entity, def) as Record<string, unknown>)[def.renderableField] });+ }+ if (rows.length) this.masked.set(entity, rows);+ }+ this.gates = next;+ this.version = world.getWorldVersion();+ }+ // A renderer enabled by another animation under a hidden ancestor must+ // still stay hidden. Only hidden renderers are visited on stable frames.+ for (const [entity, rows] of this.masked) {+ if (!world.valid(entity)) { this.masked.delete(entity); continue; }+ for (const row of rows) {+ if (!world.has(entity, row.def)) continue;+ const data = world.get(entity, row.def) as Record<string, unknown>;+ if (data[row.def.renderableField] === false) continue;+ row.value = data[row.def.renderableField];+ data[row.def.renderableField] = false;+ world.set(entity, row.def, data);+ }+ }+ }+}diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.tsindex 9c1ab26eb..74d3cd864 100644--- a/sdk/src/scene/scene.ts+++ b/sdk/src/scene/scene.ts@@ -6,6 +6,7 @@*/import { World } from '../ecs/world';+import { exportNodeVisibility } from './nodeVisibility';import { Entity, INVALID_ENTITY } from '../types';import { upgradeEntityComponents } from './legacyComponents';import { isPrefabEntry, type SceneEntry } from './sceneEntry';@@ -15,6 +16,8 @@ import { validateScene } from './validateScene';import { getComponent, Name, Camera, RuntimeOnly } from '../ecs/component';import { deepClone } from '../util/deepClone';import { discoverSceneAssets } from '../asset/discoverAssets';+import { AssetScope } from '../asset/AssetLease';+import type { PrefabResult } from '../asset/AssetLoader';import { requireResourceManager } from '../wasm/resourceManager';import { validateComponentData, formatValidationErrors } from '../util/validation';import { log } from '../util/logger';@@ -652,15 +655,22 @@ export async function loadSceneWithAssets(let scene = sceneData;if (options?.assets && sceneHasPrefabEntries(scene)) {const assets = options.assets;- scene = await timed('prefab', () => expandScenePrefabs(scene, async (ref) => {- try {- const r = await assets.loadPrefab(ref);- return (r?.data as PrefabData) ?? null;- } catch (e) {- log.warn('scene', `Failed to load prefab "${ref}": ${e}`);- return null;- }- }));+ const sources = new AssetScope();+ try {+ scene = await timed('prefab', () => expandScenePrefabs(scene, async (ref) => {+ try {+ const lease = sources.add(await assets.acquireTyped<PrefabResult>('prefab', ref));+ return (lease.value.data as PrefabData) ?? null;+ } catch (e) {+ log.warn('scene', `Failed to load prefab "${ref}": ${e}`);+ return null;+ }+ }));+ } finally {+ // Expansion copies source JSON into scene records. Only those records'+ // asset dependencies outlive this phase, acquired by the preload below.+ sources.releaseAll();+ }}// Migrate up-front to a private copy; asset resolution + spawn all operate// on it, so the caller's SceneData is never mutated.@@ -858,6 +868,7 @@ export function serializeEntityComponents(world: World, entity: Entity): SceneCo// Components with out-of-band state (e.g. TilemapLayer chunks) fold// it into the record via their registered codec.sceneComponentCodec(world, typeName)?.exportData?.(entityNum, payload);+ exportNodeVisibility(world, entity, typeName, payload);components.push({type: typeName,data: payload,diff --git a/sdk/src/scene/scenePlugin.ts b/sdk/src/scene/scenePlugin.tsindex 663eb10dc..93d15c3d7 100644--- a/sdk/src/scene/scenePlugin.ts+++ b/sdk/src/scene/scenePlugin.ts@@ -17,6 +17,7 @@ import type { SystemDef } from '../ecs/system';import type { World } from '../ecs/world';import { log } from '../util/logger';import { ensureSceneAiRegistrations } from './ai-builtins';+import { NodeVisibilityState } from './nodeVisibility';const sceneTransitionSystem = defineSystem([ResMut(SceneManager), Res(Time)],@@ -61,6 +62,9 @@ export const sceneManagerPlugin: Plugin = {// app assemblies: a cell IS an additive scene, so an assembly that can load// one can stream one, and a fourth place to remember is a place to forget.app.addPlugin(worldResidencyPlugin);+ const visibility = new NodeVisibilityState();+ app.addSystemToSchedule(Schedule.PostUpdate, defineSystem([], () => visibility.update(app.world),+ { name: 'NodeVisibilitySystem' }));const initSystem: SystemDef = {_id: Symbol('SceneInitSystem'),diff --git a/sdk/src/timeline/TimelineControl.ts b/sdk/src/timeline/TimelineControl.tsindex 3ebae35ac..e5854666b 100644--- a/sdk/src/timeline/TimelineControl.ts+++ b/sdk/src/timeline/TimelineControl.ts@@ -105,7 +105,10 @@ export class TimelineAPI {s.playing = false;s.time = 0;s.prevTime = 0;+ s.phase = 0;+ s.started = false;s.spineClipIndices = {};+ s.nested = {};}this.flags_?.reset(entity);}@@ -115,6 +118,8 @@ export class TimelineAPI {if (s) {s.prevTime = s.time;s.time = time;+ s.phase = time;+ s.started = true;}}diff --git a/sdk/src/timeline/TimelineDrive.ts b/sdk/src/timeline/TimelineDrive.tsindex af34f1365..0ee0dd60d 100644--- a/sdk/src/timeline/TimelineDrive.ts+++ b/sdk/src/timeline/TimelineDrive.ts@@ -7,16 +7,17 @@** Holds a per-entity playback clock and, each frame: advances time (speed + wrap),* samples property tracks (via the shared evaluator), and edge-detects event-track- * triggers (spine/audio/spriteAnim/activation) dispatching them through the shared- * {@link applyTimelineEvent}. The interpolation + event-detection logic is a 1:1- * port of TimelineSystem.cpp (evaluateChannel / advance / evaluateEventTracks) so- * playback matches the C++ runtime bit-for-bit and that runtime can be deleted.+ * triggers through the shared {@link applyTimelineEvent}. Event windows use the+ * same playhead runs as animator motions, including loop seams and ping-pong+ * turns; a folded sample time alone cannot preserve playback direction.*/import { applyWrapMode, sampleTimeline, type SampleDeps, type SampleOptions } from './TimelineEvaluator';import { applyTimelineEvent, TimelineEventType } from './TimelineRuntime';import { TrackType, WrapMode, type TimelineAsset } from './TimelineTypes';+import { forEachParticleEvent, playheadRuns, runCrosses, type PlayheadRun } from './timelineEvents';import { collectSequenceLayers, resolveActiveShot, type ActiveShot, type SequenceLookup } from './timelineSequences';+import type { ParticleAPI } from '../particle/ParticleAPI';import type { AudioAPI } from '../audio/Audio';import type { Entity } from '../types';@@ -24,6 +25,10 @@ import type { Entity } from '../types';export interface TimelineState {time: number;prevTime: number;+ /** Unfolded playback time. Optional for callers constructing older state records. */+ phase?: number;+ /** Whether the entry instant has already been dispatched. */+ started?: boolean;playing: boolean;speed: number;wrapMode: WrapMode;@@ -34,7 +39,7 @@ export interface TimelineState {}export function createTimelineState(wrapMode: WrapMode = WrapMode.Once, speed = 1): TimelineState {- return { time: 0, prevTime: 0, playing: false, speed, wrapMode, spineClipIndices: {}, nested: {} };+ return { time: 0, prevTime: 0, phase: 0, started: false, playing: false, speed, wrapMode, spineClipIndices: {}, nested: {} };}export interface FiredEvent {@@ -46,20 +51,22 @@ export interface FiredEvent {}/**- * Edge-detect event-track triggers fired in (prevTime, time] — a 1:1 port of- * TimelineSystem::evaluateEventTracks. Mutates `state.spineClipIndices`.+ * Edge-detect event-track triggers over playback runs. Mutates `state.spineClipIndices`.*/export function detectTimelineEvents(asset: TimelineAsset, state: TimelineState,resolveChild: (root: Entity, childPath: string) => Entity | null, root: Entity,- // Monotone edge-detection interval(s). Defaults to the single (prevTime, time]- // span; on a loop wrap the caller passes the two seam segments so a trigger- // near the loop boundary still fires (one interval is empty when time < prevTime).+ // Legacy tuples describe forward-only intervals; explicit runs also describe+ // a ping-pong return and whether this is the clip's entry instant.// Level tracks (Spine, Activation) read `state.time` directly and ignore this.- segments: ReadonlyArray<readonly [number, number]> = [[state.prevTime, state.time]],+ segments: ReadonlyArray<readonly [number, number] | PlayheadRun> = [[state.prevTime, state.time]],): FiredEvent[] {const out: FiredEvent[] = [];const { time } = state;+ const runs = segments.map(segment => 'from' in segment ? segment : {+ from: segment[0], to: Math.max(segment[0], segment[1]),+ inclusiveStart: segment[0] === 0 && segment[1] > segment[0],+ });for (let i = 0; i < asset.tracks.length; i++) {const track = asset.tracks[i];@@ -69,6 +76,12 @@ export function detectTimelineEvents(if (target == null) continue;switch (track.type) {+ case TrackType.Particle: {+ forEachParticleEvent(track, runs, action => {+ out.push({ kind: TimelineEventType.ParticleAction, entity: target, intParam: 0, floatParam: 0, str: action });+ });+ break;+ }case TrackType.Spine: {let currentClip = -1;for (let ci = track.clips.length - 1; ci >= 0; ci--) {@@ -88,8 +101,8 @@ export function detectTimelineEvents(break;}case TrackType.SpriteAnim: {- for (const [from, to] of segments) {- if (to > from && from <= track.startTime && track.startTime <= to) {+ for (const run of runs) {+ if (runCrosses(run, track.startTime)) {out.push({ kind: TimelineEventType.SpriteAnimPlay, entity: target, intParam: 0, floatParam: 0, str: track.clip });break; // fire at most once across the seam segments}@@ -97,9 +110,9 @@ export function detectTimelineEvents(break;}case TrackType.Audio: {- for (const [from, to] of segments) {+ for (const run of runs) {for (const e of track.events) {- if (e.time > from && e.time <= to) {+ if (runCrosses(run, e.time)) {out.push({ kind: TimelineEventType.AudioPlay, entity: target, intParam: 0, floatParam: e.volume, str: e.clip });}}@@ -122,6 +135,7 @@ export function detectTimelineEvents(export interface AdvanceContext {deps: SampleDeps;audio?: AudioAPI | null;+ particle?: Pick<ParticleAPI, 'play' | 'stop' | 'reset'> | null;/** Skip-channel filter (editor mute); forwarded to the sampler. */sampleOpts?: SampleOptions;/** Side-effect hook after a property field is applied (e.g. UINode anim flags). */@@ -159,6 +173,8 @@ export function applyPlayerFlags(flags: TimelinePlayerFlags, state: TimelineStatif (flags.playing && flags.finished) {state.time = 0;state.prevTime = 0;+ state.phase = 0;+ state.started = false;state.spineClipIndices = {};state.nested = {};flags.finished = false;@@ -195,24 +211,24 @@ export function advanceTimelineTS(): boolean {if (!state.playing) return false;+ let phase = state.phase ?? state.time;+ // Preserve the existing writable `time` control surface for callers that seek+ // through the state record rather than TimelineAPI.setTime.+ if (applyWrapMode(phase, asset.duration, state.wrapMode).time !== state.time) phase = state.time;state.prevTime = state.time;- const advanced = state.time + dt * state.speed;+ const advanced = phase + dt * state.speed;const wrapped = applyWrapMode(advanced, asset.duration, state.wrapMode);state.time = wrapped.time;+ state.phase = advanced;sampleTimeline(asset, state.time, root, ctx.deps, ctx.sampleOpts);ctx.onPropertyApplied?.(root, asset);- // On a loop wrap the playhead ran prevTime → duration → 0 → time; split edge- // detection across both seam segments so triggers near the loop boundary keep- // firing each loop (the plain (prevTime, time] span is empty when time < prevTime).- const segments: ReadonlyArray<readonly [number, number]> =- state.wrapMode === WrapMode.Loop && advanced >= asset.duration && asset.duration > 0- ? [[state.prevTime, asset.duration], [0, state.time]]- : [[state.prevTime, state.time]];+ const segments = playheadRuns(phase, advanced, asset.duration, state.wrapMode, !state.started);+ state.started = true;for (const e of detectTimelineEvents(asset, state, ctx.deps.resolveChild, root, segments)) {- applyTimelineEvent(ctx.deps.world, ctx.audio ?? null, e.kind, e.entity, e.intParam, e.floatParam, e.str);+ applyTimelineEvent(ctx.deps.world, ctx.audio ?? null, e.kind, e.entity, e.intParam, e.floatParam, e.str, ctx.particle);}const lookup = ctx.lookup ?? NO_TIMELINES;@@ -245,7 +261,7 @@ function advanceNested(asset: TimelineAsset, root: Entity, state: TimelineState,const segments: ReadonlyArray<readonly [number, number]> = layer.time < prev? [[prev, layer.asset.duration], [0, layer.time]] : [[prev, layer.time]];for (const e of detectTimelineEvents(layer.asset, child, ctx.deps.resolveChild, layer.root, segments)) {- applyTimelineEvent(ctx.deps.world, ctx.audio ?? null, e.kind, e.entity, e.intParam, e.floatParam, e.str);+ applyTimelineEvent(ctx.deps.world, ctx.audio ?? null, e.kind, e.entity, e.intParam, e.floatParam, e.str, ctx.particle);}state.nested[layer.key] = { time: layer.time, spineClipIndices: child.spineClipIndices };}diff --git a/sdk/src/timeline/TimelineLoader.ts b/sdk/src/timeline/TimelineLoader.tsindex 912b4a9d0..6b6aa065b 100644--- a/sdk/src/timeline/TimelineLoader.ts+++ b/sdk/src/timeline/TimelineLoader.ts@@ -10,6 +10,7 @@ import {type SpineTrack,type SpriteAnimTrack,type AudioTrack,+ type ParticleTrack,type ActivationTrack,type MarkerTrack,type CustomEventTrack,@@ -131,6 +132,11 @@ function parseTrack(raw: any): Track {markers: raw.markers ?? [],} as MarkerTrack;+ case TrackType.Particle:+ return { ...base, type: TrackType.Particle, events: (raw.events ?? []).filter((e: any) =>+ Number.isFinite(e.time) && e.time >= 0 && ['play', 'stop', 'reset'].includes(e.action))+ .map((e: any) => ({ time: e.time, action: e.action })) } as ParticleTrack;+case TrackType.CustomEvent:return {...base,diff --git a/sdk/src/timeline/TimelinePlugin.ts b/sdk/src/timeline/TimelinePlugin.tsindex 6e4a85d92..12a639754 100644--- a/sdk/src/timeline/TimelinePlugin.ts+++ b/sdk/src/timeline/TimelinePlugin.ts@@ -15,6 +15,7 @@ import { Timeline, TimelineAPI } from './TimelineControl';import { AnimatorController } from '../animation/Animator';import { TIMELINE_MOTION, createTimelineMotionDriver } from './timelineMotion';import { resolveChildEntity } from './TimelineRuntime';+import { Particle } from '../particle/ParticleAPI';import { advanceTimelineTS, applyPlayerFlags, latchPlayerFinish } from './TimelineDrive';import { CameraDirector, setTimelineShot } from '../camera/CameraDirector';import type { SampleDeps } from './TimelineEvaluator';@@ -64,7 +65,9 @@ export class TimelinePlugin implements Plugin {// and a build without it still plays timelines through TimelinePlayer.if (app.hasResource(AnimatorController)) {app.getResource(AnimatorController).registerMotionDriver(- TIMELINE_MOTION, createTimelineMotionDriver(app.getResource(Timeline)),+ TIMELINE_MOTION, createTimelineMotionDriver(app.getResource(Timeline), {+ particle: () => app.hasResource(Particle) ? app.getResource(Particle) : null,+ }),);}@@ -112,6 +115,7 @@ export class TimelinePlugin implements Plugin {this.ensureAnimFrames(entity, asset);const justFinished = advanceTimelineTS(asset, entity, state, time.delta, {+ particle: app.hasResource(Particle) ? app.getResource(Particle) : null,deps, audio,lookup: (ref) => tl.getAsset(ref),onShot: director ? (shot) => setTimelineShot(director, entity, shot) : undefined,diff --git a/sdk/src/timeline/TimelineRuntime.ts b/sdk/src/timeline/TimelineRuntime.tsindex 479847c11..395c3a0f6 100644--- a/sdk/src/timeline/TimelineRuntime.ts+++ b/sdk/src/timeline/TimelineRuntime.ts@@ -5,6 +5,7 @@ import { SpriteAnimator } from '../animation/SpriteAnimator';// Straight from the generated enum module (the C++ ES_ENUM is the single source), not// via the UI barrel: this file is core runtime and must not pull the UI module in.import { UIDisplay } from '../wasm/wasm.generated';+import type { ParticleAPI } from '../particle/ParticleAPI';import type { AudioAPI } from '../audio/Audio';import type { Entity } from '../types';import type { World } from '../ecs/world';@@ -22,6 +23,7 @@ export const TimelineEventType = {SpriteAnimPlay: 2,AudioPlay: 3,ActivationSet: 4,+ ParticleAction: 5,} as const;export { resolveChildEntity } from '../ecs/childPath';@@ -35,7 +37,7 @@ export function setNestedProperty(obj: Record<string, any>, path: string, value:}const lastKey = parts[parts.length - 1];if (!(lastKey in target)) return false;- target[lastKey] = value;+ target[lastKey] = typeof target[lastKey] === 'boolean' ? value !== 0 : value;return true;}@@ -43,9 +45,15 @@ export function setNestedProperty(obj: Record<string, any>, path: string, value:export function applyTimelineEvent(world: any, audio: AudioAPI | null,type: number, entity: Entity,- intParam: number, floatParam: number, str: string,+ intParam: number, floatParam: number, str: string, particle?: Pick<ParticleAPI, 'play' | 'stop' | 'reset'> | null,): void {switch (type) {+ case TimelineEventType.ParticleAction: {+ if (str === 'play') { particle?.reset(entity); particle?.play(entity); }+ else if (str === 'stop') particle?.stop(entity);+ else if (str === 'reset') particle?.reset(entity);+ break;+ }case TimelineEventType.SpinePlay: {if (world.has(entity, SpineAnimation)) {const current = world.get(entity, SpineAnimation);diff --git a/sdk/src/timeline/TimelineSerializer.ts b/sdk/src/timeline/TimelineSerializer.tsindex fe2910d2f..5e57c72a1 100644--- a/sdk/src/timeline/TimelineSerializer.ts+++ b/sdk/src/timeline/TimelineSerializer.ts@@ -37,6 +37,7 @@ function serializeTrack(track: Track): Record<string, unknown> {return { ...base, clips: track.clips, blendIn: track.blendIn };case TrackType.SpriteAnim:return { ...base, clip: track.clip, startTime: track.startTime };+ case TrackType.Particle:case TrackType.Audio:return { ...base, events: track.events };case TrackType.Activation:diff --git a/sdk/src/timeline/TimelineTypes.ts b/sdk/src/timeline/TimelineTypes.tsindex 38e2ad213..ac61f90f7 100644--- a/sdk/src/timeline/TimelineTypes.ts+++ b/sdk/src/timeline/TimelineTypes.ts@@ -51,6 +51,7 @@ export const TrackType = {Spine: 'spine',SpriteAnim: 'spriteAnim',Audio: 'audio',+ Particle: 'particle',Activation: 'activation',Marker: 'marker',CustomEvent: 'customEvent',@@ -104,6 +105,11 @@ export interface SpriteAnimTrack extends TrackBase {startTime: number;}+export interface ParticleTrack extends TrackBase {+ type: typeof TrackType.Particle;+ events: { time: number; action: 'play' | 'stop' | 'reset' }[];+}+export interface AudioEvent {time: number;clip: string;@@ -193,7 +199,7 @@ export interface SequenceTrack extends TrackBase {clips: SequenceClip[];}-export type Track = PropertyTrack | SpineTrack | SpriteAnimTrack | AudioTrack | ActivationTrack | MarkerTrack | CustomEventTrack | AnimFramesTrack | CameraTrack | SequenceTrack;+export type Track = PropertyTrack | SpineTrack | SpriteAnimTrack | ParticleTrack | AudioTrack | ActivationTrack | MarkerTrack | CustomEventTrack | AnimFramesTrack | CameraTrack | SequenceTrack;export interface TimelineAsset {version: string;diff --git a/sdk/src/timeline/index.ts b/sdk/src/timeline/index.tsindex f37c05956..582236637 100644--- a/sdk/src/timeline/index.ts+++ b/sdk/src/timeline/index.ts@@ -118,4 +118,5 @@ export {export {TIMELINE_MOTION,createTimelineMotionDriver,+ type TimelineMotionEffects,} from './timelineMotion';diff --git a/sdk/src/timeline/timelineEvents.ts b/sdk/src/timeline/timelineEvents.tsindex 61e082f1a..f80e51c5e 100644--- a/sdk/src/timeline/timelineEvents.ts+++ b/sdk/src/timeline/timelineEvents.ts@@ -18,7 +18,7 @@* that is here, so the loop seam is a unit test rather than a frame.*/-import { WrapMode, TrackType, type TimelineAsset } from './TimelineTypes';+import { WrapMode, TrackType, type TimelineAsset, type ParticleTrack } from './TimelineTypes';import type { MotionEvent } from '../animation/motion';/**@@ -78,6 +78,10 @@ export function playheadRuns(const cycle = duration * 2;if (span >= cycle) return [{ from: 0, to: duration, inclusiveStart: true }];+ if (span === 0) {+ const time = pingPongPhase(from, duration);+ return [{ from: time, to: time, inclusiveStart }];+ }const runs: PlayheadRun[] = [];let phase = from % cycle;const end = phase + span;@@ -106,6 +110,30 @@ export function runCrosses(run: PlayheadRun, at: number): boolean {return inclusiveStart && at === from;}+/** Shared by standalone players and animator motions; pose sampling never fires effects. */+export function forEachParticleEvent(+ track: ParticleTrack, runs: readonly PlayheadRun[],+ emit: (action: ParticleTrack['events'][number]['action']) => void,+): void {+ for (const run of runs) {+ let first: ParticleTrack['events'][number] | undefined;+ let crossed: ParticleTrack['events'] | undefined;+ for (const event of track.events) {+ if (!runCrosses(run, event.time)) continue;+ if (!first) first = event;+ else (crossed ??= [first]).push(event);+ }+ // Most frames cross no key or one key. Only a multi-key crossing needs+ // storage and ordering; a reverse run must reach the later key first.+ // Stable sort preserves authored order for actions at the same instant.+ if (crossed) {+ const direction = run.to < run.from ? -1 : 1;+ crossed.sort((a, b) => direction * (a.time - b.time));+ for (const event of crossed) emit(event.action);+ } else if (first) emit(first.action);+ }+}+/** The event's numeric payload, or 0 where it carries none. */function payloadValue(payload: Record<string, unknown> | undefined): number {const v = payload?.value;diff --git a/sdk/src/timeline/timelineMotion.ts b/sdk/src/timeline/timelineMotion.tsindex f566a248a..50563fa69 100644--- a/sdk/src/timeline/timelineMotion.ts+++ b/sdk/src/timeline/timelineMotion.ts@@ -27,9 +27,10 @@ import {applyWrapMode, sampleTimelineIntoPose, isRootPlacementChannel,sampleRootPlacement, createRootPlacement, type SampleDeps, type SampleOptions,} from './TimelineEvaluator';-import { playheadRuns, collectCustomEvents } from './timelineEvents';-import { resolveChildEntity } from './TimelineRuntime';-import { WrapMode, type TimelineAsset } from './TimelineTypes';+import { playheadRuns, collectCustomEvents, forEachParticleEvent } from './timelineEvents';+import { applyTimelineEvent, resolveChildEntity, TimelineEventType } from './TimelineRuntime';+import { TrackType, WrapMode, type TimelineAsset } from './TimelineTypes';+import type { ParticleAPI } from '../particle/ParticleAPI';import { q } from '../math/quat';import type { TimelineAPI } from './TimelineControl';@@ -54,7 +55,12 @@ const WITHOUT_ROOT: SampleOptions = { skipChannel: isRootPlacementChannel };* The driver, over the app's own {@link TimelineAPI}: which clip a name resolves* to is per App, so this is built per App rather than being a module value.*/-export function createTimelineMotionDriver(timeline: TimelineAPI): MotionDriver<AnimatorClipMotion> {+export interface TimelineMotionEffects {+ /** Resolve lazily: a module may be installed after the timeline plugin. Per App. */+ particle?: () => Pick<ParticleAPI, 'play' | 'stop' | 'reset'> | null;+}++export function createTimelineMotionDriver(timeline: TimelineAPI, effects: TimelineMotionEffects = {}): MotionDriver<AnimatorClipMotion> {// Two placements, reused: extraction runs per animated entity per frame, and// one of these per call is an allocation the steady state does not need.const before = createRootPlacement();@@ -100,7 +106,18 @@ export function createTimelineMotionDriver(timeline: TimelineAPI): MotionDriver<): void {const asset = timeline.getAsset(motion.clip);if (!asset) return;- collectCustomEvents(asset, runsOf(asset, motion, span), out);+ const runs = runsOf(asset, motion, span);+ collectCustomEvents(asset, runs, out);+ const particle = effects.particle?.();+ if (!particle) return;+ for (const track of asset.tracks) {+ if (track.type !== TrackType.Particle) continue;+ const target = ctx.resolveJoint(ctx.entity, track.childPath);+ if (target === null) continue;+ forEachParticleEvent(track, runs, action => {+ applyTimelineEvent(ctx.world, null, TimelineEventType.ParticleAction, target, 0, 0, action, particle);+ });+ }},/**diff --git a/sdk/tests/animator-particles.test.ts b/sdk/tests/animator-particles.test.tsnew file mode 100644index 000000000..124bd056e--- /dev/null+++ b/sdk/tests/animator-particles.test.ts@@ -0,0 +1,93 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { Animator, AnimatorControllerAPI, type AnimatorControllerDef } from '../src/animation';+import { World } from '../src/ecs/world';+import { ensureBuiltinComponentsRegistered } from '../src/ecs/component';+import { createMockModule } from './mocks/wasm';+import { createTimelineMotionDriver } from '../src/timeline/timelineMotion';+import { TimelineAPI } from '../src/timeline/TimelineControl';+import { TrackType, WrapMode, type TimelineAsset, type ParticleTrack } from '../src/timeline/TimelineTypes';++const clip = (events: ParticleTrack['events'], wrapMode = WrapMode.Once): TimelineAsset => ({+ version: '1.3', type: 'timeline', duration: 1, wrapMode,+ tracks: [{ type: TrackType.Particle, name: 'burst', childPath: 'Sparks', events }],+});+const motion = (name: string, loop = false) => ({ kind: 'timeline', clip: name, loop });+function fixture(clips: Record<string, TimelineAsset>, def?: AnimatorControllerDef) {+ ensureBuiltinComponentsRegistered();+ const module = createMockModule(), world = new World(); world.connectCpp(module.getRegistry(), module);+ const root = world.spawn('Actor'), sparks = world.spawn('Sparks'); world.setParent(sparks, root);+ const timeline = new TimelineAPI();+ for (const [name, asset] of Object.entries(clips)) timeline.registerAsset(name, asset);+ const calls: string[] = [], targets: number[] = [];+ const particle = Object.fromEntries(['play', 'stop', 'reset'].map(action => [action, (entity: number) => {+ calls.push(action); targets.push(entity);+ }])) as { play(e: number): void; stop(e: number): void; reset(e: number): void };+ const controller = new AnimatorControllerAPI();+ controller.registerMotionDriver('timeline', createTimelineMotionDriver(timeline, { particle: () => particle }));+ controller.registerController('graph', def ?? {+ parameters: [], initialState: 'Play', states: [{ name: 'Play', motion: motion('burst'), transitions: [] }],+ });+ world.insert(root, Animator, { controller: 'graph', currentState: '', enabled: true });+ return { world, root, sparks, calls, targets, controller, tick: (dt: number) => controller.update(world, dt) };+}++describe('native particle tracks through animator motions', () => {+ it('fires the time-zero burst once without requiring a custom-event listener', () => {+ const f = fixture({ burst: clip([{ time: 0, action: 'play' }, { time: .3, action: 'stop' }]) });+ f.tick(0); f.tick(0); f.tick(.1); f.tick(.25); f.tick(2); f.tick(1);+ expect(f.calls).toEqual(['reset', 'play', 'stop']);+ expect(f.targets.every(e => e === f.sparks)).toBe(true);+ });+ it('repeats on each loop without replaying the boundary on the following frame', () => {+ const f = fixture({ burst: clip([{ time: 0, action: 'play' }, { time: .5, action: 'stop' }], WrapMode.Loop) }, {+ parameters: [], initialState: 'Play', states: [{ name: 'Play', motion: motion('burst', true), transitions: [] }],+ });+ f.tick(0); for (let i = 0; i < 8; i++) f.tick(.26);+ expect(f.calls).toEqual(['reset', 'play', 'stop', 'reset', 'play', 'stop', 'reset', 'play']);+ });+ it('cancels events from a fading state and restarts them on re-entry', () => {+ const f = fixture({ burst: clip([{ time: 0, action: 'play' }, { time: .3, action: 'stop' }]), idle: clip([]) }, {+ parameters: [{ name: 'switch', type: 'trigger' }], initialState: 'Burst', states: [+ { name: 'Burst', motion: motion('burst'), transitions: [{ to: 'Idle', duration: .5, conditions: [{ param: 'switch', op: 'trigger' }] }] },+ { name: 'Idle', motion: motion('idle'), transitions: [{ to: 'Burst', conditions: [{ param: 'switch', op: 'trigger' }] }] },+ ],+ });+ f.tick(0); f.tick(.1); f.controller.setTrigger(f.root, 'switch'); f.tick(.1); f.tick(.4);+ expect(f.calls).toEqual(['reset', 'play']);+ f.controller.setTrigger(f.root, 'switch'); f.tick(.1); f.tick(.4);+ expect(f.calls).toEqual(['reset', 'play', 'reset', 'play', 'stop']);+ });+ it('dispatches only the selected blend motion, although both poses are sampled', () => {+ const f = fixture({ low: clip([{ time: .2, action: 'play' }]), high: clip([{ time: .2, action: 'stop' }]) }, {+ parameters: [{ name: 'speed', type: 'float', default: .8 }], initialState: 'Blend', states: [{ name: 'Blend',+ motion: { kind: 'blend1d', parameter: 'speed', thresholds: [{ value: 0, motion: motion('low') }, { value: 1, motion: motion('high') }] }, transitions: [] }],+ });+ f.tick(0); f.tick(.3); expect(f.calls).toEqual(['reset', 'play']);+ });+ it('skips missing targets and keeps effects isolated between apps', () => {+ const a = fixture({ burst: clip([{ time: 0, action: 'play' }]) });+ const b = fixture({ burst: clip([{ time: 0, action: 'play' }]) });+ a.world.despawn(a.sparks); a.tick(0); b.tick(0);+ expect(a.calls).toEqual([]); expect(b.calls).toEqual(['reset', 'play']);+ });+ it('fires once at entry and on each crossing of a ping-pong clip', () => {+ const f = fixture({ burst: clip([{ time: 0, action: 'play' }, { time: .5, action: 'stop' }], WrapMode.PingPong) }, {+ parameters: [], initialState: 'Play', states: [{ name: 'Play', motion: { kind: 'timeline', clip: 'burst' }, transitions: [] }],+ });+ f.tick(0); f.tick(0); for (let i = 0; i < 4; i++) f.tick(.6);+ expect(f.calls).toEqual(['reset', 'play', 'stop', 'stop', 'reset', 'play']);+ });+ it.each([false, true])('orders particle keys by travel direction, keeping equal-time authored order (sorted: %s)', sorted => {+ const events: ParticleTrack['events'] = [+ { time: .8, action: 'stop' }, { time: .2, action: 'play' }, { time: .2, action: 'stop' },+ ];+ if (sorted) events.sort((a, b) => a.time - b.time);+ const f = fixture({ burst: clip(events, WrapMode.PingPong) }, {+ parameters: [], initialState: 'Play', states: [{ name: 'Play', motion: { kind: 'timeline', clip: 'burst' }, transitions: [] }],+ });+ f.tick(0); f.tick(1.05); f.tick(.9);+ expect(f.calls).toEqual(['reset', 'play', 'stop', 'stop', 'stop', 'reset', 'play', 'stop']);+ });+});diff --git a/sdk/tests/node-visibility.test.ts b/sdk/tests/node-visibility.test.tsnew file mode 100644index 000000000..075741c6f--- /dev/null+++ b/sdk/tests/node-visibility.test.ts@@ -0,0 +1,67 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it, vi } from 'vitest';+import { World } from '../src/ecs/world';+import { Camera, Sprite, ensureBuiltinComponentsRegistered } from '../src/ecs/component';+import { BoxCollider2D } from '../src/physics/components';+import { NodeVisibility, NodeVisibilityState } from '../src/scene/nodeVisibility';+import { serializeEntityComponents } from '../src/scene/scene';+import { setNestedProperty } from '../src/timeline/TimelineRuntime';+import { createMockModule } from './mocks/wasm';++function fixture() {+ ensureBuiltinComponentsRegistered();+ const module = createMockModule(), world = new World();+ world.connectCpp(module.getRegistry(), module);+ const root = world.spawn('root'), child = world.spawn('child'), leaf = world.spawn('leaf');+ world.setParent(child, root); world.setParent(leaf, child);+ world.insert(root, NodeVisibility, { visible: false });+ world.insert(child, NodeVisibility, { visible: false });+ world.insert(child, Camera, { isActive: true });+ world.insert(child, BoxCollider2D, { enabled: true });+ world.insert(leaf, Sprite, { enabled: true });+ return { world, root, child, leaf, state: new NodeVisibilityState() };+}++describe('hierarchical visual visibility', () => {+ it('composes nested gates without disabling physics or the camera', () => {+ const { world, root, child, leaf, state } = fixture();+ state.update(world);+ expect(world.get(leaf, Sprite).enabled).toBe(false);+ expect(world.get(child, Camera).isActive).toBe(true);+ expect(world.get(child, BoxCollider2D).enabled).toBe(true);+ world.set(root, NodeVisibility, { visible: true }); state.update(world);+ expect(world.get(leaf, Sprite).enabled).toBe(false);+ world.set(child, NodeVisibility, { visible: true }); state.update(world);+ expect(world.get(leaf, Sprite).enabled).toBe(true);+ });++ it('saves authored flags, preserves disabled renderers and makes no stable-frame writes', () => {+ const { world, root, child, leaf, state } = fixture();+ world.insert(child, Sprite, { enabled: false });+ state.update(world);+ expect(serializeEntityComponents(world, leaf).find(c => c.type === 'Sprite')!.data.enabled).toBe(true);+ const write = vi.spyOn(world, 'set'); state.update(world);+ expect(write).not.toHaveBeenCalled();+ world.set(root, NodeVisibility, { visible: true }); world.set(child, NodeVisibility, { visible: true }); state.update(world);+ expect(world.get(child, Sprite).enabled).toBe(false);+ });++ it('restores a reparented renderer and a renderer whose gate was removed', () => {+ const { world, root, child, leaf, state } = fixture();+ state.update(world); world.removeParent(leaf); state.update(world);+ expect(world.get(leaf, Sprite).enabled).toBe(true);+ world.setParent(leaf, root); state.update(world);+ expect(world.get(leaf, Sprite).enabled).toBe(false);+ world.remove(root, NodeVisibility); state.update(world);+ expect(world.get(leaf, Sprite).enabled).toBe(true);+ world.despawn(child); state.update(world);+ });++ it('keeps boolean fields boolean when a timeline supplies numeric samples', () => {+ const data = { visible: true, layer: 3 };+ setNestedProperty(data, 'visible', 0); expect(data.visible).toBe(false);+ setNestedProperty(data, 'visible', 1); expect(data.visible).toBe(true);+ setNestedProperty(data, 'layer', 0); expect(data.layer).toBe(0);+ });+});diff --git a/sdk/tests/particle-model-units.test.ts b/sdk/tests/particle-model-units.test.tsnew file mode 100644index 000000000..95f2b77b2--- /dev/null+++ b/sdk/tests/particle-model-units.test.ts@@ -0,0 +1,31 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it, vi } from 'vitest';+import { World } from '../src/ecs/world';+import { ParticleEmitter, Transform, ensureBuiltinComponentsRegistered } from '../src/ecs/component';+import { ParticleModelUnits, ParticleModelUnitState } from '../src/particle/ParticleModelUnits';+import { createMockModule } from './mocks/wasm';++describe('particle model units', () => {+ it('updates authored sizes and forces without compounding scale or rewriting stable emitters', () => {+ ensureBuiltinComponentsRegistered();+ const module = createMockModule(), world = new World();+ world.connectCpp(module.getRegistry(), module);+ const entity = world.spawn('imported emitter'), state = new ParticleModelUnitState();+ world.insert(entity, Transform, { worldScale: { x: 100, y: 100, z: 100 } });+ world.insert(entity, ParticleEmitter, {});+ world.insert(entity, ParticleModelUnits, { startSizeMin: .25, speedMin: 2, gravity: { x: 0, y: -9.8, z: 0 } });+ state.update(world);+ expect(world.get(entity, ParticleEmitter)).toMatchObject({ startSizeMin: 25, speedMin: 200 });+ expect(world.get(entity, ParticleEmitter).gravity.y).toBeCloseTo(-980);+ const write = vi.spyOn(world, 'set'); state.update(world);+ expect(write).not.toHaveBeenCalled();+ world.set(entity, ParticleModelUnits, { ...world.get(entity, ParticleModelUnits), startSizeMin: .5 });+ state.update(world); expect(world.get(entity, ParticleEmitter).startSizeMin).toBe(50);+ world.set(entity, Transform, { ...world.get(entity, Transform), worldScale: { x: 200, y: 200, z: 200 } });+ state.update(world); expect(world.get(entity, ParticleEmitter)).toMatchObject({ startSizeMin: 100, speedMin: 400 });+ world.remove(entity, ParticleModelUnits); state.update(world);+ world.insert(entity, ParticleModelUnits, { startSizeMin: .5 }); state.update(world);+ expect(world.get(entity, ParticleEmitter).speedMin).toBe(0);+ });+});diff --git a/sdk/tests/scene-prefab-lifetime.test.ts b/sdk/tests/scene-prefab-lifetime.test.tsnew file mode 100644index 000000000..a109fcfc5--- /dev/null+++ b/sdk/tests/scene-prefab-lifetime.test.ts@@ -0,0 +1,109 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it, vi } from 'vitest';+import { Assets } from '../src/asset/Assets';+import { AssetScope } from '../src/asset/AssetLease';+import { PrefabAssetLoader } from '../src/asset/loaders/PrefabAssetLoader';+import type { Backend } from '../src/asset/Backend';+import type { PrefabResult } from '../src/asset/AssetLoader';+import { World } from '../src/ecs/world';+import { loadSceneWithAssets, type SceneData } from '../src/scene/scene';+import { createMockModule } from './mocks/wasm';++vi.mock('../src/wasm/resourceManager', () => ({+ requireResourceManager: () => ({}),+ getResourceManager: () => null,+}));++function harness(missingChild = false) {+ const child = {+ version: '2', name: 'Leaf', rootEntityId: 'leaf',+ entities: [{ prefabEntityId: 'leaf', name: 'Leaf', parent: null, children: [], components: [], visible: true }],+ };+ const root = {+ version: '2', name: 'Tree', rootEntityId: 'root',+ entities: [+ { prefabEntityId: 'root', name: 'Tree', parent: null, children: ['branch'], components: [], visible: true },+ { prefabEntityId: 'branch', name: 'Branch', parent: 'root', children: [], components: [], visible: true,+ nestedPrefab: { prefabPath: 'leaf.esprefab', overrides: [] } },+ ],+ };+ const documents: Record<string, unknown> = { 'tree.esprefab': root };+ if (!missingChild) documents['leaf.esprefab'] = child;+ const module = createMockModule();+ const assets = Assets.create({+ module: module as never,+ backend: {+ fetchText: vi.fn(async (path: string) => {+ const document = documents[path.split('/').pop()!];+ if (!document) throw new Error('missing fixture');+ return JSON.stringify(document);+ }),+ fetchBinary: vi.fn(async () => new ArrayBuffer(0)),+ resolveUrl: (path: string) => path,+ } as unknown as Backend,+ });+ const loader = new PrefabAssetLoader();+ const unloaded = vi.spyOn(loader, 'unload');+ assets.register(loader);+ const world = new World(module);+ const scene = {+ version: 4, name: 'Forest',+ entities: [1, 2].map(id => ({ id, parent: null, prefab: 'tree.esprefab', overrides: [], added: [], removed: [] })),+ } as unknown as SceneData;+ const scope = new AssetScope();+ const options = {+ assets,+ collectAssets: { scope, texturePaths: new Set<string>(), materialHandles: new Set<number>(), fontPaths: new Set<string>(), spineKeys: new Set<string>() },+ };+ return { world, assets, scene, options, unloaded };+}++describe('scene prefab source ownership', () => {+ it('repeated loads release repeated and nested source acquisitions while keeping expanded entities alive', async () => {+ const { world, assets, scene, options, unloaded } = harness();+ const original = JSON.stringify(scene);+ for (let i = 0; i < 6; i++) {+ const spawned = await loadSceneWithAssets(world, scene, options);+ expect(spawned.size).toBe(4);+ expect(world.findEntityByName('Leaf')).not.toBeNull();+ expect(assets.sizes().refRows).toBe(0);+ for (const entity of spawned.values()) if (world.valid(entity)) world.despawn(entity);+ }+ expect(JSON.stringify(scene)).toBe(original);+ expect(unloaded).toHaveBeenCalledTimes(12);+ });++ it('releases only the expansion receipts when another owner holds the same source', async () => {+ const { world, assets, scene, options, unloaded } = harness();+ const held = await assets.acquireTyped<PrefabResult>('prefab', 'tree.esprefab');+ await loadSceneWithAssets(world, scene, options);+ expect(assets.sizes().refRows).toBe(1);+ expect(unloaded).toHaveBeenCalledTimes(1); // nested source only+ const second = await assets.acquireTyped<PrefabResult>('prefab', 'tree.esprefab');+ expect(second.value).toBe(held.value);+ second.release();+ held.release();+ expect(assets.sizes().refRows).toBe(0);+ expect(unloaded).toHaveBeenCalledTimes(2);+ });++ it('releases a skipped instance whose nested source cannot be loaded', async () => {+ const { world, assets, scene, options, unloaded } = harness(true);+ const spawned = await loadSceneWithAssets(world, scene, options);+ expect(spawned.size).toBe(0);+ expect(assets.sizes().refRows).toBe(0);+ expect(unloaded).toHaveBeenCalledTimes(1);+ });++ it('does not leave source receipts behind when a phase observer aborts the load', async () => {+ const { world, assets, scene, options, unloaded } = harness();+ await expect(loadSceneWithAssets(world, scene, {+ ...options,+ onPhase: phase => { if (phase === 'prefab') throw new Error('cancelled'); },+ })).rejects.toThrow('cancelled');+ expect(assets.sizes().refRows).toBe(0);+ expect(unloaded).toHaveBeenCalledTimes(2);+ expect(world.getAllEntities()).toHaveLength(0);+ });+});diff --git a/sdk/tests/scene-prefab.test.ts b/sdk/tests/scene-prefab.test.tsindex 0c1afc810..a7b5a231c 100644--- a/sdk/tests/scene-prefab.test.ts+++ b/sdk/tests/scene-prefab.test.ts@@ -17,6 +17,7 @@ import { World } from '../src/ecs/world';import { createMockModule } from './mocks/wasm';import { defineBuiltin, defineComponent } from '../src/ecs/component';import { INVALID_ENTITY } from '../src/types';+import { ownedAssetLease } from '../src/asset/AssetLease';import {loadSceneData,loadSceneWithAssets,@@ -98,7 +99,8 @@ function mockAssets(prefabs: Record<string, PrefabData | null>) {}),resolveSceneAssetPaths: vi.fn(),trackSceneAssetReferences: vi.fn(),- loadPrefab: vi.fn(async (ref: string) => ({ data: prefabs[ref] ?? null })),+ acquireTyped: vi.fn(async (_type: string, ref: string) =>+ ownedAssetLease(ref, 1, { data: prefabs[ref] ?? null }, () => {})),// eslint-disable-next-line @typescript-eslint/no-explicit-any} as any;}@@ -227,7 +229,7 @@ describe('Prefab scene loading (PF1)', () => {const assets = mockAssets({ [REF]: prefab });await loadSceneWithAssets(world, scene, { assets });- expect(assets.loadPrefab).toHaveBeenCalledWith(REF);+ expect(assets.acquireTyped).toHaveBeenCalledWith('prefab', REF);// Ground + Turret (root) + BigBarrel (barrel); scope removed.expect(world.findEntityByName('Ground')).not.toBeNull();expect(world.findEntityByName('Turret')).not.toBeNull();diff --git a/sdk/tests/timeline-drive.test.ts b/sdk/tests/timeline-drive.test.tsindex 4a79e64dd..40a725689 100644--- a/sdk/tests/timeline-drive.test.ts+++ b/sdk/tests/timeline-drive.test.ts@@ -324,3 +324,37 @@ describe('nested sequences', () => {expect(Object.keys(s.nested)).toHaveLength(0);});});++describe('native particle event tracks', () => {+ it('keeps the ping-pong phase across frames and shares entry/crossing semantics with animator motions', () => {+ const asset: TimelineAsset={version:'1.3',type:'timeline',duration:1,wrapMode:WrapMode.PingPong,+ tracks:[{type:TrackType.Particle,name:'burst',childPath:'',events:[{time:0,action:'play'},{time:.5,action:'stop'}]}]};+ const state=createTimelineState(WrapMode.PingPong);state.playing=true;+ const calls:string[]=[],particle={reset:()=>calls.push('reset'),play:()=>calls.push('play'),stop:()=>calls.push('stop')};+ const deps:SampleDeps={world:{} as SampleDeps['world'],getComponent:()=>undefined,resolveChild:resolveRoot};+ advanceTimelineTS(asset,ROOT,state,0,{deps,particle});+ advanceTimelineTS(asset,ROOT,state,0,{deps,particle});+ const times:number[]=[];+ for(let i=0;i<4;i++){advanceTimelineTS(asset,ROOT,state,.6,{deps,particle});times.push(state.time);}+ [.6,.8,.2,.4].forEach((time,i)=>expect(times[i]).toBeCloseTo(time));+ expect(calls).toEqual(['reset','play','stop','stop','reset','play']);+ const api=new TimelineAPI();const owned=api.ensureState(ROOT,WrapMode.PingPong,1);+ Object.assign(owned,state);api.stop(ROOT);api.play(ROOT);+ advanceTimelineTS(asset,ROOT,owned,.1,{deps,particle});+ expect(owned.time).toBeCloseTo(.1);expect(calls.slice(-2)).toEqual(['reset','play']);+ });+ it('restarts once at zero, stops at its key, and fires again across a loop', () => {+ const asset: TimelineAsset={version:'1.3',type:'timeline',duration:1,wrapMode:WrapMode.Loop,+ tracks:[{type:TrackType.Particle,name:'burst',childPath:'',events:[{time:0,action:'play'},{time:.5,action:'stop'}]}]};+ const state=createTimelineState(WrapMode.Loop);state.playing=true;+ const calls:string[]=[],particle={reset:()=>calls.push('reset'),play:()=>calls.push('play'),stop:()=>calls.push('stop')};+ const deps:SampleDeps={world:{} as SampleDeps['world'],getComponent:()=>undefined,resolveChild:resolveRoot};+ advanceTimelineTS(asset,ROOT,state,.1,{deps,particle});+ advanceTimelineTS(asset,ROOT,state,.1,{deps,particle});+ expect(calls).toEqual(['reset','play']);+ advanceTimelineTS(asset,ROOT,state,.4,{deps,particle});+ expect(calls).toEqual(['reset','play','stop']);+ advanceTimelineTS(asset,ROOT,state,.5,{deps,particle});+ expect(calls).toEqual(['reset','play','stop','reset','play']);+ });+});