A Community discussion forum for Halo Custom Edition, Halo 2 Vista, Portal and Halo Machinima

Home  Search Register  Login Member ListRecent Posts
  
 
»Forums Index »Halo Custom Edition (Bungie/Gearbox) »Halo CE General Discussion »Here is an explaination of Tools commands and parameters

Author Topic: Here is an explaination of Tools commands and parameters (4 messages, Page 1 of 1)
Moderators: Dennis

MosesofEgypt
Joined: Apr 3, 2013


Posted: Mar 7, 2018 11:43 AM    Msg. 1 of 4       
Since people keep asking for help with using Tool I'm making the assumption that they aren't using Pool. For anyone interested, this is Pool:
forum.halomaps.org/index.cfm?page=topic&topicID=50518

For anyone who just wants to know Tools commands and arguments, here is most of Pools readme with the Pool directives and useless/unknown Tool commands removed.


The argument types are as follows:

bool: A true or false value. 0 for false, 1 for true.

float: A number that can have a decimal(ex: 1.337).

str: A string of characters such as "letters". If the
string contains spaces, enclose the string in quotes.
(ex: "this is a string")

dir: A path to a directory. These directories are always
relative to the data directory or tags directory(depends
on the command). Do NOT use / to separate folders. Tool
does not recognize / as a separator. Use \ instead.

str-no-quote: Same as str, except it cannot be enclosed
in quotes, and as a result cannot contain spaces.

file-no-ext: Same as file, except you do not provide the
file extension. Tool will either know the extension
already or will be able to guess it.


# TOOL COMMANDS
################

animations
Compiles a folder of jma/jmm/jmo/jmr/jmt/jmw/jmz animations in the data folder into a
model_animations tag. The directory you specify must contain these files in a folder
named "animations". Do NOT type the "animations" part of the path; it is implied.

Each jm* type compiles to a different type of animation. dx/dy/dz means the animation
will permanently move the object in the world on that/those axis, while dyaw means it
will permanently rotate the object. These are typically used for movement and turning.

base (overlays can be played on it)
jmm: none
jmw: none (completely world relative)
jma: dx/dy
jmt: dx/dy/dyaw
jmz: dx/dy/dz/dyaw

overlay (plays on the current base {aiming, tire suspension, etc})
jmo: none

replacement (replaces anything being played {grenade throw, etc})
jmr: dx/dy

# ARGUMENTS
############
<source-directory> (dir)
The directory containing the "animations" folder to be compiled.


bitmap
Compiles the .tif image specified into a bitmap tag. Name the file with a .tif
extension, not .tiff(tool only looks for .tif files). Once the bitmap is compiled,
you may edit it in Guerilla or Mozzarilla to change how tool processes and compiles
it. When you are done, run this command again to process it with those setting
applied.

# ARGUMENTS
############
<source-file> (file-no-ext)
The filepath of the bitmap to be compiled.


bitmaps
Compiles a folder of .tif images in the data folder into bitmap tags. Name them with
a .tif extension, not .tiff(tool only looks for .tif files). Once the tags are
compiled, you may edit them in Guerilla or Mozzarilla to change how tool processes
and compiles them. When you are done, run this command again to process them with
those setting applied.

# ARGUMENTS
############
<source-directory> (dir)
The directory containing the bitmaps to be compiled.


build-cache-file
Builds a cache file(a .map file) with no Open Sauce enhancements.

# ARGUMENTS
############
<scenario-path> (file-no-ext)
Filepath of the scenario tag to build the map cache file from.


build-cache-file-ex
Builds a cache file(a .map file) with extra Open Sauce arguments.

# ARGUMENTS
############
<mod-name> (str)
The name of the mod this scenario belongs to. This will also be used when
naming the new data-files.

<create-anew> (bool)
Should new data-files be created before building the map?

<store-resources> (bool)
Store the scenarios bitmaps/sounds/locale data in the data-files?

<use-memory-upgrades> (bool)
Does the scenario require Open Sauces memory upgrades to run?

<scenario-path> (file-no-ext)
Filepath of the scenario tag to build the map cache file from.


build-cache-file-new
Builds a cache file(a .map file) with extra Open Sauce arguments.

# ARGUMENTS
############
<create-anew> (bool)
Should new data-files be created before building the map?

<store-resources> (bool)
Store the scenarios bitmaps/sounds/locale data in the data-files?

<use-memory-upgrades> (bool)
Does the scenario require Open Sauces memory upgrades to run?

<scenario-path> (file-no-ext)
Filepath of the scenario tag to build the map cache file from.


build-cpp-definition
Builds a C++ definition for the tag-group specified and writes it to the current
working directory(typically the folder tool.exe is in).

