Store core

Core Module - Store - Used to store and watch for updates for values in the global table

Dependencies

utils.event

Tables

serializers
watchers

Fields

uid

Store Setup

validate(store[, key][, error_stack=1]) An error checking and serializing function for checking store uids and keys, note key is not required
register([serializer]) Required to create new stores and register an serializer to a store, serializer not required
watch(store, watcher) Register a watch function to a store that is called when the value in the store is changed, triggers for any key

Store Data Management

get(store[, key]) Used to retrive the current data that is stored, key is optional depending on if you are using them
clear(store[, key]) Used to clear the data in a store, will trigger any watchers, key is optional depending on if you are using them
set(store[, key], value) Used to set the data in a store, will trigger any watchers, key is optional depending on if you are using them
update(store[, key], updater) Used to update the data in a store, use this with tables, will trigger any watchers, key is optional depending on if you are using them
map(store, updater) Used to update all values that are in a store, similar to Store.update but acts on all keys at once, will trigger watchers for every key present
trigger(store[, key][, value]) Used to trigger any watchers that are on this store, the key and value are passed to the watcher functions

Dependencies

# utils.event

Tables

# serializers

array of the serializers that stores are using, key is store uids

# watchers

array of watchers that stores will trigger, key is store uids

Fields

# uid
  • uid : the current highest uid that is being used, will not increase during runtime

Store Setup

# validate(store[, key][, error_stack=1])

An error checking and serializing function for checking store uids and keys, note key is not required

Parameters:
  • store : (number) the uid of the store that you want to check is valid
  • key : (string or any) the key that you want to serialize or check is a string (optional)
  • error_stack : (number) the position in the stack relative to the current function (1) to raise this error on (default: 1)
Returns:
  • (string) if key is given and a serializer is registered, or key was already a string, then the key is returned
Usage: 
-- Registering a new store and checking that it is valid
-- New store will use player names as the keys
local player_scores = Store.register(function(player)
    return player.name
end)

-- player_scores is a valid store and key will be your player name
local key = Store.validate(player_scores,game.player)
# register([serializer])

Required to create new stores and register an serializer to a store, serializer not required

Parameters:
  • serializer : (function) the function used to convert non string keys into strings to be used in the store (optional)
Returns:
  • (number) the uid for the new store that you have created, use this as the first param to all other functions
Usage: 
-- Creating a store with no serializer
local scenario_diffculty = Store.register()
-- Creating a store which can take LuaPlayer
local player_scores = Store.register(function(player)
    return player.name
end)
# watch(store, watcher)

Register a watch function to a store that is called when the value in the store is changed, triggers for any key

Parameters:
  • store : (number) the uid of the store that you want to watch for changes to
  • watcher : (function) the function that will be called when there is a change to the store
Usage: 
-- Printing the changed value to all players, no keys
-- Register the new store, we are not using keys so we dont need a serializer
local scenario_diffculty = Store.register()

-- Register the watcher so that when we change the value the message is printed
Store.watch(scenario_diffculty,function(value)
    game.print('The scenario diffculty has been set to '..value)
end)

-- Set a new value for the diffculty and see that it has printed to the game
Store.set(scenario_diffculty,'hard')
-- Printing the changed value to all players, with keys
-- Register the new store, we are not using player names as the keys so it would be useful to accept LuaPlayer objects
local player_scores = Store.register(function(player)
    return player.name
end)

-- Register the watcher so that when we change the value the message is printed
Store.watch(player_scores,function(value,key)
    game.print(key..' now has a score of '..value)
end)

-- Set a new value for your score and see that it has printed to the game
Store.set(player_scores,game.player,10)

Store Data Management

# get(store[, key])

Used to retrive the current data that is stored, key is optional depending on if you are using them

Parameters:
  • store : (number) the uid of the store that you want to get the value from
  • key : (string or any) the key that you want to get the value of, must be a string unless you have a serializer (optional)
Returns:
  • (any) the data that is stored
Usage: 
-- Getting the value of a store with no keys
-- Register the new store, we are not using keys so we dont need a serializer
local scenario_diffculty = Store.register()

-- Get the current diffculty for the scenario
local diffculty = Store.get(scenario_diffculty)
-- Getting the data from a store with keys
-- Register the new store, we are not using player names as the keys so it would be useful to accept LuaPlayer objects
local player_scores = Store.register(function(player)
    return player.name
end)

-- Get your current score
local my_score = Store.get(player_scores,game.player)

-- Get all scores
lcoal scores = Store.get(player_scores)
# clear(store[, key])

Used to clear the data in a store, will trigger any watchers, key is optional depending on if you are using them

