------------------------------------------------------------------------
Santa Toolpak for UT 2004
------------------------------------------------------------------------
by Robert Uyeyama aka Santaduck 
(C) copyright 2004-2006 Robert Uyeyama
Author has nothing to do with Epic or Atari or Macsoft, who own the rights to the Unreal Tournament series of games, the logos, and all that. 

http://www.macologist.org
http://www.santaduck.com 


Feb 2006 Update, Version 3.0
Only three apps have been updated:
1) Santa Standard Bench
2) Santa DEMO Bench
3) DropInstaller

4) ALSO: I've removed the main menu script.  In other words, all toolpack apps are now standalone as they should be.  This was mainly a holdover from submission to the MSU contest.

5) Tech Support: If you have problems launching these apps, try a) fixing permissions via disk utility, or b) setting ownership & permissions to yourself in Get Info for each file.  Also a corrupted OS X (after a disk repair) can corrupt the ability of Applescripts to operate.

------------------------------------------------------------------------
NOTES on VERSION 3.0 UPDATES FEB 2006 
------------------------------------------------------------------------
--v3.0 Feb 7 2006.  1) The two ini files now enable shadows for the MAX setting (blob in v2.0 and earlier), which are not possible in the latest revisions of UT2004. (Even though the GUI control is buggy in 3369.2, shadows do work when implemented correctly in the INI settings, according to Ryan Gordon). 2) Sound is now an option (on/off) in Botmatch, to allow better comparison with windows benchmarks. Note however that sound was left enabled in Epic's bench scripts for ut2003. 3) New feature to skip video rendering added, similar to Doom3's r_skiprender 1. Currently nullrender defaults to windowed mode, and returns 0 fps with demorec playbacks.  v3.0 was an internal release only.

--v3.2 Feb 19: Added to the result dialog box whether audio was enabled or not. Fixed some redundancies in the 'view all settings' mode (sound setting no longer repeated). Put an ascii arrow by AVG FPS in the results to emphasize it.  This version is the public release.

--v3.3 June 06: For Rob-ART Morgan, added 1280x800, and arrow (<--) pointing to the AVERAGE frame rate on the Flyby as well. Publicly released September 15 2006.



1) Santa Standard Bench

* The benchmarking app, Santa Standard Bench, has been updated, as far as Sound, Shadows, and Skipping video rendering.

- Shadows: The previous versions of UT2004 could only display blob shadows, which was what the benchmarking was set to, as indicated if you click on the "see full settings" at the end of the benchmarking procedure.  However, the new versions of Mac UT2004 now are capable of displaying shadows.  Due to a bug in the GUI interface (as of v3369.2), the game client doesn't set shadows correctly through the menu, but it does work perfectly well now when three or four lines are set properly in the ut2004.ini and user.ini.  Therefore the INIs for the Benchmark app have been corrected so that shadows are always enabled at the "MAX" setting, and disabled at the "MIN" seting.  In particular, this will provide better comparison with Windows versions of benchmarkers (such as UMark), in which shadows are enabled.  Thanks to Jason H. catching this point and suggesting we update the benchmarking app.  True full shadows will not appear as ovals under the characters.  Also True Full Shadows on Antalus will be seen under the pine trees as moving shadows of individual branches and leaves.

***Note on video cards that do not support this, shadows will be BLOB, but the results dialog box will report "FULL" shadows for "Max" detail mode.***

  
- Sound: There is now an option to disable sound for BOTMATCH benchmarks (it is always been disabled on the flybys).  Sound processing will be shunted to the second processor in MP systems, but some benchmarks such as UMark (as well as those for other games like the built-in demoplay for Doom3) have sound disabled.  Thus it is an option.  

***Note however that the original UT2003 benchmark scripts from Epic had sound left enabled for botmatches, so this implemented as an option, rather than a default configuration.***


- Skip rendering: This option skips all video rendering during the benchmark, reducing the measurement to something that is more focused upon the processor-limited functions of the game.  This was inspired by the "r_skiprender 1" function in Doom 3.  I didn't check if, like D3, video settings such as resolution and shadows still affect the benchmarked value with skiprendering enabled.  For standard benchmarks, I recommend using your other standard settings (e.g. 1024x768 MAX, no sound) when adding the omission of video rendering.  In UT2004, this is implemented using Engine.NullRenderDevice.  Thanks to Jason H, Petter F, and of course Ryan Gordon for giving me this information.

