Save Game - UQdeco2800/2022-studio-1 GitHub Wiki

Navigation

Overview
Design Overview
Implementation
Improvements from Sprint 3
Environmental Obstacles
Structures
Player
Crystal
Game State
Enemies
Why not Serialise Directly?
Testing
Current State
Class Diagram
Sequence Diagram

Save Game Overview

For Sprint 3 and 4 Team 4 decided to implement the save game functionality for the game. This was done to help encourage and facilitate players to play the game without having to worry about progress or having to finish the game in a single sitting. The save game is one of the most complex systems present having to be dependent on every single other system and having the ability to retrieve and load relevant information as needed.

Currently, save game functions for loading environmental obstacles, structures, player, crystal, game night and enimeies. Since sprint three many issues and problems have been ironed out allowing for save game to be fully functional.

Save State Design Introduction

In terms of design we focused on designing a user interface for the Save and Load game functionality. To achieve that we deployed several user testing sessions along with surveys and interviews to collect data and refine the idea. That way we made sure that the Save and Load state went beyond designing a set of pretty buttons. Overview of the UI Design progress for the Save and Load Game is available here.

Save Game Implementation

Save Game generally functions by using JSON serialization of objects and their respective properties as needed. This meant that customs methods and functions were written for each of the below features. General save location is in assets/Saves/ where there is multiple json files labeled environment, game state, structures etc.

As the SaveGame is a static class, the game state can be saved and located at any point via the two static methods saveGameState() and loadGameState()

Improvements from Sprint 3

Since sprint three the main focus was fixing Save Game to account for the newly UGS system and to generally simplify the SaveGame pipeline in a general code cleanup. The main improvements since sprint 3 is the use of stack tracing where the creation name of the method is stored dynamically into the json serialisation file for each saved entity. This has two big new beneftis

Refractoring of code will not break the invocation scheme allowing save game to be more robust
significantly cleaner method than previously hard coded hashmaps and invocation

From the UGS perspective more details are required to be saved for entities, including the tile position. When loading UGS now must be used in very specific ways and order. Many issues were encountered here from concurrency issues to rendering issues.

Other improvements since sprint 3 include adding Enemy and [Game Status] save functionality

Environmental Obstacles

The pipeline for saving Environmental obstacles this was that every entity was searched for a environmental component and texture component and if an entity had these two things it was deemed to be an environmental obstacle. From this point critical data was loaded in a Tuple class which stores the name, texture and position of the environmental obstacle. Environmental obstacles were then saved via Json serialization of their attributes into an ArrayList.

The Json file for environmental objects is Saves/Environmental.json and follows the format:

[
{
	class: com.deco2800.game.files.Tuple
	texture: images/seastack2.png
	position: {}
	name: Rock@92
	tileString: "0,0"
	creationMethod: createRock
}
...
]

To load environmental objects the array list is unserialized and a brand new entity is spawned based off a class method invoke system. The details of the object are then updated and corresponding attributes set. This was done to ensure future compatability with changes to the environmental obstacles.

Structures

Structures work in a very similar way to environmental obstacles. The pipeline is that all structures are saved from the Structures entity service where their name, position and texture are saved into a tuple class for each unique structure which is put into an array list and serialized via json. The Json file is in Assets/Saves/Structures.json

The file follows with the loading method working identically to environmental objects just with different attributes and invocation methods:

[
{
	class: com.deco2800.game.files.Tuple
	position: {
		x: 936
		y: -4
	}
	name: "wall(59, 58)"
	tileString: "59,58"
	creationMethod: createWall
}
{
	class: com.deco2800.game.files.Tuple
	position: {
		x: 944
		y: -8
	}
	name: "wall(60, 58)"
	tileString: "60,58"
	creationMethod: createWall
	rotation: 1
}
]

Player

The player is saved by serialising a dictionary of relevant values, along with the standard attributes (position, etc.). When loaded back in, the existing player entity in the game area has its attributes adjusted, rather than destroying and recreating the player. This limits LoadGame() to being called only after the player (and crystal - see below) have been initialised, but minimises the complexity of the save and load process, and prevents LoadGame() from having to access private methods and attributes in the main GameArea class unnecessarily. The player serialisation is below. It stores the player position, gold, inventory, health, and combatStats:

{
position: {
	x: 964.45306
	y: 0.11982894
}
name: player
playerState: {
	gold: {
		class: java.lang.Integer
		value: 55
	}
	weapon: null
	chestplate: null
	defence: {
		class: java.lang.Integer
		value: 10
	}
	attack: {
		class: java.lang.Integer
		value: 10
	}
	helmet: null
	health: {
		class: java.lang.Integer
		value: 78
	}
	wood: {
		class: java.lang.Integer
		value: 50
	}
	items: {
		class: java.util.HashMap
	}
	stone: {
		class: java.lang.Integer
		value: 50
	}
}
}

