Gametype Technical Guide

Overview

Every game made with Unreal Engine revolves around the use of one or more gametypes. This concept is obvious in games such as Unreal Tournament where the user actually chooses the type of game to play, whether it is Deathmatch, Capture the Flag, Last Man Standing, or some other gametype. However, even games such as platformers, sports and racing games, RTS games, RPGs, etc all rely on a gametype, though it is transparent to the user.

A gametype is what determines the rules of the game: how the game starts, how scoring or other events are handled, what conditions must be met for the game to end, and any other elements of the game. The game and thus the gametype is also level-specific; when a new level is loaded (At least in the traditional sense. Level streaming loads levels into the current level leaving the current gametype.), a new gametype is loaded. In a Deathmatch game, the gametype handles spawning the players and bots into the game at various locations, handling kills by each player and keeping score, and ends the game when either the time runs out or one player has made the required number of kills. This is all very straightforward and the same concepts apply to any other game, although they may be slightly more complex.

For instance, imagine an adventure role-playing game. When the player starts the game, the gametype spawns the player into the world, either at a designated location, such as the opening of a dungeon or where the player was when the game was last saved. The player explores the world and then comes to a dungeon. When the player enters the dungeon, a new level and gametype are loaded. This gametype spawns the player at the beginning of the dungeon and then waits for the player to complete the objective of the dungeon, which may be killing a boss or collecting a specific item or what have you. When the gametypes detects the dungeon has been completed, it sends the player back to the main world, loading the main world level. In the main world, the gametype spawns the player at the opening of the dungeon and waits for the player to finish all the objectives of the game as they continue to explore.

Clearly this is a much more complex case as the game has multiple gametypes which all work together, but the concept of each gametype is the same as that for the simple case of a Deathmatch game.

GameInfo Class

The GameInfo class is the base class for all gametypes in Unreal. Each time a map is loaded, a new instance of the appropriate GameInfo class is created and assigned to be gametype. For more information on how the gametype is set for a specific level, see the Game Lifecycle section.

GameInfo Properties

Arbitration

• bUsingArbitration - If TRUE, the game will use arbitration.
• bHasArbitratedHandshakeBegun - TRUE if the arbitrated handshake has occurred. New connections will be rejected once the handshaking begins.
• bNeedsEndGameHandshake - If TRUE, the game should perform a handshake at the end of the game.
• bHasEndGameHandshakeBegun - TRUE if the end game handshake has started.
• bIsEndGameHandshakeComplete - TRUE if the end game handshake has finished.
• ArbitrationHandshakeTimeout - GLOBALCONFIG. The amount of time a client has to perform the arbitration handshake before being kicked.
• PendingArbitrationPCs - An array of PlayerControllers the game is waiting to perform handshakes with.
• ArbitrationPCs - An array of PlayerControllers the game has performed handshaking with and require finalization of arbitration data written to the online subsystem.

Cheat Detection

• [Min/Max]TimeMargin - The maximum amount of time the client clock is allowed to get behind/ahead of the server clock before triggering the speed hack detection.
• TimeMarginSlack - How quickly the client clock is allowed to drift from the server clock without triggering the speed hack detection.
• bIsStandbyCheckingEnabled - If TRUE, the game should perform checking for standby cheats.
• bIsStandbyCheckingOn - TRUE when standby cheats are being checked.
• bHasStandbyCheatTriggered - TRUE when a standby cheat has been detected.
• Standby[Rx/Tx]CheatTime - The amount of time without receiving a packet/acknowledgement that can occur before triggering the cheat code.
• BadPingThreshold - The highest ping allowed before the server is assumed to be delaying packets or has a bad upstream connection.
• PercentMissingFor[Rx/Tx]Standby - The percentage of clients allowed to be missing packet/acknowledgement data before triggering the standby code.
• PercentForBadPing - The percentage of clients allowed with bad ping values before triggering the standby code.
• JoinInProgressStandbyWaitTime - The amount of time to wait before checking a connection for standby issues.

Game Components

• PlayerControllerClass - The PlayerController class to use when new players login for the gametype.
• DefaultPawnClass - The Pawn class to use when new players login for the gametype.
• HUDType - The HUD class to use for the heads up display for the gametype.
• PlayerReplicationInfoClass - The PlayerReplicationInfo class to use when new players login for the gametype.
• GameReplicationInfoClass - The GameReplicationInfo class to use for the gametype.
• OnlineSub - The OnlinSubsystem instance used by the gametype for communicating with the platform layer's services.
• GameInterface - The OnlineGameInterface instance used by the gametype for creating, searching for, or destroying online games.
• OnlineStatsWriteClass - The OnlineStatsWrite class to send to clients to use to create and hold their stats.
• OnlineGameSettingsClass - The=OnlineGameSettings= class to use when registering dedicated servers with the online service.
• DeathMessageClass - The LocalMessage class to use for displaying messages when players die.
• GameMessageClass - The GameMessage class to use for displaying messages about gameplay events.
• AccessControlClass - The AccessControl class to use for the gametype.
• AccessControl - The AccessControl instance that controls whether players can enter the game and/or become admins.
• BroadcastHandlerClass - The BroadcastHandler class to use for the gametype.
• BroadcastHandler - The BroadcastHandler instance to use for displaying messages for the gametype.
• AutoTestManagerClass - The AutoTestManager class to use for the gametype.
• MyAutoTestManager - The AutoTestManager instance to use for managing automated testing. Only exists if requested by through the command line.

Game Settings

