TonyTools

https://tonytools.win
Admin
TonyTools is a suite of modding and reverse-engineering tools and libraries for the Hitman video...
Tokens:17,506
Snippets:160
Trust Score:5.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### HashList API functions

Source: https://tonytools.win/libraries/hmlanguages

Provides the C++ API for loading and querying the hash list. Includes functions to load from a vector or pointer/size, clear the list, get status, and retrieve LINE hashes or LINE strings. All functions are in the TonyTools::Language::HashList namespace.

```cpp
// All functions and structs below are in the
// TonyTools::Language::HashList namespace.

// Holds the status information about the hash list.
// Returned from the "GetStatus" function.
struct Status {
    bool loaded;
    uint32_t version;
};

// Loads the hash list from a vector comprised
// of the hash list file data.
// Returns if it was successful or not.
bool Load(std::vector<char> data);

// Same as above, but takes a pointer and
// size of the data.
bool Load(const char* ptr, uint32_t size);

// Clears the currently stored hash list.
void Clear();

// Gets the current status of the hash list.
Status GetStatus();

// Gets the LINE hash from a given value.
// Returns the zero-padded, 4-byte, string of the hash,
// or the input if it is not found.
std::string GetLineHash(std::string value);

// Gets the LINE from a given hash.
// Returns the LINE of the hash,
// otherwise the zero-padded, 4-byte, string of the hash.
std::string GetLine(uint32_t hash);
```

--------------------------------

### GetStatus

Source: https://tonytools.win/libraries/hmlanguages

Gets the current status of the hash list, including whether it is loaded and its version.

```APIDOC
## GetStatus

### Description
Gets the current status of the hash list.

### Method
GetStatus

### Parameters
None

### Returns
- **Status** - A struct containing:
  - **loaded** (bool) - Whether the hash list is loaded.
  - **version** (uint32_t) - The version of the hash list.

### Example
```cpp
TonyTools::Language::HashList::Status status = TonyTools::Language::HashList::GetStatus();
```
```

--------------------------------

### GetLine

Source: https://tonytools.win/libraries/hmlanguages

Gets the LINE from a given hash. Returns the LINE of the hash, otherwise the zero-padded, 4-byte string of the hash.

```APIDOC
## GetLine

### Description
Gets the LINE from a given hash. Returns the LINE of the hash, otherwise the zero-padded, 4-byte string of the hash.

### Method
GetLine

### Parameters
#### Input
- **hash** (uint32_t) - Required - The hash to look up.

### Returns
- **std::string** - The LINE string, or the zero-padded, 4-byte string of the hash if not found.

### Example
```cpp
std::string line = TonyTools::Language::HashList::GetLine(hash);
```
```

--------------------------------

### GetLineHash

Source: https://tonytools.win/libraries/hmlanguages

Gets the LINE hash from a given value. Returns the zero-padded, 4-byte string of the hash, or the input if not found.

```APIDOC
## GetLineHash

### Description
Gets the LINE hash from a given value. Returns the zero-padded, 4-byte string of the hash, or the input if it is not found.

### Method
GetLineHash

### Parameters
#### Input
- **value** (std::string) - Required - The value to look up.

### Returns
- **std::string** - The zero-padded, 4-byte string of the hash, or the input if not found.

### Example
```cpp
std::string hash = TonyTools::Language::HashList::GetLineHash(value);
```
```

--------------------------------

### Version Enum

Source: https://tonytools.win/libraries/hmlanguages

Enum class representing supported game versions, used for getting the default language map and handling version-specific quirks.

```APIDOC
## Version Enum

### Description
Enum class representing supported game versions, used for getting the default language map and handling version-specific quirks.

### Definition
```cpp
// This is in the TonyTools::Language namespace
enum class Version : uint8_t
{
    H2016 = 2,
    H2,
    H3
};
```

### Values
- **H2016** (uint8_t) - Value 2, represents Hitman 2016.
- **H2** (uint8_t) - Value 3, represents Hitman 2.
- **H3** (uint8_t) - Value 4, represents Hitman 3.
```

--------------------------------

### GFXFzip usage help

Source: https://tonytools.win/tools/gfxfzip

Displays the command-line usage, positional arguments, and optional flags for GFXFzip.

