added a modding interface

cybersyn/changelog.txt

@@ -105,3 +105,4 @@ Date: 2022-12-2
   Features:
     - Fixed a bug with combinator displays not updating correctly
     - Improved combinator display performance
+    - Added a modding interface

cybersyn/control.lua

@@ -8,3 +8,4 @@ require("scripts.layout")
 require("scripts.gui")
 require("scripts.migrations")
 require("scripts.main")
+require("scripts.remote-interface")

cybersyn/scripts/central-planning.lua

@@ -12,6 +12,7 @@ local random = math.random
 ---@param map_data MapData
 ---@param station Station
 ---@param manifest Manifest
+---@param sign -1|1
 function remove_manifest(map_data, station, manifest, sign)
 	local deliveries = station.deliveries
 	for i, item in ipairs(manifest) do
@@ -94,8 +95,8 @@ end
 ---@param r_station_id uint
 ---@param p_station_id uint
 ---@param train_id uint
----@param primary_item_name string
+---@param primary_item_name string?
-local function send_train_between(map_data, r_station_id, p_station_id, train_id, primary_item_name)
+function send_train_between(map_data, r_station_id, p_station_id, train_id, primary_item_name)
 	--trains and stations expected to be of the same network
 	local economy = map_data.economy
 	local r_station = map_data.stations[r_station_id]
