RPGcode() → {RPGcode}

new RPGcode() → {RPGcode}

The engine RPGcode API.
Returns:
RPGcode

Methods

addRunTimeProgram(filename) → {undefined}

Adds a program that will be called at run time for each game frame. You should avoid doing any lengthy operations with these programs to save freezing the browser window.
Parameters:
Name Type Description
filename type Filename of the JavaScript file stored in Programs folder.
Returns:
undefined
Example
rpgcode.addRunTimeProgram("UI/HUD.js");

addSprite(sprite, callback) → {undefined}

Dynamically adds a sprite to the current board, when the sprite has been added the callback function will be invoked, if any. Useful for spawning item pickups or enemies.
Parameters:
Name Type Description
sprite type BoardSprite object to add.
callback type If defined, the function to invoke after the sprite has been added.
Returns:
undefined
Example
var sprite = {
 "name":"skeleton.enemy",
 "id":"test3",
 "thread":"AI/PassiveEnemy.js",
 "startingPosition":{
    "x":232,
    "y":120,
    "layer":1
 },
 "events":[
    {
      "program":"AI/BumpCharacter.js",
       "type":"overlap",
       "key":""
    }
 ]
};

rpgcode.addSprite(sprite, function() {
 rpgcode.log("Sprite added to board.");
});

animateCharacter(characterId, animationId, callback)

Animates the character using the requested animation. The animationId must be available for the character.
Parameters:
Name Type Description
characterId String The label associated with the character.
animationId String The requested animation to character for the character.
callback Callback If defined, the function to invoke at the end of the animation.
Example
// Without a callback.
rpgcode.animateCharacter("Hero", "HURT_SOUTH");

// With a callback.
rpgcode.animateCharacter("Hero", "HURT_SOUTH", function(){
 rpgcode.log("Animated Hero!");
});

animateSprite(spriteId, animationId, callback)

Animates the sprite using the requested animation. The animationId must be available for the sprite.
Parameters:
Name Type Description
spriteId String The ID set for the sprite as it appears in the editor.
animationId String The requested animation to play for the sprite.
callback Callback If defined, the function to invoke at the end of the animation.
Example
var spriteId = "mysprite";
var animationId = "DANCE";
rpgcode.animateSprite(spriteId, animationId, function() {
 rpgcode.log("Finished dancing");
});

changeCharacterGraphics(characterId, swaps) → {undefined}

Changes a characters visible graphics at runtime by swapping the values stored in the left-hand slots with those on the right. These keys can be reversed to restore the previous values.
Parameters:
Name Type Description
characterId String The label associated with the character.
swaps Object An object containing the graphics to swap.
Returns:
undefined
Example
var changes = {
 "NORTH": "BOAT_NORTH",
 "SOUTH": "BOAT_SOUTH",
 "EAST": "BOAT_EAST",
 "WEST": "BOAT_WEST",
 "NORTH_EAST": "BOAT_NORTH_EAST",
 "NORTH_WEST": "BOAT_NORTH_WEST",
 "SOUTH_EAST": "BOAT_SOUTH_EAST",
 "SOUTH_WEST": "BOAT_SOUTH_WEST"
};
rpgcode.changeCharacterGraphics("Hero", changes);

// To restore the defaults all we need to do is swap them around again.
var changes = {
 "BOAT_NORTH": "NORTH",
 "BOAT_SOUTH": "SOUTH",
 "BOAT_EAST": "EAST",
 "BOAT_WEST": "WEST",
 "BOAT_NORTH_EAST": "NORTH_EAST",
 "BOAT_NORTH_WEST": "NORTH_WEST",
 "BOAT_SOUTH_EAST": "SOUTH_EAST",
 "BOAT_SOUTH_WEST": "SOUTH_WEST"
};
rpgcode.changeCharacterGraphics("Hero", changes);

clearCanvas(canvasId)

Clears an entire canvas and triggers a redraw.
Parameters:
Name Type Description
canvasId String The canvas to clear, if undefined defaults to "renderNowCanas".
Example
// Create a simple canvas and write some text on it.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.drawText(270, 300, "Hello world!", canvas);
rpgcode.renderNow(canvas);

// Clears the canvas after 5 seconds have elapsed.
rpgcode.delay(5000, function(){ 
 rpgcode.clearCanvas(canvas); 
});

clearDialog()

Clears and hides the dialog box.
Example
// Display some dialog.
rpgcode.showDialog("Hello world!");

// Clears the dialog after 5 seconds have elapsed.
rpgcode.delay(5000, function(){ 
 rpgcode.clearDialog();
});

createCanvas(width, height, canvasId)

Creates a canvas with the specified width, height, and ID. This canvas will not be drawn until renderNow is called with its ID.
Parameters:
Name Type Description
width Number In pixels.
height Number In pixels.
canvasId String The ID to be associated with the canvas.
Example
// Create a simple canvas and write some text on it.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.drawText(270, 300, "Hello world!", canvas);
rpgcode.renderNow(canvas); 

delay(ms, callback, loop) → {Object}

Delays a programs execution for a specified number of milliseconds, after which the callback function is invoked.
Parameters:
Name Type Description
ms Number Time to wait in milliseconds.
callback Callback Function to execute after the delay.
loop Boolean Should the call be indefinite?
Returns:
Object - Reference to the delay object.
Example
// Shows a dialog window after 5 seconds.
rpgcode.delay(5000, function(){ 
 rpgcode.showDialog("Hello world!");
});

destroyCanvas(canvasId)

Destroys the canvas with the specified ID removing it from the engine.
Parameters:
Name Type Description
canvasId String The ID for the canvas to destroy.
Example
// Create a simple canvas and write some text on it.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.drawText(270, 300, "Hello world!", canvas);
rpgcode.renderNow(canvas); 