```text
usage: GFXFzip [--metapath path] [--folder] mode game input_path output_path

positional arguments:
    mode            the mode to use: convert or rebuild.
    game            the version of the game to convert/rebuild from/to:
                        H2016, H2, or H3
    input_path      path to the input file
    output_path     path to the output file (or folder if using --folder)

optional arguments:
    --metapath      input/output path for the .meta.JSON (RPKG Tool!)
    --folder        if the output_path is set to a folder.
                        should be used if ther output hash is unknown
```

--------------------------------

### HMLanguageTools usage help

Source: https://tonytools.win/tools/hmlanguagetools

Displays the full command-line interface usage, including positional arguments for mode, game, and file type, as well as available optional flags.

```text
usage: HMLanguageTools [--metapath path] [--langmap map]
    [--defaultlocale locale] [--hexprecision] [--symmetric]
    mode game type input_path output_path

positional arguments:
    mode            the mode to use: convert or rebuild.
    game            the version of the game to convert/rebuild from/to:
                        H2016, H2, or H3
    type            the type of the file:
                        CLNG, DITL, DLGE, LOCR, or RTLV
    input_path      path to the input file
    output_path     path to the output file

optional arguments:
    --metapath      input/output path for the .meta.JSON (RPKG Tool!)
    --langmap       custom language map, overrides the one provided by version:
                        e.g. xx,en,fr,it,de,es
    --defaultlocale the default audio locale, used for DLGE conversion
                        and rebuilding. default: en
    --hexprecision  use this option if random weights should be output as their
                        hex variants allowing for greater precision,
                        used for DLGE convert only
    --symmetric     if a symmetric cipher should be used, early H2016 LOCR only.
```

--------------------------------

### MATE command-line usage

Source: https://tonytools.win/tools/mate

Shows the command-line usage for the MATE tool. The tool accepts a positional argument 'file' which is the path to a MATE file or a folder of them.

```text
usage: MATE file

positional arguments:
    file    path to a MATE file (or a folder of them).
```

--------------------------------

### JSONPatchCreator usage syntax

Source: https://tonytools.win/tools/jsonpatchcreator

Displays the command-line arguments required to run the tool, including paths for the original file, modified file, and the output destination.

```text
usage: JSONPatchCreator original modified output

positional arguments:
    original    path to the original JSON file.
    modified    path to the modified JSON file.
    output      path to output the JSON patch to.
```

--------------------------------

### VTXD usage command

Source: https://tonytools.win/tools/vtxd

Shows the command-line usage for the VTXD tool. It accepts a single positional argument 'file' which is the path to the VTXD file.

```text
usage: VTXD file

positional arguments:
    file    path to the VTXD file.
```

--------------------------------

### HMTextureTools CLI Usage

Source: https://tonytools.win/tools/hmtexturetools

Displays the full command-line usage, arguments, and options for HMTextureTools.

```text
usage: HMTextureTools [--texd path] [--port game] [--rebuildboth]
    [--texdoutput path] [--istexd] [--metapath path] [--ps4swizzle]
    mode game texture output_path

positional arguments:
    mode                the mode to use: convert or rebuild.
    game                the version of the game the texture(s) are from:
                            HMA, H2016, H2, or H3
    texture             path to the texture. convert requires TEXT/D, rebuild
                            requires a TGA. (For H3, pass a TEXT).
    output_path         the path to the output file.

optional arguments:
    --texd <path>       path to the input TEXD, H3 only, does nothing for 
                            rebuild or other games.
    -p, --port <game>   the game to port to, HMA is unsupported. convert only.
    --rebuildboth       use this option for the input TGA to be downscaled to
                            make a TEXT and TEXD. rebuild only.
    --texdoutput <path> path where the TEXD should be output. H3 only.
    --istexd            use this option when the input texture is a TEXD.
                            (H2016/2 only, rebuilding overrides this).
    --metapath <path>   path to use for inputting/outputting the meta.
    --ps4swizzle        use this option if you want to deswizzle/swizzle
                            textures (porting will only deswizzle).
```

--------------------------------

### Include TonyTools in a CMake project

Source: https://tonytools.win/general/installation

Use FetchContent to include TonyTools in your CMake project and link against HMLanguages.

