Lagacode SDK

7/31/2019 Lagacode SDK

1/23

Lagacode SDK v0.1.6 http://lagacode.com August 2012

Copyright 2012 Lagacode. All Rights Reserved Page 1

Lagacode SDK

Introduction .................................................................................................................................................. 1

The Lagacode Game Object Model ............................................................................................................... 2

Lagacode Package Structure ......................................................................................................................... 5

Playlist ........................................................................................................................................................... 6

Level .............................................................................................................................................................. 7

Item ............................................................................................................................................................. 11

Sprite ........................................................................................................................................................... 18

Event Handlers ............................................................................................................................................ 19

Event Handler Javascript Definitions .......................................................................................................... 19

Mouse/Touch Events .................................................................................................................................. 21

Keyboard Events ......................................................................................................................................... 22

Images ......................................................................................................................................................... 23

Sounds ......................................................................................................................................................... 23

Strings ......................................................................................................................................................... 23

IntroductionLagacode is a Javascript/JSON-powered game engine that enables rapid game development, iteration

and distribution. Lagacode games are simultaneously available on HTML5-capable web browsers as well

as mobile1

(Android, iOS, Windows). This document explains the Lagacode game model, how game

levels are constructed and the underlying API that powers Lagacode games.

1An Android prototype is currently available and iOS & Windows versions are currently in the design phase.


2/23



The Lagacode Game Object ModelLagacode is a 2D casual game engine. It is designed to enable the rapid development and iteration of

puzzlers and platformers. To take advantage of the power of the game engine, game developers must

fit their games into the Lagacode Game Object Model.

In a nutshell, games consist of one or more Playlists. Playlists consist of one or more Levels.Players play levels in the order defined by the playlist. Levels consist of Items placed inside a 2D

world. Items encapsulate both physics as well as display.

Playlists, levels and items all are defined via JSON. Items can also be added programmatically to levels

and items also can be defined independently of specific levels to foster reuse. Assets like images,

sounds and strings are all defined independent of specific levels.

JSON-based inheritance model

Both levels and items support a type of JSON inheritance. As documented below, if the JSON for a level

or item points to a parent level/item, then that objects properties are loaded when the object is

created. Only single inheritance is supported. Inheritance is supported up to 20 levels deep. In practical

terms, one must balance depth of inheritance with game performance and we dont recommend testing

the limits.

Playlist

Level Level

Playlist

Level Level Level Level

ItemsEvent

HandlerCode

Images Sounds Strings

next


3/23



The goal for level/item inheritance is to enable easy code reuse. Imagine developing a game where the

background of each level is similar or a game that uses bouncing balls with the same characteristics

(event handling, size, etc) but you want to make them different colors.

More immediately, the JSON for a level definition supports defining a list of items to be placed in the

level before gameplay begins. If the items are defined separately from the games levels, all that isneeded to place them in a level is a parent name and an x,y coordinate pair.

Event Handlers

Most Javascript code for Lagacode games should be implemented in the form of event handlers. Levels

and Items have a set of events associated with their lifecycle (level start, level end, item hit, etc.). Event

handler methods for mouse/touch events as well as key events are also provided. Game developers can

also define their own event interfaces and raise events on item or level event busses. Please see the

documentation below for how to declare event handlers as well as the specific level, item, touch and

key events raised.

A Note About Physics

Lagacode uses aJava implementationof theBox2d physics engine. Much of the documentation below

deals with creating levels and placing items in the levels. We have tried to hew as closely as practical to

the Box2D API to reduce the learning curve. In the documentation below, we refer often to the Box2D

manual (copyright Erin Catto) available athttp://box2d.org. We encourage readers to check out the

Box2D web site and also the numerous excellent tutorials available on the web. Most of the Box2D

details are hidden from Lagacode developers but an understanding of how the 2D physics package

works will prove useful.

The Level Life Cycle

On the next page, the game play life cycle of a level is illustrated. In words, a level is created and all the

items declared for the level are added to it. Then Start events are fired. Next a loop is entered to handle

events, simulate object physics and render the objects to the screen. Within the loop, collision (Hit)

events are fired as needed, key and touch events are fired. Further, when more the 1/60th

of a second

has elapsed, a Tick event is fired first to items and then to the level. If rendering takes more than 1/60th

of a second, multiple Ticks may be recorded in succession. A Tick consists of calling the physics engine

