From f010eb0119887a3fbcf75bc4250ec687e378a980 Mon Sep 17 00:00:00 2001 From: James Date: Tue, 27 Nov 2018 12:32:33 +0000 Subject: [PATCH] moved server and serverCommands module to features + added more documentation to server --- control.lua | 4 +- features/gui/poll.lua | 2 +- server.lua => features/server.lua | 57 +++++++++++++++++++ .../server_commands.lua | 2 +- features/user_groups.lua | 2 +- 5 files changed, 62 insertions(+), 5 deletions(-) rename server.lua => features/server.lua (85%) rename server_commands.lua => features/server_commands.lua (95%) diff --git a/control.lua b/control.lua index 4d5110f0..1657b6a1 100644 --- a/control.lua +++ b/control.lua @@ -8,8 +8,8 @@ require 'map_gen.shared.perlin_noise' require 'map_layout' -- Specific to RedMew hosts, can be disabled safely if not hosting on RedMew servers -require 'server' -require 'server_commands' +require 'features.server' +require 'features.server_commands' -- Library modules which, if missing, will cause other feature modules to fail require 'features.base_data' diff --git a/features/gui/poll.lua b/features/gui/poll.lua index 7bab4608..ed8c1723 100644 --- a/features/gui/poll.lua +++ b/features/gui/poll.lua @@ -5,7 +5,7 @@ local UserGroups = require 'features.user_groups' local Game = require 'utils.game' local math = require 'utils.math' local Utils = require 'utils.utils' -local Server = require 'server' +local Server = require 'features.server' local default_poll_duration = 300 * 60 -- in ticks local duration_max = 3600 -- in seconds diff --git a/server.lua b/features/server.lua similarity index 85% rename from server.lua rename to features/server.lua index 9820b51a..5025ad94 100644 --- a/server.lua +++ b/features/server.lua @@ -1,3 +1,5 @@ +--- See documentation at https://github.com/Refactorio/RedMew/pull/469 + local Token = require 'utils.global_token' local Public = {} @@ -42,6 +44,9 @@ Public.events = {on_server_started = defines.events.on_server_started} --- Sends a message to the linked discord channel. The message is sanitized of markdown server side. -- @param message message to send. +-- @usage +-- local Server = require 'server' +-- Server.to_discord('Hello from scenario script!') function Public.to_discord(message) raw_print(discord_tag .. message) end @@ -96,6 +101,9 @@ end --- Stops and saves the factorio server and starts the named scenario. -- @param scenario_name The name of the scenario as appears in the scenario table on http://redmew.com/admin +-- @usage +-- local Server = require 'server' +-- Server.start_scenario('my_scenario_name') function Public.start_scenario(scenario_name) if type(scenario_name) ~= 'string' then game.print('start_scenario - scenario_name ' .. tostring(scenario_name) .. ' must be a string.') @@ -132,6 +140,14 @@ end -- @param data_set -- @param key -- @param value Any type that is not a function. set to nil to remove the data. +-- @usage +-- local Server = require 'server' +-- Server.set_data('my data set', 'key 1', 123) +-- Server.set_data('my data set', 'key 2', 'abc') +-- Server.set_data('my data set', 'key 3', {'some', 'data', ['is_set'] = true}) +-- +-- Server.set_data('my data set', 'key 1', nil) -- this will remove 'key 1' +-- Server.set_data('my data set', 'key 2', 'def') -- this will change the value for 'key 2' to 'def' function Public.set_data(data_set, key, value) if type(data_set) ~= 'string' then error('data_set must be a string') @@ -179,6 +195,22 @@ end -- @param data_set -- @param key -- @param callback_token +-- @usage +-- local Server = require 'server' +-- local Token = require 'utils.global_token' +-- +-- local callback = +-- Token.register( +-- function(data) +-- local data_set = data.data_set +-- local key = data.key +-- local value = data.value -- will be nil if no data +-- +-- game.print(data_set .. ':' .. key .. ':' .. tostring(value)) +-- end +-- ) +-- +-- Server.try_get_data('my data set', 'key 1', callback) function Public.try_get_data(data_set, key, callback_token) if type(data_set) ~= 'string' then error('data_set must be a string') @@ -203,6 +235,21 @@ end -- If there is no data stored for the data_set entries will be nil. -- @param data_set -- @param callback_token +-- @usage +-- local Server = require 'server' +-- local Token = require 'utils.global_token' +-- +-- local callback = +-- Token.register( +-- function(data) +-- local data_set = data.data_set +-- local entries = data.entries -- will be nil if no data +-- local value2 = entries['key 2'] +-- local value3 = entries['key 3'] +-- end +-- ) +-- +-- Server.try_get_all_data('my data set', callback) function Public.try_get_all_data(data_set, callback_token) if type(data_set) ~= 'string' then error('data_set must be a string') @@ -251,6 +298,16 @@ end -- is in the control stage, i.e before on_init or on_load would be called. -- @param data_set -- @param handler +-- @usage +-- local Server = require 'server' +-- Server.on_data_set_changed( +-- 'my data set', +-- function(data) +-- local data_set = data.data_set +-- local key = data.key +-- local value = data.value -- will be nil if data was removed. +-- end +-- ) function Public.on_data_set_changed(data_set, handler) if type(data_set) ~= 'string' then error('data_set must be a string') diff --git a/server_commands.lua b/features/server_commands.lua similarity index 95% rename from server_commands.lua rename to features/server_commands.lua index 31629b5c..3a34e076 100644 --- a/server_commands.lua +++ b/features/server_commands.lua @@ -1,7 +1,7 @@ local Poll = require 'features.gui.poll' local UserGroups = require 'features.user_groups' local Token = require 'utils.global_token' -local Server = require 'server' +local Server = require 'features.server' --- This module is for the web server to call functions and raise events. -- Not intended to be called by scripts. diff --git a/features/user_groups.lua b/features/user_groups.lua index 009057c7..e35971d9 100644 --- a/features/user_groups.lua +++ b/features/user_groups.lua @@ -1,6 +1,6 @@ local Event = require 'utils.event' local Utils = require 'utils.utils' -local Server = require 'server' +local Server = require 'features.server' local Donators = require 'resources.donators' local Game = require 'utils.game' local Token = require 'utils.global_token'