```cmake
cmake_minimum_required(VERSION 3.25.0)
include(FetchContent)

project(MyProject)

set(TONYTOOLS_BUILD_TOOLS OFF)
FetchContent_Declare(tonytools
    GIT_REPOSITORY  https://github.com/AnthonyFuller/TonyTools.git
    GIT_TAG         v1.8.2
)

FetchContent_MakeAvailable(tonytools)

add_executable(MyExe
    src/main.cpp
)

add_dependencies(MyExe TonyTools::HMLanguages)
target_link_libraries(MyExe TonyTools::HMLanguages)
```

--------------------------------

### MJBATesting CLI usage

Source: https://tonytools.win/tools/mjbatesting

Command-line usage for MJBATesting. Takes one positional argument, file, which is the path to the stripped MJBA file. The tool is not intended for general use and may be removed in the future.

```text
usage: MJBATesting file

positional arguments:
    file    path to the stripped MJBA file.

```

--------------------------------

### Load

Source: https://tonytools.win/libraries/hmlanguages

Loads the hash list from a vector of file data or from a pointer and size. Returns true if successful.

```APIDOC
## Load

### Description
Loads the hash list from a vector comprised of the hash list file data. Returns if it was successful or not.

### Method
Load

### Parameters
#### Input
- **data** (std::vector<char>) - Required - The hash list file data.

### Returns
- **bool** - True if the load was successful, false otherwise.

### Example
```cpp
bool success = TonyTools::Language::HashList::Load(data);
```
```

```APIDOC
## Load (pointer version)

### Description
Loads the hash list from a pointer and size of the data. Returns if it was successful or not.

### Method
Load

### Parameters
#### Input
- **ptr** (const char*) - Required - Pointer to the hash list data.
- **size** (uint32_t) - Required - Size of the data in bytes.

### Returns
- **bool** - True if the load was successful, false otherwise.

### Example
```cpp
bool success = TonyTools::Language::HashList::Load(ptr, size);
```
```

--------------------------------

### Rebuild zip to GFXF

Source: https://tonytools.win/tools/gfxfzip

Command to rebuild a zip file into GFXF format. The tool outputs a .meta.JSON file alongside the GFXF file.

```bash
GFXFzip rebuild <game> <input file path> <output file path>
```

--------------------------------

### BOXCExporter command-line usage

Source: https://tonytools.win/tools/boxcexporter

Shows the command-line syntax for BOXCExporter. It requires a mode (convert or rebuild), a BOXC file path, and an output folder. Use --noconvert to skip texture conversion to TGA.

```text
usage: BOXCExporter [--noconvert] mode boxc output_path

positional arguments:
    mode            the mode to use: convert or rebuild.
    boxc            path to the BOXC file.
    output_path     path to the output folder.

optional arguments:
    --noconvert     use this option to skip converting textures to TGA.
```

--------------------------------

### SCDA command-line usage

Source: https://tonytools.win/tools/scda

Shows the command-line usage for the SCDA tool. The tool takes a single positional argument 'file' which is the path to the SCDA file.

```text
usage: SCDA file

positional arguments:
    file    path to the SCDA file.
```

--------------------------------

### Handling Rebuild Return Values

Source: https://tonytools.win/libraries/hmlanguages

When rebuilding fails, the library outputs an error to stderr and returns an empty struct. Check for empty file or meta members to detect failure.

```cpp
TonyTools::Language::Rebuilt rebuilt = ...;

if (rebuilt.file.empty() || rebuilt.meta.empty())
    // do something
```

--------------------------------

### Convert file to JSON

Source: https://tonytools.win/tools/hmlanguagetools

Converts a game resource file to JSON format. Use the --metapath option to specify a custom meta file path and --hexprecision for DLGE random container weight accuracy.

```bash
HMLanguageTools convert <game> <type> <input file path> <output file path>
```

--------------------------------

### Convert GFXF to zip

Source: https://tonytools.win/tools/gfxfzip

Command to convert a GFXF file to a zip archive. The command assumes a corresponding .meta.JSON file exists at the input path unless specified via --metapath.

```bash
GFXFzip convert <game> <input file path> <output file path>
```

--------------------------------

### HMAScrambler usage command

Source: https://tonytools.win/tools/hmascrambler

Shows the command-line usage for HMAScrambler. The tool takes a single file argument and converts based on its extension.

```text
usage: HMAScrambler file

positional arguments:
    file    File to run the tool on, if the extension is `.scrambled`,
                it will convert it to `.ini` and vice-versa.
```

--------------------------------