// Destroys the canvas that we just created.
rpgcode.destroyCanvas(canvas);

destroySprite(spriteId)

Destroys a particular sprite instance and removes it from the engine.
Parameters:
Name Type Description
spriteId String The ID set for the sprite as it appears in the editor.
Example
rpgcode.destroySprite("evil-eye-1");

drawCircle(x, y, radius, canvasId)

Draws a circle onto the canvas.
Parameters:
Name Type Description
x Number The start x postion.
y Number The start y postion.
radius Number In pixels.
canvasId String The ID of the canvas to draw on, defaults to "renderNowCanvas" if none specified.
Example
// Create a canvas and draw a red circle on it.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.setColor(255, 0, 0, 1.0);
rpgcode.drawCircle(100, 100, 25, canvas);
rpgcode.renderNow(canvas); 

drawLine(x1, y1, x2, y2, lineWidth, canvasId)

Draws a line onto the canvas.
Parameters:
Name Type Description
x1 Number In pixels.
y1 Number In pixels.
x2 Number In pixels.
y2 Number In pixels.
lineWidth Number In pixels.
canvasId String The ID of the canvas to draw on, defaults to "renderNowCanvas" if none specified.
Example
// Create a canvas and draw a red line on it.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.setColor(255, 0, 0, 1.0);
rpgcode.drawLine(25, 25, 50, 50, 1, canvas);
rpgcode.renderNow(canvas); 

drawOntoCanvas(sourceId, x, y, width, height, targetId)

Draws the source canvas onto the target canvas.
Parameters:
Name Type Description
sourceId String The ID of the source canvas.
x Number The start position x in pixels.
y Number The start position y in pixels.
width Number In pixels.
height Number In pixels.
targetId String The ID of the target canvas.
Example
// Canvas IDs.
var buffer = "buffer";
var lifeIcon = "life_icon";

// Assets to load up.
var assets = {
 "images": [
     "life.png"
 ]
};

// Load up the assets needed for this example.
rpgcode.loadAssets(assets, function () {
 // Smaller canvas.
 rpgcode.createCanvas(32, 32, lifeIcon);

 // Canvas to draw onto.
 rpgcode.createCanvas(640, 480, buffer);

 // Set the image on the smaller canvas.
 rpgcode.setImage("life.png", 0, 0, 32, 32, lifeIcon);
 
 // Draw 3 hearts onto the buffer canvas.
 for (var i = 1; i < 4; i++) {
     rpgcode.drawOntoCanvas(lifeIcon, i * 32, 430, 32, 32, buffer);
 }
 
 // Show the larger canvas with the smaller hearts on it.
 rpgcode.renderNow(buffer);
});

drawRect(x, y, width, height, lineWidth, canvasId)

Draws a rectangle onto the canvas.
Parameters:
Name Type Description
x Number The start x postion.
y Number The start y postion.
width Number In pixels.
height Number In pixels.
lineWidth Number In pixels.
canvasId String The ID of the canvas to draw on, defaults to "renderNowCanvas" if none specified.
Example
// Create a canvas and draw a red rectangle on it.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.setColor(255, 0, 0, 1.0);
rpgcode.drawRect(0, 0, 100, 100, 1, canvas);
rpgcode.renderNow(canvas); 

drawText(x, y, text, canvasId)

Draws the text on the canvas starting at the specified (x, y) position, if no canvas is specified it defaults to the "renderNowCanvas".
Parameters:
Name Type Description
x Number The start position x in pixels.
y Number The start postion y in pixels.
text String A string of text to draw.
canvasId String The ID of the canvas to draw onto, if undefined defaults to "renderNowCanvas".
Example
// Display the text on the default canvas.
rpgcode.drawText(270, 300, "Hello world!");
rpgcode.renderNow();

// Display the text on a custom canvas.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.drawText(270, 300, "Hello world!", canvas);
rpgcode.renderNow(canvas); 

endProgram(nextProgram)

Ends the current program and releases control back to the main game loop. If nextProgram is specified the main loop will not resume. Execution will be immediately passed to the program the user specified.
Parameters:
Name Type Description
nextProgram String The relative path to the next program to execute.
Example
// End the current program and release control back to the engine.
rpgcode.endProgram();

// End the current program, then run another.
rpgcode.endProgram("MyProgram.js");

fillCircle(x, y, radius, canvasId)

Fills a solid circle onto the canvas.
Parameters:
Name Type Description
x Number The start x postion.
y Number The start y postion.
radius Number The start y postion.
canvasId String The ID of the canvas to draw on, defaults to "renderNowCanvas" if none specified.
Example
// Create a canvas and draw a red circle on it.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.setColor(255, 0, 0, 1.0);
rpgcode.fillCircle(100, 100, 25, canvas);
rpgcode.renderNow(canvas); 

fillRect(x, y, width, height, canvasId)

Fills a solid rectangle on the canvas.
Parameters:
Name Type Description
x Number The start x postion.
y Number The start y postion.
width Number In pixels.
height Number In pixels.
canvasId String The ID of the canvas to draw on, defaults to "renderNowCanvas" if none specified.
Example
// Create a canvas and draw a red rectangle on it.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.setColor(255, 0, 0, 1.0);
rpgcode.fillRect(0, 0, 100, 100, canvas);
rpgcode.renderNow(canvas); 

fireRaycast(origin, direction, maxDistance) → {Object}

