Capture the Flag
Flags are banners that can be picked up and carried by players, and captured in designated regions. They are highly configurable and can be used to implement a wide variety of gamemodes.
To define a flag's appearance, a standing-banner must be manually placed by the map creator, at the flag's initial location in the map. This allows complete control of the banner's colors and patterns. Unlike wools, each flag defined in XML creates a single, physical flag in the game. There are never multiple objects or items representing the same flag.
In addition to flags, a CTF map also requires nets for flags to be captured in, and posts for them to respawn at.
<flags>
<post id="red-flag-post" pickup-filter="blue-only">2,5,11</post>
<flag id="red-flag" name="Red Flag" color="red" post="red-flag-post"/>
<net post="red-flag-post" points="1" region="blue-net" capture-filter="blue-only"/>
</flags>
| Flags Element | Description | Value/Children |
|---|---|---|
| Node containing a group of flags, nets and posts for this match. | ||
| Sub-elements | ||
| A single physical flag (banner) in the map. | Flag Sub-elements | |
| A point or region(s) for flags to spawn at. | Point Provider | |
| A region that flags can be captured in. | Net Sub-elements |
Flags
A <flag> is a single physical banner that can be picked up, dropped, and captured.
Its appearance is defined by an actual banner built into the map, and it has a name and color which you can override in XML.
It can be owned by a specific team, or shared.
It can serve as a one-time objective, similar to wools, or it can award or deduct points.
A flag can award points for being captured, or at a specified rate while it is carried.
It can also come with a kit that is given to the carrier.
Filters can be used to control who can pickup/capture the flag and when.
| Flag Element | Description | Value/Children |
|---|---|---|
| A single physical flag (banner) in the map. | Flag Sub-elements |
| Flag Attributes | Description | Value | Default |
|---|---|---|---|
| Unique identifier used to reference this flag from other places in the XML. | String | ||
| Specify if this objective is required to win the match. Teams completing all of their required objectives will win regardless of score or blitz configuration. | true/false | ||
| Label that appears over the flag and on the scoreboard. | String | ||
| Color of the flag, used for the label, particles, etc. If omitted, the base color of the banner is used. | Dye Color Name | ||
| Broadcast messages related to the flag in chat. | true/false | true | |
| Play sounds, fireworks and other effects related to the flag. | true/false | true | |
| Display the flag under commands such as . | true/false | true | |
| Displays the flag on scoreboard. | true/false | true | |
| Determines if this flag counts as a win condition. | true/false | true | |
| Specify if the flag should be hidden from all visible locations to the player. These locations include chat, the boss bar, and the scoreboard. This attribute sets all five values above to true/false. | true/false | true | |
| PropertyRequiredThe flag's initial & default post. | Flag Post | ||
| The team that is defending this flag i.e. trying to prevent it from being picked up or captured. Players on this team will hear special sound effects to alert them when the flag is picked up or dropped. | Team ID | ||
| This flag can be carried by multiple teams. Causes the flag's scoreboard icon to have the color of the team carrying it, rather than the color of the flag itself. | true/false | false | |
| Specify if the flag cycles through all its posts in a sequential manner, as opposed to picking a random one. | true/false | false | |
| Custom message to display to players carrying this flag. Can be used to give special instructions, if necessary e.g., "You are carrying the flag, return it to your base!" | String | ||
| Sends a message in chat stating where the flag will respawn next. Note that the chosen post must have a name in order for the chat message to display. | true/false | ||
| The amount of points awarded for capturing this flag. If the flag has an , that team receives the points. Otherwise, the carrier's team receives them. A negative number can be used to take away points rather than give them. | Number | 0 | |
| The amount of points awarded per second while this flag is being carried. If the flag has an , that team receives the points. Otherwise, the carrier's team receives them. A negative number can be used to take away points rather than give them. | Number | 0 | |
| PropertyFilter who can pickup the flag. | Filter | ||
| PropertyFilter if the flag can be dropped at the current location. | Filter | ||
| PropertyFilter who can capture the flag. | Filter | ||
| PropertyGiven to players when they pick up the flag. | Kit | ||
| PropertyGiven to flag carriers when they lose the flag, for whatever reason. | Kit | ||
| PropertyGiven to players when they pick up the flag, and removed when they lose the flag. Only removable kits are allowed. The Kit page explains which kit types are removable. | Removable Kit | ||
| Allow this flag to be dropped on water, freezing the block under it into ice. | true/false | true | |
| Show a particle beam for this flag. | true/false | true | |
| Metric used to determine proximity to the flag. Accepts , , or . | Proximity Metric | ||
| Only calculate horizontal distance for flag proximity. | true/false | false | |
| Metric used to determine proximity to the net. Accepts , , or . | Proximity Metric | ||
| Only calculate horizontal distance for net proximity. | true/false | false |
Flag Sub-elements
| Flag Sub-elements | Description | Type |
|---|---|---|
| A net where only this flag can be captured, flags accept multiple net sub-elements. | ||
| PropertyRequiredThe flag's initial & default post. | Point Provider | |
| PropertyFilter who can pickup the flag. | Filters | |
| PropertyFilter if the flag can be dropped at the current location. | Filters | |
| PropertyFilter who can capture the flag. | Filters | |
| PropertyGiven to players when they pick up the flag. | Kit | |
| PropertyGiven to flag carriers when they lose the flag, for whatever reason. | Kit |
Posts
A post is a point or region where flags can respawn after being captured or dropped. It is essentially a spawn for flags instead of players, and like spawns, they are defined with point providers, and can be randomized.
A flag remembers the last post it was at and will respawn there after being dropped or captured. Each flag must have a default post, where it will be placed at the start of the match.
If a post is defined with a region rather than a point, flags will respawn at a random point in the region.
If multiple points or regions are given, one will be chosen at random (unless the sequential option is used).
Multiple flags can be at a post simultaneously only if there is space available for them.
One flag can also have multiple posts.
The time required for a flag to respawn is configurable, as well as the time it spends on the ground after being dropped.
Posts can be owned by a team, and award them points at a specified rate while a flag is there.
The permanent option can be used to make a post into something like a monument, where the flag is mounted after being captured once.
| Post Element | Description | Value/Children |
|---|---|---|
| A point or region(s) for flags to spawn at. | Point Provider |
| Post Attributes | Description | Value | Default |
|---|---|---|---|
| Unique identifier used to reference this post from other places in the XML. | String | ||
| An identifier used in chat messages to know where the flag spawns at. | String | ||
| The team that owns this post. | Team ID | ||
| When a flag is captured and returned to this post, remove the flag from the game and consider it a completed objective. The objective is credited to the of the post, which is required in this case. | true/false | false | |
| If this post has multiple points or regions, try them in order instead of choosing one at random, when spawning a flag here. | true/false | false | |
| Points awarded per second to this post's owner while any flag is at the post. Requires the attribute to be set. | Number | 0 | |
| PropertyFilter who can pickup a flag from this post. | Filter | ||
| Time that a flag stays on the ground after being dropped. Use to let the flag stay on the ground forever. | Time Period | 30s | |
| Time between a flag being captured/recovered and respawning at this post. During this time, the flag is completely gone, giving defenders a chance to return to their base. | Time Period | ||
| Filters when a flag can respawn at a point. | Filter | ||
| Speed that a flag "moves" to respawn at this post, after being captured/recovered. This is an alternative to that calculates the time based on the distance the flag must travel. | M/s | 8 | |
| The direction a banner faces after it is returned to this post. | -180 to 180 | ||
| Fallback spawn for flag if all other post filters deny. The fallback will be used even if its own post filter denies. | Post ID |
| Post Sub-elements | Description | Value/Children |
|---|---|---|
| PropertyFilter who can pickup the flag for this net. | Filters |
Nets
A <net> is a region that flags can be captured in.
Each net has a optional list of flags that it will accept.
If a net is defined inside a flag, only that flag can be captured in the net.
Several other options are available to control which flags can be captured and when.
A net can specify which post flags are returned to after being captured. This is how flags move between posts. A net can also force other flags to be returned when any flag is captured.
A net can be owned by a team, who will receive points for the flags captured in it. If the net has no owner, then the player carrying the flag will receive the points.
| Net Element | Description | Value/Children |
|---|---|---|
| A region that flags can be captured in. | Net Sub-elements. |
| Net Attributes | Description | Value | Default |
|---|---|---|---|
| Unique identifier used to reference this net from other places in the XML. | String | ||
| PropertyRequiredThe region flag carriers must enter to capture in this net. | Region | ||
| The team that owns this net. | Team ID | ||
| The amount of points awarded for capturing a flag in this net. If the net has an , that team receives the points. Otherwise, the carrier's team receives them. A negative number can be used to take away points rather than give them. | Number | 0 | |
| The ID of the post a flag returns to after being captured in this net. | Flag Post | ||
| | | Flag(s) that can be captured in this net. This is a list of flag IDs, separated with spaces. Attribute can not be specified on nets that are defined inside a flag. | String | ALL Flags |
| Flag(s) that are "rescued" by this net. This is a list of flag IDs, separated with spaces. Nothing can be captured in the net while any of these flags are being carried. However, if none of them are being carried, but some of them are dropped on the ground, capturing any flag in this net will instantly return the dropped flags. | String | ||
| A flag carrier stays "in" the net, even after they leave. If a player enters the net at a time when the flag can't be captured (e.g. because of or ) they can then leave the net and the flag will still be captured the moment it is allowed to be. This only happens if the player continues to carry the flag. As soon as they drop it, they are no longer "in" the net. | true/false | true | |
| PropertyFilter players who can capture in this net. | Filter | ||
| Custom message to display to flag carriers while capture is being prevented by a special rule or filter. This can be used to explain an unusual to a confused player. | String | ||
| All the flags listed in must be captured before any of them respawn. | true/false | false | |
| PropertyFilter when the flags captured in this net are allowed to respawn. | Filter | ||
| Custom message to broadcast in chat when flag respawn is prevented by a special rule or filter. This can be used to explain an unusual to confused players. | String | ||
| Location where the net can be found at, used to determine proximity. | X,Y,Z | Net Region Center |
| Net Sub-elements | Description | Value/Children |
|---|---|---|
| PropertyRequiredThe region flag carriers must enter to capture in this net. | Regions | |
| PropertyFilter players who can capture in this net. | Filters | |
| PropertyFilter when the flags captured in this net are allowed to respawn. | Filters |
Examples
Classic CTF
Capture the enemy's flag in your own net. You can't capture while the enemy is carrying your flag. Capturing the enemy's flag returns yours if it is dropped on the ground.
<score>
<limit>3</limit>
</score>
<flags>
<flag id="blue-flag" name="Blue Flag" owner="blue-team">
<post pickup-filter="red-only">2,5,11</post>
</flag>
<flag id="red-flag" name="Red Flag" owner="red-team">
<post pickup-filter="blue-only">24,5,11</post>
</flag>
<flags points="1">
<net region="red-net" flag="blue-flag" rescue="red-flag"/>
<net region="blue-net" flag="red-flag" rescue="blue-flag"/>
</flags>
</flags>
Flag Football
Capture a shared flag in the enemy's net. The flag respawns in the center after each capture. Flag carriers get a speed boost.
<score>
<limit>3</limit>
</score>
<flags>
<flag id="flag" name="Flag" color="white" shared="true">
<post id="center-post">
<cylinder base="13,1,11" radius="5" height="1"/>
</post>
<pickup-kit force="true">
<potion amplifier="2" duration="oo">speed</potion>
</pickup-kit>
<drop-kit force="true">
<potion duration="0">speed</potion>
</drop-kit>
<net points="1" region="red-net" capture-filter="blue-only"/>
<net points="1" region="blue-net" capture-filter="red-only"/>
</flag>
</flags>
King of the Flag
Capture a shared flag in your own net to bring it to your side, then keep it there as long as possible.
<score>
<limit>180</limit>
</score>
<flags>
<flag name="Flag" color="white" shared="true">
<post>13,1,11</post>
<net owner="yellow-team" region="yellow-net" post="yellow-post" capture-filter="yellow-only"/>
<net owner="blue-team" region="blue-net" post="blue-post" capture-filter="blue-only"/>
</flag>
<flags points-rate="1">
<post>
<post id="yellow-post"
owner="yellow-team"
yaw="90"
pickup-filter="blue-only">
24,5,11
</post>
<post id="blue-post"
owner="blue-team"
yaw="-90"
pickup-filter="yellow-only">
2,5,11
</post>
</post>
</flags>
</flags>
Flag Blitz
Earn points while carrying a shared flag. The flag respawns at a randomly chosen location after being dropped. Dead players cannot respawn while their team has the flag (but they can spectate).
<spawns>
<spawn team="red" region="red-spawn"/>
<spawn team="blue" region="blue-spawn"/>
<filter>
<not>
<same-team>
<carrying-flag>flag</carrying-flag>
</same-team>
</not>
</filter>
</spawns>
<respawn spectate="true">
<!-- "You will respawn when the flag is dropped..." -->
<message>{ translate: "death.respawn.confirmed.waiting.flagDropped" }</message>
</respawn>
<flags>
<!-- Uses one of three posts at random -->
<!-- First post defined must contain flag on match load -->
<!-- First post mentioned is automatcally fallback post -->
<post id="post" return-time="0s" respawn-time="7s">
<post name="Post 1">3.5,15,-45.5</post>
<post name="Post 2">3.5,20,-75.5</post>
<post name="Post 3">3.5,20,-15.5</post>
</post>
<flag id="flag" name="Flag" shared="true" post="post" points-rate="1"/>
</flags>
Complete the Flag
Capture each enemy flag (once) and place them on your flag monument.
<flags>
<flags owner="blue-team" pickup-filter="red-only">
<flag id="cyan-flag" name="Cyan Flag">
<post>2,5,10</post>
</flag>
<flag id="magenta-flag" name="Magenta Flag">
<post>2,5,12</post>
</flag>
</flags>
<flags owner="red-team" pickup-filter="blue-only">
<flag id="yellow-flag" name="Yellow Flag">
<post>24,5,10</post>
</flag>
<flag id="orange-flag" name="Orange Flag">
<post>24,5,12</post>
</flag>
</flags>
<net region="red-net"
flags="cyan-flag magenta-flag"
post="red-monument"/>
<net region="blue-net"
flags="orange-flag yellow-flag"
post="blue-monument"/>
<flags permanent="true" sequential="true">
<post id="blue-monument"
owner="blue-team"
yaw="-90">
<!-- room for two flags -->
<block>2, 1, 10</block>
<block>2, 1, 12</block>
</post>
<post id="red-monument"
owner="red-team"
yaw="90">
<!-- room for two flags -->
<block>24, 1, 10</block>
<block>24, 1, 12</block>
</post>
</flags>
</flags>
Other
A flag featuring three posts.
The flag will initially appear at center-post, but won't respawn on center-post
because of the filter. The flag will always cycle respawning between East and West.
<flag name="Flag" color="white" shared="true">
<post sequential="true" fallback="center-post">
<post id="center-post" name="Center" respawn-filter="never">x,y,z</post>
<post name="East">x,y,z</post>
<post name="West">x,y,z</post>
</post>
</flag>