### Handling Conversion Return Values

Source: https://tonytools.win/libraries/hmlanguages

Functions converting raw files to HML JSON strings return a std::string. An empty string indicates a failure, which is also logged to stderr.

```cpp
std::string converted = ...;

if (converted.empty())
    // do something
```

--------------------------------

### HashList binary format structures

Source: https://tonytools.win/libraries/hmlanguages

Defines the binary format for the hash list file, including the main HashList struct with magic, version, checksum, and sections for soundtags, cases, and lines. The HashListSection and HashListEntry structs define the section layout and entry format, storing the CRC32 hash and original string.

```cpp
// This is the main file
struct HashList {
    uint32_t            magic;      // 0x484D4C41 'ALMH'
    uint32_t            version;    // Hash list version
    uint32_t            checksum;   // CRC32 checksum of the rest of the data
    HashListSection     soundtags;  // Soundtags
    HashListSection     cases;      // Switch cases
    HashListSection     lines;      // LINE hashes
}

struct HashListSection {
    uint32_t        nEntries;           // Number of entries
    HashListEntry   entries[nEntries];  // The actual entries
}

// We store the hash so we don't have to calculate this
// when loading the hash list for speed.
struct HashListEntry {
    uint32_t    hash;   // The CRC32 hash
    const char* string; // The original string (null terminated)
}
```

--------------------------------

### Rebuild Hitman 3 TGA to TEXT and TEXD

Source: https://tonytools.win/tools/hmtexturetools

Rebuilds a TGA file into TEXT and TEXD formats.

```bash
HMTextureTools rebuild H3 <path to TGA> <path to TEXT> --rebuildboth \
    --texdoutput <path to TEXD>
```

--------------------------------

### Rebuild JSON to raw file

Source: https://tonytools.win/tools/hmlanguagetools

Rebuilds a JSON file back into its original raw format. The tool automatically generates a .meta.JSON file, which can be customized using the --metapath option.

```bash
HMLanguageTools rebuild <game> <type> <input json path> <output file path>
```

--------------------------------

### RTLV::Rebuild

Source: https://tonytools.win/libraries/hmlanguages

Rebuilds RTLV and meta.json from a JSON string. The game version is used for ResourceLib and language map resolution.

```APIDOC
## Rebuild

### Description
Rebuilds RTLV and meta.json from a JSON string. The game version is used for ResourceLib and language map resolution.

### Method
Rebuild

### Parameters
- **version** (Language::Version) - Required - The game version, passed to ResourceLib and used for language map resolution.
- **jsonString** (std::string) - Required - The HML JSON string.
- **langMap** (std::string) - Optional - An optional language map.

### Returns
- **TonyTools::Language::Rebuilt** - The rebuilt RTLV and meta.json data.

### Example
```cpp
TonyTools::Language::Rebuilt rebuild =
    TonyTools::Langauge::RTLV::Rebuild(
        Language::Version version,
        std::string jsonString,
        std::string langMap = ""
    );
```
```

--------------------------------

### Convert Hitman 3 TEXT to TGA

Source: https://tonytools.win/tools/hmtexturetools

Converts a TEXT file to TGA, optionally including a TEXD file.

```bash
HMTextureTools convert H3 <path to TEXT> <path to TGA> --texd <path to TEXD>
```

--------------------------------

### Conversion Return Values

Source: https://tonytools.win/libraries/hmlanguages

Functions that convert a raw file + .meta.json to a HML JSON string return std::string. On failure, an error is output to stderr and an empty string is returned.

```APIDOC
## Conversion Return Values

### Description
Functions that convert a raw file + .meta.json to a HML JSON string return std::string. On failure, an error is output to stderr and an empty string is returned.

### Return Type
- **std::string** - The HML JSON string on success, empty string on failure.

### Error Handling
If the library fails to convert a file, an error will be output to stderr and the function will return an empty string.

### Example
```cpp
std::string converted = ...;

if (converted.empty())
    // do something
```
```

--------------------------------

### Rebuild Hitman 2016/2 TGA to TEXT and TEXD

Source: https://tonytools.win/tools/hmtexturetools

Rebuilds a TGA file into TEXT and TEXD formats for Hitman 2016 or Hitman 2.

```bash
HMTextureTools rebuild {H2016|H2} <path to TGA> <path to TEXT> \
    --texdoutput <path to TEXD> --rebuildboth
```

