New Creature Framework (NCF)

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 or no changes

Configuration loaded during .exe runtime.

Another one that includes Random blocks relations

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

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 NewCreatureFramework.yml and can be found on github.

types.xml[]

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:

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

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:

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.

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 creatures as the framework capacity is set to.
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 creature_180

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.

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.

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.

Download all files
Patch H5_game.exe and H5_editor.exe with NewCreatureFramework.yml
Put newCreatureFramework_core.pak in <game folder>/data
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.
Open the H5_editor.exe and make an empty map
From the tool panel you should be able to see the new creature - Vopar. Drag it on the map.

New Creature Framework (NCF)

Contents

Features[]

Architecture[]

Technical implementation[]

H5_Game.exe and H5_MapEditor.exe[]

types.xml[]

GameMechanics\RefTables\Creatures.xdb[]

GameMechanics\Creature\Creatures\Neutrals\Creature_XXX.xdb[]

UI\UIGameRoot.(UIGameRoot).xdb[]

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

index.bin[]

MapObjects\_(AdvMapObjectLink)\Monsters\\.xdb[]

(Optional) MapObjects\\.(AdvMapMonsterShared).xdb[]

(Optional) Scripts/common.lua[]

(Optional) Scripts/creature_XXX.lua[]

Packaging the framework[]

Example Template[]

Fan Feed

New Creature Framework (NCF)

Features[]

Architecture[]

Technical implementation[]

H5_Game.exe and H5_MapEditor.exe[]

types.xml[]

GameMechanics\RefTables\Creatures.xdb[]

GameMechanics\Creature\Creatures\Neutrals\Creature_XXX.xdb[]

UI\UIGameRoot.(UIGameRoot).xdb[]

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

index.bin[]

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

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

(Optional) Scripts/common.lua[]

(Optional) Scripts/creature_XXX.lua[]

Packaging the framework[]

Example Template[]

Fan Feed

MapObjects\_(AdvMapObjectLink)\Monsters\\.xdb[]

(Optional) MapObjects\\.(AdvMapMonsterShared).xdb[]