Skip to content

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.

feat(import): restore scene materials, animation and native effects

yhhd47de974e271
diff --git a/pipeline/bridges/godot/README.md b/pipeline/bridges/godot/README.md
new file mode 100644
index 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.gd
new file mode 100644
index 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.ts
index 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, ImportedIm
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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): Com
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 fragment
precision 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: TimelineStat
if (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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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']);
+ });
+});