2) Santa DEMO Bench

I've implemented the three points above: Full shadows, Sound, and Skip rendering.

However:
1) I have not actually tested this App.  Sorry!
2) Full Shadows is probably not enabled in the UT2004 Demo binary as of this writing.
***Therefore, shadows will probably be BLOB, yet the dialog box will report it as "Full?" shadows for the "Max" detail setting.***

3) DropInstaller-- The previous version of this app ignored .UPL and .UCL which belong in System.  I have attempted a quick fix for this, but it has not been exhaustively tested.  I tested it for UPL and UCL files in three cases, so it should be robsut enough for most uses.  However, I did not test it on, for example, the CBP (Community Bonus Pack) to see if it installs all files correctly.

If you wish to install these files manually, do the following:  control-click the Unreal Tournament 2004 application, and select "Show Package Contents", resulting in a finder window of folders within the game bundle.  Drop these files into the System folder that becomes visible here.


**************************************************************************************************
OLDER NOTES DATING FROM THE TOOLPACK'S SUBMISSION TO THE EPIC/NVIDIA MAKE SOMETHING UNREAL CONTEST,
WHERE IT WON AN "HONORABLE MENTION" ( WWW.MAKESOMETHINGUNREAL.COM )
ANY CONTRADICTORY INFO BELOW IS SUPERCEDED BY ANY INFORMATION IN THE FEB UPDATE NOTES ABOVE
**************************************************************************************************

May 23, 2004

------------------------------------------------------------------------
Mission Statement:  What was the goal here?
------------------------------------------------------------------------
* Mac Utility Pack: UT and UT2003/4 for Mac OS X are woefully deficient in utilities from the community.  I decided to make my own for UT2004, and make them as good and feature-packed and safe-from-overwriting as I would demand myself.  I wanted the Santa Toolpak to change the entire experience for the Mac community.

* Synergy: This is a full set a utilities that all work together.  Custom map content installed by DropInstaller, as well as umod files installed by DropUModOUt, both generate "Dependencies" files so that months later, you can go back & see which files go together--  no more will you forget which textures or meshes go with a map!  Better yet, UnInstallIt will even use these dependencies files to uninstall files for you.  

* More Synergy: All applications store the path to UT2004, and use the same file to do so, so once you identify UT2004 in one of the Santa Toolpak apps, you've done so for all of them.

* The keyword is OPTIONS.  None of these tools will overwrite existing files, unless you explicitly say so.  The uModExtractor won't make changes to your INI files unless you approve.  If you attempt to use DropInstaller to install a mod in its own group in the .app hierarchy, it will double-check that you want to do that.  Uninstaller has the option of moving files out to an external folder, or simply deleting them.  DropUZ2 and the Expander have the option of putting processed files in the same path as the source file, or in a folder of your choosing.  

* Requested Options: All Installers  (DropInstaller, CacheOut, DropUModOut) have the two options of putting files in: the UT2004.app bundle (the most common), the application support UT2k4 folder hierarchy in the user library (where the stock INI files, screenshots, and benchmarks go by default in stock UT2004), and the latter two applications have the _third_ option of extracting files to an external folder.

* More Requested Options: The most requested option was OS X finder color labels.  Any time you install files to the ut2004.app bundle, you are asked for the option of color-labeling these files for easy sorting and identification of custom content.  Make it a rainbow!

* More options?  How about a windows version of the benchmark utility, so you can compare your mac rig with your XP rig?

* The other key is ROBUSTNESS.  All utilities resist unusual situations without crashing, and give proper logging:  Try to uz2-compress a uz2 file.  Try to extract cache files from a cache.ini with empty lines, duplicate entries, and bad entries.  Try to extract a .ut4mod file which is not really a ut4mod.  Try doing something from a folder with spaces in its name.  I can't guarantee I've thought of everything, but I've thought of many contingencies.



------------------------------------------------------------------------
CONTENTS AND SHORT DESCRIPTION
------------------------------------------------------------------------

SANTADUCK TOOLPAK 2K4 "Main Application":  This is a main menu selection where the user can choose any of the seven Santa Toolpak utility functions.

SPECIAL NOTE: The apps can also be launched individually, and the "Drop" applications can also be launched "drag-and-drop" droplet style.  In other words, if you highlight 10 files in the OS X finder, just drag them onto the DropUZ2 icon to compress them all, or DropInstaller to install them.  These function much like the familiar Aladdin utilties for mac, DropStuff and StuffitExpander, which you are of course familiar with if you are a mac user.