--------------------------------

### DLGE C++ API Methods

Source: https://tonytools.win/libraries/hmlanguages

Methods for converting DLGE data to JSON and rebuilding JSON back into DLGE format.

```cpp
// DLGE + meta.json -> DLGE
std::string json = TonyTools::Language::DLGE::Convert(
    Language::Version version,              // game version
    std::vector<char> data,                 // raw DLGE data
    std::string metaJson,                   // .meta.json string
    std::string defaultLocale = "en",       // optional default locale
    bool hexPrecision = false,              // should random weights be
                                            //   output as hex?
    std::string langMap = ""                // optional language map
                                            //   (must be exact!)
);

// JSON -> DLGE + meta.json
TonyTools::Language::Rebuilt rebuild =
    TonyTools::Langauge::DLGE::Rebuild(
        Language::Version version,          // game version
        std::string jsonString,             // HML JSON string
        std::string defaultLocale = "en",   // optional default locale
        std::string langMap = ""            // optional language map
                                            //   (must be exact!)
    );
```

--------------------------------

### Convert Hitman 2016/2 TEXD to TGA

Source: https://tonytools.win/tools/hmtexturetools

Converts a TEXD file to TGA for Hitman 2016 or Hitman 2.

```bash
HMTextureTools convert {H2016|H2} <path to TEXD> <path to TGA> --istexd
```

--------------------------------

### Clear

Source: https://tonytools.win/libraries/hmlanguages

Clears the currently stored hash list.

```APIDOC
## Clear

### Description
Clears the currently stored hash list.

### Method
Clear

### Parameters
None

### Returns
None

### Example
```cpp
TonyTools::Language::HashList::Clear();
```
```

--------------------------------

### DITL Conversion and Rebuild API

Source: https://tonytools.win/libraries/hmlanguages

Methods for converting DITL data to JSON and rebuilding JSON back into DITL format. This format does not require a version parameter.

```cpp
// DITL + meta.json -> JSON
std::string json = TonyTools::Language::DITL::Convert(
    std::vector<char> data,     // raw CLNG data
    std::string metaJson        // .meta.json string
);

// JSON -> DITL + meta.json
TonyTools::Language::Rebuilt rebuild =
    TonyTools::Langauge::DITL::Rebuild(
        std::string jsonString  // HML JSON string
    );
```

--------------------------------

### RTLV::Convert

Source: https://tonytools.win/libraries/hmlanguages

Converts RTLV data and meta.json into a JSON string. The game version is passed to ResourceLib for proper conversion.

```APIDOC
## Convert

### Description
Converts raw RTLV data and meta.json into a JSON string. The game version is passed to ResourceLib for proper conversion.

### Method
Convert

### Parameters
- **version** (Language::Version) - Required - The game version, passed to ResourceLib.
- **data** (std::vector<char>) - Required - Raw RTLV data.
- **metaJson** (std::string) - Required - The .meta.json string.

### Returns
- **std::string** - The converted JSON string.

### Example
```cpp
std::string json = TonyTools::Language::RTLV::Convert(
    Language::Version version,
    std::vector<char> data,
    std::string metaJson
);
```
```

--------------------------------

### RTLV Conversion and Rebuild API

Source: https://tonytools.win/libraries/hmlanguages

C++ functions for converting RTLV data to JSON and rebuilding JSON back into RTLV format. Note that game versioning is required for both operations, and language map resolution is performed during rebuild.

```cpp
// RTLV + meta.json -> JSON
std::string json = TonyTools::Language::RTLV::Convert(
    Language::Version version,      // game version
    std::vector<char> data,         // raw RTLV json
    std::string metaJson            // .meta.json string
);

// JSON -> RTLV + meta.json
TonyTools::Language::Rebuilt rebuild =
    TonyTools::Langauge::RTLV::Rebuild(
        Language::Version version,  // game version
        std::string jsonString,     // HML JSON string
        std::string langMap = ""    // optional language map
    );
```

--------------------------------

### CLNG Conversion and Rebuild API

Source: https://tonytools.win/libraries/hmlanguages

Methods for converting CLNG data to JSON and rebuilding JSON back into CLNG format.