Fires a ray from its origin in the direction and report entities that intersect with it, given the parameter constraints. This will return any characters, enemies, NPCs, and SOLID vectors caught in the path of the raycast enclosing them inside an object.
Parameters:
Name Type Description
origin type The point of origin from which the ray will be cast. The object must contain the properties _x and _y
direction type The direction the ray will be cast. It must be normalized. The object must contain the properties x and y.
maxDistance type The maximum distance up to which intersections will be found. This is an optional parameter defaulting to Infinity. If it's Infinity find all intersections. If it's negative find only first intersection (if there is one). If it's positive find all intersections up to that distance.
Returns:
Object - An object containing all of the entities in the path of the raycast.
Example
var hits = rpgcode.fireRaycast({
    _x: location.x,
    _y: location.y
 }, vector, 13);
 hits["characters"].forEach(function(character) {
     rpgcode.log(character);
 });
 hits["enemies"].forEach(function(sprite) {
     rpgcode.log(sprite.enemy);
 });
 hits["npcs"].forEach(function(sprite) {
     rpgcode.log(sprite.npc);
 });
 hits["solids"].forEach(function(solid) {
     rpgcode.log(solid.distance);
     rpgcode.log(solid.x);
     rpgcode.log(solid.y);
 });
 rpgcode.endProgram();

getAngleBetweenPoints(x1, y1, x2, y2) → {Number}

Gets the angle between two points in radians.
Parameters:
Name Type Description
x1 Number
y1 Number
x2 Number
y2 Number
Returns:
Number - The angle between the points in radians.
Example
// Get the angle in radians between two points.
var angle = rpgcode.getAngleBetweenPoints(location.x, location.y, this.x, this.y);

getBoard() → {String}

Gets the current board, useful for accessing certain properties e.g. name, description etc.
Returns:
String - Name of the current board.
Example
var board = rpgcode.getBoard();
rpgcode.log(board);

getBoardName() → {String}

Gets the current board's name and returns it.
Returns:
String - Name of the current board.
Example
var boardName = rpgcode.getBoardName();
rpgcode.log(boardName);

getCharacter() → {Object}

Gets the active character object.
Returns:
Object - Active character.
Example
var character = rpgcode.getCharacter();
rpgcode.log(character);

getCharacterDirection() → {String}

Gets the character's current direction. var direction = rpgcode.getCharacterDirection(); rpgcode.log(direction);
Returns:
String - A NORTH, SOUTH, EAST, or WEST value.

getCharacterLocation(inTiles, includeOffset) → {Object}

Gets the character's current location, optionally including the visual offset that happens when boards are smaller than the viewport dimensions.
Parameters:
Name Type Description
inTiles Boolean Should the location be in tiles, otherwise pixels.
includeOffset Boolean Should the location include the visual board offset.
Returns:
Object - An object containing the characters location in the form {x, y, z}.
Example
var location = rpgcode.getCharacterLocation();
rpgcode.log(location);

getDistanceBetweenPoints(x1, y1, x2, y2) → {Number}

Gets the straight line distance between two points in pixels.
Parameters:
Name Type Description
x1 Number
y1 Number
x2 Number
y2 Number
Returns:
Number - The distance in pixels.
Example
// Get the distance between two points in pixels.
var distance = rpgcode.getDistanceBetweenPoints(location.x, location.y, this.x, this.y);

getGlobal(id) → {Object}

Gets the value of global variable.
Parameters:
Name Type Description
id String The ID associated with the global variable.
Returns:
Object - Value of the requested global.
Example
var swordActive = rpgcode.getGlobal("swordActive");
rpgcode.log(swordActive);

getImage(fileName) → {Object}

Gets the image object if it has been loaded into the engine already, otherwise it returns undefined.
Parameters:
Name Type Description
fileName String The relative path to the image.
Returns:
Object - Image object or undefined if none available.
Example
// Set the image on the smaller canvas.
var image = rpgcode.getImage("life.png");
rpgcode.log(image.width);
rpgcode.log(image.height);

getPixel(x, y, canvasId)

Gets the pixel ImageData at the (x, y) coordinate on the canvas.
Parameters:
Name Type Description
x Number In pixels.
y Number In pixels.
canvasId String The ID of the canvas to draw on, defaults to "renderNowCanvas" if none specified.
Example
// Draw a rectangle on the default canvas and render it.
rpgcode.setColor(255, 0, 0, 1.0);
rpgcode.fillRect(0, 0, 100, 100);
rpgcode.renderNow();

// Get the red pixel at (50, 50) from the rectangle.
var imageData = rpgcode.getPixel(50, 50);
rpgcode.log(imageData);

getRandom(min, max) → {Number}

Gets a random number between the min and max inclusive.
Parameters:
Name Type Description
min Number Minimum value for the random number.
max Number Maximum value for the random number.
Returns:
Number - A random number in the from the requested range.
Example
var result = rpgcode.getRandom(1, 10);
rpgcode.log(result); // Will be between 1 and 10.

getRunningProgram() → {Object}

Gets the current running program as an Object.
Returns:
Object - An object with the attributes inProgram (boolean) and the filename of the current running program, if any.
Example
var program = rpgcode.getRunningProgram();
rpgcode.log(program);

getScale() → {Number}

Gets the current scale factor that the renderer has been drawn with, useful for creating responsive and scalable UIs.
Returns:
Number
Example
var scale = rpgcode.getScale();
rpgcode.log(scale);

getSprite(spriteId) → {Entity}

Gets the sprite associated with the ID set in the Board editor.
Parameters:
Name Type Description
spriteId type
Returns:
Entity
Example
var sprite = rpgcode.getSprite("MySprite");

getSpriteDirection(spriteId) → {String}

