MapAdd Documentation [u4.1]

[TABLESPOON DEV COMMITTEE]

MapAdd Documentation; Current Version - u4.1

Table of Contents
I ..... What is a MapAdd?
II .... File Creation
III ... The Bare Essentials
IV .... Basic Entity Format
V ..... MapAdd Specific Entities


What is a MapAdd?

By using a simple text file we can completely transform any map by adding/removing/modifying enemies, weapons, events, companions, and so much more. It can be as simple as adding in more ammo or as complex as making combine rappel from helicopters! With the MapAdd system we can literally change the entire gameplay of a map, without ever editing the map itself! This was one of the key features of SMOD, and now it has found its way into TBSP (MapAdd system based off of SirMasters' excellent code. Thank you).

So, how similar is the new MapAdd structure compared to SMOD's system?? Well its pretty damn close (now), but not exact. It may be worth while to check out some of the excellent and very thorough documentation of the old SMOD mapadd system, both on BSNOOCH.COM and the Unofficial SMOD Wiki before we get started.

[TABLESPOON DEV COMMITTEE]

File Creation

Creating a MapAdd file is as easy as creating a new blank text file. That's it. Seriously. However, to get the thing working in-game, there are a few more steps that need to be completed:

1.) The MapAdd file needs to have the exact same name as the map you want it to be used for. As a quick example, if you wanted to make a MapAdd for the first map (ep2_outland_01) of HL2: Episode 2 you would need to name your MapAdd file ep2_outland_01 so that it exactly matches the map name.

* You can find out which map you are on in-game by typing cl_showfps 1 into the developer console. It should appear in the top right corner of the game.
* You do not need to include the extension of the map in the MapAdd name! For example: Your Map's FileName = cs_dust2.bsp; Your MapAdd's FileName = cs_dust2.txt   (NOT cs_dust2.bsp.txt !!)

2.) Your MapAdd file needs to be in this directory: .../sourcemods/tbsp/mapadd/

* Look for a file named "_MAPADD FILES GO HERE!!.txt"

[TABLESPOON DEV COMMITTEE]

The Bare Essentials

Now it's time to open up our MapAdd file and give it the bare necessities to make it run. Lets begin with the MapAdd block, which runs the whole system.  It's code is represented below:

Code: [Select]

"MapAdd" {

}
This should be the FIRST block you put into your MapAdd file. Blocks are sort of like storage areas where we can put data and also access it. All blocks will start with an open curly brace " { ", and end with a closing curly brace "}". Anything put between these two braces is considered in the block. All the data we are going to add to, change, and remove in our map via MapAdd will go in the "MapAdd" block.

* You should only ever have one "MapAdd" block per map (or file).

Next up we need to add a MapInitialize ("Init") block. This block is special, because anything stored inside it will be processed and spawned when the map loads. It is necessary to have this block in your MapAdd file, so that you can inject in your entities and code into the map. The MapInitialize section is represented like this:

Code: [Select]

"Init" {

}
     * Remember that the "Init" block needs to go inside of the "MapAdd" block.

[TABLESPOON DEV COMMITTEE]

Basic Entity Format

So now we have our barebones MapAdd file ready to be filled in. It should look something like this:

Code: [Select]

"MapAdd" {

"Init" {

}
}
Now lets add a standard HL2 entity to our map via MapAdd. Here is the standard format for all entities so that they can be processed by the MapAdd system:

Code: [Select]

"ClassName" {
"Origin" "x y z"
"Angle" "p y r"
"KeyValues" {
"Key" "Value"
"Key" "Value"
"Output" "Target,Input,Parameter,Delay,FireOnce"
"Output" "Target,Input,Value,Parameter,FireOnce"
}
}
Lets break this down line by line:

"ClassName" - This block defines what type of entity we are using. There is a big list of entities here. Change the ClassName to match whatever entity you want to spawn there.
* Example: If we wanted a combine soldier we would use "npc_comine_s".

"Origin" - This value tells the game where on the map this entity should spawn at.

"Angle" - Tells the game what direction the entity should be facing (Pitch Yaw Roll).

"KeyValues" - This block will store information that helps us fine-tune this entity for a specific task. These bits of information are called keyvalues, because they consist of a key, and a value (imagine that).

"Key" - This is a bit of information that helps define our entity. Anything from its name, to whether it should start disabled, or even what kind of weapon it uses. For every key there is value on the same line. You can have as many or as few keyvalues defined as you like.

"Output" - Inputs/Outputs (I/O) are the way that entities communicate with each other in maps. For more information on the I/O system see this article. Outputs and Inputs go within the "KeyValues" block of the entity. Like keyvalues, you can have as few or as many Outputs as you need (or even none).

Now that we have our basic entity format broken down and covered, lets look at an example of how a MapAdd might be used to spawn a Combine Soldier.

Code: [Select]

"MapAdd" {

"Init" {

"npc_combine_s" {
"origin" "212.5 -36.0 7.2"
"angle" "0 -90 0"
"keyvalues" {
"targetname" "soldier_01"
"additionalequipment" "weapon_smg1"
}
}
}
}
* Almost any standard HL2 entity can be spawned via MapAdd!

[TABLESPOON DEV COMMITTEE]

MapAdd Specific Entities

Now lets cover some special entities that have been made specifically for the MapAdd system. These entities are what give the system its impressive power.

