Class GameObject extends MessageDispatcher

Building block in Black Engine.

Methods

GameObject() constructor
Creates new instance of GameObject.
checkStatic(includeChildren) method

Returns true if object was clean for at least 1 update.

Note: Make sure to apply all changes to this game object before checking for static.

Parameters
includeChildren : boolean
Returns
boolean
onAdded() method
This method called each time object added to stage.
onRemoved() method
Called when object is removed from stage.
add(gameObjectsAndOrComponents) method

Sugar method for adding child GameObjects or Components in a simple manner.

Parameters
gameObjectsAndOrComponents : GameObject | Component — A GameObject or Component to add.
Returns
GameObject — This game object
addChild(child) method

Adds a child GameObject instance to this GameObject instance. The child is added to the top of all other
children in this GameObject instance.

Parameters
child : GameObject — The GameObject instance to add as a child of this GameObject instance.
Returns
GameObject
addChildAt(child, index) method

Adds a child GameObject instance to this GameObject instance. The child is added to the top of all other
children in this GameObject instance.

Parameters
child : GameObject — The GameObject instance to add as a child of this GameObject instance.
index : number — The index position to which the child is added.
Returns
GameObject — The GameObject instance that you pass in the child parameter.
setChildIndex(child, index) method

Sets the index (layer) of the specified GameObject to the specified index (layer).

Parameters
child : GameObject — The GameObject instance to change index for.
index : number — Desired index.
Returns
GameObject — The `GameObject` instance that you pass in the child parameter.
removeFromParent() method
Removes this GameObject instance from its parent.
removeChild(child) method

Removes specified child GameObject instance from children.

Parameters
child : GameObjectGameObject instance to remove.
Returns
GameObject — The `GameObject` instance that you pass in the child parameter.
getChildByName(name) method

Finds children by name.

Parameters
name : string — Name of the child object to find.
Returns
GameObject | null — GameObject instance or null if not found.
removeChildAt(index) method

Removes GameObjects instance from specified index.

Parameters
index : number — Index of child.
Returns
GameObject — The removed `GameObject` instance.
getChildAt(index) method

Returns GameObject at specified index.

Parameters
index : number — The index of child GameObject.
Returns
GameObject — The `GameObject` at specified index.
addComponent(component) method

Adds Component instance to the end of the list.

Parameters
component : ComponentComponent instance or instances.
Returns
Component — The `Component` instance you pass in the instances parameter.
removeComponent(instance) method

Remove specified component.

Parameters
instance : Component — The Component instance.
Returns
Component | null
getComponent(typeName) method

Get component by type.

Parameters
typeName : function — The component type.
Returns
Component | null — The `Component` instance or null if not found.
getComponentAt(index) method

Retrieves Component at given index.

Parameters
index : number — Index of component.
Returns
Component | null
onUpdate() method
Called at every engine update. The execution order of onFixedUpdate, onUpdate and onPostUpdate is
going from top to bottom of the display list.
onCollectRenderables(driver, parentRenderer, isBackBufferActive) method

Called every time GameObject has to be rendered. Doesn't render itself. Collects render data to be processed by
video driver after.

NOTE: Adding, removing or changing children elements inside onRender method can lead to unexpected behavior.

Parameters
driver : VideoNullDriver — Current registered video driver.
parentRenderer : Renderer — Renderer of parent GameObject if there is one.
isBackBufferActive : boolean — Specifies if render to backBuffer.
Returns
Renderer
onGetLocalBounds(outRect) method

Override this method if you need to specify GameObject size. Should be always be a local coordinates.

Parameters
outRect : Rectangle — Rectangle to be returned.
Returns
Rectangle — bounds in local space without taking care about transformation matrix
getBounds(space, includeChildren, outRect) method

Returns world bounds of this object and all children if specified (true by default).

object.getBounds() - relative to parent (default).

object.getBounds(object) - local bounds.