to update body positions, recording any collisions and firing the Tick event for both items and the level.

The physics loop is enclosed within a render loop. In this manner, more powerful clients can achieve

frame rates of more than 60fps. Realistically, since most event handling is restricted to 60 Ticks/second,

higher frame rates will not produce smoother rendering. The goal of a constant frame rate was to

simplify time calculations within event handlers, especially when item sprites are animated.

Note: tick frequency can be accessed/changed via a levels getTickFrequency()/setTickFrequency()

methods.
http://code.google.com/p/gwtbox2d/http://code.google.com/p/gwtbox2d/http://code.google.com/p/gwtbox2d/http://box2d.org/http://box2d.org/http://box2d.org/http://box2d.org/http://box2d.org/http://box2d.org/http://box2d.org/http://box2d.org/http://code.google.com/p/gwtbox2d/


4/23



The Level Life Cycle Illustrated

Create Level and Level

event handlers

Add Items and item event handlers

Fire onLevelStart() Event

For each Item, fire onItemStart() Event

Fire onLevelTick() Event

For each item fire onItemTickEvent

Fire any Touch & Key events received

Advance Level physics by one clock tick

Fire an onItemHit events due to collisions

Level

Complete?

Fire

onLevelDone()

event

No YesDone

Elapsed time >

1/60th second?

Render Level

No

Yes

Decrement Elapsed time by 1/60th sec


5/23



Lagacode Package StructureLagacode games are organized via apackage structure. A Lagacode package is a collection of images,

sounds, event-handler code, game items and game levels. Lagacode packages should be viewed asatomic in the sense that, if a reference is made to an element (image, sound, code file, etc.) in the

package, the entire package will be downloaded in order to access that element.

The goal is to keep packages as small as reasonable to enable quick download and caching of games.

Packages can be grouped together via the package importfeature. A package declares which other

packages it depends on within the IDE via adding an Import list (a JSON object with a list of package

names to import). When a game level is loaded from the package, a recursive check is done ensure all

needed packages are downloaded before level gameplay is launched.

Package Forking

One of the goals for building the Lagacode developer community is the sharing of packages, both as

imports as well as forking. A package fork is a deep copy of all the elements in the package. The main

use case for forking a package is to give a developer a quick way jumpstart game development. This is

especially useful when one is starting out and trying to learn the SDK. Rather than coding a Hello

World game from scratch, a forked copy of a sample game gives a developer a quick way to start

playing around with the SDK and build on the work of others.

In order for a Lagacode community member to fork a package developed by another community

member, the package must be marked Public. Otherwise, it will be inaccessible for forking. Similarly,

any package imports must also be public or the package will be unusable to other developers.

Package:FileName format

Files and other assets (sounds, images) are uniquely referenced via package:fileName format. That is,

a resource locator for items within the Lagacode universe consists of a package name and file name

delimited by a colon (:). For example, suppose your package is named MyPackage and you have an

image named MyImage. You can reference the image asMyPackage:MyImage (no spaces).

__pkg__ Identifier

Lagacode packages are designed to be forked (cloned) to create new packages. We believe the best way

to learn a new language or platform is to dig in to someone elses code and change it. To aid this reuse,

the package part of the package:fileName format can be replaced with__pkg__ (two underscores oneither side ofpkg). When packages are loaded, the__pkg__ character sequence is replaced with the

current package name. In the example above, MyPackage:MyImage could be referenced as

__pkg__:MyImage within the MyPackage package. The motivation for this macro replacement is to

enable simpler package forking. A package that consistently uses the__pkg__ identifier can easily be

forked without any code modifications in the new package.


6/23



PlaylistA playlist is an ordered collection of levels.

JSON Properties

Name Type DescriptionnextPlaylist String The name of a playlist, in package:fileName format, that will be

played after this playlist is completed. Default is null.

playlist[] Array An ordered array containing the names of the levels, in

package:fileName format, to be played. The package to which the

playlist belongs must have access (import if necessary) all the

packages of the levels listed in the array. A valid, non-empty array

declaration is required for the playlist to be valid.


7/23



Level

JSON Properties

Name Type Descriptionparent String The name of the of the parent level, if any, in package:fileName

format. Default is null.

helpLevel String The name of the help level, if any, in package:fileName format. The

help level is displayed when a user selects the menu and then clicks