Simple Trigger
A trigger similar to the brush based trigger_once available in the Hammer Map Editor, or the instant_trig entity available in SMOD. It essentially defines a radius from its origin, and activates when the player steps into that radius.

Here is how it looks in MapAdd code:

Code: [Select]

"mapadd_trig" {
"Origin" "x y z"
"KeyValues" {
"Radius" "50"
"OnTrigger" "Target,Input,Parameter,Delay,FireOnce"
}
}
Special KeyValues:
"Radius" - This is the radius of the trigger, measured in game units. It is projected out from the origin point of the trigger entity.

"OnTrigger" - This is an output similar to the brush-based triggers available in the Hammer Map Editor. It is only processed when the player sets off the trigger (enters its radius).


Target Trigger
This is a type of trigger which functions almost identically to the Simple Trigger, except that it has additional KeyValues which allows you to filter the type/name of the entity that can trigger it.

Here is how it looks in MapAdd code:

Code: [Select]

"mapadd_target_trig" {
"Origin" "x y z"
"KeyValues" {
"Radius" "50"
"TriggerTarget" "name"
"OnTrigger" "Target,Input,Parameter,Delay,FireOnce"
}
}
Special KeyValues:
"TriggerTarget" - This is the parameter that filters what entity can set off the trigger. Use a name here.


Remove Entity
This is a special MapAdd function which removes an entity from the map.

Here is how it looks in MapAdd code:

Code: [Select]

"removeentity" {
"classname" "name"
"targetname" "name"
"origin" "x y z"
"radius" "##"
}
Special KeyValues:
"classname" - This defines the class of entity we want to remove. This takes top priority.

"targetname" - This defines the name of the entity we wish to remove.

"origin" - Set an origin point to search for our entity from.

"radius" - Define how far from our origin point to search from.


Replace Entity
An interesting MapAdd function that will replace one entity type with another. You can also define KeyValues for your newly replaced entity!

Here is how it looks in MapAdd code:

Code: [Select]

"replaceentity" {
"classname" "name"
"newclassname" "name"
"KeyValues" {
"Key" "Value"
"Output" "Target,Input,Parameter,Delay,FireOnce"
}
}
Special KeyValues:
"classname" - This defines the entity class we want to replace!

"newclassname" - And this defines the type of entity that we will be inserting in it's place!

"KeyValues" {} - In this section you can define KeyValues and Outputs that will be inherited by our newly replaced entities.


Modify Entity
A powerful MapAdd function that operates similar to an "AddOutput" output. Basically, it will search for an entity already in the map, and allow you to change or add KeyValues on the fly.

Here is how it looks in MapAdd code:

Code: [Select]

"modifyentity" {
"Origin" "x y z"
"classname" "class"
"KeyValues" {
"Key" "Value"
"Output" "Target,Input,Parameter,Delay,FireOnce"
}
}
Special KeyValues:
"Origin" - Select an point where the entity you wish to modify is. If no entity is found here (that matches the classname) then it will search for the closest match from this point.

"Classname" - Define the entity class that you wish to modify.

"KeyValues" {} - This is the block where we place the KeyValues we wish to modify for this entity, and outputs we wish to add. This will override an entity's current KeyValue, or add the KeyValue/Output if none exists.


Custom Ammo Item
This entity creates a Custom Ammo Item which the player can pickup. It's mainly used to give the player an additional stock of a desired type of custom ammo.

Here is how it looks in MapAdd code:

Code: [Select]

"item_custom_ammo" {
"origin" "x y z"
"angle" "p y r"
"KeyValues" {
"AmmoType" "YourAmmoType"
"EntityName" "YourAmmoPickup"
}
}
Special KeyValues:
"AmmoType" - Selects a user-defined type for this item and loads values for that class. Custom types can be defined in .../tbsp/scripts/custom_ammo.txt; Please refer to Scripting Documentation for more info.

EntityName - This defines what type of item pickup we will use for this custom ammo type. It is defined in the custom ammo script. Please refer to Scripting Documentation for more info.


Custom Soldier NPC
This entity spawns a custom soldier in the map. Custom Soldiers will take all normal KeyValues as well as special unique ones described below.

Here is how it looks in MapAdd code:

Code: [Select]

"npc_custom_soldier" {
"Origin" "x y z"
"Angle" "p y r"
"KeyValues" {
"sclass" "name"
"key" "value"
}
}
Special KeyValues:
"sclass" - Selects a user-defined type for this Custom Soldier and loads values from that class. Custom types can be defined in .../tbsp/scripts/npc_custom_soldier.txt; Please refer to Scripting Documentation for more info.

[TABLESPOON DEV COMMITTEE]

Reserved for future Updates...

[TABLESPOON DEV COMMITTEE]

Reserved for Future Updates...

[Bitl]

I'll guess i'll have to repost this..

Please note that this format is also inter-compatible with FIREFIGHT RELOADED's mapadd system (with some modifications) since both of these mods use SMMOD's format.

[BIZ]

I'll guess i'll have to repost this..

Please note that this format is also inter-compatible with FIREFIGHT RELOADED's mapadd system (with some modifications) since both of these mods use SMMOD's format.

You can copy the relevant info to your forum if you like.
I did this write up for SMMOD, but never got around to posting it.
I updated it for the newer features and passed it along to DevCom for sharing