factorio-expcluster/exp_scenario

ExpGaming - Scenario

The Explosive Gaming scenario. It adds the in-game commands, guis and control modules players see on ExpGaming servers, and loads them into every instance as the exp_scenario save patch module.

Most parts of the scenario are features that can be turned on and off and configured from the web interface while the game is running. Permissions in game are clusterio permissions checked through exp_roles, so the plugin needs exp_roles, exp_groups, exp_reports, exp_server_list, exp_player_statistics, exp_commands, exp_gui and exp_util loaded as well.

Features

Each feature is registered in Lua with Feature.register from module/features.lua and declared again in features.ts with a title, description and the fields the web interface can edit. The defaults on both sides must match, test/features.test.js checks this.

The controller keeps one record per feature in database/exp_scenario/features.json with its enabled state and the values that differ from the default. On start it adds new features, deletes removed ones and drops stored values that no longer fit a field, logging a warning for each.

Edits are made on the Scenario Features page of the web interface. When a record changes the controller broadcasts it, and each running instance sends every value of the feature over RCON to exp_scenario.features.receive_update. Instances also fetch the full list when they start and when they reconnect to the controller. The Lua side keeps the last values in storage, so they survive saving and loading the map.

While a feature is disabled its event handlers do nothing, its commands are denied and its toolbar buttons are hidden.

Feature	Description
afk_kick	Kick everyone when nobody online is active.
autofill	Fill ammo and fuel into entities when they are built.
chat_auto_reply	Reply to key words in chat and run chat commands.
community_details	Community name and links, see below.
custom_start	Map settings applied when the map is created, and the items new players start with.
deconstruction_log	Write actions of players to log/deconstruction.log.
degrading_tiles	Tiles wear down as players walk and build on them.
death_markers	Map markers, lights and lines to corpses, and collecting expired corpses into chests.
discord_alerts	Write alerts for the Discord bot on bans, mutes, kicks, jails and logged commands.
extra_logging	Write rockets, deaths, research, joins and leaves to a log file.
greetings	Greet players when they join and show their join message.
help_bubbles	A compilatron at spawn that cycles through tips and the community links.
inventory_clear	Move the items of banned and kicked players to a chest at spawn.
lawnmower	The /lawnmower command.
mine_depletion	Deconstruct mining drills when their resources run out.
module_inserter	A selection tool that fills machines with modules.
nuke_protection	Remove banned items from players without the bypass permission.
player_bonus	Points players spend on personal bonuses.
pollution_grading	Scale the pollution overlay.
popups	Flying text for chat messages and damage.
protection	Stop players removing protected entities placed by others.
repair	The /repair command.
research	Research effects such as bonus inventory slots.
research_milestones	A gui tracking research against target times.
rocket_info	A gui with rocket launch statistics and silo progress.
science_production	A gui with the production of each science pack.
spawn_area	Build the spawn area when the first player joins.
station_auto_name	Name train stops when they are built.
task_list	A shared list of tasks.
warp_list	Warp points players can travel between.
vlayer	A shared virtual surface for solar panels, accumulators and storage.

community_details holds the community name and the Discord, website, status page, GitHub and Patreon links. Chat replies, the readme gui, the help bubbles and the greeting read them. They are always used, the enabled switch has no effect.

Some settings are not features. Data tables such as the bonuses in config/player_bonus.lua and the research targets in config/research_data.lua are only changed by editing the module.

Adding a feature

Register it in the Lua file that uses it and guard the handlers:

local Feature = require("modules/exp_scenario/features")
local feature, config = Feature.register("my_feature", {
    show_message = true,
    role_id = Feature.optional("number"),
    item_names = Feature.set{ "iron-plate" },
    section = { count = 1 }, -- edited as "section.count"
})

return feature:guard{ events = { ... } }

Commands take :add_flags{ feature = feature }. Read config where it is used, the table is updated in place. Then add an entry with the same name and defaults to features in features.ts, or the web interface can not configure it. Values read while the file loads, such as on_nth_tick periods, can not be changed at runtime and are left out of features.ts.

Seed

The Seed roles and groups button on the Roles page creates the roles and Factorio permission groups the scenario used before roles moved to the controller. It needs the exp_scenario.seed permission and the exp_roles and exp_groups plugins.

It creates 13 roles, Senior Administrator down to Regular plus Jail. The controller's admin role becomes System and its default role becomes Guest, the seed sets their short hand and colour but not their permissions. Each role also gets the permissions of its parent in the seed, the way the old config inherited them. Regular is auto assigned after 3 hours played and Veteran after 10. Jail has priority 1 and blocks auto assignment.

It creates the permission groups Admin, Trusted, Standard, Guest and Restricted, and maps each role to one of them, higher roles getting a higher mapping priority.

It can be run again. Roles that already exist by name keep their permissions and gain the seeded ones. Groups that already exist by name are reset to the seeded input actions.

Player settings

The controller keeps some settings per player in database/exp_scenario/players.json, so they follow a player between servers:

• Join message. Printed to everyone when the player joins, unless greetings is disabled. Set in game with /set-join-message and removed with /remove-join-message, or edited on the user page of the web interface. Up to 255 characters.
• Toolbar. The order and state of the player's toolbar buttons, sent when they leave and restored when they join.

Permissions

Permission	Description
exp_scenario.config.view	View the Scenario Features page.
exp_scenario.config.edit	Edit features on the Scenario Features page.
exp_scenario.seed	Seed the roles and permission groups.
exp_scenario.join_message.set	Set your own join message from the web interface.
exp_scenario.join_message.set_other	Set the join message of other users.

Users can always see their own player settings on the user page, core.user.get allows it for other users.

permissions.ts defines another 109 permissions checked in game through exp_roles. They are grouped by prefix: exp_scenario.command.* for each command, exp_scenario.gui.* for guis and their actions, exp_scenario.bypass.*, exp_scenario.decon.*, exp_scenario.player.* and exp_scenario.chat.commands. Every command checks exp_scenario.command.<name> with hyphens replaced by underscores, including commands added by other ExpGaming plugins such as /server-ups. 24 of them, mostly guis and informational commands, are granted by default.

Lua

The module is split into:

• commands/ the chat commands, plus _authorities.lua for the permission and feature checks, _rcon.lua for the /_rcon environment and _types.lua for argument types.
• control/ event handlers that run without a gui, such as afk kick, protection and the spawn area.
• gui/ the guis and toolbar buttons, with the debug gui in gui/debug/.
• config/ data tables and some feature registrations, such as community_details.lua and spawn_area.lua.
• features.lua the feature registry described above.

exp_scenario.features and exp_scenario.player_settings are globals so the instance plugin can call them with /sc.