on the help button. It is intended to instruct the user on game play.

Default is null.

config Object Configuration object to be passed to each of the levels event

handlers. Default is null.

viewportWidth Number The width, in World units, of the display viewport. Note: 1 World unit

is equivalent to 1 meter when used by the physics engine. Default

value is 100

viewportHeight Number The height, in World units, of the display viewport. Note: 1 World

unit is equivalent to 1 meter when used by the physics engine.Default value is 50.

viewportX Number The center X coordinate, in World units, for the display viewport.

Default is 0.

viewportY Number The center Y coordinate, in World units, for the display viewport.

Default is 0.

gravity Number The X component of the gravitational force for the World, in meters

per seconds squared. Default is 0.

gravityY Number The Y component of the gravitational force for the World, in meters

per seconds squared. Default is 0. To simulate Earth gravity, a value

of -9.8 (or something close like -10) should be used.

itemDefs[] Array An array containing item declarations to be placed in the level beforethe level event loop is started. Default is null

eventHandlers[] Array An array of event handlers to be created for the level. See Event

Handler JSON definition. Default is null

backgroundColor String The background color (in CSS/HTML format) of the level. Default

value is black

infoColor String The color (in CSS/HTML format) of the info bar (level score, menu

button, etc.). Default value is white


8/23



Level Events

Name DescriptiononLevelStart(Object evtParms) Raised automatically when a level has been initialized and the event

loop is about to commence. Called before item start events.

Parameters: evtParms - null

onLevelTick(Object evtParms) Raised automatically at each clock tick (1/60th of a second) of theevent loop. Clock ticks are called after physics (movements,

collisions) have been resolved and before items are rendered.


onLevelDone(Object evtParms) Raised manually by calling the _level objects done() method to

indicate level play has completed.

Parameters: evtParmsnull

_level Object Methods

Each level and item event handler is injected with a_level property that exposes the following methods.

Name Descriptionvoid addItem(Object itemDef) Adds an item to the level. Once added, the items

onItemStart event is raised.

Parameters: itemDef object containing the JSON definition

of the item to be added.

void addItemByName(String

itemDefName)

Adds an item to the level. Once added, the items

onItemStart event is raised.

Parameters: itemDefName string referencing the name

item definition in package:fileName format.

void dropItem(item) Removes an item from the level.

Parameters: item the_item object which is to be dropped.

_item is a property injected into Item event handlers (alongwith_game and_level).

void setViewportXY(x, y) Sets the center point for the viewport. The default center is

(0,0).

Parameters: x, y the x and y coordinates (in world units).

World coordinates are right-handed meaning that x units

increase from left to right and y units increase from bottom to

top.

XY getViewportXY() Retrieves the current center point for the viewport.

Return Value an object with x and y properties representing

the center point.

For example:

var center = this._level.getViewportXY();alert('center is ' + center.x + ',' +center.y);

Number getTickFrequency() Returns the number of tick events generated per second by

the level. Default is 60

Return Value a number between 1 and 1,000.


9/23



void setTickFrequency(Number freq) Sets the number of tick events generated per second by the

level.

Parameters: freq a number between 1 and 1,000

Number getLevelScore() Returns the current score for the level.

Return Value a number between 0 and 10,000

void setLevelScore(Number score) Sets the current score for the level.Parameters: score a number between 0 and 10,000

Number getPlayerHighScore() Returns the players highest score for the level. Note: high

scores are retrieved asynchronously and may not be

available when onStart() events are fired.

Number getGlobalHighScore() Returns the highest score recorded for the level by any

player. Note: high scores are retrieved asynchronously and

may not be available when onStart() events are fired.

void raiseEvent(String eventType,

String eventName, Object

eventParms)

Raises an event to the level.

Parameters: eventType the type of event, possibly user-

defined. Event listeners are attached to specific event types.

Example value - Touch

eventName the name of the event being raised. For

example, Start

eventParms event-specific parameters. Vary by event and

can be null.

void done() Signals that the level is complete. The game event loop is

stopped and the levels score is recorded. The game then

moves to the next level in the playlist.

void switchToLevel(String

playlistName, String levelName,

boolean raiseDoneEvent)

Switch to a new level, possibly raising the onLevelDone()

event for the current level.

Parameters: playlistName the name of the playlist, in

package:filename format, which contains the level.

levelName the name of the level, in package:filenameformat, to be played.