```cpp
// CLNG + meta.json -> JSON
std::string json = TonyTools::Language::CLNG::Convert(
    Language::Version version,  // game version
    std::vector<char> data,     // raw CLNG data
    std::string metaJson,       // .meta.json string
    std::string langMap = ""    // optional custom langmap
);

// JSON -> CLNG + meta.json
TonyTools::Language::Rebuilt rebuild =
    TonyTools::Langauge::CLNG::Rebuild(
        std::string jsonString  // HML JSON string
    );
```

--------------------------------

### Rebuild Return Values

Source: https://tonytools.win/libraries/hmlanguages

Functions that rebuild a HML JSON string to the raw file + .meta.json return a Rebuilt struct. On failure, an error is output to stderr and an empty struct is returned.

```APIDOC
## Rebuild Return Values

### Description
Functions that rebuild a HML JSON string to the raw file + .meta.json return a Rebuilt struct. On failure, an error is output to stderr and an empty struct is returned.

### Return Type
- **TonyTools::Language::Rebuilt** - Contains the raw file bytes and the JSON string of the .meta.json.

### Struct Definition
```cpp
// This is in the TonyTools::Language namespace
struct Rebuilt
{
    std::vector<char> file; // contains the raw file bytes
    std::string meta;       // contains the JSON string of the .meta.json
};
```

### Error Handling
If the library fails to rebuild a file, an error will be output to stderr and an empty struct will be returned.

### Example
```cpp
TonyTools::Language::Rebuilt rebuilt = ...;

if (rebuilt.file.empty() || rebuilt.meta.empty())
    // do something
```
```

--------------------------------

### DLGE::Rebuild

Source: https://tonytools.win/libraries/hmlanguages

Rebuilds DLGE data and meta.json from a JSON string. This function is used to convert JSON back into the binary DLGE format.

```APIDOC
## DLGE::Rebuild

### Description
Rebuilds DLGE data and meta.json from a JSON string. This function is used to convert JSON back into the binary DLGE format.

### Method
C++ function

### Signature
TonyTools::Language::Rebuilt rebuild = TonyTools::Language::DLGE::Rebuild(
    Language::Version version,
    std::string jsonString,
    std::string defaultLocale = "en",
    std::string langMap = ""
);

### Parameters
- **version** (Language::Version) - Required - Game version.
- **jsonString** (std::string) - Required - HML JSON string.
- **defaultLocale** (std::string) - Optional - Default locale, defaults to "en".
- **langMap** (std::string) - Optional - Language map (must be exact), defaults to empty string.

### Returns
- **TonyTools::Language::Rebuilt** - Rebuilt DLGE data and meta.json.

```

--------------------------------

### DITL JSON Representation

Source: https://tonytools.win/libraries/hmlanguages

The JSON structure for DITL files, mapping soundtags to Wwise Event hashes.

```json
{
    "hash": "...",
    "soundtags": {
        "In-world_AI_Important": "...",
        "In-world_AI_Normal": "...",
        ...
    }
}
```

--------------------------------

### WavFile JSON Structure

Source: https://tonytools.win/libraries/hmlanguages

The JSON representation of a WavFile container. All fields are required unless otherwise specified, and the type must be set to 'WavFile'.

```json
{
    "type": "WavFile",        // important, cannot differ from this
    "wavName": "...",         // CRC32 of the "wav name", retrieved from the
                              //    path, otherwise it is the hash in hex
    "cases": [...],           // array of switch cases, see the Switch section
    "weight": ...,            // a decimal (or hexadecimal string) random weight
                              //    see the Random section
    "soundtag": "...",        // soundtag name (or hash in hex)
    "defaultWav": "...",      // the path of the "default" wav (usually english)
    "defaultFfx": "...",      // like defaultWav, but for the FaceFX animation
    "languages": {            // this can be empty or be missing languages
                              //   (i.e. xx)
        "en": "...",          // subtitle for this language
        ...
        "jp": {               // this is optional, IOI use this in H2016
            "wav": "...",     // required, the path of the wav for thislanguage
            "ffx": "...",     // required, the path of the FaceFX animation for
                              //   this language
            "subtitle": "..." // optional, subtitle for this language
        }
    }
}
```

--------------------------------

### Switch Container JSON Representation

Source: https://tonytools.win/libraries/hmlanguages

The JSON structure for a Switch container, which uses a switchKey to reference cases and includes a default fallback property.

