jStage.Stage

Description

A special kind of actor that acts as the root node in the scene graph. Contains many methods for performing game state management, as well as canvas initialization and rendering properties.

Hierarchy

Remarks

You should not ever need to explicitly instantiate this class or use it directly! To create your custom game Stage, subclass Stage and pass a reference to your subclass constructor to jStage.init to bootstrap your game into existence (see Basic Game Tutorial).

Articles

Objects

Property List

Function List

Property Documentation

debugHotkeysEnabled

A boolean determining if the Stage object is currently responding to debug hotkey events.

Remarks

See mouseEvents.

gravity

A jStage.Vector object representing this actor's acceleration due to gravity (px/s^-2).

keyboardEvents

A boolean determining if the Stage object is currently responding to keyboard events.

Remarks

See mouseEvents.

mouseEvents

A boolean determining if the Stage object is currently responding to mouse events.

Remarks

Setting this value after the game is initialized will have no effect! If you wish to alter listener state once the Stage has initialized (i.e. after onInitialized() has fired), use setMouseEvents(listening), setTouchEvents(listening), setKeyboardEvents(listening) and setDebugHotkeysEnabled(listening).

touchEvents

A boolean determining if the Stage object is currently responding to touch events.

Remarks

See mouseEvents.

Function Documentation

Stage()constructor

changeState(state)

Transitions between game states.

Parameters

state:An integer value representing the game state to transition to. -1 is a reserved value (representing uninitialized) and may not be used.

Returns

this (itself) - so you can chain operations.

Remarks

How you use this function is up to you and the needs of your game; you may have many states for things like loading, loaded, game in progress, paused, ended, etc., or you may just choose to use the initial ready (0) state and handle game state in a different way.

You do not need to explicitly call this to transition out of the uninitialized state; the Stage will do this automatically once all resource preloading has been completed. When this occurs it will enter state 0.

Calling this may invoke onInitialized(), onStateBeginning(state) and onStateEnding(state) - it is up to you to implement these in your subclasses if you need them.

Be very wary of calling this from within onStateBeginning(state) or onStateEnding(state) as infinite loop potential is very high!

changeStateTimer(state, timeout)

Transitions between game states on a delay.

Parameters

state:An integer value representing the game state to transition to. -1 is a reserved value (representing uninitialized) and may not be used.

timeout:The delay, in seconds, until the state change occurs. Passing values <= 0.0 will instead cancel any pending timed state change.

Returns

this (itself) - so you can chain operations.

onActorCreated()event

Event that is fired whenever an actor is instantiated.

onActorKilled(actor)event

Event that is fired whenever an actor is killed.

Parameters

actor:The actor that was just removed from the world and flagged for garbage collection.

onInitialized()event

Event that is fired when leaving the uninitialized (-1) state.

onKeyDown(keyCode)event

Event that is fired whenever a key is first pressed down.

Parameters

keyCode:The key code triggering the event.

onKeyHeld(keyCode)event

Event that is fired whenever a key is held down.

Parameters

keyCode:The key code triggering the event.

onKeyPress(keyCode)event

Event that is fired whenever a key is pressed.

Parameters

keyCode:The key code triggering the event.

Remarks

This event is not the same as onKeyDown(keyCode); onKeyPress refers to a complete down/up cycle without any delayed holding.

onKeyUp(keyCode)event

Event that is fired whenever a key is released.

Parameters

keyCode:The key code triggering the event.

onMouseDown(location)event

Event that is fired whenever a mouse button is first pressed down.

Parameters

location:A vector object containing the location of the event.

onMouseEnter(location)event

Event that is fired whenever the mouse cursor enters the canvas.

Parameters

location:A vector object containing the location of the event.

onMouseLeave(location)event

Event that is fired whenever the mouse cursor leaves the canvas.

Parameters

location:A vector object containing the location of the event.

onMouseMove(location)event

Event that is fired whenever the mouse cursor is moved over the canvas.

Parameters

location:A vector object containing the location of the event.

onMouseUp(location)event

