Player State Management, Now And In the Future

[zicklag]

A reply to #195 (comment).

---

OK, I had another idea which I'm going to brain-dump here. Forgive the length and ambition and anything that I might have missed that might make this all pointless. 😜

SparseSet Components Instead of Events

We can use components with SparseSet storage to trigger actions on the player in other systems, instead of using events. SparseSet storage is important because we an add and remove components with SparseSet storage more efficiently without causing archetype table moves.

Note: If you haven't seen it before, a sparse set component in Bevy is made with just an extra attribute on the derive:

#[derive(Component)]
#[component(storage = "SparseSet")]
struct MyComponent;

For instance, when we want the player to flop, would add a ShouldFlop component to the player entity that we want to flop. Then the system that makes the player flop would iterate through all players with the ShouldFlop component. That way we let Bevy handle efficiently iterating through all the entities that we need to worry about flopping or moving, etc.

I feel like this could be a good idea regardless of the rest of this comment which is far more ambitious and possibly overreaching for what we should do right now.

Extensible Player Actions/Effects

This got me thinking about the bigger scheme of things and how we would manage scriptable actions and even things like player effects later.

What if we structured it so that each player state would be governed by a system responsible for controlling the player while they are in that state. The state of the player would be represented by a component on the player.

For instance, let's consider the following state systems and their components:

• System: idle, Component: Idling
• System: flop, Component: Flopping
• System: move, Component: Moving { velocity: Vec2 }
• System: fall, Component: Falling { from_super_move: bool } ( handles when the player is getting hit )

If the player is flopping, they will have a Flopping component and the flop state will operate on that player and be responsible for modifications to the player such as animation frames, movement, etc.

Additionally, whatever state the player is in is responsible for triggering transitions to other states. For instance, if the player is flopping, they won't stop flopping until the flop system willingly removes the Flopping component and adds another state component.

Inputs and Attempted State Transitions

Finally, we have to manage input both from the player gamepad/keyboard and from other player influencing factors such as attacks that are hitting them, etc. For instance we could have the following systems that will want to try and control the player:

• player_input: This system grabs input from the ActionState that is generated from our controller bindings and will want to cause the player to move or start flopping, etc. when buttons are pressed.
• enemy_attacks: This system will want to trigger the player Falling when the player gets hit by an attack.

Each player will have a PlayerStateEvents component added to it that will simply be a vector containing all the events that are sent by systems that are attempting to control the player. We use this instead of normal Bevy events because each event should only be handled once, and only by the system for the players currently active state.

For instance, if we are currently Flopping, the flop system will run on the player and drain(..) all of events out of the player's PlayerStateEvents component and handle them as it deems fit. Each event will be a PlayerStateEvent defined like so:

struct PlayerStateEvent {
    /// The `ReflectComponent` of the state component we want to transition to
    target_state_component: ReflectComponent,
    /// The data of the component we want to transition to
    target_state_data: Box<dyn Reflect>,
    /// The priority of the state transition
    /// 
    /// A priority of `i32::MAX` should usually be transitioned to immediately regardless of
    /// the current state.
    priority: i32
}

This is where things get interesting. Because we could end up with any number of player states eventually, and ones that have been added by scripts, for that matter, we can't have an enum that lists all of the possible states we might need to transition the player to. Therefore we must have our PlayerStateEvent contain the information needed to transition to the new state, even though the current state may not know what actual component type to add at compile time.

That is where the power of ReflectComponent and Box<dyn Reflect> come into play.

We will implement a DynamicCommands system parameter that acts just like Commands, but that has an additional method for inserting components not known at compile time from it's ReflectComponent and Box<dyn Reflect>.

Flopping Example

Let's consider a hypothetical flop system. It could be implemented like this:

const FLOP_PRIORITY: i32 = 10;

