@donkeyclip/motorcortex-threejs v3.2.1

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
• 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 two 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

*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
  },
};

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],
};

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,
  },
};

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",
  };

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] } },
};

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"],
};

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 },
  },
};

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(threejs);

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(
  {
    /* Only add this property if you want to use postprocessing functionalities */
    postProcessing: {
      bloomPass: {
        parameters: [1.5, 0.4, 0.85],
        settings: {
          threshold: 0,
          strength: 1,
          radius: 0,
        },
      },
    },
    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] }}
    },
    {
      id:"man_1",
      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 },
      }
    }
    ],
      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. The example below will animate the camera's position to 20,20,20 and will continuously looking at box_1 position. Note that for targetEntity and selector we are using the ids as they were set in the clip definition. We can also use the followEntity option to follow a specific moving object with optionally defined offset. *Important Note: When targe Entity and follow Entity are used combined you must first declare the followEntity and then the targetEntity as shown in the example bellow.

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

MorphAnimation Effect

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

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

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