So, basically, this function simply returns a pointer to the first entity it find with a classname of "item_script". The line starts looking in the entity list from the "flag" variable's position, and since we set the "flag" variable to it's return variable, the while loop will cycle nicely through all the "item_script" entities in the map.

The next line is as follows:

    if (flag.flag_state == FLAG_BEING_CARRIED AND flag.carrier == other)

The next important bit is the (return FALSE) line. We return FALSE because we don't want to allow the player to pick up the Flag... it's his flag after all, and in ctf style modes, we don't allow player's to carry their flags.

Now, onto the last bit of the script, which handles what happens if a player _not_ on the Flag's team touches it... obviously, we want the player to pick up the flag, so we return TRUE, and let the TF2 code give the player the Flag.

GetItem Scripts

Now, we're starting to get into the trickiest part of mapC... item handling. Lets look at the Flag's "getitem" script:

    int entity::get_flag(entity other, int no_of_flags)
    {
        self.flag_state = FLAG_BEING_CARRIED;
        self.carrier = other;

        // Since we're not going to let the Code remove this item,
        // we need to hide it ourselves
        self.svflags |= SVF_NOCLIENT;
        self.solid = SOLID_NOT;

        // Return False to prevent the Code from removing the item 
        // now its been picked up
        return FALSE;
    }

Item Handling

For every player in the game, TF2 records a single number for every Item Type in the game, which represents the number of those Item Types the player has. For instance, if a player gets a weapon, the player's count for that weapon Type is incremented, and the actual weapon Entity itself is _removed_.
It'd be a terrible waste of memory to keep all the entities that player's are carrying around, when we can simply keep track of a number of them a player has.
So, way back when we declared a new Custom Entity definition, TF2 took note of the fact that we were deriving it from an "item_script". Whenever TF2 spots an "item_script" in a map, it creates a new Item Type based upon that item_script. If there are 20 of those item's in the map, it still only creates 1 Item Type.
Then, whenever a player gets one of those Item Entities, it simply increments the player's count of that Item Type, and nukes the Item Entity. And whenever a player drops one of those item's, it simply decrements the player's count of that Item Type, and then, and this is important, creates a new Item Entity Based Upon The Original Item Type.

So, after the Item Type is created, which occurs during the spawning of the "item_script", any changes to any Item Entities derived from this Item Type do not affect the Item Type. This is the fundamental thing to understand when it comes to handling items in TF2 mapC.

Now, this creates a problem for us in our ctf mapC... because we don't want the item (in this case, the Flag) destroyed and the player's count simply incremented... because we store information in that item. In the Flag's "postspawn" script, we store the Flag's initial origin. The Item Type is created during spawning, which means that initial origin, and the flag state for that matter, is _not_ stored inside the Item Type. Which means that if we allowed the Flag entity to be destroyed when the player picked it up, and then recreated when the player drops it, we'd lose that initial origin and flag state.

Item Pickup Summary

So, to make things simple for mapC coders, there's two scripts related to item pickups, and each has a distinct purpose.
The "activate" script is called before the pickup, and is designed to return TRUE if you want the TF2 code to handle the pickup and increment the player's count of this Item Type.
The "getitem" script is called after the pickup, and is designed to return TRUE if you want the TF2 code to destroy the Item Entity.

In this case, we're happy to let TF2 handle the pickup and the item count incrementing and all that crap... we just don't want it to remove the Flag entity afterwards.

So, we return TRUE in the Flag's "activate" script, and we return FALSE in the Flag's "getitem" script. But we don't want to just leave the flag there, so we need to do a bit more work... here's the code again:

    int entity::get_flag(entity other, int no_of_flags)
    {
        self.flag_state = FLAG_BEING_CARRIED;
        self.carrier = other;

        // Since we're not going to let the Code remove this item,
        // we need to hide it ourselves
        self.svflags |= SVF_NOCLIENT;
        self.solid = SOLID_NOT;

        // Return False to prevent the Code from removing the item 
        // now its been picked up
        return FALSE;
    }