Gets the sprites's current direction. var direction = rpgcode.getSpriteDirection(); rpgcode.log(direction);
Parameters:
Name Type Description
spriteId String ID associated with the sprite.
Returns:
String - A NORTH, SOUTH, EAST, or WEST value.

getSpriteLocation(spriteId, inTiles, includeOffset) → {Object}

Gets the sprites's current location, optionally including the visual offset that happens when boards are smaller than the viewport dimensions.
Parameters:
Name Type Description
spriteId String ID associated with the sprite.
inTiles Boolean Should the location be in tiles, otherwise pixels.
includeOffset Boolean Should the location include the visual board offset.
Returns:
Object - An object containing the characters location in the form {x, y, z}.
Example
var location = rpgcode.getSpriteLocation("rat");
rpgcode.log(location);

getViewport() → {Object}

Gets the viewport object, this is useful for calculating the position of characters or sprites on the board relative to the RPGcode screen. The viewport contains the (x, y) values of the upper left corner of screen relative to a board's (x, y). It also returns the width and height of the viewport.
Returns:
Object
Example
var viewport = rpgcode.getViewport();
rpgcode.log(viewport.x);
rpgcode.log(viewport.y);
rpgcode.log(viewport.width);
rpgcode.log(viewport.height);

giveItem(filename, characterId, callback) → {undefined}

Gives an item to a character, placing it in their inventory.
Parameters:
Name Type Description
filename String
characterId String
callback Callback Invoked when the item has finished loading assets.
Returns:
undefined

hitCharacter(characterId, damage, animationId, callback)

Hits the character dealing the requested damage while playing the corresponding animation. Optionally a callback can be invoked when the hit animation has finished playing.
Parameters:
Name Type Description
characterId String ID of the character.
damage Number Amount of health to take away.
animationId String Animation to play while the character is hit.
callback Callback An optional function to invoke when the animation has ended.
Example
// Without a callback.
rpgcode.hitCharacter("Hero", 1, "DEFEND");

// With a callback.
rpgcode.hitCharacter("Hero", 1, "DEFEND", function() {
 // The animation has ended, do something.
});

hitEnemy(spriteId, damage, animationId, callback) → {undefined}

Hits the enemy dealing the requested damage while playing the corresponding animation. Optionally a callback can be invoked when the hit animation has finished playing.
Parameters:
Name Type Description
spriteId String ID of the BoardSprite that represents the enemy.
damage Number Amount of health to take away.
animationId String Animation to play while the enemy is hit.
callback Callback An optional function to invoke when the animation has ended.
Returns:
undefined
Example
// Without a callback.
rpgcode.hitEnemy("rat-1", 1, "DEFEND");

// With a callback.
rpgcode.hitEnemy("rat-1", 1, "DEFEND", function() {
 // The animation has ended, do something.
});

isAssetLoaded(asset, type) → {Boolean}

Returns a true/false value indicating whether an asset has been loaded.
Parameters:
Name Type Description
asset String Filename of the asset including any subfolders.
type String Either "image" or "audio".
Returns:
Boolean
Example
rpgcode.log(rpgcode.isAssetLoaded("Hero/attack_east.png", "image")); // logs true
rpgcode.log(rpgcode.isAssetLoaded("intro", "audio")); // logs true

isControlEnabled() → {Boolean}

Returns a true/false value indicating whether standard movement controls are currently enabled in the engine.
Returns:
Boolean

loadAssets(assets, onLoad)

Loads the requested assets into the engine, when all of the assets have been loaded the onLoad callback is invoked.
Parameters:
Name Type Description
assets Object Object of assets to load.
onLoad Callback Callback to invoke after assets are loaded.
Example
// Game assets used in this program.
var assets = {
 "audio": {
     "intro": "intro.mp3"
 },
 "images": [
     "block.png",
	"mwin_small.png",
	"sword_profile_1_small.png",
	"startscreen.png"
 ]
};

// Load up the assets we need
rpgcode.loadAssets(assets, function () {
 // Assets we need are ready, continue on...
});

loadJSON(path, successCallback, failureCallback) → {undefined}

Loads the requested JSON file data from the requested path and returns the JSON text as it appears in the file.
Parameters:
Name Type Description
path String File path to read from.
successCallback Callback Invoked if the load succeeded.
failureCallback Callback Invoked if the load failed.
Returns:
undefined
Example
rpgcode.loadJSON(
     "Boards/start.board", 
     function(response) {
         // Success callback.
         console.log(response);
     }, 
     function(response) {
         // Failure callback.
         console.log(response);
     }
 );

log(message)

Log a message to the console.
Parameters:
Name Type Description
message String Message to log.
Example
rpgcode.log("Hello world!");

measureText(text) → {Object}

Measures text as it would appear on a canvas using the current font, returning the width and height of the text in pixels.
Parameters:
Name Type Description
text String
Returns:
Object - An object containing the width and height of the text.
Example
var dimensions = rpgcode.measureText("Hello world");
rpgcode.log(dimensions.width);
rpgcode.log(dimensions.height);

moveCharacter(characterId, direction, distance)

Moves the character by n pixels in the given direction.
Parameters:
Name Type Description
characterId String The id of the character to move. (unused)
direction String The direction to push the character in.
distance Number Number of pixels to move.
Example
// Move the character with the "Hero" ID north 50 pixels.
rpgcode.moveCharacter("Hero", "NORTH", 50);

moveCharacterTo(characterId, x, y, duration, callback)

