API Docs for: 1.4.0
Show:

Kiwi.State Class

Extends Kiwi.Group
Defined in: src\core\State.ts:9
Module: Kiwi

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
)
Kiwi.State

Defined in src\core\State.ts:9

Parameters:

  • name String

    Name of this State. Should be unique to differentiate itself from other States.

Returns:

Methods

_destroyChildren

(
  • child
)
private

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 String

    A key for this audio so that you can access it when the loading has finished

  • url String

    The 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 optional

    If 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
)
Object public

Adds an Entity to this Group. The Entity must not already be in this Group.

Parameters:

  • child Object

    The child to be added.

Returns:

Object:

The child that was added.

addChildAfter

(
  • child
  • beforeChild
)
Object public

Adds an Entity to this Group after another child.

Parameters:

  • child Object

    The child to be added.

  • beforeChild Object

    The child after which the child will be added.

Returns:

Object:

The child.

addChildAt

(
  • child
  • index
)
Object public

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 Object

    The child to be added.

  • index Number

    The index the child will be set at.

Returns:

Object:

The child.

addChildBefore

(
  • child
  • beforeChild
)
Object public

Adds an Entity to this Group before another child.

Parameters:

  • child Object

    The child to be added.

  • beforeChild Entity

    The child before which the child will be added.

Returns:

Object:

The child.

addImage

(
  • key
  • url
  • [storeAsGlobal=true]
  • [width]
  • [height]
  • [offsetX]
  • [offsetY]
)
public

Adds a new image file that is be loaded when the state gets up to the loading all of the assets.

Parameters:

  • key String

    A key for this image so that you can access it when the loading has finished.

  • url String

    The location of the image.

  • [storeAsGlobal=true] Boolean optional

    If 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 optional

    The width of the image. If not passed the width will be automatically calculated.

  • [height] Number optional

    The height of the image. If not passed the height will be automatically calculated.

  • [offsetX] Number optional

    The offset of the image when rendering on the x axis.

  • [offsetY] Number optional

    The offset of the image when rendering on the y axis.

addJSON

(
  • key
  • url
  • [storeAsGlobal=true]
)
public

Adds a json file that is to be loaded when the state gets up to the stage of loading the assets.

Parameters:

  • key String

    A key for this json so that you can access it when the loading has finished

  • url String

    The location of the JSON file.

  • [storeAsGlobal=true] Boolean optional

    If 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]
)
public

Adds a new spritesheet image file that is be loaded when the state gets up to the loading all of the assets.

Parameters:

  • key String

    A key for this image so that you can access it when the loading has finished.

  • url String

    The location of the image.

  • frameWidth Number

    The width of a single frame in the spritesheet

  • frameHeight Number

    The height of a single frame in the spritesheet

  • [storeAsGlobal=true] Boolean optional

    If 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 optional

    The 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 optional

    The number of cells that are in a row. If not specified will calculate this based of the width/height of the image.

  • [cols] Number optional

    The 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 optional

    The offset of the whole spritesheet on the x axis.

  • [sheetOffsetY=0] Number optional

    The offset of the whole spritesheet on the y axis.

  • [cellOffsetX=0] Number optional

    The spacing between cells on the x axis.

  • [cellOffsetY=0] Number optional

    The spacing between cells on the y axis.

addTag

(
  • tag
)
public

Inherited from Kiwi.Group: src\core\Group.ts:1260

Available since 1.1.0

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 String

    The tag that you would like to add to this Entity.

addTextureAtlas

(
  • key
  • imageURL
  • [jsonID]
  • [jsonURL]
  • [storeAsGlobal=true]
)
public

Adds a new texture atlas that is to be loaded when the states gets up to the stage of loading the assets.

Parameters:

  • key String

    A key for this image so that you can access it when the loading has finished.

  • imageURL String

    The location of the image.

  • [jsonID] String optional

    The id for the json file that is to be loaded. So that you can access it outside of the texture atlas.

  • [jsonURL] String optional

    The location of the json file you have loaded.

  • [storeAsGlobal=true] Boolean optional

    If 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
)
public

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 Object

    The 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
)
public

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 String

    The name of the component to call the function on - set to null to call a function on the entity.

  • functionName String

    The name of the function to call.

  • args Array

    An array of arguments to pas to the function.

childType

() Number public

Returns the type of child this is.

Returns:

Number:

Kiwi.GROUP

clear

() public

Clear all children from this Group

contains

(
  • child
)
Boolean public

Checks if the given entity is in this group

Parameters:

  • child IChild

    The IChild that you want to checked.

Returns:

Boolean:

true if entity exists in group.

containsAncestor

(
  • descendant
  • ancestor
)
Boolean public

Checks to see if one child is an ansector of another child.

Parameters:

  • descendant Object

    The object that you are checking.

  • ancestor Group

    The parent (ancestor) that you are checking for.

Returns:

Boolean:

containsDescendant

