CTF caplimit
[divverent/nexuiz.git] / Docs / mapping.txt
1 ==============\r
2 =Mapping Help=\r
3 ==============\r
4 \r
5 While I can't help you make a map, I can help you get it listed in the menu and\r
6 working in the maplist. :p  The central object is the .mapinfo file, but\r
7 there's much more available.\r
8 \r
9 Table of Contents\r
10 -----------------\r
11 I        Map Lists & Scripts\r
12          (get your map listed and working)\r
13   i.     mapinfo\r
14   ii.    mapname.cfg\r
15 \r
16 II       Map Image\r
17 \r
18 III      Domination\r
19 \r
20 IV       CTF\r
21 \r
22 V        Rune Match\r
23 \r
24 VI       Assault\r
25 \r
26 VII      Onslaught\r
27 \r
28 Appendix A - Advanced mapinfo\r
29 \r
30 Appendix B - Helpful extras\r
31   i.     Team Colors\r
32   ii.    Text Colors\r
33
34 Appendix C - Advanced Darkplaces shaders\r
35 \r
36 ========================\r
37 =I. Map Lists & Scripts=\r
38 ========================\r
39 \r
40 There are actually 2 script/cfg options available to you, each serving a\r
41 different purpose and being executed at a different time during the map's life\r
42 cycle:\r
43 \r
44 1. mapname.mapinfo\r
45 2. mapname.cfg\r
46 \r
47 Of these, the mapinfo is the only one that's truely required - and the game is\r
48 even so nice that it automatically generates a draft of it for you.\r
49 \r
50 ------------------\r
51 -The mapinfo file-\r
52 ------------------\r
53 \r
54 *cue even more scary music*\r
55 \r
56 The mapinfo file is basically what gets your map listed in the menu, and sets\r
57 up the options needed to change to it. If no mapinfo file exists, the menu\r
58 will automatically generate a rough draft for you on game startup. It will get\r
59 stored into data/data/mapname.mapinfo.\r
60 \r
61 As an example, let's say I make a map called "wazat1.bsp". As long as I'm\r
62 fantasizing, I might as well say this map is so well done I'm actually willing\r
63 to release it for friends, neighbors, fellow forum visitors and other people\r
64 who like me to judge me by. Let's also assume that I want domination,\r
65 deathmatch/team deathmatch and runematch to all be playable on my map.\r
66 \r
67 This is very easy. First, I start the game and exit it again so the game writes\r
68 data/data/wazat1.mapinfo for me. The file may look like:\r
69 \r
70     title Wazat's Great Map\r
71     description Bleh.\r
72     author Unknown\r
73     _diameter 1966.839355\r
74     _spawnpoints 5\r
75     has weapons\r
76     type dm 30 20\r
77     type dom 200 20\r
78     type rune 200 20\r
79     type lms 9 20\r
80     type arena 10 20\r
81 \r
82 As I see, the menu autodetected that my map may be suitable for deathmatch,\r
83 domination, runematch, last man standing and arena. But I want the map to be\r
84 played in domination, deathmatch, team deathmatch, runematch only, and I also\r
85 want different timelimits/fraglimits, so I will change the "type" lines to:\r
86 \r
87     type dom 100 15\r
88     type rune 1000 25\r
89     type dm 40 15\r
90     type tdm 50 0 2\r
91 \r
92 Also, while I am at it, I should fix the placeholders in the map description lines:\r
93 \r
94     title Wibble\r
95     description A large multi level arena map\r
96     author Wazat\r
97 \r
98 Although not entirely necessary, I will now move the .mapinfo file from\r
99 data/data/maps/wazat1.mapinfo to data/maps/wazat1.mapinfo, so it is at the same\r
100 place as my map. Next time I start the game, my map will be shown supporting\r
101 the right game modes and with the right description in the menu.\r
102 \r
103 Also, note the "has weapons" line. If this line is not there (which happens if\r
104 the map contains no weapon entities other than the Nex), the map will run in\r
105 MinstaGib only and not be shown in the menu normally. So if you look for your\r
106 map and don't find it, add "has weapons" to the mapinfo file, and make sure you\r
107 have weapon entities placed.\r
108 \r
109 There's much more power in a mapinfo file. See Appendix A for more details.\r
110 \r
111 By the way: the Domination and Keyhunt types allow a third number to specify\r
112 the number of teams; the CTF type allows a third number to specify a capture\r
113 limit (if g_ctf_win_mode is 0 or 1).\r
114 \r
115 \r
116 -------------\r
117 -mapname.cfg-\r
118 -------------\r
119 \r
120 Unlike the mapinfo, which is processed by the server, the mapname.cfg file is\r
121 processed by the client, and therefore is used for client settings like fog or\r
122 the music to play.\r
123 \r
124 To make the mapname.cfg, make a file with the same name as your map's .bsp\r
125 file, except with a .cfg extension instead of .bsp. For example, my\r
126 "wazat1.bsp" map would use "wazat1.cfg". It uses the same name as your map,\r
127 thus the term mapname.cfg. It will typically only contain a single line:\r
128 \r
129     cd loop 6\r
130 \r
131 where 6 is the number or name of a track in sound/cdtracks/\r
132 \r
133 \r
134 ===============\r
135 =II. Map Image=\r
136 ===============\r
137 \r
138 So, you've got your map listed in the menu and it plays properly, but the menu\r
139 isn't showing your picture! Or the picture is scaled badly! What manner of man\r
140 would create such an accursed abomination?!\r
141 \r
142 Well... That sounds like something I'd do. :D\r
143 \r
144 And it is really easy: just make a screenshot of the map in action (preferably\r
145 with crosshair and HUD switched off), and place it next to the map as\r
146 mapname.jpg. For best rendering and file size, make the image in 4:3 aspect\r
147 ratio, but scale it to the resolution 256x256 or possibly 512x512. It will look\r
148 skewed in your image editing app, but the menu will show it right, and your\r
149 graphics card LOVES images of such dimension.\r
150 \r
151 \r
152 =================\r
153 =III. Domination=\r
154 =================\r
155 \r
156 In order to get Domination working well in your map, you need to place dom_team\r
157 and dom_controlpoint entites. You *must* have at least 3 dom_team entities - 2\r
158 minimum teams and one blank one (empty netname and no team). You can have up\r
159 to 4 teams (5 dom_team entities).\r
160 \r
161 Dom Team\r
162 --------\r
163 classname  dom_team\r
164 netname    name of team (Red Team). Set to "" or don't define for the required\r
165            blank team.\r
166 cnt        color of the team. See the "Helpful Extras" section for info.\r
167 model      When this team captures control points, the points turn to this\r
168            model. If this is the neutral team, points start out as this model.\r
169 noise      Sound to be played on the control point when it's captured. Only\r
170            players nearby will hear it.\r
171 noise1     Sound to be played to all players when the control point is\r
172            captured. Also good for an annoncer voice ("Red Team has captured a\r
173            control point")\r
174 \r
175 Control Points\r
176 --------------\r
177 classname  dom_controlpoint\r
178 message    message to be displayed to all players when this point is captured,\r
179            preceded by the team's name. This defaults to " has captured a control point".\r
180            You can specify different names for each point, for example " has captured the\r
181            Lava Room".\r
182 origin     where in the map this point is\r
183 wait       How often this point gives its controlling team frags.\r
184 frags      How many frags this point gives each wait cycle.\r
185 \r
186 Here is an example entry in a .ent file that includes colored text and 3 teams:\r
187 \r
188 {\r
189 "classname" "dom_team"\r
190 "netname" ""\r
191 "model" "models/domination/dom_unclaimed.md3"\r
192 }\r
193 {\r
194 "classname" "dom_team"\r
195 "netname" "^4Blue Team"\r
196 "cnt" "13"\r
197 "noise" ""\r
198 "noise1" "domination/claim.wav"\r
199 "model" "models/domination/dom_blue.md3"\r
200 }\r
201 {\r
202 "classname" "dom_team"\r
203 "netname" "^1Red Team"\r
204 "cnt" "4"\r
205 "noise" ""\r
206 "noise1" "domination/claim.wav"\r
207 "model" "models/domination/dom_red.md3"\r
208 }\r
209 {\r
210 "classname" "dom_team"\r
211 "netname" "^6Pink Team"\r
212 "cnt" "9"\r
213 "noise" ""\r
214 "noise1" "domination/claim.wav"\r
215 "model" "models/domination/dom_pink.md3"\r
216 }\r
217 {\r
218 "classname" "dom_team"\r
219 "netname" "^3Yellow Team"\r
220 "cnt" "12"\r
221 "noise" ""\r
222 "noise1" "domination/claim.wav"\r
223 "model" "models/domination/dom_yellow.md3"\r
224 }\r
225 {\r
226 "classname" "dom_controlpoint"\r
227 "message" " ^3has captured the ^1Hallways"\r
228 "origin" "-206.0 -488.8 -150.0"\r
229 "frags" "3"\r
230 "wait" "5"\r
231 "scale" "1.3"\r
232 }\r
233 {\r
234 "classname" "dom_controlpoint"\r
235 "message" " ^3has captured the ^1Lavaroom"\r
236 "origin" "1457.1  19.9 -110.0"\r
237 "frags" "1"\r
238 "wait" "5"\r
239 }\r
240 {\r
241 "classname" "dom_controlpoint"\r
242 "message" " ^3controls the ^1Nex & Strength"\r
243 "origin" "-259.8 299.3  5"\r
244 "frags" "1"\r
245 "wait" "5"\r
246 }\r
247 {\r
248 "classname" "dom_controlpoint"\r
249 "message" " ^3has captured the ^1Upper Platform"\r
250 "origin" "539.7 1206.0 182.0"\r
251 "frags" "1"\r
252 "wait" "5"\r
253 }\r
254 {\r
255 "classname" "dom_controlpoint"\r
256 "message" " ^3has captured the ^1Teleport Room"\r
257 "origin" "-1000.0 636.2 -16.0"\r
258 "frags" "1"\r
259 "wait" "5"\r
260 }\r
261 \r
262 \r
263 As you can see in the example, there are 5 dom_team ents: one blank, Red, Blue,\r
264 Pink and Yellow. Each control point has a different message (giving it a\r
265 special name), and the one in the hallways gives 3 frags every 5 seconds\r
266 instead of just one, making it more valuable.\r
267 \r
268 If your map contains the required entities for Domination, the menu will\r
269 automatically detect it for supporting Domination. To force the map to get\r
270 re-detected after you add such entities, delete the data/data/mapname.mapinfo\r
271 file - or simply edit it to add the "type dom" line.\r
272 \r
273 \r
274 ==========\r
275 =III. CTF=\r
276 ==========\r
277 \r
278 Capture the flag needs at least 1 CTF flag per team, and can also make use of\r
279 team spawnpoints.\r
280 \r
281 CTF Flags\r
282 ---------\r
283 classname  item_flag_team1 or item_flag_team2\r
284 angle      direction the flag will point\r
285 model      model of the flag (default: models/ctf/flag_red.md3 or\r
286            models/ctf/flag_blue.md3)\r
287 noise      sound played when flag is stolen (default: "ctf/take.wav")\r
288 noise1     sound played when flag is returned by a teammate (default:\r
289            "ctf/return.wav")\r
290 noise2     sound played when flag is captured (default: "ctf/capture.wav")\r
291 noise3     sound played when flag returns itself (default: "ctf/respawn.wav")\r
292 \r
293 Team Spawnpoints\r
294 ----------------\r
295 classname  info_player_team1 or info_player_team2\r
296 *note: These function just like info_player_deathmatch, but for one team only.\r
297 If you don't make team spawnpoints, info_player_deathmatch is used instead.\r
298 \r
299 If your map contains the required entities for CTF, the menu will automatically\r
300 detect it for supporting CTF. To force the map to get re-detected after you add\r
301 such entities, delete the data/data/mapname.mapinfo file - or simply edit it to\r
302 add the "type ctf" line.\r
303 \r
304 ================\r
305 =III. Runematch=\r
306 ================\r
307 \r
308 Runematch needs only one type of entity to work: rune spawn points. You will\r
309 need at least one for each rune (5 minimum at the time of this writing), though\r
310 you should probably have more than that in the map. Just give the points a\r
311 classname and origin.\r
312 \r
313 Rune Spawnpoints\r
314 ----------------\r
315 classname  runematch_spawn_point\r
316 \r
317 If your map contains the required entities for Runematch, the menu will automatically\r
318 detect it for supporting Runematch. To force the map to get re-detected after you add\r
319 such entities, delete the data/data/mapname.mapinfo file - or simply edit it to\r
320 add the "type rune" line.\r
321 \r
322 \r
323 ===============================\r
324 =Appendix A - Advanced mapinfo=\r
325 ===============================\r
326 \r
327 You now know how to make a basic, bare-bones mapinfo to set up a couple options\r
328 and load your map. However, there's much more you can do!  Consider these\r
329 senarios:\r
330 \r
331 1. The laser has too high of a force for laser jumps and ruins CTF\r
332 2. I don't want players to start out with the shotgun, but with the machinegun\r
333    instead\r
334 3. The map takes so much server CPU performance that the anti-wallhack can't be\r
335    made active\r
336 \r
337 Each of these situations can be resolved with ease with a little work in the\r
338 mapinfo file.\r
339 \r
340 To do this, I can add the following lines to my mapinfo file:\r
341 \r
342     settemp_for_type ctf g_balance_laser_primary_force 200\r
343     settemp_for_type all g_start_weapon_shotgun 0\r
344     settemp_for_type all g_start_weapon_uzi 1\r
345     settemp_for_type all sv_cullentities_trace 0\r
346 \r
347 These "settemp" settings are automatically removed when the map is left and\r
348 another is loaded. As you can see, it is possible to make per-mode temporary\r
349 settings, and global ones.\r
350 \r
351 \r
352 =============================\r
353 =Appendix B - Helpful Extras=\r
354 =============================\r
355 \r
356 ----------------\r
357 -i. Team Colors-\r
358 ----------------\r
359 When you need to set an entity's color or team, use these values:\r
360 \r
361 Red\r
362 ---\r
363 Team:      5\r
364 Color:     4\r
365 \r
366 Blue\r
367 ----\r
368 Team:      14\r
369 Color:     13\r
370 \r
371 Yellow\r
372 ------\r
373 Team:      13\r
374 Color:     12\r
375 \r
376 Pink\r
377 -----\r
378 Team:      10\r
379 Color:     9\r
380 \r
381 \r
382 ----------------\r
383 -i. Text Colors-\r
384 ----------------\r
385 Occasionally you may want to print text in color, such as team names. Here are your options:\r
386 \r
387 1  Red\r
388 2  Green\r
389 3  Yellow\r
390 4  Blue\r
391 5  Cyan\r
392 6  Magenta\r
393 7  White\r
394 8  Grey (transparent)\r
395 9  Grey (solid)\r
396 0  Black\r
397
398 ==========================================\r
399 =Appendix C - Advanced Darkplaces shaders=\r
400 ==========================================
401
402 Shader parameters for DP's own features:
403 - dp_reflect <distort> <r> <g> <b> <a>
404   Makes surfaces of this shader reflective with r_water. The reflection is
405   alpha blended on the texture with the given alpha, and modulated by the given
406   color. distort is used in conjunction with the normalmap to simulate a
407   nonplanar water surface.
408 - dp_refract <distort> <r> <g> <b>
409   Makes surfaces of this shader refractive with r_water. The refraction
410   replaces the transparency of the texture. distort is used in conjunction with
411   the normalmap to simulate a nonplanar water surface.
412 - dp_water <reflectmin> <reflectmax> <refractdistort> <reflectdistort> <refractr> <refractg> <refractb> <reflectr> <reflectg> <reflectb> <alpha>
413   This combines the effects of dp_reflect and dp_refract to simulate a water
414   surface. However, the refraction and the reflection are mixed using a Fresnel
415   equation that makes the amount of reflection slide from reflectmin when
416   looking parallel to the water to reflectmax when looking directly into the
417   water. The result of this reflection/refraction mix is then layered BELOW the
418   texture of the shader, so basically, it "fills up" the alpha values of the
419   water. The alpha value is a multiplicator for the alpha value on the texture
420   - set this to a small value like 0.1 to emphasize the reflection and make
421   the water transparent; but if r_water is 0, alpha isn't used, so the water can
422   be very visible then too.
423