Quick Start

If you’ve just acquired the plugin, verify your Discord account and begin by reading the beginner’s guide in its entirety. Please only ask for support in the Discord server after you have done so at least once. The beginner’s guide covers the essential basics of the plugin, many of your initial questions will probably resolve themselves simply by reading it.

The manual contains further reading material that you don’t necessarily need to get into right away.

If you are migrating from GMCv1, refer to the Migration Guide.

General Information

Keep the following in mind while reading through the documentation.

Documentation Integrity

The GMC is an evolving asset that is constantly being updated and improved upon. Therefore, it is generally not possible for me to keep this documentation 100% accurate at all times with every new release. If you discover any outdated/wrong information, broken links, etc. please let me know in the Discord, I will correct it as soon as possible. You are also free to report any spelling errors, regardless of how insignificant they may be, and share suggestions if you think a particular section is missing some crucial details or could be formulated more clearly.

Single vs. Multiplayer Development

Everything in this documentation is written with multiplayer development in mind. The concepts presented herein will work in real-world networks, and the GMC implements a host of tried and proven networking techniques to deal with issues such as latency and packet loss. This does not mean however that the GMC cannot be used for single-player games. Any code presented will generally also work for a single-player game. In the context of this documentation, single-player development can be viewed as a subset of multiplayer development. So if you are developing a single-player game, you can – but don’t have to – follow the documentation. If you are developing a multiplayer game on the other hand, you absolutely have to follow it. In either case, if you adhere to the documentation your logic will work in both single and multiplayer scenarios in the end.

Be aware that choosing multiplayer is a game design choice. If you deviate from the techniques and concepts outlined because you are developing a single-player-only game, there is usually no turning back. Single-player games that were not originally designed with networking in mind generally cannot be converted into multiplayer games afterward, at least not without rewriting large portions of the code from scratch.

In summary, everything in this documentation is written and formulated from a multiplayer perspective, but you can still follow along without problems if you are creating a single-player game. Some of the code or concepts may not be relevant to your game, but they generally won’t break anything either.

Blueprint vs. C++

Most of the code you’ll encounter in this documentation will be in Blueprint. This is simply because Blueprint users are in the majority, and also because C++ programmers can generally read Blueprint code as well (but usually not the other way round). The only time you may see C++ code is when something is not possible to do in Blueprint. Keep in mind that the Blueprint code can virtually always be translated directly into C++ since the interfaces are almost completely identical.

To avoid misunderstandings though, let me clarify one thing: The GMC aims to make Blueprint-only development as feasible as possible by exposing large portions of the interface to the editor. But the plugin itself is completely written in C++, and there are absolutely no restrictions to using C++ with it whatsoever. Additionally, the Blueprint interface can be disabled entirely to eliminate any overhead for people who want to use C++ exclusively.

Demo Content

If you are already an intermediate Unreal Engine user, the quickest way to familiarize yourself with the GMC is to analyse the demo project. The project files and any other additional resources to download can be found in the Discord server. There are different plugins available which demonstrate how various features could be implemented with the GMC. Beginners should use the demo project as a starting point for their games since it already has all the essential setup pre-configured, and I advise that you refer to it frequently while reading through the documentation to deepen your understanding of how the presented concepts can be applied in practice.

Plugin Architecture

