Skip to content
Wima Engine
← All news

Wima 0.4.0 - Scenes, worlds and richer scheduling.

Wima 0.4.0 expands how you build, organize, and reuse game content. Scenes gain JSON serialization, resource snapshots, embedded assets, and selective restoration. Applications can manage multiple worlds and run systems across them. Particle emitters provide a new way to build effects, while changes to queries, commands, plugins, and scheduling give developers more control over application behavior.

This release also improves the everyday experience of working with Wima. A rebuilt documentation website, expanded guides and API references, unified pointer events, and fixes to scene instancing, asset ownership and canvas resizing.

There is a lot to cover. Here is a closer look at the individual changes.

Save and load scenes as JSON

PRs: #338

Scenes can now be exported to JSON and reconstructed through Wima’s asset pipeline. JSONSceneExporter converts scene data into a persistent representation, while JSONSceneImporter reconstructs scenes from JSON assets.

This moves scene content beyond application initialization code. A scene can be stored separately, loaded when needed, and instantiated through the same asset-oriented workflow used elsewhere in the engine. The type registry supplies the component reconstruction behavior, allowing supported types to participate without adding a special case to the scene importer for each component.

The JSON representation also makes scene data inspectable. You can examine serialized content independently of a running application, making it easier to understand what a scene contains and how that content is restored.

Include resources in scene snapshots

PRs: #346

Scene snapshots now include resources alongside entities and components. Components describe individual entities; resources represent state shared within a world. Capturing both allows scenes to represent more of the state needed to reconstruct their contents.

Resource restoration also supports patching existing resources. This provides a path for applying scene resource state incrementally, instead of requiring every restoration to replace an entire resource. The behavior depends on the restoration support provided by the resource type.

Component and resource snapshot handling now follows a shared conversion workflow. Registered snapshot methods are used where available, with cloning as a fallback and warnings for unsupported cases. Custom types still need the appropriate registration and conversion behavior to participate correctly.

Package embedded assets with a scene

PRs: #348

Serializing an asset handle is only part of preserving a scene. Runtime asset identifiers belong to the world that created them; they cannot simply be assumed to identify the same assets in another world.

Embedded asset support addresses this by allowing scenes to contain serialized asset collections. During restoration, Wima reconstructs those assets and maps scene-local references to their new runtime handles. Handle restoration can resolve asset-server paths where available, or use the mapping for embedded assets.

For supported assets, this removes the need to manually recreate matching asset collections before loading a scene. The updated scene-loading sample uses embedded assets to demonstrate that workflow.

Choose what a scene restores

PRs: #367

The new SceneFilter asset lets you control which component and resource types are restored when instantiating a scene.

An allow list restores only the listed types. A deny list excludes the listed types while allowing the others. The filter is applied during restoration, before unwanted types are introduced into the destination world.

Because filters are assets, multiple scene instances can share the same configuration. This lets one scene participate in different restoration workflows without requiring a separate serialized copy for every selection of component and resource types.

Keep scene instances independent

PRs: #308, #309, #311

Scene instantiation now uses registered cloning behavior to duplicate component state. This fixes cases where instances could reuse component references and unintentionally share mutable objects.

The change is supported by standardized static copy and clone methods across engine components and registration of those methods in the type registry. Generic scene code can ask a type how it should be duplicated, while each type retains control over its own copying semantics.

For custom scene components, registering cloning behavior remains important. Unsupported components are skipped with a warning rather than being silently treated as safely cloneable.

Preserve relationships when instantiating scenes

PRs: #339, #340

Cloning component values does not, by itself, fix entity references. A parent reference stored in a scene must point to the newly created parent entity after instantiation.

Scene spawning now uses two passes: destination entities are created first, and relationships are remapped once the complete entity mapping exists. This avoids references being resolved before their target entities have been created.

The relationship abstraction also gains explicit remapping support through TraverseEntities. Relationship components can expose the entities they reference and update those references when entities are reconstructed with new identifiers.