--------------------
The Seven Utilties:
--------------------

1) DropUZ2 -- Compresses any files to .uz2 format.  This is for game server admins who are setting up compressed redirected downloads.

2) DropUZ2Expander -- Expands .uz2 files.  

3) CacheOut -- Clean your Cache folder. You can install files to your game (.app bundle or home directory), or simply extract files to an outside folder.  Will also repair bad or outdated cache.ini files.  Installations to the .app bundle can be color-labeled by the finder.  There are two modes, Automatic or Manual.  In manual mode, you can confirm or decline the extraction of each file one at at time.

4) DropInstaller -- Will install files as well as folder sets (either to .app bundle or home directory).   You can install entire folders from unzipped custom maps or even full conversion mods.  For example, it will search through a main folder which has UT folders within it (e.g. Maps, Music, Texturs), as well as a "Mod" group folder with a full set of UT folders with that.  Finally, DropInstaller will even make a "Dependencies" file, so you'll always know which files are necessary for each set, whether it's a map or a mod.  No more wondering which textures go with that map!

5) DropUModOut -- Extracts .umod, .ut2mod, and .ut4mods to either an outside folder, or installs them.  Will also read the .ut4mod files for the option of making changes to your INI file, and writes INI change suggestions for .ut2mod and .umod files to the log file for later viewing.  Like DropInstaller, UmodExtractor also will make a "Dependencies" file, so you'll always know which files are necessary for each set, whether it's a map or a mod. 

6) UnInstallIt -- Reads "Dependencies" files created by either DropInstaller or UmodExtractor, to allow you to uninstall files from your game.  You can simply use this to view the dependencies between files, or you can uninstall them as a set-- If so, you have the option of removing the files to an outside folder, or simply deleting them.

7) UT2K4 Santa Standard Bench  -- Performance benchmarks in either "flyby" or "botmatch" mode. No mucking around in the commandline, just point and click. Uses standard INI files of both maximum and minimum video and audio settings, so you can be sure what your video settings were every time. Windows version also included for comparison.  


FOLDERS

1) Santa_Bench_Support contains support files for the benchmarker Santa Standard Bench.  These will be installed automatically.

2) Windows version of Santa Standard Bench contains support files and .bat files for running the *exact* equivalents of the Mac benchmarks, to make valid comparisons between platforms.  Further instructions are included in the file Instructions.txt.

3) Toolpak Applications  contains the components.  The four beginning with "Drop" in their filename are droplet applications, and can be considered standalone apps with the added convenience of batching multiple files or folders that are selected, dragged, and dropped onto the icon.


------------------------------------------------------------------------
LONG DESCRIPTIONS-- 
------------------------------------------------------------------------

-----------------------------------
1) DROPUZ2 - NO LONG DOCUMENTATION
-----------------------------------

------------------------------------------
2) DROPUZ2Expander - NO LONG DOCUMENTATION
------------------------------------------

---------------
3) CACHEOUT -
---------------
 There are two modes, Automatic or Manual.  In manual mode, you can confirm or decline the extraction of each file one at at time.

Note that files in the cache folder are actually fine and accessible by your game.  Therefore if you extract cache files to an external folder, these files are effectively "Uninstalled".

Also I did not implement creating dependencies files using CacheOut.  I tried linking files by time of file creation, but even then unrelated file groups would be linked together.  For example, if you go to a new server, you could conceivably get a new anticheat .u file, new models, and then a custom map and its auxiliary texture/mesh/music files all in one go-- the files will be separated by less than 2 minutes each, but would actually represent at least three groups: the anticheat, the model, and the custom map.  Therefore I left dependencies files creation to DropInstaller and DropUModOut only.

----------------------------------------
4) DROPINSTALLER - NO LONG DOCUMENTATION
----------------------------------------

----------------------------------------
5. DROPUMODOUT, LONG DOCUMENTATION
----------------------------------------
Dropumodout has the option to extract to 1) userhome, 2) ut2004.app bundle, 3) in a new folder in same path as original umod.  If 1) or 3), the script opens the appropriate destination folder at the end of installation.  Dropumodout will handle .umod (UT), .ut2mod (UT2003), and .ut4mod (UT2004) files.

It also features:
protection against spaces in umod's path (ucc-bin can't handle that)

