feat: mode command

[keithharvey]

Adds a /mode easy_tax resource_sharing_tax=0.5 command with the mode being required, and every parameter after that being an optional unlocked mod option. This allows users to customize that mode from its defaults, or just short-hand the mode itself and skip the details. Right now, the modes are focused on co-op solutions but they could be expanded to other categories, so mode seems appropriately general.

In chobby, this calls a vote on the set highlighting any differences from the mode defaults.

Testing: Working on testing this now.

LLM Disclosure: Opus 4.6, but read it then re-read it and it looks correct.

Issue: beyond-all-reason/BYAR-Chobby#1040

[Yaribz]

I'm not sure I understand the goal of this PR.

After taking a brief look at the code, it seems this new mode command does nothing with the first parameter (except printing it back in response) and the other parameters are used to apply multiple modoptions changes in one go.
Battle presets are the usual way to implement grouped modoptions changes, and this is already supported by SPADS core.

Maybe if you explain what functionality you need exactly I can try to answer better.

Regarding the code itself:

• it's missing the help part of the command (every command in SPADS core has its goal and usage briefly explained in the help.dat file, which makes it possible to generate the online documentation and allows users to use !help mode for example)
• when planning to submit a PR to SPADS core, I strongly recommend to get in touch with me first to check two things: 1) Doesn't SPADS already offer a way to do what you want ? 2) Is it really a sufficiently fundamental and global functionality to be included in SPADS core instead of implementing it in a plugin ?
• the goal of the SPADS plugin interface is precisely to allow anyone to add any new functionalities to SPADS without requiring any change in SPADS core. So anyone is really free to customize SPADS the way he wants, especially adding new commands for instance. There are even tutorials that show how to do that very easily in Python or in Perl. An AI should be able to do that very easily when pointed to these resources.

[keithharvey]

Thanks for the detailed feedback!

So we're building a mode system in BAR where players can switch between curated gameplay configurations (e.g. "Easy Tax" bundles specific sharing/economy options together). The problem it solves is that currently, changing a "mode" requires voting on each mod option individually, which creates a wall of sequential votes. !mode bundles them into a single vote.

You're right that SPADS doesn't do anything functional with the mode name, and that's intentional. The mode name gets passed through to the vote message, and Chobby uses it client-side to look up the mode definition (which lives in the game archive) and render a rich vote panel showing the mode name, defaults, any deviations the player made, and which optional options are being disabled. SPADS just needs to validate and apply the key=value pairs.

I did look at battle presets, but those seem to be server-admin configuration (defined per SPADS instance in battlePresets.conf). Modes are game-shipped definitions that live in the BAR game archive (modes/*.lua) with typed schemas shared with modoptions.lua. They're a game design concept, not a server config concept. That said, I can see them potentially converging in the future.

Totally open to moving this to a plugin instead of a core change, that makes sense. I'll look at the plugin tutorials and rewrite it as a standalone plugin. Will close this PR once that's ready. Good catch on the missing help.dat entry too, will add that to the plugin version.

Sorry for not reaching out first, lesson learned! Happy to discuss the design further.

[keithharvey]

Went ahead and did that, had most of this commit already done but just needed the plugin part, much better thank you! beyond-all-reason/BYAR-Chobby@0f474e4

I might reach out to you and ask for help on the best way to set up a test harness/emulate a vote for this plugin.

[Yaribz]

Ok I see. Making SPADS aware of these game-defined modoption presets so that it can use them directly as such might be more efficient, but I understand the use case better now.

Regarding your plugin code, it seems it no longer checks that the modoption definitions provided as !mode command parameters are correct (see updateSetting function doc: "The new value provided by the plugin is not checked: the plugin is reponsible for providing only correct values."). In particular it doesn't check that:

• the modoptions exist for current selected game (i.e. modoptions declared by the game)
• the modoption values are valid (i.e. correct types, as declared by the game)
• the modoption values are allowed (i.e. according to current SPADS battle preset)

This means that a user could put the lobby in an incorrect state by calling the !mode command manually with incorrect parameters for instance.

In your ModeCommandHelp.dat file, you don't need to use indentation, nor prefix the example lines with Ex: . This file is actually a data file, SPADS already knows that for each command the first line is the usage and the following lines are examples. It will present the data correctly to the user according to these rules. Also, the syntax for the example lines is: command example between double quotes followed by description (cf the example file from the tutorials)

Regarding automated tests, I usually use my own lobby server emulation module in Perl which offers ways to simulate players joining, calling commands etc. Unfortunately it's not documented and it would take some time to explain everything...
Maybe I should reorganize the lobby interface module a bit to make it easier to inplement automated tests directly from the plugins. Plugins could then call lobby interface module functions to simulate events such as players joining the lobby, entering commands etc.

[Yaribz]

I realize a isSettingValueAllowed function might be useful in the plugin API to complement the updateSetting function btw, maybe I will add something like that in the API.

[Yaribz]

I added the isSettingValueAllowed function to the plugin API, so fixing your code just consists in adding a call to this function to check the values before performing the configuration changes.

[keithharvey]

Maybe I should reorganize the lobby interface module a bit to make it easier to implement automated tests directly from the plugins. Plugins could then call lobby interface module functions to simulate events such as players joining the lobby, entering commands etc.

It would be interesting if we incorporated your perl module layer as a script in BAR-Devtools, maybe? That's what I'm using to boot the stack so it would fit nicely. The tests don't need to be automated in this case, that would require me have some sort of bootstrapped test runner in Chobby which I did not intend to set up for this spike.