@strixit/storyscript 0.0.0-stage → 1.0.0

package/src/Engine/Services/DataSerializer.ts

@@ -0,0 +1,326 @@
+import {IDataSerializer, IFeature, parseFunction, serializeFunction} from 'storyScript';
+import {InitEntityCollection} from "src/Engine/EntityCreatorFunctions";
+import {StateProperties} from "src/Engine/stateProperties";
+import {SerializationData} from "./serializationData";
+import {getKeyPropertyNames, getPlural, isDataRecord} from "src/Engine/utilityFunctions";
+import {DescriptionProperty, IdProperty} from 'src/constants';
+
+export class DataSerializer implements IDataSerializer {
+    private conversationPropertiesToSerialize = [
+        'actions',
+        'startNode',
+        'singleRepliesChosen'
+    ]
+
+    constructor(private readonly _pristineEntities: Record<string, Record<string, any>>) {
+    }
+
+    createSerializableClone = (original: any): any => {
+        return this.buildStructureForSerialization(undefined, original, undefined);
+    }
+
+    restoreObjects = (
+        loaded: any
+    ): any => {
+        for (const key in loaded) {
+            if (!loaded.hasOwnProperty(key)) {
+                continue;
+            }
+
+            const value = loaded[key];
+
+            if (this.restoreArray(value, loaded, key)) {
+                continue;
+            }
+
+            if (typeof value === 'object') {
+                this.restoreObjects(value);
+            } else if (typeof value === 'string' && value.indexOf('function') > -1) {
+                loaded[key] = parseFunction(value);
+            }
+        }
+
+        return loaded;
+    }
+
+    private readonly buildStructureForSerialization = (clone: any, original: any, pristine: any, parentKey?: string): any => {
+        clone ??= this.createClone(original);
+
+        if (clone == original) {
+            return clone;
+        }
+
+        for (const key in original) {
+            if (!original.hasOwnProperty(key)) {
+                continue;
+            }
+
+            let originalValue = original[key];
+            let pristineValue: any;
+
+            if (original.type && original.id) {
+                pristine = this._pristineEntities[getPlural(original.type)]?.[original.id];
+            }
+
+            pristineValue = pristine?.[key];
+
+            // When we haven't found a pristine entity even though we checked the pristine collection,
+            // we may be dealing with an entity that is added as a feature, such as an item. These are
+            // not in the pristine features entities but in their own set. Try to find the pristine
+            // entity by checking the features of the pristine locations.
+            if (!pristineValue && original.type && original.id) {
+                let feature: IFeature;
+
+                for (const location in this._pristineEntities.locations) {
+                    feature = this._pristineEntities.locations[location].features?.find(f => f.id === original.id);
+
+                    if (feature) {
+                        pristineValue = feature[key];
+                        break;
+                    }
+                }
+            }
+
+            // Do add NULL values to the clone for equipment, as these can be used as placeholders.
+            // This is used by the engine to determine which equipment slots are available.
+            if (originalValue === null) {
+                if (parentKey === 'equipment') {
+                    clone[key] = null;
+                }
+
+                continue;
+            }
+
+            if (this.skipProperty(original, originalValue, key, parentKey)) {
+                continue;
+            }
+
+            let newValue = this.processArrayDeletedValuesAndProperties(originalValue);
+
+            this.getClonedValue({
+                clone: clone,
+                key: key,
+                original: original,
+                originalValue: newValue,
+                pristine: pristine,
+                pristineValue: pristineValue
+            });
+        }
+
+        return clone;
+    }
+
+    private processArrayDeletedValuesAndProperties(originalValue: any,): any {
+        let newValue: any = originalValue;
+
+        // Add deleted entries to the array. Create a new array for this to prevent changing
+        // the one used at runtime. Also copy over additional properties that may be there,
+        // except for the array of deleted entities. This is handled differently.
+        if (Array.isArray(originalValue)) {
+            const deletedEntries = originalValue.getDeleted();
+            newValue = [...originalValue];
+            deletedEntries.forEach(e => newValue.push(e));
+            const additionalProperties = Object.keys(originalValue).filter(k => k !== '_deleted' && !newValue[k]);
+            additionalProperties.forEach(p => {
+                newValue[p] = originalValue[p];
+            });
+        }
+
+        return newValue;
+    }
+
+    private readonly restoreArray = (value: any, loaded: any, key: string): boolean => {
+        if (!Array.isArray(value)) {
+            return false;
+        }
+
+        InitEntityCollection(loaded, key);
+        this.restoreObjects(value);
+        const entriesToDelete = value.filter(e => e?.[StateProperties.Deleted]);
+
+        entriesToDelete.forEach(e => {
+            value.delete(e);
+        });
+
+        const arrayPropertyKey = `${key}_arrProps`;
+        const additionalArrayProperties = loaded[arrayPropertyKey];
+
+        if (additionalArrayProperties) {
+            Object.keys(additionalArrayProperties).forEach(k => {
+                // Use a cast to any to suppress the warning that named properties should be used
+                // with objects and numeric indexes with arrays.
+                (<any>value)[k] = additionalArrayProperties[k];
+            });
+
+            delete loaded[arrayPropertyKey];
+        }
+
+        return true;
+    }
+
+    private readonly createClone = (values: any): any => {
+        let clone: any;
+
+        if (Array.isArray(values)) {
+            clone = [];
+        } else {
+            clone = typeof values === 'object' ? {} : values;
+        }
+
+        return clone;
+    }
+
+    private readonly getClonedValue = (data: SerializationData): void => {
+        if (this.processDataRecord(data)) {
+            return;
+        }
+
+        if (this.processArray(data)) {
+            return;
+        }
+
+        if (typeof data.originalValue === 'object') {
+            if (Array.isArray(data.clone)) {
+                data.clone.push({});
+            } else {
+                data.clone[data.key] = {};
+            }
+
+            const createdObject = data.clone[data.key];
+            this.buildStructureForSerialization(createdObject, data.originalValue, data.pristineValue, data.key);
+
+            // Do not include empty objects in the serialized data.
+            if (!Array.isArray(data.clone) && typeof (createdObject) === 'object' && Object.keys(createdObject).length === 0) {
+                delete data.clone[data.key];
+            }
+
+            return;
+        }
+
+        if (typeof data.originalValue === 'function') {
+            if (!data.originalValue.isProxy && data.originalValue.toString() !== data.pristineValue?.toString()) {
+                data.clone[data.key] = serializeFunction(data.originalValue);
+            }
+            return;
+        }
+
+        // Store only values that are different from the pristine value, values that are needed to create a
+        // traversable world structure, and the key values of deleted array records.
+        if (data.originalValue != data.pristineValue || this.isKeyProperty(data.pristine, data.key) || data.original[StateProperties.Deleted] === true) {
+            data.clone[data.key] = data.originalValue;
+        }
+    }
+
+    private readonly processDataRecord = (data: SerializationData): boolean => {
+        if (!isDataRecord(data.originalValue)) {
+            return false;
+        }
+
+        data.clone[data.key] = [];
+        const record = data.clone[data.key];
+        const match = data.pristine?.find((p: any[]) => p[0] === data.originalValue[0]);
+
+        if (!match) {
+            const value = data.originalValue[1];
+
+            if (value[StateProperties.Deleted]) {
+                record[0] = data.pristineValue[0];
+                record[1] = {[StateProperties.Deleted]: true};
+                return true;
+            } else if (typeof value === 'function' && value[StateProperties.Added]) {
+                record[0] = data.originalValue[0];
+                record[1] = {'function': serializeFunction(value), [StateProperties.Added]: true};
+                return true;
+            }
+        }
+
+        record[0] = data.originalValue[0];
+
+        this.getClonedValue(<SerializationData>{
+            clone: data.clone[data.key],
+            key: '1',
+            original: data.originalValue,
+            originalValue: data.originalValue[1],
+            pristine: match,
+            pristineValue: match?.[1]
+        });
+
+        // Delete empty objects from the record.
+        if (record[1] && !Object.keys(record[1]).length) {
+            record.splice(1, 1);
+        }
+
+        return true;
+    }
+
+    private readonly processArray = (data: SerializationData): boolean => {
+        if (!Array.isArray(data.originalValue)) {
+            return false;
+        }
+
+        // Do not include empty arrays in the serialized data when we have a pristine value to compare
+        // to. Otherwise, keep empty arrays as they are needed to correctly reconstruct the object.
+        if (data.pristine && !data.originalValue.length) {
+            return false;
+        }
+
+        data.clone[data.key] = [];
+        const resultArray = data.clone[data.key];
+        this.buildStructureForSerialization(resultArray, data.originalValue, data.pristineValue);
+
+        // Delete empty objects from the array. Only remove objects that have no properties or
+        // only properties with no values.
+        const emptyItems = resultArray.filter(e => {
+            if (typeof e !== 'object') {
+                return false;
+            }
+            return !Object.values(e).filter(v => v !== undefined && v !== null && v !== '').length;
+        });
+        emptyItems.forEach(e => resultArray.splice(resultArray.indexOf(e), 1));
+
+        const additionalArrayProperties = Object.keys(data.originalValue).filter(v => {
+            let isAdditionalProperty = isNaN(parseInt(v));
+
+            if (isAdditionalProperty) {
+                // add and delete proxies are used for location destinations, these are added in the LocationService.
+                // Ignore these proxies.
+                if (v === 'add' || v === 'delete') {
+                    isAdditionalProperty = false;
+                }
+            }
+
+            return isAdditionalProperty;
+        });
+
+        additionalArrayProperties.forEach(p => {
+            const arrayPropertyKey = `${data.key}_arrProps`;
+            data.clone[arrayPropertyKey] = data.clone[arrayPropertyKey] || {};
+            this.getClonedValue({
+                clone: data.clone[arrayPropertyKey],
+                key: p,
+                original: data.originalValue,
+                originalValue: data.originalValue[p],
+                pristine: data.pristine,
+                pristineValue: data.pristineValue
+            });
+        });
+
+        return true;
+    }
+
+    private readonly skipProperty = (original: any, originalValue: any, key: string, parentKey: string): boolean => {
+        return (
+            originalValue === undefined
+            || originalValue.isProxy
+            // Exclude descriptions and conversation nodes from the save data, these are not present on the pristine data.
+            // Use an additional property to identify them, as their names are quite generic.
+            || (original[IdProperty] && (key === DescriptionProperty || key === 'descriptions'))
+            || (parentKey === 'conversation' && !this.conversationPropertiesToSerialize.includes(key))
+        );
+    }
+
+    private readonly isKeyProperty = (item: any, propertyName: string): boolean => {
+        const keyProperties = getKeyPropertyNames(item);
+        return keyProperties.first === propertyName || keyProperties.second === propertyName;
+    }
+}