raiseDoneEvent a flag indicating whether or now the

onLevelDone() event should be raised for the current level.

void setBackgroundColor(String color) Sets the levels background color.

Parameters: color - the color (in CSS/HTML format) of the

body. Transparent bodies should have a color of

transparent. Default value is black

String getBackgroundColor() Returns the levels background color.

log (String text) Displays a line of text in the console window of the

development IDE. Has no effect if the game is being played

outside the IDE.Parameters: text - the string to be displayed.

Return ValueNone


10/23



playSound (String soundName,

Number [volume])

Plays a named sound immediately.

soundName the name of the sound in package:filename

format

volume (optional) a value between 0 and 1 indicating how

loud to play the sound. Default is 0.5

Return ValueNone

playStereoSound (String soundName,

Number leftVolume, Number

rightVolume)

Plays a named sound immediately with possibly different left

and right channel volumes.

soundName the name of the sound in package:filename

format

leftVolume a value between 0 and 1 indicating how loud to

play the sound in the left channel.

rightVolume a value between 0 and 1 indicating how loud to

play the sound in the left channel.

Return Value - None


11/23



Item

JSON Properties

Name Type Descriptionparent String The name of the of the parent item, if any, in package:fileName

format. Default is null.

config Object Configuration object to be passed to each of the items event

handlers. Default is null.

bodyType static |

kinematic |

dynamic

Please refer to theBox2D Manualfor a full description of static,

kinematic and dynamic bodies. Note that static and kinematic

bodies do not collide with each other. Default value is static

sensor Boolean Sometimes game logic needs to know when two fixtures overlap

yet there should be no collision response. This is done by using

sensors. A sensor is a fixture (item) that detects collision but

does not produce a response.Default value is: false

shape circle |

rectangle

The physical shape of the item. Currently, we only support

circles and rectangles. Also, we only support one fixture perbody (in Box2D terminology) Default value is rectangle

fixedRotation Boolean From theBox2D Manual: You may want a rigid body, such as a

character, to have a fixed rotation. Such a body should not

rotate, even under load The fixed rotation flag causes the

rotational inertia and its inverse to be set to zero. Default value

is false.

bullet Boolean Please see theBox2d Manualfor a detailed description of the

bullet attribute. In a nutshell, setting bullet to true helps

ensure that small, fast-moving objects do not tunnel thru

other objects and avoid collision detection. There is a

performance cost for this, so set this attribute to truejudiciously.

Default value is false.

angularDamping Number From theBox2d Manual: Damping is used to reduce the world

velocity of bodies. Damping is different than friction because

friction only occurs with contact. Damping is not a replacement

for friction and the two effects should be used together.

Damping parameters should be between 0 and infinity, with 0

meaning no damping, and infinity meaning full damping.

Normally you will use a damping value between 0 and 0.1.

Default value is 0.01
http://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdf


12/23



linearDamping Number From theBox2d Manual: Damping is used to reduce the world

velocity of bodies. Damping is different than friction because

friction only occurs with contact. Damping is not a replacement

for friction and the two effects should be used together.

Damping parameters should be between 0 and infinity, with 0

meaning no damping, and infinity meaning full damping.

Normally you will use a damping value between 0 and 0.1.I

generally do not use linear damping because it makes bodies

look floaty.

Default value is 0

color String The color (in CSS/HTML format) of the body. Transparent

bodies should have a color of transparent.Default value is

transparent

alpha Number Level of opacity/transparency of item. 0 is transparent, 1 is

completely opaque. Default value is 1

radius Number The radius, in world units, of a circle shape. Not used by

rectangle shapes. Default value is 0

width Number The (full) width of a rectangle shape. Not used by circle shapes.

This use differs from the Box2D API, which defines rectangles

using half the width. Default value is 0

height Number The (full) height of a rectangle shape. Not used by circle

shapes. This use differs from the Box2D API, which defines

rectangles using half the height. Default value is 0

density Number From theBox2d Manual: The fixture density is used to compute

the mass properties of the parent body. The density can be zero

or positive. You should generally use similar densities for all

your fixtures. Default value is 1

restitution Number From theBox2d Manual:Restitution is used to make objects

bounce. The restitution value is usually set to be between 0 and1. Consider dropping a ball on a table. A value of zero means

the ball won't bounce. This is called an inelastic collision. A