Refresh instances when their scene changes

PRs: #372

Live instances now respond to changes in their source scene asset. When a SceneModified event is processed, instances referencing that asset are queued for rebuilding.

Each instance keeps its root entity while its spawned children are recreated from the updated scene. This fixes the previous behavior where the asset could change but existing instances continued displaying outdated contents.

This behavior responds to scene asset modification events; it does not imply automatic filesystem watching or preservation of arbitrary state on rebuilt children.

Build particle effects in 2D and 3D

PRs: #301

The emitter module introduces configurable particle spawning for both 2D and 3D.

Particles are defined through prefab functions, allowing their composition to use the engine’s existing entity and component model. A customization hook can modify individual spawned particles, providing variation without requiring a different emitter implementation for every effect.

Emission timing uses the timer infrastructure, and the module provides spawning and lifecycle behavior alongside examples. This gives applications a reusable starting point for effects while leaving particle composition under application control.

Manage multiple worlds in one application

PRs: #353

An application can now manage multiple ECS worlds through a world registry. Schedules can target specific worlds, allowing independent collections of entities and resources to run under one application.

For example, a game could keep its main simulation separate from a preview world. Each world owns its state, and the application determines which schedules operate on it. The core plugin supplies MainWorld as the default, so ordinary applications do not need to adopt multiple worlds to continue using the engine.

World configuration is also staged through application APIs. Hooks, resource aliases, and resources are applied during startup, giving plugins a consistent way to configure the worlds they use.

Run systems across two worlds

PRs: #354

Cross-world schedules provide an explicit place for logic that needs access to two worlds. A cross-world system receives both its target world and its source world, allowing application-defined synchronization or data extraction.

These schedules reuse the ordering infrastructure, including before and after constraints. The default runner executes cross-world schedules before standard schedules and resolves their configured worlds at runtime.

This provides the mechanism for transferring selected state between worlds. Applications still define what gets transferred and how it is transformed; multiple worlds do not automatically synchronize their contents.

Express system execution order

PRs: #318, #322, #329

Systems can declare explicit ordering constraints, making dependencies part of schedule configuration.

A system that produces data can be placed before the systems that consume it. Transform updates are a familiar example: local changes must be propagated before later systems rely on the resulting global transforms. Explicit ordering makes this relationship visible and allows the scheduler to build an execution order around it.

This release also fixes transform-system ordering and ordering behavior involving empty groups.

Organize systems into nested groups

PRs: #316, #319, #320, #321

System groups provide a way to organize related work and express ordering at the group level. Nested groups extend that organization to subsystems with their own internal structure.

A plugin can contribute systems to a group, while application configuration controls where that group belongs relative to other work. This avoids requiring every application to order every internal system individually.

Default groups establish shared places for engine systems to participate in schedules. Together with individual ordering constraints, groups give developers control over both broad execution stages and dependencies within them.

Drive schedules through an application runner

PRs: #300, #298

Schedule execution moves from individual executors to a runner-based model. The runner coordinates execution, allowing multiple schedules to be driven from one loop.

Applications using the default setup receive the standard runner through the core infrastructure. Applications with specialized execution requirements can provide their own runner.

This changes custom scheduling integrations: executor implementations must migrate to the runner model, and schedule configuration uses the new configuration-based API. Per-system error handling is also available through configured schedule handlers.

Query optional components

PRs: #365

Queries can now select a component without requiring every matching entity to contain it. The Optional filter and optional() helper distinguish required components from optional ones.

// Position and Velocity are application-defined component types.
const query = new Query(
  world,
  [Position, Velocity],
  [optional(Velocity)]
)

query.each(([position, velocity]) => {
  // Every result has Position.
  // Velocity is undefined when the entity does not have it.
  if (velocity !== undefined) {
    // Handle the optional component here.
  }
})

Only required descriptors participate in archetype matching. The selected tuple keeps its component order, and type information reflects that an optional component can be undefined. This behavior applies across query access and iteration methods, including combination iteration.

