My program doesn't have bugs. It just develops random features.

UE3:Mapping for Jailbreak (UT3)

From Unreal Wiki, The Unreal Engine Documentation Site
Jump to: navigation, search

This article gives an overview about how to create maps for the custom UT3 gametype Jailbreak.

Preparing the UT3 Editor[edit]

Before you start diving into the editor, make sure you have the latest version of UT3 Jailbreak installed. You'll be needing actors and Kismet objects from the Jailbreak.u and JailbreakContent.u packages (and possibly from JailbreakTitanContent.u as well, depending on your map) to set up Jailbreak-specific things in your map. To load them automatically, open your UTEditor.ini (MyDocs\MyGames\UT3\UTGame\Config), find the [ModPackages] section and add the following lines to it:

ModPackages=Jailbreak
ModPackages=JailbreakContent
ModPackages=JailbreakTitanContent

Now you can open the editor and map right away. See Spoondog's Guide to Mapping for Jailbreak for general considerations about Jailbreak maps, but keep in mind that it was written for JB2004.

To playtest Jailbreak maps in the editor, you need to edit your UTEditor.ini. Look for the line InEditorGameURLOptions=... in the [UTEditor.UTUnrealEdEngine] section and extend it to something like:

InEditorGameURLOptions=?game=Jailbreak.Jailbreak?mutator=Jailbreak.JBMutatorTesting?quickstart=1?numplay=1

The Jailbreak testing mutator is not selectable in the game by default, but it will provide some helpful console commands for testing Jailbreak-specific features of your map. Type "mutate help" at the in-game console to see a list of possible commands. (All commands must be prefixed with "mutate".)

Starting a new map[edit]

As always in UT3 it's probably better to start out additive, i.e. with an empty world, because it saves you a lot of time when rebuilding lighting. If your Jailbreak map is going to be indoor, just add a cube of about the size your map will be and start subtracting from that. The first thing you should probably do when you start a new Jailbreak map is setting up the map info:

  1. Open View -> World Properties.
  2. Open the group WorldInfo, find the property MyMapInfo and click the blue triangle button.
  3. Select JBMapInfo from the pop-up menu. If it isn't listed, make sure you have loaded the Jailbreak package. (You can do so from the Actor Classes browser.)

In addition to the usual UTMapInfo properties for the radar map, music and level descriptions, the JBMapInfo also has some gameplay-related properties:

Execution group
ExecutionFallbackDelay
Maximum time in seconds players are allowed to live during the execution sequence before they will definitely be killed by the game.
JBMapInfo group
bDarkMatch
Whether "darkmatch" rules should be applied to the map. That means, players do not have any ambient glow and the area immediately surrounding your view is lit up a bit. Play DM-DarkMatch to get a feel for this mode.
bStartWithLockerWeaps
Whether free players should start with the weapons from the nearest weapon locker, like in VCTF or Warfare. Jailed players always only start with default weapons.
TransportationDevice group
See Transportation settings below for details.
CustomTranslocatorClass
An Inventory class to replace the Translocator on this map. If specified, and the game determines that the Translocator should be used, this inventory class is given to the player instead.
DefaultTransportationDevice
The default transportation device (Translocator or Hoverboard) to give players in this map. If Translocator and Hoverboard are both allowed (i.e. none of the "No Translocator/Hoverboard" mutators are in use), this property also tells which of the two to prefer.
SupportedTransportationDevice
What transportation devices are allowed on this map at all. Unsupported devices can't be forced, but if both are supported and forced (i.e. the "Force Translocator/Hoverboard" mutators are both in use), this property specifies which one to use.

Note that darkmatch, locker weapons and transportation settings are also available for arenas and will override the map settings there.

Jailbreak's music manager works a bit differently than the default UT3 music manager, so the standard music arrangements might not work as nicely for Jailbreak. No need to worry though, as there are custom arrangements of the stock music in the JailbreakMusicArrangements package.

Concepts[edit]