• bRestartLevel - If TRUE, the level should be restarted when the player dies.
• bTeamGame - If TRUE, the game is designated as a team game, meaning that the players are divided up into more than one team. There is no built-in logic for creating the teams in the base GameInfo. This simply specifies that the game has teams.
• bGameEnded - TRUE when end game conditions have been met. Set by EndGame().
• bOverTime - If TRUE, the game is in overtime. This occurs when EndGame() is called, but CheckEndGame() returns false because some condition has not been met.
• bDelayedStart - If TRUE, the game will not immediately begin when the player joins.
• bWaitingToStartMatch - TRUE when the game is in the PendingMatch state, waiting for the game to begin.
• bChangeLevels - GLOBALCONFIG. If TRUE, a new map should be loaded when the game is restarted.
• bAlreadyChanged - TRUE once the loading process has begun on the new map when the game is restarted and bChangeLevels=TRUE.
• bGameRestarted - TRUE when the game has been restarted.
• bLevelChange - TRUE when a level transition (via ProcessServerTravel()) is in progress.
• GameDifficulty - GLOBALCONFIG. The difficulty modifier for the game. The application of this must be done in a subclass as it is extremely game-specific.
• GoreLevel - GLOBALCONFIG. The amount of gore to show. A value of 0 means show normal amount of gore with increasing values showing less gore.
• GameSpeed - Scaling factor for the game time. Used to set WorldInfo.TimeDilation.
• MaxSpectators - GLOBALCONFIG. The maximum number of players allowed by the gametype on the server.
• MaxSpectatorsAllowed - The maximum number of spectators ever allowed by the gametype. Used to clamp the MaxSpectators to a sensible value as it is set in a config and could be modified.
• NumSpectators - The current number of spectators in the game.
• MaxPlayers - GLOBALCONFIG. The maximum number of players allowed by the gametype on the server.
• MaxPlayersAllowed - The maximum number of players ever allowed by the gametype. Used to clamp the MaxPlayers to a sensible value as it is set in a config and could be modified.
• NumPlayers - The current number of human-controlled players in the game.
• NumBots - The current number of AI-controlled players in the game.
• NumTravellingPlayers - The number of players that are currently still traveling from the previous map.
• CurrentID - The current ID used to assign unique PlayerIDs to each PlayerReplicationInfo as they are created.
• DefaultPlayerName - LOCALIZED. The default name prefix to use when assigning names to players for the gametype.
• GameName - LOCALIZED. The display name for the gametype.
• FearCostFalloff - The factor that determines how quickly the FearCost for NavigationPoints falls off over time when bDoFearCostFalloff=true.
• bDoFearCostFalloff - If TRUE, FearCost for NavigationPoints will fall off over time.
• GoalScore - The "score" needed by a player to end the match. Score is an arbitrary concept, though many games keep track of some sort of score and end the game when a particular score is attained.
• MaxLives - The maximum number of lives a player is allowed per match.
• TimeLimit - The amount of time allowed for a single match.
• GameInfoClassAliases - An array of GameClassShortName structures that map short names for the gametype to full class names.
• DefaultGameType - CONFIG. The default gametype to use when no gametype is specified otherwise (in the form of a string specifying the full path to the gametype class).
• DefaultMapPrefixes - CONFIG. An array of GameTypePrefix structures that map the prefix in a level's name to a specific gametype. Used to determine the gametype to use when no gametype is specified. Overrides the DefaultGameType. See the Gametype Prefixes section for more details.
• CustomMapPrefixes - CONFIG. An array of GameTypePrefix structures that map the prefix in a level's name to a specific gametype. Used to determine the gametype to use when no gametype is specified. Overrides the DefaultGameType. See the Gametype Prefixes section for more details.
• bRequiresPushToTalk - If TRUE, voice communications are required to be push-to-talk for this gametype. Otherwise, voice comms could be left open at all time.

Mutator

• BaseMutator - A reference to the first Mutator applied to the gametype.

Network/Replication

• InactivePRIArray - An array of the PlayerReplicationInfos of players who have left the game. These are saved in case those players reconnect.
• bKickLiveIdlers - GLOBALCONFIG. If TRUE, PlayerControllers with Pawns can be kicked from the game for idling.
• MaxIdleTime - The maximum amount of time a player is allowed to idle before being kicked.
• LeaderboarId - The id of the leaderboard to write stats to for skill/scoring.
• ArbitratedLeaderBoardId - The id of the arbitrated leaderboard to write stats to for skill/scoring.
• bUseSeamlessTravel - If TRUE, map travels will be performed using SeamlessTravel() which loads in the background and doesn't disconnect the clients.
• CoverReplicatorBase - The URL options string to apply when a dedicated server starts to register.
• bHasNetworkError - TRUE when a critical network error has occurred which prevents the server from performing a map travel.
• ServerOptions - The URL options string to apply when a dedicated server starts to register.
• AdjustNetSpeed - The current adjusted net speed which is used for dynamically managing the net speed for listen servers.
• LastNetSpeedUpdateTime - The last time the net speed was updated for the server by a client entering or leaving.
• TotalNetBandwidth - GLOBALCONFIG. The total amount of bandwidth available for a listen server, which is split dynamically across net connections.
• [Min/Max]DynamicBandwidth - The minimum and maximum amount of bandwidth dynamically set per connection.

Pausing

• bPauseable - If TRUE, the game can be paused by a player when playing online. The game can always be paused by the player when playing in a standalone game.
• bAdminCanPause - If TRUE, the game can be paused by admins when playing online.
• Pausers - An array of delegates that are checked in ClearPause() to determine if the game can be unpaused.

Profiling/Testing

• bFixedPlayerStart - If TRUE, the game should use the same spawn point(s) to make profiling consistent. There is no functionality for this in GameInfo. It must be added to the logic for choosing spawn points in a subclass.
• CauseEventCommand - Holds the console event passed to the game in the map URL. Usually used for testing, i.e. triggering an automated flythrough. There is no functionality for executing this command in GameInfo. It must be added in a subclass.
• BugLocString - Holds the BugIt location string passed to the game in the map URL.
• BugRotString - Holds the BugIt rotation string passed to the game in the map URL.

