Add scene component snapshots

[waynemwashuma]

Objective

Introduce a snapshot-based serialization workflow for scenes and components. The primary goal is to allow resource-backed (especially asset-backed) components to serialize stable references instead of transient runtime handles, enabling scenes to be saved and restored across worlds while preserving asset relationships.

This introduces HandleSnapshot, component snapshot APIs, and TypeRegistry-driven snapshot restoration.

Secondary changes include a small abstraction utility for snapshot interfaces and reusable abstract class error helpers.

Solution

Handle snapshots

Asset handles are runtime objects whose underlying IDs are not stable across scene serialization. To address this, Handle now supports conversion into a serializable snapshot, HandleSnapshot<T>.

When an asset was loaded through the AssetServer, the snapshot stores asset type, and asset path or it falls back to the asset id. Snapshots can later be used to restore a live handle. Path-backed assets are reloaded through the asset server while asset id snapshots upgrade against the registered asset pool.

Note

Asset path snapshots are preferred because they survive world recreation. Asset ID snapshots remain supported as a fallback but restoration is currently limited and may become invalid when asset collections diverge between scene and world state.

Scene serialization pipeline

Scenes previously relied exclusively on registered clone() methods. This worked for runtime duplication but could not correctly serialize resource-backed references. Scene serialization now supports dedicated snapshot methods. This allows components to serialize external references differently from runtime cloning behavior.

Snapshot-enabled asset components

Added snapshot support for:

• AudioPlayer
• Meshed
• BasicMaterial2D
• BasicMaterial3D
• SceneInstance
• Asset Handle

Each component now converts asset handles into HandleSnapshot instances during scene serialization and restores them during scene spawning.:

TypeRegistry integration

New snapshot types are registered in reflection metadata:

• HandleSnapshot
• AudioPlayerSnapshot
• MeshedSnapshot
• BasicMaterial2DSnapshot
• BasicMaterial3DSnapshot
• SceneInstanceSnapshot

The registry now stores snapshot conversion methods allowing scene serialization to remain entirely reflection-driven.

Utility improvements

Added:

formatString(...)

for indexed string formatting.

Added:

abstractMethod(...)
abstractClass(...)

for reusable abstract-class and abstract-method validation.

Showcase

Example:

class MyComponent {
  toSnapshot(world) {
    return new MyComponentSnapshot(...)
  }
}

class MyComponentSnapshot {
  fromSnapshot(world) {
    return new MyComponent(...)
  }
}

Register snapshot methods in the TypeRegistry:

registry.get(MyComponent)
  ?.setMethod(MyComponent.prototype.toSnapshot)

registry.get(MyComponentSnapshot)
  ?.setMethod(MyComponentSnapshot.prototype.fromSnapshot)

Scenes cloned runtime handles directly. Asset-backed components depended on runtime asset IDs remaining valid. Now, components can serialize stable asset references to scenes. On spawning, snapshot is reloaded through the asset server to yield a correct handle.

Migration guide

No migration required

Checklist

• I have updated the documentation accordingly.
• I have added tests to cover my changes.