Parameters:
  • store : (number) the uid of the store that you want to clear
  • key : (string or any) the key that you want to clear, must be a string unless you have a serializer (optional)
Usage: 
-- Clear a store which does not use keys
-- Register the new store, we are not using keys so we dont need a serializer
local scenario_diffculty = Store.register()

-- Clear the scenario diffculty
Store.clear(scenario_diffculty)
-- Clear data that is in a store with keys
-- Register the new store, we are not using player names as the keys so it would be useful to accept LuaPlayer objects
local player_scores = Store.register(function(player)
    return player.name
end)

-- Clear your score
Store.clear(player_scores,game.player)

-- Clear all scores
Store.clear(player_scores)
# set(store[, key], value)

Used to set the data in a store, will trigger any watchers, key is optional depending on if you are using them

Parameters:
  • store : (number) the uid of the store that you want to set
  • key : (string or any) the key that you want to set, must be a string unless you have a serializer (optional)
  • value : (any) the value that you want to set
Usage: 
-- Setting a store which does not use keys
-- Register the new store, we are not using keys so we dont need a serializer
local scenario_diffculty = Store.register()

-- Set the new scenario diffculty
Store.set(scenario_diffculty,'hard')
-- Set data in a store with keys
-- Register the new store, we are not using player names as the keys so it would be useful to accept LuaPlayer objects
local player_scores = Store.register(function(player)
    return player.name
end)

-- Set your current score
Store.set(player_scores,game.player,10)

-- Set all scores, note this might not have much use
Store.set(player_scores,{
    [game.player.name] = 10,
    ['SomeOtherPlayer'] = 0
})
# update(store[, key], updater)

Used to update the data in a store, use this with tables, will trigger any watchers, key is optional depending on if you are using them

Parameters:
  • store : (number) the uid of the store that you want to update
  • key : (string or any) the key that you want to update, must be a string unless you have a serializer (optional)
  • updater : (function) the function which is called to make changes to the value, such as changing table keys, if a value is returned it will replace the current value in the store
Usage: 
-- Incrementing a global score
-- Because we are only going to have one score so we will not need keys or a serializer
local game_score = Store.register()

-- Setting a default value
Store.set(game_score,0)

-- We now will update the game score by one, we return the value so that it is set as the new value in the store
Store.update(game_score,function(value)
    return value + 1
end)
-- Updating keys in a table of data
-- Register the new store, we are not using player names as the keys so it would be useful to accept LuaPlayer objects
local player_data = Store.register(function(player)
    return player.name
end)

-- Setting a default value for your player, used to show the table structure
Store.set(player_data,game.player,{
    group = 'Admin',
    role = 'Owner',
    show_group_config = false
})

-- Updating the show_group_config key in your player data, note that it would be harder to call set every time
-- We do not need to return anything in this case as we are not replacing all the data
Store.update(player_data,game.player,function(data)
    data.show_group_config = not data.show_group_config
end)
# map(store, updater)

Used to update all values that are in a store, similar to Store.update but acts on all keys at once, will trigger watchers for every key present

Parameters:
  • store : (number) the uid of the store that you want to map
  • updater : (function) the function that is called on every key in this store
Usage: 
-- Updating keys in a table of data
-- Register the new store, we are not using player names as the keys so it would be useful to accept LuaPlayer objects
local player_data = Store.register(function(player)
    return player.name
end)

-- Setting a default value for your player, used to show the table structure
Store.set(player_data,game.player,{
    group = 'Admin',
    role = 'Owner',
    show_group_config = false
})

-- Updating the show_group_config key for all players, note that it would be harder to call set every time
-- We do not need to return anything in this case as we are not replacing all the data
-- We also have access to the current key being updated if needed
Store.map(player_data,function(data,key)
    data.show_group_config = not data.show_group_config
end)
# trigger(store[, key][, value])

Used to trigger any watchers that are on this store, the key and value are passed to the watcher functions

Parameters:
  • store : (number) the uid of the store that you want to trigger
  • key : (string or any) the key that you want to trigger, must be a string unless you have a serializer (optional)
  • value : (any) the new value that is at this key or store, passed directly to the watcher (optional)
Usage: 
-- Triggering a manule call of the watchers
-- The type of store we use does not really matter for this as long as you pass it what you watchers are expecting
local scenario_diffculty = Store.register()

-- Trigger the watchers with a fake change of diffculty
-- This is mostly used internally but it can be useful in other cases
Store.trigger(scenario_diffculty,nil,'normal')
generated by LDoc
Last updated 2019-10-08 23:22:49 UTC