Mattercraft

Overview

Cognitive3D integrates with Mattercraft by Zappar through a dedicated NPM package — @cognitive3d/three-mattercraft — that provides native Mattercraft behaviors with a visual properties panel, automatic session management, dynamic object tracking, and one-click scene/object export. Add a single behavior to your scene and your WebXR experience starts streaming spatial analytics to the Cognitive3D dashboard.

Requirements

• A Cognitive3D account. Your project needs an Application Key (used at runtime) and a Developer Key (used for asset uploads). Both are available under Manage Developer Key in the Cognitive3D dashboard.
• A Mattercraft project with a WebXR scene.

Step 1 — Install the Cognitive3D package

In the Mattercraft editor, open Add-ons & Dependencies in the left sidebar, click Browse, choose From NPM, and search for @cognitive3d/three-mattercraft. Press Install.

Step 2 — Add the Cognitive3D Manager behavior

Open scene.zcomp, select an object in the hierarchy, and under the Behaviors tab press the (+) button. Add the Cognitive3D behavior — this is the Manager and should exist exactly once per scene. It owns the connection to the Cognitive3D platform.

The properties panel exposes:

• Api Key — your Cognitive3D Application API key.
• Scene Id — the Scene ID generated when you upload your scene.
• Scene Name — the human-readable name of your scene.
• Scene Version — the version number of the uploaded scene.
• App Version — your app's version string (default "1.0").
• Enable Export — toggle to enable scene and dynamic object export at runtime.
• Enable Debug — verbose logging in the browser console.

You can fill in the Api Key immediately. Scene Id, Scene Name, and Scene Version come back to you after you upload your scene geometry in Step 5.

Step 3 — Mark your dynamic objects

Cognitive3D treats your scene as static geometry plus a set of dynamic objects — things that move, that users interact with, or that you want heatmap data on. Mark each one by attaching the Cognitive3DDynamicObject behavior.

Where to attach it depends on the object type. ZComponents (the lightning-bolt nodes — Mattercraft's equivalent of a Unity prefab) get the behavior inside their ZComponent definition in the Project window. Standard scene objects get it directly on the node in the scene hierarchy.

For animated sub-parts of a glb (e.g. the moving platform of a forklift), Cognitive3D doesn't track animations directly, but you can track the transform of the moving piece via an AttachmentPoint: right-click the glb, pick New → AttachmentPoint, set its Attach To to the child node name, then attach Cognitive3DDynamicObject to the AttachmentPoint.

Each dynamic object exposes four properties:

• C3D Mesh Name — must match the mesh name uploaded to the dashboard. Always set this.
• C3D Custom ID — must be unique among objects sharing the same mesh. Leave blank to auto-generate, or set your own (e.g. Box-1, Box-2, Box-3) for clarity.
• Position Threshold (default 0.1) — minimum position change before a new snapshot is sent.
• Rotation Threshold (default 0.1) — minimum rotation change before a new snapshot is sent.

Larger thresholds mean fewer snapshots — slightly better performance, slightly less precise replays. The defaults are right for most projects.

Step 4 — Export your scene and dynamic objects

Once everything is marked:

1. On the Cognitive3D Manager behavior, check Enable Export and save.
2. Start the game in Live Preview (Open In Simulator).
3. Press Shift + E to export the scene.
4. Press Shift + D to export the dynamic objects.

Mattercraft drops compressed .zip archives into your Downloads folder. Disable Enable Export and save again before you ship.

Tip: drag any of the exported .zip files onto the glTF Viewer to sanity-check your dynamic objects before uploading.

Step 5 — Upload to Cognitive3D

Go to the Cognitive3D Upload Web App and sign in with your Developer Key. Upload the scene archive, then upload each dynamic object archive.

After the upload completes, return to the Cognitive3D Manager behavior in Mattercraft and fill in the Scene Id, Scene Name, and Scene Version that the dashboard shows for your project.

Step 6 — Record sensors and custom events

Inside any Mattercraft behavior script you can pull in the Cognitive3D context and start recording game logic. Import once:

import { Cognitive3DContext } from "@cognitive3d/three-mattercraft";

Then grab the context once in your constructor() or started():

const ctx = this.contextManager.getExisting(Cognitive3DContext);

Sensors capture a named value over time — speed, rotation, temperature, battery, anything you want a time series for:

// Numeric or boolean
ctx?.recordSensor("lever.rotation", 45);
ctx?.recordSensor("door.open", true);

Custom events capture a moment — with an optional 3D position and arbitrary properties:

// "Something happened, here, with this context"
ctx?.sendEvent("StepCompleted", [0, 1, 0], { step: 1 });

A more complete behavior — recording a sensor every frame and firing an event when a player completes a step — looks like this:

import { Behaviour } from "@zappar/mattercraft";
import { Cognitive3DContext } from "@cognitive3d/three-mattercraft";

export class WarehouseTask extends Behaviour {
  private ctx?: Cognitive3DContext;

  started() {
    this.ctx = this.contextManager.getExisting(Cognitive3DContext);
  }

  update(_dt: number) {
    const lever = this.node.getChildByName("Lever");
    if (!lever) return;
    this.ctx?.recordSensor("lever.rotation", lever.rotation.y);
  }

  onStepComplete(stepIndex: number, worldPos: [number, number, number]) {
    this.ctx?.sendEvent("StepCompleted", worldPos, {
      step: stepIndex,
      taskId: "warehouse-tutorial",
    });
  }
}

Step 7 — Iterating on your project

As your experience evolves you'll add geometry and new dynamic objects. Re-export from Mattercraft, re-upload through the Upload Web App, and then bump the Scene Version on the Cognitive3D Manager behavior to match the new version number on the dashboard. Existing data stays attached to the previous version, so you can compare before-and-after sessions cleanly.

Resources

• Cognitive3D Mattercraft documentation — the canonical step-by-step setup guide.
• Mattercraft by Zappar — Mattercraft product page and editor download.
• Cognitive3D Upload Web App — upload scenes and dynamic objects.
• glTF Viewer — preview exported .zip files before you upload them.