Custom Animation Variables

Using animation variables outside of the default M2UP animation variables to control your Animation Blueprint.

M2UP has a default set of AnimVars (animation variables) that are used to define how the ABP (Animation Blueprint) logic operates. These variables are either replicated or filled locally in code every tick to determine what the animation state should be based on the current state of the character. For example, if the player's gait isn't replicated, the animation component code can calculate the gait AnimVar from the speed of the player.

The variables used are in the M2_AnimVars struct and cover things like walking, running, basic combat poses, which you can see being used in ABP_M2_Human. Your project may want to use a different ABP which requires different AnimVars. M2UP provides a couple of different ways to do this.

Custom Booleans

The quickest solution for basic cases is to use the M2UP provided custom bools. M2UP provides eight generic bool AnimVars within the M2_AnimVars struct that are never used by M2UP blueprints. These bools are client-authoritative background replicated variables, so will be replicated to all players, and work on Crowd members too.

There are functions on the JM_AnimVarsComponent to set and get the values from the authoritative client. This example will toggle the first bool:

The bools will be replicated and set on the M2_AnimVars struct that’s available in the ABP (see the existing AnimVars macros). They will look like this:

You can use these to drive your new animation state changes as usual in your custom ABP.

Define your own variables

The tools in this section are available from MSquared v27.

For more advanced use cases, you can also directly use AnimVars that you've defined in your own ABP. To ensure that these function correctly with Crowd members and with M2UP's actor pooling system, you'll need to register these variables in a custom AnimVarsComponent and use appropriate callbacks to set the variable.

Defining and registering the variable

You can create an AnimVar as usual, by creating a variable inside your ABP.

I've created "TestCustomAnimVar" that defines a test transition in my ABP.

To register my variable, I need to create a custom anim vars component. This is a component that extends JM Anim Vars Component, but to use the base M2UP anim var settings, you can extend from BPMC M2 Anim Vars Base.

In this component, you need to register your custom anim var by calling RegisterCustomAnimVar from the InitializeAnimVarsComponent event. In RegisterCustomAnimVar, you need to provide:

• CrowdAnimVarName: a string that matches the name of the anim var. This is only if you want your variable to function in the Crowd; you can leave it blank otherwise. In the above example, this would be "TestCustomAnimVar".

• UpdateAnimVarValue: an event that accepts an Anim Instance (which is your ABP) and a float input. This event should perform the action of setting the anim var on your ABP to the input value. This event will be called whenever the anim var needs changing.

• AnimInstanceClass: the class of the ABP that this variable is on.

This function returns a handle that you need to store to make updates to the anim var later on.

Note that your project can be set up to use multiple different ABPs at once for different user configurations, and not all the ABPs will necessarily have every custom anim var. This register function only registers the anim var for the given AnimInstanceClass, so you'll need to register for each separate class that has the variable.

Here, I'm registering my TestCustomAnimVar. My UpdateAnim function needs to cast the AnimInstance to my ABP that actually has the anim var in order to set it. Because the input can only be a float, I'm also converting the float to a bool before setting it in my ABP.

Finally, we need to tell our MorpheusActor character class to actually use this new anim vars component that we've created. This is done by setting the Anim Vars Component Class in your player MorpheusActor class to the class of your new anim vars component.

If you attempt to use a variable inside your ABP that has not been registered, you will see warnings along the lines of:

LogAnimatedCrowd: Warning: UAnimatedCrowdComponent::ValidateAnimVars: Crowd expected to support anim var with name [YourVarName], but this could not be found. Please check your anim var names.

From release v40 onwards, these will default to 0/false. (earlier releases will have these variables with undefined values)

Updating your custom variable

To update the variable, we can't just update the anim var that's in the ABP instance, because the ABP instances are pooled and not available on Crowd members. Instead, we just need to call UpdateCustomAnimVar in our anim vars component and pass in the handle we saved from registration, and the (float) value that the anim var should be set to.

Never set the value of the anim var on the ABP instance directly; always call UpdateCustomAnimVar.

Anim vars are not replicated by default. To replicate them, you can simply create your own replicated variable and update the anim var as above to match your replicated variable.

I've created a client-auth, midground replicated "TestCustomAnimVar" in my anim vars component, with a RepNotify that updates the anim var. Note I'm casting back to a float here.

This is an example implementation of how you'd update an anim var from the authoritative client. My auth client is updating my replicated bool every 5 seconds; the OnRep shown earlier handles this replicated bool applying the update to the anim var.

Performance

Lots of AnimVars in traditional games are calculated and set every frame. For example, values like turning angle that depend on your current velocity. Due to the scale of M2UP experiences, you cannot create anim vars in projects that need to be updated every tick, since that would involve calling into a BP function every frame for all (potentially 15k+) players in the game.

Variables that need to be updated every frame are kept in code. Custom anim vars should instead only be used for states that don't need changing that frequently.