Modules

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
<flags> </flags> Node containing a group of flags, nets and posts for this match.
Sub-elements Value/Children
<flag> A single physical flag (banner) in the map. Flag Sub-elements
<post>X,Y,Z</post> A point or region(s) for flags to spawn at. Point Provider
<net> 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
<flag> A single physical flag (banner) in the map. Flag Sub-elements
Flag Attributes Description Value Default
id Unique identifier used to reference this flag from other places in the XML. String
required 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 true
name Label that appears over the flag and on the scoreboard. String
color Color of the flag, used for the label, particles, etc.
If omitted, the base color of the banner is used.
Dye Color Name
show Show this flag on the scoreboard, chat, etc. true/false true
post Property Required The flag's initial & default post. Flag Post
owner 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
shared 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
carry-message 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
points The amount of points awarded for capturing this flag.
If the flag has an owner, 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
points-rate The amount of points awarded per second while this flag is being carried.
If the flag has an owner, 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
pickup-filter Property Filter who can pickup the flag. Filter
drop-filter Property Filter if the flag can be dropped at the current location. Filter
capture-filter Property Filter who can capture the flag. Filter
pickup-kit Property Given to players when they pick up the flag. Kit
drop-kit Property Given to flag carriers when they lose the flag, for whatever reason. Kit
carry-kit Property Given 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
drop-on-water Allow this flag to be dropped on water, freezing the block under it into ice. true/false true
beam Show a particle beam for this flag. true/false true
flag-proximity-metric Metric used to determine proximity to the flag.
Accepts closest player, closest block or closest kill
Proximity Metric closest kill
flag-proximity-horizontal Only calculate horizontal distance for flag proximity. true/false false
net-proximity-metric Metric used to determine proximity to the net.
Accepts closest player, closest block or closest kill
Proximity Metric closest player
net-proximity-horizontal Only calculate horizontal distance for net proximity. true/false false
Flag Sub-elements Description Type
<net> A net where only this flag can be captured, flags accept multiple net sub-elements.
<post>X,Y,Z</post> Property Required The flag's initial & default post. Point Provider
<pickup-filter> Property Filter who can pickup the flag. Filters
<drop-filter> Property Filter if the flag can be dropped at the current location. Filters
<capture-filter> Property Filter who can capture the flag. Filters
<pickup-kit> Property Given to players when they pick up the flag. Kit
<drop-kit> Property Given 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.

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
<post>X,Y,Z</post> A point or region(s) for flags to spawn at. Point Provider
Post Attributes Description Value Default
id Unique identifier used to reference this post from other places in the XML. String
owner The team that owns this post. Team ID
permanent 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 owner of the post, which is required in this case.
true/false false
sequential 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-rate Points awarded per second to this post's owner while any flag is at the post.
Requires the owner attribute to be set.
Number 0
pickup-filter Property Filter who can pickup a flag from this post. Filter
recover-time Time that a flag stays on the ground after being dropped. Use oo to let the flag stay on the ground forever. Time Period 30s
respawn-time 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
respawn-speed Speed that a flag "moves" to respawn at this post, after being captured/recovered.
This is an alternative to respawn-time that calculates the time based on the distance the flag must travel.
M/s 8
yaw The direction a banner faces after it is returned to this post. -180 to 180
Post Sub-elements Description Value/Children
<pickup-filter> Property Filter 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
<net> A region that flags can be captured in. Net Sub-elements.
Net Attributes Description Value Default
id Unique identifier used to reference this net from other places in the XML. String
region Property Required The region flag carriers must enter to capture in this net. Region
owner The team that owns this net. Team ID
points The amount of points awarded for capturing a flag in this net.
If the net has an owner, 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
post The ID of the post a flag returns to after being captured in this net. Flag Post
flag | flags 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
rescue 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
sticky 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 rescue or capture-filter) 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
capture-filter Property Filter players who can capture in this net. Filter
deny-message 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 capture-filter to a confused player.
String
respawn-together All the flags listed in flags must be captured before any of them respawn. true/false false
respawn-filter Property Filter when the flags captured in this net are allowed to respawn. Filter
respawn-message 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 respawn-filter to confused players.
String
location Location where the net can be found at, used to determine proximity. X,Y,Z Net Region Center
Net Sub-elements Description Value/Children
<region> Property Required The region flag carriers must enter to capture in this net. Regions
<capture-filter> Property Filter players who can capture in this net. Filters
<respawn-filter> Property Filter 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 id="red-post"
              owner="red-team"
              yaw="90"
              pickup-filter="blue-only">
            24,5,11
        </post>
        <post id="blue-post"
              owner="blue-team"
              yaw="-90"
              pickup-filter="red-only">
            2,5,11
        </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>
    <post id="post" return-time="0s" respawn-time="7s">
        <block> 3.5,15,-445.5 </block>
        <block> 3.5,20,-475.5 </block>
        <block> 3.5,20,-415.5 </block>
    </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>