About Game State

kheljs provides a set of utilties and classes to manage the state of a game without enforcing a rigid structure for the data related to game state. Basically, the state of the game is stored in a global object of type GameState. The GameState object, in turn, contains a list of LevelState objects, one for each level of the game. Both GameState and LevelState objects can store any data that is serializable as json objects.

When the game starts, a global GameState object is created and the content of the the object is initialized from a persistent store if it was saved earlier. When game components modify the content of the GameState or LevelState, the state is saved transparently to the persistent store. Developer can also save the entire game state or a level state at any point in the game by calling appropriate methods.

The kheljs framework stores a variety of information in the game state object like current level of the game, start time of the game, player position, the list of inventory items acquired by player, the list of inventory items in the game level etc. Developers can store additional data in the state object to be persisted for later use.

Organization of data in GameState and LevelState

Both GameState and LevelState can be thought as a key/value store where any serializable data can be placed. If you want to store an object as a value, make sure the object is provided as a plain javascript object. GameState and LevelState can't store type information of your objects - that is, everything is stored as plain javascript objects.

Reading and modifying data in GameState and LevelState

Since GameState and LevelState are global data structures, you can get hold of these data structures from anywhere in the program. The following example shows how to get hold of the GameState and LevelState objects, read them or modify them. Normally, you don't have to access the game state or the level state objects from your program. You just modify and access data structures in your program and, they are transparently saved by the framework.

import { store } from "@kheljs/core/store"

let gameState = store.getGameState();
console.log( "Current level:" + gameState.getCurrentLevel() );
console.log( "Game Start Time:" + gameState.getStartTime() );
console.log( "Last Modified:" + gameState.getLastModified() );
console.log( "Current user:" ) + gameState.getKeyValue( "user" );

let levelState = gameState.getCurrentLevelState()
console.log( "Level Start Time:" + levelState.getStartTime() );
console.log( "Last Modified:" + levelState.getLastModified() );
console.log( "Level score:" + levelState.getKeyValue("score") );

Persistent storage for game state

By default, game state is stored in browser's local storage but, you can pass an IStoragePlugin interface during initialization of the game to specify how data is stored and retrieved.

You don't have to save game state always necessarily. You can initialize the game level with a NullStoragePlugin to bypass storing or retrieving of data from any persistent storage. In that case, GameState will remain in the memory during the game but will be lost as soon as the user quits the game.