Organic Movement Overview

The GMC_OrganicMovementCmp class serves as the plugin’s counterpart to Unreal’s CharacterMovementComponent class (CMC). The GMC’s version is structured a bit differently, can be extended in Blueprint and has more features out of the box, but it covers the same use cases from a game design perspective as the CMC: Both are intended for actors that represent organic characters such as humanoids, animals, creatures etc. (as opposed to vehicles like cars or planes, which move very differently).

In the real world organic entities usually move through muscles manipulating a skeleton, but you can probably imagine that trying to simulate these intricate physical processes in a video game for every character would be highly impractical. Instead, we simplify the movement by giving our characters a basic rigid collision shape for which we can calculate the physics comparatively easily and efficiently ourselves. In the case of the CMC, this collision shape is limited to a vertical capsule, but the GMC additionally supports horizontally oriented capsules, spheres, and boxes. It’s important to understand that this collision shape (which must always be the root component of the actor) is the object that is actually being transformed by the movement logic – it’s not the skeletal mesh that plays the animations or any other component that may be attached to your actor, these just follow the root component wherever it goes. This whole setup is called kinematic movement. It enables us to have full control over the character’s movement, rather than relying on the physics engine to autonomously simulate the movement.

Entry Points

To get an understanding of the internal organic movement logic, refer to the following high level diagram. There are more events available than shown here, and in C++ you can override virtually every function in the movement component, but these are the main ones you should know about. Events displayed in color can be overridden in Blueprint.

 

 

  • PhysicsSimulationUpdate: This event is triggered only when the root component is simulating physics. Simulating physics disables all kinematic movement, so the movement ends after the event in this case. For multiplayer, remember that predicted physics simulations are not supported by the GMC.
  • PreMovementUpdate: Use this for any setup that must always happen before the movement (regardless of whether the movement logic will actually be executed afterwards or not). It’s important to note that at this stage none of the pawn’s movement-related properties have been updated yet.

  • CanMove: If this returns false, the movement logic will not be executed. It is important to understand that this is a fundamental check of the pawn’s mobility. By default, false is returned if the root component is not set to Movable or the movement mode is set to None. Returning false means that there will be no updates to the pawn state at all, not even animations.

  • UpdateMovementModeDynamic: This function updates the movement mode (Grounded, Airborne, Buoyant, etc.) based on dynamic conditions if necessary. E.g. there is a flag called ReceivedUpwardForce that, when set, automatically switches the movement mode to Airborne within this function, even if the pawn is still on the ground currently (meaning the static check would actually determine the movement mode to be Grounded). If the movement mode was in fact updated within this function, true is returned and UpdateMovementModeStatic will be skipped. You will usually need to add your own checks here if you made a custom movement mode that you want to switch to based on certain conditions, otherwise your custom movement mode may never get activated.

  • UpdateMovementModeStatic: This function updates the movement mode without considering any dynamic conditions. For instance, if the pawn currently touches a walkable surface, the movement mode will be set to Grounded, or if it is within a fluid volume, the movement mode will be set to Buoyant, etc. Essentially, it determines the movement mode simply by the current transform of the pawn, disregarding most other factors.

  • OnMovementModeUpdated: As the name implies, this event is called after the new movement mode for the current frame has been set by either UpdateMovementModeDynamic or UpdateMovementModeStatic.

  • PreProcessInputVector: Do any custom processing of the input vector here. The function passes you the raw input vector, but the vector you return from the function is what will actually be used for all movement calculations. For instance, if you need to disable player input in certain situations, you could simply return a zero vector. By default, this function rotates the raw input vector, which is in world space, by the control rotation yaw (so forward corresponds to where the camera is looking). However, you can do any transformations you like, e.g. while your character is on a ladder you may want to transform forward to be up and backward to be down.

  • PrePhysicsUpdate: Can be used to do any setup logic required before the physics for the current movement mode are computed. After this event, the pawn’s new velocity will be calculated and the location delta for the current frame will be applied.

  • PhysicsCustom: Physics for custom movement modes can be added here. Keep in mind that a custom movement mode requires you to not only compute the velocity yourself, but also apply the location delta and handle collisions. No movement will occur on its own. Custom movement modes are typically used when you want the physics to deviate significantly from the existing ones, common mechanics like wall running or flying do not require a new movement mode usually.

  • PostPhysicsUpdate: This event is called after the location delta for the current frame was applied.

  • MovementUpdate: This is the primary event intended for adding custom movement logic. At this point, the pawn’s state has been fully updated, and switching between the built-in movement modes is handled automatically for movement you implement here. It is often enough to manipulate the pawn’s velocity/acceleration/force within this event to achieve custom features, moving the updated component yourself should not be required in most cases.

  • PostMovementUpdate: This event is called after all movement calculations have been completed.