@@ -140,9 +141,6 @@ local function send_train_between(map_data, r_station_id, p_station_id, train_id
 	local i = 1
 	while i <= #manifest do
 		local item = manifest[i]
-		if item.count < 1000 then
-			local hello = true
-		end
 		local keep_item = false
 		if item.type == "fluid" then
 			if total_liquid_left > 0 then
@@ -214,6 +212,9 @@ local function send_train_between(map_data, r_station_id, p_station_id, train_id
 			r_station.display_state = 2
 			update_display(map_data, r_station)
 		end
+		interface_raise_train_dispatched(map_data, train_id)
+	else
+		interface_raise_train_dispatch_failed(map_data, train_id)
 	end
 end
 
@@ -471,6 +472,7 @@ local function tick_poll_train(map_data, mod_settings)
 
 	if train and train.manifest and not train.se_is_being_teleported and train.last_manifest_tick + mod_settings.stuck_train_time*mod_settings.tps < map_data.total_ticks then
 		send_stuck_train_alert(train.entity, train.depot_name)
+		interface_raise_train_stuck(map_data, train_id)
 	end
 end
 ---@param map_data MapData
@@ -492,7 +494,6 @@ function tick(map_data, mod_settings)
 		map_data.economy.all_p_stations = {}
 		map_data.economy.all_r_stations = {}
 		map_data.economy.all_names = {}
-		map_data.tick_state = STATE_POLL_STATIONS
 		for i, id in pairs(map_data.warmup_station_ids) do
 			local station = map_data.stations[id]
 			if station then
@@ -504,6 +505,8 @@ function tick(map_data, mod_settings)
 				map_data.warmup_station_ids[i] = nil
 			end
 		end
+		map_data.tick_state = STATE_POLL_STATIONS
+		interface_raise_tick_init(map_data)
 		tick_poll_train(map_data, mod_settings)
 		tick_poll_comb(map_data)
 	end

cybersyn/scripts/global.lua

@@ -47,7 +47,7 @@
 ---@field public available_train_id uint?--train_id
 
 ---@class Train
----@field public entity LuaTrain
+---@field public entity LuaTrain --should only be invalid if se_is_being_teleported is true
 ---@field public layout_id uint
 ---@field public item_slot_capacity int
 ---@field public fluid_capacity int

cybersyn/scripts/layout.lua

@@ -3,8 +3,6 @@ local area = require("__flib__.area")
 local abs = math.abs
 local floor = math.floor
 local ceil = math.ceil
-local string_find = string.find
-local string_sub = string.sub
 
 
 local function table_compare(t0, t1)
@@ -73,6 +71,7 @@ function remove_train(map_data, train_id, train)
 		map_data.layout_train_count[layout_id] = count - 1
 	end
 	map_data.trains[train_id] = nil
+	interface_raise_train_removed(map_data, train_id, train)
 end
 
 

cybersyn/scripts/main.lua

@@ -25,8 +25,9 @@ local function set_comb1(map_data, station, manifest, sign)
 end
 
 ---@param map_data MapData
+---@param train_id uint
 ---@param train Train
-local function on_failed_delivery(map_data, train)
+function on_failed_delivery(map_data, train_id, train)
 	--NOTE: must change train status to STATUS_D or remove it from tracked trains after this call
 	local is_p_delivery_made = train.status ~= STATUS_D_TO_P and train.status ~= STATUS_P
 	if not is_p_delivery_made then
@@ -49,6 +50,7 @@ local function on_failed_delivery(map_data, train)
 	train.r_station_id = 0
 	train.p_station_id = 0
 	train.manifest = nil
+	interface_raise_train_failed_delivery(map_data, train_id, is_p_delivery_made, is_r_delivery_made)
 end
 
 
@@ -56,7 +58,7 @@ end
 ---@param map_data MapData
 ---@param train_id uint
 ---@param train Train
-local function add_available_train(map_data, train_id, train)
+function add_available_train(map_data, train_id, train)
 	local network_name = train.network_name
 	if network_name then
 		local network = map_data.available_trains[network_name]
@@ -66,6 +68,7 @@ local function add_available_train(map_data, train_id, train)
 		end
 		network[train_id] = true
 		train.is_available = true
+		interface_raise_train_available(map_data, train_id)
 	end
 end
 ---@param map_data MapData
@@ -74,7 +77,7 @@ end
 ---@param depot Depot
 ---@param train_id uint
 ---@param train Train
-local function add_available_train_to_depot(map_data, mod_settings, train_id, train, depot_id, depot)
+function add_available_train_to_depot(map_data, mod_settings, train_id, train, depot_id, depot)
 	local comb = depot.entity_comb
 	local network_name = get_comb_network_name(comb)
 	if network_name then
@@ -110,6 +113,7 @@ local function add_available_train_to_depot(map_data, mod_settings, train_id, tr
 				end
 			end
 		end
+		interface_raise_train_available(map_data, train_id)
 	end
 end
 ---@param map_data MapData
@@ -140,7 +144,9 @@ local function on_depot_built(map_data, stop, comb)
 		entity_comb = comb,
 		available_train_id = nil,
 	}
-	map_data.depots[stop.unit_number] = depot
+	local depot_id = stop.unit_number--[[@as uint]]
+	map_data.depots[depot_id] = depot
+	interface_raise_depot_created(map_data, depot_id)
 end
 
 ---@param map_data MapData
@@ -153,7 +159,9 @@ local function on_depot_broken(map_data, depot)
 		send_lost_train_alert(train.entity, depot.entity_stop.backer_name)
 		remove_train(map_data, train_id, train)
 	end
-	map_data.depots[depot.entity_stop.unit_number] = nil
+	local depot_id = depot.entity_stop.unit_number--[[@as uint]]
+	map_data.depots[depot_id] = nil
+	interface_raise_depot_removed(map_data, depot_id, depot)
 end
 
 ---@param map_data MapData
@@ -190,6 +198,7 @@ local function on_station_built(map_data, stop, comb1, comb2)
 	map_data.warmup_station_ids[#map_data.warmup_station_ids + 1] = id
 
 	update_station_if_auto(map_data, station, nil)
+	interface_raise_station_created(map_data, id)
 end
 ---@param map_data MapData
 ---@param station_id uint
@@ -205,7 +214,7 @@ local function on_station_broken(map_data, station_id, station)
 				local is_r_delivery_made = train.status == STATUS_R_TO_D
 				if (is_r and not is_r_delivery_made) or (is_p and not is_p_delivery_made) then
 					--train is attempting delivery to a stop that was destroyed, stop it
-					on_failed_delivery(map_data, train)
+					on_failed_delivery(map_data, train_id, train)
 					if not train.se_is_being_teleported then
 						remove_train(map_data, train_id, train)
 						lock_train(train.entity)
@@ -218,6 +227,7 @@ local function on_station_broken(map_data, station_id, station)
 		end
 	end
 	map_data.stations[station_id] = nil
+	interface_raise_station_removed(map_data, station_id, station)
 end
 
 ---@param map_data MapData
@@ -441,6 +451,7 @@ function combinator_update(map_data, comb)
 	local control = get_comb_control(comb)
 	local params = control.parameters
 	local old_params = map_data.to_comb_params[unit_number]
+	local has_changed = false
 
 	if params.operation ~= old_params.operation then
 		if (old_params.operation == OPERATION_PRIMARY_IO) and (params.operation == OPERATION_PRIMARY_IO_ACTIVE or params.operation == OPERATION_PRIMARY_IO_FAILED_REQUEST) then
@@ -450,6 +461,7 @@ function combinator_update(map_data, comb)
 			--NOTE: This is rather dangerous, we may need to actually implement operation changing
 			on_combinator_broken(map_data, comb)
 			on_combinator_built(map_data, comb)
+			interface_raise_combinator_changed(map_data, comb, old_params)
 			return
 		end
 	end
@@ -459,7 +471,6 @@ function combinator_update(map_data, comb)
 	local old_network = old_signal and old_signal.name or nil
 	if new_network ~= old_network then
 		on_combinator_network_updated(map_data, comb, new_network)
-		map_data.to_comb_params[unit_number] = params
 	end
 	if params.second_constant ~= old_params.second_constant then
 		local stop = global.to_stop[comb.unit_number]
@@ -477,7 +488,10 @@ function combinator_update(map_data, comb)
 				end
 			end
 		end
+	end
+	if has_changed then
 		map_data.to_comb_params[unit_number] = params
+		interface_raise_combinator_changed(map_data, comb, old_params)
 	end
 end
 
@@ -614,7 +628,7 @@ local function on_train_arrives_depot(map_data, depot_id, train_entity)
 				train.r_station_id = 0
 				train.manifest = nil
 			else
-				on_failed_delivery(map_data, train)
+				on_failed_delivery(map_data, train_id, train)
 				send_unexpected_train_alert(train.entity)
 			end
 		end
@@ -622,11 +636,13 @@ local function on_train_arrives_depot(map_data, depot_id, train_entity)
 			remove_available_train(map_data, train_id, train)
 			add_available_train_to_depot(map_data, mod_settings, train_id, train, depot_id, map_data.depots[depot_id])
 			set_depot_schedule(train_entity, train.depot_name)
+			interface_raise_train_parked_at_depot(map_data, train_id, depot_id)
 		else
 			--train still has cargo
 			lock_train(train_entity)
 			remove_train(map_data, train_id, train)
 			send_nonempty_train_in_depot_alert(train_entity)
+			interface_raise_train_nonempty_in_depot(map_data, depot_id, train_entity, train_id)
 		end
 	elseif is_train_empty then
 		--NOTE: only place where new Train
@@ -653,9 +669,11 @@ local function on_train_arrives_depot(map_data, depot_id, train_entity)
 		add_available_train_to_depot(map_data, mod_settings, train_id, train, depot_id, map_data.depots[depot_id])
 
 		set_depot_schedule(train_entity, train.depot_name)
+		interface_raise_train_created(map_data, train_id, depot_id)
 	else
 		lock_train(train_entity)
 		send_nonempty_train_in_depot_alert(train_entity)
+		interface_raise_train_nonempty_in_depot(map_data, depot_id, train_entity)
 	end
 end
 ---@param map_data MapData
@@ -685,7 +703,7 @@ local function on_train_arrives_buffer(map_data, stop, train_id, train)
 		elseif (train.status == STATUS_R or train.status == STATUS_R_TO_D) and train.r_station_id == station_id then
 			--this player intervention that is considered valid
 		else
-			on_failed_delivery(map_data, train)
+			on_failed_delivery(map_data, train_id, train)
 			remove_train(map_data, train_id, train)
 			lock_train(train.entity)
 			send_lost_train_alert(train.entity, train.depot_name)
@@ -719,6 +737,7 @@ local function on_train_leaves_station(map_data, mod_settings, train_id, train)
 					end
 				end
 			end
+			interface_raise_train_completed_provide(map_data, train_id)
 		elseif train.status == STATUS_R then
 			train.status = STATUS_R_TO_D
 			local station = map_data.stations[train.r_station_id]
@@ -752,6 +771,7 @@ local function on_train_leaves_station(map_data, mod_settings, train_id, train)
 			elseif fuel_fill/total_slots > mod_settings.depot_bypass_threshold then
 				add_available_train(map_data, train_id, train)
 			end
+			interface_raise_train_completed_request(map_data, train_id)
 		end
 	elseif train.status == STATUS_D then
 		--The train is leaving the depot without a manifest, the player likely intervened
@@ -769,7 +789,7 @@ local function on_train_broken(map_data, train_id, train)
 	--NOTE: train.entity is only absent if the train is climbing a space elevator as of 0.5.0
 	if not train.se_is_being_teleported then
 		if train.manifest then
-			on_failed_delivery(map_data, train)
+			on_failed_delivery(map_data, train_id, train)
 		end
 		remove_train(map_data, train_id, train)
 	end
@@ -781,7 +801,7 @@ local function on_train_modified(map_data, pre_train_id)
 	--NOTE: train.entity is only absent if the train is climbing a space elevator as of 0.5.0
 	if train and not train.se_is_being_teleported then
 		if train.manifest then
-			on_failed_delivery(map_data, train)
+			on_failed_delivery(map_data, pre_train_id, train)
 		end
 		remove_train(map_data, pre_train_id, train)
 	end
@@ -997,9 +1017,10 @@ local function main()
 
 				local train = map_data.trains[old_id]
 				if not train then return end
-				--NOTE: IMPORTANT, until se_on_train_teleport_finished_event is called map_data.trains[old_id] will reference an invalid train entity; very few of our events care about this and the ones that do should be impossible to trigger until teleportation is finished
+				--NOTE: IMPORTANT, until se_on_train_teleport_finished_event is called map_data.trains[old_id] will reference an invalid train entity; our events have either been set up to account for this or should be impossible to trigger until teleportation is finished
 				train.se_is_being_teleported = true
 				map_data.se_tele_old_id[train_unique_identifier] = old_id
+				interface_raise_train_teleport_started(map_data, old_id)
 			end)
 			flib_event.register(se_on_train_teleport_finished_event, function(event)
 				---@type MapData
@@ -1065,6 +1086,7 @@ local function main()
 					end
 					train_entity.schedule = schedule
 				end
+				interface_raise_train_teleported(map_data, new_id, old_id)
 			end)
 		end)
 	end

cybersyn/scripts/remote-interface.lua

@@ -0,0 +1,427 @@
+--By Mami
+local raise_event = script.raise_event
+local script_generate_event_name = script.generate_event_name
+
+------------------------------------------------------------------
+--[[all events]]
+------------------------------------------------------------------
+--NOTE: events only start to be raised when a mod has called its associated "get" function
+--NOTE: if there is a useful event missing you may submit a request for it to be added on the mod portal.
+
+local on_combinator_changed = nil
+local on_station_created = nil
+local on_station_removed = nil
+local on_depot_created = nil
+local on_depot_removed = nil
+local on_train_created = nil
+local on_train_removed = nil
+local on_train_available = nil
+local on_train_nonempty_in_depot = nil
+local on_train_dispatched = nil
+local on_train_dispatch_failed = nil
+local on_train_failed_delivery = nil
+local on_train_completed_provide = nil
+local on_train_completed_request = nil
+local on_train_parked_at_depot = nil
+local on_train_teleport_started = nil
+local on_train_teleported = nil
+local on_train_stuck = nil
+local on_tick_init = nil
+
+---@param map_data MapData
+---@param entity LuaEntity
+---@param old_parameters ArithmeticCombinatorParameters
+function interface_raise_combinator_changed(map_data, entity, old_parameters)
+	if on_combinator_changed then
+		raise_event(on_combinator_changed, {
+			map_data = map_data,
+			entity = entity,
+			old_parameters = old_parameters,
+		})
+	end
+end
+
+---@param map_data MapData
+---@param station_id uint
+function interface_raise_station_created(map_data, station_id)
+	if on_station_created then
+		raise_event(on_station_created, {
+			map_data = map_data,
+			station_id = station_id,
+		})
+	end
+end
+---@param map_data MapData
+---@param old_station_id uint
+---@param old_station Station
+function interface_raise_station_removed(map_data, old_station_id, old_station)
+	if on_station_removed then
+		raise_event(on_station_removed, {
+			map_data = map_data,
+			old_station_id = old_station_id, --this id is now invalid
+			old_station = old_station, --this is the data that used to be stored at the old id
+		})
+	end
+end
+
+---@param map_data MapData
+---@param depot_id uint
+function interface_raise_depot_created(map_data, depot_id)
+	if on_depot_created then
+		raise_event(on_depot_created, {
+			map_data = map_data,
+			depot_id = depot_id,
+		})
+	end
+end
+---@param map_data MapData
+---@param old_depot_id uint
+---@param old_depot Depot
+function interface_raise_depot_removed(map_data, old_depot_id, old_depot)
+	if on_depot_removed then
+		raise_event(on_depot_removed, {
+			map_data = map_data,
+			old_depot_id = old_depot_id, --this id is now invalid
+			old_depot = old_depot, --this is the data that used to be stored at the old id
+		})
+	end
+end
+
+---@param map_data MapData
+---@param train_id uint
+---@param depot_id uint
+function interface_raise_train_created(map_data, train_id, depot_id)
+	if on_train_created then
+		raise_event(on_train_created, {
+			map_data = map_data,
+			train_id = train_id,
+			depot_id = depot_id,
+		})
+	end
+end
+---@param map_data MapData
+---@param old_train_id uint
+---@param old_train Train
+function interface_raise_train_removed(map_data, old_train_id, old_train)
+	if on_train_removed then
+		raise_event(on_train_removed, {
+			map_data = map_data,
+			old_train_id = old_train_id, --this id is now invalid
+			old_train = old_train, --this is the data that used to be stored at the old id
+		})
+	end
+end
+---@param map_data MapData
+---@param train_id uint
+function interface_raise_train_available(map_data, train_id)
+	if on_train_available then
+		raise_event(on_train_available, {
+			map_data = map_data,
+			train_id = train_id,
+		})
+	end
+end
+---@param map_data MapData
+---@param depot_id uint
+---@param train_entity LuaTrain
+---@param train_id uint?
+function interface_raise_train_nonempty_in_depot(map_data, depot_id, train_entity, train_id)
+	if on_train_nonempty_in_depot then
+		raise_event(on_train_nonempty_in_depot, {
+			map_data = map_data,
+			train_entity = train_entity,
+			train_id = train_id,
+			depot_id = depot_id,
+		})
+	end
+end
+
+---@param map_data MapData
+---@param train_id uint
+function interface_raise_train_dispatched(map_data, train_id)
+	if on_train_dispatched then
+		raise_event(on_train_dispatched, {
+			map_data = map_data,
+			train_id = train_id,
+		})
+	end
+end
+---@param map_data MapData
+---@param train_id uint
+function interface_raise_train_dispatch_failed(map_data, train_id)
+	if on_train_dispatch_failed then
+		raise_event(on_train_dispatch_failed, {
+			map_data = map_data,
+			train_id = train_id,
+		})
+	end
+end
+---@param map_data MapData
+---@param train_id uint
+---@param is_p_delivery_made boolean
+---@param is_r_delivery_made boolean
+function interface_raise_train_failed_delivery(map_data, train_id, is_p_delivery_made, is_r_delivery_made)
+	if on_train_failed_delivery then
+		raise_event(on_train_failed_delivery, {
+			map_data = map_data,
+			train_id = train_id,
+			is_p_delivery_made = is_p_delivery_made,
+			is_r_delivery_made = is_r_delivery_made,
+		})
+	end
+end
+---@param map_data MapData
+---@param train_id uint
+function interface_raise_train_completed_provide(map_data, train_id)
+	if on_train_completed_provide then
+		raise_event(on_train_completed_provide, {
+			map_data = map_data,
+			train_id = train_id,
+		})
+	end
+end
+---@param map_data MapData
+---@param train_id uint
+function interface_raise_train_completed_request(map_data, train_id)
+	if on_train_completed_request then
+		raise_event(on_train_completed_request, {
+			map_data = map_data,
+			train_id = train_id,
+		})
+	end
+end
+---@param map_data MapData
+---@param train_id uint
+---@param depot_id uint
+function interface_raise_train_parked_at_depot(map_data, train_id, depot_id)
+	if on_train_parked_at_depot then
+		raise_event(on_train_parked_at_depot, {
+			map_data = map_data,
+			train_id = train_id,
+			depot_id = depot_id,
+		})
+	end
+end
+---@param map_data MapData
+---@param train_id uint
+function interface_raise_train_stuck(map_data, train_id)
+	if on_train_stuck then
+		raise_event(on_train_stuck, {
+			map_data = map_data,
+			train_id = train_id,
+		})
+	end
+end
+---@param map_data MapData
+---@param old_train_id uint
+function interface_raise_train_teleport_started(map_data, old_train_id)
+	if on_train_teleport_started then
+		raise_event(on_train_teleport_started, {
+			map_data = map_data,
+			old_train_id = old_train_id,--this id is currently valid but will become valid just before on_train_teleported is raised
+		})
+	end
+end
+---@param map_data MapData
+---@param new_train_id uint
+---@param old_train_id uint
+function interface_raise_train_teleported(map_data, new_train_id, old_train_id)
+	if on_train_teleported then
+		raise_event(on_train_teleported, {
+			map_data = map_data,
+			new_train_id = new_train_id,--this id stores the train
+			old_train_id = old_train_id,--this id is now invalid
+		})
+	end
+end
+
+---@param map_data MapData
+function interface_raise_tick_init(map_data)
+	if on_tick_init then
+		raise_event(on_tick_init, {
+			map_data = map_data,
+		})
+	end
+end
+
+
+local interface = {}
+
+------------------------------------------------------------------
+--[[get event id functions]]
+------------------------------------------------------------------
+
+function interface.get_on_combinator_changed()
+	if not on_combinator_changed then on_combinator_changed = script_generate_event_name() end
+	return on_combinator_changed
+end
+function interface.get_on_station_created()
+	if not on_station_created then on_station_created = script_generate_event_name() end
+	return on_station_created
+end
+function interface.get_on_station_removed()
+	if not on_station_removed then on_station_removed = script_generate_event_name() end
+	return on_station_removed
+end
+function interface.get_on_depot_created()
+	if not on_depot_created then on_depot_created = script_generate_event_name() end
+	return on_depot_created
+end
+function interface.get_on_depot_removed()
+	if not on_depot_removed then on_depot_removed = script_generate_event_name() end
+	return on_depot_removed
+end
+function interface.get_on_train_created()
+	if not on_train_created then on_train_created = script_generate_event_name() end
+	return on_train_created
+end
+function interface.get_on_train_removed()
+	if not on_train_removed then on_train_removed = script_generate_event_name() end
+	return on_train_removed
+end
+function interface.get_on_train_available()
+	if not on_train_available then on_train_available = script_generate_event_name() end
+	return on_train_available
+end
+function interface.get_on_train_nonempty_in_depot()
+	if not on_train_nonempty_in_depot then on_train_nonempty_in_depot = script_generate_event_name() end
+	return on_train_nonempty_in_depot
+end
+function interface.get_on_train_dispatched()
+	if not on_train_dispatched then on_train_dispatched = script_generate_event_name() end
+	return on_train_dispatched
+end
+function interface.get_on_train_dispatch_failed()
+	if not on_train_dispatch_failed then on_train_dispatch_failed = script_generate_event_name() end
+	return on_train_dispatch_failed
+end
+function interface.get_on_train_failed_delivery()
+	if not on_train_failed_delivery then on_train_failed_delivery = script_generate_event_name() end
+	return on_train_failed_delivery
+end
+function interface.get_on_train_completed_provide()
+	if not on_train_completed_provide then on_train_completed_provide = script_generate_event_name() end
+	return on_train_completed_provide
+end
+function interface.get_on_train_completed_request()
+	if not on_train_completed_request then on_train_completed_request = script_generate_event_name() end
+	return on_train_completed_request
+end
+function interface.get_on_train_parked_at_depot()
+	if not on_train_parked_at_depot then on_train_parked_at_depot = script_generate_event_name() end
+	return on_train_parked_at_depot
+end
+function interface.get_on_train_stuck()
+	if not on_train_stuck then on_train_stuck = script_generate_event_name() end
+	return on_train_stuck
+end
+function interface.get_on_train_teleport_started()
+	if not on_train_teleport_started then on_train_teleport_started = script_generate_event_name() end
+	return on_train_teleport_started
+end
+function interface.get_on_train_teleported()
+	if not on_train_teleported then on_train_teleported = script_generate_event_name() end
+	return on_train_teleported
+end
+function interface.get_on_tick_init()
+	if not on_tick_init then on_tick_init = script_generate_event_name() end
+	return on_tick_init
+end
+
+
+------------------------------------------------------------------
+--[[internal API access]]
+------------------------------------------------------------------
+--NOTE: The following, while they can be called from outside the mod safely, can cause serious longterm damage if they are given bad parameters. Extercise caution.
+
+---@param station_id Station
+---@param manifest Manifest
+---@param sign -1|1
+function interface.remove_manifest(station_id, manifest, sign)
+	local station = global.stations[station_id]
+	assert(station)
+	remove_manifest(global, station, manifest, sign)
+end
+---@param r_station_id uint
+---@param p_station_id uint
+---@param train_id uint
+---@param primary_item_name string?
+function interface.send_train_between(r_station_id, p_station_id, train_id, primary_item_name)
+	local train = global.trains[train_id]
+	assert(global.stations[r_station_id] and global.stations[p_station_id] and train and train.is_available)
+	send_train_between(global, r_station_id, p_station_id, train_id, primary_item_name)
+end
+---@param train_id uint
+function interface.failed_delivery(train_id)
+	local train = global.trains[train_id]
+	assert(train)
+	on_failed_delivery(global, train_id, train)
+end
+
+---@param train_id uint
+function interface.add_available_train(train_id)
+	local train = global.trains[train_id]
+	assert(train)
+	add_available_train(global, train_id, train)
+end
+---@param depot_id uint
+---@param train_id uint
+function interface.add_available_train_to_depot(train_id, depot_id)
+	local train = global.trains[train_id]
+	local depot = global.depots[depot_id]
+	assert(train and depot)
+	add_available_train_to_depot(global, mod_settings, train_id, train, depot_id, depot)
+end
+---@param train_id uint
+function interface.remove_available_train(train_id)
+	local train = global.trains[train_id]
+	assert(train)
+	remove_available_train(global, train_id, train)
+end
+---@param comb LuaEntity
+function interface.combinator_update(comb)
+	combinator_update(global, comb)
+end
+
+------------------------------------------------------------------
+--[[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 are unnecessary, the are provided more as a guide how the mod api works rather than as practical functions.
+
+function interface.get_map_data()
+	return global
+end
+function interface.get_mod_settings()
+	return mod_settings
+end
+---@param id uint
+function interface.get_station(id)
+	return global.stations[id]
+end
+---@param id uint
+function interface.get_depot(id)
+	return global.depots[id]
+end
+---@param id uint
+function interface.get_train(id)
+	return global.trains[id]
+end
+---@param train_entity LuaTrain
+function interface.get_train_id_from_luatrain(train_entity)
+	return train_entity.id
+end
+---@param stop LuaEntity
+function interface.get_station_or_depot_id_from_stop(stop)
+	return stop.unit_number
+end
+---@param comb LuaEntity
+function interface.get_station_or_depot_id_from_comb(comb)
+	local stop = global.to_stop[comb.unit_number]
+	if stop then
+		return stop.unit_number
+	end
+end
+
+
+remote.add_interface("cybersyn", interface)