Initially, we considered using the existing Memento and CareTaker classes to save and load player state, but these classes were difficult to serialise and often buggy when called from SaveGame. This would be a valuable avenue for future work, however

Crystal

Saving and loading the crystal works nearly identically to saving and loading the player, but less complex. Like the player, the crystal can only be loaded in after the crystal entity has been initialised in GameArea When loading the crystal back in, if the crystal level is larger than 1, this level is applied by repeatedly calling the upgradeCrystal() method in CrystalFactory, which ensures the state of the terrain is also updated.

{
texture: images/crystal.png
position: {
	x: 964
	y: 2
}
name: crystal
level: 1
health: 1000
}

Game State

The Game State comprises the 'DayNightCycleService' and associated features (i.e. 'DayNightClockComponent', attached to the UI entity). The DayNightCycleService details are saved through direct serialisation:

{
currentCycleStatus: NIGHT
lastCycleStatus: DUSK
currentDayNumber: 1
currentDayMillis: 106252
isStarted: true
config: {
	dawnLength: 15000
	dayLength: 60000
	duskLength: 15000
	nightLength: 30000
	maxDays: 4
}
timer: {
	startTime: 1664686569471
}
timeSinceLastPartOfDay: 220547
timePerHalveOfPartOfDay: 15000
partOfDayHalveIteration: 2
lastPartOfDayHalveIteration: 2
}

Though saving is simple, loading is decidedly more complex. For an overview of how the day and night cycle service works, go here.

Loading in the DayNightCycle had two major requirements: load in the DayNightCycleService, and update the UI DayNightClockComponent.

Loading the DayNightCycleService

Although the full service is serialised, only relevant attributes are loaded back into the DayNightCycleService. This is primarily to prevent unwanted behaviour - when all attributes were loaded directly back, clicking the game screen caused an exit back to the main menu. We still don't know why this happened, but being selective with the attributes being loaded solved it.

DayNightCycleService is changed after a load using the 'loadFromSave' function. Because of the complexity (and amount of repeated code) that would be necessary to destroy and restart the service, this was the best option available.

public void loadFromSave(int dayNum, long dayMs, DayNightCycleStatus currentStatus, DayNightCycleStatus prevStatus, int partOfDayHalveIteration) {
        long dayDiff = (dayNum - currentDayNumber) * (config.nightLength + config.duskLength + config.dayLength + config.dawnLength);
        long dayMsDiff = dayMs - currentDayMillis;

        this.loadedTimeOffset = dayDiff + dayMsDiff;

        this.currentDayNumber = dayNum;
        this.currentCycleStatus = prevStatus;
        setPartOfDayTo(currentStatus);
        this.partOfDayHalveIteration = partOfDayHalveIteration;

        this.currentDayMillis = this.timer.getTime() - (this.currentDayNumber * (config.nightLength + config.duskLength + config.dayLength + config.dawnLength)) - this.totalDurationPaused + this.loadedTimeOffset;

        loaded = true;
    }

This function initialises relevant variables - currentDayNumber and currentCycleStatus are self-explanatory. SetPartOfDayTo triggers a a time of day update, which notifies other services (e.g. the DayNightCycleComponent, which deals with shaders) of the time of day.

The loadedTimeOffset allows us to work with the GameTime timer the DayNightCycleService works on. Prior to that, the service would fail to update as it would have the right day number and time set, but the timer would be equivalent to an earlier day - we would effectively have to wait for the timer to 'catch up' before the clock progressed again. loadedTimeOffset is set to 0 on initialisation, and is only ever changed in loadFromSave to prevent unexpected behaviour in an unloaded save.

loaded is set in this function, and then used in the start() to prevent it from setting the timer back to dawn. Without this sentinel, there would be a rapid series of updates when the game loaded in to progress from dawn to the time of day the timer thinks we're at, leading to unexpected behaviour with the DayNightClockComponent

Loading the DayNightClockComponent

The DayNightClockComponent is loaded from save entirely through references to the DayNightCycleService and is not saved directly. Although clunky, this prevents serialisation issues, so was the best solution. the loadFromSave() function here calculates which sprite to access based on the day number and time of day (accessed from DayNightCycleService), then updates the sprite 'pointer' to that number.