The GMC is a very large plugin consisting of more than 40,000 lines of C++ code, around 20 classes and countless functions and properties. Most of the time however, you’ll only be interacting directly with a small portion of the interface. The main module with the most important classes is organized as shown in the diagram.

 

  • GMC_ReplicationCmp: Unsurprisingly, this component is what handles the replication within the plugin. It contains all the netcode and provides the interface for syncing data across the network. One of the main standout features of this component is that it makes no assumptions about the underlying movement implementation at all, so it doesn’t really do anything on its own until you provide some code and data to it that you want replicated. This can be done by inheriting from the component directly and overriding the PredictionTick function. The replication process will work according to the same principles as the other movement components that come pre-packaged with the plugin, so if you are well versed in C++ you also have the option to look at those for an idiomatic implementation of the network interface. However, even if you want to make your own fully custom movement component from scratch, it may be a better option to inherit from GMC_MovementUtilityCmp instead of directly from the replication component, especially if you want to use Blueprint instead of C++.

  • GMC_MovementUtilityCmp: This class serves multiple purposes. Firstly, it acts as a wrapper around the replication component, simplifying its usage and exposing a significant portion of the replication interface to Blueprint. Secondly, it provides a basic physics framework that lets you quickly manipulate the pawn’s velocity/acceleration/force without worrying much about the formulas required or adjusting for the frame time. Lastly, it provides a lot of utility functions that you can use to implement your own movement. Similar to its parent, this component doesn’t implement any movement functionality yet, but you will have a lot more utility to use and you can make your movement component entirely in Blueprint if you inherit from this instead of GMC_ReplicationCmp directly.

  • GMC_OrganicMovementCmp: This component is a comprehensive overhaul of Unreal’s CharacterMovementComponent class with numerous significant enhancements and a user-friendly interface fully exposed to Blueprints. If you’re looking for a solid foundation and need organic movement (i.e. movement characteristic for humans or animals rather than vehicle-like motion such as that of a car or plane), it’s highly recommended to use this component as a base class. It already provides a wealth of functionality, with grounded, airborne, and swimming movement, as well as support for AI, root motion montages, and dynamic bases.

  • GMC_GoldSrcMovementCmp: A specialized version of organic movement that accurately emulates the locomotion system of games made with the GoldSrc engine. For those of you who don’t know what that means: GoldSrc, or GoldSource, is the unofficial name for Valve’s version of id Software’s Quake engine and the predecessor of the Source engine. Many now classic titles were developed using the GoldSrc engine such as Half-Life (1998), Team Fortress Classic (1999), Counter-Strike (2000) and Day Of Defeat (2003). The interesting thing about the movement physics of the GoldSrc engine (which at its core remained mostly unchanged from the Quake engine) is that the way the velocity is calculated allows for an exploit that let’s you gain speed far beyond the intended limit. The technique used to achieve this is known today as bunny hopping or strafe jumping. Surfing is another widely known mechanic that has its origins in the GoldSrc engine.

  • GMC_Pawn: This is the pawn class that must be used in connection with the movement component. However, it is not nearly as glued together as Unreal’s Character/CharacterMovementComponent combo, and there’s no actual movement functionality in this class at all. It’s main purpose it to hold the synchronization data and pass it through to the movement component to prevent the additional replication cost of having to address a subcomponent. This actually means that the movement component itself does not have to be set to replicate at all, only the owning pawn must replicate. This class doesn’t hold much additional significance, so there’s no need for an extensive discussion. Unlike with Unreal’s default character, you can switch out any components of the actor directly in the Blueprint.

  • GMC_PlayerController: This controller class must be used for player-controlled pawns. Its main purpose is ensuring accurate synchronization of the client time with the server time. Beyond this key function, there’s not much more to this class either.

Required Setup

If you are not starting from the demo project and want to implement the GMC in a blank or custom project instead, you must ensure that all necessary prerequisites are fulfilled for any object you want to use with the plugin:

  • Pawns must inherit from GMC_Pawn.
  • Pawns must replicate in multiplayer (enabled by default). Activating replication on the movement component itself is not required (disabled by default).
  • The movement component must be owned by an actor of type GMC_Pawn.
  • Pawns that use organic movement must have a collision shape as root component (of type CapsuleComponent, GMC_FlatCapsuleCmp, BoxComponent, or SphereComponent).
  • Player controllers must inherit from GMC_PlayerController.
  • Player controllers must replicate in multiplayer (enabled by default).
  • In multiplayer, you need to place an actor of type GMC_WorldTimeReplicator in your level (handles time synchronization).
  • You should place an actor of type GMC_Aggregator in your level as well. This is optional but highly recommended (can improve performance in many cases).

Additionally, ensure that the game mode and game state class you use fit together. If you use GameModeBase you also need to use GameStateBase, if you use GameMode you need to use GameState. This has nothing to do with the GMC and applies to any Unreal Engine project, but it is a common error so it’s worth mentioning nonetheless.