1 /* -------------------------------------------------------------------------------
3 Copyright (C) 1999-2007 id Software, Inc. and contributors.
4 For a list of contributors, see the accompanying CONTRIBUTORS file.
6 This file is part of GtkRadiant.
8 GtkRadiant is free software; you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation; either version 2 of the License, or
11 (at your option) any later version.
13 GtkRadiant is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with GtkRadiant; if not, write to the Free Software
20 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 -------------------------------------------------------------------------------
24 This code has been altered significantly from its original form, to support
25 several games based on the Quake III Arena engine, in the form of "Q3Map2."
27 ------------------------------------------------------------------------------- */
39 const char* description;
42 void HelpOptions(const char* group_name, int indentation, int width, struct HelpOption* options, int count)
45 char* indent = malloc(indentation+1);
46 memset(indent, ' ', indentation);
47 indent[indentation] = 0;
48 printf("%s%s:\n", indent, group_name);
50 indent = realloc(indent, indentation+1);
51 memset(indent, ' ', indentation);
52 indent[indentation] = 0;
55 for ( i = 0; i < count; i++ )
57 int printed = printf("%s%-24s ", indent, options[i].name);
58 int descsz = strlen(options[i].description);
60 while ( j < descsz && descsz-j > width - printed )
63 printf("%s%26c",indent,' ');
64 int fragment = width - printed;
65 while ( fragment > 0 && options[i].description[j+fragment-1] != ' ')
67 j += fwrite(options[i].description+j, sizeof(char), fragment, stdout);
69 printed = indentation+26;
73 printf("%s\n",options[i].description+j);
75 else if ( j < descsz )
77 printf("%s%26c%s\n",indent,' ',options[i].description+j);
88 struct HelpOption bsp[] = {
89 {"-bsp [options] <filename.map>", "Switch that enters this stage"},
90 {"-altsplit", "Alternate BSP tree splitting weights (should give more fps)"},
91 {"-bspfile <filename.bsp>", "BSP file to write"},
92 {"-celshader <shadername>", "Sets a global cel shader name"},
93 {"-custinfoparms", "Read scripts/custinfoparms.txt"},
94 {"-debuginset", "Push all triangle vertexes towards the triangle center"},
95 {"-debugportals", "Make BSP portals visible in the map"},
96 {"-debugsurfaces", "Color the vertexes according to the index of the surface"},
97 {"-deep", "Use detail brushes in the BSP tree, but at lowest priority (should give more fps)"},
98 {"-de <F>", "Distance epsilon for plane snapping etc."},
99 {"-fakemap", "Write fakemap.map containing all world brushes"},
100 {"-fastmeta", "Use small lightmap/surface verts/number maximum numbers (like Q3A), to be used with `-meta`"},
101 {"-flares", "Turn on support for flares"},
102 {"-flat", "Enable flat shading (good for combining with -celshader)"},
103 {"-fulldetail", "Treat detail brushes as structural ones"},
104 {"-keeplights", "Keep light entities in the BSP file after compile"},
105 {"-leaktest", "Abort if a leak was found"},
106 {"-linfile <filename.lin>", "Line file to write"},
107 {"-maxarea", "Use Max Area face surface generation"},
108 {"-maxlightmapvertices <N>", "Sets the maximum number of vertices per lightmapped surface"},
109 {"-maxsurfaceindexes <N>", "Sets the maximum number of indexes per surface"},
110 {"-maxsurfacevertices <N>", "Sets the maximum number of vertices per surface"},
111 {"-meta", "Combine adjacent triangles of the same texture to surfaces (ALWAYS USE THIS)"},
112 {"-metaadequatescore <N>", "Adequate score for adding triangles to meta surfaces"},
113 {"-metagoodscore <N>", "Good score for adding triangles to meta surfaces"},
114 {"-metamaxbboxdistance <F>", "Maximum bounding box distance for meta surfaces"},
115 {"-minsamplesize <N>", "Sets minimum lightmap resolution in luxels/qu"},
116 {"-mi <N>", "Deprecated alias for `-maxsurfaceindexes`"},
117 {"-mv <N>", "Deprecated alias for `-maxlightmapverts`"},
118 {"-ne <F>", "Normal epsilon for plane snapping etc."},
119 {"-nocurves", "Turn off support for patches"},
120 {"-nodetail", "Leave out detail brushes"},
121 {"-noflares", "Turn off support for flares"},
122 {"-nofog", "Turn off support for fog volumes"},
123 {"-nohint", "Turn off support for hint brushes"},
124 {"-nosRGB", "Treat colors and textures as linear colorspace"},
125 {"-nosRGBcolor", "Treat shader and light entity colors as linear colorspace"},
126 {"-nosRGBtex", "Treat textures as linear colorspace"},
127 {"-nosubdivide", "Turn off support for `q3map_tessSize` (breaks water vertex deforms)"},
128 {"-notjunc", "Do not fix T-junctions (causes cracks between triangles, do not use)"},
129 {"-nowater", "Turn off support for water, slime or lava (Stef, this is for you)"},
130 {"-np <A>", "Force all surfaces to be nonplanar with a given shade angle"},
131 {"-onlyents", "Only update entities in the BSP"},
132 {"-patchmeta", "Turn patches into triangle meshes for display"},
133 {"-prtfile <filename.prt>", "Portal file to write"},
134 {"-rename", "Append suffix to miscmodel shaders (needed for SoF2)"},
135 {"-samplesize <N>", "Sets default lightmap resolution in luxels/qu"},
136 {"-skyfix", "Turn sky box into six surfaces to work around ATI problems"},
137 {"-snap <N>", "Snap brush bevel planes to the given number of units"},
138 {"-srffile <filename.srf>", "Surface file to write"},
139 {"-sRGBcolor", "Treat shader and light entity colors as sRGB colorspace"},
140 {"-sRGBtex", "Treat textures as sRGB colorspace"},
141 {"-tempname <filename.map>", "Read the MAP file from the given file name"},
142 {"-texrange <N>", "Limit per-surface texture range to the given number of units, and subdivide surfaces like with `q3map_tessSize` if this is not met"},
143 {"-tmpout", "Write the BSP file to /tmp"},
144 {"-verboseentities", "Enable `-v` only for map entities, not for the world"},
146 HelpOptions("BSP Stage", 0, 80, bsp, sizeof(bsp)/sizeof(struct HelpOption));
151 struct HelpOption vis[] = {
152 {"-vis [options] <filename.map>", "Switch that enters this stage"},
153 {"-fast", "Very fast and crude vis calculation"},
154 {"-hint", "Merge all but hint portals"},
155 {"-mergeportals", "The less crude half of `-merge`, makes vis sometimes much faster but doesn't hurt fps usually"},
156 {"-merge", "Faster but still okay vis calculation"},
157 {"-nopassage", "Just use PortalFlow vis (usually less fps)"},
158 {"-nosort", "Do not sort the portals before calculating vis (usually slower)"},
159 {"-passageOnly", "Just use PassageFlow vis (usually less fps)"},
160 {"-prtfile <filename.prt>", "Portal file to read"},
161 {"-saveprt", "Keep the Portal file after running vis (so you can run vis again)"},
162 {"-tmpin", "Use /tmp folder for input"},
163 {"-tmpout", "Use /tmp folder for output"},
164 {"-v -v", "Extra verbose mode for cluster debug"}, // q3map2 common takes first -v
166 HelpOptions("VIS Stage", 0, 80, vis, sizeof(vis)/sizeof(struct HelpOption));
171 struct HelpOption light[] = {
172 {"-light [options] <filename.map>", "Switch that enters this stage"},
173 {"-vlight [options] <filename.map>", "Deprecated alias for `-light -fast` ... filename.map"},
174 {"-approx <N>", "Vertex light approximation tolerance (never use in conjunction with deluxemapping)"},
175 {"-areascale <F, `-area` F>", "Scaling factor for area lights (surfacelight)"},
176 {"-border", "Add a red border to lightmaps for debugging"},
177 {"-bouncegrid", "Also compute radiosity on the light grid"},
178 {"-bounceonly", "Only compute radiosity"},
179 {"-bouncescale <F>", "Scaling factor for radiosity"},
180 {"-bounce <N>", "Number of bounces for radiosity"},
181 {"-bspfile <filename.bsp>", "BSP file to write"},
182 {"-cheapgrid", "Use `-cheap` style lighting for radiosity"},
183 {"-cheap", "Abort vertex light calculations when white is reached"},
184 {"-compensate <F>", "Lightmap compensate (darkening factor applied after everything else)"},
185 {"-cpma", "CPMA vertex lighting mode"},
186 {"-custinfoparms", "Read scripts/custinfoparms.txt"},
187 {"-dark", "Darken lightmap seams"},
188 {"-debugaxis", "Color the lightmaps according to the lightmap axis"},
189 {"-debugcluster", "Color the lightmaps according to the index of the cluster"},
190 {"-debugdeluxe", "Show deluxemaps on the lightmap"},
191 {"-debugnormals", "Color the lightmaps according to the direction of the surface normal"},
192 {"-debugorigin", "Color the lightmaps according to the origin of the luxels"},
193 {"-debugsurfaces, -debugsurface", "Color the lightmaps according to the index of the surface"},
194 {"-debugunused", "This option does nothing"},
195 {"-debug", "Mark the lightmaps according to the cluster: unmapped clusters get yellow, occluded ones get pink, flooded ones get blue overlay color, otherwise red"},
196 {"-deluxemode 0", "Use modelspace deluxemaps (DarkPlaces)"},
197 {"-deluxemode 1", "Use tangentspace deluxemaps"},
198 {"-deluxe, -deluxemap", "Enable deluxemapping (light direction maps)"},
199 {"-dirtdebug, -debugdirt", "Store the dirtmaps as lightmaps for debugging"},
200 {"-dirtdepth", "Dirtmapping depth"},
201 {"-dirtgain", "Dirtmapping exponent"},
202 {"-dirtmode 0", "Ordered direction dirtmapping"},
203 {"-dirtmode 1", "Randomized direction dirtmapping"},
204 {"-dirtscale", "Dirtmapping scaling factor"},
205 {"-dirty", "Enable dirtmapping"},
206 {"-dump", "Dump radiosity from `-bounce` into numbered MAP file prefabs"},
207 {"-export", "Export lightmaps when compile finished (like `-export` mode)"},
208 {"-exposure <F>", "Lightmap exposure to better support overbright spots"},
209 {"-external", "Force external lightmaps even if at size of internal lightmaps"},
210 {"-extradist <F>", "Extra distance for lights in map units"},
211 {"-extravisnudge", "Broken feature to nudge the luxel origin to a better vis cluster"},
212 {"-extrawide", "Deprecated alias for `-super 2 -filter`"},
213 {"-extra", "Deprecated alias for `-super 2`"},
214 {"-fastallocate", "Deprecated alias for `-fastlightmapsearch`"},
215 {"-fastbounce", "Use `-fast` style lighting for radiosity"},
216 {"-faster", "Use a faster falloff curve for lighting; also implies `-fast`"},
217 {"-fastgrid", "Use `-fast` style lighting for the light grid"},
218 {"-fastlightmapsearch", "Use `-fastlightmapsearch` to trade lightmap size against packing time (useful with hi res lightmaps on large maps: reduce allocation time from days to minutes for only some extra bytes)"},
219 {"-fast", "Ignore tiny light contributions"},
220 {"-fill", "Fill lightmap colors from surrounding pixels to improve JPEG compression"},
221 {"-filter", "Lightmap filtering"},
222 {"-floodlight", "Enable floodlight (zero-effort somewhat decent lighting)"},
223 {"-gamma <F>", "Lightmap gamma"},
224 {"-gridambientdirectionality <F>", "Ambient directional lighting received (default: 0.0)"},
225 {"-gridambientscale <F>", "Scaling factor for the light grid ambient components only"},
226 {"-griddirectionality <F>", "Directional lighting received (default: 1.0)"},
227 {"-gridscale <F>", "Scaling factor for the light grid only"},
228 {"-lightanglehl 0", "Disable half lambert light angle attenuation"},
229 {"-lightanglehl 1", "Enable half lambert light angle attenuation"},
230 {"-lightmapdir <directory>", "Directory to store external lightmaps (default: same as map name without extension)"},
231 {"-lightmapsearchblocksize <N>", "Restrict lightmap search to block size <N>"},
232 {"-lightmapsearchpower <N>", "Optimize for lightmap merge power <N>"},
233 {"-lightmapsize <N>", "Size of lightmaps to generate (must be a power of two)"},
234 {"-lightsubdiv <N>", "Size of light emitting shader subdivision"},
235 {"-lomem", "Low memory but slower lighting mode"},
236 {"-lowquality", "Low quality floodlight (appears to currently break floodlight)"},
237 {"-minsamplesize <N>", "Sets minimum lightmap resolution in luxels/qu"},
238 {"-nobouncestore", "Do not store BSP, lightmap and shader files between bounces"},
239 {"-nocollapse", "Do not collapse identical lightmaps"},
240 {"-nodeluxe, -nodeluxemap", "Disable deluxemapping"},
241 {"-nofastpoint", "Disable fast point light calculation"},
242 {"-nogrid", "Disable grid light calculation (makes all entities fullbright)"},
243 {"-nolightmapsearch", "Do not optimize lightmap packing for GPU memory usage (as doing so costs fps)"},
244 {"-normalmap", "Color the lightmaps according to the direction of the surface normal (TODO is this identical to `-debugnormals`?)"},
245 {"-nosRGB", "Treat colors, textures, and lightmaps as linear colorspace"},
246 {"-nosRGBcolor", "Treat shader and light entity colors as linear colorspace"},
247 {"-nosRGBlight", "Write lightmaps as linear colorspace"},
248 {"-nosRGBtex", "Treat textures as linear colorspace"},
249 {"-nostyle, -nostyles", "Disable support for light styles"},
250 {"-nosurf", "Disable tracing against surfaces (only uses BSP nodes then)"},
251 {"-notrace", "Disable shadow occlusion"},
252 {"-novertex", "Disable vertex lighting"},
253 {"-patchshadows", "Cast shadows from patches"},
254 {"-pointscale <F, `-point` F>", "Scaling factor for spherical and spot point lights (light entities)"},
255 {"-q3", "Use nonlinear falloff curve by default (like Q3A)"},
256 {"-randomsamples", "Use random sampling for lightmaps"},
257 {"-rawlightmapsizelimit <N>", "Sets maximum lightmap resolution in luxels/qu (only affects patches if used -patchmeta in BSP stage)"},
258 {"-samplescale <F>", "Scales all lightmap resolutions"},
259 {"-samplesize <N>", "Sets default lightmap resolution in luxels/qu"},
260 {"-samplessearchboxsize <N>", "Search box size (1 to 4) for lightmap adaptive supersampling"},
261 {"-samples <N>", "Adaptive supersampling quality"},
262 {"-scale <F>", "Scaling factor for all light types"},
263 {"-shadeangle <A>", "Angle for phong shading"},
264 {"-shade", "Enable phong shading at default shade angle"},
265 {"-skyscale <F, `-sky` F>", "Scaling factor for sky and sun light"},
266 {"-smooth", "Deprecated alias for `-samples 2`"},
267 {"-sphericalscale <F, `-spherical` F>", "Scaling factor for spherical point light entities"},
268 {"-spotscale <F, `-spot` F>", "Scaling factor for spot point light entities"},
269 {"-srffile <filename.srf>", "Surface file to read"},
270 {"-sRGB", "Treat colors, textures, and lightmaps as sRGB colorspace"},
271 {"-sRGBcolor", "Treat shader and light entity colors as sRGB colorspace"},
272 {"-sRGBlight", "Write lightmaps as sRGB colorspace"},
273 {"-sRGBtex", "Treat textures as sRGB colorspace"},
274 {"-style, -styles", "Enable support for light styles"},
275 {"-sunonly", "Only compute sun light"},
276 {"-super <N, `-supersample` N>", "Ordered grid supersampling quality"},
277 {"-thresh <F>", "Triangle subdivision threshold"},
278 {"-trianglecheck", "Broken check that should ensure luxels apply to the right triangle"},
279 {"-trisoup", "Convert brush faces to triangle soup"},
280 {"-wolf", "Use linear falloff curve by default (like W:ET)"},
283 HelpOptions("Light Stage", 0, 80, light, sizeof(light)/sizeof(struct HelpOption));
288 struct HelpOption analyze[] = {
289 {"-analyze [options] <filename.bsp>", "Switch that enters this mode"},
290 {"-lumpswap", "Swap byte order in the lumps"},
293 HelpOptions("Analyzing BSP-like file structure", 0, 80, analyze, sizeof(analyze)/sizeof(struct HelpOption));
298 struct HelpOption scale[] = {
299 {"-scale [options] <S filename.bsp>", "Scale uniformly"},
300 {"-scale [options] <SX SY SZ filename.bsp>", "Scale non-uniformly"},
301 {"-tex", "Scale without texture lock"},
302 {"-spawn_ref <F>", "Vertical offset for info_player_* entities (adds spawn_ref, scales, subtracts spawn_ref)"},
304 HelpOptions("Scaling", 0, 80, scale, sizeof(scale)/sizeof(struct HelpOption));
309 struct HelpOption convert[] = {
310 {"-convert [options] <filename.bsp>", "Switch that enters this mode"},
311 {"-deluxemapsastexcoord", "Save deluxemap names and texcoords instead of textures (only when writing ase and obj)"},
312 {"-de <F>", "Distance epsilon for the conversion (only when reading map)"},
313 {"-format <converter>", "Select the converter, default ase (available: map, map_bp, ase, obj, or game names)"},
314 {"-lightmapsastexcoord", "Save lightmap names and texcoords instead of textures (only when writing ase and obj)"},
315 {"-meta", "Combine adjacent triangles of the same texture to surfaces (only when reading map)"},
316 {"-ne <F>", "Normal epsilon for the conversion (only when reading map)"},
317 {"-patchmeta", "Turn patches into triangle meshes for display (only when reading map)"},
318 {"-readbsp", "Force converting bsp to selected format"},
319 {"-readmap", "Force converting map to selected format"},
320 {"-shadersasbitmap", "Save shader names as bitmap names in the model so it works as a prefab (only when writing ase and obj)"},
323 HelpOptions("Converting & Decompiling", 0, 80, convert, sizeof(convert)/sizeof(struct HelpOption));
328 struct HelpOption exportl[] = {
329 {"-export <filename.bsp>", "Copies lightmaps from the BSP to `filename/lightmap_0000.tga` ff"}
332 HelpOptions("Exporting lightmaps", 0, 80, exportl, sizeof(exportl)/sizeof(struct HelpOption));
335 void HelpExportEnts()
337 struct HelpOption exportents[] = {
338 {"-exportents <filename.bsp>", "Exports the entities to a text file (.ent)"},
340 HelpOptions("ExportEnts Stage", 0, 80, exportents, sizeof(exportents)/sizeof(struct HelpOption));
345 struct HelpOption fixaas[] = {
346 {"-fixaas <filename.bsp>", "Switch that enters this mode"},
349 HelpOptions("Fixing AAS checksum", 0, 80, fixaas, sizeof(fixaas)/sizeof(struct HelpOption));
354 struct HelpOption info[] = {
355 {"-info <filename.bsp>", "Switch that enters this mode"},
358 HelpOptions("Get info about BSP file", 0, 80, info, sizeof(info)/sizeof(struct HelpOption));
363 struct HelpOption import[] = {
364 {"-import <filename.bsp>", "Copies lightmaps from `filename/lightmap_0000.tga` ff into the BSP"},
367 HelpOptions("Importing lightmaps", 0, 80, import, sizeof(import)/sizeof(struct HelpOption));
372 struct HelpOption minimap[] = {
373 {"-minimap [options] <filename.bsp>", "Creates a minimap of the BSP, by default writes to `../gfx/filename_mini.tga`"},
374 {"-autolevel", "Automatically level brightness and contrast"},
375 {"-black", "Write the minimap as a black-on-transparency RGBA32 image"},
376 {"-boost <F>", "Sets the contrast boost value (higher values make a brighter image); contrast boost is somewhat similar to gamma, but continuous even at zero"},
377 {"-border <F>", "Sets the amount of border pixels relative to the total image size"},
378 {"-brightness <F>", "Sets brightness value to add to minimap values"},
379 {"-contrast <F>", "Sets contrast value to scale minimap values (doesn't affect brightness)"},
380 {"-gray", "Write the minimap as a white-on-black GRAY8 image"},
381 {"-keepaspect", "Ensure the aspect ratio is kept (the minimap is then letterboxed to keep aspect)"},
382 {"-minmax <xmin ymin zmin xmax ymax zmax>", "Forces specific map dimensions (note: the minimap actually uses these dimensions, scaled to the target size while keeping aspect with centering, and 1/64 of border appended to all sides)"},
383 {"-noautolevel", "Do not automatically level brightness and contrast"},
384 {"-nokeepaspect", "Do not ensure the aspect ratio is kept (makes it easier to use the image in your code, but looks bad together with sharpening)"},
385 {"-o <filename.tga>", "Sets the output file name"},
386 {"-random <N>", "Sets the randomized supersampling count (cannot be combined with `-samples`)"},
387 {"-samples <N>", "Sets the ordered supersampling count (cannot be combined with `-random`)"},
388 {"-sharpen <F>", "Sets the sharpening coefficient"},
389 {"-size <N>", "Sets the width and height of the output image"},
390 {"-white", "Write the minimap as a white-on-transparency RGBA32 image"},
393 HelpOptions("MiniMap", 0, 80, minimap, sizeof(minimap)/sizeof(struct HelpOption));
398 struct HelpOption common[] = {
399 {"-connect <address>", "Talk to a " RADIANT_NAME " instance using a specific XML based protocol"},
400 {"-force", "Allow reading some broken/unsupported BSP files e.g. when decompiling, may also crash"},
401 {"-fs_basepath <path>", "Sets the given path as main directory of the game (can be used more than once to look in multiple paths)"},
402 {"-fs_forbiddenpath <pattern>", "Pattern to ignore directories, pk3, and pk3dir; example pak?.pk3 (can be used more than once to look for multiple patterns)"},
403 {"-fs_game <gamename>", "Sets a different game directory name (default for Q3A: baseq3, can be used more than once)"},
404 {"-fs_home <dir>", "Specifies where the user home directory is on Linux"},
405 {"-fs_homebase <dir>", "Specifies game home directory relative to user home directory on Linux (default for Q3A: .q3a)"},
406 {"-fs_homepath <path>", "Sets the given path as the game home directory name (fs_home + fs_homebase)"},
407 {"-fs_nobasepath", "Do not load base paths in VFS, imply -fs_nomagicpath"},
408 {"-fs_nomagicpath", "Do not try to guess base path magically"},
409 {"-fs_nohomepath", "Do not load home path in VFS"},
410 {"-fs_pakpath <path>", "Specify a package directory (can be used more than once to look in multiple paths)"},
411 {"-game <gamename>", "Load settings for the given game (default: quake3)"},
412 {"-subdivisions <F>", "multiplier for patch subdivisions quality"},
413 {"-threads <N>", "number of threads to use"},
414 {"-v", "Verbose mode"},
415 {"-werror", "Make all warnings into errors"}
418 HelpOptions("Common Options", 0, 80, common, sizeof(common)/sizeof(struct HelpOption));
422 void HelpMain(const char* arg)
424 printf("Usage: q3map2 [stage] [common options...] [stage options...] [stage source file]\n");
425 printf(" q3map2 -help [stage]\n\n");
429 struct HelpOption stages[] = {
430 {"-bsp", "BSP Stage"},
431 {"-vis", "VIS Stage"},
432 {"-light", "Light Stage"},
433 {"-analyze", "Analyzing BSP-like file structure"},
434 {"-scale", "Scaling"},
435 {"-convert", "Converting & Decompiling"},
436 {"-export", "Exporting lightmaps"},
437 {"-exportents", "Exporting entities"},
438 {"-fixaas", "Fixing AAS checksum"},
439 {"-info", "Get info about BSP file"},
440 {"-import", "Importing lightmaps"},
441 {"-minimap", "MiniMap"},
443 void(*help_funcs[])() = {
458 if ( arg && strlen(arg) > 0 )
464 for ( i = 0; i < sizeof(stages)/sizeof(struct HelpOption); i++ )
465 if ( strcmp(arg, stages[i].name+1) == 0 )
472 HelpOptions("Stages", 0, 80, stages, sizeof(stages)/sizeof(struct HelpOption));