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

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.

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.

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.

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>