object.getBounds(object.parent) - relative to parent.

object.getBounds(objectB) - relative to objectB space.


Parameters
space : GameObject — The GameObject relative to.
includeChildren : boolean — Specifies if include children in calculations.
outRect : Rectangle — Rectangle to be returned.
Returns
Rectangle — Returns bounds of the object with/without all children.
getStageBounds(outRect) method

Returns stage relative bounds of this object excluding it's children;

Parameters
outRect : Rectangle — Rectangle to be store resulting bounds in.
Returns
Rectangle
hitTest(localPoint) method

Evaluates whether the game object or one of its children intersects with the given point

Parameters
localPoint : Vector — Coordinates vector.
Returns
GameObject | null
setTransform(x, y, r, scaleX, scaleY, anchorX, anchorY, includeChildren) method

Sets the object transform in one line.

Parameters
x : number — Cord X.
y : number — Cord Y.
r : number — Rotation.
scaleX : number — Scale X.
scaleY : number — Scale Y.
anchorX : number — Anchor X.
anchorY : number — Anchor Y.
includeChildren : boolean — Include children when adjusting pivot?
Returns
GameObject — This.
relativeTo(gameObject, outVector) method

Calculates GameObject's position relative to another GameObject.

Parameters
gameObject : GameObject — Coordinates vector.
outVector : Vector | null — Vector to be returned.
Returns
Vector
localToGlobal(localPoint, outVector) method

Calculate global position of the object.

Parameters
localPoint : Vector — Coordinates vector.
outVector : Vector | null — Vector to be returned.
Returns
Vector
globalToLocal(globalPoint, outVector) method

Calculate local position of the object

Parameters
globalPoint : Vector — Coordinates vector.
outVector : Vector | null — Vector to be returned.
Returns
Vector
alignAnchor(ax, ay) method

Sets the origin point relatively to its bounds. For example, setting x and y value to 0.5 will set origin to the
center of the object.

Parameters
ax : number — Align along x-axis.
ay : number — Align along y-axis.
Returns
GameObject — This.
alignPivot(ax, ay) method

Sets anchor point to given position. See alignPivotOffset.

Parameters
ax : number — Align along x-axis.
ay : number — Align along y-axis.
Returns
GameObject — This.
alignPivotOffset(ax, ay, includeChildren) method

Sets the origin point offset from current anchor value. For example, setting anchor-x value to 0.5 and pivotOffsetX
to 10 will center object by x-axis and will shift object to the left by 10 pixels from half of the width.

Parameters
ax : number — Align along x-axis.
ay : number — Align along y-axis.
includeChildren : boolean — Include children elements when calculating bounds?
Returns
GameObject — This.
spawn(gen, ctx) method

Starts coroutine.

Parameters
gen : function — Generator function.
ctx : * — Context for Generator function.
Returns
*
wait(seconds) method

Waits for given amount of seconds before processing.

Parameters
seconds : number — Duration
Returns
function
waitMessage(message) method

Waits for a specific message.

Parameters
message : string — The name of the message to wait for.
Returns
function
setDirty(flag, includeChildren) method

Marks this GameObject and/or its children elements as dirty.

Parameters
flag : DirtyFlag — The flag or flag bit mask.
includeChildren : boolean — Specifies if the flag needed for all children.
Returns
void
setParentDirty(flag) method

Marks the GameObject's parent as dirty.

Parameters
flag : DirtyFlag — The flag or flag bit mask.
Returns
void
setTransformDirty() method
Marks this GameObject as Local dirty and all children elements as World dirty.
setRenderDirty() method
Marks this GameObject with Render dirty flag if it is not suspended for dirty.
intersects(gameObject, point) static method

Returns whenever a given GameObject intersects with a point.

Parameters
gameObject : GameObject — GameObject to test.
point : Vector — A point to test.
Returns
boolean — True if intersects.
intersectsAt(gameObject, point, outVector) static method

Returns a point where intersection were made in local space.

