Architecture and core concepts

Matter separates simulation, presentation, and authoring so a project can use the same world data with either simulation backend, with or without rendering, and with its own persistence or networking layer.

Assembly boundaries

MasterTech.Matter.Editor (Unity Editor only)
        |                 |
        v                 v
MasterTech.Matter.Rendering.URP
        |
        v
MasterTech.Matter.Runtime

MasterTech.Matter.Runtime owns substances, simulation, world mapping, cell editing, persistence, diagnostics, and transport-neutral replication contracts. It does not depend on a renderer, an Editor assembly, or a networking library.

MasterTech.Matter.Rendering.URP depends on Runtime. It owns the visible terrain, fluid, gas, lighting, atmosphere, heatmap, and collision-proxy components, and borrows the generation-tracked presentation resources exposed by MatterSimManager.

MasterTech.Matter.Editor depends on Runtime and Rendering.URP. It owns inspectors, validation, substance-library baking, .matterworld importing, the Scene View world editor, sample helpers, and build support. Unity excludes this assembly from player builds; runtime code must not reference it.

The world model

A Matter world is a rectangular, zero-based grid. Cell (0, 0) begins at the configured world origin. Increasing x moves across the grid and increasing y moves up it. TryWorldToCell maps a world position to a valid coordinate, while CellToWorldCenter maps a coordinate back to its world-space center.

Cells are stored in row-major order. Each Cell contains a substance ID, fill amount, temperature, and compact simulation flags such as flow and burning state. A fill value of zero means that the cell is empty. Substance IDs are indexes into the assigned SubstanceDatabase, so append new substances rather than reordering a database used by saved worlds or network snapshots.

The grid is divided into square chunks. Chunks do not change the logical cell coordinates; they let simulation, rendering, persistence, and diagnostics identify which regions changed. Grid width, height, and chunk size define the allocated layout and remain locked while the simulation is initialized.

Simulation lifecycle

MatterSimManager is the main integration point. It owns the selected backend, world mapping, fixed-rate tick scheduling, runtime edit queue, persistence state, dirty chunks, and presentation resources.

When automatic simulation is enabled, the manager accumulates Unity frame time and runs zero or more fixed simulation ticks. The catch-up limit prevents one slow frame from running an unbounded number of ticks. Runtime edits queued with TryQueueEdit are applied in order at the next tick; a false return means the manager is unavailable or its per-tick queue is full.

Use backend-neutral APIs such as ReadAllCells, ReadChunk, WriteChunk, cell exchange, dirty-flag consumption, and TryQueueEdit. Do not retain or modify backend-owned buffers directly. Use asynchronous read and persistence methods when the active platform can require GPU readback.

Custom presentation code obtains a MatterPresentationResources view through TryGetPresentationResources. The view is borrowed: its buffers remain owned by the simulation. A backend switch, shutdown, or resource rebind invalidates the view and raises PresentationResourcesChanged; subscribers must reacquire the view and must never dispose its buffers.

Backends

Auto selects the compute backend when the assigned compute shader and graphics hardware are available. Otherwise it selects the Burst CPU backend. Both backends preserve the same cell format, pass order, queued-edit behavior, dirty chunks, reads and writes, persistence format, and replication-facing contracts.

The CPU backend owns persistent native arrays. It can optionally maintain a GPU presentation mirror for rendering. Disable that mirror for headless or simulation-only use. The CPU worker setting limits only Matter's scheduling; it does not change Unity's global job-worker count.

On native graphics APIs, TrySetBackend switches backend while preserving the world. WebGPU requires the asynchronous SetBackendAsync path because synchronous GPU readback is unavailable. See Web deployment for the platform-specific workflow.

If a load, applied edit, manual tick, or immediate exchange changes cells while an asynchronous switch is reading back state, the switch returns a failure and preserves the newer world. Retry after the mutation finishes. Edits that are only queued remain queued across a successful switch.

Data flow and ownership

SubstanceDatabase
        |
        v
MatterSimManager
  | cell state
  +--> gameplay
  +--> persistence
  +--> replication
  |
  | presentation buffer
  +--> MatterRenderer
  +--> TerrainMaterialField
  +--> MatterLightingField
  +--> MatterCellHeatmapRenderer

The simulation cell state is authoritative. Renderers consume presentation data and do not own the world. Persistence captures cell state and simulation settings, while networking adapters transfer state through transport-neutral contracts. Gameplay may query or edit cells through MatterSimManager without depending on a renderer.

Rendering

Matter renders through URP. A scene commonly uses separate MatterRenderer components for opaque terrain and transparent matter. TerrainMaterialField reconstructs terrain boundaries, while MatterLightingField builds the packed grid-lighting data used by the shaders.

Surface-quality presets copy values into independent controls. After applying a preset, individual settings remain editable and can be saved as a custom configuration. Render-only surface dynamics affect appearance, not the authoritative cells, collision, persistence, replication, or deterministic simulation checksums.

Customer configuration uses grouped MatterRendererSettings. A renderer can either use embedded component settings or an optional MatterPresentationProfile. Assigned profiles are copied into instance-owned runtime settings, so changing one renderer at runtime never changes the shared asset.

Persistence

.matterworld documents contain simulation cells, tick, grid layout, solver settings, world mapping, ordered substance-schema identity, metadata, payload encoding, and a document checksum. They do not contain scene GameObjects, renderers, lights, physics bodies, or networking components.

MatterWorldPersistence is the runtime entry point. Files placed under Assets are imported as typed MatterWorldAsset objects and can also be used through Addressables. See Persistence for save and load examples, or use the Editor tools to author and preview a world in Scene View.

Networking boundary

Gameplay can depend on IMatterReplicationAdapter and IMatterWorldTransferAdapter without referencing a transport. The separately distributed Matter: FishNet Integration package supplies the FishNet adapter; see FishNet integration.

For exact public members and signatures, continue with the API integration guide and API reference.