API integration guide

The API reference documents public and protected types and members in Matter's Runtime, Rendering.URP, and supported Editor surface. It combines compiled signatures with source-authored summaries, overloads, parameters, and return types. Use this guide for recommended entry points and working patterns; use the reference afterward for exact member lookup. Maintenance-only editor utilities are excluded.

API support policy

Matter's recommended integration surface is the set of facades, components, contracts, and authoring entry points described below. Other public low-level types exist for serialization, rendering, and advanced extension work, but public visibility alone does not make them the preferred gameplay layer.

When upgrading, review the package changelog and compile the project before shipping. If an integration depends directly on a low-level type, include that dependency in the project's upgrade tests.

Main entry points

Simulation

  • MatterSimManager: initialization, backend selection, tick control, backend-neutral cell and chunk access, exchange operations, world mapping, borrowed presentation resources, events, and diagnostics.
  • MatterSimulationSettings: allocated grid layout and solver configuration.
  • MatterThermalSource: target-temperature heating/cooling regions, evaluated once per simulation tick. See thermal authoring for modes, strength, falloff and scene ownership.
  • MatterPresentationResources: read-only borrowed GPU resources for custom presentation integrations. Reacquire after the manager raises PresentationResourcesChanged; never dispose borrowed buffers.
  • Cell: packed material, fill, temperature, movement, and state flags.
  • EditCommand: paint, add fill, erase, excavate, temperature, and explosion commands.
  • CellExchangeResult: bounded extraction and injection results.

See MasterTech.Matter.Runtime for compiled signatures.

Substance data

  • SubstanceDefinition: authored physical, thermal, reaction, color, rendering, and per-object-layer collision, displacement, and impact-wave properties.
  • SubstanceDatabase: stable substance ordering, validation, and baked simulation data.
  • SubstanceRenderLibrary: baked arrays and GPU render data.
  • SubstanceRenderingSettings and related settings types: texture mapping, variation, blending, transparency, and stylized lighting.

Custom renderers that call SubstanceRenderLibrary.TryBind should reuse their MaterialPropertyBlock and call ReleaseBinding(block) after they stop using it or change libraries. Each block retains its selected texture tier, so two renderers can share a library while using different quality settings. Rebinding one block changes only its own tier. MatterRenderer handles this ownership automatically; disposing a library releases every remaining binding.

Persistence and replication

  • MatterWorldPersistence: capture, serialize, save, load, and apply complete worlds.
  • MatterWorldAsset: typed .matterworld asset imported under Assets.
  • MatterWorldLoadOptions: layout, settings, mapping, and schema policy.
  • IMatterReplicationAdapter: transport-neutral edit submission and diagnostics.
  • IMatterWorldTransferAdapter: transport-neutral saved-world transfer.

Rendering

  • MatterRenderer: visible terrain, liquid, powder, solid, static, and gas presentation, including bounded render-only travelling ripples and sparse, event-localized foam.
  • MatterRendererSettings: grouped surface, fluid, lighting, phase-detail, and top-surface configuration used by CaptureSettings and ApplySettings.
  • MatterPresentationProfile: optional shared authoring asset. Each renderer copies profile values into instance-owned runtime state; runtime edits do not mutate the profile asset. ResetToProfile reapplies the assigned profile.
  • LiquidSurfaceDynamicsSettings: toggle and tune ripple strength, world-scaled wavelength, simulation-time speed, and impact/compression/curvature-gated foam without changing authoritative cells.
  • TerrainMaterialField: terrain material and contour reconstruction.
  • MatterLightingField: packed directional, ambient, grid-light, visibility, and emission data.
  • GridAtmosphereRenderer: sky and cave connectivity presentation.
  • MatterCellHeatmapRenderer: renderer-only diagnostic overlays.

See MasterTech.Matter.Rendering.URP for compiled signatures.

Editor

  • MatterDataPrebuildValidator: build-time database and asset validation.
  • MatterDependencyValidator: dependency checks for menus and automation.
  • MatterPackagePaths: package and imported-sample location resolution.
  • MatterWebBuildPipeline: WebGPU-first player configuration, build, hosting, and cache-invalidation entry points.
  • SubstanceRenderLibraryBaker: programmatic render-library baking.