Moves the character to the (x, y) position, the character will travel for the supplied duration (milliseconds). A short duration will result in the character arriving quicker and vice versa.
Parameters:
Name Type Description
characterId String The name set for the character as it appears in the editor.
x Number A pixel coordinate.
y Number A pixel coordinate.
duration Number Time taken for the movement to complete (milliseconds).
callback Callback Function to invoke when the sprite has finished moving.
Example
// Move towards (100, 150) for 50 milliseconds, this will animate the character.
var characterId = "hero";
var x = 100;
var y = 150;
var delay = 50;
rpgcode.moveCharacterTo(characterId, x, y, delay);

moveSprite(spriteId, direction, distance)

Moves the sprite by the requested number of pixels in the given direction.
Parameters:
Name Type Description
spriteId String The ID set for the sprite as it appears in the editor.
direction String The direction to push the sprite in e.g. NORTH, SOUTH, EAST, WEST.
distance Number Number of pixels to move.
Example
// Move the sprite with id "mysprite" in the north direction by 50 pixels.
var spriteId = "mysprite";
var direction = "NORTH";
var distancePx = 50;
rpgcode.moveSprite(spriteId, direction, distancePx);

moveSpriteTo(spriteId, x, y, duration, callback)

Moves the sprite to the (x, y) position, the sprite will travel for the supplied duration (milliseconds). A short duration will result in the sprite arriving quicker and vice versa.
Parameters:
Name Type Description
spriteId String The ID set for the sprite as it appears in the editor.
x Number A pixel coordinate.
y Number A pixel coordinate.
duration Number Time taken for the movement to complete (milliseconds).
callback Callback Function to invoke when the sprite has finished moving.
Example
// Move towards (100, 150) for 50 milliseconds, this will animate the sprite.
var spriteId = "mysprite";
var x = 100;
var y = 150;
var delay = 50;
rpgcode.moveSpriteTo(spriteId, x, y, delay);

playSound(file, loop, volume) → {Object}

Plays the supplied sound file, up to five sound channels can be active at once.
Parameters:
Name Type Description
file String Relative path to the sound file to play.
loop Boolean Should it loop indefinitely?
volume Number (Optional) Value ranging from 1.0 to 0.0, default is 1.0 (i.e. 100%).
Returns:
Object - A HTML5 audio element representing the playing sound.
Example
// Game assets used in this program.
var assets = {
 "audio": {
     "intro": "intro.mp3"
 }
};

// Load up the assets we need
rpgcode.loadAssets(assets, function () {
 // The sound file is loaded play it in an infinite loop.
 rpgcode.playSound("intro", true);
}); 

registerKeyDown(key, callback, globalScope)

Registers a keyDown listener for a specific key, for a list of valid key values see: http://craftyjs.com/api/Crafty-keys.html The callback function will continue to be invoked for every keyDown event until it is unregistered.
Parameters:
Name Type Description
key String The key to listen to.
callback Callback The callback function to invoke when the keyDown event fires.
globalScope Boolean Is this for use outside of the program itself?
Example
rpgcode.registerKeyDown("ENTER", function() {
 rpgcode.log("Enter key is down!");
});

registerKeyUp(key, callback, globalScope)

Registers a keyUp listener for a specific key, for a list of valid key values see: http://craftyjs.com/api/Crafty-keys.html The callback function will continue to be invoked for every keyUp event until it is unregistered.
Parameters:
Name Type Description
key String The key to listen to.
callback Callback The callback function to invoke when the keyUp event fires.
globalScope Boolean Is this for use outside of the program itself?
Example
rpgcode.registerKeyUp("ENTER", function() {
 rpgcode.log("Enter key is up!");
});

registerMouseClick(callback, globalScope) → {undefined}

Registers a mouse move event callback, when the mouse is moved the supplied callback function will be called and provided with the current mouse state. The callback function will continue to be invoked for every mouse move event until it is unregistered.
Parameters:
Name Type Description
callback Callback The callback function to invoke when the event fires.
globalScope Boolean Is this for use outside of the program itself?
Returns:
undefined
Example
rpgcode.registerMouseClick(function(e) {
 // Log the x and y coordinates of the mouse.
 rpgcode.log(e.realX);
 rpgcode.log(e.realY);
 
 // Log the mouse button that has been clicked.
 rpgcode.log(e.mouseButton); // LEFT: 0, MIDDLE: 1, RIGHT: 2
});

registerMouseDoubleClick(callback, globalScope) → {undefined}

Registers a mouse move event callback, when the mouse is moved the supplied callback function will be called and provided with the current mouse state. The callback function will continue to be invoked for every mouse move event until it is unregistered.
Parameters:
Name Type Description
callback Callback The callback function to invoke when the event fires.
globalScope Boolean Is this for use outside of the program itself?
Returns:
undefined
Example
rpgcode.registerMouseDoubleClick(function(e) {
 // Log the x and y coordinates of the mouse.
 rpgcode.log(e.realX);
 rpgcode.log(e.realY);
 
 // Log the mouse button that has been double clicked.
 rpgcode.log(e.mouseButton); // LEFT: 0, MIDDLE: 1, RIGHT: 2
});

registerMouseDown(callback, globalScope) → {undefined}

Registers a mouse down event callback, when the mouse is pressed down the supplied callback function will be called and provided with the current mouse state. The callback function will continue to be invoked for every mouse move event until it is unregistered.
Parameters:
Name Type Description
callback Callback The callback function to invoke when the event fires.
globalScope Boolean Is this for use outside of the program itself?
Returns:
undefined
Example
rpgcode.registerMouseDown(function(e) {
 // Log the x and y coordinates of the mouse.
 rpgcode.log(e.realX);
 rpgcode.log(e.realY);
 
 // Log the mouse button that has been pressed down.
 rpgcode.log(e.mouseButton); // LEFT: 0, MIDDLE: 1, RIGHT: 2
});