/// Control the player while we are flopping
fn flop_system(
    // This will act just like commands, with additional methods for inserting dynamic components.
    mut dyn_commands: DynamicCommands,

    // Queries all the players that are flopping
    players: Query<(Entity, &mut PlayerStateEvents, &mut PlayerAnimations), With<Flopping>>
) {
    for (entity, player_events, animations) in &mut players {
        // This is just illustrative of what the system might do
        let is_flop_finished = animations.play_flop_animation();

        // Now we loop through any attempts to change our state
        for event in player_events.drain(..) {

            /// If they want to transition to a falling state
            if let Some(falling) = event.target_state_data.downcast_ref::<Falling>() {

                // And we we are falling from a super move
                if falling.from_super_move {

                    /// Transition to the falling state
                    dyn_commands
                        .entity(entity)
                        .remove::<Flopping>()
                        .insert_dynamic(event.target_state_component, event.target_state_data);

                } // We don't need to stop flopping for non-super moves

            // Otherwise, if the event has a higher priority than flopping
            } else if event.priority > FLOP_PRIORITY {

                // Transition to the new state without asking questions
                dyn_commands
                    .entity(entity)
                    .remove::<Flopping>()
                    .insert_dynamic(event.target_state_component, event.target_state_data);
            }

            // Ignore any other events such as moving, flopping takes priority
        }

        // If we are done flopping
        if is_flop_finished {

            // Transition back to the idle state
            commands.entity(entity).remove::<Flopping>().insert(Idling);
        }
    }
}

With this design, we can add new attacks and fighter moves in Rust and in scripts without having to know them all upfront, and each state can intelligently decide when to transition out of the state.

Summary

At this point you can probably imagine how you might implement the other states:

• idle would be very low priority and would transition to whatever the highest priority event it gets in a given frame without asking questions.
• move would transition back to idle every frame, so that you would stop moving as soon as the player released the button
• fall would work similar to flop

There could be things I'm missing, and I wouldn't really know if this would work well without trying it, but there's the idea!

[zicklag]

I'm going to experiment to see if I can test out something in this direction to see if anything glaring comes up to make it not possible/reasonable.

[zicklag]

I'm making progress on the design attempt and so far I don't see any glaring issues yet. I think I'm going to try to finish out a prototype implementation and then get review to see if it actually helps anything other than scripting.

[64kramsystem]

We can use components with SparseSet storage to trigger actions on the player in other systems, instead of using events. SparseSet storage is important because we an add and remove components with SparseSet storage more efficiently without causing archetype table moves.

Which scale is this game expected to reach? Beat 'em ups should be very lightweight, so I think performance shouldn't be a concern. If it comes for free, sure 😄

[zicklag]

Which scale is this game expected to reach?

I'm not sure, but I don't think we're going to have scaling issues.

SparseSet components are specifically supposed to be cheap to insert and remove, and while it wasn't in Bevy specifically I know of a guy who used temporarily placed components like that for events extensively with a SparseSet based ECS and he seemed to think it worked very well and was a useful design model.

So I think there isn't a performance cost for it but it might be good to ask on the Bevy discussions just to see what other people's thoughts are.

[zicklag]

Opened a discussion about performance: bevyengine/bevy#5553.

[64kramsystem]

even though the current state may not know what actual component type to add at compile time.

He. Interesting; I didn't think that the states could be extended 😅 I think I understand the architecture described.

[odecay]

I'm not sure the sparse set thing will matter for us based on the amount of components/entities I expect we will end up with, unsure about that as your starting point for basing the design off/if it's premature optimization

I'm not yet 100% sold yet and haven't quite pieced together implications for scripting/extensibility.
However, there are multiple aspects of the "Ambitious" part of the design that I like.

Using components as state is really nice because you can just directly query for the components, and have a system/systems responsible for behavior. I think it would end up with systems that are very readable/maintainable.
(Ofc we will have to account for command application when adding and removing components to transfer between states, so we might end up with a limited amount of state transitions per frame although this should/could be handled by the priority properties). Another thing that this lets us do is have "state" that is described by more than a single component. Composable state? Eg we have hitstun and knock back components, both or either could be applied, causing movement to be applied in knock back system and disallowing the character from taking actions till the hitstun frames elapse in hitstun system.

I really like the input priority handling stuff, this would be something similar to what that the parsing system in an input buffer would usually require to decide priority of actions based on sets of inputs over a certain window #148, so it's something that I was already imagining to be in future design. What I was going to implement for the event buffer sounds very similar to what you are suggesting for the player input event component, only extended over a multi frame window so as to account for actions triggered by sequential inputs. (and maybe would not drain?)

I'm going to keep chewing it over. I look forward to looking at code if you want to put up a draft PR.

[odecay]

I feel like this sort of change in thinking about our state model might imply some change in our animation systems to better fit together, but will think on that more as well.

[odecay]

Another thing we might consider for managing state transitions could be something some sort of Tree data structure of states.

[zicklag]

I'm going to keep chewing it over. I look forward to looking at code if you want to put up a draft PR.