value of one means the ball's velocity will be exactly reflected.

This is called a perfectly elastic collision. Default value is 0.3

friction Number From theBox2d Manual: Friction is used to make objects slide

along each other realistically. Box2D supports static and

dynamic friction, but uses the same parameter for both. Friction

is simulated accurately in Box2D and the friction strength is

proportional to the normal force (this is called Coulomb

friction). The friction parameter is usually set between 0 and 1,

but can be any non-negative value. A friction value of 0 turns offfriction and a value of 1 makes the friction strong. Default value

is 0.3

x Number The x coordinate, in world units, of the item. Note that world

coordinates are a right-handed system (with z-axis pointing

towards us) where x increases from left to right and y increases

from bottom to top. Default value is 0
http://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdf


13/23



y Number The y coordinate, in world units, of the item. Note that world

coordinates are a right-handed system (with z-axis pointing

towards us) where x increases from left to right and y increases

from bottom to top. This differs from typical graphics systems

(left-handed) where y increases from top to bottom. Default

value is 0

zIndex Number The stack order of items during rendering. As with CSS, an item

with a higher z index will overlap an item with a lower z-index.

Default value is 0

angle Number The rotation of the item in radians. In the world coordinate

system, increasing the angle rotates the item counter-

clockwise. Default value is 0

text String Text to display over this item. Default is null

textColor String Color of the text to be displayed. Default is black.

textAlign center | left |

right

Alignment of the text (in HTML/CSS format).Default is center

textCharWidth Number The width, in world units, that a capital A should be. For

example, if the levels viewport width is 100 world units, then a

textCharWidth of 2 means 50 As will fit across the viewport

horizontally. Default is 2.5.

textFont String The name of the font to display. Default is Calibri

textAlpha Number A number between 0 and 1 (inclusive) indicating the alpha level

of the text. 0 is completely transparent and 1 indicates

completely opaque. Default value is 1.

sprites[] Array List of sprites attached to this item. May be null if no sprites

are used. See Sprite JSON definition. Default is null.

eventHandlers[] Array An array of event handlers to be created for the item. See Event

Handler JSON definition. Default is null


14/23



Item Events

Event handler type Item

Name Description

onItemStart(evtParms) Raised automatically after an item has been created and before the nextevent loop clock tick.


onItemTick(evtParms) Raised automatically at each clock tick (1/60th

of a second) of the event loop.

Clock ticks are called after physics (movements, collisions) have been

resolved and before items are rendered.


onItemHit(evtParms) Raised automatically by the physics engine when two items collide. Two

onItemHit events are raised. Assume item A hits item B, then an onItemHit

event is raised to item A passing in itemB as a parameter and an onItemHit

event is raised to item B passing in item A as a parameter.

Parameters: evtParmsthe_item object of the item with which this item

collided


15/23



_item Object Methods

Each item event handler is injected with a_item property that exposes the following methods.

Location

Name DescriptionNumber getRadius () Returns the radius, in world coordinates, of a circle item.

Number getWidth () Returns the width, in world coordinates, of a rectangle item.

Number getHeight () Returns the height, in world coordinates, of a rectangle item.

Number getAngle () Returns the items angle in radians.

void setAngle (Number radians) Sets the items angle

Parameters: angle the radians value of the angle

XY getPosition() Retrieves the current center point for the item.

Return Value an object with x and y properties representing the

center point.

For example:

var pos = this._item.getPosition();

alert('Position is ' + pos.x + ',' + pos.y);void setPosition (Number x,

Number y)

Sets the center point for the item.

Parameters: x, y the x and y coordinates (in world units). World

coordinates are right-handed meaning that x units increase from

left to right and y units increase from bottom to top.

void setTransform (Number x,

Number y, Number radians)

Sets the center point and angle of the item. This is a way to move

an item without using forces or setting a velocity. Item velocity is

preserved.

Parameters: x, y the x and y coordinates (in world units). World

coordinates are right-handed meaning that x units increase from

left to right and y units increase from bottom to top.

anglethe radians value of the items angle


16/23



Physics

The_item property exposes a number of physics-related methods. For an explanation of the methods,

please see theBox2d Manual.

Name Description

void applyAngularImpulse (Number impulse)void applyForce:(Number force_x, Number force_y, Number

point_x, Number point_y)

void applyLinearImpulse (Number impulse_x, Number impulse_y,

Number point_x, Number point_y)