registerMouseMove(callback, globalScope) → {undefined}

Registers a mouse move event callback, when the mouse is moved the supplied callback function will be called and provided with the current mouse state. The callback function will continue to be invoked for every mouse move event until it is unregistered.
Parameters:
Name Type Description
callback Callback The callback function to invoke when the event fires.
globalScope Boolean Is this for use outside of the program itself?
Returns:
undefined
Example
rpgcode.registerMouseMove(function(e) {
 // Log the x and y coordinates of the mouse.
 rpgcode.log(e.realX);
 rpgcode.log(e.realY);
});

registerMouseUp(callback, globalScope) → {undefined}

Registers a mouse move event callback, when the mouse is moved the supplied callback function will be called and provided with the current mouse state. The callback function will continue to be invoked for every mouse move event until it is unregistered.
Parameters:
Name Type Description
callback Callback The callback function to invoke when the event fires.
globalScope Boolean Is this for use outside of the program itself?
Returns:
undefined
Example
rpgcode.registerMouseUp(function(e) {
 // Log the x and y coordinates of the mouse.
 rpgcode.log(e.realX);
 rpgcode.log(e.realY);
 
 // Log the mouse button that has been released.
 rpgcode.log(e.mouseButton); // LEFT: 0, MIDDLE: 1, RIGHT: 2
});

removeAssets(assets)

Removes assets from the engine and frees up the memory allocated to them.
Parameters:
Name Type Description
assets Object The object containing the assets identifiers.
Example
// Game assets to unload from the engine.
var assets = {
 "audio": {
     "intro": "intro.mp3"
 }
};

rpgcode.removeAssets(assets); 

removeGlobal(id) → {undefined}

Removes a globally scoped variable from the engine.
Parameters:
Name Type Description
id String
Returns:
undefined

removeRunTimeProgram(filename) → {undefined}

Removes a run time program from the engine, if the program is currently executing it will be allowed to finish first.
Parameters:
Name Type Description
filename type
Returns:
undefined
Example
rpgcode.removeRunTimeProgram("UI/HUD.js");

removeTile(tileX, tileY, layer)

Removes the specified tile from the board.
Parameters:
Name Type Description
tileX Number The x position in tiles.
tileY Number The y postion in tiles.
layer Number The layer the tile is on.
Example
// Removes the tile at (x: 11, y: 9, z: 1).
rpgcode.removeTile(11, 9, 1); 

renderNow(canvasId)

Renders the specified canvas, if none then the "renderNowCanvas" is shown.
Parameters:
Name Type Description
canvasId String The ID of the canvas to render.
Example
// Draw a rectangle on the default canvas and render it.
rpgcode.setColor(255, 0, 0, 1.0);
rpgcode.fillRect(0, 0, 100, 100);
rpgcode.renderNow();

// Create a canvas and draw a red rectangle on it.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.setColor(255, 0, 0, 1.0);
rpgcode.fillRect(0, 0, 100, 100, canvas);
rpgcode.renderNow(canvas);  

replaceTile(tileX, tileY, layer, tileSet, tileIndex)

Replaces a tile at the supplied (x, y, z) position.
Parameters:
Name Type Description
tileX Number The x position in tiles.
tileY Number The y postion in tiles.
layer Number The layer the tile is on.
tileSet String The name of the TileSet of the replacement tile.
tileIndex Number The index of the tile in the replacement set.
Example
// Places the tile at (x: 11, y: 10, z: 0) with the 81st tile 
// from the tileset "tileset1.tileset".
rpgcode.replaceTile(11, 10, 0, "tileset1.tileset", 81);

resetActivationChecks(characterId) → {undefined}

Resets activation checks for the requested character, useful for cases where you want continually check a program activation.
Parameters:
Name Type Description
characterId type The identifier associated with the character.
Returns:
undefined
Example
// An example of a pushable block that can only be moved when the character is
// facing EAST. This program would be attached to an NPCs EventProgram.
var direction = rpgcode.getCharacterDirection();
if (!rpgcode.getGlobal("dungeonState").room2.doorOpened && direction === "EAST") {
 var id = "pushable-rock";
 var movementTime = 500;
 var animationId = "SOUTH";

 var loc = rpgcode.getSpriteLocation("pushable-rock");
 loc.x += 16;

 rpgcode.moveSpriteTo("pushable-rock", loc.x, loc.y, movementTime, function() { 
     rpgcode.playSound("door");
     rpgcode.destroySprite("closed_door");
     rpgcode.getGlobal("dungeonState").room2.doorOpened=true;
     rpgcode.endProgram();
 });
} else {
 if (!rpgcode.getGlobal("dungeonState").room2.doorOpened) {
     rpgcode.resetActivationChecks("Hero");
 }
 rpgcode.endProgram();
}

restart()

Restarts the game by refreshing the browser page.
Example
rpgcode.restart(); // Will refresh the browser page.

runProgram(filename)

Runs the requested program, movement is disabled for the programs duration.
Parameters:
Name Type Description
filename String
Example
rpgcode.runProgram("MyProgram.js");

saveJSON(data, successCallback, failureCallback) → {undefined}

Saves the requested JSON data to the file specified, if the file does not exist it is created. If the file does exist it is overwritten.
Parameters:
Name Type Description
data Object JSON object containing path and data properties.
successCallback Callback Invoked if the file save succeeded.
failureCallback Callback Invoked if the file save failed.
Returns:
undefined
Example
rpgcode.saveJSON(
 {
     path: "Boards/start2.board", // Subdirectory and file to save.
     data: {"Test": "Hello world!"} // JSON data to store.
 },
 function(response) {
    // Success callback.
    console.log(success);
    rpgcode.endProgram();
 }, 
 function(response) {
    // Failure callback.
    console.log(response);
    rpgcode.endProgram();
 }
);