The next two lines are more involved in the Quake2 dll code than we'd like to get into at this time, so I'll describe them only in what they do, not in how they do it.
The (self.svflags |= SVF_NOCLIENT) line sets a bit in the Flag's serverflags which prevents the game server from telling any clients that it exists... effectively making it invisible to everyone.
The (self.solid = SOLID_NOT) line makes the Flag non-solid, making it impossible for any entities to touch it.
So, these two lines effectively "remove" the Flag, but still leave the actual Flag's entity intact.

And then finally, we return FALSE, preventing the TF2 code from removing the Flag entity. And we're done with Flag pickups.

Flag Capturing

Now, lets backtrack just a bit, to the bit in the Flag's "activate" script where we capture flags being carried by the player... the code again:

        if (flag.flag_state == FLAG_BEING_CARRIED AND flag.carrier == other)
        {
            // Setup and Print Messages
            [snip]
            // Play Wav files
            [snip]

            remove_item(other, flag.name, 0);
            flag.origin = flag.init_origin;
            flag.svflags = flag.svflags - (flag.svflags & SVF_NOCLIENT);
            flag.solid = SOLID_TRIGGER;
            flag.flag_state = FLAG_HOME;
            flag.carrier = NULL;

            iscore += 1;
            set_scoreboard("my_board", iscore);
        }

The (flag.origin = flag.init_origin) sets the Flag's origin back to the initial origin that we saved in the "postspawn" script.
The (flag.svflags = flag.svflags - (flag.svflags & SVF_NOCLIENT)) line removes the bit we set in the Flag's serverflags, effectively making it visible again.
The (flag.solid = SOLID_TRIGGER) line makes the Flag solid again, ready to be touched by players. Then we update the Flag's status, and clear the Flag's carrier variable, since it's not being carried by anyone.

The following lines just update the scoreboard... they're not part of the CTF code. I just needed a way of incrementing the scoreboard while I was testing it. Capture the flag a few times and you'll see the scoreboard keep count of how many captures you've made.

DropItem Scripts

Now lets look at the last piece of the Flag puzzle... the "dropitem" script. An item's "dropitem" script can be called for a few reasons, so the second parameter passed to the "dropitems" script specifies the cause for the drop. The last parameter specifies the number of these Item Types the player has... more on this shortly.
Let's look at the first part:

    int entity::drop_flag(entity other, int flags, int no_of_flags)
    {
        entity flag;
        string fstr, estr, astr;

        if (flags & SF_DI_PLAYER_DROP OR flags & SF_DI_PLAYER_TRADE)
            return 0;               // Prevent Drop

    const int SF_DI_PLAYER_DEATH	=   1;
    const int SF_DI_PLAYER_DROP	    =   2;
    const int SF_DI_PLAYER_TRADE    =   4;

Now, unfortunately things are going to get tricky again here, because we're about to discover the other part of Item Handling... Item dropping. When the "getitems" script is called, the "self" variable is set to point to the Item Entity... the one the player has just picked up. When the "dropitems" script is called, the "self" variable is NOT set to point to an Item Entity... why? Because there may not be one. Remember... a player does not have a list of Item Entities he/she is carrying. All a player has is a count of the number of Item TYPES he/she is carrying.

So, when the "dropitems" script is called for an Item, it is called for an Item TYPE. Remember... when a map spawns, TF2 creates an Item Type for each new Custom Item Definition it finds in a map. This Item Type is a template that is never altered after it's initial creation.
So in the "dropitems" script the "self" variable is set to point at that Item Type... at that template. You can read information out of it as much as you like, but you cannot alter it.

Now, lets continue:

        // Play Wav files
        [snip]

        // We want to handle it ourselves
        remove_item(other, self.name, no_of_flags);

        // Cycle through all the flags, and find the correct flags
        while ((flag = find_ent(flag, entvar, "item_script")) != NULL)
        {
            if (flag.flag_state == FLAG_BEING_CARRIED AND flag.carrier == other)
            {
                throw_object(flag, other.origin);

                flag.solid = SOLID_TRIGGER;
                flag.flag_state = FLAG_AWAY;
                flag.carrier = NULL;

                // Setup and Print Messages
                [snip]
            }
        }

    throw_object(flag, other.origin);

        return 0;
    }