Event that is fired whenever a mouse button is released.

Parameters

location:A vector object containing the location of the event.

onPreLoadProgress(file, complete, remaining)event

Event that is fired when the Stage finishes preloading one audio or image resource.

Parameters

file:The filename of the resource that finished loading.

complete:The total number of preload resources that have completed loading.

remaining:The total number of preload resources still awaiting load completion.

onPreLoadStart(remaining)event

Event that is fired when the Stage begins preloading audio and image resources.

Parameters

remaining:The total number of preload resources still awaiting load completion.

onStateBeginning(state)event

Event that is fired when a new state is beginning.

Parameters

state:The state that is beginning.

onStateEnding(state)event

Event that is fired when an old state is ending (but before the next one has begun).

Parameters

state:The state that is ending.

setBackBufferTransform(transform)

If the canvas is being rendered in double-buffered mode, this sets the transform method used to copy the image from the backbuffer to the frontbuffer.

Parameters

transform:A string value from the following:
'stretch': The backbuffer image is stretched to match the frontbuffer, without regard for aspect ratios. This is default.
'copy': The backbuffer image is copied without scaling, and centered on the frontbuffer. Larger backbuffers will appear cropped evenly on all sides, smaller backbuffers will appear center-letterboxed.
'fit': Scales the backbuffer to fit perfectly within the frontbuffer, while maintaining the original aspect ratio. Will appear letterboxed vertically or horizontally.
'zoom': The opposite of 'fit', this mode scales the backbuffer so it's smallest side fits perfectly within the frontbuffer, cropping the larger dimension.

Returns

this (itself) - so you can chain operations.

setDebugHotkeysEnabled(listening)

Registers/unregisters the global keyboard debug hotkey listeners.

Parameters

listening:A boolean representing whether you would like to be listening to keyboard debug hotkey events or not.

Returns

this (itself) - so you can chain operations.

Remarks

Calling this while the Stage is in the uninitialized (-1) state has no effect; if you'd like to set the initial state of the keyboard debug hotkey listers, set Stage.debugHotkeysEnabled directly.

setFrameRateLimits(min, max)

Sets target frame rates.

Parameters

min:Your desired minimum frame rate. If undefined or NaN, 30.0 is assumed.

max:Your desired maximum frame rate. If undefined or NaN, 65.0 is assumed.

Returns

this (itself) - so you can chain operations.

Remarks

Owing to the variable nature of graphics rendering, this function will not garuntee minimum or maximum frame rates, but will ensure that delays between frames are as close as possible to your chosen targets.

Only rarely will you need to use this function, the default values should be fine.

setKeyboardEvents(listening)

Registers/unregisters the global keyboard listeners.

Parameters

listening:A boolean representing whether you would like to be listening to keyboard events or not.

Returns

this (itself) - so you can chain operations.

Remarks

Calling this while the Stage is in the uninitialized (-1) state has no effect; if you'd like to set the initial state of the keyboard listers, set Stage.keyboardEvents directly.

setMouseEvents(listening)

Registers/unregisters the global mouse listeners.

Parameters

listening:A boolean representing whether you would like to be listening to mouse events or not.

Returns

this (itself) - so you can chain operations.

Remarks

Calling this while the Stage is in the uninitialized (-1) state has no effect; if you'd like to set the initial state of the mouse listers, set Stage.mouseEvents directly.

setTouchEvents(listening)

Registers/unregisters the global touch listeners.

Parameters

listening:A boolean representing whether you would like to be listening to touch events or not.

Returns

this (itself) - so you can chain operations.

Remarks

Calling this while the Stage is in the uninitialized (-1) state has no effect; if you'd like to set the initial state of the touch listers, set Stage.touchEvents directly.

updateScreenBounds()

The Stage calculates it's own padding, margins etc based on the current computed styles and it's own dimensions, which get used to help accurately determine where mouse and touch events take place. Calling this will recalculate those bounds on rare occasions that you need to force them (e.g. resizing the canvas).

Returns

this (itself) - so you can chain operations.