sendToBoard(boardName, tileX, tileY, layer)

Sends the character to a board and places them at the given (x, y) position in tiles.
Parameters:
Name Type Description
boardName String The board to send the character to.
tileX Number The x position to place the character at, in tiles.
tileY Number The y position to place the character at, in tiles.
layer Number The layer to place the character on.
Example
rpgcode.sendToBoard("Room1.board", 11.5, 18);

setCanvasPosition(x, y, canvasId) → {undefined}

Sets the position of a canvas relative to its parent.
Parameters:
Name Type Description
x type
y type
canvasId type
Returns:
undefined
Example
// Create a canvas and draw a red rectangle on it.
var canvas = "myCanvas";
rpgcode.createCanvas(640, 480, canvas);
rpgcode.setColor(255, 0, 0, 1.0);
rpgcode.fillRect(0, 0, 100, 100, canvas);
rpgcode.renderNow(canvas);

// Now move it to a new position relative to its parent.
rpgcode.setCanvasPosition(100, 100, canvas);

setCharacterLocation(characterId, x, y, layer, isTiles)

Sets the character's location without triggering any animation.
Parameters:
Name Type Description
characterId String The identifier associated with character to move.
x Number In pixels by default.
y Number In pixels by default.
layer Number Target layer to put the character on.
isTiles Boolean Is (x, y) in tile coordinates, defaults to pixels.
Example
var characterId = "Hero";
var x = 10;
var y = 10;
var layer = 1;
var isTiles = true;
rpgcode.setCharacterLocation(characterId, x, y, layer, isTiles);

setCharacterSpeed(characterId, change)

Sets the character speed by proportionally applying the change, can be used to increase or decrease the character speed by some factor i.e. 3 times faster or 3 times slower. Positive change values are interpreted as an increase and negative values as a decrease.
Parameters:
Name Type Description
characterId String The index of the character on the board.
change String Factor to change the character speed by.
Example
// Increase the character's movement speed by 3 times.
rpgcode.setCharacterSpeed("Hero", 3);

// Decrease the character's movement speed by 3 times, returning it to normal.
rpgcode.setCharacterSpeed("Hero", -3);

setCharacterStance(characterId, stanceId)

Sets the character's current stance, uses the first frame in the animation.
Parameters:
Name Type Description
characterId String The index of the character on the board.
stanceId String The stanceId (animationId) to use.
Example
// Set the sprite with ID 5 to its idle stance.
var characterId = "Hero";
var stanceId = "IDLE";
rpgcode.setCharacterStance(characterId, stanceId); 

setColor(r, g, b, a)

Sets the RGBA color for all drawing operations to use.
Parameters:
Name Type Description
r number
g number
b number
a number
Example
// Set the color to red.
rpgcode.setColor(255, 0, 0, 1.0);

setDialogDimensions(profileDimensions, dialogDimensions)

Sets the dialog box's profile and text area dimensions.
Parameters:
Name Type Description
profileDimensions Object Dimensions object containing a width and height.
dialogDimensions Object Dimensions object containing a width and height.
Example
// Set the profile picture to use and the background dialog image.
var profileDimensions = {width: 100, height: 100};
var dialogDimensions = {width: 640, height: 480};
rpgcode.setDialogDimensions(profileDimensions, dialogDimensions);

setDialogGraphics(profileImage, backgroundImage)

Sets the dialog box's speaker profile image and the background image.
Parameters:
Name Type Description
profileImage String The relative path to the profile image.
backgroundImage String The relative path to the background image.
Example
// Set the profile picture to use and the background dialog image.
rpgcode.setDialogGraphics("sword_profile_1_small.png", "mwin_small.png");

setDialogPadding(padding) → {undefined}

Sets the padding from the top left corner of the dialog window for the x and/or y values. This can be used to prevent text from overlapping the start or end of the dialog window graphics. The default padding value is 5px for both x and y.
Parameters:
Name Type Description
padding Object An object containing x and/or y padding values in pixels.
Returns:
undefined
Example
// Set just the x padding value.
rpgcode.setDialogPadding({x: 10});

// Set just the y padding value.
rpgcode.setDialogPadding({y: 10});

// Set both.
rpgcode.setDialogPadding({x: 10, y: 10});

setDialogPosition(position) → {undefined}

Sets the position of the dialog window for the next call to showDialog. The dialog window can either appear at the top of the screen i.e. "NORTH", or the bottom of the screen i.e. "SOUTH". The default position is "SOUTH".
Parameters:
Name Type Description
position String Either NORTH (top of screen) or SOUTH (bottom of screen).
Returns:
undefined
Example
rpgcode.setDialogPosition(rpgcode.dialogPosition.NORTH);
rpgcode.showDialog("Hello north!");

rpgcode.delay(5000, function() {
 rpgcode.clearDialog();
 rpcode.setDialogPosition(rpgcode.dialogPosition.SOUTH);
 rpgcode.showDialog("Hello south!");
});

setGlobal(id, value)

Sets a global value in the engine, if it doesn't exist it is created.
Parameters:
Name Type Description
id String The ID to use for this global.
value Object The value this global holds.
Example
// Store a simple boolean.
rpgcode.setGlobal("swordactive", false);

// Store a string.
rpgcode.setGlobal("name", "Bob");

// Store an object.
rpgcode.setGlobal("shield", {def: 10, price: 100}); 
  

setGlobalAlpha(alpha) → {undefined}