void applyTorque (Number torque)

Number getAngularDamping ()

void setAngularDamping (Number angularDamping)

Number getAngularVelocity ()

void setAngularVelocity (Number angularVelocity)

Number getInertia ()

XY getCenterOfMass ()Number getMass ()

boolean getBullet()

void setBullet (Boolean flag)

void setFixedRotation (Boolean flag)

Number getLinearDamping ()

void setLinearDamping (Number linearDamping)

XY getLinearVelocity ()

void setLinearVelocity (Number x, Number y)
http://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdfhttp://box2d.org/manual.pdf


17/23



Display

Name DescriptionsetColor(String color) Sets the color of the shape (in HTML/CSS format).

getColor() Returns the current color of the shape.

setText (String text) Sets the text to display over this item.

getText () Returns the current text for the item.

setText Color(String textColor) Sets the color of the text to be displayed (in

HTML/CSS format).

getText Color() Returns the current text color of the item.

setText Align(String textAlign) Sets the alignment of the items text (in HTML/CSS

format).

getText Align() Returns the alignment of the items text.

setText Alpha(Number textAlpha) Sets the alpha level of the items text.

getText Alpha() Retrieves the alpha level of the items text.

putSprite (String spriteName, Object spriteDef) Attaches (or updates) a named sprite to the item.

Parameters: spriteName the name of the sprite

spriteDef a sprite definition (see JSON descriptionbelow).

dropSprite (String spriteName) Detaches (removes) a named sprite from an object.

The sprite will no longer be displayed.

getSprite (String spriteName) Retrieves a named sprite from the object. Can be

used in conjunction with putSprite to update a

sprites position/appearance/etc and enable

animation.

Return value: a sprite definition.

Miscellaneous

Name DescriptionraiseEvent (String eventType, String

eventName, Object eventParms)

Raises an event to the item.

Parameters:

eventType the type of event, possibly user-defined. Event

listeners are attached to specific event types. Example value -

Touch

eventName the name of the event being raised. For

example, Start

eventParms event-specific parameters. Vary by event and

can be null.


18/23



SpriteA sprite is a scaled image that is connected to an item. An item can have zero or more sprites connected

to it.

JSON Properties

Name Type DescriptionimageName String The name of the image, in package::fileName format, to be displayed.

tileX Number The x offset of which tile in the image to be used. Default is 0.

tileY Number The y offset of which tile in the image to be used. Default is 0.

width Number The width of the sprite in world units. Indicates how the sprite is

scaled horizontally. Default value is 5.

height Number The height of the sprite in world units. Indicates how the sprite is

scaled vertically. A value of-1 indicates the sprite should maintain its

aspect ratio. Default value is -1.

x Number The offset, in world units, of the center of the sprite relative to thex

position of the item. That is, a value of 0 indicates the horizontal

center of the sprite matches that of the underlying item. Default

value is 0.

y Number The offset, in world units, of the center of the sprite relative to they

position of the item. That is, a value of 0 indicates the vertical center

of the sprite matches that of the underlying item. Default value is 0.

angle Number The rotation of the sprite in radians. Default value is 0.

alpha Number A number between 0 and 1 (inclusive) indicating the alpha level of the

image. 0 is completely transparent and 1 indicates completely

opaque. Default value is 1.


19/23



Event HandlersEvent handlers, within Level and Item definitions must be declared in the following manner.

{

handler: "handlerObjectName",

types: ["eventType1", "eventType2", ]}

The handlerObjectName is the name of the Javascript object that will be created and the eventTypes

are the types of events the object should be contacted to handle. For example, assume a Javascript

object called uiLaunchPad will handle both Item and Touch events. Its event handler declaration would

look something like this:

eventHandlers:[

{

handler: "uiLaunchPad",

types : ["Touch","Item"],

}]

A single item or level can have more than one event handler and a single event handler may handle

events of more than one type.

IMPORTANT: currently, an item or level can only have one handler for each type of event. What that

means is that if a child item or level declares a handler for a specific type of event, it will effectively

hide parent event handlers of the same event. We are considering easing this restriction and (as

always) welcome feedback from the developer community.

Event Handler Javascript DefinitionsEvent handlers are implemented within package Code files. More than one event handler can be

defined within a single code file. Event handlers need not implement every event in their declared