See MasterTech.Matter.Editor for compiled signatures.

Simulation lifecycle

Use an assigned, validated database with this complete CPU-only example. The temporary GameObject is owned by the helper; production scene components should instead follow their scene's lifetime. Invoke from Unity's main thread. For rendering, start from Quick Setup rather than this headless example.

using System;
using MasterTech.Matter.Data;
using MasterTech.Matter.Simulation;
using UnityEngine;

public static class MatterLifecycleExample
{
    public static uint RunOneTick(SubstanceDatabase database)
    {
        if (database == null) throw new ArgumentNullException(nameof(database));
        var owner = new GameObject("Matter example");
        owner.SetActive(false);
        var simulation = owner.AddComponent<MatterSimManager>();
        try
        {
            simulation.SubstanceDatabase = database;
            simulation.RequestedBackend = SimulationBackendPreference.CpuBurst;
            simulation.CreateCpuPresentationBuffer = false;
            simulation.SimulateAutomatically = false;
            simulation.Settings.Width = 160;
            simulation.Settings.Height = 90;
            simulation.Initialize();
            simulation.SimulateTick();
            return simulation.TickIndex;
        }
        finally
        {
            simulation.Shutdown();
            if (Application.isPlaying) UnityEngine.Object.Destroy(owner);
            else UnityEngine.Object.DestroyImmediate(owner);
        }
    }
}

Width and height are even cell counts of at least two. Width, height, chunk size and edit capacity lock after initialization. Shut down before changing allocation. Tick rate must be finite and positive; pressure iterations are nonnegative; temperature diffusion is in [0, 1]. CPU workers 0 uses available workers, 1 uses the serial path, and larger values cap Matter's lanes without changing Unity's global job-worker setting.

Read and modify cells

This helper queues one in-bounds, radius-zero edit using a caller-selected valid database ID, then lets the caller inspect state asynchronously. Queued edits are applied by simulation work, not by repainting a renderer. Check the returned bool.

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

public static class MatterCellExample
{
    public static bool PaintCenter(MatterSimManager simulation, ushort materialId)
    {
        if (simulation == null) throw new ArgumentNullException(nameof(simulation));
        if (!simulation.IsInitialized)
            throw new InvalidOperationException("Initialize Matter before editing.");
        if (materialId >= simulation.SubstanceCount)
            throw new ArgumentOutOfRangeException(nameof(materialId));
        return simulation.TryQueueEdit(EditCommand.Paint(
            simulation.Settings.Width / 2, simulation.Settings.Height / 2,
            0, materialId));
    }

    public static async Task<Cell[]> ReadAsync(MatterSimManager simulation)
    {
        if (simulation == null) throw new ArgumentNullException(nameof(simulation));
        var cells = new Cell[simulation.Settings.CellCount];
        await simulation.ReadAllCellsAsync(cells);
        return cells;
    }
}

Cell arrays use row-major indexing: x + y * width. Temperature is encoded as whole degrees Celsius from 0 to 255; fill is an encoded byte, not cubic metres. LoadInitialCells replaces the complete grid and resets tick zero; LoadWorldCells restores a supplied tick. Read arrays are caller-owned.

Save and load

Use the complete portable byte-save example. It awaits capture/application, keeps schema validation enabled and restores the previous automatic-tick state in finally. Native file helpers add atomic file replacement; browser code supplies its own byte storage or synchronized virtual filesystem. World documents do not save scene objects or presentation profiles.

Compatibility rules

  • Preserve database ordering and validate saved schemas.
  • Do not retain backend-owned buffers. Reacquire borrowed presentation resources after invalidation and never dispose them.
  • Release custom render-library property-block bindings when their consumer ends.
  • Coordinate loads, edits and backend switches; asynchronous readback is not a lock on every gameplay system.
  • Use asynchronous reads and switching on WebGPU. Inspect switch results and errors instead of assuming the requested backend became active.
  • Treat Showcase controllers as optional project examples, not core facades.
  • Use the supported entry points above for production integrations.

Authored reference coverage

The supported documentation coverage list follows the entry points above, including their public configuration and result contracts. The build checks authored summaries and method parameters/results for that list. Other public types remain searchable in the complete compiled index, where generated descriptions are identified. Use the authored entry points above for supported integration workflows.