A classic Jailbreak map contains two bases, each with a release switch and a spawn area for one team, and two jails, each with player starts for one team. Jail locations are a frequent reason for debate, as they could be in the team's own base (not very realistic), in the enemy base (may cause "base swap", i.e. all players are in their respective enemy base and it's difficult to gain control over the own base again) or on neutral ground. The latter is usually the preferred way to do it because released players will not immediately gain control over either base.

The classic layout goes back to the UT version of Jailbreak, where only one switch per team was really supported and jail areas had to be assigned to a specific team. UT3 Jailbreak has come a long way since then. There can be more than one release switch per team, switches can change team ownership and even be neutral or disabled. Similarly, jail areas can contain player starts for both teams, allowing "shared jails" that can have separate exits for the two teams. Prisoners of both teams can't attack each other unless they pull out a melee weapon. This kind of jail fight is also allowed between players of the same team without penalty.

Jail setup[edit]

Jail areas are defined with volumes associated to a JBInfoJail, a subclass of Info. Any kind of volume can be used, but the preferred type is JBVolumeJail, because it prevents players from using the Translocator to escape. The names of the volumes can be entered in the JailVolumes list of the JBInfoJail, but a much easier way is to use Kismet. The JBInfoJail actor has a Kismet event called Jail Status, which controls most of the jail functionality. That Jail Status event can be used to assign volumes to the jail as well.

Jails are not owned by any team directly. To ensure only players of one team are put in a jail, simply place UTTeamPlayerStarts for that specific team inside any of the volumes assigned to the JBInfoJail. There's a property called bReleasesBothTeams in JBInfoJail that should have the value True in most cases. Only set it to False if your jail prevents the opposite team from leaving this jail, for example if you have a shared jail with separate exits for both teams. Keep in mind that regular jails allow people to walk in while the door is open. Such jails, even though designed to only contain one team's players, should allow the enemy player to get out as well while the jail is open.

Release setup[edit]

Jails are opened by release switches, subclasses of UTGameObjective >> JBObjectiveRelease. The jails a release switch opens can be specified either by adding the JBInfoJail's Tag value to the JailTags list of the switch actor or in Kismet by linking the corresponding Jail Status events to the Jails connector of the release switch's Release event. It is recommended to set the value of the Jail Status property ReleasingTeam to 0 (red) or 1 (blue) so the game knows which team to open the jail for, especially if it's a neutral switch.

Jails will automatically monitor whether they are currently open and for which team. For this to work, the mapper needs to specify navigation points that act as jail exits via the Jail Doors connector of the Jail Status event. when the jail is closed, the navigation point must be blocked. Each jail door point must either be outside the jail volumes or must have a direct connection to a navigation point outside the jail volume. Almost all navigation point types support toggling of their blocked status, but only few make sense as jail door. The most obvious choice would be the DoorMarker of an InterpActor used as jail door. Other options include the JBJumpPad and the various JBTeleporter versions.

To start the mechanism that eventually allows players to leave the jail area, use the Activated output connector of the Jail Status event. This event should open the door or enable the teleporter, jumppad, lift or whatever else your jail uses. The Opened output of the Jail Status will activate once the first jail door navigation point is unblocked and the Closed output activates when the last jail door navigation point is blocked again. If you have multiple jail doors, make sure they are opened in a way that during the entire release (first open to last close) there is always at least one unblocked jail door navigation point, otherwise you may confuse the release mechanism.

Execution setup[edit]

When all players of a single team are captured, the Start execution output of all Execution events is activated. The execution script should take care of killing captured prisoners in all jails. The execution sequence should activate an execution camera via the Set execution camera action. Players of the capturing team, spectators and dead players of the captured team will be viewing the execution through the specified camera actor. This camera can be animated via Matinee and Set execution camera can be used throughout the entire execution sequence to switch to a different camera.

If your execution script should not end right when all players are dead, use the End of execution action to explicitly specify the end of your script. Note however, that if you use End of execution anywhere in your script, it must always be used to signal the end of the execution script. Also be sure to set the ExecutionFallbackDelay in your JBMapInfo to a value that won't interfere with your execution script. Be generous with the time margin here, a weird online bug on an early version of JB-Pagoda was caused by the fallback execution (players just falling over) kicking in at approximately the same time as the execution script trying to gib players.

Arena setup[edit]