Access optional resources without throwing

PRs: #362

World.getOptionalResource() and World.getOptionalResourceByTypeId() return undefined when the requested resource is absent. Both preserve resource alias resolution.

// DebugSettings is an application-defined resource type.
const settings = world.getOptionalResource(DebugSettings)

if (settings !== undefined) {
  // Use the optional configuration.
}

Required getters continue to assert when a resource is missing. This gives systems an explicit choice: enforce a required dependency, or support an optional integration whose absence is expected.

Use a shared deferred command queue

PRs: #305, #358

Deferred command execution now uses a shared CommandQueue. Entity and window command providers feed that queue instead of maintaining independent buffers and separate flushing systems.

Command providers are constructed around a world, rather than retrieved as stateful command resources. Commands implement execute(world), and execution is centralized.

The command infrastructure also moves into a dedicated package. Applications using direct package imports should review those imports as part of upgrading.

Defer more world operations

PRs: #357, #359

The available command operations expand beyond the queue refactor itself. Resource changes can now be deferred, and entity commands gain cloning, component removal, and reparenting operations.

These additions let systems express more structural changes through the command workflow. Entity cloning provides a deferred duplication operation; component removal changes an entity’s composition; reparenting changes its hierarchy placement. Resource commands extend the same deferred model to world-level state.

Validate plugin dependencies at startup

PRs: #364

Plugins can declare dependencies through requires(). After plugin registration, Wima validates those requirements before systems begin running.

Missing dependencies are reported with the requiring plugin and the missing plugin, making configuration mistakes easier to identify at their source. Duplicate-plugin registration also receives stronger diagnostics, including registration traces.

Applications assembling their own plugin sets should ensure every declared dependency is present and remove duplicate registrations.

Finish initialization after plugin registration

PRs: #364

Plugins also gain a finish(app) lifecycle stage. It runs after registration and dependency validation, providing a place for setup that relies on the complete set of registered plugins.

This is distinct from declaring dependencies. A dependency declaration describes what must be present; finish() provides the later initialization opportunity once registration is complete. Queued hooks, aliases, and resources are applied after this stage.

Describe more types through reflection

PRs: #295, #302, #307, #352

Reflection gains metadata for common container structures: arrays, sets, maps, and tuples. These metadata types describe the relationships between a container and the types of values it contains.

Type entries can also register callable methods. Generic systems can discover and invoke registered behavior by name, supporting workflows such as cloning and serialization without hardcoding every participating type.

Automatic type registration in the ECS world and expanded engine type registration further connect runtime state to the reflection system.

Serialize components and resources consistently

PRs: #337

Supported engine types gain static serialization, deserialization, and serialized-data validation methods, registered through the type system.

Each type controls how its values are represented and reconstructed. This supplies a common contract for persistence while retaining the type-specific behavior needed for engine objects and asset references.

These methods underpin scene persistence, but are useful independently wherever supported runtime values need a serializable representation.

Serialize reflection metadata

PRs: #363

Reflection metadata itself can now be serialized, deserialized, and validated. Supported TypeInfo subtypes define their representations, and TypeRegistry supports registry-level conversion.

This preserves descriptions of types, rather than the application objects those types describe. It makes reflection schemas persistable and portable, with a kind discriminator identifying the appropriate metadata representation during reconstruction.

Deserialization can also reuse supported output instances. Serializing metadata should not be confused with serializing executable JavaScript implementations.

Share one material component across 2D and 3D

PRs: #342

MaterialInstance replaces the separate Material2D and Material3D component variants. The material asset remains the reusable material data, while the component associates the material with an entity.

This removes duplicated component and plugin infrastructure across the two rendering paths. Reusable mesh prefab helpers also simplify common render-entity setup.

Existing applications should migrate their material components and review custom code that refers to the old variants.

Release owned asset handles on component removal

PRs: #341

Engine-defined components that own asset handles now release those handles when removed. The cleanup covers relevant animation, rendering, and scene components, keeping reference counts aligned with component ownership.

