doodle/dev-assets/guidebook/pages/DoodadScripts.md

Doodad Scripts

Doodads are programmed using JavaScript which gives them their behavior and ability to interact with the player and other doodads.

An example Doodad script looks like the following:

// The main function is called when the doodad is initialized in Play Mode
// at the start of the level.
function main() {
    // Important global variables:
    // - Self: information about the current Doodad running this script.
    // - Events: handle events raised during gameplay.
    // - Message: publish or subscribe to named messages to interact with
    //   other doodads.

    // Logs go to the game's log file (standard output on Linux/Mac).
    console.log("%s initialized!", Self.Doodad().Title);

    // If our doodad has 'solid' parts that should prohibit movement,
    // define the hitbox here. Coordinates are relative so 0,0 is the
    // top-left pixel of the doodad's sprite.
    Self.SetHitbox(0, 0, 64, 12);

    // Handle a collision when another doodad (or player) has entered
    // the space of our doodad.
    Events.OnCollide(function(e) {
        // The `e` object holds information about the event.
        console.log("Actor %s has entered our hitbox!", e.Actor.ID());

        // InHitbox is `true` if we defined a hitbox for ourselves, and
        // the colliding actor is inside of the hitbox we defined.
        if (e.InHitbox) {
            // To prohibit movement, return false from the OnCollide handler.
            // If you don't return false, the actor is allowed to keep on
            // moving through.
            return false;
        }
    });

    // OnLeave is called when an actor, who was previously colliding with
    // us, is no longer doing so.
    Events.OnLeave(function(e) {
        console.log("Actor %s has stopped colliding!", e.Actor.ID());
    })
}

JavaScript API

Global Variables

The following global variables are available to all Doodad scripts.

Self

Self holds information about the current doodad. The full surface area of the Self object is subject to change, but some useful things you can access from it include:

• Self.Doodad(): a pointer to the doodad's file data.
  • Self.Doodad().Title: get the title of the doodad file.
  • Self.Doodad().Author: the name of the author who wrote the doodad.
  • Self.Doodad().Script: the doodad's JavaScript source code. Note that modifying this won't have any effect in-game, as the script had already been loaded into the interpreter.
  • Self.Doodad().GameVersion: the version of {{ app_name }} that was used when the doodad was created.

Events

Message

Global Functions

The following useful functions are also available globally:

Timers and Intervals

Doodad scripts implement setTimeout() and setInterval() functions similar to those found in web browsers.

// Call a function after 5 seconds.
setTimeout(function() {
    console.log("I've been called!");
}, 5000);

setTimeout() and setInterval() return an ID number for the timer created. If you wish to cancel a timer before it has finished, or to stop an interval from running, you need to pass its ID number into clearTimeout() or clearInterval(), respectively.

// Start a 1-second interval
var id = setInterval(function() {
    console.log("Tick...");
}, 1000);

// Cancel it after 30 seconds.
setTimeout(function() {
    clearInterval(id);
}, 30000);

Console Logging

Doodad scripts also implement the console.log() and similar functions as found in web browser APIs. They support "printf" style variable placeholders.

console.log("Hello world!");
console.error("The answer is %d!", 42);
console.warn("Actor '%s' has collided with us!", e.Actor.ID());
console.debug("This only logs when the game is in debug mode!");

RGBA(red, green, blue, alpha uint8)

RGBA initializes a Color variable using the game's native Color type. May be useful for certain game APIs that take color values.

Example: RGBA(255, 0, 255, 255) creates an opaque magenta color.

Point(x, y int)

Returns a Point object which refers to a location in the game world. This type is required for certain game APIs.