New Creature Framework (NCF) is additional module for Heroes V ToE that allows increasing the total amount of creatures. It was first developed by SImonak but later expanded by community members.

Features

Current state of NCF increase creature count from 180 to 999 and enables their inclusion in random generated maps (RMG/ARMG).

Architecture

Bringing NCF into existence is possible through EXE edits and technical implementations in the data.pak files shown below.

  • Red background - necessary changes
  • White background - optional changes

Configuration loaded during .exe runtime.

H5 exe launch.png

LUA engine configuration loaded during adventure map runtime (start of the game).

Lua architecture-0.png





Technical implementation

H5_Game.exe and H5_MapEditor.exe

Hex edit change increases exe creature count capability from 180 to 999 and also makes the game skip rotation of NCF creatures without Map Object Visuals (MapAdvSharedObject) so when random map generation begins, only existing creatures are placed on the map. This change makes the exes capable of using 999 but now creature dummy files and IDs have to be created for the game not to crash at start. Patch for exes is called NCF_Converged_v1.1.yml and can be found on github.

types.xml

Types.xml 1

Create global unique creature identifier (creature ID):

  • Find <Base><Tables><Item><dbid><XPointer> = /GameMechanics/RefTables/Creatures.xdb#xpointer(/Table_Creature_CreatureType).
  • Go to <EnumEntries> last item - CREATURE_CYCLOP_BLOODEYED.
  • Add new items below for each creature from 180 to 999 while keeping the same format. Replace XXX with creature ID.
<Item>CREATURE_XXX</Item>

Enumerate the new unique creature identifier by mapping it to numerical value:

Types.xml-2

  • Find <Base><SharedClasses><Item><TypeName> = CreatureType.
  • Go to <Entries> last item CREATURE_CYCLOP_BLOODEYED.
  • Add new items below for each creature from 180 to 999 while keeping the same format. Replace XXX with creature ID.
<Item>
   <Name>CREATURE_XXX</Name>
   <Value>XXX</Value>
</Item>

Increase enumeration size:

  • Find <Base><SharedClasses><Item><Attributes><TypeName> = Table_Creature_CreatureType
    1. Inside Table_Creature_CreatureType Item find <Attributes><__ObjectData><Attributes><Item><Key> = ref_table_num_objs. Change its <Data> element from 180 to 1000
    2. Inside Table_Creature_CreatureType Item find <Fields><Item><Constraints><Item><__ObjectData><MaxElements> = 180 and change that value to 1000

GameMechanics\RefTables\Creatures.xdb

Add connections between creature ID and the creature base file

Clipboard04.png

  • Go to <Table_Creature_CreatureType><objects><Item><ID> = CREATURE_CYCLOP_BLOODEYED.
  • Add new items below for each creature from 180 to 999 while keeping the same format. Replace XXX with creature ID.
<Item>
   <ID>CREATURE_XXX</ID>
   <Obj href="/GameMechanics/Creature/Creatures/Neutrals/Creature_'''XXX'''.xdb#xpointer(/Creature)"/>
</Item>

GameMechanics\Creature\Creatures\Neutrals\Creature_XXX.xdb

Previous change created links, now create the creature dummy data files otherwise game crash upon launch as it cannot find them. All creature dummy files will point to a visual file. It does not matter which one as this is required only for the game engine to function. Later when NCF creatures are installed dummy files will be overwritten.

  • Create a file Creature_XXX.xdb for each creature in the 180-999 range with the dummy template below.
<?xml version="1.0" encoding="UTF-8"?>
<Creature>
	<AttackSkill>1</AttackSkill>
	<DefenceSkill>1</DefenceSkill>
	<Shots>0</Shots>
	<MinDamage>1</MinDamage>
	<MaxDamage>1</MaxDamage>
	<Speed>1</Speed>
	<Initiative>1</Initiative>
	<Flying>false</Flying>
	<Health>1</Health>
	<KnownSpells/>
	<SpellPoints>0</SpellPoints>
	<SpellPoints1>0</SpellPoints1>
	<SpellPoints2>0</SpellPoints2>
	<Exp>1</Exp>
	<Power>1</Power>
	<TimeToCommand>10</TimeToCommand>
	<CreatureTier>1</CreatureTier>
	<Upgrade>false</Upgrade>
	<PairCreature>CREATURE_UNKNOWN</PairCreature>
	<CreatureTown>TOWN_NO_TYPE</CreatureTown>
	<MagicElement>
		<First>ELEMENT_NONE</First>
		<Second>ELEMENT_NONE</Second>
	</MagicElement>
	<WeeklyGrowth>0</WeeklyGrowth>
	<Cost>
		<Wood>0</Wood>
		<Ore>0</Ore>
		<Mercury>0</Mercury>
		<Crystal>0</Crystal>
		<Sulfur>0</Sulfur>
		<Gem>0</Gem>
		<Gold>0</Gold>
	</Cost>
	<SubjectOfRandomGeneration>true</SubjectOfRandomGeneration>
	<MonsterShared/>
	<CombatSize>1</CombatSize>
	<PatternAttack/>
	<flybySequence/>
	<Visual href="/GameMechanics/CreatureVisual/Creatures/Neutrals/SnowApe.xdb#xpointer(/CreatureVisual)"/>
	<Range>0</Range>
	<BaseCreature>CREATURE_UNKNOWN</BaseCreature>
	<Upgrades/>
	<Abilities/>
</Creature>


UI\UIGameRoot.(UIGameRoot).xdb

Add connections between creature ID and the creature camera file:

UIGameRoot.png

  • Go to <UIGameRoot><creaturesCameras><Item><creatures><Item> = CREATURE_CYCLOP_BLOODEYED.
  • Add new items below for each creature from 180 to 999 while keeping the same format. Replace XXX with creature ID.
<Item>
  <Camera href="/Cameras/Interface/HireCreatures/Creature_'''XXX'''.(Camera).xdb#xpointer(/Camera)"/>
  <creatures>
    <Item>CREATURE_XXX</Item>
  </creatures>
</Item>

Cameras\Interface\HireCreatures\Creature_XXX.(Camera).xdb

Previous change created links, now the creature camera files have to be created. If they are not, game will crash upon launch as it cannot find them.

  • Create a file Creature_XXX.(Camera).xdb for each creature in the 180-999 range with the dummy template below.
<?xml version="1.0" encoding="UTF-8"?>
<Camera>
	<Name/>
	<Pos>
		<x>-2.91306</x>
		<y>-15.2688</y>
		<z>1.88227</z>
	</Pos>
	<Rot>
		<x>-6.34191</x>
		<y>-1.2952</y>
		<z>0</z>
	</Rot>
	<Rod>14.6206</Rod>
	<FOV>54.4316</FOV>
	<ClipDistanceMin>1</ClipDistanceMin>
	<ClipDistanceMax>500</ClipDistanceMax>
	<SrcName>Cameras\Interface\HireCreatures.mb</SrcName>
	<RootJoint>camera_hire_screen</RootJoint>
</Camera>

index.bin

Changes in this file will allow the user too see the new framework entities in the editor.

  • open Heroes V editor in game editing mode.
  • From the game database drop down menu select "AdvMapObjectLink" table.
  • A File tree will appear, browse to "MapObjects/_(AdvMapObjectLnk)/Monsters"
  • Create a new folder where custom creatures will reside. In our case that is NCF. To do that Right click on folder Monsters -> New Folder
  • After that right click on folder NCF -> New Object. This will create the new object link.

New Creature link.png

  • Set a name for the new object - in this case it will be "Creature_180" and click OK.
  • Repeat all steps above to create as many dummy hero classes as the framework capacity is required.
  • 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 to all engine AdvMapObjectLink files including the new one that was just added
    • MapObjects folder - that includes the newly created AdvMapObjectLink file for creature_180

Adv obj folder.png Adv obj link file.png

MapObjects\_(AdvMapObjectLink)\Monsters\*\*.xdb

The newly created AdvMapObjectLink xdb files created from the previous step are found in <game folder>/data/MapObjects/_(AdvMapObjectLink)/Monsters/ 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/Neutral/NecroGiant.(AdvMapMonsterShared).xdb#xpointer(/AdvMapMonsterShared)"/>
	<RndGroup/>
	<IconFile>Icons\Creature_180.dds</IconFile>
	<HideInEditor>false</HideInEditor>
</AdvMapObjectLink>
  • Link - path to creature AdvMapMonsterShared 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 folder so Icon path equal to "Icon/heroes/creature_180.dds" will look for icon file in "<game folder>/Complete/Icon/heroes/creature_180.dds"
  • Hide in Editor - can be true or false depending on if this creature should be hidden in the editor or not

Each of the newly created creature slots should have such file but because this is a template for framework, fields Link, RndGroup, Icon File should be left empty and Hide in Editor should be set to true as the inventory slot should stay invisible if there is no real creature.

<?xml version="1.0" encoding="UTF-8"?>
<AdvMapObjectLink>
	<Link/>
	<RndGroup href=""/>
	<IconFile/>
	<HideInEditor>true</HideInEditor>
</AdvMapObjectLink>

(Optional) MapObjects\*\*.(AdvMapMonsterShared).xdb

This file is used by the game engine and the editor to locate the Adventure map elements of the creature. It is not necessary for the framework (as there is no creature data to fill) but must be created for each existing creature later on.

(Optional) Scripts/common.lua

This file contains mapping between creature IDs and their enumeration. It is the same thing that is done in types.xml file for H5 game engine but this config is for the LUA in-game engine. In order to be able modders to add and remove creatures without constantly editing common.lua is add links to external files, one for each creature.

Common lua.png

Add load entries for creature LUA file:

  • Find CREATURE_CYCLOP_BLOODEYED = 179
  • Add load entry below for each creature from 180 to 999 while keeping the same format. Replace XXX with creature ID.
doFile("/scripts/creature_XXX.lua")

(Optional) Scripts/creature_XXX.lua

Create a file Creature_XXX.lua for each creature in the 180-999 range with the dummy template below. Replace XXX with creature ID.

Lua.png

CREATURE_XXX = XXX

Packaging the framework

All new and edited xdb files created above should be selected and archived to create a new .pak file that will be considered the NCF core. Make sure that the folder tree is kept for each of the edited files. And example package to check can be downloaded from here.

Example Template

To gain an idea of the amount of files required for a class mod you can download the template mentioned below. The EXE patch and the map editor index.bin file extends game and editor inventory creature slots up to 999. One creature - Vopar with ID 225 is provided for reference.

  1. Download all files
  2. Patch H5_game.exe and H5_editor.exe with NewCreatureFramework.yml
  3. Put newCreatureFramework_core.pak in <game folder>/data
  4. Unzip the contents of template_creature_Vopar_225_by_Psatka.zipinto <game folder> directory. This is a single creature used for the purposes of testing the functionality of NCF. Credit goes to Psatka.
  5. Open the H5_editor.exe and make an empty map
  6. From the tool panel you should be able to see the new creature - Vopar. Drag it on the map.

Template ncf.png

Community content is available under CC-BY-SA unless otherwise noted.