Arenas are almost entirely set up in Kismet via the Arena Fight event. The only thing you need to place in the map are the arena PlayerStarts. To make things interesting, arenas can be integrated into the main area of the map, like it is done on JB-FacingWorlds. It is common practice to have the arena area completely separated from everything else, though. JB-Gasoline, for example, has a separate arena room that is neither visible nor reachable in any way from the main playing area. Arena winners and losers can be respawned as special startspots that don't necessarily have to be PlayerStarts.

UT3 Jailbreak not only supports one-on-one deathmatch arenas, but also x-on-x team deathmatch arenas and "challenge" arenas where killing the opponents isn't the primary goal. Challenge arenas might also be for one team only, with your only enemy being the arena timer. Challenge arenas could be anything from a race track to an obstacle course. A one-team challenge could e.g. be used to activate an alternate escape route for the remaining players in jail.

Arena fights aren't started automatically, but should be activated via a Kismet script. Use the Schedule arena fight action to let the game find players for an arena fight and start the fight after a short countdown. You can use the Request arena fight and Ignore for arena fight actions to let players volunteer for or opt out from being selected for an arena fight respectively. To cancel a scheduled arena fight during the start countdown, use the Cancel arena fight action. To end an arena fight in progress, especially for declaring the winner of a challenge arena, use the End of arena fight action.

For arenas involving certain powerups, it might be a good idea to ensure those are available when the arena fight starts. You can use the Respawn pickup action to ensure a pickup is available.

Alternate escapes[edit]

Instead of (or in addition to) arena fights, a mapper might include an alternate escape route for the jails. This feature must be well-balanced or it can make a map unplayable because either team can capture the opponent. Therefore activating or using alternate escapes should be made sufficiently difficult or expensive. Ideally an escape route is shut down during execution and any players inside should be executed as well.

For example, JB-FacingWorlds has a second jumppad exit, but that one can only be activated by doing a Titan melee attack on the titan pad inside the jail/arena tower. Activating it and using the jumppad to escape is relatively easy, but the player activating the alternate escape is killed and usually doesn't have enough time to reach the jumppad because the titan explosion is in the way. The balance here is that the escape requires you to spend a whole Titan transformation and that it's extremely difficult to use it to release yourself. And of course it is only available if the Titan mutator is active.

Other alternate escapes might require prisoners to form a human ladder. In Jailbreak players can stand on each others' shoulders to reach a small hole in the wall that can only be entered when the player is crouched. You can only crouch while standing on something, so a human ladder is the only way to get into the escape route.

The escape route itself should be set up like a jail area, but with a JBInfoEscape instead of a JBInfoJail. The JBInfoEscape's Tag should be added to the JBInfoJail's EscapeRouteTags so the game knows how the escape is connected. Like regular jails, escape routes might have to be opened in order for players to escape. If a JBObjectiveRelease (with bIsPrimaryRelease set to False) is used to perform this activation, the activating player is remembered as assister. Similarly, any players forming a human ladder to help a player enter an escape route are remembered as assisters as well. If a player manages to reach freedom, any assisting players score a point and receive one hero point.

Transportation settings[edit]

Unlike the artificial separation between CTF and VCTF, Jailbreak is a single vehicle-supporting gametype where the mapper decides whether to include vehicles or not. Matching this philosophy, Jailbreak also allows the mapper to decide whether to give players a Translocator like in CTF and a Hoverboard like in VCTF, but this mapper decision isn't set in stone. The "transportation device" settings can be a bit confusing at first, but they actually provide a great amount of flexibility to the mapper and the player or server admin.

Mappers are encouraged to always support both transportation devices, even if the map will be using only one or neither of them by default. Maps with a default transportation device should also stay playable if the player decides to play with both devices disabled. That means it should be possible to reach the release switches and exit jails without a Translocator or Hoverboard. If an arena definitely won't work at all without a specific transportation device, you can either set that device as required for the arena or disable the arena if the transportation device is not available.

