Store core

Core Module - Store - Adds an easy way to store and watch for updates to a value

Usage

-- The data store module is designed to be an alterative way to store data in the global table
-- each piece of data is stored at a location and optional key of that location
-- it is recomented that you use a local varible to store the location
local scenario_difficuly = Store.uid_location()
local team_scores = 'team-scores'

-- Setting and getting data is then as simple as
-- note that when storing a table you must use Store.update
Store.set(scenario_difficuly,'Hard')
Store.set(team_scores,game.player.force.name,20)

Store.get(scenario_difficuly) -- returns 'Hard'
Store.get(team_scores,game.player.force.name) -- returns 20

Store.update(team_scores,game.player.force.name,function(value,key)
    return value + 10 -- add 10 to the score
end)

-- The reason for using stores over global is the abilty to watch for updates
-- for stores to work you must register them, often at the end of the file
Store.register(scenario_difficuly,function(value)
    game.print('Scenario difficulty has been set to: '..value)
end)

Store.register(team_scores,function(value,key)
    game.print('Team '..key..' now has a score of '..value)
end)

-- This can be very powerful when working with data that can be changed for a number of locations
-- with this module you can enable any location to output its changes to a file
-- say we wanted team scores to be synced across servers or between saves
-- although you will need to set up a method of storing the data outside the game
Store.register(team_scores,true,function(value,key)
    game.print('Team '..key..' now has a score of '..value)
end)

-- If you want multiple handlers on one store location then you can register to the raw event
Event.add(Store.events.on_value_changed,function(event)
    game.print('Store '..event.location..'/'..event.key..' was updated to: '..event.value)
end)

Dependencies

utils.global
utils.event
expcore.common
utils.token

Functions

register([location][, synced=false][, callback])	Registers a new location with an update callback which is triggered when the value updates
get(location[, key])	Gets the value stored at a location, this location must be registered
set(location[, key], value[, from_sync=false][, from_internal=false])	Sets the value at a location, this location must be registered
update(location[, key][, update_callback])	Allows for updating a value based on the current value; only valid way to change tables in a store
update_all(location[, update_callback])	Allows for updating all values at a location based on the current value; only valid way to change tables in a store
clear(location[, key][, from_sync=false])	Sets the value at a location to nil, this location must be registered
get_keys(location)	Gets all non nil keys at a location, keys can be added and removed during runtime this is similar to Store.get but will always return a table even if it is empty
is_registered(location)	Check for if a location is registered
uid_location()	Returns a unique name that can be used for a store

Dependencies

# utils.global

# utils.event

# expcore.common

# utils.token

Functions

# register([location][, synced=false][, callback])

Registers a new location with an update callback which is triggered when the value updates

Parameters:

• location : (string) string a unique that points to the data, string used rather than token to allow migration (optional)
• synced : (boolean) when true will output changes to a file so it can be synced (default: false)
• callback : (function) when given the callback will be automatically registered to the update of the value (optional)

Returns:

• (string) the location that is being used

Usage:

-- Registering a new store location
local store_id = Store.register()

-- Registering a new store location, with custom update callback
local store_id = Store.uid_location()
Store.register(store_id,function(value,key)
    game.print('Store '..store_id..'/'..key..' was updated to: '..value)
end)

# get(location[, key])

Gets the value stored at a location, this location must be registered

Parameters:

• location : (string) the location to get the data from
• key : (string) the key location if used (optional)

Returns:

• (any) the data which was stored at the location

Usage:

-- Getting the data at a store location
local data = Store.get(store_id_no_keys)
local data = Store.get(store_id_with_keys,'key_one')

# set(location[, key], value[, from_sync=false][, from_internal=false])

Sets the value at a location, this location must be registered

Parameters:

• location : (string) the location to set the data to
• key : (string) the key location if used (optional)
• value : (any) the new value to set at the location, value may be reverted if there is a watch callback, cant be nil
• from_sync : (boolean) set this true to avoid an output to the sync file (default: false)
• from_internal : (boolean) set this true to add one to the error stack offset (default: false)

Returns:

• (boolean) true if it was successful

Usage:

-- Setting the data at a store location
Store.set(store_id_no_keys,'Hello, World!')
Store.set(store_id_with_keys,'key_one','Hello, World!')

# update(location[, key][, update_callback])

Allows for updating a value based on the current value; only valid way to change tables in a store

Parameters:

• location : (string) the location to set the data to
• key : (string) the key location if required (optional)
• update_callback : (function) the function called to update the value stored, rtn value to set new value (optional)

Usage:

-- Updating a value stored at a location
Store.update(store_id_no_keys,function(value)
    return value + 1
end)
Store.update(store_id_with_keys,'key_one',function(value)
    return value + 1
end)

-- Updating a table stored at a location
Store.update(store_id_no_keys,function(value)
    value.ctn = value.ctn + 1
end)
Store.update(store_id_with_keys,'key_one',function(value)
    value.ctn = value.ctn + 1
end)

# update_all(location[, update_callback])

Allows for updating all values at a location based on the current value; only valid way to change tables in a store

Parameters:

• location : (string) the location to set the data to
• update_callback : (function) the function called to update the value stored (optional)

Usage:

-- Updating all values at a location
Store.update(store_id_with_keys,function(value)
    return value + 1
end)

-- Updating all tables at a location
Store.update(store_id_with_keys,function(value)
    value.ctn = value.ctn + 1
end)

# clear(location[, key][, from_sync=false])

Sets the value at a location to nil, this location must be registered

Parameters:

• location : (string) the location to set the data to
• key : (string) the key location if used (optional)
• from_sync : (boolean) set this true to avoid an output to the sync file (default: false)

Returns:

• (boolean) true if it was successful

Usage:

-- Clear the data at a location
Store.clear(store_id_no_keys)
Store.clear(store_id_with_keys,'key_one')

# get_keys(location)

Gets all non nil keys at a location, keys can be added and removed during runtime this is similar to Store.get but will always return a table even if it is empty

Parameters:

• location : (string) the location to get the keys of

Returns:

• (table) a table containing all the keys names

Usage:

-- Get all keys at a store location
local keys = Store.get_keys(store_id_with_keys)

# is_registered(location)

Check for if a location is registered

Parameters:

• location : (string) the location to test for

Returns:

• (boolean) true if registered

Usage:

-- Check that a store is registered
local registerd = Store.is_registered(store_id)

# uid_location()

Returns a unique name that can be used for a store

Returns:

• (string) a unique name

Usage:

-- Get a new unique store id
local store_id = Store.uid_location()