Class Black extends MessageDispatcher

The Black class represents the core of the Black Engine.

Methods

Black(containerElementId, gameClass, videoDriverClass, systemClasses) constructor

Creates a new Black instance.

First parameter has to be a id of the HTML div element the game will be rendered to.
Second parameter has to be GameObject class which will be the root object of your application.
Third parameter has to be a class name of VideoNullDriver subclass eg CanvasDriver.
Fourth parameter is optional array of System to use,

Parameters
containerElementId : string — The id of an DOM element.
gameClass : function — Type name of an GameObject to start execution from.
videoDriverClass : function — Type name of an VideoDriver (VideoNullDriver, DOMDriver or CanvasDriver)
systemClasses : Array.<function(new:System)> — The list of systems to be initialized with Black engine.
pause() method
Pauses all engine update logic. Note: RAF is not going to be paused and will work in background.
resume() method
Resumes update execution.
hasSystem(systemTypeName) method

Returns true if system exists.

Parameters
systemTypeName : function
getSystem(typeName) method

Gets system by type.

Parameters
typeName : function — The system type.
Returns
System | null — The `System` instance or null if not found.
start() method
Boots up the engine!
stop() method
Stops any executions, destroys resources and scene.
onTagUpdated(child, oldTag, newTag) method

Called when tag changed for specific GameObject.

Parameters
child : GameObject — A game object fired the event.
oldTag : string | null — Old tag.
newTag : string | null — New tag.
Returns
void
onChildrenAdded(child) method

Called when specific game object is added to display list.

Parameters
child : GameObject — Instance of GameObject.
Returns
void
onChildrenChanged(child) method

Called when specific game object is changed its index in display list.

Parameters
child : GameObject — Instance of GameObject.
Returns
void
onChildrenRemoved(child) method

Called when specific game object is added to display list.

Parameters
child : GameObject — Instance of GameObject.
Returns
void
onComponentAdded(child, component) method

Called when specific component is added to GameObject instance.

Parameters
child : GameObject — Instance of GameObject.
component : Component — Instance of Component added to game object.
Returns
void
onComponentRemoved(child, component) method

Called when specific component is removed from its owner.

Parameters
child : GameObject — Instance of GameObject.
component : Component — Instance of Component removed from game object.
Returns
void

Inherited Methods

on(name, callback, context) inherited method

Adds listener by given name and callback.

Parameters
name : string — Message name.
callback : function — Function to be called on message send.
context : * — Object to be used as this in callback function.
Returns
MessageBinding
off(names) inherited method

Removes all bindings by given message name.

Parameters
names : string — One or more message name.
Returns
void
once(name, callback, context) inherited method

Adds listener by given name and callback. Binding will be automatically removed after first execution.

Parameters
name : string — Message name.
callback : function — Function to be called on message send.
context : * — Object to be used as this in callback function.
Returns
MessageBinding
post(name, params) inherited method

Posts message with a given params.

Adding ~ character to the begging of the name will bubble message to the top of the tree.

Parameters
name : string — The name of a message
params : * — A list of params to send
Returns
void

Properties

ups : number property
Gets/Sets the number of updates should be done per second.
viewport : Viewport property
Returns the current viewport instance. Used to get size of a game screen, or listen for resize messages.
containerElement : Element property
Returns the DOM element the engine runs in.
pauseOnHide : boolean property
Gets/Sets if engine should be automatically paused when window is hidden.
pauseOnBlur : boolean property
Gets/Sets if engine should be automatically paused when container element is blurred.
isPaused : boolean property
Returns True if engine is paused.
stage : Stage property
Returns current stage.
containerElementId : string property
Returns HTML container element id.
splashScreen : SplashScreen property
Returns currently active splash screen. Splash screen posts Message.COMPLETE message on hide.
useHiDPR : boolean property
Gets/sets whenever driver should be created with high DPR support.
NOTE: Cannot be changed at runtime.
magic : number static property
Black.magic! Got it? Got it?!?! Same as Math.random() but much cooler.
driver : VideoNullDriver static property
Returns current video driver.
stage : Stage static property
Returns current stage.
frameNum : number static property
Returns number of frame since engine start.
instance static property
Reference to the current Black instance.
numUpdates static property
Indicates how many updates will be done during this frame.
maxUpdatesPerFrame static property
Limit for number of updates to be done per one RAF.

Inherited Properties

parent : MessageDispatcher | null inherited property
Returns parent MessageDispatcher.
path : string | null inherited property
Returns string representing a url like path to this object in the display
tree.

Messages

paused message
Posted after engine entered paused state.
unpaused message
Posted after engine is unpaused.
ready message
Posted when all systems, stage and driver ready to be used.
looped message

Posted when engine is not able to achieve desired amount of updates per second.

Usually happens when user switches to another tab in browser or update logic is too heavy to be executed
withing one update loop. Lowering Black.ups value can help if update is heavy.
Increasing Black.maxUpdatesPerFrame can lead to dead lock.