Kiwi.State Class
A State in Kiwi.JS is the main class that developers use when wanting to create a Game. States in Kiwi are used keep different sections of a game seperated. So a single game maybe comprised of many different States. Such as one for the menu, in-game, leaderboard, e.t.c. There can only ever be a single State active at a given time.
Constructor
Kiwi.State
-
name
Parameters:
-
name
StringName of this State. Should be unique to differentiate itself from other States.
Returns:
Item Index
Methods
- _destroyChildren
- addAudio
- addChild
- addChildAfter
- addChildAt
- addChildBefore
- addImage
- addJSON
- addSpriteSheet
- addTag
- addTextureAtlas
- addToTrackingList
- boot
- callAll
- childType
- clear
- contains
- containsAncestor
- containsDescendant
- countDead
- countLiving
- create
- destroy
- destroyUnused
- forEach
- forEachAlive
- getAllChildren
- getChildAt
- getChildByID
- getChildByName
- getChildIndex
- getChildrenByTag
- getFirstAlive deprecated
- getFirstChildByTag
- getFirstDead deprecated
- getLastChildByTag
- hasTag
- init
- loadComplete
- loadProgress
- loadUpdate
- numChildren
- objType
- postRender
- postUpdate
- preload
- preUpdate
- removeChild
- removeChildAt
- removeChildren
- removeFirstAlive deprecated
- removeFromTrackingList
- removeTag
- render deprecated
- replaceChild
- setAll
- setChildIndex
- shutDown
- swapChildren
- swapChildrenAt
- update
Properties
- _active
- _destroyRemoveChildren
- _dirty
- _parent
- _tags
- _visible
- _willRender deprecated
- active
- anchorPointX
- anchorPointY
- audio
- audioLibrary
- components
- config
- data
- dataLibrary
- dirty
- exists
- game
- id
- members
- name
- parent
- rotPointX
- rotPointY
- scale
- state
- textureLibrary
- textures
- trackingList
- transform
- visible
- willRender deprecated
- worldX
- worldY
- x
- y
Methods
_destroyChildren
-
child
Recursively goes through a child given and runs the destroy method on all that are passed.
Parameters:
-
child
Object
addAudio
-
key
-
url
-
[storeAsGlobal=true]
Adds a new audio file that is to be loaded when the state gets up to the stage of loading the assets.
Parameters:
-
key
StringA key for this audio so that you can access it when the loading has finished
-
url
StringThe location of the audio file. You can pass a array of urls, in which case the first supported filetype will be used.
-
[storeAsGlobal=true]
Boolean optionalIf the audio should be deleted when switching to another state or if the other states should still be able to access this audio.
addChild
-
child
Adds an Entity to this Group. The Entity must not already be in this Group.
Parameters:
-
child
ObjectThe child to be added.
Returns:
The child that was added.
addChildAfter
-
child
-
beforeChild
Adds an Entity to this Group after another child.
Parameters:
-
child
ObjectThe child to be added.
-
beforeChild
ObjectThe child after which the child will be added.
Returns:
The child.
addChildAt
-
child
-
index
Adds an Entity to this Group in the specific location. The Entity must not already be in this Group and it must be supported by the Group.
Parameters:
-
child
ObjectThe child to be added.
-
index
NumberThe index the child will be set at.
Returns:
The child.
addChildBefore
-
child
-
beforeChild
Adds an Entity to this Group before another child.
Parameters:
-
child
ObjectThe child to be added.
-
beforeChild
EntityThe child before which the child will be added.
Returns:
The child.
addImage
-
key
-
url
-
[storeAsGlobal=true]
-
[width]
-
[height]
-
[offsetX]
-
[offsetY]
Adds a new image file that is be loaded when the state gets up to the loading all of the assets.
Parameters:
-
key
StringA key for this image so that you can access it when the loading has finished.
-
url
StringThe location of the image.
-
[storeAsGlobal=true]
Boolean optionalIf the image should be deleted when switching to another state or if the other states should still be able to access this image.
-
[width]
Number optionalThe width of the image. If not passed the width will be automatically calculated.
-
[height]
Number optionalThe height of the image. If not passed the height will be automatically calculated.
-
[offsetX]
Number optionalThe offset of the image when rendering on the x axis.
-
[offsetY]
Number optionalThe offset of the image when rendering on the y axis.
addJSON
-
key
-
url
-
[storeAsGlobal=true]
Adds a json file that is to be loaded when the state gets up to the stage of loading the assets.
Parameters:
-
key
StringA key for this json so that you can access it when the loading has finished
-
url
StringThe location of the JSON file.
-
[storeAsGlobal=true]
Boolean optionalIf the json should be deleted when switching to another state or if the other states should still be able to access this json.
addSpriteSheet
-
key
-
url
-
frameWidth
-
frameHeight
-
[storeAsGlobal=true]
-
[numCells]
-
[rows]
-
[cols]
-
[sheetOffsetX=0]
-
[sheetOffsetY=0]
-
[cellOffsetX=0]
-
[cellOffsetY=0]
Adds a new spritesheet image file that is be loaded when the state gets up to the loading all of the assets.
Parameters:
-
key
StringA key for this image so that you can access it when the loading has finished.
-
url
StringThe location of the image.
-
frameWidth
NumberThe width of a single frame in the spritesheet
-
frameHeight
NumberThe height of a single frame in the spritesheet
-
[storeAsGlobal=true]
Boolean optionalIf the image should be deleted when switching to another state or if the other states should still be able to access this image.
-
[numCells]
Number optionalThe number of cells/frames that are in the spritesheet. If not specified will calculate this based of the width/height of the image.
-
[rows]
Number optionalThe number of cells that are in a row. If not specified will calculate this based of the width/height of the image.
-
[cols]
Number optionalThe number of cells that are in a column. If not specified will calculate this based of the width/height of the image.
-
[sheetOffsetX=0]
Number optionalThe offset of the whole spritesheet on the x axis.
-
[sheetOffsetY=0]
Number optionalThe offset of the whole spritesheet on the y axis.
-
[cellOffsetX=0]
Number optionalThe spacing between cells on the x axis.
-
[cellOffsetY=0]
Number optionalThe spacing between cells on the y axis.
addTag
-
tag
Adds a new Tag to this Entity. Useful for identifying large amounts of the same type of GameObjects. You can pass multiple strings to add multiple tags.
Parameters:
-
tag
StringThe tag that you would like to add to this Entity.
addTextureAtlas
-
key
-
imageURL
-
[jsonID]
-
[jsonURL]
-
[storeAsGlobal=true]
Adds a new texture atlas that is to be loaded when the states gets up to the stage of loading the assets.
Parameters:
-
key
StringA key for this image so that you can access it when the loading has finished.
-
imageURL
StringThe location of the image.
-
[jsonID]
String optionalThe id for the json file that is to be loaded. So that you can access it outside of the texture atlas.
-
[jsonURL]
String optionalThe location of the json file you have loaded.
-
[storeAsGlobal=true]
Boolean optionalIf the image should be delete when switching to another state or if the other states should still be able to access this image.
addToTrackingList
-
child
Adds a new Objects to the tracking list. This is an INTERNAL Kiwi method and DEVS shouldn't need to worry about it.
Parameters:
-
child
ObjectThe Object which you are adding to the tracking list.
boot
()
public
This method is executed when this State is about to be switched too. This is the first method to be executed, and happens before the Init method. Is called each time a State is switched to.
callAll
-
componentName
-
functionName
-
args
Calls a function on every member. If componentName is null the function is called on the entity itself, otherwise it is called on the named component. Uses runtime string property lookups. Not optimal for large groups if speed is an issue.
Parameters:
-
componentName
StringThe name of the component to call the function on - set to null to call a function on the entity.
-
functionName
StringThe name of the function to call.
-
args
ArrayAn array of arguments to pas to the function.
childType
()
Number
public
Returns the type of child this is.
Returns:
Kiwi.GROUP
clear
()
public
Clear all children from this Group
contains
-
child
Checks if the given entity is in this group
Parameters:
-
child
IChildThe IChild that you want to checked.
Returns:
true if entity exists in group.
containsAncestor
-
descendant
-
ancestor
Checks to see if one child is an ansector of another child.
Parameters:
-
descendant
ObjectThe object that you are checking.
-
ancestor
GroupThe parent (ancestor) that you are checking for.
Returns:
containsDescendant
-
child
Checks to see if the given object is contained in this group as a descendant
Parameters:
-
child
ObjectThe IChild that you want to check.
Returns:
countDead
()
Number
public
Returns the number of member which are not marked as 'alive'
Returns:
countLiving
()
Number
public
Returns the number of member which are marked as 'alive'
Returns:
create
-
[values]
Is executed once all of the assets have loaded and the game is ready to be 'created'.
Parameters:
-
[values]
Any optional multiple
destroy
-
[deleteAll=true]
Used to mark all Entities that have been created for deletion, regardless of it they are on the stage or not.
Parameters:
-
[deleteAll=true]
Object optionalIf all of the Objects ever created should have the destroy method executed also.
destroyUnused
()
Number
public
Destroys all of Objects in the tracking list that are not currently on stage. All that currently don't have this STATE as an ancestor. Returns the number of Objects removed.
Returns:
The amount of objects removed.
forEach
-
context
-
callback
-
[params]
Loops through each member in the group and run a method on for each one.
Parameters:
-
context
AnyThe context that the callbacks are to have when called.
-
callback
AnyThe callback method to execute on each member.
-
[params]
Any optional multipleAny extra parameters.
forEachAlive
-
context
-
callback
-
[params]
Loop through each member of the groups that is alive.
Parameters:
-
context
AnyThe context that the callbacks are to have when called.
-
callback
AnyThe callback method to execute on each member.
-
[params]
Any optional multipleAny extra parameters.
getAllChildren
-
getGroups
-
destinationArray
Get all children of this Group. By default, this will search the entire sub-graph, including children of children etc.
Parameters:
-
getGroups
BooleanOptional: Whether to include Groups in the results. When false, will only collect GameObjects.
-
destinationArray
ArrayOptional: The array in which to store the results.
Returns:
getChildAt
-
index
Get the child at a specific position in this Group by its index.
Parameters:
-
index
NumberThe index of the child
Returns:
The child, if found or null if not.
getChildByID
-
id
-
recurse
Get a child from this Group by its UUID. By default this will not check sub-groups, but if you supply the correct flag it will check the entire scene graph under this object.
Parameters:
-
id
StringThe ID of the child.
-
recurse
BooleanWhether to search child groups for the child. Default FALSE.
Returns:
The child, if found or null if not.
getChildByName
-
name
-
recurse
Get a child from this Group by its name. By default this will not check sub-groups, but if you supply the correct flag it will check the entire scene graph under this object.
Parameters:
-
name
StringThe name of the child.
-
recurse
BooleanWhether to search child groups for the child. Default FALSE.
Returns:
The child, if found or null if not.
getChildIndex
-
child
Returns the index position of the Entity or -1 if not found.
Parameters:
-
child
ObjectThe child.
Returns:
The index of the child or -1 if not found.
getChildrenByTag
-
tag
Returns an array of children which contain the tag which is passed.
Parameters:
-
tag
String
Returns:
getFirstAlive
()
Object
deprecated
public
Returns the first Entity from this Group marked as 'alive' or null if no members are alive
Returns:
getFirstChildByTag
-
tag
Returns the first child which contains the tag passed.
Parameters:
-
tag
String
Returns:
getFirstDead
()
Object
deprecated
public
Returns the first member of the Group which is not 'alive', returns null if all members are alive.
Returns:
getLastChildByTag
-
tag
Returns the last child which contains the tag passed.
Parameters:
-
tag
String
Returns:
hasTag
-
tag
Checks to see if this Entity has a Tag based upon a string which you pass.
Parameters:
-
tag
String
Returns:
init
-
[values]
Gets executed when the state has been initalised and gets switched to for the first time. This method only ever gets called once and it is before the preload method. Can have parameters passed to it by the previous state that switched to it.
Parameters:
-
[values]
Any optional
loadComplete
()
public
Gets executed when the game is finished loading and it is about to 'create' the state.
loadProgress
-
percent
-
bytesLoaded
-
file
This method is progressively called whilst loading files and is executed each time a file has been loaded. This can be used to create a 'progress' bar during the loading stage of a game.
Parameters:
-
percent
NumberThe percent of files that have been loaded so far. This is a number from 0 - 1.
-
bytesLoaded
NumberThe number of bytes that have been loaded so far.
-
file
Kiwi.Files.FileThe last file to have been loaded.
loadUpdate
()
public
The game loop that gets executed while the game is loading.
numChildren
()
Number
public
Returns the total number of children in this Group. Doesn't distinguish between alive and dead children.
Returns:
The number of children in this Group
objType
()
String
public
Returns the type of object this state is.
Returns:
"State"
postRender
()
public
Called after all of the layers have rendered themselves, useful for debugging.
postUpdate
()
public
The post update loop is executed every frame after the update method. When overriding make sure you include a super call at the end of the method.
preload
()
public
This method is where you would load of all the assets that are requried for this state or in the entire game.
preUpdate
()
public
Is called every frame before the update loop. When overriding make sure you include a super call.
removeChild
-
child
-
[destroy=false]
Removes an Entity from this Group if it is a child of it.
Parameters:
-
child
ObjectThe child to be removed.
-
[destroy=false]
Boolean optionalIf the entity that gets removed should be destroyed as well.
Returns:
The child.
removeChildAt
-
index
Removes the Entity from this Group at the given position.
Parameters:
-
index
NumberThe index of the child to be removed.
Returns:
The child, or null.
removeChildren
-
begin
-
end
-
destroy
Removes all Entities from this Group within the given range.
Parameters:
-
begin
NumberThe begining index.
-
end
NumberThe last index of the range.
-
destroy
NumberIf the children should be destroyed as well.
Returns:
The number of removed entities.
removeFirstAlive
-
[destroy=false]
Removes the first Entity from this Group marked as 'alive'
Parameters:
-
[destroy=false]
Boolean optionalIf the entity should run the destroy method when it is removed.
Returns:
The Entity that was removed from this Group if alive, otherwise null
removeFromTrackingList
-
child
Removes a Object from the tracking list. This should only need to happen when a child is being destroyed. This is an INTERNAL Kiwi method and DEVS shouldn't really need to worry about it.
Parameters:
-
child
ObjectThe object which is being removed from the tracking list.
removeTag
-
tag
Removes a Tag from this Entity.
Parameters:
-
tag
StringThe tag that you would like to remove from this Entity.
render
-
camera
The render method that is required by the IChild. This method never gets called as the render is only worried about rendering entities.
Parameters:
-
camera
Kiwi.Camera
replaceChild
-
oldChild
-
newChild
Replaces a child Entity in this Group with a new one.
Parameters:
-
oldChild
ObjectThe Entity in this Group to be removed.
-
newChild
ObjectThe new Entity to insert into this Group at the old Entities position.
Returns:
true if the Entities were replaced successfully, otherwise false.
setAll
-
componentName
-
property
-
value
Sets a property on every member. If componentName is null the property is set on the entity itself, otherwise it is set on the named component. Uses runtime string property lookups. Not optimal for large groups if speed is an issue.
Parameters:
-
componentName
StringThe name of the component to set the property on - set to null to set a property on the entity.
-
property
StringThe name of the property to set.
-
value
AnyThe value to set the property to.
setChildIndex
-
child
-
index
Sets a new position of an existing Entity within the Group.
Parameters:
-
child
ObjectThe child in this Group to change.
-
index
NumberThe index for the child to be set at.
Returns:
true if the Entity was moved to the new position, otherwise false.
shutDown
()
public
Called just before this State is going to be Shut Down and another one is going to be switched too.
swapChildren
-
child1
-
child2
Swaps the position of two existing Entities that are a direct child of this group.
Parameters:
-
child1
ObjectThe first child in this Group to swap.
-
child2
ObjectThe second child in this Group to swap.
Returns:
true if the Entities were swapped successfully, otherwise false.
swapChildrenAt
-
index1
-
index2
Swaps the position of two existing Entities within the Group based on their index.
Parameters:
-
index1
NumberThe position of the first Entity in this Group to swap.
-
index2
NumberThe position of the second Entity in this Group to swap.
Returns:
true if the Entities were swapped successfully, otherwise false.
update
()
public
The update loop that is executed every frame while the game is 'playing'. When overriding make sure you include a super call too.
Properties
_active
Boolean
private
An active Entity is one that has its update method called by its parent.
Default: true
_destroyRemoveChildren
Boolean
private
A temporary property that holds a boolean indicating whether or not the group's children should be destroyed or not.
_dirty
Boolean
private
An indication of whether or not this group is 'dirty' and thus needs to be re-rendered or not.
_visible
Boolean
private
A boolean that indicates whether or not this entity is visible or not. Note that is does not get set to false if the alpha is 0.
Default: true
_willRender
Boolean
deprecated
private
Controls whether render is automatically called by the parent.
active
Boolean
public
Toggles the active state of this Entity. An Entity that is active has its update method called by its parent. This method should be over-ridden to handle specific dom/canvas/webgl implementations.
Default: true
anchorPointX
Number
public
The anchor point offset of this group in the X axis. This is just aliased to the transform property, and is in turn an alias of rotPointX.
anchorPointY
Number
public
The anchor point offset of this group in the Y axis. This is just aliased to the transform property, and is in turn an alias of rotPointY.
audio
Object
public
Holds all of the audio that are avaiable to be accessed once this state has been loaded. E.g. If you loaded a piece of audio and named it 'lazerz', once everything has loaded you can then access the lazers (pew pew) by saying this.audio.lazerz
audioLibrary
Kiwi.Sound.AudioLibrary
public
The library that this state use's for the loading of audio.
data
Object
public
Holds all of the data that are avaiable to be accessed once this state has been loaded. E.g. If you loaded a piece of data and named it 'cookieLocation', once everything has loaded you can then access the cookies by saying this.data.cookieLocation
dataLibrary
Kiwi.Files.DataLibrary
public
The library that this state use's for the loading of data.
dirty
Boolean
public
Sets all children of the Group to be dirty.
exists
Boolean
private
If an Entity no longer exists it is cleared for garbage collection or pool re-allocation
id
String
public
A unique identifier for this Group within the game used internally by the framework. See the name property for a friendly version.
members
Array
public
The collection of children belonging to this group
name
String
public
A name for this Group. This is not checked for uniqueness within the Game, but is very useful for debugging.
Default: ''
parent
Kiwi.Group
public
Set's the parent of this entity. Note that this also sets the transforms parent of this entity to be the passed groups transform.
rotPointX
Number
public
The rotation offset of this group in the X axis. This is just aliased to the transform property.
rotPointY
Number
public
The rotation offset of this group in the Y axis. This is just aliased to the transform property.
scale
Number
public
The scale of this group. This is just aliased to the transform property. This is WRITE-ONLY.
textureLibrary
Kiwi.Textures.TextureLibrary
public
The library that this state use's for the loading of textures.
textures
Object
public
Holds all of the textures that are avaiable to be accessed once this state has been loaded. E.g. If you loaded a image and named it 'flower', once everything has loaded you can then access the flower image by saying this.textures.flower
trackingList
Array
private
Contains a reference to all of the Objects that have ever been created for this state. Generally Kiwi.Entities or Kiwi.Groups. Useful for keeping track of sprites that are not used any more and need to be destroyed.
transform
Kiwi.Geom.Transform
public
The transform object for this group. Transform handles the calculation of coordinates/rotation/scale e.t.c in the Game World.
visible
Boolean
public
Set the visibility of this entity. True or False.
Default: true
willRender
Boolean
deprecated
public
Controls whether render is automatically called by the parent.
worldX
Number
public
The X coordinate of this group in world space; that is, after parent transforms. This is just aliased to the transform property. This is READ-ONLY.
worldY
Number
public
The Y coordinate of this group in world space; that is, after parent transforms. This is just aliased to the transform property. This is READ-ONLY.
x
Number
public
The X coordinate of this group. This is just aliased to the transform property.
y
Number
public
The Y coordinate of this group. This is just aliased to the transform property.