RESGen v2.0 manual

INDEX
1. Copyright and warranty
2. About RESGen
3. Command line parameters
4. Changes between v1 and v2
5. Using resource verification
6. Credits
7. Changelog


1. Copyright and warranty
	RESGen. A tool to create .res files for Half-Life.
	Copyright (C) 2000-2003 Jeroen Bogers
	
	RESGen is free software; you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation; either version 2 of the License, or
	(at your option) any later version.
	
	RESGen is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.
	
	You should have received a copy of the GNU General Public License
	along with RESGen; if not, write to the Free Software
	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

	
2. About RESGen
	RESGen is a tool to create res (resource) files for Half-Life.
	If a Half-Life map has a corresponding res file, Half-Life is able to
	send all resources the resources the map uses to the clients, if they
	don't have them. This helps a great deal when running a server with
	custom maps, instead of the defaults. Most players do not have these
	custom maps and the resources that should go with them. The res file
	enables them to download the map via Half-Life and start playing right
	away.
	The problem with res files, however, is that it can take hours to create
	one if the resources used by a map are not known. RESGen can shorten this
	time to mere seconds. It reads the maps BSP file and searches it for
	used resources. The results of this search are then used to create the
	res file.


3. Command line parameters
	-h help
		Displays the help screen.
	
	-c
		Displays the RESGen credits.
	
	-w
		Displays the warranty for RESGen.
	
	-v
		Makes RESGen only give minimal output.
		It's recommended you use this if you want to create res files as fast
		as possible. RESGen will still report any error.
	
	-s
		RESGen will not display it's status line. This might considerably speed
		up res file generation, especially on smaller maps.
	
	-i
		RESGen will only report the base folder it's searching, but not the
		subfolders. Useful with -r option.
	
	-j
		Resources found while building the resource list will not be displayed.
		Useful with -e option.
	
	-d [folder]
		[folder] will be searched for bsp files. A trailing (back)slash is
		optional.
	
	-r [folder]
		[folder] and it's subfolders will be searched for bsp files. A trailing
		(back)slash is optional.
	
	-f [map]
		A res file will be generated for [map]. The .bsp file extension is
		optional.
	
	-x [map]
		Exclude this map from res file generation. Only works on maps found
		with -d or -r options. The .bsp file extension is optional.
	
	-o
		If a res file already exists it will be overwritten.
	
	-a [rfafile]
		The contents of the rfa file will be added to the end of the res file.
		This is useful when adding custom resources, like the StatsMe
		sound pack. The .rfa file extension is optional.
	
	-l
		Turns off converting all res file entries to lowercase. RESGen converts
		all res file entries to lowercase since this is the	default for
		Half-Life files. It has to do this because a lot of resource files in
		maps don't have the proper case that matches the actual	resources.
		Only use this option if you know what you are doing.
	
	-e [modpath]
		Makes RESGen verify that all resources in the res file actually exist.
		Resources that can't be found will be excluded from the res file.
		RESGen expects modpath to point to a valid mod directory structure.
		If the modpath isn't the valve folder, RESGen will try to find the
		valve folder too, so a complete resource list can be established.
	
	-p
		Prevents RESGen from using the contents of any pakfile for resource
		verification. Thus, any resource that is available, but in a pakfile
		is excluded from the res file. This option is only useful when the
		-e option is also used. Please note that if a map comes with it's own
		pakfile, using this option will generate a res file that is
		incomplete.
	
	-k
		Windows only. RESGen will not wait for the user to press a key to exit.
	
	-t
		Linux only. RESGen will ignore symbolic links when searching folders
		for .bsp files. Please note that this does NOT affect resource
		searching. Useful with -d or -r options.
	
	
	Example:
	    resgen -ok -r C:\sierra\half-life\tfc -e C:\sierra\half-life\tfc -a shadowlord.rfa
	
	This will make RESGen generate res files for all maps that are in the tfc
	folder. It will verify it's resources from the tfc folder and the valve
	folder (C:\sierra\half-life\valve). Any existing res file will be
	overwritten. The contents of shadowlord.rfa will be added to all res files.
	When RESGen is finished it will exit immediately, not waiting for a
	keypress.