GameInfo Functions

Game

• OnEngineHasLoaded - Event called from native code when the engine has been loaded on startup. This is only called once when the game is first started and not each time a new map (and thus gametype) is loaded.
• GetSupportedGameTypes [InFilename] [OutGameType] [bCheckExt] - Retrieves the GameTypePrefix struct for the given map name. See the Gametype Prefixes section for more details.
  • InFilename - The name of the map to retrieve the gametype for.
  • OutGameType - Out. Outputs the GameTypePrefix struct associated with the given map.
  • bCheckExt - Optional. If TRUE, the file extension of the map name will be checked to ensure it is a valid map file.
• GetMapCommonPackageName [InFilename] [OutCommonPackageName] - Retrieves the name of the common package (if any) for the given map filename. Returns TRUE if successful. Returns FALSE if the GameTypePrefix for the map is not found or if the GameTypePrefix does not use a common package. See the Common Packages section for more details.
  • InFilename - The name of the map to retrieve the common package name for.
  • OutCommonPackageName - Out. Outputs the name of the common package.
• GetDefaultGameClassPath [MapName] [Options] [Portal] - Returns the full path to the optimal GameInfo class to use for the specified map and options. This is used for preloading cooked packages, etc. and therefore doesn't need to include any fallbacks as SetGameType() will be called later to actually find/load the desired class.
  • MapName - The name of the map to get the default gametype for.
  • Options - The options string from the URL for the map, if any.
  • Portal - The name of the destination portal to send the player to, if any.
• SetGameType [MapName] [Options] [Portal] - Returns the class of GameInfo to spawn for the game on the specified map and the specified options. This function should include any fallbacks in case the desired class can't be found.
  • MapName - The name of the map to get the gametype for.
  • Options - The options string from the URL for the map, if any.
  • Portal - The name of the destination portal to send the player to, if any.
• InitGame [Options] [ErrorMessage] - Called by the engine before any other script executes to initialize parameters and spawn helper classes for the gametype.
  • Options - The options string from the URL for the map, if any.
  • ErrorMessage - Out. Outputs any error messages encountered while initializing the gametype.
• StartMatch - Informs all actors that the match is starting and spawns Pawns for the players.
• Reset - Resets the gametype to its initial state. Called after all other Actors have been reset.
• ShouldReset [ActorToReset] - Determines whether the given Actor is allowed to be reset. Returns TRUE if the given Actor should have Reset() called on it while restarting the game or FALSE if the GameInfo will manually reset it or if the actor does not need to be reset.
  • ActorToReset - The Actor to reset.
• ResetLevel - Resets the level by calling Reset() on all Controllers, then all Actors, and then the GameInfo.
• RestartGame - Restarts the game by either changing maps if bChangeLevels=TRUE or by reloading the current map.
• EndGame [Winner] [Reason] - Performs end of game handling. Should be called when end game condition(s) have been met.
  • Winner - The PlayerReplicationInfo of the player that won the game.
  • Reason - A String specifying the reason the game is ending. For instance, "TimeLimit", "LastMan", "DungeonComplete", etc.
• CheckEndGame [Winner] [Reason] - Called from EndGame() to check if the game should indeed end based on the reason given. Subclasses can override this to place additional game-specific modifications.
  • Winner - The PlayerReplicationInfo of the player that won the game.
  • Reason - A String specifying the reason the game is ending. For instance, "TimeLimit", "LastMan", "DungeonComplete", etc.
• CheckModifiedEndGame [Winner] [Reason] - Called from CheckEndGame() to allow modification of the end game conditions. By default, this calls CheckEndGame() on all Mutators.
  • Winner - The PlayerReplicationInfo of the player that won the game.
  • Reason - A String specifying the reason the game is ending. For instance, "TimeLimit", "LastMan", "DungeonComplete", etc.
• PerformEndGameHandling - Performs end of game handling for the online layer.
• GameEnding - Called by the engine to notify the gametype that the game is shutting down, meaning the application is exiting or a new map is being loaded.
• PreExit - Called by the engine to notify the game that the engine is shutting down.
• MatchIsInProgress - Returns whether the match is currently in progress.
• GameEventsPoll - Function stub that serves as an entry point of the stats code for custom game logging at a regular interval. It is called by Poll() timer of the GameplayeStatsWriter at regular intervals when stat logging is started. Subclasses should override this to add custom stats logging.
• EndLogging [Reason] - Function stub for stopping the logging of stats. Subclasses should override this to add logic to stop stats logging.
  • Reason - A String specifying the reason to quit logging.

Travel

• ProcessServerTravel [URL] [bAbsolute] - Handles jumping the server to a new level.
  • URL - The URL of the map to travel to.
  • bAbsolute - If TRUE, absolute travel should be used. Otherwise, relative travel is used.
• ProcessClientTravel [URL] [NextMapGuid] [bSeamless] [bAbsolute] - Notifies all clients to travel to the specified URL.
  • URL - The URL of the map to travel to.
  • NextMapGuid - The GUID of the server's version of the next map.
  • bSeamless - If TRUE, seamless travel should be used.
  • bAbsolute - If TRUE, absolute travel should be used. Otherwise, relative travel is used.
• SendPlayer [aPlayer] [URL] - Sends a player to the given URL.
  • aPlayer - The PlayerController of the player to send to the new URL.
  • URL - The URL of the map to travel to.
• GetNextMap - Function stub that returns the map players should travel to for the next game. Subclasses should override this if the game should have a map cycle.
• GetTravelType - Determines which type of travel should be used. Return TRUE for absolute travel and false for relative.
• PreCommitMapChange [PreviousMapName] [NextMapName] - Event stub called by the engine by CommitMapChange() before unloading the previous level.
  • PreviousMapName - The name of the map being unloaded.
  • NextMapName - The name of the map being loaded.