Now you might be wondering at this moment... why are we using the "dropitems" script of one Type of Flag to drop all the Flag's the player is carrying? Isn't that kind of illogical, not to mention stupid if the player has more than one flag, because this script will be called for each Flag Type?
Well... yes.

The correct way of handling this would be to define all the Flag's "dropitem" scripts as nothing but a simple function that returned 0 and do the actual dropping of the Items in the player's "script_die" script, which would be called whenever a player dies.

But, that'd be easy... and I wanted to try and push the difference between an Item Entity and an Item Type.

Item Handling Summary

While the whole Item Handling concept isn't simple, the implications for mapC coders are. Its important to keep in your head the difference between an Item Entity and an Item Type... do that, and you shouldn't have any trouble.

    - Player's carry numerical counts of Item Types.
    - Players pickup Item Entities, which increments their counts of the 
      corresponding Item Types, and destroys the Item Entities.
    - Players drop Item Types, which decrements their counts of those Item 
      Types, and creates new Item Entities based upon those Item Types.

Simpler Items

Now, you're probably thinking mapC looks fairly daunting. Not so... as I said, the ctf style flags are among the most complex uses of mapC there is, because they're items that you want to keep track of even when they're being carried. That's fairly rare... you'll usually be happy to let the TF2 code do the item handling.

Lets look at a far simpler item, and one that's more like the standard item's most mapmakers will want to add.
Here's the entity definition:

    entity_def 
    {
        "classname"         "item_comm_marker_team1"
        "spawnclass"        "item_script"
        "script_postspawn"  "comm_marker_postspawn"
        "script_activate"   "comm_marker_touched"
        "script_getitem"    "comm_marker_getitem"
        "script_dropitem"   "comm_marker_dropitem"
        "owned_by_team"     "1"
        "name"              "Blue Command Marker"
        "model"             "models/items/healing/medium/tris.md2"
        // Criteria
        "team_no"           "1"
    }

The Command Marker's scripts are very simple. No spawn script, and a postspawn script as follows:

    int entity::comm_marker_postspawn(int flags)
    {
        droptofloor(self);
        return TRUE;
    }

The "activate" script called when a player tries to pick up a Command Marker is as follows:

    int entity::comm_marker_touched(entity other, int flags)
    {
        // Only allow them to carry 1 at a time
        if (get_num_items(other, self.name) == 0)
            return TRUE;    

        return FALSE;
    }

The "getitem" script for the Command Marker's is also simple:

    int entity::comm_marker_getitem(entity other, int no_of_flags)
    {
        return FALSE;
    }

The "dropitem" script is just as simple:

    int entity::comm_marker_dropitem(entity other, int flags, int no_of_flags)
    {
        return 0;   // Lost when player dies
    }

And that's it. In their "activate" scripts, the Command Points check to see if player's have any Command Markers, and if so, allow the player to capture that Command Point. Command Markers themselves provide player's with no other capabilities.
So, lets look at an item that does.

Command Items

Command Items are a special type of item that adds a command to any player carrying it. The ctf mapC uses a Command Item for the "flaginfo" command, so we'll look at that. Here's it's entity definition:

    entity_def
    {
        "classname"         "item_flaginfo"  
        "spawnclass"        "item_script"
        "script_spawn"      "spawn_flaginfo"
        "command_func"      "flaginfo_command"
        "command_str"       "flaginfo"
        "name"              "flaginfo"
        "item_flags"        "96"         // IT_NOT_VISIBLE | IT_RESPAWN_KEEP
    }

    int entity::spawn_flaginfo(int flags)
    {
        return FALSE;
    }