This matters when entities and scenes are repeatedly created and destroyed. A removed component should no longer keep an asset alive through an unreleased handle.

Custom components holding asset handles still need their own removal hooks. The automatic cleanup added here applies to the engine components that register that behavior.

Respect orthographic projection in Canvas2D

PRs: #313

The Canvas2D renderer now uses orthographic camera projection bounds. Camera configuration determines the visible world area instead of rendering relying solely on implicit bounds derived from window dimensions.

This gives 2D cameras meaningful control over projection and world-space scale. It also makes projection an explicit part of the renderer contract: unsupported camera projection types are rejected.

Applications upgrading older Canvas2D scenes should review their camera projection and coordinate assumptions together.

Handle mouse and touch through pointer events

PRs: #299, #369, #370

Pointing input now uses a shared pointer-event pipeline. Separate mouse and touch event streams are replaced by pointer events, while device-specific handling can inspect the pointer type.

The change brings mouse and touch input under one event model and improves touch tracking through stable pointer-to-touch identifiers. Existing code consuming removed mouse or touch event types must migrate to their pointer equivalents.

Separate fixes address mouse event consumption and movement updates for the first touch pointer.

Keep canvas buffers synchronized with CSS

PRs: #368

CSS can change a canvas’s displayed size without changing its backing-buffer dimensions. Previously, this could leave the engine’s logical window size and the actual drawing buffer out of step.

The resize handling now rounds layout measurements to integer dimensions and uses those dimensions consistently for the backing buffer, engine window state, and emitted resize event. Rounding before comparison also avoids repeated resize detection caused by fractional CSS measurements.

This improves canvas behavior in responsive layouts and embedded examples where the surrounding page controls the available space.

Explore the rebuilt documentation website

PRs: #371, #373

The documentation website now brings guides, generated API references, and runnable examples together through an Astro-based build.

Examples are self-contained, with camera setup defined locally and legacy example-launcher infrastructure removed. The site also receives updated navigation, Wima branding, and light and dark themes.

Learn through expanded guides and API references

PRs: #373

Alongside the website rebuild, the documentation content expands substantially. Getting-started material covers application setup, entities, components, systems, queries, and resources. Deeper guides explain worlds, schedules, plugins, commands, rendering, assets, and other engine concepts.

Package READMEs describe responsibilities and core abstractions. Source-level API documentation adds parameter descriptions, return behavior, limitations, examples, and cross-references. Building and contributing guides provide additional entry points for developers working on the engine itself.

Additional improvements

Several supporting changes round out this release:

  • Entity naming: Entity is renamed to EntityHandle, making the handle abstraction explicit. #350
  • Plugin-group customization: add() and remove() become chainable, and replace() provides a direct way to replace a plugin of the same type. #315, #344
  • Asset import/export APIs: asset exporters are introduced, parsers are renamed to importers, and the type registry becomes available to those workflows. #330, #331, #332
  • Primary-window configuration: configured primary-window options are passed through when the default window is created. #343
  • Math and color dependencies: internal implementations are replaced with Hisabati and Marangi, respectively. #360, #361
  • Collection utilities: internal collection infrastructure moves to Vifaa. #335
  • Package distribution: UMD builds return, alongside distribution-based exports. #356
  • Repository tooling: workspace organization, the build pipeline, and development tooling are updated. #351

Planned future work

The next roadmap items are changes to the renderer, scene pipeline and editor workflow:

WebGPU renderer

Wima’s rendering is already organized around the ECS: cameras, meshes, materials, transforms, and renderable state live in the world, while backend systems gather that state and draw it through WebGL2. The current path works for the existing examples, but its rendering stages are still closely tied to the backend and do not provide a clear extension model. Renderer plugins cannot easily add, replace, or reorder stages without depending on backend-specific behavior.

