Update Programming Tips
[xonotic/xonotic.wiki.git] / Mapping-FirstMap.md
1 Mapping - First Map
2 ===================
3
4 Types of Maps
5 -------------
6
7 There are three types of xonotic maps.
8
9 -   Indoor (stormkeep)
10 -   Outdoor (space elevator)
11 -   Mixture of the above (solarium)
12
13 Regardless of the type, every map needs to be completely enclosed. No entity should be able to escape from your map.
14 The map compiler will tell you if your map is *leaking*.
15
16 Per-Map Setup
17 -------------
18
19 To keep things organized, every map should be created in its own folder in your userdata folder (see [Setup](mapping-Setup)).
20 This folder's name needs to end with `.pk3dir` for Xonotic to recognize it. The convention is to name this folder `map-<mapname>_<version>.pk3dir`.
21 In this folder, you need to save your map in a `maps` subfolder. For example, on Linux it should go into `~/.xonotic/data/map-<mapname>_<version>.pk3dir/maps/<mapname>_<version>.map`.
22
23 The `<mapname>` should be alpha-numeric, lowercase with dashes.
24
25 Keeping every map in its own folder also simplifies [Packaging and releasing](mapping-packaging).
26
27 Building blocks
28 ---------------
29
30 There are three types of building blocks for every map:
31
32 ### Brushes
33 Brushes are the main building blocks for every map. They need to be [convex](https://en.wikipedia.org/wiki/Convex_polytope).
34 If you need concave shapes in your map, either break them down into multiple convex brushes or use a model (see Entities).
35 Brushes are defined by a number of faces.
36
37 Brushes are used to create the layout of your map.
38
39 To create a new brush, make sure that you don't have any object selected (`Esc`) and simply Click+Drag in any 2D pane.
40
41 ![Create a brush](assets/images/radiant-create-brush.gif)
42
43 To move a brush (or even multiple brushes), select it and drag it around in either a 2D or 3D view.
44 If you initially click outside of any selected brush, dragging will resize these brushes.
45
46 ![Move and resize a brush](assets/images/radiant-move-resize-brush.gif)
47
48 ### Patch meshes
49 Patch meshes (or curves) are one-sided surfaces. They are defined by two types of points (use `V` to activate vertex selection):
50 -   Green points: describe points that are on the surface
51 -   Pink points: Control points that describe how the surface curves between the green points
52
53 ![Simple patch mesh](assets/images/radiant-patch-example.png)
54
55 The detail/smoothness of patch meshes is controlled by the ingame settings.
56
57 ### Entities
58 Entities are used for everything that needs special handling ingame. This includes spawn points, game models, doors/moving brushes, control logic and more.
59 Entities can be placed from the rightclick menu in 2D panes.
60
61 First room
62 ----------
63
64 First of all you should select a big grid size (Grid64 by pressing `7`). Leftclick and drag in a 2D view to create a reasonably sized brush
65 (at least 128 Units high - player models are a bit more than 64 Units high). With this brush selected, select a smaller grid size (Grid16 - `5`)
66 and use the `Make Room` tool. The selected grid size will determine the wall thickness. Only make thin walls if absolutely needed! 
67 If your NetRadiant build is too old to have the `Make Room` tool, you can use the `Make Hollow` tool and move all the resulting walls out a bit
68 so that they no longer overlap.
69
70 ![First Room](assets/images/radiant-first-room.png)
71
72 Next, the room needs to be textured. For this, with your brushes selected, open the Texture browser (`T`) and select a Texture.
73 Note that for optimized maps only faces that are visible should be textured, all non-visible faces should use the `caulk` shader.
74 For more information, see [Optimizations](mapping-Optimizing).
75
76 Every map needs at least one entity. To place one, a right-click in a 2D pane will make a menu appear. Player spawnpoints have names that start with `info-player-`.
77 For now, choose `info-player-deathmatch`. Make sure you don't have anything selected as this will replace your selection.
78 If the spawnpoint is not inside the room, move it just like you move a brush.
79
80 Compiling and Testing
81 ---------------------
82
83 Before a map can be tested ingame, it first needs to be compiled to a `.bsp` file. There are several presets in the `Build` menu. To simply test the layout,
84 `Single: -bsp` is a good choice. It will also not add any lighting information, making it possible to test the map without placing lights or light emiting shaders.
85 The `Final` presets take much longer to compile and should only be used once you're confident in your layout and lighting.
86
87 Once the build is finished without errors, you can start Xonotic. To test your map, type `chmap <mapname>_<version>` in the ingame console (`Shift+Esc`).  
88 **TIP**: You can use `Tab` to autocomplete commands and mapnames.
89
90 The engine will automatically generate a `<mapname>_<version>.mapinfo` file in your userdata folder under `data/maps/autogenerated/`,
91 e.g. under Linux `~/.xonotic/data/data/maps/autogenerated/` (yes, `data` **twice**). You should move this file next to your `.map` file
92 and adapt it (- it's just a text file).
93
94 Adding a second room
95 --------------------
96
97 You can create a second room just like you did with the first one. To make a doorway, select a wall brush and use the `Clipper` tool (`X`).
98 With the Clipper tool, you can define a plane that will cut the selected brushes. Define up to three points by leftclicking in any 2D pane.
99 You can also move these points by dragging them around. Once you have at least two points defined NetRadiant will preview the cutted brush.
100 The infinitely long line (red in 2D panes, white in the 3D view) show the cutting plane's normal. By pressing `Enter` the selected brushes will be cut,
101 removing all the parts on the side of the normal. If you want to keep both sides, you can press `Shift+Enter` instead.
102
103 ![Using the clipper tool](assets/images/radiant-second-room-clipper.png)
104
105 Create new brushes to create a hallway connecting the two rooms. You can also use `Ctrl+C` and `Ctrl+V` to copy&paste brushes. The toolbar also has
106 buttons to flip and rotate objects around the three major axes. Make sure that the map is completely enclosed and brushes are not overlapping,
107 otherwise textures might flicker (so called *Z-fights*).
108
109
110 \<\< [NetRadiant](mapping-NetRadiant) | [Packaging](mapping-packaging) \>\>
111
112 … [Creating_Maps](Creating-Maps) …
113