TagTool_Documentation_WIP.txt

Get TagTool from https://ci.appveyor.com/project/Beatthezombie/tagtool/builds/32275655/job/0nyje3212u82w3li/artifacts
Source is at https://github.com/TheGuardians/TagTool.
Extract the archive into the game's maps folder, then open TagTool.exe.

Current capabilities (TLDR):
Create, duplicate, rename tags.
Edit tag fields and tagblocks.
Import custom texture, model, sound, simple collisions tags.
Port content from Halo 3 and ODST 360 .map files.

Use "help" command to get a list of all available commands.
Use "help" command within EditTag to get a list of new commands for that tag class. Example: "SetString" only appears when editing a multilingual_unicode_string_list (unic) tag.



// General info about tags:
- Tags are "files" that tell the game which object does what. How fast a weapon can fire, how to display a texture, what text lines should say, groups of materials, map objects etc. They are stored in tags.dat.
- Raw data and resources are stored in resources.dat, textures.dat etc. They are locked while the game runs. Tags.dat is not locked, therefore you can save tag changes and reload the map to apply.
- Do NOT use TagTool and Assembly to edit tags at the same time, it will corrupt tags.dat.
- Modified tags need to be shared by every player when it comes to modified or new objects, maps, etc. Render models are not affected.
- .map files are basically empty, they only have a map ID and Scenario tag index as reference.
- Tags are loaded in memory trough the tag dependency tree, each tag has an internal list of which tags they load.

A tag has (on the user end):
- a tag index (ID) always shown in hexadecimal.
- a name: many Halo Online tags have a name, but not always. If no name is provided, use the tag index.
- a class/group (weapons, vehicles, models, shaders, globals, etc)

Example 1:
Tagname: objects\characters\masterchief\mp_masterchief\mp_masterchief
Tag Index: 0x0CBD
Tag class/group: render_model
Shortened tag class/group: mode
Full tagname: objects\characters\masterchief\mp_masterchief\mp_masterchief.render_model
Shortened tagname: objects\characters\masterchief\mp_masterchief\mp_masterchief.mode
Ingame: main player biped.

Example 2:
Tagname: objects\levels\multi\salvation\shaders\jitter_dataplate1
Tag Index: 0x3401
Tag class/group: shader_halogram
Shortened tag class/group: rmhg
Full tagname: objects\levels\multi\salvation\shaders\jitter_dataplate1.shader_halogram
Shortened tagname: objects\levels\multi\salvation\shaders\jitter_dataplate1.rmhg
Ingame: holograms on Guardian's middle platform, which gets fuzzy when you touch them.