Sets the global drawing alpha for all subsequent canvas drawing operation. Useful for drawing transparent elements to a canvas. For more details see: https://www.w3schools.com/Tags/canvas_globalalpha.asp
Parameters:
Name Type Description
alpha type
Returns:
undefined

setImage(fileName, x, y, width, height, canvasId)

Sets an image on the canvas specified or the default if none.
Parameters:
Name Type Description
fileName String The relative path to the image.
x Number The start position x in pixels.
y Number The start position y in pixels.
width Number In pixels.
height Number In pixels.
canvasId String The ID of the canvas to put the image on.
Example
// Set the image on the smaller canvas.
rpgcode.setImage("life.png", 0, 0, 32, 32, lifeIcon);

setPixel(x, y, canvasId)

Sets the pixel ImageData at the (x, y) coordinate on the canvas.
Parameters:
Name Type Description
x Number In pixels.
y Number In pixels.
canvasId String The ID of the canvas to draw on, defaults to "renderNowCanvas" if none specified.
Example
// Draw a rectangle on the default canvas and render it.
rpgcode.setColor(255, 0, 0, 1.0);
rpgcode.fillRect(0, 0, 100, 100);
rpgcode.renderNow();

// Set a pixel to green at (50, 50) from the rectangle.
rpgcode.setColor(0, 255, 0, 1.0);
rpgcode.setPixel(50, 50);

setSpriteLocation(spriteId, x, y, layer, inTiles)

Sets the location of the sprite.
Parameters:
Name Type Description
spriteId String The ID set for the sprite as it appears in the editor.
x Number In pixels by default.
y Number In pixels by default.
layer Number Target layer to put the sprite on.
inTiles Boolean Is (x, y) in tile coordinates, defaults to pixels.
Example
// Place a sprite at the tile coordinates (10, 10, 1).
var spriteId = "mysprite";
var x = 10;
var y = 10;
var layer = 1;
var inTiles = true;
rpgcode.setSpriteLocation(spriteId, x, y, layer, inTiles);

setSpriteStance(spriteId, stanceId)

Sets the sprite's current stance, uses the first frame in the animation.
Parameters:
Name Type Description
spriteId String The ID set for the sprite as it appears in the editor.
stanceId String The stanceId (animationId) to use.
Example
// Set the sprite with ID "mysprite" to its idle stance.
var spriteId = "mysprite";
var stanceId = "IDLE";
rpgcode.setSpriteStance(spriteId, stanceId);

showDialog(dialog)

Shows the dialog window and adds the dialog to it if it is already visible the dialog is just appended to the current window. Note the dialog window is drawn on the default "renderNowCanvas".
Parameters:
Name Type Description
dialog String The dialog to output.
Example
rpgcode.showDialog("Pssst, Over here");

stopSound(file)

Stop playing a specific sound file, if no file is set stop all sounds.
Parameters:
Name Type Description
file String The relative path of the sound file to stop.
Example
rpgcode.stopSound("intro");

takeItem(filename, characterId) → {undefined}

Takes the item from the specified character's inventory.
Parameters:
Name Type Description
filename String The filename of the item.
characterId String The character to remove it from.
Returns:
undefined

unregisterKeyDown(key, globalScope)

Removes a previously registered KeyDown listener.
Parameters:
Name Type Description
key String The key associated with the listener.
globalScope Boolean Is this a global scope key down handler.
Example
rpgcode.unregisterKeyDown("ENTER");

unregisterKeyUp(key, globalScope)

Removes a previously registered KeyUp listener.
Parameters:
Name Type Description
key String The key associated with the listener.
globalScope Boolean Is this a global scope key up handler.
Example
rpgcode.unregisterKeyUp("ENTER");

unregisterMouseClick(globalScope) → {undefined}

Removes a previously registered mouse click handler.
Parameters:
Name Type Description
globalScope Boolean Is this a global scope mouse handler.
Returns:
undefined
Example
// Removes the mouse click handler local to this program.
rpgcode.unregisterMouseClick();

// Removes the global engine mouse click handler.
rpgcode.unregisterMouseClick(true);

unregisterMouseDoubleClick(globalScope) → {undefined}

Removes a previously registered mouse double click handler.
Parameters:
Name Type Description
globalScope Boolean Is this a global scope mouse handler.
Returns:
undefined
Example
// Removes the mouse double click handler local to this program.
rpgcode.unregisterMouseDoubleClick();

// Removes the global engine mouse double click handler.
rpgcode.unregisterMouseDoubleClick(true);

unregisterMouseDown(globalScope) → {undefined}

Removes a previously registered mouse down handler.
Parameters:
Name Type Description
globalScope Boolean Is this a global scope mouse handler.
Returns:
undefined
Example
// Removes the mouse down handler local to this program.
rpgcode.unregisterMouseDown();

// Removes the global engine mouse down handler.
rpgcode.unregisterMouseDown(true);

unregisterMouseMove(globalScope) → {undefined}

Removes a previously registered mouse move handler.
Parameters:
Name Type Description
globalScope Boolean Is this a global scope mouse handler.
Returns:
undefined
Example
// Removes the mouse move handler local to this program.
rpgcode.unregisterMouseMove();

// Removes the global engine mouse move handler.
rpgcode.unregisterMouseMove(true);

unregisterMouseUp(globalScope) → {undefined}

Removes a previously registered mouse up handler.
Parameters:
Name Type Description
globalScope Boolean Is this a global scope mouse handler.
Returns:
undefined
Example
// Removes the mouse up handler local to this program.
rpgcode.unregisterMouseUp();

// Removes the global engine mouse move handler.
rpgcode.unregisterMouseUp(true);