• PostCommitMapChange - Event stub called by the engine by CommitMapChange() after unlaoding the previous level and loading the new level.
• GetSeamlessTravelActorList [bToEntry] [ActorList] - Called by the engine on the server during seamless level transitions to get the list of Actors that should be moved into the new level. PlayerControllers, Role < ROLE_Authority Actors, and any non-Actors that are inside an Actor that is in the list i.e. Object.Outer = Actor= in the list are all automatically moved regardless of whether they're included here. Only dynamic (bStatic and bNoDelete) actors in the PersistentLevel may be moved (this includes all actors spawned during gameplay). This is called for both parts of the transition because actors might change while in the middle (e.g. players might join or leave the game)
  • bToEntry - If TRUE the server is traveling from old level -> entry. Otherwise, the server is traveling from entry -> new level.
  • ActorList - Out. Outputs the array of Actors to be moved.
• PostSeamlessTravel - Called by the engine on the new GameInfo after a seamless level transition has been completed. This is generally used to reinitialize players already in the game as they will not have Login() called.
• HandleSeamlessTravelPlayer [C] - Handles reinitializing players that remained through a seamless level transition. Called from PostSeamlessTravel() and from the engine for players that finished loading after the server.
  • C - The Controller of the player to handle.
• SetSeamlessTravelViewTarget [PC] - Sets the ViewTarget for a player that remained through a seamless level transition.
  • PC - The PlayerController to set the ViewTarget for.

Player

• PreLogin [Options] [Address] [ErrorMessage] - Accepts or rejects a player joining the server.
  • Options - The options string from the URL for the map, if any.
  • Address - IP address of the connecting player.
  • ErrorMessage - Out. Outputs the error message for a failed login. A non-empty String here means the login failed.
• Login [Portal] [Options] [UniqueID] [ErrorMessage] - Logs a player in and spawns the PlayerController for the player. Returns the spawned PlayerController.
  • Portal - The name of the destination portal to send the player to, if any.
  • Options - The options string from the URL for the map, if any.
  • UniqueID - The UniqueNetID for the player logging in.
  • ErrorMessage - Out. Outputs the error message for a failed login. A non-empty String here means the login failed.
• PostLogin [NewPlayer] - Called by the engine after a successful player login to handle player setup.
  • NewPlayer - The PlayerController of the player that logged in.
• Logout [Exiting] - Called from the Controller to remove the player from the game when it is being destroyed.
  • Exiting - The Controller of the player leaving the game.
• SpawnDefaultPawnFor [NewPlayer] [StartSpot] - Spawns and returns a Pawn for the given Controller using the DefaultPawnClass.
  • NewPlayer - The Controller of the player to spawn the Pawn for.
  • StartSpot - The NavigationPoint to spawn the pawn at.
• GetDefaultPlayerClass [C] - Returns the default Pawn class to use for the given Controller.
  • C - The Controller to get the Pawn class for.
• StartHumans - Starts human-controlled players by calling RestartPlayer().
• StartBots - Starts AI-controlled players by calling RestartPlayer().
• RestartPlayer [NewPlayer] - Restarts a player (human or AI) by finding a starting spot, spawning a Pawn, adding default inventory, etc. for the player.
  • NewPlayer - The Controller of the player to restart.
• GenericPlayerInitialization [C] - Handles all player initialization that is shared between the travel methods, PostLogin() and HandleSeamlessTravelPlayer().
  • C - The Controller of the player to initialize.
• UnregisterPlayer [PC] - Removes the player from the named session when they leave the game.
  • PC - The PlayerController of the player leaving the game.
• AtCapacity [bSpectator] - Returns whether the game is already full or not.
  • bSpectator - If TRUE, returns whether the game is at max capacity for spectators. Otherwise, return whether the game is at max capacity for players.
• GetNumPlayers - Returns the number of players in the game.
• GetNextplayerID - Returns the next ID to use for joining players.
• SetPlayerDefaults [PlayerPawn] - Resets certain player Pawn properties back to their default values. Called from RestartPlayer().
  • PlayerPawn - The Pawn to reset properties for.
• CanSpectate [Viewer] [ViewTarget] - Return whether the given PlayerController is allowed to spectate from the point of view of the given PlayerReplicationinfo.
  • Viewer - The PlayerController of the spectator.
  • ViewTarget - The PlayerReplicationInfo to spectate.
• ChangeName [Other] [S] [bNameChange] - Changes the given player's name to the specified name.
  • Other - The Controller of the player.
  • S - The name to give the player.
  • bNameChange - Unused.
• ChangeTeam [Other] [N] [bNewTeam] - Changes the given player's team to the specified team.
  • Other - The Controller of the player.
  • N - The number of the team to place the player on.
  • bNewteam - Unused.
• PickTeam [Current] [C] - Returns the actual number of the team to place the given player on.
  • Current - The temporary number of the team to place the player on.
  • C - The Controller of the player.
• PlayerCanRestartGame [aPlayer] - Returns whether the given player is allowed to restart the game.
  • aPlayer - The PlayerController of the player requesting the restart.
• PlayerCanRestart [aPlayer] - Returns whether the given player is allowed to be restarted.
  • aPlayer - The PlayerController of the player requesting to be restarted.
• SwapPlayerControllers [OldPC] [NewPC] - Swaps a viewport/connection's PlayerControllers when seamless travelling and the new gametype's Controller class is different than the previous.
  • OldPC - The PlayerController of the player from the previous gametype.
  • NewPC - The PlayerController for the player in the new gametype.

Navigation

