Objects

Usage

import { ObjectsTranslator } from 'wc3maptranslator';
var result = Translator.ObjectsTranslator.jsonToWar(Translator.ObjectsTranslator.ObjectType.Units, { original: { ... }, custom: { ... } });
// Now you can write result.buffer to a war3map file (w3a,w3h,w3b,w3d,w3t,w3u,w3q)

// The first argument to ObjectsTranslator is a string specifying the type of object data (use Translator.ObjectsTranslator.ObjectType.*):
type: 'units' | 'items' | 'destructables' | 'doodads' | 'abilities' | 'buffs' | 'upgrades'

Specification

{
    original: {
        <ObjId>: [
            {
              // Required for all mods
              id: <FieldId>,
              type: 'int' | 'real' | 'unreal' | 'string',
              value: <Value>,
              
              // Use as needed
              column: 0, // for 'Abilities': 0 = unused, 1 = A, 2 = B, ...
              level: 2 // for abilities, doodads, and upgrades
            },
            ... etc.
        ]
    },
    custom: {
        <NewId:OrigId>: [
            // Same format as original object above
        ]
    }
}

Examples

Units - Modify original footman and create a custom unit

{
    "original": {
        "hfoo": [ // modifies the human footman in the object editor
            { "id": "umvs", "value": 500 }, // e.g. custom movement speed
            { "id": "umpr", "type": "unreal", "value": 452.14 }, // e.g. custom mana regen
            { "id": "ua1b", "type": "int", "value": 77 } // e.g. custom base attack damage
        ]
    },
    "custom": {
        "h000:hfoo": [ // creates a new unit based off the footman, with some modified fields
            { "id": "ua1b", "type": "int", "value": 13 }, // e.g. base attack dmg is 13
            { "id": "uhpm", "value": 999 }, // e.g. max hitpoints is 999
            { "id": "utip", "value": "hey there! this is a custom footman, woohoo~" } // e.g. tooltip set to custom string
        ]
    }
}

Abilities - Modify the Holy Light ability's healing value and icon

{
    "original": {
        "AHhb": [
            { "id": "Hhb1", "column": 1, "level": 1, "value": 1200, "type": "unreal" },
            { "id": "Hhb1", "column": 1, "level": 2, "value": 2400, "type": "unreal" },
            { "id": "Hhb1", "column": 1, "level": 3, "value": 3600, "type": "unreal" },
            
            { "id": "aart", "value": "ReplaceableTextures\\CommandButtons\\BTNHowlOfTerror.blp" }
        ]
    },
    "custom": {}
}

Buffs - Modify original avatar, and create custom banish spell

{
    "original": {
        "BHav": [
            { "id": "fnam", "value": "hello world!" }
        ]
    },
    "custom": {
        "B000:BHbn": [
            { "id": "frac", "value": "orc" },
            { "id": "feff", "value": 1 }
        ]
    }
}

Doodads - Modify a fire doodad
Note that the backslashes should be escaped

{
    "original": {},
    "custom": {
        "D000:YOtf": [
            { "id": "dvar", "value": 3 },
            { "id": "dfil", "value": "Doodads\\Outland\\Props\\Grate\\Grate0.mdl"},
            { "id": "dvr1", "value": 125, "variation": 1, "type": "int" }
        ]
    }
}

How do I know which data type to use for modifications?

Some data types are obvious, especially when the value should be text (i.e. use type string). However, how do we know that Holy Light's "amount healed" is an unreal, as opposed to a real or int? For that we need to do some poking around. An example is provided below.

Finding the type of Holy Light's "amount healed" (ability id: AHhb)
Is amount healed an integer, real, or unreal?

1. Find the corresponding entry in WorldEditStrings, located in War3.mpq > UI (you'll need an MPQ editor for this step, e.g. Ladik's MPQ Editor)
2. We see a suspecting WE string for "WESTRING_AEVAL_HHB1=Amount Healed/Damaged", which clearly corresponds with Holy Light's amount healed field, and also the _HHB1 name suggests that this is for the AHhb ability.
3. Find the row in AbilityMetaData.slk where the displayName matches "WESTRING_AEVAL_HHB1". This row contains which type to use. Screenshot posted below.

Discovering the type (unreal) to use for Holy Light's "amount healed" data

This can be an annoying and time-consuming process. We suggest developing this functionality in a higher-level API such as a helper library to look things up. This behavior will not be implemented by WC3MapTranslator due to its low-level API nature.

Notes

• When must I specify type? Can it be optional? The type field is optional for types int or string. In these cases, the type can be inferred from what value you've supplied. However, if your value is of type real or unreal, you must specify type! For example, notice in the Doodads example above how our modification on D000:YOtf to change its dfil path is a string. WC3MapTranslator will notice its a string so will use the string type. For modifying Holy Light, though, we had to specify that our 1200/2400/3600 values were of type unreal. Had we not put a type, the translator would have incorrectly used type int, which may cause errors in WE or in-game.
• How do I find the ids for the fields I want to modify? These ids are in the various ~~MetaData.slk files found in the war3.mpq and war3x.mpq files. Refer to lookup tables for these values.