Creating Custom Contexts

Contexts are used to manage and maintain states and functionality that can be shared across different components and behaviors. Some examples of custom components include:

  • A custom material
  • The value of a score
  • The time remaining in a game experience

Creating Custom Contexts

To add a new custom context to your Mattercraft project:

Adding a Custom Context to your project

  1. Click on the Left Menu
  2. Click the + (plus) icon button to the top of the panel and click on + New Custom Context
  3. Type a name for the context then click Create
  4. The Left Menu will now have this context script file with the skeleton of a brand new context

Custom Context structure

Let’s look at the basic structure of a context:

// Import the base context class and context manager
import { Context, ContextManager } from "@zcomponent/core";

interface ConstructionProps {
    // Add any constructor props you'd like for your context here
}

/** @zcontext */
export class MyContext extends Context<ConstructionProps> {

    // You can declare variables here if you'd like

    constructor(contextManager: ContextManager, constructorProps: ConstructionProps) {
        super(contextManager, constructorProps);
    }

    // You can declare functions here if you'd like

}

The @zcontext annotation tells the Mattercraft editor that you’d like this script to appear as a context in your experience.

Contexts are JavaScript or TypeScript classes that extend the Context base class provided by Mattercraft.

See Mattercraft's full API documentation here.

Using Custom Contexts

You can use custom contexts in custom behaviors and custom components. For example, the following code shows creating a score using a custom context and then displaying it in your zcomp via a custom behavior.

ScoreContext

import { Context, ContextManager, Observable } from "@zcomponent/core";

interface ConstructionProps {
    // Add any constructor props you'd like for your context here
}

/** @zcontext */
export class ScoreContext extends Context<ConstructionProps> {

    // Create a variable called currentScore which
    // you can use in other custom scripts
    public currentScore = new Observable<number>(0);

    constructor(contextManager: ContextManager, constructorProps: ConstructionProps) {
        super(contextManager, constructorProps);
    }
}

// Create a function which can be used to get the current score
export function useCurrentScore(contextManager) {
    return contextManager.get(ScoreContext).currentScore;
}

DisplayBehavior

// Other imports...
import { ScoreContext } from "./ScoreContext";

interface ConstructionProps {
    // Add any constructor props you'd like for your behavior here
}

/**
* @zbehavior
* @zicon scoreboard
 */
export class ScoreDisplayBehavior extends Behavior<Div> {

    protected zcomponent = this.getZComponentInstance(Scene);

    constructor(contextManager: ContextManager, instance: Div, protected constructorProps: ConstructionProps) {
        super(contextManager, instance);

        // Get the score context
        const scoreContext = contextManager.get(ScoreContext);

        // Display the current store in this instance
        // (a HTML Div in this example)
        this.register(scoreContext.currentScore, score => {
            instance.element.innerHTML = score.toString();
        });

    }

    dispose() {
        // Clean up any resources
        // ...
        return super.dispose();
    }
}

// ...

Properties

Just as with custom behaviors and custom components, you can add properties to your contexts that can be controlled from the 3D editor.

For more information about controlling properties, see our dedicated Properties article.

Documenting your Contexts

To make it easy to manage your context, it’s possible to add documentation in the script comments throughout your script.

Documentation is written using the popular JSDoc syntax. You may find our Glossary of helpful terms useful here.

// Imports and construction props...

/**
* This is a JSDoc custom context description
* @zcontext
*/
export class MyContext extends Context<ConstructionProps> {

    constructor(contextManager: ContextManager, constructorProps: ConstructionProps) {
        super(contextManager, constructorProps);
    }

}
zapcode branded_zapcode i