Meta
- Type: request for comments
- Title: mod settings
Problem domain
Every mod with rare exceptions needs to deal with variable values -- either persistent or not -- that require user input. We'll call these "settings". Some examples of settings would be:
- Whether or not to enable particular functionality
- Preferred number of iterations of some loop
- A text string to use in certain cases
Noteably, it isn't correct to assume "settings" are what the user sees on a settings page of the club, more on that later.
It is therefore proposed to unify the code that deals with settings in a separate library so that mod authors don't have to invent and implement their own incompatible ways to that end.
Goals and non-goals list will be discussed later, after setting more context.
Entity analysis
Fundamentally, these entities are at play:
Type
Javascript is dynamic and weakly typed, but it does have types. Basically, for the purposes of this document, Type is twofold:
- what actual JSON type will the value have
- how to convert a string value (text that the user will input into the chat command) into an actual setting value
Emptiness
Whether the value can be empty or not. The language around this question is confusing, because English isn't formal, while Javascript is, so more correct term would be "Nullableness", but it's quite unwieldy. To try to mitigate any confusion, formal emptiness will be marked with all caps, like this: EMPTY.
The value is EMPTY if and only if one of the following is true:
- Setting doesn't exist
- Setting is null
- Setting is undefined
Noteably, zero or empty string or empty array or false aren't EMPTY values.
Default
Often, though not always, it makes sense to have a value that is used instead of an EMPTY value. This value is a Default value.
Validator
Tempting as it may be, defining custom types for values is unrealistic and serves no real purpose. Instead, any rules for determining valid values withing a given type constitute a validator.
Persistence
Whether, and how, the value will persist between the user's club sessions. More on that later.
Setting
Bringing all of the above together, a setting is a value of a particular type with emptiness specification, an optional default value, an optional validator, and a persistence specification.
Element
An important part of the problem is dealing with UI/UX, including GUI. An element is a club GUI control that is associated with a setting.
Page
Traditionally, GUI is organised using forms, but the club is much more centered around pages. A page is a collection of elements, with some important implications that will be, again, discussed later.
Migration
Code tends to change. New settings are added, old are discarded, things move around. One can not simply design the ultimate data structure from the get go. Migrations declare mutations of settings scheme. Noteably, the initial state is blank, any setting there is should come from a migration, including the ones that are essential to the mod, are declared right away and never change later. No exceptions.
UI/UX analysis
There are three main ways users interact with the club, all of them should be well supported:
- club GUI
- chat commands
- browser console
Let's go from simple to complex.
Browser console
The browser gives us ready to use tools for a well established interaction pattern, all that needs to exist is a set of callable functions. Care should be taken to utilise autocomplete functionality where appropriate and affordable.
Chat commands
Making a new command isn't a problem, the main challenge is making it easy to use, at least for people with a keyboard. Autocomplete is mandatory, however in absence of club native functionality it is proposed to outsource its mechanical implementation to a separate library, unless ready made options exist.
Club GUI
On a surface level it looks like an easy problem to solve: just have a manifest with element coordinates, however there are edge cases that bring a lot of nuance. One example would be LSCG's collar buy-in, which is custom code not easily packed into a declarative manifest. Still, from the user's perspective the club GUI offers a well established, if quirky, pattern of interaction with, well, somewhat rich palette of elements to more or less satisfy all common types of values. It shouldn't be hard to make use of it.
Interoperability analysis
As we propose a library, care should be taken to make it easy to use for actual mod authors to achieve everything (well, at least a sufficient part of) that they are now implementing independently.
Development time
Mod authors should have access to the current API documentation, examples and typedefs in order to make use of the library.
Load time
It is proposed to utilise FUSAM for load time dependency management, it should take care of everything, loading the library as a module and exposing it either as a global variable, or passing it to the mods that depend on it. As FUSAM itself is under development, the particularities of the load process is beyond the scope of this document.
Important note to consider
This library may become a part of FUSAM itself, especially if FUSAM will make use of it.
Run time
Having the module variable, mods can call the library API directly.