Skip to main content

Getting Started

This guide covers the basic structure and concepts you need to understand when writing OasisW scripts, whether you're using the modern ESM approach or the classic system.

What is a Script?​

A script is a piece of JavaScript code that defines behavior for an Entity in your scene. Scripts are:

  • Reusable - The same script can be attached to multiple entities
  • Configurable - Use attributes to customize behavior per entity
  • Event-driven - Respond to lifecycle events and user interactions

Basic Script Structure​

Every OasisW script follows a similar pattern, regardless of which system you use:

var MyScript = pc.createScript('myScript');

MyScript.attributes.add('speed', { type: 'number', default: 10 });

MyScript.prototype.initialize = function() {
    // Called once when the script starts
    console.log('Script initialized!');
};

MyScript.prototype.update = function(dt) {
    // Called every frame
    this.entity.rotate(0, this.speed * dt, 0);
};

Key points for classic scripts:

  • Use pc.createScript() to declare the script
  • Add attributes using the .attributes.add() method
  • Define methods on the prototype
  • File has .js extension

Core Concepts​

Script Lifecycle​

Scripts have several methods that are called automatically at different times:

  • initialize() - Called once when the script starts
  • update(dt) - Called every frame with delta time
  • postUpdate(dt) - Called after all updates complete
  • Event handlers for enable, disable, destroy

Learn more about the Script Lifecycle.

Attributes​

Attributes let you expose script properties to the editor, making scripts configurable without code changes:

var Configurable = pc.createScript('configurable');

Configurable.attributes.add('speed', { type: 'number', default: 5 });
Configurable.attributes.add('color', { type: 'rgba', default: [1, 0, 0, 1] });
Configurable.attributes.add('target', { type: 'entity' });

Learn more about Script Attributes.

Accessing the Entity​

Every script has access to the entity it's attached to via this.entity:

// Get the entity's position
const position = this.entity.getPosition();

// Find child entities
const child = this.entity.findByName('ChildName');

// Access components
const camera = this.entity.camera;
const rigidbody = this.entity.rigidbody;

Next Steps​

  • Understand Lifecycle: Read about Script Lifecycle to understand when your code runs
  • Add Interactivity: Explore Events to make scripts communicate with each other