Parameters
gameObject : GameObject — GameObject to test intersection with.
point : Vector — The point to test.
outVector : Vector — If passed point of intersection will be stored in it.
Returns
boolean — True if intersects.
intersectsWith(gameObject, point) static method

Checks if GameObject or any of its children elements intersects the given point.

Parameters
gameObject : GameObject — GameObject to test.
point : Vector — Point to test.
Returns
GameObject | null — Intersecting object or null.
findWithTag(tag) static method

Returns all GameObject with given tag.

Parameters
tag : string — Tag to find.
Returns
Array. | null — Array of GameObject or null if not found.
findComponents(gameObject, type) static method

Returns a list of Components.

Parameters
gameObject : GameObject — GameObject to start search from.
type : function — Type of Component.
Returns
Array. — Array of Component or empty array.
forEach(gameObject, action) static method

Runs action across all GameObjects.

Parameters
gameObject : GameObject — GameObject to start iteration from.
action : function — The function to be executed on every GameObject.
Returns
void
find(name, node) static method

Finds object by its name. If node is not passed the root will be taken as
starting point.

Parameters
name : string — Name to search.
node : GameObject — Starting GameObject.
Returns
GameObject — GameObject or null.
findById(id, node) static method

Finds object by its id property. If node is not passed the root will be taken as
starting point.

Parameters
id : number — Id to search.
node : GameObject — Starting GameObject or null.
Returns
GameObject — GameObject or null.

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

id : number property
Returns unique object id.
numComponents : number property
Returns number of component's of this GameObject.
localTransformation : Matrix property
Returns local transformation Matrix
worldTransformation : Matrix property
Gets/Sets cloned Matrix object which represents object orientation in world space.
worldTransformationInverted : Matrix property
Returns cloned and inverted Matrix object which represents object orientation in world space
localBounds property
Returns local bounds of this object (without children).
bounds property
Returns parent-relative bounds (including children).
numChildren : number property
Gets a count of children elements.
name : string | null property
Gets/Sets the name of this GameObject instance.
x : number property
Gets/Sets the x coordinate of the GameObject instance relative to the local coordinates of the parent GameObject.
y : number property
Gets/Sets the y coordinate of the GameObject instance relative to the local coordinates of the parent GameObject.
pivotOffsetX : number property
Gets/Sets the x coordinate of the object's origin in its local space in pixels.
pivotOffsetY : number property
Gets/Sets the y coordinate of the object's origin in its local space in pixels.
anchorX : number property
Returns current anchor-x value in range from 0 to 1.
anchorY : number property
Returns current anchor-y value in range from 0 to 1.
pivotX : number property
Returns current pivot-x value in range from 0 to 1.
pivotY : number property
Returns current pivot-y value in range from 0 to 1.
scaleX : number property
Gets/Sets the scale factor of this object along x-axis.
scaleY : number property
Gets/Sets the scale factor of this object along y-axis.
scale : number property
Gets/sets both scaleX and scaleY. Getter will return scaleX value;
skewX : number property
Gets/sets horizontal skew angle in radians.
skewY : number property
Gets/sets vertical skew angle in radians.
rotation : number property
Gets/Sets rotation in radians.
parent : GameObject | null property
Returns this GameObject parent GameObject or null.
root : GameObject property
Returns top most parent object or this if there is no parents.
width : number property
Gets/sets the width of this object.
height : number property
Gets/sets the height of this object.
localWidth : number property
Returns width of this GameObject in local space without including children
elements.
localHeight : number property
Returns height of this GameObject in local space without including children
elements.
tag : string | null property
Gets/Sets tag of this GameObject.
touchable : boolean property
Gets/Sets whether the object will listen for user input messages.

Inherited Properties

stage : Stage | null inherited property
Returns the stage Game Object to which this belongs to or null if not added onto stage.
path : string | null inherited property
Returns string representing a url like path to this object in the display
tree.