Tweaking 3rd Party Plugins

[alice-i-cecile]

3rd-party plugins are great. But what happens if you need to change how they work?

There are two extremes here:

1. Black-box plugins: you cannot reuse any of the systems, modify its internal resources or modify how and when they are run in any way.
2. White-box plugins: you can completely reuse any of the systems, freely modify its internal resources or modify how and when they are run in any way.

Both have their merits. The black-box approach:

1. Simple, easy to use. You add a plugin, and it will work the same way forever.
2. Hard to screw up in non-obvious ways.
3. Less likely to break when the plugin is patched.
4. Doesn't require (or really benefit from) internal knowledge of how the plugin works.

The white-box approach:

1. Infinitely configurable to match your app's needs.
2. It's easy to replace parts of the plugin as your needs grow and change.
3. Easier to hook into, in case you want to intercept part of the plugin's data processing pipeline.
4. Much easier to debug when conflicts arise.

As raised by @cart in #1512, these questions parallel those of public APIs in general, and the pub and module framework in Rust itself. Rather than aiming for either extreme, we should be encouraging plugin authors (including Bevy itself) to define and expose thoughtful public APIs to hook into.

Types of conflict

Why might we want to interfere with a plugins internals? Here's my best attempt at the important use cases:

1. Resolving system ordering ambiguity bugs, especially between two third-party plugins. This is much less critical if System-order-independent ECS change tracking #68 is fixed, but can still result in strange behavior or frame lag.
2. Pausing the behavior of plugin in some states
3. Hijacking the plugins data stream, either to read from it, or to modify the plugin's behavior
4. Replacing parts of the plugin
5. Better synchronous performance of systems between plugins by moving them all safely to the same stage
6. Unusual, advanced control flow: plugin assumptions may be violated badly if the basic "every system runs once" pattern is heavily modified (as you might see in server-client architectures, turn-based games, or other yet-unexplored space)

What can be changed?

Systems are by far the largest part of every plugin, and the most contentious.

Resources and entities that a plugin might use, under the current design, can usually be queried for and then overridden or removed. This is impossible if the underlying types are not made pub however.

There are a number of ways we can configure systems, all of which we might want to be able to tweak for plugin systems:

1. Which plugin systems are added to the schedule at all
2. The order of plugin systems:
   a. relative to other systems in the same plugin
   b. relative to other systems in other plugins
   c. relative to user systems
3. Which stage the plugin systems run in
4. Whether plugin systems are controlled by a run criteria
5. Which states the plugin systems run in
6. Post 0.5: What many-to-many labels apply to the systems, and which external systems share a plugin's labels
7. Post 0.5: if and how a system is run asynchronously

Each of these items is worth considering on its own merits.

How can we change system behavior?

Ultimately, there seems to be consensus that many-to-many labels, as discussed in #1375, are the ideal solution for system configuration of this sort in general.

They should allow for intuitive modification of the system properties discussed above, without requiring repetitive, easy-to-omit boilerplate on every system.

Stop-gap solutions for 0.5

Unfortunately, many-to-many labels aren't going to make it into 0.5. In the meantime, we need to provide users the ability to avoid some of the worst of these difficulties. Easy solutions:

1. Label most or every system in DefaultPlugins. This may or may not include generated systems like those used for event-cleanup.
2. Keep each plugin within DefaultPlugins in a stage of its own. This removes much of the benefit of the fancy new scheduler from System sets and parallel executor v2 #1144, but it is certainly safe.

If neither of these are adequate (say, if adding run criteria to plugin systems is deemed critical), we may need to either implement multiple labels for 0.5 or some more complex stop-gap.

How can the desired solution be enforced?

1. Naive automatic labelling forces every system to have a label. IMO, it would make a lot of sense to automatically generate labels for systems if and only if the function is pub from the current scope.
2. Community guidelines for what must / should have labels and be pub. Eventually, this could be enforced in Bevy's library discovery tools.

[Ratysz]

Unfortunately, many-to-many labels aren't going to make it into 0.5.

They did, #1576.