// TagTool tag editing Commands:
Command: EditTag 
Example 1: EditTag shaders\invalid.shader
Example 2: EditTag 0x4A08
Usage: This command is used to start editing a tag. (leave out extended 0's in your tag: 0x00004cb7 = 0x4cb7)

Command: Listfields
Example 1: Listfields
Example 2: Listfields Sandbox
Usage: Display all tag fields and values, tagblocks, and other data. Example for Scenario: MapId (integer), Lightmap (tag reference), tagblocks names and counts. The argument will filter the results.

Command: EditBlock
Example 1: Editblock ShaderProperties[0]
Example 2: Editblock ShaderProperties[*]
Usage: Edit a tagblock. [0] means the first tagblock, it can be between 0 and the max number of tagblocks available. [*] means the last tagblock.

Command: Setfield
Example 1: Setfield Name assault_rifle
Example 2: Setfield ShaderProperties[0].ShaderMaps[0].Bitmap objects\bitmaps\default\grid_256x256.bitmap
Usage: Assign a value to a tag field. To set values in a tagblock, you can either use EditBlock first, or chain tagblocks.

Command: AddBlockElements
Example 1: AddBlockElements SandboxScenery 1
Example 2: AddBlockElements SandboxScenery 10 1
Usage: Add new tagblocks. You can also specify the tagblocks count and the start index. For Example 2, it'll add 1 tagblocks after the 10th tagblock, rarely used.

Command: RemoveBlockElements
Example: RemoveBlockElements SandboxScenery 0 *
Example 2: RemoveBlockElements SandboxScenery 5 1
Usage: Remove tagblocks. You can also specify the tagblocks count and the start index.
Use 0 * to remove all.
When * is added to the command, it will remove all tablocks after the index specified. 
If there are 39 elements in the tagblock, RemoveBlockElements SandboxScenery 8 * will remove all elements after the 8th tagblock.

Command: CopyBlockElements
Example 1: Copyblockelements SandboxScenery
Example 2: Copyblockelements SandboxScenery 2 1
Usage: Copy the contents of tagblocks. To be used with PasteBlockElements. and use PasteBlockElements. You can also specify the tagblocks count and the start index.
Usage: Copy the contents of one tagblock and to paste it into another tagblock or another tag using the Pasteblockelements command.

Command: PasteBlockElements
Example: Pasteblockelements Sandboxteleporters
Usage: Used with the Copyblockelements command. Paste the previously copied tagblocks. Works only with the same tagblocks (by name). Works between tags.

Command: ForEach
Example 1: ForEach ShaderMaps ListFields
Example 2: ForEach SandboxScenery SetField Name null
Example 3: ForEach ShaderProperties ForEach ShaderMaps ListFields
Example 4: ForEach ShaderProperties ForEach ShaderMaps ListFields Bitmap
Example 5: ForEach ShaderProperties ForEach ShaderMaps SetField Bitmap objects\bitmaps\default\grid_256x256.bitmap
Usage: Loop trough every tagblock and execute the command. You can also chain them as in Example 4, to loop trough every tagblock and all its sub tagblocks. For example 5, it'll set all textures to grid_256.

Command: SaveTagChanges
Usage: Save all current changes to tags.dat. Only required once per EditTag.

Command: Exit
Usage: Quit "EditTag" or go to the parent tagblock (when using EditBlock). This will not save the changes.

Command: ExitTo tags
Usage: If you used EditBlock multiple times, this returns to root TagTool.

// Model importing
Note: This command becomes avaliable to the user after using edittag on a mode/render_model tag.
Command: replacerendergeometry <yourObject.dae>
Usage: Export the mesh you wish to import as a dae file from your 3D modeling application. The objects in your list must be named (region)_(permutation)Mesh. Make sure to have this name in the object panel as the importer does not read 
the name from the object list.
Example: replacerendergeometry H3Biped.dae objects\characters\mp_masterchief\mp_masterchief.render_model


// Shaders specific commands:
Command: ListArguments
Usage: Lists the shader’s arguments and their type. Arguments are used to tweak the shader’s behavior, such as reflection strength or color, detail map and bump detail map repetition.

Command: ListBitmaps
Usage: Lists all the bitmaps and their type.

Command: SpecifyBitmaps
Usage: Sets all the textures/bitmaps.
Full Example:
SpecifyBitmaps
bitmaps\myDiffuse.bitm
bitmaps\myDetailMap.bitm
bitmaps\myBumpMap.bitm
Exit



// Tag Commands:
Command: DuplicateTag
Example: DuplicateTag 0x101F
Usage: Create a new tag by copying an existing tag. 
Warning: Copied tags such as bitmaps, render models, bsp's, sounds and animations will not copy their raw resource, therefore both the original and the copy will share the same resource reference. Use specific commands to avoid corruption, such as importbitmap, or RenderModelTest.
- For mod making, it's best to duplicate an existing tag such as a shader, and rename it, and edit its arguments or other fields.

Command: CreateTag
Example: CreateTag bitm
Usage: This is used to create a new empty tag with the specified class/group. It's best to use DuplicateTag when making mods. Reserve CreateTag for new bitm, mode, snd!, cfgt (smallest tag, import any tag over it to change it to any class)

Command: NameTag
Example: NameTag 0x101F shaders\invalid
Example 2: NameTag * shaders\myShader
Usage: This is used to name tags and can be used with Assembly. For example 2, * means the last tag index.  So if you created a bitmap, such as the example above, myShader will be the name of the newly created tag.

Command: SaveTagNames
Example: SaveTagNames
Usage: Use this command to save the newly added tag names to tag_list.csv using NameTag.

Command: TagDependency
Example 1: TagDependency list objects\characters\masterchief\mp_masterchief\mp_masterchief.model
Usage: In Halo Online, the tag dependency list will show all the tags loaded trough the specified tag. The above example will list mp_masterchief.render_model and a few other tags.
WARNING: if the host loads new tags such as vehicles, joining clients will crash if they don't have the same tags. This does not apply to tags such as shaders.

Example 2: TagDependency liston objects\characters\masterchief\mp_masterchief\mp_masterchief.render_model
This will show the parent tag which loads the specified tag, in this case the result for this example is objects\characters\masterchief\mp_masterchief\mp_masterchief.model

Example 3: TagDependency add objects\characters\masterchief\mp_masterchief\mp_masterchief.model objects\characters\masterchief\mp_masterchief\mp_masterchief.render_model
This will make mp_masterchief.model also load mp_masterchief.render_model. objects\characters\masterchief\mp_masterchief\mp_masterchief.model.

Note: SetField command automatically sets tag dependencies.



// Strings Commands
Command: ListAllStrings
Example 1: ListAllStrings English
Example 2: ListAllStrings English falling
Usage: Display all strings and in which unic tag they are. Argument is used to filter them.

Command: SetString (under EditTag)
Example 1: Changing stringid's such as the fall to death message:
edittag multiplayer\in_game_multiplayer_messages.multilingual_unicode_string_list
SetString english gen_killed_by_falling_effect_player "What about gravity?"
savetagchanges



// Model extraction
Command: edittag on a hlmt tag, followed by the ExtractModel command.
Usage: ExtractModel <variant> <filetype> <filename>
Example for objects\characters\masterchief\mp_masterchief\mp_masterchief (0x1348) which is the base player body:
edittag objects\characters\masterchief\mp_masterchief\mp_masterchief.model
ExtractModel default obj mp_masterchief.obj



// Textures extraction
Command: edittag on a hlmt tag, followed by the ExtractBitmaps command.
Example for 0x1348 which is the base player body.
ExtractBitmaps 0x1348
Press y to confirm folder creation if required.



// Import texture
Command: edittag and importbitmap
Example:
EditTag shaders\invalid.shader
importbitmap resources_b 0 newTexture.dds
savetagchanges
exit



// Extract/import tags
Usage: Extract or import tags. It does not extract new stringids or resources. Use CreateTag to create a new tag first if you don't want to replace an existent tag.
ExtractTag shaders\invalid.shader invalid.rmsh
ImportTag shaders\invalid.shader invalid.rmsh
ImportTag shaders\invalid.shader modifiedTags/invalid.rmsh



// Extract a sound file, fp_sniper rifle as example:
edittag 0x1FC9
resourcedata extract sniper_rifle.mp3