(
  • child
)
Boolean public

Checks to see if the given object is contained in this group as a descendant

Parameters:

  • child Object

    The IChild that you want to check.

Returns:

Boolean:

countDead

() Number public

Returns the number of member which are not marked as 'alive'

Returns:

Number:

countLiving

() Number public

Returns the number of member which are marked as 'alive'

Returns:

Number:

create

(
  • [values]
)
public

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]
)
public

Inherited from Kiwi.Group but overwritten in src\core\State.ts:433

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 optional

    If 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:

Number:

The amount of objects removed.

forEach

(
  • context
  • callback
  • [params]
)
public

Loops through each member in the group and run a method on for each one.

Parameters:

  • context Any

    The context that the callbacks are to have when called.

  • callback Any

    The callback method to execute on each member.

  • [params] Any optional multiple

    Any extra parameters.

forEachAlive

(
  • context
  • callback
  • [params]
)
public

Loop through each member of the groups that is alive.

Parameters:

  • context Any

    The context that the callbacks are to have when called.

  • callback Any

    The callback method to execute on each member.

  • [params] Any optional multiple

    Any extra parameters.

getAllChildren

(
  • getGroups
  • destinationArray
)
Array

Inherited from Kiwi.Group: src\core\Group.ts:585

Available since 1.1.0

Get all children of this Group. By default, this will search the entire sub-graph, including children of children etc.

Parameters:

  • getGroups Boolean

    Optional: Whether to include Groups in the results. When false, will only collect GameObjects.

  • destinationArray Array

    Optional: The array in which to store the results.

Returns:

Array:

getChildAt

(
  • index
)
Object public

Get the child at a specific position in this Group by its index.

Parameters:

  • index Number

    The index of the child

Returns:

Object:

The child, if found or null if not.

getChildByID

(
  • id
  • recurse
)
Object public

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 String

    The ID of the child.

  • recurse Boolean

    Whether to search child groups for the child. Default FALSE.

Returns:

Object:

The child, if found or null if not.

getChildByName

(
  • name
  • recurse
)
Object public

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 String

    The name of the child.

  • recurse Boolean

    Whether to search child groups for the child. Default FALSE.

Returns:

Object:

The child, if found or null if not.

getChildIndex

(
  • child
)
Number public

Returns the index position of the Entity or -1 if not found.

Parameters:

  • child Object

    The child.

Returns:

Number:

The index of the child or -1 if not found.

getChildrenByTag

(
  • tag
)
Array public

Inherited from Kiwi.Group: src\core\Group.ts:776

Available since 1.1.0

Returns an array of children which contain the tag which is passed.

Parameters:

  • tag String

Returns:

Array:

getFirstAlive

() Object deprecated public

Inherited from Kiwi.Group: src\core\Group.ts:689

Deprecated: in v1.1.0

Returns the first Entity from this Group marked as 'alive' or null if no members are alive

Returns:

Object:

getFirstChildByTag

(
  • tag
)
IChild public

Inherited from Kiwi.Group: src\core\Group.ts:803

Available since 1.3.0

Returns the first child which contains the tag passed.

Parameters:

  • tag String

Returns:

IChild:

getFirstDead

() Object deprecated public

Inherited from Kiwi.Group: src\core\Group.ts:707

Deprecated: in v1.1.0

Returns the first member of the Group which is not 'alive', returns null if all members are alive.

Returns:

Object:

getLastChildByTag

(
  • tag
)
IChild public

Inherited from Kiwi.Group: src\core\Group.ts:832

Available since 1.3.0

Returns the last child which contains the tag passed.

Parameters:

  • tag String

Returns:

IChild:

hasTag

(
  • tag
)
Boolean public

Inherited from Kiwi.Group: src\core\Group.ts:1295

Available since 1.1.0

Checks to see if this Entity has a Tag based upon a string which you pass.

Parameters:

  • tag String

Returns:

Boolean:

init

(
  • [values]
)
public

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
)
public

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 Number

    The percent of files that have been loaded so far. This is a number from 0 - 1.

  • bytesLoaded Number

    The number of bytes that have been loaded so far.

  • file Kiwi.Files.File

    The 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:

Number:

The number of children in this Group

objType

() String public

Inherited from Kiwi.Group but overwritten in src\core\State.ts:33

Returns the type of object this state is.

Returns:

String:

"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]
)
Object public

Removes an Entity from this Group if it is a child of it.

Parameters:

  • child Object

    The child to be removed.

  • [destroy=false] Boolean optional

    If the entity that gets removed should be destroyed as well.

Returns:

Object:

The child.

removeChildAt

(
  • index
)
Object

Removes the Entity from this Group at the given position.

Parameters:

  • index Number

    The index of the child to be removed.

Returns:

Object:

The child, or null.

removeChildren

(
  • begin
  • end
  • destroy
)
Number public

Removes all Entities from this Group within the given range.