# ARGUMENTS
############
<tag-group> (str-no-quote)
The four character code designated for this tag type. For example, 'bitm' is for
bitmap, 'matg' is globals, and 'snd!' is sound.

<add-boost-asserts> (bool)
Add assertions to the C++ definition to help make sure the structures are the
correct size if you modify them?


collision-geometry
Compiles a directory of .jms models in the data folder into a
model_collision_geometry tag. The directory you specify must contain these files in
a folder named "physics". Do NOT type the "physics" part of the path; it is implied.

The name of each jms file in the "physics" folder must be the permutation name that
jms file contains. Here are most of the special permutation names as well as when
they are used:
__base (the default model)
~blur (vehicle tires are spinning fast)
~primary-blur (weapon primary trigger is firing fast)
~secondary-blur (weapon secondary trigger is firing fast)
~damaged (health of a region hit zero and died)

If there is a "physics.jms" file in the "physics" folder, make sure it either has
no vertices and triangles, or you have Pool's "Fix physics.jms" setting checked.
The command might fail otherwise.

# ARGUMENTS
############
<source-directory> (dir)
The directory containing the "physics" folder to be compiled.


compile-shader-postprocess
Creates shader_postprocess_generic tags from HLSL .fx shaders in the data directory.

# ARGUMENTS
############
<shader-directory> (dir)
Directory that contains the shaders to compile


hud-messages
Compiles a "hud messages.hmt" file in the specified folder into a hud_message_text
tag. The .hmt file must be saved in Unicode 16Bit encoding(not ANSI/ASCI/UTF8).
Each line in the .hmt file must have the format "X=Y" where X is the message name,
and Y is the message.

The message name must be 31 characters or less. The entire message must be on the
same line as the "X=" part. If you need to put a line break in the message, type |n
instead. You can also specify a button/weapon icon to appear in part of the message
using special characters. Here is a list of the icon names:
%a-button, %b-button, %x-button, %y-button
%black-button, %white-button, %left-trigger, %right-trigger
%dpad-up, %dpad-down, %dpad-left, %dpad-right
%start-button, %back-button, %integrated-light, %jump
%left-thumb, %right-thumb, %left-stick, %right-stick
%action, %throw-grenade, %primary-trigger
%use-equipment, %rotate-weapons, %rotate-grenades
%zoom, %crouch, %accept, %back, %move, %look
%custom-1, %custom-2, %custom-3, %custom-4
%custom-5, %custom-6, %custom-7, %custom-8

Example:
pickup=Press %action to swap|n%custom-1|nfor|n%custom-2

# ARGUMENTS
############
<hmt-path> (dir)
The directory containing the "hud messages.hmt" file.

<scenario-name> (str)
After the hud_messages_text tag is compiled, this is the name of the scenario
to put a reference to it in. This scenario must be in the same folder as where
the hud_message_text tag will compile to.


import-structure-lightmap-uvs
Replaces the lightmap UVs of a bsp with custom ones loaded from an obj file. The obj
file must have lightmaps grouped by object and have the group index appending the
group name (lightmap_0). Best way to ensure this is to export a fresh lightmaps obj
using Aether, import it into your modelling program, and then ONLY edit the UVs to
ensure the model matches the bsp.

# ARGUMENTS
############
<structure-bsp-path> (file-no-ext)
Location of the target bsp, relative to the tags directory.

<obj-file-path> (file-no-ext)
Location of the source obj, relative to the data directory.


lightmaps
Runs radiosity on the specified bsp to calculate static lighting. This process can
typically take a long time at highest quality, so only run it when you have time to
spare.

Quick and dirty lightmaps can be calculated to allow you to quickly test changes to
the level geometry. Use this command if you dont know what good testing values for
your bsp are:
lightmaps <scenario> <bsp-name> 0 0.1

Best quality lightmaps would use these settings:
lightmaps <scenario> <bsp-name> 1 0.0000001

# ARGUMENTS
############
<scenario-path> (file-no-ext)
Filepath to the scenario that uses the bsp you want to light.

<bsp-name> (str)
The name of the bsp to run radiosity on.
This is the name of the structure_scenario_bsp tag you are running this on.

<render-high-quality> (bool)
Use highest quality radiosity settings?

<stop-threshold> (float)
The amount of light remaining to stop calculating at. Light is cast in multiple
passes from each surface, getting progressively finer with each pass. Each pass
also reduces the total amount of light to be cast from each surface. When the
amount of light remaining hits this value, radiosity will stop.


merge-scenery
Merges scenery instances from the source-scenario into the destination-scenario.

# ARGUMENTS
############
<source-scenario> (file-no-ext)
The filepath of the scenario to copy the scenery from.

<destination-scenario> (file-no-ext)
The filepath of the scenario to paste the scenery into.


model
Compiles a directory of .jms models in the data folder into a gbxmodel tag. The
directory you specify must contain these files in a folder named "models". Do NOT
type the "models" part of the path; it is implied.

