Troubleshooting

Benchmark capture path is too long

The launcher validates the longest planned capture path before starting. On Windows, a deeply nested project can exceed the capture-path budget even when the report root is the default Artifacts/MatterBenchmarks. Use a project closer to the drive root, or supply a shorter artifact root through the command-line harness. The failure is explicit; it does not produce a valid performance report. Preserve the failure log and retry from the shorter path.

The simulation does not initialize

  • Confirm that a SubstanceDatabase is assigned and has been validated and baked.
  • Confirm that grid dimensions are even and other layout values are valid.
  • For the compute backend, assign the included MatterSimulation.compute shader.
  • Select Auto or CPU Burst when compute shaders are unavailable.
  • Check the Unity Console for the first Matter validation message.

The simulation runs but nothing is visible

  • Assign the same initialized MatterSimManager to each MatterRenderer.
  • Verify that render modes include the phases present in the world.
  • Confirm the project uses URP and Matter shaders are assigned.
  • Confirm the substance database has a compatible baked render library.
  • Compare the scene with the imported Basic Setup sample.

Materials change after loading a world

Substance IDs are positions in the database. Use the same ordered SubstanceDatabase used when the world was saved. Append new entries rather than reordering existing entries.

Keep MatterWorldLoadOptions.ValidateSubstanceSchema enabled during normal loading. Disable it only for a deliberate migration that remaps or otherwise controls material identity.

Layout settings cannot be changed

Grid width, height, chunk size, and edit capacity are locked while a MatterSimManager is initialized. Call Shutdown(), change the layout, and call Initialize() again.

Runtime edits are ignored

TryQueueEdit returns false when an edit is invalid or the bounded queue is full. Check the return value, keep radius and coordinates inside configured limits, and tune edit capacity for the project's maximum burst.

A WebGPU read or backend switch fails

WebGPU does not support synchronous GPU readback. Use SetBackendAsync, ReadAllCellsAsync, ReadChunkAsync, ExtractCellAsync, and InjectCellAsync. Use asynchronous persistence capture before saving.

A .matterworld file does not import or load

  • Confirm the file is complete and uses a supported format version.
  • Keep the file extension .matterworld.
  • Check the Console or caught MatterWorldSerializationException for the checksum, size, payload, layout, or schema failure.
  • Confirm the target database's ordered substance schema matches the file.
  • Use MatterWorldSerializer.TryDeserialize when an application needs a non-throwing validation path.

The Scene View world editor is unavailable

  • Select a configured MatterSimManager with a valid SubstanceDatabase.
  • Selecting the manager activates the component tool in Scene View. Follow Open the World Editor if its overlays are hidden.
  • The editor initializes the backend for Edit Mode authoring automatically; no Play Mode initialization step is required.
  • In the Scene View Overlays menu, enable Matter World Paint and Matter World Settings if either panel is hidden.
  • Resolve package compilation errors before opening the tool.
  • Check Library/MatterWorldEditor when the editor offers a recovery document.

Browser build does not load

  • Serve the build through localhost or HTTPS; direct file:// loading is not supported.
  • Verify Brotli content types and Content-Encoding: br.
  • Upload the generated hidden .htaccess files when using Apache.
  • Upload matter-build-version.json after all other files.
  • Clear stale CDN objects after changing server headers.

GPU timings are missing in a benchmark

Frame timing can be unavailable in Editor batch mode on some graphics APIs. Check the benchmark's valid_gpu field. Use the Benchmark Suite's standalone player path for GPU timing, or compare paired CPU and wall-time results and confirm GPU work in a platform profiler.

Collecting a useful support report

Send the report through the Master Technologies Discord. If the issue occurs in an imported sample, reproduce it with an unchanged copy when possible.

Include:

  • Matter and Unity versions.
  • Operating system, CPU, GPU, driver, and graphics API.
  • Active simulation backend and grid dimensions.
  • A minimal reproduction or the closest imported sample.
  • The first relevant Console error and complete stack trace.
  • For benchmarks, the generated environment.json, summary.md, and failure file when present.

Quick Setup needs a target choice

When several simulations or databases exist, select the intended one explicitly. Check the active scene and the create/reuse/repair summary. Scene-changing actions are disabled during Play Mode; stop Play before using them. Repeated setup reuses compatible components, so do not create duplicate managers to bypass the choice.

A sample is missing or its import did not finish

Open Tools > Matter > Samples, select the individual sample and inspect its status. An imported copy is never overwritten automatically. Resolve compilation errors and allow Asset Database import to finish before opening its scene. Feature Showcase requires TMP Essential Resources; use the TextMeshPro import menu if automatic setup cannot find them. Basic Setup and Benchmark Suite do not require Showcase.

Basic Setup ignores my painted world

Generated Basin intentionally recreates the sample fixture on Play. Save the painting under Assets, choose Saved World on the bootstrap, and assign the resulting MatterWorldAsset. For an error, check the first Console message and the ordered substance schema. Do not disable schema validation as a workaround.

Editing one look changes another renderer

Check whether both reference the same presentation profile. Select Profile edits that shared asset. Use Duplicate and Assign before authoring a unique look. Runtime ApplySettings edits an instance copy; it does not save changes to the shared asset. ResetToProfile intentionally discards those instance changes.

New material textures or behavior do not appear

Use Bake Simulation Data for physical/thermal/reaction changes and Bake Rendering Data for surface maps and appearance. Fix inline validation issues first. Check that the renderer uses the intended database/library and that the selected tier was rebuilt after source or importer changes. Generated arrays are caches, not the authoring source. A palette-only fallback may also indicate a compute-free rendering device rather than a failed texture import.

A backend or overlay is unavailable

Read the capability explanation before changing settings. WebGL2 uses the CPU fallback, simplified presentation and a fixed Showcase grid. WebGPU requires asynchronous readback. CPU simulation on a compute-capable device can still use full presentation; disabling its presentation buffer is intended for headless workloads. See Requirements.

A benchmark was interrupted or has no report

Inspect the launcher status and the first Console error. Rendering runs that are interrupted are not successful measurements. Check the reported output directory for the failure artifact before starting again. Backend Comparison runs synchronously; it can keep the Editor occupied until completion. Retain failed runs separately and do not combine their partial samples with completed results.

Open Report Folder accepts either a summary file or a report directory. If the button is disabled for a completed run, check whether that report was moved or deleted. The displayed path identifies the original location.

Inspector links open the bundled HTML. Check that Documentation~/Html is present in the installed package. The public Docs URL requires a separate website deployment; until then use the bundled entry point. Search is verified through an HTTP-served site; browser restrictions can limit active features on file URLs.

Unity 6.6 shader diagnostics

On Unity 6000.6.2f1 with URP 17.6, a Windows player can log that Hidden/Universal Render Pipeline/DBufferClear is unsupported. The same startup message was reproduced in an empty URP control scene without Matter components. The Matter D3D11/D3D12 smoke checks still rendered correctly. A blank or pink Matter surface, or a later rendering exception, needs investigation separately; include the complete player log in a support report.

Unity's imported TMP Essential Resources can also report a deprecated enable_d3d11_debug_symbols shader directive during a build. This is a TMP resource warning, separate from Matter's C# API compatibility and simulation.