package/src/Engine/Services/DataService.ts

@@ -0,0 +1,93 @@
+import {isEmpty} from '../utilityFunctions';
+import {
+    IDataSerializer,
+    IDataService,
+    IDataSynchronizer,
+    IGame,
+    ILocalStorageService,
+    IRules,
+    ISaveGame,
+    PlayState
+}from 'storyScript';
+import {GameStateSave, SaveGamePrefix} from "src/constants";
+
+export class DataService implements IDataService {
+
+    constructor(
+        private _localStorageService: ILocalStorageService,
+        private serializer: IDataSerializer,
+        private synchronizer: IDataSynchronizer,
+        private _rules: IRules,
+        private _gameNameSpace: string) {
+    }
+
+    save = <T>(key: string, value: T): void => {
+        const clone = this.serializer.createSerializableClone(value);
+        this._localStorageService.set(this.getKey(key), JSON.stringify({data: clone}));
+    }
+
+    load = <T>(key: string): T => {
+        try {
+            const jsonData = this._localStorageService.get(this.getKey(key));
+
+            if (jsonData) {
+                const data = JSON.parse(jsonData).data;
+
+                if (isEmpty(data)) {
+                    return null;
+                }
+
+                const result = this.serializer.restoreObjects(data);
+                this.synchronizer.synchronizeEntityData(result);
+                return result;
+            }
+
+            return null;
+        } catch (exception: any) {
+            console.log('No data loaded for key ' + key + '. Error: ' + exception.message);
+        }
+
+        return null;
+    }
+
+    remove = (key: string): void => {
+        this._localStorageService.remove(this.getKey(key));
+    }
+
+    saveGame = (game: IGame, name?: string): void => {
+        if (!game.started) {
+            return;
+        }
+
+        name = name ? SaveGamePrefix + name : GameStateSave;
+        this._rules.general?.beforeSave?.(game);
+
+        const saveGame = <ISaveGame>{
+            party: game.party,
+            world: game.locations,
+            maps: game.maps,
+            worldProperties: game.worldProperties,
+            statistics: game.statistics,
+            playedAudio: game.sounds.playedAudio
+        };
+
+        this.save(name, saveGame);
+
+        if (game.playState === PlayState.Menu) {
+            game.playState = null;
+        }
+
+        this._rules.general.afterSave?.(game);
+    }
+
+    getSaveKeys = (): string[] => this._localStorageService.getKeys(this.getKey(SaveGamePrefix));
+
+    hasGameState = (): boolean => {
+        const state = this._localStorageService.get(this.getKey(GameStateSave));
+        return state !== null;
+    }
+
+    private getKey = (key?: string): string => {
+        return key ? `${this._gameNameSpace}_${key}` : this._gameNameSpace;
+    }
+}

