Skip to main content

Getting Started

This guide covers the basic structure and concepts you need to understand when writing OasisW scripts.

What is a Script?​

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

  • Reusable - The same script can be attached to multiple entities
  • Configurable - Behavior can be customized per entity using attributes
  • Event-driven - Responds to lifecycle events and user interactions

Basic Script Structure​

All OasisW scripts follow 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
  • Use .attributes.add() method to add attributes
  • Define methods on the prototype
  • File has .js extension

Core Concepts​

Script Lifecycle​

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

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

Learn more about Script Lifecycle.

Attributes​

Attributes allow you to expose script properties to the editor, enabling script configuration 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.

Entity Access​

All scripts can access the connected entity through this.entity:

// Get entity 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 Script Lifecycle to understand when your code runs
  • Add Interaction: Explore Events to make scripts communicate with each other