You can alter and extend the behaviour of the base movement by adding custom logic to these events/functions. You do this by hovering over the Functions tab in the movement component Blueprint and selecting the function you want to override from the Override drop-down (alternatively you can also right-click in the event graph and type out the function you want to override).

Some of the events already have logic in them, so you must always remember to call the parent implementation for anything you override. This can be done by right-clicking the node and selecting Add Call to Parent Function. Also remember to connect the output pins of the original node to the input pins of the parent node.

 

Adding Custom Code

After overriding the desired event you can start writing the code to implement custom movement functionalities. In addition to the built-in functions and variables that you always have available in Unreal, there is also much utility included in the GMC out of the box. To view all of the GMC-specific functions and properties at your disposal directly in the editor, right-click in the event graph and type “General Movement Component”. However, be prepared for an extensive list of results, so we’ll be going over the things you’re most likely to need in the following.

But first, keep in mind that nearly all functions, parameters, and properties within the GMC have descriptions. Hover your cursor over a node or an input/output pin of a function/event and their corresponding comments will be displayed.

Physics Functions

The GMC allows for easy manipulation of the pawn’s physics state through the following functions. Velocity, acceleration and force are linked and update each other when one value is modified. Scaling with the delta time also happens automatically, and if the passed delta time value is <= 0 the currently set physics delta time will be used (which will be appropriate for most use cases). The calculations also consider the configured mass of the pawn, which can be adjusted through the Mass property of the movement component.

Root Collision Utility

The GMC offers support for dynamic switching of the root collision shape and extent during gameplay. If you’re working with organic movement, the collision extent and shape will automatically synchronize between clients and the server. While other properties of the collision component aren’t replicated by default, the current component settings will carry over to the new collision shape when switching. If you’re inheriting from GMC_OrganicMovementCmp, dynamic naming of the root component is handled automatically, so you can leave the Name parameter of SetRootCollisionShape as “None.” Below, you can find some of the functions available for manipulating and querying the root collision at runtime. For a more comprehensive list, right-click in the event graph and type “Root Collision”.

Floor Utility

While writing custom movement, there will likely be instances where you need information about the ground beneath your character. You can always access that data as long as the ground is within the floor trace length (regardless of the current movement mode). CurrentFloor consists of two downward traces starting at the lower end of the pawn’s collision shape, one shape trace and one line trace from the center. If any of the two traces produced a blocking hit, the floor is within reach and information will be available (if not, ShapeDistanceToFloor and LineDistanceToFloor will be -1). You can manually update the floor through the UpdateFloor function. However, only do this when absolutely necessary since it is an expensive operation. The floor will usually be kept up to date automatically, so you can generally just read from it directly without updating manually. To visualize the floor traces use the console command gmc.ShowFloorSweep 1.

Movement Modes

By default, there are 3 primary movement modes: Grounded, Airborne and Buoyant (swimming). When setting a movement mode through the SetMovementMode function, the OnMovementModeChanged event will be called. As goes for all events, do not forget to call the parent implementation when overriding OnMovementModeChanged. Also, do not confuse this event with the similarly named OnMovementModeUpdated event (depicted previously in the flowchart).