Hello3D Scripts API - Usage Guide

Overview

Scripts in Hello3D allow you to add interactive behavior and animations to 3D objects. Scripts are written in JavaScript and executed at runtime.

Event-Based Script Structure

Scripts use event handlers that are triggered at specific times:

function OnLoad(context, api) {
  // Runs once when the object is first loaded
}

function OnUpdate(context, api) {
  // Runs every frame (60 times per second)
}

function OnClick(context, api, event) {
  // Runs when the user clicks on the object
}

function OnMouseEnter(context, api, event) {
  // Runs when the mouse enters the object
}

function OnMouseLeave(context, api, event) {
  // Runs when the mouse leaves the object
}

function OnMouseDown(context, api, event) {
  // Runs when the mouse button is pressed on the object
}

function OnMouseUp(context, api, event) {
  // Runs when the mouse button is released on the object
}

function OnScroll(context, api, event) {
  // Runs when the user scrolls while hovering the object
}

Context Object

The context parameter provides access to the object and runtime data:

Object Properties

• context.object - The Three.js object reference
• context.position - Object position (x, y, z)
• context.rotation - Object rotation (x, y, z in radians)
• context.scale - Object scale (x, y, z)

Time Properties

• context.time - Current time in seconds since start
• context.deltaTime - Time since last frame (seconds)

Persistent Variables

• context.variables - Object to store persistent data between frames

API Object

The api parameter provides utility functions and classes:

Math Utilities

Access via api.Math:

• api.Math.PI - Pi constant
• api.Math.sin(value) - Sine function
• api.Math.cos(value) - Cosine function
• api.Math.tan(value) - Tangent function
• api.Math.abs(value) - Absolute value
• api.Math.sqrt(value) - Square root
• api.Math.pow(base, exp) - Power function
• api.Math.min(a, b, ...) - Minimum value
• api.Math.max(a, b, ...) - Maximum value
• api.Math.random() - Random number 0-1
• api.Math.clamp(value, min, max) - Clamp value to range
• api.Math.lerp(start, end, t) - Linear interpolation
• api.Math.radToDeg(radians) - Radians to degrees
• api.Math.degToRad(degrees) - Degrees to radians

Vector3 Class

Create 3D vectors using api.Vector3:

var v = new api.Vector3(1, 2, 3);
var distance = v.distanceTo(otherVector);
var normalized = v.clone().normalize();

Time Utilities

Access via api.Time:

• api.Time.now() - Current time in seconds
• api.Time.deltaTime - Time since last frame

Helper Functions

Access helper functions via context.helpers:

Transform Helpers

• context.helpers.getWorldPosition() - Get world position as Vector3
• context.helpers.lookAt(target) - Look at object or position
• context.helpers.distanceTo(target) - Distance to object or position

Movement Helpers

• context.helpers.moveLocal(x, y, z) - Move in local space
• context.helpers.moveWorld(x, y, z) - Move in world space
• context.helpers.rotate(x, y, z) - Rotate by amount (radians)

Example Scripts

Rotate Object

function OnUpdate(context, api) {
  // Rotate around Y axis at 90 degrees per second
  context.rotation.y += api.Math.degToRad(90) * context.deltaTime;
}

Bobbing Animation

function OnUpdate(context, api) {
  // Bob up and down using sine wave
  var time = context.time;
  context.position.y = api.Math.sin(time * 2) * 0.5;
}

Scale Pulse

function OnUpdate(context, api) {
  // Pulse scale between 0.8 and 1.2
  var time = context.time;
  var scale = 1 + api.Math.sin(time * 3) * 0.2;
  context.scale.set(scale, scale, scale);
}

Look at Another Object

// Store target reference in OnLoad
function OnLoad(context, api) {
  context.variables.targetObject = scene.getObjectByName("Target");
}

function OnUpdate(context, api) {
  if (context.variables.targetObject) {
    context.helpers.lookAt(context.variables.targetObject);
  }
}

Click Interaction

function OnLoad(context, api) {
  context.variables.clicked = false;
  context.variables.baseY = context.position.y;
}

function OnClick(context, api, event) {
  context.variables.clicked = !context.variables.clicked;
}

function OnUpdate(context, api) {
  if (context.variables.clicked) {
    // Jump up when clicked
    context.position.y = context.variables.baseY + 2;
  } else {
    // Return to base position
    context.position.y = api.Math.lerp(
      context.position.y,
      context.variables.baseY,
      context.deltaTime * 5
    );
  }
}

Move Forward

function OnUpdate(context, api) {
  // Move forward in local Z direction
  context.helpers.moveLocal(0, 0, 2 * context.deltaTime);
}

Orbit Around Center

function OnUpdate(context, api) {
  var time = context.time;
  var radius = 5;
  var speed = 1;
  
  context.position.x = api.Math.cos(time * speed) * radius;
  context.position.z = api.Math.sin(time * speed) * radius;
  
  // Always look at center
  context.helpers.lookAt(new api.Vector3(0, 0, 0));
}

Color Change on Hover

function OnLoad(context, api) {
  context.variables.baseColor = context.object.material.color.clone();
}

function OnMouseEnter(context, api, event) {
  context.object.material.color.setHex(0xff0000);
}

function OnMouseLeave(context, api, event) {
  context.object.material.color.copy(context.variables.baseColor);
}

Important Notes

Frame Rate

Scripts run at approximately 60 frames per second. Use context.deltaTime to make animations frame-rate independent.

Property Modification

Direct changes to context.position, context.rotation, and context.scale are automatically applied to the object.

Script Errors

If a script has an error, it will be disabled automatically to prevent crashing the scene. Check the browser console for error messages.

Variable Persistence

Use context.variables to store data that needs to persist between frames. Regular variables declared with var will reset each frame.

Performance

Keep scripts efficient. Heavy computations in OnUpdate can impact frame rate. Use simple math operations and avoid creating new objects every frame when possible.

Legacy Mode

If you write code without event handlers, it will be treated as an OnUpdate script:

// This is treated as OnUpdate code
context.rotation.x += 0.01;

However, using the event-based structure is recommended for better organization and more control.

How to Add Scripts to Objects

Step 1: Open the Script Editor

Click the script icon in the toolbar or select "Scripts" from the menu to open the Script Editor panel.

Step 2: Create a New Script

In the Script Editor:

• Click the "+ New Script" button
• Enter a name for your script
• Click "Create" to add it to the script list

Step 3: Write Your Code

Select the script from the list and write your code in the editor area. Use the event handlers (OnLoad, OnUpdate, etc.) shown above.

Step 4: Assign Script to an Object

There are two ways to assign a script:

Method A - From the Script Editor:

• Select the script in the list
• Click the "Assign to Object" button
• Click on the object in the 3D viewport

Method B - From the Inspector:

• Select the object in the hierarchy or viewport
• In the Inspector panel, find the "Script" section
• Click the dropdown and select your script from the list

Step 5: Run the Script

Click the "Run" button in the Script Editor toolbar to start script execution. The "Stop" button halts all scripts.

Step 6: Test and Edit

Scripts update in real-time. You can edit the code while running and see changes immediately.

Example Scripts