You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(scene): built-in component codecs and UUID reference hooks #717
Register production YAML/binary codecs and UUID-reference hooks for every
currently authored built-in ECS component. The existing reflection registrations
are not serializer registrations, and static initialization is not an accepted
production lifecycle.
Implement codecs for the current document components: TransformComponent, ParentComponent, MeshComponent, CameraComponent, LightComponent, MaterialComponent, NameComponent, and RigidBodyComponent.
Materialize the mandatory UUIDComponent from the owning entity record UUID;
it is not a second component-map payload with an independently editable UUID.
Classify authored, runtime-derived, editor-only, and forbidden fields. Runtime
fields such as RenderInstanceId and GPU handles are excluded.
Invalid component payloads produce structured errors rather than being dropped.
Tests cover codec values, field keys, reference enumeration, and rejection
cases for each built-in component.
References
ZEngine/docs/future-plan/scene-serialization.md sections 2, 4, 6, and 11.
Implementation API contract
This function is the sole built-in registration entry point and is called by
engine startup immediately after the registry is initialized. It registers the
following fixed durable schema keys: zengine.ecs.transform, zengine.ecs.parent, zengine.ecs.mesh, zengine.ecs.camera, zengine.ecs.light, zengine.ecs.material, zengine.ecs.name, and zengine.ecs.rigid_body. These names are source compatibility commitments, not
C++ type names.
Each schema supplies the SceneComponentCodecFns and SceneReferenceFns
defined by #714. ParentComponent uses a parent_uuid source field and is
resolved only after every candidate entity has been created. Mesh/material UUIDs
are enumerated as asset references. Duplication, clipboard, undo/redo, and Play
snapshot remapping operate on SceneValue payloads through Remap; they do not
patch a live ECS scene.
The required authored-field matrix is:
Schema key
Authored fields
Excluded derived fields
zengine.ecs.transform
position, rotation, scale
previous_position, world_transform
zengine.ecs.parent
parent_uuid
runtime EntityID
zengine.ecs.mesh
mesh_uuid
render_instance_id
zengine.ecs.camera
fov_y, near, far, aspect_ratio, is_main
padding
zengine.ecs.light
type, intensity, range, spot_angle, color
padding
zengine.ecs.material
material_uuid
—
zengine.ecs.name
value
—
zengine.ecs.rigid_body
motion_type, mass, friction, restitution
body_id, padding
The loader—not a schema callback—adds UUIDComponent{SceneEntityRecord::UUID}
and rejects a conflicting component-map UUID entry. This prevents two durable
identity sources from drifting apart.
changed the title [-]feat(scene): register YAML + binary serialize fns for all 8 built-in components[/-][+]feat(scene): built-in component codecs and UUID reference hooks[/+]on Sep 17, 2026
Summary
Register production YAML/binary codecs and UUID-reference hooks for every
currently authored built-in ECS component. The existing reflection registrations
are not serializer registrations, and static initialization is not an accepted
production lifecycle.
Scope
during engine startup.
TransformComponent,ParentComponent,MeshComponent,CameraComponent,LightComponent,MaterialComponent,NameComponent, andRigidBodyComponent.UUIDComponentfrom the owning entity record UUID;it is not a second component-map payload with an independently editable UUID.
fields such as
RenderInstanceIdand GPU handles are excluded.references, and component-specific constraints.
by staged load, duplication, undo/redo, and Play restoration.
scene-document path, and keep
EntityIDonly in loader/runtime maps.Non-goals
std::function, reflection offsets, orraw-byte serialization.
and staged resolver.
Dependencies
Acceptance criteria
UUIDComponentwhose value exactly equals itsSceneEntityRecord::UUID.feat(scene): transactional scene load and runtime reconstruction #829.
cases for each built-in component.
References
ZEngine/docs/future-plan/scene-serialization.mdsections 2, 4, 6, and 11.Implementation API contract
This function is the sole built-in registration entry point and is called by
engine startup immediately after the registry is initialized. It registers the
following fixed durable schema keys:
zengine.ecs.transform,zengine.ecs.parent,zengine.ecs.mesh,zengine.ecs.camera,zengine.ecs.light,zengine.ecs.material,zengine.ecs.name, andzengine.ecs.rigid_body. These names are source compatibility commitments, notC++ type names.
Each schema supplies the
SceneComponentCodecFnsandSceneReferenceFnsdefined by #714.
ParentComponentuses aparent_uuidsource field and isresolved only after every candidate entity has been created. Mesh/material UUIDs
are enumerated as asset references. Duplication, clipboard, undo/redo, and Play
snapshot remapping operate on
SceneValuepayloads throughRemap; they do notpatch a live ECS scene.
The required authored-field matrix is:
zengine.ecs.transformposition,rotation,scaleprevious_position,world_transformzengine.ecs.parentparent_uuidEntityIDzengine.ecs.meshmesh_uuidrender_instance_idzengine.ecs.camerafov_y,near,far,aspect_ratio,is_mainzengine.ecs.lighttype,intensity,range,spot_angle,colorzengine.ecs.materialmaterial_uuidzengine.ecs.namevaluezengine.ecs.rigid_bodymotion_type,mass,friction,restitutionbody_id, paddingThe loader—not a schema callback—adds
UUIDComponent{SceneEntityRecord::UUID}and rejects a conflicting component-map UUID entry. This prevents two durable
identity sources from drifting apart.