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