```json
{
    "type": "Switch",
    "switchKey": "AI_Sentry_ItemRequest",
    "default": "INVITE",
    "containers": [
        {
            "type": "Random",
            "cases": [
                "INVITE"        // although this is an array, it's perfectly
                                //   fine (and normal) to just have one
            ],
            ...
        },
        {
            "type": "WavFile",
            "cases": [
                "TICKET",       // but you can have more than one
                "VIPTICKET"
            ],
            ...
        }
    ]
}
```

--------------------------------

### Sequence Container JSON Representation

Source: https://tonytools.win/libraries/hmlanguages

The JSON structure for a Sequence container, which acts as a root container to house and play other containers in a specific order.

```json
{
    "type": "Sequence",
    "containers": [
        {
            "type": "Random",
            ...
        },
        {
            "type": "Switch",
            ...
        },
        {
            "type": "WavFile",
            ...
        }
    ]
}
```

--------------------------------

### DLGE JSON Schema Representation

Source: https://tonytools.win/libraries/hmlanguages

The JSON structure for DLGE files, featuring a root container with sequence, random, switch, and wav file types.

```json
{
    "hash": "...",
    "DITL": "...",      // the hash where soundtags will be resolved
    "CLNG": "...",      // the hash for the CLNG file, the default one
                        //   in chunk0 should really be used
    "rootContainer": {
        "type": "Sequence",
        "containers": [
            {
                "type": "Random",
                ...
            },
            {
                "type": "Switch",
                ...
            },
            {
                "type": "WavFile",
                ...
            }
        ]
    }
}
```

--------------------------------

### Random Container JSON Structure

Source: https://tonytools.win/libraries/hmlanguages

The JSON representation of a Random container, demonstrating both decimal and hexadecimal weight representations.

```json
{
    "type": "Random",
    "cases": [...],             // this only occurs when it is
                                //   a child of a Switch container
    "containers": [
        {
            "type": "WavFile",
            ...
            "weight": 0.25,
            ...
        },
        {
            "type": "WavFile",
            ...
            "weight": "3FFFFF", // this is a 1 in 4 chance
            ...
        }
        {
            "type": "WavFile",
            ...
            "weight": 0.5,
            ...
        }
    ]
}
```

--------------------------------

### DLGE::Convert

Source: https://tonytools.win/libraries/hmlanguages

Converts raw DLGE data and meta.json to a JSON string. This function is used to parse DLGE files into a human-readable JSON representation.

```APIDOC
## DLGE::Convert

### Description
Converts raw DLGE data and meta.json to a JSON string. This function is used to parse DLGE files into a human-readable JSON representation.

### Method
C++ function

### Signature
std::string json = TonyTools::Language::DLGE::Convert(
    Language::Version version,
    std::vector<char> data,
    std::string metaJson,
    std::string defaultLocale = "en",
    bool hexPrecision = false,
    std::string langMap = ""
);

### Parameters
- **version** (Language::Version) - Required - Game version.
- **data** (std::vector<char>) - Required - Raw DLGE data.
- **metaJson** (std::string) - Required - .meta.json string.
- **defaultLocale** (std::string) - Optional - Default locale, defaults to "en".
- **hexPrecision** (bool) - Optional - Whether random weights should be output as hex, defaults to false.
- **langMap** (std::string) - Optional - Language map (must be exact), defaults to empty string.

### Returns
- **std::string** - JSON representation of the DLGE data.

```

--------------------------------

### LOCR C++ API Methods

Source: https://tonytools.win/libraries/hmlanguages

Methods for converting LOCR data to JSON and rebuilding JSON back into LOCR format. The symmetric parameter is used to handle different ciphers, particularly for early H2016 files.

```cpp
// LOCR + meta.json -> JSON
std::string json = TonyTools::Language::LOCR::Convert(
    Language::Version version,      // game version
    std::vector<char> data,         // raw LOCR data
    std::string metaJson,           // .meta.json string
    std::string langMap = "",       // optional language map
    bool symmetric = false          // whether a symmetric cipher should
                                    //   be used 
);

// JSON -> LOCR + meta.json
TonyTools::Language::Rebuilt rebuild =
    TonyTools::Langauge::LOCR::Rebuild(
        Language::Version version,  // game version
        std::string jsonString,     // HML JSON string
        bool symmetric = false      // whether a symmetric cipher should
                                    //   be used
    );
```
Tokens:
Raw