In addition to the default "No Translocator" mutator included in UT3, Jailbreak also provides a "No Hoverboard" mutator (which could also be used in VCTF or Warfare) and the "Force Hoverboard/Translocator" mutators, which only really work in Jailbreak. These four mutators interact with the map's (or arena's) transportation settings in a well-defined (and hopefully obvious) way. A transportation device is "available" if the corresponding "No" mutator isn't used and a device is "forced" if the corresponding "Force" mutator is active.

  • If an arena requires a specific device, it will ignore the default and supported device settings and the four mutators.
  • Conflicts between the supported devices and default devices settings (i.e. a device is specified as default, but is not supported) are resolved in favor of the supported devices.
  • Unsupported devices cannot be forced via mutator.
  • If both devices are supported, forcing either of them will enable that device even if the default device setting would prefer the other device if both are available.
    For the special case when both devices are forced, the supported device setting has the options "Both (prefer Translocator if forced)" and "Both (prefer Hoverboard if forced)" to let the mapper resolve this ambiguity.

Reference[edit]

Jailbreak-specific actors[edit]

JBExecution[edit]

A helper actor for execution sequences. The various subclasses provide more specific executions, like depresurization or burning.

JBInfoEscapeRoute[edit]

Info actor for alternate escape routes. Works exactly like a JBInfoJail.

JBInfoJail[edit]

Info actor for jails. See Jail setup for details on using it.

JBJumpPad[edit]

A jumppad that can be Kismet toggled and optionally made team-specific.

JBObjectiveRelease[edit]

The release switch. There are subclasses for neutral, blue and red switches. See Release setup for details on using them.

JBTeleporter[edit]

A teleporter that can be Kismet toggled and optionally made team-specific.

JBTurret[edit]

An automatic turret.

JBVehicleFactory_NighShade[edit]

Spawns a special version of the Nightshade that can deploy an X-Ray Field instead of Spidermine Traps.

JBVehicleFactory_StealthBender[edit]

Spawns a special version of the Stealthbender that can deploy an EMP Mine instead of Spidermine Traps.

Jailbreak-specific volumes[edit]

JBKillZVolume[edit]

A UTKillZVolume that only affects specific classes.

JBLadderVolume[edit]

A LadderVolume that allows the mapper to modify the ladder direction.

JBSlowVolume[edit]