Note DayNightCycleService.loadFromSave() - the function setting these values so they can be accessed by DayNightClockComponent - does not run asynchronously like much of the rest of the DayNightCycleService, so the values are guaranteed to be correct when accessed.

    public void loadFromSave() {
        DayNightCycleService cycleService = ServiceLocator.getDayNightCycleService();
        int dayNum = cycleService.getCurrentDayNumber();
        //8 segments in the clock, starts at dawn (between night & dawn)
        int numUpdates = (dayNum - 1) * 8;
        DayNightCycleStatus status = cycleService.getCurrentCycleStatus();
        switch (status) {
            case DUSK:
                numUpdates += 5;
                break;
            case NIGHT:
                numUpdates += 6 + (cycleService.partOfDayHalveIteration - 1);
                break;
            case DAY:
                numUpdates += cycleService.partOfDayHalveIteration;
                break;
            default:
                break;
        }
        if (numUpdates >= clockSprites.length) {
            numUpdates = clockSprites.length;
        }
        this.currentSprite = numUpdates - 1;
        changeSprite(status);
        loaded = true;
        timeLoaded = cycleService.getTimer().getTime();
    }

At the end of the function, loaded is set to true, and the time loaded is recorded. These values are used as sentinels in the ChangeSprite function (see below) to prevent updates for 300ms after the clock sprite is loaded. This is necessary because the DayNightCycleService runs asynchronously, and sometimes triggers setPartOfDayTo() after the clock has been set, causing it to iterate forward one more than it should be.

    private void changeSprite(DayNightCycleStatus partOfDay) {
        if (loaded) {
            if (ServiceLocator.getDayNightCycleService().getTimer().getTime() - timeLoaded < 300) {
                //avoid asynchronous update triggers right after being loaded in
                return;
            } else {
                loaded = false;
            }
        }

Enemies

Enemies works most similarly to structures and environmental objects. The pipeline is that every entity was searched, the ones that are Enemy subclasses and has texture component are considered to be an enemy. Like other saving methods, data was loaded in a Tuple class which stores the name, position, and creation method (since enemies can have different creation methods and parameters) of the enemy. Enemies were then saved via Json serialization of their attributes into an ArrayList.

The Json file for environmental objects is Saves/Environmental.json and follows the format:

[
{
	class: com.deco2800.game.files.Tuple
	position: {
		x: 4
		y: 4
	}
	name: Mr. Starfish@92
	creationMethod: createStarFishEnemy
}
{
	class: com.deco2800.game.files.Tuple
	position: {
		x: 3
		y: 3
	}
	name: Mr. Electricity@91
	creationMethod: createElectricEelEnemy
}
{
	class: com.deco2800.game.files.Tuple
	position: {
		x: 2
		y: 2
	}
	name: Mr. Crabs@90
	creationMethod: createPirateCrabEnemy
}
...
]

Loading enemies is done by unserializing the array list and new entities are spawned based off the class method invoke system along side their details and attributes. However, loading enemies are different from structures and environments. As they require the player and the crystal in invoking their method. Because of this, reference of the Player and Crystal entity needs to be passed from the loadPlayer and loadCrystal method to the loadEnemies method.

Why not serialize the objects directly?

The biggest problem faced is that it is impossible to serialize the objects directly. This is due to the fact that most objects reference themselves indirectly so when a json serialziation is attempted, stack overflow will ensue. For example take a entity. If you attempt to json serialize then the engine will attempt to save everything within the entity including the components. When saving the components though as the components store the entity the engine attempts to save the entity once again causing a never ending loop of serialization.

This issue has been mitigrated via two methods, the use of adding transient to attributes to stop serialization but this is slow process and requires extensive debugging and makes loading the object difficult. THe other method to store all relevant details, recreate the object and set the details which was the chosen method for most of the above implementations. The issue with this is that compatability is an issue and if new features are added this typically requries a modification to the save method. Due to this it is unreasonable to expect a fully functional save/load game without adequate time for method rewriting and bug fixing.

Testing

Due to the complexity of save game significant unit testing was conducted with 15+ units tests and over 700 lines of code written to test indivdual saving, loading and full save/load pipeline. Specifically these tests work by establishing a full recreation of all the services and attempting to spawn and save a predertermined number of entites and types of entites such as structures or environmental obstacles. This is useful as it ensures functionality should be adhered to when other teams merge their content.

Current State

The current load/Game state functionality can be seen as of 16/10/2022 below ON MAIN BRANCH.

During Day, Structures and Environmental Objects: https://user-images.githubusercontent.com/87936020/196016774-ab807758-fce3-4fd1-ab00-b00bccae71b3.mp4

Class Diagram Map

Sequence Diagram Map when saving the game state