• DoNavFearCostFalloff - Updates navigation point fear cost fall off when bDoFearCostFalloff=true. Called from the Timer() of the GameInfo.
• NotifyNavigationChanged [N] - Function stub notifying the gametype when a NavigationPoint becomes blocked or unblocked allowing it to notify AIs in the world so they can update their routes.
  • N - The NavigationPoint that was changed.
• ShouldSpawnAtStartSpot [Player] - Returns whether the StartSpot property of the given player should be used as the spawn location for its Pawn.
  • Player - The Controller of the player.
• FindPlayerStart [Player] [InTeam] [IncomingName] - Returns the NavigationPoint that is the best location for this player to start from. PlayerStarts are rated by RatePlayerStart().
  • Player - The Controller of the player.
  • InTeam - Optional. The number of the team the player is on.
  • IncomingName - Optional. Specifies the tag of a teleporter to use as the starting location.
• ChoosePlayerStart [Player] [InTeam] - Returns the best PlayerStart for the given player to start from. PlayerStarts are rated by RatePlayerStart().
  • Player - The Controller of the player.
  • InTeam - Optional. The number of the team the player is on.
• RatePlayerStart [P] [Team] [Player] - Returns the rating of how desirable the given PlayerStart is for the given player and team.
  • P - The PlayerStart to get the rating for.
  • Team - The number of the team the player is on.
  • Player - The Controller of the player.

Inventory

• ShouldRespawn [Other] - Returns whether the given PickupFactory should respawn. By default, items are only allowed to respawn in multiplayer games.
  • Other - The PickupFactory of the item to respawn.
• AddDefaultInventory [P] - Spawns any default inventory for the given Pawn (via Pawn::AddDefaultInventory()). Called from RestartPlayer() and also from any ActorFactory spawning a Pawn.
  • P - The Pawn to give the default inventory to.
• PickupQuery [Other] [ItemClass] [Pickup] - Returns whether the given item is allowed to be picked up by the given player. Called by a PickupFactory or DroppedPickup when a Pawn tries to pick the item up.
  • Other - The Pawn attempting to pick up the item.
  • ItemClass - The Inventory class of the item.
  • Pickup - The Actor containing the item, i.e. the PickupFactory.
• DiscardInventory [Other] [Killer] - Discards or drops a player's inventory after it dies.
  • Other - The Controller of the player that died.
  • Killer - Optional. The Controller of the player that killed the player that died, if any.

Messages

• BroadcastDeathMessage [Killer] [Other] [damageType] - Displays a message from the DeathMessageClass when one player (Killer) kills another (Other). Calls BroadcastLocalized().
  • Killer - The Controller of the player who killed the other player. Can be None (not killed by a player) or the same as Other (Suicide).
  • Other - The Controller of the player who was killed.
  • damageType - The DamageType of the damage that caused the player's death.
• Broadcast [Sender] [Msg] [Type] - Displays the given message to all players in the game.
  • Sender - The Actor responsible for initiating the message.
  • Msg - A String representing the message to display.
  • Type - Optional. A Name that can be used to provide an additional "type" of message being sent.
• BroadcastTeam [Sender] [Msg] [Type] - Displays the given message to all players on the same team as the sender.
  • Sender - The Actor responsible for initiating the message.
  • Msg - A String representing the message to display.
  • Type - Optional. A Name that can be used to provide an additional "type" of message being sent.
• BroadcastLocalized [Sender] [Message] [Switch] [RelatedPRI_1] [RelatedPRI_2] [OptionalObject] - Displays a localized message to all players in the game.
  • Sender - The Actor responsible for initiating the message.
  • Message - The LocalMessage class to obtain the message from.
  • Switch - Optional. The index of the message to display.
  • RelatedPRI_1 - Optional. A PlayerReplicationInfo that can be used to obtain information to be displayed in the message.
  • RelatedPRI_2 - Optional. A PlayerReplicationInfo that can be used to obtain information to be displayed in the message.
  • OptionalObject - Optional. An Object that can be used in displaying the message. For instance, the default behavior of the LocalMessage class is to treat this as a Class object and call GetLocalString() on it to obtain the message to display (used for BroadcastDeathMessage).
• BroadcastLocalizedTeam [TeamIndex] [Sender] [Message] [Switch] [RelatedPRI_1] [RelatedPRI_2] [OptionalObject] - Displays a localized message to all players on the given team.
  • TeamIndex - The number of the team to display the message to.
  • Sender - The Actor responsible for initiating the message.
  • Message - The LocalMessage class to obtain the message from.
  • Switch - Optional. The index of the message to display.
  • RelatedPRI_1 - Optional. A PlayerReplicationInfo that can be used to obtain information to be displayed in the message.
  • RelatedPRI_2 - Optional. A PlayerReplicationInfo that can be used to obtain information to be displayed in the message.
  • OptionalObject - Optional. An Object that can be used in displaying the message. For instance, the default behavior of the LocalMessage class is to treat this as a Class object and call GetLocalString() on it to obtain the message to display (used for BroadcastDeathMessage).

Kick

• KickIdler [PC] - Removes the given player from the game via AccessControl::KickPlayer().
  • PC - The PlayerController of the player to kick.
• Kick [S] - Removes the given player from the game.
  • S - A String specifying the player to be removed. This should be the player's PlayerName or PlayerID.
• ForceKickPlayer [PC] [KickReason] - Removes the given player from the game regardless of admin status.
  • PC - The PlayerController of the player to kick.
  • KickReason - A String specifying the reason the player is being removed.
• KickBan [S] - Removes the given player from the game and bans them, denying re-entry.
  • S - A String specifying the player to be removed. This should be the player's PlayerName or PlayerID.

Network/Replication