Chorama is an experimental rendering package that organizes the sequence as an ordered graph of rendering nodes. A node can prepare scene data, establish a camera view, draw a particular class of objects, or apply a later image-processing step. The graph already describes stages such as opaque and transparent drawing, depth preparation, shadows, tone mapping, bloom, and presenting the final image. Chorama is still implemented on WebGL2 today; its value for Wima is the way it explores extensible rendering structure, not a finished WebGPU backend that can be copied directly.

Wima will map those rendering nodes to systems and system groups. Scene preparation, camera setup, opaque and transparent drawing, depth and shadow work, and post-processing will each have an explicit place in the application schedule. Their ordering will use Wima’s existing scheduling model, so renderer plugins can add a stage, declare what it must run before or after, and participate in the same lifecycle as the rest of the engine. Rendering will remain driven by Wima’s ECS and scenes rather than introducing a separate scene representation just for the renderer.

The target is feature parity with Chorama, not just a replacement for Wima’s current backends. At the renderer level, that means supporting 2D and 3D meshes, multiple material and shader paths, textures and samplers, camera and multi-view rendering, canvas and offscreen targets, opaque and transparent passes, depth and shadow passes, lighting, skinning, morph targets, and post-processing such as fog, tone mapping, and bloom. Wima’s plugin and scheduling model should make each of those stages available for extension without binding them to one graphics API.

Once that system-based rendering structure is in place, Wima can add a WebGPU backend beneath it. The backend will implement the full Chorama renderer feature set while the scene, camera, mesh, material, and transform data stays independent of the graphics API. The migration will proceed in slices, starting with camera and mesh rendering and then covering materials, multi-view targets, transparent objects, depth and shadow passes, lighting, animation data, and post-processing. Existing WebGL and Canvas2D backends will remain available while the feature set moves across; they can be deprecated after the WebGPU renderer reaches Chorama-level parity.

Scene-based particle emitters

The current emitter API builds each particle from a prefab callback. That works for small effects, but it makes particle content difficult to work with outside application code. An emitter cannot create effects and the resources those effects need. The result is that a particle effect has to be reconstructed by hand wherever it is used.

Scene-based emitters will replace that callback-oriented workflow with a reference to a scene asset. Each emission will instantiate the referenced scene as a particle, then apply the emitter’s lifetime and particle bookkeeping while preserving the scene instance particle. The same scene can then be used by multiple emitters. For example, a spark scene can be emitted from a torch, a hit effect, or a moving projectile without duplicating its component setup. Both 2D and 3D emitters will use the same model, with the emitted effects retaining its own local structure and visuals.

This also gives particle effects a clearer authoring path. A scene can be created and adjusted once, serialized with its assets, and assigned to an emitter through normal scene data. Per-emission settings such as burst count and lifetime will continue to control how often the scene appears and how long each instance remains active, while a lightweight variation patch can support differences such as random scale, color, direction, or velocity between instances.

The transform relationship will be made explicit as part of this work. Emitters should be able to spawn scenes in world space for effects that detach from their source, or in local space for effects that should follow a parent such as smoke from an engine or sparks from a moving weapon. This avoids forcing every effect to choose between correct placement and reusable scene content.

Wima editor prototype

The Wima editor prototype already provides a working foundation for inspecting and authoring a running application. Its major features currently include:

  • Remote inspection: connect to a running Wima app and inspect live ECS captures, including worlds, scene entities, resources, schedules, archetypes, tables, and reflected component types.
  • Scene outliner: browse entities as a list or hierarchy tree, search by name or entity ID, follow parent and child relationships, and keep context while filtering large scenes.
  • Component and resource inspection: view reflected values, navigate entity references, edit supported components and resources, add or remove types, update aliases, and work with serialized values through the inspector.
  • 2D scene viewport: select entities visually, pan and zoom the view, frame the current selection, move, rotate, and scale positioned entities, and use grid, snapping, local-space, and world-space controls.
  • Scene authoring: create, clone, rename, delete, duplicate, reparent, group, and ungroup entities through validated remote commands, with multi-selection and hierarchy-aware editing.
  • Remote session safety: track connection state, capture age, command results, pending edits, transport errors, and stale sessions while keeping the authoritative Wima snapshot as the source of truth.
  • Diagnostics and offline workflows: inspect scheduler and table data, review activity and command history, undo or redo acknowledged edits, retry recoverable commands, export and import captures, and continue investigating a saved capture while disconnected.
  • Workspace tools: use keyboard navigation, a command palette, searchable inspector targets, saved filters, named layouts, and accessible controls to move between inspection workflows quickly.

