In-game Map Entities

originally written by grayman

Create atdm:map_of entity

Create an "atdm:map_of" entity as if you intend to place it in the player's inventory at the start of the mission. Then turn off the "inv_map_start" spawnarg.

For example, create one with these spawnargs:

"name" "MapOfSewer"
"inv_map_start" "0"
"inv_name" "Sewer Map"
"gui" "guis/map_of_sewer.gui"

Create gui file

Create a gui file called "map_of_sewer.gui" with the following contents, and put it into your guis directory:

windowDef Desktop
{
       rect 0,0,640,480
       nocursor 1
 
       windowDef background_map
       {
               rect 64,48, 512, 384
               background "guis/assets/game_maps/map_of_sewer"
               visible 1
       }
}

Create image

Create the image you want displayed (your map) in "map_of_sewer.tga", with an alpha channel. (The alpha channel supports a map with a ragged edge. Unlike the method in Startpack_Mappers'_Guide#Adding_an_In-game_Map_to_your_FM, here, a custom .mtr or .def file is unneeded for such support.)

Put that image into guis/assets/game_maps/.

Retrieve a copy of guis/assets/game_maps/map_of_icon.tga from startmap.pk4 and place it into guis/assets/game_maps/.

Create atdm:static_custom_item entity

Create an "atdm:static_custom_item" entity with these spawnargs:

"name" "SewerMap"
"inv_map_start" "0"
"model" "models/darkmod/readables/scroll_rolled_up.lwo" (or use whatever model you prefer)
"sr_class_1" "R"
"sr_effect_1_1" "effect_script"
"sr_effect_1_1_arg1" "FrobSewerMap"
"sr_state_1" "1"
"sr_type_1" "STIM_FROB"

The "sr_*" spawnargs describe how your custom entity will react to a frob stim.

Adding the script

There are 2 types of script files. Map scripts and external scripts. Map scripts are used only in one map, while external scripts can be used in multiple maps. Map scripts always go in one script file which is stored inside the maps folder of your mission.
The filename must always be: mapname.script (the same name as your map file, but with a .script extension) . In this example we use a map script. See also the guide A to Z Scripting: Setting up the .script files.

Place the following code inside your mapname.script file:

void FrobSewerMap()
{
       // Put MapOfSewer into inventory, replacing the frobbed scroll named SewerMap.
       // MapOfSewer shows the sewer map when used while in inventory.
       // Make sure HUD shows the map icon.

       $player1.replaceInvItem($SewerMap,$MapOfSewer);
       $player1.setCurInvItem("Sewer Map"); // provide inventory name, not item name
}

void main() // this might already be there; skip if so
{
}

The names in the script with a $ next to them must match the name property of your entities, and the string in setCurInvItem must match the inv_name property of the atdm:map_of entity. $player1 is the player entity.

Result

When you play the mission, frobbing the custom item that looks like a scroll will cause the script to run, which replaces the custom item in your inventory with the "atdm:map_of" entity you created at the top of this note.

From here on, it's as if the game gave you the map at mission start. Hit your "use" key and your map should appear on the screen.