• InitGameReplicationInfo - Initializes the GameReplicationInfo for the game.
• StartOnlineGame - Called from StartMatch() to tell the online system to start the game and waits for the callback. Tells each connected client to mark their session as in progress.
• OnStartOnlineGameComplete [SessionName] [bWasSuccessful] - Called when the online system completes the starting of the game.
  • SessionName - The Name of the session.
  • bWasSuccessful - If TRUE, the online system successfully completed starting the game and all clients should be registered.
• EndOnlineGame - Called from PerformEndGameHandling() to tell the online system to end the game and tells all clients to do the same.
• GetNetworkNumber - Returns the IP address of the host machine.
• RequiresPassword - Returns whether the game requires a password to join.
• ReplicateStreamingStatus [PC] - Replicates the current level streaming status to the given PlayerController.
  • PC - The PlayerController of the player to replicate the streaming status to.
• BestNextHostSort [A] [B] - Returns which of the given hosts is preferable. Used to sort the list of best hosts. Clients with the most peer connections come first. Then sort based on time of join so that newest players are preferred.
  • [A/B] - The PlayerControllers of the hosts to sort.
• UpdateBestNextHosts - Updates the list of best next hosts on the current server and also replicates this list to all clients.
• UpdateNetSpeeds - Updates all PlayerControllers in the game with the new speed.
• CalculatedNetSpeed - Calculates current net speed clamped between MinDynamicBandwidth and MaxDynamicBandwidth.
• WriteOnlineStats - Tells all clients to write stats and then handles writing local stats.
• WriteOnlinePlayerScores - If the match is arbitrated, tells all clients to write out their copies of the player scores. If not arbitrated, it only has the first local player write the scores.
• UpdateGameSettings - Function stub used to update any changes in game settings that need to be published to players that are searching for games. Subclasses should override this.
• UpdateGameSettingsCounts - Updates the online subsystem's information for player counts so that LAN matches can show the correct player counts.
• ProcessClientRegistrationCompletion [PC] [bWasSuccessful] - Function stub to notify the game that the given player has completed arbitration registration. Subclasses should override this to handle registration completeion.
  • PC - The PlayerController of the player that complete registration.
  • bWasSuccessful - If TRUE, the registration was successful.
• StartArbitrationRegistration - Function stub that starts off async registration. Subclasses should override this.
• StartArbitratedMatch - Function stub that starts an arbitrated match. Subclasses should override this.
• RegisterServerForArbitration - Function stub that registers the server for arbitration. Subclasses should override this.
• ArbitrationRegistrationComplete [SessionName] [bWasSuccessful] - Function stub called when the registration of the server for arbitration has completed.
  • SessionName - The Name of the session.
  • bWasSuccessful - If TRUE, the registration was successful.
• NotifyArbitratedMatchEnd - Called when an arbitrated match has ended and tells all clients to disconnect and then goes to the menu.
• ProcessServerLogin - Checks for the login parameters being passed on the command line. If present, it does an async login before starting the dedicated server registration process. Returns TRUE if the login is in progress.
• ClearAutoLoginDelegates - Clears the login delegates once the login process has passed or failed.
• OnLoginFailed [LocalUserNum] [ErrorCode] - Called if the server login fails and calls ClearAutoLoginDelegates().
  • LocalUserNumber - The controller number of the associated user.
  • ErrorCode - The EOnlineServerConnectionStatus async error code that occurred.
• OnLoginChanged [LocalUserNum] - Called when the server login has completed and registers the server.
  • LocalUserNumber - Unused.
• RegisterServer - Registers the dedicated server with the online service.
• OnServerCreateComplete [SessionName] [bWasSuccessful] - Called when the dedicated server registration has completed.
  • SessionName - The Name of the session.
  • bWasSuccessful - If TRUE, the registration was successful.
• TellClientsToReturnToPartyhost - Iterates the player controllers and tells them to return to their party.
• TellClientsToTravelToSession [SessionName] [SearchClass] [PlatformSpecificInfo] - Iterates the player controllers and tells remote players to travel to the specified session.
  • SessionName - The Name of the session to register.
  • SearchClass - The OnlineGameSearch class that should be populated with the session.
  • PlatformSpecificInfo - The binary data to place in the platform-specific areas.
• AddInactivePRI [PRI] [PC] - Adds the given PlayerReplicationInfo to the inactive list and removes it from the active list.
  • PRI - The PlayerReplicationInfo of the player to add to the inactive list.
  • PC - The PlayerController of the player associated with the PRI.
• FindInactivePRI [PC] - Finds and returns the PRI associated with the given re-entering player.
  • PC - The PlayerController of the player.
• OverridePRI [PC] [OldPRI] - Overrides, as needed, the properties of the PlayerReplicationInfo of the given player with properties from the old PlayerReplicationInfo which were assigned during the login process.
  • PC - The PlayerController of the player.
  • OldPRI - The PlayerReplicationInfo holding the properties assigned at login.

Pausing

