MotorCortex-Threejs

Table of Contents

• MotorCortex-Threejs
  • Demo
• Intro / Features
  • Renderers
  • Scenes
  • Cameras
  • Lights
  • Entities
  • Mesh
  • Model
  • Object
  • Controls
• Getting Started
  • Installation
  • Importing and Loading
• Creating Incidents
  • 3D Clip
  • ObjectAnimation Effect
  • MorphAnimation Effect
  • CameraFollow Effect
  • OrbitalMotion Effect
  • AppearanceChange Effect
  • MaterialEffect
• Adding Incidents in your clip
• Contributing
• License
• Sponsored by

Demo

Check it out here

Intro / Features

Can you become a 3d video creator with threejs? Well yes, you can! Motorcortex-threejs is a threejs plugin for motorcortex. It exposes most of threejs functionality in a descriptive format. It automates most of the basic stuff (scenes, lights, cameras) and focuses on the animation. With motorcortex-threejs a 3d environment mainly consists of five distinct parts

• renderers
• scenes
• cameras
• lights
• entities

Scenes, cameras and lights are self-explanatory. Entities refer to any object added in the 3d scene model or mesh geometry. The plugin exports a Clip method to initialize a new 3D Clip and several Effects. The ObjectAnimation Effect is from where you can animate any property of an object's tranformation matrix ( location, rotation, scale ) and with the MorphAnimation Effect you can play any animation that your model supports.

In order to support most of the features and possible updates of threejs out of the box the descriptive representation of a 3d scene has 3 concepts

| threejs | motorcortex-threejs | | -------------------- | ------------------------ | | any property | is an object property | | any function call | is a value type of array | | any value assignment | is a primitive value |

*it will all make sense please continue reading :)

Renderers

For example, if we want to create a new renderer with alpha enabled and run setClearColor with a value of "#999" and set physicallyCorrectLights to true with threejs we would do:

const renderer = new THREE.WebGLRenderer({ alpha: true });
renderer.setClearColor("#999");
renderer.physicallyCorrectLights = true;

in our descriptive representation we would do:

const renderer = {
  type: "WebGLRenderer",
  parameters: [{ alpha: true }],
  settings: {
    setClearColor: ["#999"], // any function call for threejs is an array for us
    physicallyCorrectLights: true, // any value assignment for threejs is a primitive value for us
  },
};

| Property | Description | | ---------- | ---------------------------------------------- | | id | Assign an id for selecting purposes | | class | Assign a class for selecting purposes | | type | A valid renderer type | | parameters | The arguments to pass in the renderer function | | settings | Any other setting related to the renderer |

Scenes

If we want to create a new scene with a fog of color "#999" near 1 and far 100 with threejs we would do:

const scene = new THREE.Scene();
scene.fog = new THREE.Fog("#999", 1, 100);

in our descriptive representation we would do:

const scene = {
  fog: ["#999", 1, 100],
};

| Property | Description | | -------- | --------------------------------------------------------- | | id | Assign an id for selecting purposes | | class | Assign a class for selecting purposes | | fog | An array with arguments to pass in the THREE.Fog function |

Cameras

If we want to create a new PerspectiveCamera with specific position and rotation with threejs we would do:

const camera = new THREE.PerspectiveCamera(45, 800 / 600, 1, 1000);
camera.position.x = 10;
camera.position.y = 10;
camera.position.z = 10;
camera.lookAt(20, 20, 20);
camera.far = 10000;
camera.near = 1;

in our descriptive representation we would do:

const camera = {
  type: "PerspectiveCamera",
  parameters: [45, 800 / 600, 1, 1000],
  settings: {
    position: { x: 10, y: 10, z: 10 },
    lookAt: [20, 20, 20],
    far: 10000,
    near: 1,
  },
};

| Property | Description | | ---------- | -------------------------------------------- | | id | Assign an id for selecting purposes | | class | Assign a class for selecting purposes | | type | A valid camera type | | parameters | The arguments to pass in the camera function | | settings | Any other setting related to the camera |

Lights

If we want to create a new AmbientLight with threejs we would do:

const light = new THREE.AmbientLight("#cacaca");
scene.add(light);

in our descriptive representation we would do:

const light = {
  type: "AmbientLight",
  parameters: ["#cacaca"],
};

const Directional = {
  addHelper:true
  id: "DirectionalLight",
  type: "DirectionalLight",
  parameters: ["0xfff", 1],
  settings: {
    position: { x: 0, y: -2, z: 10 },
    target: "!#myObj",
  };

| Property | Description | | ---------- | ------------------------------------------- | | id | Assign an id for selecting purposes | | class | Assign a class for selecting purposes | | type | A valid light type | | parameters | The arguments to pass in the light function | | settings | Any other setting related to the light | | addHelper | Add helper object to the light |

Entities

As we mentioned, entities are any threejs mesh or model.

Mesh

If we want to create a new Box with threejs we would do:

const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial({ color: "#0f0" });
const cube = new THREE.Mesh(geometry, material);
cube.position.set(0, 0, 0);
scene.add(cube);

in our descriptive representation we would do:

const box = {
  geometry: { type: "BoxGeometry", parameters: [1, 1, 1] },
  material: {
    type: "MeshBasicMaterial",
    parameters: [{ color: "#0f0" }],
  },
  settings: { position: { set: [0, 0, 0] } },
};

| Property | Description | | ---------- | ------------------------------------------- | | id | Assign an id for selecting purposes | | class | Assign a class for selecting purposes | | type | A valid light type | | parameters | The arguments to pass in the light function | | settings | Any other setting related to the light |

Model

If we want to load a model with threejs we would do:

import { DRACOLoader } from "three/examples/jsm/loaders/DRACOLoader.js";
import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";

const loader = new GLTFLoader();
const dracoLoader = new DRACOLoader();
loader.setDRACOLoader(dracoLoader);
const url = "path/to/our/model.glb";
loader.load(url, (glb) => {
  //here we have the glb scene model
  glb.position.set(10, 10, 10);
  glb.rotation.set(0, -Math.PI / 2, 0);
  glb.scale.set(2, 2, 2);
});

in our descriptive representation we would do:

const glb = {
  id: "my-model",
  model: {
    loader: "GLTFLoader",
    file: "path/to/our/model.glb",
  },
  settings: {
    position: { x: 10, y: 10, z: 10 },
    rotation: { x: 0, y: -Math.PI / 2, z: 0 },
    scale: { x: 2, y: 2, z: 2 },
  },
  children: ["child_model_name"],
};

| Property | Description | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Assign an id for selecting purposes | | class | Assign a class for selecting purposes | | type | A valid light type | | parameters | The arguments to pass in the light function | | settings | Any other setting related to the light | | children | The name of a child object that the model has and you want to use it in an effect. This will then be available to use with the selector !#my-model.child_model_name |

Object

When you need to add a simple Object3D to your scene just to use it in any animation you can use this type of entity. This type of entity can be used as a target to any light that supports target simply by refering to its selector.

const object = {
  id: "myObj",
  object: true,
  settings: {
    position: { x: 10, y: 10, z: 10 },
  },
};

Dynamic Custom Entities (addCustomEntity)

You can dynamically add 3D primitives to a running scene using MotorCortex's addCustomEntity API. This is useful for building scenes programmatically — e.g. an AI agent creating shapes on the fly.

clip.addCustomEntity(
  {
    geometry: "BoxGeometry",
    params: [2, 2, 2],
    material: { color: "#e76f51" },
    position: [0, 1, 0],
    rotation: [0, Math.PI / 4, 0],
    scale: [1, 1, 1],
  },
  "my_box", // unique entity id
  ["shapes"], // classes
  true // hidden (starts invisible)
);

The entity is created and added to the default scene. When hidden is true, the object starts with visible: false — use an AppearanceChange incident to reveal it.

Extended entity types: In addition to standard Mesh entities, addCustomEntity supports:

• Lines: Set entityType: "Line" with geometry: "BufferGeometry" and points: [[x,y,z], [x,y,z]] for line geometry. Supports LineDashedMaterial.
• Sprites: Set entityType: "Sprite" with text: "label text" to create a billboard text label. Control size via spriteScale and color via material.color.

// Dashed line between two points
clip.addCustomEntity(
  {
    geometry: "BufferGeometry",
    points: [
      [0, 0, 0],
      [5, 0, 5],
    ],
    entityType: "Line",
    edges: false,
    material: {
      type: "LineDashedMaterial",
      color: "#ffffff",
      dashSize: 0.3,
      gapSize: 0.15,
    },
  },
  "my_line",
  ["lines"]
);

// Text label sprite
clip.addCustomEntity(
  {
    geometry: "BufferGeometry",
    entityType: "Sprite",
    text: "1.52 AU",
    spriteScale: 2,
    position: [2.5, 1, 2.5],
    edges: false,
    material: { type: "SpriteMaterial", color: "#ffffff" },
  },
  "my_label",
  ["labels"]
);

Supported geometry types: Any Three.js geometry — BoxGeometry, SphereGeometry, CylinderGeometry, ConeGeometry, PlaneGeometry, TorusGeometry, TorusKnotGeometry, RingGeometry, DodecahedronGeometry, BufferGeometry, etc.

Material shorthand: { color: "#e76f51" } defaults to MeshStandardMaterial. For other materials, specify { type: "MeshPhongMaterial", color: "#e76f51", shininess: 100 }.

Definition shape:

| Property | Type | Description | | ----------- | ------- | ---------------------------------------------------------- | | geometry | string | Three.js geometry class name (e.g. "BoxGeometry") | | params | array | Constructor arguments for the geometry | | points | array | Array of [x,y,z] for BufferGeometry line endpoints | | entityType | string | "Mesh" (default), "Line", or "Sprite" | | text | string | Label text (Sprite only) | | spriteScale | number | Scale factor for sprite labels | | material | object | { color, type?, emissive?, roughness?, metalness?, ... } | | position | [x,y,z] | World position | | rotation | [x,y,z] | Euler rotation in radians | | scale | [x,y,z] | Scale multiplier | | edges | boolean | Add wireframe edges (default true, set false to skip) |

Controls

Controls will provide interactivity with your 3D Clip and will help you on creation time. To enable controls simply type

const controls = { enable: true, enableEvents: true };

and add them to your clip. The property enableEvents will be triggered on each click inside the scene and will log the camera position and the 3d point of where you clicked if there is any intersection with any object in the scene.

Getting Started

Installation

$ npm install --save @donkeyclip/motorcortex-threejs
# OR
$ yarn add @donkeyclip/motorcortex-threejs

Importing and Loading

import { loadPlugin } from "@donkeyclip/motorcortex";
import threejsPlugin from "@donkeyclip/motorcortex-threejs";
const threejs = loadPlugin(threejsPlugin);

Creating Incidents

3D Clip

With the Clip method you describe the initial state of your 3D Scene with a javascript object. All five main parts (renderers, scenes, cameras, lights, entities) are properties of this object and of type object or collection, containing information for each part accordingly.

const clip = new threejs.Clip(
  {
    renderers: {
      type: "WebGLRenderer",
      parameters: [{ alpha: true }],
      settings: {
        setClearColor: ["#999"],
        physicallyCorrectLights: true,
      },
    },
    scenes: {
      fog: ["#999", 1, 100],
    },
    lights: {
      type: "AmbientLight",
      parameters: ["#cacaca"],
    },
    cameras: {
      id: "camera_1",
      type: "PerspectiveCamera",
      parameters: [45, 800 / 600, 1, 1000],
      settings: {
        position: { x: 10, y: 10, z: 10 },
        lookAt: [20, 20, 20],
        far: 10000,
        near: 1,
      },
    },
    entities: [
      {
        id: "box_1",
        geometry: { type: "BoxGeometry", parameters: [1, 1, 1] },
        material: {
          type: "MeshBasicMaterial",
          parameters: [{ color: "#0f0" }],
        },
        settings: { position: { set: [0, 0, 0] } },
      },
    ],
    controls: { enable: true, enableEvents: true },
  },
  {
    host: document.getElementById("clip"),
    containerParams: { width: "800px", height: "600px" },
  }
);

ObjectAnimation Effect

If you want to animate the tranformation matrix of any object (camera, scene, light or any entity) you can do it by using the ObjectAnimation Effect.

const cameraAnimation = new threejs.ObjectAnimation(
  {
    animatedAttrs: {
      position: { x: 20, y: 20, z: 20 },
      targetEntity: "!#box_1",
    },
  },
  {
    selector: "!#camera_1",
    duration: 10000,
  }
);
clip.addIncident(cameraAnimation, 0);

| Animate Attribute | Value | Description | | ----------------- | -------------------------------------------------- | ------------------------------------- | | targetEntity | "!#targetId", "!.targetClass" | A selector of the entity to lookAt | | followEntity | {entity:"!#targetId", offsetX, offsetY, offsetZ} | Entity to follow with optional offset | | position | {x, y, z} | New position of the object | | rotation | {x, y, z} | New rotation of the object | | scale | {x, y, z} | New scale of the object |

MorphAnimation Effect

If you want to play an animation that your model supports then MorphAnimation is what you are looking for.

const manWalk = new threejs.MorphAnimation(
  {
    attrs: {
      singleLoopDuration: 1000,
      animationName: "walk",
    },
    animatedAttrs: {
      time: 15000,
    },
  },
  {
    selector: "!#man_1",
    duration: 15000,
  }
);
clip.addIncident(manWalk, 0);

CameraFollow Effect

A magnetic-chase camera that tracks a target entity with configurable offset. The camera smoothly approaches the target using exponential decay — it moves fast when far and tracks precisely when close.

const chase = new threejs.CameraFollow(
  {
    animatedAttrs: {
      follow: { offsetX: 5, offsetY: 3, offsetZ: 5 },
    },
    targetSelector: "!#earth",
    lookAtTarget: true,
  },
  {
    selector: "!#camera_1",
    duration: 5000,
  }
);
clip.addIncident(chase, 0);

| Attribute | Type | Description | | -------------- | ------- | ---------------------------------------------------- | | follow | object | { offsetX, offsetY, offsetZ } — offset from target | | targetSelector | string | Entity selector to chase (e.g. "!#earth") | | lookAtTarget | boolean | When true, camera always looks at the target |

The camera uses spring-based interpolation, so consecutive CameraFollow incidents create smooth orbital paths when offsets change between segments.

OrbitalMotion Effect

Moves an entity along a circular orbit. Used for planetary systems, moons, or any circular animation. Supports parent-relative orbits (e.g. moon orbiting a planet that itself orbits the sun).

const orbit = new threejs.OrbitalMotion(
  {
    animatedAttrs: {
      orbit: {
        radius: 10,
        revolutions: 1,
        phase: 0,
        centerX: 0,
        centerZ: 0,
        parentSelector: null,
      },
    },
  },
  {
    selector: "!#earth",
    duration: 10000,
  }
);
clip.addIncident(orbit, 0);

| Attribute | Type | Description | | -------------- | ------ | --------------------------------------------------------------- | | radius | number | Orbit radius | | revolutions | number | Number of full orbits during the incident | | phase | number | Starting angle in radians | | centerX | number | Orbit center X (default 0) | | centerZ | number | Orbit center Z (default 0) | | parentSelector | string | Parent entity selector for relative orbits (e.g. "!#jupiter") |

AppearanceChange Effect

Toggles visibility of a three.js object on the timeline. Used to show/hide entities at specific points in time.

// Show entity
clip.addIncident(
  new threejs.AppearanceChange(
    { animatedAttrs: { visible: true } },
    { selector: "!#my_entity", duration: 2 }
  ),
  1000
);

// Hide entity
clip.addIncident(
  new threejs.AppearanceChange(
    { animatedAttrs: { visible: false } },
    { selector: "!#my_entity", duration: 2 }
  ),
  5000
);

The Effect sets object.visible to the target value when MC calls onProgress. Use short durations (1-2ms) for instant toggles.

MaterialEffect

Animate any material property on a three.js object. Uses the material composite attribute to pass all properties as a single object.

Supported property types:

• Numeric (opacity, roughness, metalness, emissiveIntensity) — smoothly interpolated
• Color (color, emissive, specular) — interpolated via THREE.Color.lerp
• Clipping planes (clippingPlanes) — array of [nx, ny, nz, constant]; constants are interpolated for animated cutaway effects
• Boolean (transparent, depthWrite, wireframe) — toggled when the incident is active

Color animation

clip.addIncident(
  new threejs.MaterialEffect(
    {
      animatedAttrs: { material: { color: "#2a9d8f" } },
      initialValues: { material: { color: "#e76f51" } },
    },
    { selector: "!#my_box", duration: 3000 }
  ),
  0
);

Opacity fade

clip.addIncident(
  new threejs.MaterialEffect(
    {
      animatedAttrs: { material: { opacity: 0, transparent: true } },
      initialValues: { material: { opacity: 1 } },
    },
    { selector: "!#my_sphere", duration: 2000 }
  ),
  0
);

Animated cutaway (clipping planes)

Clipping planes slice away geometry at render time — the geometry is untouched and the effect is fully reversible. Each plane is [nx, ny, nz, constant] where the normal (nx, ny, nz) defines the clip direction and constant controls how deep the cut goes. Animate the constant from outside the object (no cut) to the center (full cut).

const R = 1.2; // sphere radius

// Animate open: planes slide from outside to center
clip.addIncident(
  new threejs.MaterialEffect(
    {
      animatedAttrs: {
        material: {
          clippingPlanes: [
            [1, 0, 0, 0], // target: cut through center on X
            [0, 0, 1, 0], // target: cut through center on Z
          ],
        },
      },
      initialValues: {
        material: {
          clippingPlanes: [
            [1, 0, 0, R], // initial: outside sphere (no cut)
            [0, 0, 1, R],
          ],
        },
      },
    },
    { selector: "!#my_sphere", duration: 2000, easing: "easeInOutCubic" }
  ),
  0
);

// Animate close: reverse the constants
clip.addIncident(
  new threejs.MaterialEffect(
    {
      animatedAttrs: {
        material: {
          clippingPlanes: [
            [1, 0, 0, R],
            [0, 0, 1, R],
          ],
        },
      },
      initialValues: {
        material: {
          clippingPlanes: [
            [1, 0, 0, 0],
            [0, 0, 1, 0],
          ],
        },
      },
    },
    { selector: "!#my_sphere", duration: 2000, easing: "easeInOutCubic" }
  ),
  5000
);

This works on any geometry — spheres, boxes, models. For planet cross-sections, place concentric spheres inside and clip all of them with the same planes to reveal inner layers.

All material properties

| Property | Type | Interpolation | Description | | ----------------- | ------- | ------------- | --------------------------------- | | color | string | Color.lerp | Diffuse color | | emissive | string | Color.lerp | Emissive (glow) color | | specular | string | Color.lerp | Specular highlight color | | opacity | number | linear | 0 (transparent) to 1 (opaque) | | roughness | number | linear | 0 (glossy) to 1 (rough) | | metalness | number | linear | 0 (non-metal) to 1 (metal) | | emissiveIntensity | number | linear | Emissive light intensity | | transparent | boolean | toggle | Enable transparency | | depthWrite | boolean | toggle | Write to depth buffer | | wireframe | boolean | toggle | Render as wireframe | | clippingPlanes | array | constant lerp | Array of [nx, ny, nz, constant] |

Adding Incidents in your clip

clipName.addIncident(incidentName, startTime);

Contributing

In general, we follow the "fork-and-pull" Git workflow, so if you want to submit patches and additions you should follow the next steps:

1. Fork the repo on GitHub
2. Clone the project to your own machine
3. Commit changes to your own branch
4. Push your work back up to your fork
5. Submit a Pull request so that we can review your changes

License

MIT License

Sponsored by