protection against spaces in umod file name.

protection against installing .umod or .ut2mod into ut2004

special "long processing" message if umod > 10 Mb

user-interactive editing of INI files, if specified by uMod
 *will make new file if specified INI does not exist
 *will make new [section.section] if the one specified does not exist
 *will not make INI changes for .umod or .ut2mod, but in these cases it will list the suggested changes in the log file.

Writes dependencies file into application support/ut2k4/dependencies folder.  This can be viewed by user, and also used by the UnInstaller application in the Santa Toolpak.  The entries in the dependency file includes all files in the umod, whether or not they were actually installed (e.g. if the file exists, ucc-bin will not overwrite them).


3) UNINSTALLIT - NO LONG DOCUMENTATION

---------------------------------------------
7) SANTA STANDARD BENCH,  LONG DOCUMENTATION
---------------------------------------------

__________________________________
A. WINDOWS VERSION FOR COMPARISON
__________________________________
The windows version of this benchmark in the form of .bat files is included.  The default map for both botmatch and flyby demos is dm-inferno.  The textfile instructions with the windows versions detail how to compare other maps with the mac version.

______________________
B. NOTES:
______________________
1.These benchmarks are based upon the benchmarks that shipped from Epic for UT2003.  Both seconds and botcount have been preserved exactly from these.  The only major change is that in the botmatch, difficulty of the bots have been set to 7 (Godlike), to produce more action, otherwise the bots just stand still and shoot their default assault gun.  The other exception is that both flyby and botmatch have "stat fps" in the exec to view the FPS score developing in real time.

Of course mindesiredframerate is set to 0, and -nosound is used for the flyby.

These values (taken from UT2003's standard benchmarks) are:
	
Botmatch     Bots   Seconds
dm-antalus    12     77
br-anubis     12     77
dm-asbestos   12     77
ctf-citadel   12     77
dm-inferno    10     100
dom-suntemple 10     100

Flyby:
dm-antalus           77
dm-asbestos          71
ctf-citadel          77
ctf-face3            116
dm-inferno           77
dm-phobos2           77
dom-suntemple        77



2. All benchmarks also utilize standardized .ini files.  There are two versions each of ut2004.ini and user.ini, one with the full maximum video/audio settings, and one with the bare minimum.


These default settings are:

Max:
These default settings are: color depth 32bit, texture detail Highest, Character Detail Highest, World Detail High, Physics Detail High, Dynamic Mesh LOD Highest, Decal Stay High, Character Shadows Blob, Decals (X), Dynamic Lighting (X), Cornoas (X), Trilinear Filtering (X), Projectors (X), Foliage (X), Weather Effects (X), Fog Distance Bar all the way to the right, Low Sound Detail ( )

Min:
These default settings are: color depth 16bit, texture detail Lowest, Character Detail Lowest, World Detail Low, Physics Detail Low, Dynamic Mesh LOD Low, Decal Stay --, Character Shadows (None), Decals ( ), Dynamic Lighting ( ), Cornoas ( ), Trilinear Filtering ( ), Projectors ( ), Foliage ( ), Weather Effects ( ), Fog Distance Bar all the way to the left, Low Sound Detail (X)

NOTES:
* Max settings uses "Blob" shadows rather than "Full", because full is not functional in mac UT2004 (up to 3204)
* flyby: Sound is disabled with -nosound flag, so the CPU is not computing sound.
* both: mindesiredframerate is set to 0, so video settings remain the same.
* keyboard & mouse inputs are for the most part disabled, to prevent slight changes these may cause in the result.  Spacebar will allow you to quit at any time during the demo.
* user.ini -- note some of these settings are stored in the user.ini, hence there are different custom user.ini files for "max" and "min" settings.
* I assume the matinees for the flybys are the same as in UT2003, but I haven't checked.


3. This benchmark will not work if you have newly installed ut2k4 and have never run it even once.  You must run it at least once.  This creates your "Unreal Tournament 2004" folder inside your user's Library/Application Support area.  This folder is used by this benchmark.

4. For best results, quit all other running applications, including Classic mode .


________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________

Acknowledgements:
The Clan MacAddict folks, Macologist folks, and Ryan Gordon.



Please see my site for the latest versions.
Get Info in the finder will list the version of each component.
http://www.santaduck.com/

Please post feedback at MACOLOGIST forums:
http://www.macologist.org

Thank you!
Frag Different.

--Santa