The name of each jms file in the "models" folder must be the permutation name that
jms file contains. Here are most of the special permutation names as well as when
they are used:
__base (the default model)
~blur (vehicle tires are spinning fast)
~primary-blur (weapon primary trigger is firing fast)
~secondary-blur (weapon secondary trigger is firing fast)
~damaged (health of a region hit zero and died)

# ARGUMENTS
############
<source-directory> (dir)
The directory containing the "models" folder to be compiled.


physics
Compiles a "physics.jms" model in the data folder into a physics tag. The directory
you specify must contain a folder named "physics" with "physics.jms" INSIDE that
"physics" folder. Do NOT type the "physics\physics" part of the path; it is implied.

# ARGUMENTS
############
<source-directory> (dir)
The directory containing the "physics" folder to be compiled. The "physics"
folder must contain the physics.jms file to be compiled.


remove-os-tag-data
Removes OS tag data that would prevent loading in the stock tools. Back up your
tags before hand to be safe.

# ARGUMENTS
############
<tag-path> (file-no-ext)
Filepath to the tag to clean.

<tag-type> (str)
Type of the tag (the tags file extension).

<recursive> (bool)
Process all tags referred to by the given tag?


sounds
Compiles a directory of folders of .wav files in the data folder into sound tags.
Each folder in the directory specified will be compiled into a sound tag. Any
sub-folders within these are treated as pitch ranges. Any .wav files inside these
pitch range folders are permutations within that pitch range. If you do not need to
use pitch ranges, just put each .wav permutation file directly inside each sounds
folder.

For example, to compile the tag:
vehicles\sophia\sounds\cannon_fire.sound

you would create this audio perumtation:
vehicles\sophia\sounds\cannon_fire\default.wav

and then run the command:
sounds vehicles\sophia\sounds ogg 1

NOTE: All .wav data files MUST be saved with 16bit signed, little endian, PCM
encoding. This is the only format that tool can read.

# ARGUMENTS
############
<directory-name> (dir)
The directory containing the sounds to be compiled.

<platform> (str)
The format to compile the sounds to. The xbox and wav formats are basically the
same, and are the only ones that will work on an Xbox. Ogg can only be used PC,
and has higher quality than the others. If you have a choice, choose xbox for
short quick sounds, and ogg for music or dialog.

<ogg-quality> (float)
The relative quality of ogg compressed audio. Higher values create higher quality
audio, but also higher filesize. Valid values are (-0.1, 1]. The value -0.1
is itself not a valid value, so -0.09999999 is the closest you can get to it.

-0.09999999 = ~48 kbit/s
0.0 = ~64 kbit/s
0.2 = ~96 kbit/s
0.4 = ~128 kbit/s
0.6 = ~192 kbit/s
0.8 = ~256 kbit/s
1.0 = ~500 kbit/s


strings
Compiles a folder .txt files into string_list tags. Each .txt file must be saved in
ANSI or ASCII encoding.

NOTE: After each separate string in the text file you must put ###END-STRING### on
the next line. This is how it should look:

Here is my first string
###END-STRING###
Here is my second string
###END-STRING###
Here is my last string
###END-STRING###

# ARGUMENTS
############
<source-directory> (dir)
The folder containing the .txt files to turn into string_list tags.


structure
Compiles a .jms model in the data folder into a scenario_structure_bsp (sbsp) tag.
The directory you specify must contain this .jms file in a folder named "models".
Do NOT type the "models" part of the path; it is implied.

The name of the jms file in the "models" folder is the name the bsp it compiles to
will be given. This is typically the same name as the scenario, but large levels
may utilize multiple bsps.

If a scenario tag doesn't already exist in the folder this sbsp tag will be compiled
into, one referencing the new bsp will be created.

# ARGUMENTS
############
<scenario-directory> (dir)
The directory containing the "models" folder that contains the .jms file you
are compiling.

<bsp-name> (str)
The name of the .jms file to compile, as well as the name to give the
scenario_structure_bsp tag you are compiling.


structure-breakable-surfaces
Creates breakable surfaces structures in the specified structure_scenario_bsp (sbsp)
tag. Each surface has a flag to specify if it is breakable. When the sbsp tag is
compiled from a .jms file, the shaders determine whether to set these flags for each
surface. This command will generate breakable-surface structures for each surface
flagged as breakable. Surfaces will not actually break if these structures are not
generated after compiling the sbsp tag.

# ARGUMENTS
############
<structure-path> (file-no-ext)
The scenario-structure-bsp tag to generate breakable surfaces for.