package/src/Engine/Services/DataSynchronizer.ts

@@ -0,0 +1,216 @@
+import {IDataSynchronizer}from 'storyScript';
+import {StateProperties} from "src/Engine/stateProperties";
+import {getPlural, isDataRecord, propertyMatch} from "src/Engine/utilityFunctions";
+import {InitEntityCollection} from "src/Engine/EntityCreatorFunctions";
+
+export class DataSynchronizer implements IDataSynchronizer {
+    constructor(private _pristineEntities: Record<string, Record<string, any>>) {
+    }
+
+    synchronizeEntityData = (
+        entity: any,
+        pristineEntity?: any,
+        parentEntity?: any,
+        pristineParentEntity?: any,
+        parentProperty?: string
+    ): void => {
+        if (this.updateDataRecord(entity, pristineEntity)) {
+            return;
+        }
+
+        if (this.updateArray(entity, pristineEntity, parentEntity, pristineParentEntity, parentProperty)) {
+            return;
+        }
+
+        if (this.isEntity(entity)) {
+            if (pristineEntity === undefined) {
+                pristineEntity = this._pristineEntities[getPlural(entity.type)][entity.id];
+            }
+        }
+
+        // We don't have pristine entities for the 'world' and 'maps' properties of saved games.
+        // Use the pristine collections for these. When location and map files are deleted from
+        // the game, we need to remove them from the stored data as well.
+        if (parentProperty === 'world') {
+            pristineEntity = this._pristineEntities['locations'];
+            this.deleteRemovedEntities(entity, pristineEntity);
+        } else if (parentProperty === 'maps') {
+            pristineEntity = this._pristineEntities['maps'];
+            this.deleteRemovedEntities(entity, pristineEntity);
+        }
+
+        // Use the properties of both the entity and the pristine entity, but only
+        // process them once.
+        let propertyNames = [...new Set(
+            ((pristineEntity && Object.keys(pristineEntity)) ?? [])
+                .concat((entity && Object.keys(entity)) ?? []))];
+
+        propertyNames.forEach(p => {
+            let currentProperty = entity[p];
+
+            // If there is no pristine entity, recurse down the object to find entities to synchronize.
+            if (pristineEntity === undefined) {
+                if (Array.isArray(currentProperty) || typeof currentProperty === 'object') {
+                    this.synchronizeEntityData(currentProperty, undefined, entity, pristineEntity, p);
+                }
+                return;
+            }
+
+            let pristineProperty = pristineEntity[p];
+
+            if (currentProperty === undefined) {
+                if (Array.isArray(pristineProperty)) {
+                    entity[p] = [];
+                } else if (typeof pristineProperty === 'object' && pristineProperty !== null) {
+                    entity[p] = {};
+                } else {
+                    // If there is no value for this property on the object yet, 
+                    // it wasn't changed during runtime. Set it now.
+                    entity[p] = pristineProperty;
+                    return;
+                }
+            }
+
+            currentProperty = entity[p];
+
+            if (pristineProperty === undefined) {
+                if (Array.isArray(currentProperty)) {
+                    pristineProperty = [];
+                } else if (typeof currentProperty === 'object') {
+                    pristineProperty = {};
+                }
+            }
+
+            if (Array.isArray(pristineProperty) || typeof pristineProperty === 'object') {
+                this.synchronizeEntityData(currentProperty, pristineProperty, entity, pristineEntity, p);
+            }
+
+            // Either the property is the same on the entity and the pristine entity (a key value)
+            // or the value was changed at runtime. Either way, do nothing.
+        });
+    }
+
+    private updateDataRecord = (entity: any, pristineEntity: any): boolean => {
+        if (!isDataRecord(pristineEntity?.[0]) && !isDataRecord(entity?.[0])) {
+            return false;
+        }
+
+        pristineEntity.forEach((p: any[]) => {
+            const match = entity.concat(entity.getDeleted()).find((e: any[]) => e[0] === p[0]);
+
+            if (!match) {
+                // If there is no match, it means the record was added during design-time.
+                // Add it to the entity as well.
+                entity.push(p);
+            } else if (match[StateProperties.Deleted]) {
+                return;
+            } else if (typeof (p[1]) === 'function') {
+                match[1] = p[1];
+            } else {
+                if (!match[1]) {
+                    match.push(p?.[1] && Array.isArray(p[1]) ? [] : {});
+                }
+
+                this.synchronizeEntityData(match[1], p[1], entity, pristineEntity, '1');
+            }
+        });
+
+        const newRecords = entity.filter((e: any[]) => !pristineEntity.find(p => p[0] === e[0]));
+        const recordsToRemove = newRecords.filter((e: any[]) => !e[1]?.[StateProperties.Added]);
+        recordsToRemove.forEach(r => entity.splice(entity.indexOf(r), 1));
+        const recordsToKeep = newRecords.filter((e: any[]) => e[1]?.[StateProperties.Added]);
+        recordsToKeep.forEach(r => {
+            if (r[1].function) {
+                r[1] = r[1].function;
+                r[1][StateProperties.Added] = true;
+            }
+        })
+
+        this.markEntriesAsDeleted(entity);
+        return true;
+    }
+
+    private updateArray(
+        entity: any[],
+        pristineEntity: any[],
+        parentEntity?: any,
+        pristineParentEntity?: any,
+        parentProperty?: string
+    ): boolean {
+        if (!Array.isArray(entity) || !Array.isArray(pristineEntity)) {
+            return false;
+        }
+
+        if (entity.length == 0 && pristineEntity.length == 0) {
+            // Empty arrays weren't included in the serialized data. Call InitEntityCollection
+            // on them now to properly restore entities.
+            InitEntityCollection(parentEntity, parentProperty);
+            return true;
+        }
+
+        const existingItems = entity.filter(e => e[StateProperties.Added] && !pristineEntity.find(p => propertyMatch(e, p)));
+        const matchedItems = pristineEntity.filter(e => entity.find(p => propertyMatch(e, p)));
+        const itemsToAdd = pristineEntity.filter(e => !entity.concat(entity.getDeleted()).find(p => propertyMatch(e, p)));
+        const finalItems = [];
+
+        // matched and existing items need to be recursively checked. Added items aren't in the stored data yet, so they
+        // can be added straight away. The order is very important! Matched items are in both and need to go first. Added 
+        // items second, as these are now part of the design. Existing items have been added at runtime and should go last.
+        matchedItems.forEach(e => {
+            finalItems.push(this.updateArrayElement(e, entity, parentEntity, pristineParentEntity, parentProperty));
+        });
+
+        itemsToAdd.forEach(i => finalItems.push(i));
+
+        existingItems.forEach(e => {
+            finalItems.push(this.updateArrayElement(e, entity, parentEntity, pristineParentEntity, parentProperty));
+        });
+
+        entity.length = 0;
+
+        finalItems.forEach(i => {
+            entity.push(typeof i === 'object' ? {...i} : i);
+        });
+
+        this.markEntriesAsDeleted(entity);
+        return true;
+    }
+
+    private updateArrayElement = (element: any, entity: any, parentEntity, pristineParentEntity, parentProperty) => {
+        const currentValue = entity.filter(p => propertyMatch(element, p))[0];
+
+        // In case of an entity with the 'added' flag, 'i' is a skeleton value. Set the pristine entity to 'undefined' 
+        // so it will be looked up again later on.
+        const pristineValue = element[StateProperties.Added] && this.isEntity(element) ? undefined : element;
+
+        if (!currentValue[StateProperties.Deleted]) {
+            this.synchronizeEntityData(currentValue, pristineValue, parentEntity, pristineParentEntity, parentProperty);
+        }
+
+        return currentValue;
+    }
+
+    private isEntity = (entity: any): boolean => {
+        return entity?.type !== undefined && entity?.id !== undefined;
+    }
+
+    private markEntriesAsDeleted = (item: any[]) => {
+        const itemsToDelete = item.filter(i => i[StateProperties.Deleted]);
+        itemsToDelete.forEach(i => item.delete(i));
+    }
+
+    private deleteRemovedEntities = (entity: any, pristineEntity: any): void => {
+        if (!pristineEntity) {
+            return;
+        }
+
+        const entityKeys = Object.keys(entity);
+        const pristineKeys = Object.keys(pristineEntity);
+
+        entityKeys.forEach(k => {
+            if (pristineKeys.indexOf(k) < 0) {
+                delete entity[k];
+            }
+        });
+    }
+}