A permanent version of the Slow Field, but without the green cube visuals. (It's up to the mapper to provide visual effects.)

JBVolumeJail[edit]

This volume does not define a jail area, but is a JBVolumeTransportRestriction preconfigured for use as a jail-defining volume. There's also a dynamic version of this volume that can be attached to InterpActors.

JBVolumeTransportRestriction[edit]

Imposes certain restrictions on players inside this volume. The restrictions are configurable and include:

  • using the Hoverboard
  • throwing Translocator discs while in the volume
  • translocating while in the volume
  • translocating to a disc in the volume
  • transforming into a Titan or Behemoth

Players from one team can be excluded from these restrictions and the restrictions can be turned off entirely via Kismet Toggle. There's also a dynamic version of this volume that can be attached to InterpActors.

JBVolumeTunnelExit[edit]

Normally players can't fall off ledges while walking or crouching. This volume removes that feature in this area and thus allows players to exit low tunnels while crouching.

JBXRayVolume[edit]

A permanent version of the X-Ray Field, but without the inverted vision effect. (It's up to the mapper to provide visual effects.)

Jailbreak-specific Kismet events[edit]

Arena Fight[edit]

Describes an arena in the map, including the type of arena, where players spawn, etc.

An arena event is not tied to any actor in the level. Every Arena Fight event stands for a separate arena.

Outputs:

Failed
An attempt to schedule an arena fight in this arena (e.g. via Start arena fight) has failed.
Scheduled
A fight in this arena was successfully scheduled.
Canceled
A scheduled fight in this arena was canceled before it started.
Started
A scheduled arena fight has started.
Ended
An arena fight was ended regularly.
Aborted
An arena fight has ended without a winner because the arena timer has run out.

Variables:

Arena start spots (in)
Start spots for players who fight in this arena. These must be PlayerStarts or UTTeamPlayerStarts and should not be changed ar runtime.
Winner start spots (in)
Possible start spots for the arena winner(s). These can be any kind of NavigationPoint and should not be changed ar runtime.
Loser start spots (in)
Possible start spots for the arena loser(s). These can be any kind of NavigationPoint and should not be changed ar runtime.
Arena goals (in)
(not yet implemented)
Players (out)
All outputs, except Failed, provide a list of players selected for the arena fight.
Winners (out)
The Ended output provides the list of winners here.
Arena Fight (out)
All outputs, except Failed, provide an identification object for the arena fight here. This object can be used in Cancel arena fight and End of arena fight to identify the arena fight to cancel or end.

Execution[edit]

Provides an entry point for the execution script. This event will not trigger if both teams are captured.

An Execution event is not tied to any actor in the level. All Execution events are activated simultaneously for execution events.

Outputs:

Start execution
The execution has started. One of the first things you should do here is the Set execution camera action.
All prisoners dead
All remaining prisoners have died, either due to your script or because the fallback execution kicked in. If your execution script needs to run beyond this point, you should use the End of execution action.

Variables:

Capturing Player (out)
The player who was responsible for jailing the last player of the captured team. Might be empty if the last free player left the game or a player on the captured team if it was a team kill or suicide.
Captured Team (out)
The number of the team that was captured.
Captured Player (out)
The last player of the captured team who went to jail.

Jail Status[edit]

Associates jail volumes and exit markers to a JBInfoJail and provides an entry point for release scripts.

A Jail Status event must always be associated to a JBInfoJail. Multiple events may be associated to a single JBInfoJail, e.g. to provide exit markers for different teams in a shared jail.

Properties:

int ReleasingTeam
The number of the team allowed to activate this event. (-1 = any team, 0 = red, 1 = blue) The event won't trigger if the jail was activated by a different team.
This property also specifies, which team can use the Jail Doors specified for this Jail Status event.

Outputs:

Activated
The jail was activated by a release switch. This output should activate the release mechanism, e.g. open jail doors or activate teleporters/jumppads.
Opened
The first jail door has opened.
Closed
The last jail door has closed, the release is over for this jail.
Locked
The jail has been locked, either by Kismet Toggle on the JBInfoJail actor or by a mutator. Either way, the jail will ignore activations from now on.
Unlocked
The jail is no longer locked and can be activated again.

Variables:

Jail Volumes (in)
The volumes making up the jail arena. Volumes from all Jail Status events are merged with the JailVolumes list of the JBInfoJail actor.
Exit Markers (in)
The NavigationPoints marking exit locations of this jail. Make absolutely sure these NavPoints are initially blocked, otherwise the game considers the jail open all the time. This manifests in the release switch not working and the round not ending despite all players being captured. If you use a DoorMarker, make sure you set bBlockedWhenClosed to True. If a ReleasingTeam other than -1 is specified (strongly recommended), the jail exit marker is used only for that team.
(This variable link was formerly called "Jail Doors", but had the same meaning.)
Releaser (out)
The player who activated the release switch. Might be empty if the release was activated via script.
Release Switch (out)
The JBObjectiveRelease actor used to activate this jail. Use this to distinguish between the different switches if this jail is associated to more than one switch, e.g. because it has an alternate escape route.

Release[edit]

Can be used to associate base volumes and jails with a release switch and provides switch-related events.

Outputs:

Release activated
The release switch was activated. Do not activate actual release mechanisms through this output, use the Jail Status output Activated instead.
Release ended
All jails activated by this switch are closed again and the release has ended.

Variables:

Base Volume (in)
Sets the release switch's MyBaseVolume. This volume can be changed at runtime. Leave it empty if you already specified the MyBaseVolume property of the switch or just want to rely on BaseRadius.
Near Base Volume (in)
Sets the release switch's NearBaseVolume. Leave it empty if you already specified the NearBaseVolume property of the switch or just want to rely on NearBaseRadius.
Releasing Team (out)
The number of the team for which the switch was activated.
Releaser (out)
The player who activated the switch. Could be empty if the switch was activated via script.
Jails (event)
Connect this to Jail Status events of JBInfoJail actors that will be activated by the release switch.

Jailbreak-specific Kismet actions[edit]

Activate Release[edit]

Remotely activates a release switch for a specified player and/or team.

Become Titan[edit]

Forces a player to transform into a titan or behemoth.

Cancel arena fight[edit]

Cancels a scheduled arena fight before it starts.

Count players[edit]

Counts free, jailed and arena players, optionally in a specific jail or arena, or only jailed players releasable through a specific switch.

Do Melee Attack[edit]

Forces a titan or behemoth player to perform a melee attack.

End of arena fight[edit]

Ends an arena fight in progress, potentially declaring one or more players the winner.

End of execution[edit]

Manually marks the end of the execution script. If this action is used anywhere in a map, Jailbreak expects it to end all possible executions in that map.

Get match settings[edit]

Returns various match-related settings, such as time/score limit and whether titans are allowed. It also tells whether the Translocator or Hoverboard can be used in the map or a specific arena, based on the map settings and mutators in use.

Get prisoners[edit]

Returns a list of prisoners, optionally filtered by team, jail and whether the prisoners are bots or not.

Ignore for arena fight[edit]

Lets a player opt out from arena fights.

Pick one[edit]

Picks and optionally removes an object from an object list, like the prisoner list returned by Get prisoners.

Play Announcement (Target)[edit]

Special version of the standard Play Announcement action that sends the announcement only to the specified target players.

Request arena fight[edit]

Lets a player volunteer for arena fights in general or one specific arena fight. Players requesting an arena fight are preferred when the game picks players for the arena.

Respawn pickup[edit]

Ensures a pickup is available immediately, without any respawn wait.

Schedule arena fight[edit]

Schedules an arena fight, picking random players if none specifically requested a fight.

Set execution camera[edit]

Sets or changes the execution camera actor.

Set Owning Team[edit]

Changes team ownership of actors that support it. Potential targets are release switches, JBTurrets, JBJumpPads and the various JBTeleporter versions.

Spawn Projectile[edit]

Spawns a projectile, like the standard Spawn Projectile action. The difference is, that you can specify spawn and target locations with actors variables and an instigator is not required.

Start Execution[edit]

Activates a JBExecution. This is a latent action, i.e. it will trigger outputs some time after it has been activated.

Jailbreak-specific Kismet conditions[edit]

Final Round?[edit]

Returns whether this is definitely the last round being played.

The game is in its final round when

  • it is in overtime - the next capture decides the match or
  • there's a goal score and
    • any team reached or exceeded the goal score, i.e. the match is actually over, or
    • the execution sequence is running and the capturing team is about to reach the goal score or
    • both teams only need one more capture to reach the goal score.

Is a bot?[edit]

Tests whether the specified player is a bot. You can use this e.g. to tell bots how to win an arena fight or how to use an escape route.

Is locked?[edit]

Tests whether the specified JBInfoJail or JBInfoEscapeRoute is locked.

Outputs:

Yes
The jail is locked and can't be activated for release.
No
The jail is not locked and can be activated by the associated release switch(es).

Variables:

Jail (in)
The JBInfoJail or JBInfoEscapeRoute actor to test.
Kismet-locked (out)
Returns True if the jail was locked via the Toggle action.
Script-locked (out)
Returns True if the jail was locked from UnrealScript, e.g. by a custom Jailbreak mutator.

Respawn Type[edit]

Tests where a player has just spawned.

Outputs:

Freedom
The player regularly spawned in freedom. This usually only happens at the beginning of a round or when a free player was killed by a jailed player.
Jail
The player regularly spawned in jail.
Arena
The player spawned in an arena.
Arena winner
The player has won an arena match. This is the same as Freedom unless there are special winner start spots for the arena.
Arena loser
The player has lost an arena match. This is the same as Jail unless there are special loser start spots for the arena.
Unknown
The player respawn type could not be determined. This usually only happens if another mod broke things, which most likely breaks Jailbreak in other, more severe ways as well. (Might be removed in future versions.)

Currently there is no easy way to figure out which arena or jail exactly a player respawned at. You either need to use the Player Spawned event to get the spawn point used, or look for the player in the various jails (via Get Prisoners) and arena fights. (via the Players list) These might be added as variable links later.