structure-lens-flares
Calculates and inserts lens flare markers and dependencies into the specified
scenario_structure_bsp (sbsp) tag. The lens_flares as well as how far apart to
place them are pulled from the sbsp's shaders.
The only shaders tags that can reference lens_flare tags are these:
shader_environment
shader_transparent_generic
shader_transparent_chicago
shader_transparent_chicago_extended

# ARGUMENTS
############
<structure-path> (file-no-ext)
The scenario-structure-bsp tag to calculate lens flares markers and
dependencies for.


unicode-strings
Compiles a folder .txt files into unicode_string_list tags. Each .txt file must be
saved in Unicode 16Bit encoding. Big/little endian byteorder does not matter, just
do not save as ANSI, ASCII, or UTF8, only UTF16.

NOTE: After each separate string in the text file you must put ###END-STRING### on
the next line. This is how it should look:

Here is my first string
###END-STRING###
Here is my second string
###END-STRING###
Here is my last string
###END-STRING###

# ARGUMENTS
############
<source-directory> (dir)
The folder containing the .txt files to turn into unicode_string_list tags.


windows-font
Displays a prompt which allows you to select an installed Windows font you wish to
compile into a font tag.

# ARGUMENTS
############
None


Edited by MosesofEgypt on Mar 7, 2018 at 11:12 PM


not giraffe
Joined: Jul 17, 2014


Posted: Mar 7, 2018 09:34 PM    Msg. 2 of 4       
<use-high-quality(ogg_only)>  (bool)

This is incorrect. It is a float value.

Use -0.09999999 (rounds close to -0.1 which for some reason isn't allowed) to 1 for varying qualities.
Assuming 44 kHz stereo:

-0.09999999 = ~48 kbit/s
0.0 = ~64 kbit/s
0.1 = ~80 kbit/s
0.2 = ~96 kbit/s
0.3 = ~112 kbit/s
0.4 = ~128 kbit/s
0.5 = ~160 kbit/s
0.6 = ~192 kbit/s
0.7 = ~224 kbit/s
0.8 = ~256 kbit/s
0.9 = ~320 kbit/s
1.0 = ~500 kbit/s

Or if you want to specify bitrate you would use a value from 32000 to 256000.


Edited by not giraffe on Mar 10, 2018 at 04:42 AM


MosesofEgypt
Joined: Apr 3, 2013


Posted: Mar 7, 2018 11:04 PM    Msg. 3 of 4       
Thanks, I'll make the change and push it when there is another change more significant to attach it to lol. At least calling a bool was still technically correct lol. I have to admit though, I haven't experimented enough with all of the commands to guarantee these are 100% accurate. I'm 99% confident about everything, though there may be a mistake or two. Let me know if you find any other things needing fixing.
Edited by MosesofEgypt on Mar 7, 2018 at 11:37 PM


not giraffe
Joined: Jul 17, 2014


Posted: Mar 9, 2018 02:16 AM    Msg. 4 of 4       
While that argument is ogg quality, it is also interchangeable with ogg bitrate. As I mentioned, if you want then you can specify a bitrate between 32000 and 256000. Using Ogg quality gives a variable bitrate, while specifying a bitrate will try to maintain an average bitrate.

When specifying a bitrate, tool allows a minimum input of 16000. However, a value less than 32000 will cause an error while compressing. It can be fixed by modifying the minimum float to 32000 instead. Also the maximum bitrate of 256000 can be modified to a higher value of 500000.

After some testing it seems max bitrate varies depending on kHz and audio channel count. The bitrates of the quality levels I had mentioned assumed you were using 44 kHz stereo, however it seems the actual bitrate is dependent on kHz and audio channel count. These are the max values you can use without getting an error while compressing:
22 kHz mono max bitrate is 90000.
22 kHz stereo max bitrate is 180000.
44 kHz mono max bitrate is 240000.
44 kHz stereo max bitrate is 500000.

This might be a bit too confusing for the average user, so ogg quality is probably easier to use.

Also, it seems -0.1 is invalid because of a rounding error. It is stored as a double while the input argument is a float. Changing the hex value to a float and assembly to load it as a float fixes the issue. The hex value can also be changed to as low as -0.2 which is ~32 kbit/s for 44 kHz stereo, but only if you are using the aoTuV dlls.

EDIT: I noticed the ogg vorbis dlls you included with your app are official, rather than aoTuV (allows compressing with lower quality settings and improves compression quality). With the official dlls the minimum bitrate you can specify is 45000 instead of 32000. This also changes the bitrate of quality -0.1 to ~45 kbit/s for 44 kHz stereo.

ANOTHER EDIT: While 44 kHz mono compiles fine with ogg and also plays fine in guerilla, it does not seem to play in-game.

Edited by not giraffe on Mar 10, 2018 at 04:39 AM

 

 
Previous Older Thread    Next newer Thread







Time: Sun December 9, 2018 8:03 PM 187 ms.
A Halo Maps Website