Heroes 5 Wiki

New Dwelling Framework (NDF) is additional module for Heroes V ToE that allows increasing the total amount of dwelling buildings on the adventure map.

Credit:

  • JonnyP - Original Adv. Map objects
  • Waterfall - 3D advice, Haven T6 dwelling replacement model.
  • dredknight - redesign of all models, new effects for each dwelling, hex changes.

Features[]

Current state of NDWF increase dwelling count from 4 per faction to 8 per faction, where the 4 new additions are a unique dwelling for tiers 4 to 7. Original faction Military posts tier changed from Tier 4 to Tier 8.

Architecture[]

Bringing NDWF to existing is possible through EXE edits and technical implementations in the data.pak files shown below.

  • Red background - core file, necessary changes
  • White background - core file, optional or no changes

Configuration loaded during .exe runtime.

H5 New DWelling Framework architecture

Dwelling placement is done in two different ways by the game:

  • Specific Dwelling - Used when a RMG map is generated with "Random Towns" feature off. During that process the game predefines specific map faction for each town location. A map is generated in that manner if player faction choice is disabled and the faction is predetermined in the lobby. During map generation the following set of actions are taken in regards to dwelling placement.
    • Map Generation
      • If zone has town, game selects a faction for that town.
      • If that zone will also have dwellings (configured in RMG/Templates/<template_name>.xdb) game goes to GameMechanics/RefTables/RMGPreset.xdb finds the proper faction item and gets all available dwellings for the faction from <Dwellings> xml array.
        • Then dwellings are placed where each dwelling building depends on recruitment creature tier defined for the zone in RMG/Templates/<template_name>.xdb. The following properties are valid for the placement.
          • For Template Tier 1 creature recruitment Tier 1 Faction dwelling is placed, providing Tier 1 units for recruitment
          • For Template Tier 2 creature recruitment Tier 2 Faction dwelling is placed, providing Tier 2 units for recruitment
          • For Template Tier 3 creature recruitment Tier 3 Faction dwelling is placed, providing Tier 3 units for recruitment
          • For Template Tier 4 creature recruitment Tier 4 Faction dwelling is placed, providing Tier 4 units for recruitment (first creature in Custom Array)
          • For Template Tier 5 creature recruitment Tier 4 Faction dwelling is placed, providing Tier 5 units for recruitment (second creature in Custom Array)
          • For Template Tier 6 creature recruitment Tier 4 Faction dwelling is placed, providing Tier 6 units for recruitment (third creature in Custom Array)
          • For Template Tier 7 creature recruitment Tier 4 Faction dwelling is placed, providing Tier 7 units for recruitment (forth creature in Custom Array)
  • Random dwelling - Used when a RMG map is generated with "Random Towns" feature on. During that process the game uses a dummy random faction for each town location. A map is generated in that manner if player faction choice is enabled in the lobby, the player can choose any faction he wishes including random. Map town and dwelling objects are set during game initialization. During map generation and initialization the following set of actions are taken in regards to dwelling placement.
    • Map Generation
      • If zone has town, game sets a dummy random town object.
      • If that zone will have dwellings game sets a dummy random dwelling object linked to the town object so during game runtime they will always be of the same faction. The following pattern is kept during dummy random dwelling placement:
        • For Template Tier 1 creature recruitment Tier 1 Random dwelling is placed
        • For Template Tier 2 creature recruitment Tier 2 Random dwelling is placed
        • For Template Tier 3 creature recruitment Tier 3 Random dwelling is placed
        • For Template Tier 4 creature recruitment Tier 4 Random dwelling is placed
        • For Template Tier 5 creature recruitment Tier 5 Random dwelling is placed
        • For Template Tier 6 creature recruitment Tier 6 Random dwelling is placed
        • For Template Tier 7 creature recruitment Tier 7 Random dwelling is placed
    • Map Initialization
      • As the game is started on the map, for each zone with random town and dwelling placeholder objects the game:
        • if this is starting zone that has an active player - the faction chosen by the player is set for the town and all dwellings
        • If this is not a starting zone - a random faction is chosen that is set for the town and all dwellings.
      • Every random town object is replaced by the chosen faction town object.
      • Every random dwelling object is replaced by dwelling building from the chosen faction (from /MapObjects/_(AdvMapSharedGroup)/*/<Faction>.xdb) based on the creature recruitment tier of the random dwelling object. The following pattern is used:
        • Tier 1 Random Dwelling is replaced by Tier 1 Faction dwelling providing Tier 1 units for recruitment
        • Tier 2 Random Dwelling is replaced by Tier 2 Faction dwelling providing Tier 2 units for recruitment
        • Tier 3 Random Dwelling is replaced by Tier 3 Faction dwelling providing Tier 3 units for recruitment
        • Tier 4 Random Dwelling is replaced by Tier 4 Faction dwelling providing Tier 4 units for recruitment (first creature in Custom Array)
        • Tier 5 Random Dwelling is replaced by Tier 4 Faction dwelling providing Tier 5 units for recruitment (second creature in Custom Array)
        • Tier 6 Random Dwelling is replaced by Tier 4 Faction dwelling providing Tier 6 units for recruitment (third creature in Custom Array)
        • Tier 7 Random Dwelling is replaced by Tier 4 Faction dwelling providing Tier 7 units for recruitment (forth creature in Custom Array)

LUA commands affiliated with dwelling placement:

  • CreateDwelling() LUA command uses Static dwelling pattern placement.
  • ReplaceDwelling() LUA command swaps faction dwellings by taking the tier of selected dwelling from /MapObjects/_(AdvMapSharedGroup)/*/<selected_dwelling_Faction>.xdb and replace it with target faction dwelling of the same tier from /MapObjects/_(AdvMapSharedGroup)/*/<target_dwelling_Faction>.xdb. It is important to note that dwelling tier depends on the dwelling entry within AdvMapSharedGroup array list. First item is considered tier 1, second - tier 2, third - T3 and so on.

In order more dwellings to be placed we need to make multiple overrides and add additional objects.

Technical implementation[]

This guide goal is to provide step-by-step process creating the framework. The framework change is meant to add 4 new dwelling buildings per faction so this means any author needs either create 32 new dwellings or reduce the number of new dwellings per faction by changing the hex patch. For the purpose of example we will mention one new dwelling building with the following specifications:

  • AdvMapDwellingShared file at this location /MapObjects/Haven/Haven_T4_Post/Haven_T4_Post.xdb
  • Dwelling tier will be set to 4
  • Dwelling faction will be Heaven
  • Dwelling guards will be 4 stacks of Griffins
  • Creature type available for recruitment will be Griffins

H5_Game.exe and H5_MapEditor.exe[]

NDF hex edits[1] will provide the following modifications to the above architecture:

Static dwelling pattern in Map Generation mode is changed to:

  • Tier 1 Random Dwelling is replaced by Tier 1 Faction dwelling providing Tier 1 units for recruitment
  • Tier 2 Random Dwelling is replaced by Tier 2 Faction dwelling providing Tier 2 units for recruitment
  • Tier 3 Random Dwelling is replaced by Tier 3 Faction dwelling providing Tier 3 units for recruitment
  • Tier 4 Random Dwelling is replaced by Tier 4 Faction dwelling providing Tier 4 units for recruitment (first creature in Custom Array)
  • Tier 5 Random Dwelling is replaced by Tier 5 Faction dwelling providing Tier 5 units for recruitment (first creature in Custom Array)
  • Tier 6 Random Dwelling is replaced by Tier 6 Faction dwelling providing Tier 6 units for recruitment (first creature in Custom Array)
  • Tier 7 Random Dwelling is replaced by Tier 7 Faction dwelling providing Tier 7 units for recruitment (first creature in Custom Array)
  • Tier 8 Random Dwelling is replaced by Tier 8 Faction dwelling providing Tier 4 (can be customized) units for recruitment (first creature in Custom Array of T4, T5, T6 and T7)

Random dwelling pattern in Map Initialization mode is changed to:

  • Tier 1 Random Dwelling is replaced by Tier 1 Faction dwelling providing Tier 1 units for recruitment
  • Tier 2 Random Dwelling is replaced by Tier 2 Faction dwelling providing Tier 2 units for recruitment
  • Tier 3 Random Dwelling is replaced by Tier 3 Faction dwelling providing Tier 3 units for recruitment
  • Tier 4 Random Dwelling is replaced by Tier 4 Faction dwelling providing Tier 4 units for recruitment (first creature in Custom Array)
  • Tier 5 Random Dwelling is replaced by Tier 5 Faction dwelling providing Tier 5 units for recruitment (first creature in Custom Array)
  • Tier 6 Random Dwelling is replaced by Tier 6 Faction dwelling providing Tier 6 units for recruitment (first creature in Custom Array)
  • Tier 7 Random Dwelling is replaced by Tier 7 Faction dwelling providing Tier 7 units for recruitment (first creature in Custom Array)

Note: Tier 8 dwelling entries will be disregarded and no random dwellings will be placed during Random dwelling in Map Generation mode

CreateDwelling() LUA command supersedes all changes affecting Static dwelling pattern.

ReplaceDwelling() is not affected by hex changes.

types.xml (optional)[]

Increase NewDwelling array size from 4 to 8. After some tests it seems this value (along with NewDwelling elements in XDB files) is not used at all. We change it for consistency.

GameMechanics\RefTables\RMGPreset.xdb[]

Changes in this file will add new dwellings within the faction ownership array that is used in Specific Dwelling Map Generation step.

  • Go to <Table_RMGPreset_Race><objects>
  • Find <Item> that has ID RACE_HAVEN and add new items for Dwelling and NewDwellings arrays.

Dwelling array[]

  • Inside it find <Dwelling> array and add <Item> element within. For Haven T4 dwelling that will be
<Item href="/MapObjects/Haven/Haven_T4_Post/Haven_T4_Post.xdb#xpointer(/AdvMapDwellingShared)"/>
  • The item structure should be a replica of existing items in the array and point to properly configured AdvMapDwellingShared file (in MapObjects directory) of a new dwelling. Order of the dwelling item in the array represents its tier. Item 1 is tier 1 dwelling, item 2 is tier 2 dwelling and so on. This means our Haven T4 dwelling should be just below the barracks.
  • Repeat this step to fill all 4 dwelling buildings spots for Haven faction.

RMGPreset Dwelling Array

NewDwellings array (optional)[]

  • Find <NewDwellings> array. Its contents are not used by the game or the editor but we will fill them for consistency.
  • Add new <Item> element within. The item structure should be a replica of existing items.
<Item>
	<Building href="/MapObjects/Haven/Haven_T4_Post/Haven_T4_Post.xdb#xpointer(/AdvMapDwellingShared)"/>
	<Value>0</Value>
	<GuardStrenght>0</GuardStrenght>
</Item>
  • Building href pointing to properly configured AdvMapDwellingShared file (in MapObjects directory) of a new dwelling. Dwelling order should be the same as in <Dwellings> array. Not used by the editor.
  • Value - not used by the editor.
  • GuardStrenght - not used by editor.
  • Repeat this step to fill 4 dwellings for each faction so the framework can function.

RMGPreset NewDwelling Array

Note: <NewDwellings> array and any of its values are not actually used by the game. They are updated for consistency.

MapObjects\_(AdvMapSharedGroup)\Dwellings\*.(AdvMapSharedGroup).xdb[]

Changes in this file will add new dwellings within the random faction ownership array that is used in Random Dwelling Map Initialization step. The order of dwelling items in the file represents their tier level. First one is tier 1, second is tier 2 etc..

  • Go to MapObjects/_(AdvMapSharedGroup)/Dwellings
  • Open file Haven.xdb
  • Add the new item after the third one. Below Barracks and above Military_post. It should point to the AdvMapSharedModel of the dwelling.
<Item href="/MapObjects/Haven/Haven_T4_Post/Haven_T4_Post.xdb#xpointer(/AdvMapDwellingShared)"/>
  • Repeat the steps above for all 4 new dwellings for this faction.
  • Repeat the steps above for all Faction files in MapObjects/_(AdvMapSharedGroup)/Dwellings folder.

AdvMapSharedGroup for Haven dwellings1

Create the Dwelling files[]

Each dwelling is a case of Adventure Map Building which is a case of Adventure Map Object. Each such object is defined by AdventureMapShared file that defines all object properties - model, textures, sound, effects, icons, texts and so on. One such object needs to be created for each new dwelling.

AdvMapDwellingShared[]

  • Open /MapObjects/Haven/Haven_T4_Post/Haven_T4_Post.xdb
  • set Blocking Tiles, Active Tiles and Possession Tiles to be the same count and on the same coordinates as tier 4 dwellings of all factions. This should also include the Random Dwelling object found at /MapObjects/Random/RandomDwelling4.xdb. Example tile setup:
    • 8 blocked -1, 1; 0, 1; -1, 0; -1,-1; 0,0; 1,1; 1,-1; 1,0
    • 1 active - 0,-1
    • Possession tile - 0,0

Note: Above is mandatory step to allow ReplaceDwelling() to function properly. If tile setup between same tier dwellings is not aligned it is possible the command to fail if the new dwelling cannot be placed or the dwelling to be replaced but the new dwelling active tile to be missing. Active tile will work only if it is on the same spot as the active tile of the dwelling that is being replaced.

  • set Type to BUILDING_HAVEN_MILITARY_POST where faction id is based on the faction that will own the dwelling
  • in <guards> add 4 new <item> elements of type CREATURE_GRIFFIN
  • in <creatures> add new <item> element of type CREATURE_GRIFFIN
  • set RandomType to DWELLING_TYPE_SPECIFIC
<Type>BUILDING_HEAVEN_MILITARY_POST</Type>
<guards>
	<Item>CREATURE_GRIFFIN</Item>
	<Item>CREATURE_GRIFFIN</Item>
	<Item>CREATURE_GRIFFIN</Item>
	<Item>CREATURE_GRIFFIN</Item>
</guards>
<creatures>
	<Item>CREATURE_GRIFFIN</Item>
</creatures>
<RandomType>DWELLING_TYPE_SPECIFIC</RandomType>

AdvMapDwellingShared for object

Note: Defining AdvMapDwellingShared file contents is not in the scope of this guide. Only what is required for the framework is mentioned.

index.bin (optional)[2][]

Changes in this file will allow the user too see the new dwelling in the Map editor.

  • Open Heroes V editor in game editing mode.[3]
  • From the game database drop down menu select "AdvMapObjectLink" table.
  • A File tree will appear, browse to "MapObjects/_(AdvMapObjectLnk)/Object-Dwellings/Haven" this is where custom creatures will reside.
  • Right click on "Haven -> New Object". This will create the new object link.
  • After that right click on folder NCF -> New Object.

AdvMapObjectLink Dwellings

  • Set a name for the new object, in this case it will be "Haven_T4_Post.(AdvMapObjectLink)" and click OK.
  • Repeat all steps above to create as many dwelling objects as you need.
  • Quit the editor and agree to save changes
  • Go to <game folder>\data, there a number of new elements are present as follow:
    • index.bin file that includes references to all engine AdvMapObjectLink files including the new one that was just added
    • MapObjects folder - that includes the newly created AdvMapObjectLink file for Haven_T4_Post.(AdvMapObjectLink)

MapObjects\_(AdvMapObjectLink)\*\*.(AdvMapObjectLink).xdb (Optional)[]

The newly created AdvMapObjectLink xdb files created from the previous step are found in <game folder>/data/MapObjects/_(AdvMapObjectLink)/Objects-Dwellings/ and are meant to point at AdvMapMonsterShared creature file and IconFile image shown in the Map Editor.

<?xml version="1.0" encoding="UTF-8"?>
<AdvMapObjectLink>
	<Link href="/MapObjects/Haven/Haven_T4_Post/Haven_T4_Post.xdb#xpointer(/AdvMapDwellingShared)"/>
	<RndGroup/>
	<IconFile>Icons\Generated\MapObjects\_(AdvMapObjectLink)\Objects-Dwellings\Heaven\Haven_T4_Post.(AdvMapObjectLink)-icon.tga</IconFile>
	<HideInEditor>false</HideInEditor>
</AdvMapObjectLink>
  • Link - path to dwelling AdvMapDwellingShared file
  • RndGroup - this field is not used
  • Icon File - path to creature DDS/TGA format icon that will be used in inventory pane. the root path begins from <game folder>/Complete so Icon path equal to "Icons/dwell/dwell_t4.dds" will look for icon file in "<game folder>/Complete/Icons/dwell/dwell_t4.dds"
  • Hide in Editor - can be true or false depending on if this dwelling should be hidden in the editor or not.

Packaging the framework[]

All new and edited XDB files created above should be selected and archived to create a new .pak file[4] that will be considered the NDF framework. Make sure that the folder tree is kept for each of the edited files.

Example Template[]

NDF Framework that includes all new 4 dwelling buildings for tiers from 4 to 7 for each faction is available. can be found here

Installation[]

  1. Patch game exe and map editor with the hex patch[1]
  2. Download the NDF pak[5] file and place in data folder.
  3. Run the editor and generate new map.

Note: Make sure map is generated from template that includes Dwelling tiers between T4 and T7 in order to see the new buildings!

References[]