feat(mods): Add first iteration of mod API

This PR is a first step towards supporting mods.

It is regarded as very experimental.

Why

From time to time I get requests to implement things which I know I'll not implement. Either because it's just something I don't see the value of, other things that I would like to tackle first or because I don't have the actual skills to implement it myself to a satisfactory degree.

Some ideas I do see the value of, but it's so niche that adding it to the main code base is just extra load for the vast majority of the users.

Mod support would allow some of these things to still see the light of day.

Server configuration

There will be multiple iterations of this as this is completely new territory for me too!

This first iteration will allow server owners to add .js (potentially accompanied by a .css file) files to a new folder /static/mods. This folder structure will change in the future, when a more proper system of adding mods and enabling/disabling mods is worked out.

Right now mods added will be enabled for all users on the server. I'm highlighting this to make it clear that this is really expected to be experimented with in local/private setups and not in setups used by many people at this point in time.

The Mod API

Mods will be able to access most of PA's internal functions. In particular access to all systems and their state is provided, which should allow you to interact with the majority of features. Some additional APIs that are not provided through these systems are also exposed.

There will be plenty of things that you might want to do, that PA does not offer a specific function for yet, this is normal, feel free to request certain things! For the examples I made, I had to add some things as well. The main location where you'll need extra hooks is to create/integrate with certain UI components.

Eventually (if there is actually any interest) there will be an official API package that offers all the types etc. At this point in time you'll just have to define them yourself. You can do this by looking at the api package in the example repo linked below.

I am well aware that it's not going to be an obvious task for any person to just start making mods as the internals of PA are not documented in a nice developers portal, so feel free to ask me anything.

Currently your mod will be called when:

A PA page has loaded (after login), this can be the dashboard, an actual game session, it's just a place to potentially load stuff
A game has been loaded
A location has been loaded

These should for now be useful enough entry-points, but let me know if other things are interesting.

Also important to note is that mods will only run client-side. No server-side code can be provided. Server-side storage is however supported in the form of the recently added DataBlocks.

Examples

As an effort to show a bit how one could interact with PA, I made two sample mods in a separate repository. These can be build and added to the aforementioned mods folder as is.

They are extensively documented and mostly function as examples of interacting with the API, not necessarily as finalized mods to be used.

Example mod repository: https://github.com/Kruptein/planarally-mods

The Future

As mentioned before, there should be a proper UI for adding/removing/enabling/disabling mods as a user, without having to interact with the server owner.

Whether or not the rest of the API will see expansion will depend a bit on whether or not there actually is any traction. I honestly don't really expect much here, but I've been surprised before :D

Kruptein / PlanarAlly