• CanUnpause - Delegate. Called when the game is requested to be unpaused to determine if that action is allowed. Returns TRUE if the game can be unpaused. The default implementation allows all requests to succeed.
• SetPause [PC] [CanUnpauseDelegate] - Pauses the game and adds the delegate to the list if the given player has the right to pause the game. The delegate is called to see if it is ok to unpause the game, e.g. the reason the game was paused has been cleared.
  • PC - The PlayerController of the player trying to pause the game.
  • CanUnpauseDelegate - The delagate (matching the CanUnpause delegate's signature) that will be used to determine if this pause is allowed to be cleared.
• ClearPause - Checks the list of delegates to determine if the pausing can be cleared. If the delegate says it's ok to unpause, that delegate is removed from the list and the rest are checked. The game is considered unpaused when the list is empty.
• ForceClearUnpauseDelegates [PauseActor] - Forcibly removes an object's CanUnpause delegates from the list of pausers. If any of the object's CanUnpause delegate handlers were in the list, triggers a call to ClearPause(). Called when the player controller is being destroyed to prevent the game from being stuck in a paused state when a PC that paused the game is destroyed before the game is unpaused.
  • PauseActor - The Actor to clear all CanUnpause delegates for.
• AllowPausing [PC] - Returns whether the given player is allowed to pause the game.
  • PC - The PlayerController of the player requesting to pause the game.

Gameplay

• SetGameSpeed [T] - Sets the game speed and world TimeDilation to the given value. This controls how often the game's Timer() is executed.
• AllowCheats [P] - Returns whether cheats are allowed in the game. The default is to allow cheats in offline games only.
• UpdateGameplayMuteList [PC] - Used to notify the game type that it is ok to update a player's gameplay specific muting information now. The player needs to notify the server when it is possible to do so or the unique net id will be incorrect and the muting not work.
  • PC - The PlayerController of the player to update muting info for.
• RecalculateSkillRating - Used by the game type to update the advertised skill for this game.
• MatineeCancelled - Called when this PC is in cinematic mode, and its matinee is cancelled by the user.
• GetCoverReplicator - Returns the CoverReplicatorBase for the game. If none exists, a new one is spawned and that is returned.
• NotifyKilled [Killer] [Killed] [KilledPawn] [damageType] - Notifies a given player it has been killed. Called from Killed().
  • Killer - The Controller of the player that did the killing.
  • Killed - The Controller of the player that was killed.
  • KilledPawn - The Pawn of the player that was killed.
  • damageType - The DamageType of the damage responsible for the player's death.
• Killed [Killer] [KilledPlayer] [KilledPawn] [damageType] - Called by the Pawn to notify the game it has been killed.
  • Killer - The Controller of the player that did the killing.
  • Killed - The Controller of the player that was killed.
  • KilledPawn - The Pawn of the player that was killed.
  • damageType - The DamageType of the damage responsible for the player's death.
• PreventDeath [KilledPawn] [Killer] [DamageType] [HitLocation] - Called by the Pawn to allow the game to override the Pawn being killed.
  • KilledPawn - The Pawn of the player that was killed.
  • Killer - The Controller of the player that did the killing.
  • DamageType - The DamageType of the damage responsible for the player's death.
  • HitLocation - A Vector specifying the location of the hit that caused the player's death.
• ReduceDamage [Damage] [injured] [instigatedBy] [HitLocation] [Momentum] [DamageType] [DamageCauser] - Called From TakeDamage() when damage is done to a player to allow the amount of the damage to be modified.
  • Damage - Out. Takes in and outputs the amount of damage to be done.
  • injured - The Pawn of the player being damaged.
  • instigatedBy - The Controller of the player responsible for the damage.
  • HitLocation - A Vector specifying the location of the hit that caused the damage.
  • Momentum - A Vector specifying the direction and magnitude of the momentum applied by the damage.
  • DamageType - The DamageType of the damage being done.
  • DamageCauser - The Actor that actually caused the damage.
• AddObjectiveScore [Scorer] [Score] - Increments the given player's score after completing an objective.
  • Scorer - The PlayerReplicationInfo of the player.
  • Score - The amount to add to the player's score.
• ScoreObjective [Scorer] [Score] - Adds to the player's score and checks if the game should end after completing an objective.
  • Scorer - The PlayerReplicationInfo of the player.
  • Score - The amount to add to the player's score.
• CheckScore [Scorer] - Called by ScoreObjective() to determine if the game should end based on the gievn player's score.
  • Scorer - The PlayerReplicationInfo of the player.
• ScoreKill [Killer] [Other] - Adds to the players score and checks if the game should end after a kill.
  • Killer - The Controller of the player that caused the player death.
  • Other - The Controller of the player that died.

Options

• GrabOption [Options] [Result] - Parses out the next key-value pair from the options string. Returns TRUE if a pair was found.
  • Options - Out. Takes in the current options string and outputs the options string minus the parsed pair.
  • Result - Out. Outputs the parsed pair.
• GetKeyValue [Pair] [Key] [Value] - Breaks up a key-value pair into a key and a value.
  • Pair - Takes in the key-value pair.
  • Key - Out. Outputs the key.
  • Value - Out. Outputs the value.
• ParseOption [Options] [InKey] - Parses out the key-value pair from the options string for the given key. returns the key-value pair in String form.
  • Options - Takes in the current options string.
  • InKey - The key to find.
• HasOption [Options] [InKey] - Returns whether the key-value pair for the given key exists in the options string.
  • Options - Takes in the current options string.
  • InKey - The key to find.
• GetIntOption [Options] [ParseString] [CurrentValue] - Returns an Int value for the given key from the options string.
  • Options - Takes in the current options string.
  • ParseString - The key to find.
  • CurrentValue - The current, or default, value to use if the key is not found.

Mutator

• AddMutator [mutname] [bUserAdded] - Adds the specified mutator to the game.
  • mutname - A string specifying the mutator class to add.
  • bUserAdded - If TRUE, the mutator was added by the player through the game's interface.
• RemoveMutator [MutatorToRemove] - Removes the given mutator from the game.
  • MutatorToRemove - The Mutator to remove.
• AllowMutator [MutatorClassName] - Returns whether the given Mutator class can be added to the game.
  • MutatorClassName - A string specifying the mutator class to check.
• Mutate [MutateString] [Sender] - Passes an input string to the mutator list. Used by PlayerController.Mutate(), intended to allow mutators to have input exec functions (by binding mutate xxx to keys).
  • MutateString - The String to pass to the mutator list.
  • Sender - The PlayerController of the player sending the mutate string.
• CheckRelevance [Other] - Returns TRUE if actor is relevant to this game and should not be destroyed. Called in Actor::PreBeginPlay(), intended to allow mutators to remove or replace actors being spawned.
  • Other - The Actor to check for relevance.
• ModifyScoreKill [Killer] [Other] - Passes a player kill to the mutator list to process for scoring.
  • Killer - The Controller of the player that caused the player death.
  • Other - The Controller of the player that died.
• DriverEnteredVehicle [V] [P] - Passes a vehicle entered event to the mutator list.
  • V - The Vehicle that was entered.
  • P - The Pawn of the player entering the vehicle.
• CanLeaveVehicle [V] [P] - Checks whether the given Pawn can leave the specified Vehicle. Allows the mutator list to make the decision if any mutators exist.
  • V - The Vehicle that is being exited.
  • P - The Pawn of the player exiting the vehicle.
• DriverLeftVehicle [V] [P] - Passes a vehicle exited event to the mutator list.
  • V - The Vehicle that is being exited.
  • P - The Pawn of the player exiting the vehicle.

Cheat Detection

• EnableStandbyCheatDetection [bIsEnabled] - Turns standby detection on or off.
  • bIsEnabled - If TRUE, cheat detection is turned on. Otherwise, it is turned off.
• StandbyCheatDetected [StandbyType] - Notifies the game code that a standby cheat was detected.
  • StandbyType - The EStandbyType of the cheat detected.

Automated Testing

• DoTravelTheWorld - Starts world traveling for automated testing.
• IsAutomatedPerfTesting - Returns true if Automated Performance testing is enabled.
• IsCheckingForFragmentation - Returns true if checking for fragmentation is enabled.
• IsCheckingForMemLeaks - Returns true if checking for memory leaks is enabled.
• IsDoingASentinelRun - Returns true if doing a sentinel run.
• ShouldAutoContinueToNextRound - Returns true if should auto-continue to next round.
• CheckForSentinelRun - Asks AutoTestManager to start a sentinel run if needed. Must be called by gameinfo subclass - not called in base implementation of GameInfo::StartMatch().

Game Lifecycle

The lifecycle of a game - when the gametype is created, how players are created, how the game checks for ending conditions, etc. - is an important aspect to understand. It will help you to adapt the engine to fit your specific gametype. A complete rundown of the game flow from engine startup to the gametype's own lifecycle is provided on the UnrealScript Game Flow document.

Gametype Prefixes

The gametype system in Unreal Engine 3 provides a mechanism for automatically selecting the appropriate GameInfo class to use for maps based on the prefix given to the map filename. The DefaultMapPrefixes and CustomMapPrefixes arrays hold a list of GameTypePrefix structs each of which maps a specific prefix string to a gametype class (among other things).

GameTypePrefix Struct

• Prefix - A String specifying the map prefix. The map prefix is a sequence of characters that begins the map name and is followed by a hyphen (-). The hyphen is not included in the prefix. It simply spearates the prefix from the rest of the map name.
• bUseCommonPackage - If TRUE, a common package should be generated for this gametype. See Common Packages for more details.
• GameType - A String specifying the class of the gametype to map to the prefix. This is the gametype that will be used for maps with this prefix if no gametype is specified in the URL.
• AdditionalGameTypes - An array of Strings specifying additional gametype classes supported by this map prefix via the URL.
• ForcedObjects - Forced objects (and classes) that should go into the common package to avoid cooking into every map.

Adding Gametype Prefixes

Gametype prefix mappings are added by creating new entries in the [Engine.GameInfo] section of the DefaultGame.ini config file. An example is show below:

[Engine.GameInfo]
+DefaultMapPrefixes=(Prefix="DM",bUsesCommonPackage=FALSE,GameType="UTGame.UTDeathmatch")

Common Packages

TODO

Pausing

The game is paused by calling SetPause() on the GameInfo. SetPause() accepts a delegate as a parameter which is added to this array. When the game is paused for a specific reason, a particular delegate that checks to make sure that condition is no longer an issue is passed to SetPause().

For example, in PlayerController.uc when a controller is plugged in or unplugged, it calls SetPause() on the PlayerController passing it the CanUnpauseControllerConnected function, which is then passed on to SetPause() of the GameInfo:

// Pause if the controller was removed, otherwise unpause
SetPause(!bIsConnected,CanUnpauseControllerConnected);

The CanUnpauseControllerConnected function simply returns whether the controller is plugged in or not:

If no delegate is passed to the SetPause function in the GameInfo, then the default CanUnpause function is used which always returns true. This would be the case if a player simply wants to pause the game since there are no particular conditions to be checked when they unpause the game.

When ClearPause() is then called to unpause the game, each delegate in the Pausers array is executed. If the delegate returns TRUE, it is removed from the array. Only when the array is empty will the game be unpaused.

Mutators

Mutators are special Actors that can be applied to a game to modify certain aspects of the gameplay. For instance, Mutators can do the following:

• Modify the player login parameters
• Modify the properties of the player's Pawn
• Modify, remove, or replace any or all Actors (which are not bGameRelevant=TRUE)
• Override the player start location
• Modify the game ending conditions

The above items are just some of the aspects of the game that Mutators can modify.

Adding Mutators

Mutators are added to a game through the AddMutator() function in GameInfo. This can potentially be called from any other Actor to allow mutators to be added dynamically during play to modify certain aspects in response to gameplay events. By default, this is called from InitGame() to add any Mutators specified in the map URL.

Mutators can be specified in the map URL by adding Mutator= followed by the list of Mutators to add, with each separated by a comma. For example:

MapName?Game=GameName?Mutator=BigHeads,Instagib

This map URL would load the MapName map using the GameName gametype which would then add the BigHeads and Instagib mutators. The map URL for adding Mutators in this manner would usually be dynamically created by a menu allowing the player to choose the Mutators to use. It would also be possible to hardcode one or more "default" mutators to be added for a particular gametype by adding exlpicit AddMutator() calls for those Mutators in the InitGame() event for the gametype.