state

Documentation

Overview

Package state provides functions for managing persistent game data.

Index

• Variables
• func All() ([]string, error)
• func Delete(name string) error
• func Load[T any](name string, out *T) error
• func Save(name string, data any) error

Variables

var (
	ErrNotFound             = errors.New("state not found")    // ErrNotFound is an expected error which is returned when state is not stored.
	ErrInvalidStateName     = errors.New("invalid state name") // ErrInvalidStateName is a programmer error which is returned when state name is invalid.
	ErrNilStateOutput       = errors.New("nil state output")   // ErrNilStateOutput is a programmer error which is returned when output is nil.
	ErrStateUnmarshalFailed = errors.New("state unmarshal failed")
	ErrStateMarshalFailed   = errors.New("state marshal failed")
)

Functions

func All

func All() ([]string, error)

All returns names of all states.

func Delete

func Delete(name string) error

Delete permanently deletes data with given name.

func Load

func Load[T any](name string, out *T) error

Load reads the persistent game data with specified name. Data will be stored in out param. The type of out should be compatible with type used during Save. For example, trying to load stored string into an int will return the ErrStateUnmarshalFailed.

ErrNotFound error is returned when state does not exist. Please check the error with following code:

if errors.Is(err, pi.ErrNotFound) { ... }

ErrNilStateOutput is returned when out is nil.

func Save

func Save(name string, data any) error

Save permanently stores the data with given name. Data could be loaded using Load after restarting the game. Data can be of any type: string, int, time.Time, slice, map or a struct. Only struct public fields will be stored.

Please note that on some platforms there are limits for how much data could be stored. Web browsers for example have 5MB total data limit. So, if you want your game to be portable across different platforms, please limit the size of data below that number (in fact a game which stores more than hundreds of KBs per savegame does not look retro anymore). Similarly to data size limit, there is a limit for the number of states. It should be no more than tens of states. Generally using structs instead of primitive types like string or int could overcome this limit. For example, a single struct could have all the user preferences, or the entire hall of fame.

Saving a state is an atomic operation. Either the entire operation is successful and state is stored, or error is reported and no data is stored (previous data is not updated). You can leverage this feature to store similar data in a consistent manner - either all changes to data are applied or no changes at all. For example, you could design a struct having all user preferences, or a struct dedicated for an entire savegame. Such design will highly decrease the chance of consistency problems in case the game/OS crashes or during power loss.

Name cannot be empty, have characters "/", "\", or by longer than 32 characters