Now, lets look at the interesting parts of the Flaginfo Entity Definition:

        "command_func"      "flaginfo_command"
        "command_str"       "flaginfo"

    void flaginfo_command(entity ent)
    {
        entity flag;

        // Cycle through all the flags, and dump the status of each
        while ((flag = find_ent(flag, entvar, "item_script")) != NULL)
        {
            if (flag.flag_state == FLAG_HOME)
            {
                cprint(ent, flag.name);
                cprint(ent, " is in its base.\n");
            }
            else if (flag.flag_state == FLAG_AWAY)
            {
                cprint(ent, flag.name);
                cprint(ent, " is lying around somewhere.\n");
            }
            else if (flag.flag_state == FLAG_BEING_CARRIED)
            {
                cprint(ent, flag.name);
                cprint(ent, " is being carried by ");
                cprint(ent, flag.carrier.name);
                cprint(ent, "\n");
            }
        }
    }

There's only one catch... the player must have one or more of the Command Items. So how does a player get the Flaginfo item, since the spawn function automatically removes it from the map?
Easy... through the use of a Global Script.

Global Scripts

Global Scripts are scripts that aren't attached to a specific entity... they're generally event based. An event occurs which has an attached Global Script, and if the Global Script exists in the mapC file, it's called.

The first Global script we'll look at is PlayerConnect. As it's name suggests, it's called whenever a Player connects to the server. Here's mc2's PlayerConnect script:

    int entity::script_PlayerConnect(int flags)
    {
        add_item(self, "flaginfo", 1);
    	return TRUE; // yes, the player is allowed to join the game
    }

There are currently only two other Global Scripts: Worldspawn, called at the initial spawning of the map, and Precaches, called when the server begins to precache sounds and models. We will be adding more... for when Player's disconnect, join teams, leave teams, etc. Like Interface Functions, we'd like to hear your requests for Global Scripts.

Think Functions

And last but not least, lets look at Think functions. The Command Point System uses a Think function to check the status of every Command Point in the map.
Every entity can have a think function and a nextthink time. The TF2 engine will automatically call that think function when the time is reached. Lets look at the WorldSpawn Global Script:

    int entity::script_Worldspawn(int flags)
    {
        entity ent;

        number_of_teams = 2;
        team_set_name(1, "Blue");
        team_set_name(2, "Red");

        // Command Point Scoring Entity
        ent = create_entity();
        ent.think = comm_scorer_think;
        ent.nextthink = time + 300;    // 30 Seconds

    	return TRUE;
    }

The (ent = create_entity()) line creates a new entity and sets the "ent" variable to point at it. The next two lines set that entity's think and nextthink. We set the think to "comm_scorer_think" and the nextthink to time + 300. What this means is that the TF2 code will automatically call the "comm_scorer_think" script 30 seconds from now.
You might want to take a look at the "comm_scorer_think" script.

Other MC2 Code of Interest

We'll let you look over the mc2 mapC and mess with what's there. Take a look at the scoreboard... it's an example of a more complex interaction between mapC and brushes inside a map.

You might notice the use of the "entlist" variable in some places, such as the "print_team_updates" script. An "entlist" is an Entity List. Entities can be added and removed from lists simply and effectively, and any operation applied to a list is applied individually to all entities in the list. Handy for messaging everyone on a team, or providing bonuses to a subset of players.
More complex uses of them will come later.

Also, check out the entity definitions for the spawnpoints. Players attempting to spawn on a spawnpoint have their criteria checked just like everything else... a spawnpoint's "activate" script can check any of the player's details, and return TRUE if the player is allowed to spawn on it.

Results

So what have we got here?
We've got a chunk of mapC code that, among other things, will handle any CTF map, with any number of Flags per team, with upto 32 teams. And all the mapmaker has to do is set the worldspawn's "scriptfile" key to "ctf", and put the Flag and Spawnpoint entities around the map.

Robin. [email protected]

[Front][News][Download][TF Info][TF Clans][Links][Contact][Maps][Classes][Supporters]