Plugins should be more customizable and work with states

[alice-i-cecile]

Bevy version

0.5

Problem description

1. Many plugins add interesting and valuable gameplay systems.
2. States are very commonly used to control whether a game's core systems operate, such as creating a Paused or Loading state.
3. Systems added in plugins are inserted into the stage and state that the plugin author set, with no way to change this.
4. System labels cannot be added to systems added via plugins.

The State problem here is side effect of the fact that we cannot add run criteria to systems added in plugins.

Potential solutions

Solution 1: Everything is pub

Rather than trying to solve this directly, the Bevy community forces plugin authors to make all of their systems (and supporting types) pub.

Users then reconstitute the plugins from scratch by adding the systems etc. on their own terms in their own code to get the interoperability they need.

This is bad because it creates cluttered, confusing APIs and exposes details that should be internal carelessly. This then causes every non-trivial plugin crate version to have breaking changes.

It is also very heavy on boilerplate.

Solution 2: Just fork it

As Solution 1, but users fork all plugins (and the engine) and forcibly make the things they need pub / make the changes they need.

Like Solution 1, but shifts the maintenance burden and headaches to the end users.

Very bad for user experience and ecosystem fragmentation.

Solution 3: Post-hoc configurability

Allow users to set the stages / states / run criteria of all systems in a plugin at once.

This doesn't involve any changes to our logic, and patches the most pressing issues.

However, it starts to break down pretty badly if you need to have plugins with systems that cannot coexist in the same stage or state: startup systems and those that must be separated by commands are particularly common and painful here.

Solution 4: Plugins contain only one system set

As solution 3, but each plugin can only have a single system set.

Solves the problems above, but makes their common use more onerous.

Solution 5: App as a structured object

Completely rework how App works by replacing the "mutate the entire AppBuilder" approach with one where the AppBuilder (and App) have carefully structured fields that you can mutate regardless of the visibility of the field.

To solve this particular issue:

1. All systems belong to a system set, and the app can have any number of system sets.
2. Each system set must have a label (although it might be automatically generated).
3. All system sets can be modified using their label after their insertion into the AppBuilder.
4. Each plugin contains their own app in this way, and their labels are exposed to the larger app that they make up.
5. The App is not constructed until .run is called, at which point it is constituted in a deterministic order that is independent of insertion order.

Solves #1255, which would be great for clarity and ease of refactoring. This would be a serious endeavor though, and might limit users ability to throw new ad-hoc behavior onto the AppBuilder (not that I've ever seen anyone try?).

This is a sensible compromise on the level of granularity and visibility that plugins expose, grouping their functionality into configurable units.

Conclusions

Solution 1 is the de-facto standard right now for the Bevy engine, as virtually all of our systems are pub. Solution 2 is what will happen if we do nothing (or advanced users instead develop severe NIH syndrome). Both of these are pretty terrible.

Thus, we need a thoughtful approach to configuration. Solutions 3 and 4 are somewhat better than what we have now as they allow more than 0 configurability, but are almost certain to fall short in real use.

I am in favor of Solution 5, but this needs some serious thought. If you want to make an RFC, go for it! Otherwise, I'll probably get around to it after 0.6 launches due to other priorities.

Of course, all of these problems get dramatically worse once we have large games and an editor, and want to examine and manipulate systems visually.

[Nilirad]

A bit of context about AppBuilder and App

AppBuilder wraps an App.

The App struct contains a World, a Schedule, and a runner function.

Bevy plugins (first or third party), implementing the Plugin trait, expose the build method, that takes &mut app: AppBuilder as a parameter. Therefore, plugins are able to edit any field of the underlying App.

The problem

The property of a plugin to be added with no configurability (at least by default), can have its pros and cons.

The major concern that comes to my mind is relevance of builder method order. This comes from the fact that some methods overlap and end up overwriting previous data or other kinds of stuff. For example, you can have two plugins, A and B, that both add a SystemStage (i.e. a stage) after Bevy's Update stage. Based on order of plugin addition we get different stage order results:

With A then B:

'Update' -> 'B' -> 'A'

With B then A:

'Update' -> 'A' -> 'B'

A possible solution

Solution 5 seems the best decision when compared against the others. It will require the most work, but it will give us the most benefits in the long run.

About system reordering, it's ok to give the user the chance of moving them around, but there should be constraints. I'll explain.

Once, I had to fix an obscure bug on bevy_prototype_lyon (the API consists in you creating a stub object with a description that gets completed later) where meshes for the shapes weren't generated. Then I discovered that moving the mesh-generating system to a new stage after 'Update' solved the problem.

Therefore I think that it's ok to give the user the ability to reorder system sets within a stage, but they should not be able to move them to other stages, since stages are kind of hard boundaries. Also, stage reordering should be limited to only across plugins. If we take the previous example, you shouldn't be able to have a stage configuration like the following:

'A' -> 'Update' -> 'B'

since that would break the 'Update' -> 'A' stage configuration requirement that the A plugin author originally intended. In poor words, configuration is only allowed where plugins don't know each other (A doesn't know B and vice versa).

The solution that I see is one where a Plugin is made of smaller building blocks that the client can (not must) move around (with some well thought limitations) to their needs.

[alice-i-cecile]

For others who may encounter this before we fix it properly: I hand-rolled a solution for allowing the end user to control which state if any a plugin's system runs.

You can examine it here: it's reasonably nice, but must be added to each plugin ahead of time and adds significant boilerplate.

[pjankiewicz]

Just want to add from the other issue (#4362) that I think you should also analyze in what circumstances people what to change the plugin behaviour. In my case I just wanted to disable the plugin under some conditions and something like:

app.add_plugin_with_criterium(PluginA, some_criterium_system)

or inheriting System Set

app.add_plugin(PluginA.with_run_criteria(some_criterium_system))

Would solve the problem.

I'm a new Bevy user and I found it a little bit confusing that plugins and System Sets have different functionalities. In my opinion when someone writes a plugin that is just a single System Set then it shouldn't be in fact a Plugin but a System Set. This makes it possible to use every functionality of a System Set in this case. So a solution in this case would be not to allow creating objects which behave in the same way but are different type. I think it makes me vote for 4th solution. Maybe creating SystemSetPlugin could be an option.