Module io

This package contains classes for serializing and deserializing the entities in an Ash game. This lets you save the entire game state by serializing all the entities in the engine, and restore the game by deserializing them again.

Installation

npm i @ash.ts/tools

Documentation

TypeDoc generated API docs

Examples

The basics

import { JsonEngineCodec } from '@ash.ts/io';
import { Position, Display, Health } from '../components';

const classMap = { Position, Display, Health };

const codec = new JsonEngineCodec(classMap);
const serialized = codec.encodeEngine(engine);
LocalStorage.setItem('game-state', serialized);
Copy

import { Engine } from '@ash.ts/core';
import { JsonEngineCodec } from '@ash.ts/io';
import { Position, Display, Health } from '../components';

const classMap = { Position, Display, Health };

const codec = new JsonEngineCodec(classMap);
const serialized = LocalStorage.getItem('game-state');
const engine:Engine = new Engine();
codec.decodeEngine(serialized, engine);
Copy

Custom codecs

import { JsonEngineCodec } from '@ash.ts/io';

const codec = new JsonEngineCodec(classMap);
const animationCodec = new AnimationObjectCodec();
codec.addCustomCodec(animationCodec, Animation);
const serialized = codec.encodeEngine(engine);
LocalStorage.setItem('game-state', serialized);
Copy

import { Engine } from '@ash.ts/core';
import { JsonEngineCodec } from '@ash.ts/io';

const codec = new JsonEngineCodec(classMap);
const animationCodec = new AnimationObjectCodec();
codec.addCustomCodec(animationCodec, Animation);
const serialized = LocalStorage.getItem('game-state');
const engine = new Engine();
codec.decodeEngine(serialized, engine);
Copy

This lets you write custom code to handle complex objects that the core code provided can't handle.

Overlaying the save

import { JsonEngineCodec } from '@ash.ts/io';

const codec = new JsonEngineCodec(classMap);
const serialized = codec.encodeEngine(engine);
LocalStorage.setItem('game-state', serialized);
Copy

import { JsonEngineCodec } from '@ash.ts/io';

const codec = new JsonEngineCodec(classMap);
const serialized = LocalStorage.getItem('game-state');
codec.decodeOverEngine(serialized, engine);
Copy

This will replace data in the engine with the saved data, and leave untouched any data that exists in the engine but not in the save. This lets you ignore complex objects that don't change, like animations, but store the simple data that does change, like the name of the current running animation and what frame it is on.

The Engine Codecs

There are two levels to the serialization/deserialization. At the top level is the engine codecs. These can be found in the enginecodecs package. There are two codecs in this package, the JsonEngineCodec encodes and decodes the engine as a Json string, and the ObjectEngineCodec encodes and decodes the engine as an anonymous object, which could be further serialized into another format.

An engine codec implements the EngineCodec interface, and has four methods and two properties. If you wish to write your own engine codecs to serialize in a form other than Json, you should implement this interface. The methods in the interface are

function encodeEngine(engine:Engine):any;
Copy

To encode the entities in an engine. The returned object is the encoded data.

function decodeEngine(encodedData:EncodedData, engine:Engine):void;
Copy

To decode the entities back into the provided engine.

function decodeOverEngine(encodedData:any, engine:Engine):void;
Copy

To decode the entities over the top of the entities already in the provided engine. Entities in the decoded data are matched to entities already in the engine based on their names, and components are then matched based on their type. Where a matching entity and component are found, non-null properties in the decoded data are applied to the existing component in the entity. If no matching component is found a new component is created. When no matching entity is found a new entity is created. This lets you save only part of the engine state and restore it later.

function addCustomCodec(codec:ObjectCodec, ...types):void;
Copy

Adds a custom ObjectCodec to the EngineCodec for encoding/decoding objects of a specific type. See the section on the Object Codecs for more info.

The Object Codecs

The object codecs are in the objectcodecs package. Object codecs convert objects of particular types to/from an anonymous object form. Object codecs are used by engine codecs to encode/decode each specific object.

An object codec implements the ObjectCodec interface, and has four methods.

function encode(object:T, codecManager:CodecManager):EncodedObject;
Copy

To encode from one of the types handled by the codec into an anonymous object.

function decode(object:EncodedObject, codecManager:CodecManager):T;
Copy

To decode from an anonymous object into the type handled by the codec.

function decodeIntoObject(target:T, object:EncodedObject, codecManager:CodecManager):void;
Copy

To decode from an anonymous object into the given target object of a type handled by the codec. This is used when overlaying a saved game state over the current game state.

function decodeIntoProperty(parent:any, property:string, object:EncodedObject, codecManager:CodecManager):void;
Copy

To decode from an anonymous object into the given property of another object. This is used when overlaying a saved game state over the current game state.

Included object codecs

There are four ObjectCodecs included.

• NativeObjectCodec handles types number, string and boolean.
• ArrayObjectCodec handles typee Array.
• ClassObjectCodec handles objects of type Class.
• ReflectionObjectCodec uses reflection to handle any property types. By default, it handles all components in the engine but does not handle any properties of those components. You can add it as a handler for more object types using the EngineCodec's addCustomCodec method.

With these four ObjectCodecs, the EngineCodecs can save and restore all components and all properties of those components that are of type number, string, boolean, Class, and Arrays of these types. This is the default behaviour and requires no configuration. If you want to save and restore other more complex types you need to make a custom ObjectCodec for each of those types and add it to the EngineCodec using its addCustomCodec method.