Skip to content
Docs & Tutorialsbeta

Getting Started

Projects created after 1st May 2026 use the decorator-based scripting system described here. If you are unsure which system your project uses, check your package.json. If your typescript dependency is version 5, you are in the right place. Otherwise, see the Legacy Scripting Reference or follow the Migration Guide to update your project.

Mattercraft is built around a component architecture. Everything in a scene (from 3D objects to interactive behaviors) is defined by components, behaviors, and contexts that are attached to nodes in the scene graph. Understanding how to build your own is the key to unlocking the full power of Mattercraft.

Under the hood, Mattercraft runs on Three.js, giving you direct access to the world leading 3D engine for the web. Scripting is done in TypeScript, which means you get full type safety, editor autocomplete, and compile-time checks, all of which make it much easier to build and maintain complex experiences.

Mattercraft’s scripting system uses TypeScript decorators to define how your classes integrate with the editor and runtime. A class marked with @zComponent() becomes a component you can drag onto scene nodes; @zBehavior() adds reusable logic; @zContext() creates shared state. Properties decorated with @zUI() appear as editable fields in the inspector.

This decorator-driven approach keeps your code clean and co-located: the class definition is the component definition, with no separate registration files or boilerplate.

See Mattercraft’s full API documentation here.

Decorator Quick Reference

Section titled “Decorator Quick Reference”

Decorator Purpose Details
@zBehavior() Mark class as a behavior Custom Behaviors
@zComponent() Mark class as a component Custom Components
@zContext() Mark class as a context Custom Contexts
@zLoad() Register async loading with progress screen Custom Components
@zOnBeforeRender() Run code every frame (before render) Scripting 101
@zOnAfterRender() Run code every frame (after render) Scripting 101
@zOnStart() Run code when experience starts Scripting 101
@zRegister() Listen to events from the attached node Custom Behaviors
@zUI() Customize how a property appears in the editor Properties
@zObserve() React to property value changes Properties
@zIgnore() Hide a property from the editor Properties

Upgrading from Legacy Scripting

Section titled “Upgrading from Legacy Scripting”

If you have an existing project using the older JSDoc-based scripting system:

In this section

Section titled “In this section”