interfaces. For example, an object that implements the Item interface might only define anonItemTick()

method.

Event handlers should be declared as functions that take a single config parameter . We highly

recommend keeping all Javascript code within event handlers. If globals are needed for a level, use the

_level field that is assigned to each event handler.

Below is an example event handler for a level. Keep in mind that an event handler can handle multiple

types of events. Indeed, it is generally advantageous to group the event handlers for an object (item or

level) into a single Javascript object.


20/23



function myEventHandler(config)

{

this.firstTime = true;

this.configThing = config.configThing;

// handle the Level Start event

this.onLevelStart = function(evtParms)

{

// add a property to the _level object.

this._level.myGlobal = true;

return true; // weve handled the event, do not pass it on

};

// handle the Level Done event

this.onLevelDone = function(evtParms)

{

return true;

};

// handle the Level Tick event (a tick is 1/60th of a second)

this.onLevelTick = function(evtParms)

{

// do something at each clock tick

// assume that isDone is a Boolean indicating whether the level

// is complete.

if (isDone === true)

{

this._level.done(); // let the system know were done}

}

};


21/23



Mouse/Touch EventsMouse events and touch events are not differentiated. That means that mouse down/up/move events

are treated identically to mobile touch down/up/move events. It also means that a full set of multi-

touch events are not supported to maintain compatibility with browser versions of games.

Touch events are first fired on the item(s) (if any) at the point of event contact. If there is no itemsituated there or the items do not have a touch event handler or an items touch event handler returns

false (ie/allows further event handlers to be fired), then the current levels touch event handler(s) will

be called.

Over & Out events are also supported and work in a similar manner to JavaScript mouseover and

mouseout events, including event bubbling.

Name DescriptiononTouchStart(Object xy) Fires on a mouse down/touch start event.

Parameters: xy an XY object indicating (in world coordinates)

where the touch event occurred

onTouchEnd(Object xy) Fires on a mouse up/touch endevent.



onTouchMove(Object xy) Fires on a mouse move/touch move event.



onTouchOver(Object o) Fires when a mouse pointer (or touch move) enters an object. Only

fires on items.

Parameters: o null

onTouchOut(Object o) Fires when a mouse pointer (or touch move) exits an object. Only

fires on items.Parameters: o - null


22/23



Keyboard EventsKeyboard events can arise from actual keyboard events and can be simulated as well for devices that do

not have keyboards. For example, a level can create items that handle Touch Start and End events to

fire Key Down and Up events.

Name DescriptiononKeyDown(Object keyEvt) Fires when a key is depressed. May be fired multiple times if the

user holds the key down for an extended period of time.

Parameters: keyEvt a JSON object containing the following fields:

keyCode: the integer value for the key. For a good discussion of

JavaScript keyCode issues, please see

http://www.javascripter.net/faq/keycodes.htm

keyChar: the character value of the key.

altKey: boolean flag indicating whether the Alt key is pressed.

ctrlKey: boolean flag indicating whether the Ctrl key is pressed.shiftKey: boolean flag indicating whether the Shift key is pressed.

onKeyUp(Object keyEvt) Fires when a depressed key is released.

Parameters: keyEvt a JSON object containing the following fields:

keyCode: the integer value for the key. For a good discussion of

JavaScript keyCode issues, please see

http://www.javascripter.net/faq/keycodes.htm

keyChar: the character value of the key.

altKey: boolean flag indicating whether the Alt key is pressed.ctrlKey: boolean flag indicating whether the Ctrl key is pressed.

shiftKey: boolean flag indicating whether the Shift key is pressed.
http://www.javascripter.net/faq/keycodes.htmhttp://www.javascripter.net/faq/keycodes.htmhttp://www.javascripter.net/faq/keycodes.htmhttp://www.javascripter.net/faq/keycodes.htmhttp://www.javascripter.net/faq/keycodes.htmhttp://www.javascripter.net/faq/keycodes.htm


23/23


Copyright 2012 Lagacode All Rights Reserved Page 23

ImagesImages are uploaded within the IDE. A single image may consist of multiple tiles. If so, the image is

divided evenly based on the number of Horizontal Tiles (columns) and Vertical Tiles (columns) it

contains.

When uploading images, make sure you have the legal right to use the image and also make sure youassign the image appropriate attribution.

SoundsComing soon.

StringsComing soon.

Documents

Lagacode SDK