Worlds, saving and loading

A .matterworld document contains cells, tick, grid layout, solver settings, world mapping, ordered substance-schema identity, metadata and a checksum. It does not contain GameObjects, renderer settings, lights, physics bodies or network connections. Save those separately in the application's scene/save system.

Paint, save, assign, Play

1. Import Basic Setup through Tools > Matter > Samples and open its scene.
2. Select the MatterSimManager to open the World Editor in Scene View.
3. Paint the world and choose Save As under Matter World Settings.
4. Save a .matterworld file below Assets; Unity imports a MatterWorldAsset.
5. Select the sample bootstrap. Choose Saved World and assign that asset.
6. Enter Play Mode and verify the saved cells and mapping.

Generated Basin remains Basic Setup's default. A missing or incompatible Saved World reports an error; it never silently substitutes the generated basin. See Editor tools for preview, Undo and recovery behavior.

Choose the appropriate API

Task	Entry point
Capture cells and metadata	MatterWorldPersistence.CaptureAsync
Produce portable bytes	SaveToBytesAsync
Save a native filesystem document	SaveToFileAsync
Read and validate a native file	LoadFromFileAsync
Apply an already read document	ApplyAsync
Read an imported asset	MatterWorldAsset.Deserialize
Validate bytes without an exception-based result	MatterWorldSerializer.TryDeserialize

CPU and native compute support synchronous equivalents. Prefer asynchronous capture/application in portable integrations: WebGPU cannot perform synchronous GPU readback. MatterWorldAsset.LoadInto is synchronous; for WebGPU deserialize the asset and pass the result to ApplyAsync.

Call simulation and Unity-object APIs from Unity's main thread. Await operations normally rather than using .Wait() or .Result. Serialize gameplay mutations around a load: pause automatic ticking, block competing edits/backend switches, and restore the application's prior running state in finally.

Portable byte saves

The following complete helper works with an initialized manager and delegates byte storage to the application. Call it from an awaited gameplay operation; handle cancellation, I/O and validation errors at that application's boundary.

using System;
using System.Threading;
using System.Threading.Tasks;
using MasterTech.Matter.Serialization;
using MasterTech.Matter.Simulation;

public static class MatterSaveExample
{
    public static async Task<byte[]> CaptureAsync(
        MatterSimManager simulation, CancellationToken cancellationToken)
    {
        if (simulation == null) throw new ArgumentNullException(nameof(simulation));
        bool wasRunning = simulation.SimulateAutomatically;
        simulation.SimulateAutomatically = false;
        try
        {
            return await MatterWorldPersistence.SaveToBytesAsync(
                simulation, cancellationToken: cancellationToken);
        }
        finally
        {
            if (simulation != null) simulation.SimulateAutomatically = wasRunning;
        }
    }

    public static async Task RestoreAsync(
        MatterSimManager simulation, byte[] bytes, CancellationToken cancellationToken)
    {
        if (simulation == null) throw new ArgumentNullException(nameof(simulation));
        if (bytes == null) throw new ArgumentNullException(nameof(bytes));
        MatterWorldSave world = MatterWorldSerializer.Deserialize(bytes);
        bool wasRunning = simulation.SimulateAutomatically;
        simulation.SimulateAutomatically = false;
        try
        {
            await MatterWorldPersistence.ApplyAsync(simulation, world,
                new MatterWorldLoadOptions { ValidateSubstanceSchema = true },
                cancellationToken);
        }
        finally
        {
            if (simulation != null) simulation.SimulateAutomatically = wasRunning;
        }
    }
}

The helper does not drain queued edits or stop other scripts from modifying the world. The application must coordinate those systems before calling it. Cancellation is checked around readback and application; it does not guarantee that an already submitted GPU operation or filesystem write can be interrupted.

Loading policy and failures

MatterWorldLoadOptions defaults all four policies to true:

• ReconfigureSimulation: permit allocating the saved layout when needed.
• ApplySimulationSettings: restore saved solver/cadence settings.
• ApplyWorldMapping: restore origin and cell size.
• ValidateSubstanceSchema: require the target database's ordered identity to match the saved document.

Disabling reconfiguration rejects an incompatible layout. Disabling schema validation is not a material remapper: only use it inside a deliberate migration that controls every ID. Append substances carefully and test compatibility; unchanged numeric IDs alone do not establish matching saved-schema identity.

Deserialization validates format, lengths, encoding and checksum. Capture requires an initialized manager. Application validates the target database and captures rollback state when a world is already initialized. A failed application attempts to restore that state; if rollback also fails, the exception includes both failures. Report the error and stop relying on that manager until repaired. Do not report a successful save or load until its awaited operation completes.

Native file saving uses an atomic replacement path. Browser persistence requires an application storage layer; the Showcase synchronizes its virtual filesystem to IndexedDB. See Web deployment.

Recovery and backups

The World Editor's recovery snapshots protect authoring work, not the player's save directory. Its recovery banner, source conflict handling, Retry Recovery, and preview acceptance rules are described in Recovery and file conflicts.

Keep backups of your original worlds and preserve the database's substance order. Validate saved worlds before applying them to a running simulation.