From fd5b0b6aad32d1ac7e81aa34092b69de70ae1843 Mon Sep 17 00:00:00 2001 From: Monica Moniot Date: Sun, 4 Dec 2022 10:51:40 -0500 Subject: [PATCH] improved remote interface --- cybersyn/scripts/global.lua | 2 +- cybersyn/scripts/remote-interface.lua | 55 ++++++++++++++++++++++++--- 2 files changed, 50 insertions(+), 7 deletions(-) diff --git a/cybersyn/scripts/global.lua b/cybersyn/scripts/global.lua index e193d68..0da4b92 100644 --- a/cybersyn/scripts/global.lua +++ b/cybersyn/scripts/global.lua @@ -17,7 +17,7 @@ ---@field public tick_state uint ---@field public tick_data {} ---@field public economy Economy ----@field public se_tele_old_id {[any]: uint} +---@field public se_tele_old_id {[string]: uint} ---@class Station ---@field public entity_stop LuaEntity diff --git a/cybersyn/scripts/remote-interface.lua b/cybersyn/scripts/remote-interface.lua index 87cbea9..33f427f 100644 --- a/cybersyn/scripts/remote-interface.lua +++ b/cybersyn/scripts/remote-interface.lua @@ -350,7 +350,31 @@ end ------------------------------------------------------------------ --[[unsafe API]] ------------------------------------------------------------------ ---NOTE: The following functions can cause serious longterm damage to someone's world if they are given bad parameters. Use caution. +--NOTE: The following functions can cause serious longterm damage to someone's world if they are given bad parameters. Please refer to global.lua for type information. Use caution. + +---@param key string +---@param value any +function interface.write_setting(key, value) + --be careful that the value you write is of the correct type specified in global.lua + mod_settings[key] = value +end + +---@param ... string|uint|any +function interface.write_global(value, ...) + --this can write anything into cybersyn's map_data, please be very careful with anything you write, it can cause permanent damage + --so interface.read_global(nil, "trains", 31415, "manifest") will cause global.trains[31415].manifest = nil (or return false if train 31415 does not exist) + local params = {...} + local size = #params + local key = params[size] + assert(key ~= nil) + local base = global + for i = 1, size - 1 do + base = base[params[i]] + if not base then return false end + end + base[key] = value + return true +end ---@param station_id Station ---@param manifest Manifest @@ -384,6 +408,9 @@ end ---@param train_id uint function interface.add_available_train(train_id) + --This function marks a train as available but not in a depot so it can do depot bypass, be sure the train has no active deliveries before calling this + --available trains can be chosen by the dispatcher to be rescheduled and dispatched for a new delivery + --when this train parks at a depot add_available_train_to_depot will be called on it automatically local train = global.trains[train_id] assert(train) add_available_train(global, train_id, train) @@ -391,6 +418,8 @@ end ---@param depot_id uint ---@param train_id uint function interface.add_available_train_to_depot(train_id, depot_id) + --This function marks a train as available and in a depot, be sure the train has no active deliveries before calling this + --available trains can be chosen by the dispatcher to be rescheduled and dispatched for a new delivery local train = global.trains[train_id] local depot = global.depots[depot_id] assert(train and depot) @@ -398,6 +427,7 @@ function interface.add_available_train_to_depot(train_id, depot_id) end ---@param train_id uint function interface.remove_available_train(train_id) + --this function removes a train from the available trains list so it cannot be rescheduled and dispatched. if the train was not already available nothing will happen local train = global.trains[train_id] assert(train) remove_available_train(global, train_id, train) @@ -431,15 +461,28 @@ interface.send_stuck_train_alert = send_stuck_train_alert ------------------------------------------------------------------ --[[helper functions]] ------------------------------------------------------------------ ---NOTE: the policy of cybersyn is to give modders access to the raw data of the mod, please either treat all tables returned from the modding interface as "read only", or if you do modify them take responsibility that your modification does not result in an error occuring in cybersyn later on. ---NOTE: the follow functions aren't strictly necessary; they are provided more as a guide how the mod api works rather than as practical functions. +--NOTE: the policy of cybersyn is to give modders access to as much of the raw data of the mod as possible. Factorio only allows me to return copies of the original data rather than the actual thing, which sucks. The unsafe api has some tools to help you bypass this limitation. -function interface.get_map_data() - return global -end function interface.get_mod_settings() return mod_settings end +---@param key string +function interface.read_setting(key) + return mod_settings[key] +end +---@param ... string|uint +function interface.read_global(...) + --this can read anything off of cybersyn's map_data + --so interface.read_global("trains", 31415, "manifest") == global.trains[31415].manifest (or nil if train 31415 does not exist) + local base = global + local depth = 0 + for i, v in ipairs({...}) do + depth = i + base = base[v] + if not base then break end + end + return base, depth +end ---@param id uint function interface.get_station(id) return global.stations[id]