Parameters:

  • begin Number

    The begining index.

  • end Number

    The last index of the range.

  • destroy Number

    If the children should be destroyed as well.

Returns:

Number:

The number of removed entities.

removeFirstAlive

(
  • [destroy=false]
)
Object deprecated public

Inherited from Kiwi.Group: src\core\Group.ts:564

Deprecated: in v1.1.0

Removes the first Entity from this Group marked as 'alive'

Parameters:

  • [destroy=false] Boolean optional

    If the entity should run the destroy method when it is removed.

Returns:

Object:

The Entity that was removed from this Group if alive, otherwise null

removeFromTrackingList

(
  • child
)
public

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 Object

    The object which is being removed from the tracking list.

removeTag

(
  • tag
)
public

Inherited from Kiwi.Group: src\core\Group.ts:1279

Available since 1.1.0

Removes a Tag from this Entity.

Parameters:

  • tag String

    The tag that you would like to remove from this Entity.

render

(
  • camera
)
deprecated public

The render method that is required by the IChild. This method never gets called as the render is only worried about rendering entities.

Parameters:

replaceChild

(
  • oldChild
  • newChild
)
Boolean public

Replaces a child Entity in this Group with a new one.

Parameters:

  • oldChild Object

    The Entity in this Group to be removed.

  • newChild Object

    The new Entity to insert into this Group at the old Entities position.

Returns:

Boolean:

true if the Entities were replaced successfully, otherwise false.

setAll

(
  • componentName
  • property
  • value
)
public

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 String

    The name of the component to set the property on - set to null to set a property on the entity.

  • property String

    The name of the property to set.

  • value Any

    The value to set the property to.

setChildIndex

(
  • child
  • index
)
Boolean public

Sets a new position of an existing Entity within the Group.

Parameters:

  • child Object

    The child in this Group to change.

  • index Number

    The index for the child to be set at.

Returns:

Boolean:

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
)
Boolean public

Swaps the position of two existing Entities that are a direct child of this group.

Parameters:

  • child1 Object

    The first child in this Group to swap.

  • child2 Object

    The second child in this Group to swap.

Returns:

Boolean:

true if the Entities were swapped successfully, otherwise false.

swapChildrenAt

(
  • index1
  • index2
)
Boolean public

Swaps the position of two existing Entities within the Group based on their index.

Parameters:

  • index1 Number

    The position of the first Entity in this Group to swap.

  • index2 Number

    The position of the second Entity in this Group to swap.

Returns:

Boolean:

true if the Entities were swapped successfully, otherwise false.

update

() public

Inherited from Kiwi.Group but overwritten in src\core\State.ts:223

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.

_parent

Kiwi.Group private

The parent group of this group.

_tags

Array private

Inherited from Kiwi.Group: src\core\Group.ts:1250

Available since 1.1.0

Any tags that are on this Entity. This can be used to grab GameObjects or Groups on the whole game which have these particular tags. By default Entitys contain no tags.

_visible

Boolean private

Inherited from Kiwi.Group: src\core\Group.ts:1217

Available since 1.0.1

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

Inherited from Kiwi.Group: src\core\Group.ts:1193

Deprecated: Use _visible instead

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

Inherited from Kiwi.Group: src\core\Group.ts:234

Available since 1.1.0

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

Inherited from Kiwi.Group: src\core\Group.ts:248

Available since 1.1.0

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.

components

Kiwi.ComponentManager public

The Component Manager

config

Kiwi.StateConfig public

The configuration object for this State.

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

Inherited from Kiwi.Group but overwritten in src\core\Group.ts:1082

If an Entity no longer exists it is cleared for garbage collection or pool re-allocation

game

Kiwi.Game public

Inherited from Kiwi.Group but overwritten in src\core\State.ts:61

A reference to the Kiwi.Game that this State belongs to.

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

Inherited from Kiwi.Group: src\core\Group.ts:206

Available since 1.1.0

The rotation offset of this group in the X axis. This is just aliased to the transform property.

rotPointY

Number public

Inherited from Kiwi.Group: src\core\Group.ts:220

Available since 1.1.0

The rotation offset of this group in the Y axis. This is just aliased to the transform property.

scale

Number public

Inherited from Kiwi.Group: src\core\Group.ts:182

Available since 1.1.0

The scale of this group. This is just aliased to the transform property. This is WRITE-ONLY.

state

Kiwi.State public

The State that this Group belongs to

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

Inherited from Kiwi.Group: src\core\Group.ts:1227

Available since 1.0.1

Set the visibility of this entity. True or False.

Default: true

willRender

Boolean deprecated public

Inherited from Kiwi.Group: src\core\Group.ts:1202

Deprecated: Use visible instead

Controls whether render is automatically called by the parent.

worldX

Number public

Inherited from Kiwi.Group: src\core\Group.ts:134

Available since 1.1.0

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

Inherited from Kiwi.Group: src\core\Group.ts:145

Available since 1.1.0

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.