4. Changes between v1 and v2
	From the outside RESGen 1 and 2 look similar. On the inside a lot of
	changes have been made. First of all, major parts have been rewritten,
	and other parts have had a major upgrade. The biggest change is that the
	RESGen core is fully C++ now, instead of a bit C++ in a C program.
	Because of this I have DROPPED the scripting return values. It's very
	easy to use the RESGen source in your own programs now.

	The RESGen parser should be a bit faster now. It's speed mainly depends
	on the speed of your hard disk and your output window. That last limitation
	can be overcome by using the -v option (minimal output).

	The last major change is the -e option. It enables you to have RESGen
	automatically verify if you server actually has the resources the map
	claims to need. This especially applies to missing wad files. See
	chapter 4 for more information on how to use the -e option.

	Additionally, RESGen now tries to locate the maps information txt and
	overview pictures. Please note that RESGen can only find these if they
	are stored in the same folder layout as they would be on the server
	(mapname.txt, ../overviews/mapname.txt and ../overviews/mapname.bmp).


5. Using resource verification
	The -e option, can be quite powerful. It can be used several ways.
	Here I try to describe a few of the more common ways, although there
	are many more.
	NOTE: There is a subtle difference between Win32 and the Linux when
	checking if a resource is available or not. On Win32 RESGen does not
	care about case when comparing the found files to the res entry. On
	Linux it does care about it and reject resources when the case
	doesn't match. In 99% of the cases this doesn't matter. However,
	because of this difference it it's recommended to run RESGen on the
	target platform whenever possible.
	
	Method 1, the simple way:
	This method is most commonly used by server admins that want to add
	res files to their servers. Run RESGen on the mod folder you want to
	make res files for. Point the -e option to this folder too. This
	will generate good res files, which contain all found resources.
	You should not use the -p option unless you are certain that you
	have no maps with their own pakfile.
	Example: resgen -r half-life\cstrike -e half-life\cstrike
	
	Method 2, the mapper way:
	You run resgen on the map, and point the -e option to the folder with
	the resources (these can be the same). Please note that the resource
	folder must match the folder layout of a normal folder.
	Using -p is possible if you aren't using a pakfile for your map.
	Also, note that resgen will look for the map info txt and overviews 
	relative to the map itself, not the folder specified with -e
	Example: resgen -f mymap.bsp -e mapping\resourcetank


6. Credits
	This program was made by Jeroen "ShadowLord" Bogers.
	E-mail: resgen@hltools.com
	URL: http://resgen.hltools.com

	Special thanks to:
		"HoundDawg" and UnitedAdmins for hosting this program.
		"luvless" for having the great idea to create this app.
		Valve for creating Half-Life!
		Everyone who uses RESGen.


7. Changelog
	Version 2.0 BETA 3
	 - Bugfix: Overviews were not properly added to the res file. RESGen
	   only looked for a bmp file. To make matters worse, it added it as a tga
	   file to the res file. This behaviour has been corrected. RESGen now
	   looks for a tga and a bmp file (favouring the tga if both are present).
	 - Fix: Half-Life already transfers the map's txt file to the client,
	   without looking at the res file. RESGen used to add this txt file to 
	   the res file too. Since this is not needed and can even create errors,
	   RESGen now does not add the map's txt file to the res file.

	Version 2.0 BETA 2
	 - Bugfix: The parsing enigne crashed when the BSP entity data wasn't in
	   Linux format. It now can work with data in Windows format too. If the
	   BSP is in any other format, the parser will generate an error, instead
	   of crashing.
	 - Bugfix: If there were no WAD files specified for a map, the parser gave
	   an error message for the map and stopped parsing it. It now correctly
	   handles this and can continue parsing the rest of the BSP.
	 - Fix: Entity data corruption errors now give a bit more information about
	   what is wrong with the data.
	 - Bugfix: While running RESGen I discovered that the memory use increased
	   with every parsed map. After running a memory leak detector and
	   reviewing the code, I discovered that I forgot to close the BSP files
	   after reading them (*doh*). They are now properly closed and there is no
	   more memory leaking. (That I know of anyways :)

	Version 2.0 BETA 1
	 - New: Initial release. Total rework of the parsing engine. Also much more
	   object oriented.