We are actively working on the prototype and expanding it from a remote inspector into a complete Wima authoring environment. The next stage is to make scenes first-class editor assets that can be created, previewed, edited, saved, and reused without hand-written spawn code. This includes deeper scene and asset workflows, stronger 2D and 3D preview support, and a more direct path from an editor change to a serialized scene that can be loaded by a Wima application. The editor remains experimental while these workflows are being refined against the engine’s runtime and scene systems.

Scene patches

Scene assets are useful for storing a complete starting point, but many workflows need to change only a small part of an existing scene. Duplicating the whole scene for every variation makes updates difficult: a change to the base scene has to be copied into every duplicate, and small application-specific overrides become hard to track. A ScenePatch asset will provide a smaller, composable way to describe those changes.

A patch will target an entity, component, resource, or relationship in an existing scene and record only the part that should change. It could adjust the values of a component on one entity, replace a shared resource, add or remove scene content, or change how entities are related without rewriting the rest of the scene. Patches can then be applied to a base scene to create variants for different levels, characters, game modes, or platform-specific content while keeping the common scene data in one place.

The patch system will resolve scene entities through the scene’s instance mapping rather than relying on runtime entity identifiers. That allows the same patch to be applied whenever the scene is loaded or instantiated, even though the destination world assigns new entity handles each time. The editor will be able to use this workflow for overrides as well: an author can edit a scene instance, save the intentional differences as a patch, and keep the original scene reusable.

Asset dependency tracking

Asset dependencies are a property of the asset system itself, not only of scenes. An asset can refer to other assets directly or indirectly, creating a dependency graph that must be tracked as one connected set. For example, a material may refer to image assets, while another asset may refer to that material or to a collection of related resources. The engine needs to understand those relationships instead of treating only the first-level handles as the complete requirement.

The asset server should preserve each reference, retain shared asset identity, and avoid copying data it already manages. Dependencies that are not available in the destination can be embedded or packaged according to the asset workflow, while already-managed assets remain external and shared. The process should deduplicate repeated references, resolve indirect dependencies, and keep dependency ownership clear as assets are loaded, modified, or released.

This will make asset loading, caching, packaging, and transfer between worlds more predictable. Missing dependencies can be reported while the graph is being resolved instead of failing later when a consumer tries to use an incomplete reference. Editor and packaging tools can expose the full dependency set for any asset, while scenes, materials, models, animations, and other asset consumers can all rely on the same resolution and lifecycle rules.

Change detection for components and resources

Systems currently have to infer changes themselves by keeping previous values, adding marker components, or reprocessing every matching entity on each update. The planned change-detection work will let query iteration report which selected components changed, so systems can distinguish newly relevant data from state that is unchanged since the last observation. This should apply consistently to required and optional components and remain useful when iterating combinations of entities.

Change detection will also cover resources. A system should be able to react when shared world state changes—such as configuration, input state, asset collections, or other resource-backed data—without treating every update as a change. Using the same model for components and resources will make incremental systems easier to write and give editor, simulation, and rendering workflows a clearer way to respond to updates.

The surrounding query work will support this model by moving query filters into the core package, renaming has and without to include and exclude, and adding clearer controls for relationship traversal. Relationship visitors should be able to skip a subtree, continue with sibling branches, or stop the traversal immediately without confusing those choices with change detection itself.

Explore the Wima repository for the source and examples, and the release page for published release information. Feedback and focused bug reports are welcome as these workflows are used in more projects.