How to load alternative resources in fheroes2

This informations are from fheroes2 official website, but the page was removed from the site.

Here you can learn how to use your own images into Free Heroes 2.

Note: the term icon (icn) is used for all groups of image sprites, but it can be a background, a monster attacking, or really an icon.

Explanation

You can use your own sprites (images groups) to customize the appearance of the game. For this you need do some steps:

You need to know the name of the sprite to replace. You can see a list in the icn reference page.
Next you need to extract it, to know how many images have it or use that images as templates.
- First unpack the resources, in the file heroes2.agg. For this purpose use tools/extractor.exe path_to/heroes2.agg agg_unpack_dir .
- All sprites are in files ICN. To unpack them it is possible by means of the utility: tools/icn2img.exe icn_file unpack_dir
The next step is make the folder that contain the change images. It's name should be the same as the icn (ending with the .icn) and with the letters in lowercase. And one more thing, it should be in the files/images/ folder of fheroes 2.
Add the images to that folder. If you extracted it, it name may be something as 000.png, 001.png, ... .
Now make a text file named spec.xml on the icon folder.
Add template code to it (see bellow), adding one sprite line for each image that have the icon (as you can see when extracted it).
Complete the template using the name of the images that you have, their location, the name of the icon, and the number of sprites (images) that it have. And save it, of course.
Edit the fheroes2.cfg file and change/add the option "alt resource = on".
Now you can play with your changes images (support png and jpg format).

spec.xml template

<?xml version="1.0" ?>
<icn name="test.icn" count="3">
    <sprite name="0.png" ox="ORIX" oy="ORIY"/>
    <sprite name="1.png" ox="ORIX" oy="ORIY"/>
    <sprite name="2.png" ox="ORIX" oy="ORIY"/>
</icn>

Where:

test.icn is the name of the ICN.
count="3" is the number of sprites of the icon (in the template are 3 sprites).
0.png, 1.png, 2.png are the name of the images files of each sprite.
ORIX are the x origin coordinate, for example 20, -1, or 0 for the left side. Each sprite can (and normally) have different values.
ORIY are the y origin coordinate, for example 20, -1, or 0 for the upper side. Each sprite can (and normally) have different values.

Example with the main menu background

For loading alternative sprites, it is necessary to learn name ICN of a file and an index sprite:
- It is necessary to unpack a file heroes2.agg. For this purpose use:
  - tools/extractor.exe path_to/heroes2.agg agg_unpack_dir
- All sprites are in files ICN. To unpack them it is possible by means of the utility:
  - tools/icn2img.exe icn_file unpack_dir
- Unpack all sprites. For example: HEROES.ICN is an image of the start menu, 1 sprite.
We load an alternative picture into the starting menu:
- create folder files/images/heroes.icn (case sensitive!)
- create xml file files/images/heroes.icn/spec.xml

<?xml version="1.0" ?>
<icn name="heroes.icn" count="1">
    <sprite name="000.png" ox="0" oy="0"/>
</icn>

Copy your variant of a picture files/images/heroes.icn/000.png. They should be the same size as well as the original.
Set options: "alt resource = on"
Start game.

Battle animations

prepare alternative sprites (above)
edit files/images/battle.xml

<?xml version="1.0" ?>
<battle>
  <!--
 <icn name="unknown.icn">
  <animation state="idle" start="0" count="0"/>  // idle frame
  <animation state="move" start="0" count="0"/>  // move frame
  <animation state="fly1" start="0" count="0"/>  // jump up frame
  <animation state="fly2" start="0" count="0"/>  // fly frame
  <animation state="fly3" start="0" count="0"/>  // jump down frame
  <animation state="shot0" start="0" count="0"/> // prepare shot frame
  <animation state="shot1" start="0" count="0"/> // shot up frame
  <animation state="shot2" start="0" count="0"/> // shot frame
  <animation state="shot3" start="0" count="0"/> // shot down frame
  <animation state="attk0" start="0" count="0"/> // prepare attack frame
  <animation state="attk1" start="0" count="0"/> // attack up frame
  <animation state="attk2" start="0" count="0"/> // attack frame
  <animation state="attk3" start="0" count="0"/> // attack down frame
  <animation state="wcne" start="0" count="0"/>  // wcne frame
  <animation state="kill" start="0" count="0"/>  // kill frame
 </icn> -->

 <!-- example: original frame for peasant.icn -->
 <icn name="peasant.icn">
  <animation state="idle" start="1" count="4"/>
  <animation state="move" start="5" count="8"/>
  <animation state="attk1" start="16" count="6"/>
  <animation state="attk2" start="22" count="6"/>
  <animation state="attk3" start="28" count="6"/>
  <animation state="wcne" start="13" count="3"/>
  <animation state="kill" start="34" count="4"/>
 </icn>

 <!-- example: original frame for archer.icn -->
 <icn name="archer.icn">
  <animation state="idle" start="1" count="4"/>
  <animation state="move" start="5" count="8"/>
  <animation state="shot0" start="16" count="4"/>
  <animation state="shot1" start="20" count="4"/>
  <animation state="shot2" start="24" count="4"/>
  <animation state="shot3" start="28" count="4"/>
  <animation state="attk0" start="32" count="4"/>
  <animation state="attk1" start="36" count="3"/>
  <animation state="attk2" start="39" count="3"/>
  <animation state="attk3" start="42" count="3"/>
  <animation state="wcne" start="13" count="3"/>
  <animation state="kill" start="45" count="6"/>
 </icn>

 <!-- more other -->

</battle>

Sounds

support mp3 and ogg format
see files/sounds/sound.txt list files

Music

support mp3 and ogg format
set option: music = ext
list of required track names for full music support
- 02.ogg - Random for Battle
- 03.ogg - Random for Battle
- 04.ogg - Random for Battle
- 05.ogg - Barbarian Castle
- 06.ogg - Sorceress Castle
- 07.ogg - Warlock Castle
- 08.ogg - Wizard Castle
- 09.ogg - Necromancer Castle
- 10.ogg - Knight Castle
- 11.ogg - Lava Theme
- 12.ogg - Wasteland Theme
- 13.ogg - Desert Theme
- 14.ogg - Snow Theme
- 15.ogg - Swamp Theme
- 16.ogg - Beach Theme
- 17.ogg - Dirt Theme
- 18.ogg - Grass Theme
- 23.ogg - Map Puzzle
- 28.ogg - AI Turns
- 29.ogg - Battle Wins
- 30.ogg - Battle Loss
- 42.ogg - Main Menu