Absolutely. I'm trying to get that made as soon as possible.

I'm not sure the sparse set thing will matter for us based on the amount of components/entities I expect we will end up with, unsure about that as your starting point for basing the design off/if it's premature optimization

The motivation for using components was their dynamic nature and the ability to use them in query filters. The SparseSet thing is just a simple flag on the components that makes it more efficient to add and remove. I'd just heard before that it's not as good to add and remove components frequently with archetype-based ECS storage.

(Ofc we will have to account for command application when adding and removing components to transfer between states, so we might end up with a limited amount of state transitions per frame although this should/could be handled by the priority properties).

I found a way to create a custom command buffer that's gets flushed before the normal commands, before the state handler systems actually run. That might solve that issue.

Now I've got the following "stages" in my prototype ( which may or may not end up literal bevy stages ):

• Collect transition intents
  • This is where all the systems that nay express t intent to transition the player state will go.
• Compute state transitions
  • This contains the state transition logic ( this is a new concept ).
  • For each state there will be a transition_from_[state] system that will read intents to transition the state and determine whether there are indeed any state transitions.
  • These are the systems that will use our command buffer to add and remove components
• Flush state transitions
  • This is a system that flushes the state transition command buffer, immediately applying any component updates requested by the "Compute state transitions" stage.
• Handle states
  • This is where the real state systems are, the ones that modify the player based on their current state, such as playing animations, etc.

[zicklag]

I'm working on a real PR, but here's what the player state looks like so far. I got flopping ( animation-only ) and idling working in the actual game with the new design, but I've commented out most of the game just to get it compiling, since I've removed the State enum.

https://gist.github.com/zicklag/b9ada0123580d0bfb8c54b71d2837394

I would have avoided stages and just used .after(), but unfortunately exclusive systems may not be schedule in between parallel systems in the same stage, so I had to make a new stage for command flushing and put it in between PreUpdate and Update.

I could have made 3 new stages, instead, but it seems like we may as well allow the collector and transition systems to run at the same time as any other PreUpdate systems, and we might as well allow the state handler systems to run at the same time as other Update systems.

We can use .after() and .before() to do any other scheduling within those stages. At least that's what I'm thinking so far.

I feel like this sort of change in thinking about our state model might imply some change in our animation systems to better fit together, but will think on that more as well.

I did make a change ( we may want to make more ) that just replaces the animation states with the animation String name, and makes it the responsibility of the state handler to choose when to play it. It turned out very clean so far.

[zicklag]

Got moving working and pushed a draft PR ( #203 ) that is wildly un-ready with tons of changes I'm still working on. Here's the latest player state file with the most relevant code:

https://github.com/zicklag/punchy/blob/fighter-state-refactor/src/fighter_state.rs

[zicklag]

In #203 I now have pretty much everything other than items and attack collision detection working, which I can hopefully finish tomorrow.

I think the design is turning out very clean and easy to read.

I also removed the need to clamp the player movements in multiple places. Now all movement is controlled by modifying the Velocity component, and clamping happens in one place.

Before the Velocity is applied to any entity's Transform a series of constraint systems run, making sure, for instance, that the players stay within the boundaries that we define. This works extremely cleanly and makes it trivial for us to add constraints to anything else in the future.

Here's the list of files that are just about where I want them:

• https://github.com/zicklag/punchy/blob/fighter-state-refactor/src/fighter_state.rs
• https://github.com/zicklag/punchy/blob/fighter-state-refactor/src/movement.rs
• https://github.com/zicklag/punchy/blob/fighter-state-refactor/src/commands.rs
• https://github.com/zicklag/punchy/blob/fighter-state-refactor/src/enemy_ai.rs
• https://github.com/zicklag/punchy/blob/fighter-state-refactor/src/animation.rs

---

Also, I'm sorry if I changed some stuff I didn't need to change for the sake of the player state effort! It just helps my brain to fix the stuff that is bugging me about design while I work on it, but I know it makes it so hard to review when everything is changing at the same time.

If we want to merge this at all we can do whichever of these you feel is easiest:

• Just merge all the changes at the same time, and fix whatever you don't like afterwards
• Ask me to break the huge change into smaller changes that are as incremental as possible so that you can review each change individually.

I know I could have tried to change one thing at a time, but for me it it'd be easier just to break it into pieces later because so much is changing that it's heard to make standalone commits. Again, sorry this is so difficult to review!