===========================================================================
 HEROES OF MIGHT AND MAGIC 1 - MANUAL FILE COPYING INSTRUCTIONS
===========================================================================

This engine does not include the original game's data. To play, you must
copy a handful of files from a copy of the original 1995 game that you own.

You can use the automatic installer scripts for MacOS or Windows, or you
can copy the files by hand using the steps below. Copying by hand needs no
extra tools.


---------------------------------------------------------------------------
 WHERE THE GAME DATA COMES FROM
---------------------------------------------------------------------------

Your source is ONE of the following:

  * The original CD (in a CD/DVD drive), or a CD image (.iso) you have
    mounted so it appears as a drive/folder.

        On the CD/ISO the files live inside a top-level folder called
        HEROES, with these sub-folders:

            HEROES\ANIM
            HEROES\DATA
            HEROES\MAPS
            HEROES\SOUND

  * The GOG.com version, already installed. Look inside the GOG install
    folder for HEROES.AGG, the MAPS folder, and the high score files
    (STANDARD.HS, CAMPAIGN.HS).

        IMPORTANT - GOG animations and sounds: the GOG build does NOT keep
        the animations and sound effects in loose ANIM / SOUND folders. They
        are packed inside a file named  homm1.gog  that sits next to
        HEROES.AGG. That file is really a CD image (ISO). You must open it
        and copy two folders out of it - see the "GOG ONLY" box in Steps 3
        and 4 below.

        NOTE: If you only have the GOG installer .exe and have NOT installed
        the game, you cannot copy files out of it by hand - it is a
        compressed package. Either install the game first, or use the
        automatic installer, which can unpack the .exe for you.


---------------------------------------------------------------------------
 WHERE THE FILES NEED TO GO
---------------------------------------------------------------------------

Copy everything into the game's BASE directory - the folder the game runs
from. This is one level ABOVE the "install" folder that contains these
instructions.

When you are done, the base directory should look like this:

    <game folder>\
        HEROES.AGG                 (single file)
        STANDARD.HS                (single file, optional)
        CAMPAIGN.HS                (single file, optional)
        maps\                      (folder - see below)
        ANIM\                      (folder - see below)
        SOUND\                     (folder - see below)
        install\                   (already present - these instructions)

Folder names on your source may be UPPER or lower case - that is fine.
Create the destination folders (maps, anim, SOUND) if they do not exist.


---------------------------------------------------------------------------
 GOG ONLY - OPENING homm1.gog  (needed for Steps 3 and 4)
---------------------------------------------------------------------------

SKIP this section if your source is a real CD or an .iso - your ANIM and
SOUND folders are already loose and ready to copy.

The GOG version stores the animations and sound effects inside a single
file called  homm1.gog  (found next to HEROES.AGG). Despite its name this
is an ISO CD image. Inside it are exactly two folders:

    DANIM      <- the animation videos (note the "D"; this becomes anim)
    SOUND      <- the sound effect samples

Open it using whichever method fits your system:

  WINDOWS 11 / 10
    1. Make a copy of  homm1.gog  and rename the copy to  homm1.iso
       (Windows only mounts files ending in .iso).
    2. Double-click  homm1.iso . It appears as a new drive in "This PC".
    3. Open that drive; you will see the DANIM and SOUND folders.
    4. Do Steps 3 and 4 below, then eject the drive when finished.

  macOS
    1. Make a copy of  homm1.gog  and rename the copy to  homm1.iso .
    2. Double-click it (or run:  hdiutil attach homm1.iso ). It mounts
       under /Volumes and opens in Finder.
    3. Do Steps 3 and 4, then eject the mounted image.

  ANY SYSTEM (using an archive tool)
    7-Zip (Windows) or The Unarchiver / 7z (macOS) can open the image
    directly - no rename needed. Right-click  homm1.gog  -> open with the
    archive tool, and extract the DANIM and SOUND folders.

Remember which two folders you extracted; Steps 3 and 4 tell you where each
one goes. In short: DANIM -> anim,  SOUND -> SOUND.


---------------------------------------------------------------------------
 STEP 1 - THE MAIN ARCHIVE AND HIGH SCORES  (from DATA)
---------------------------------------------------------------------------

From the DATA folder of your source, copy these files into the BASE folder:

    HEROES.AGG      <- REQUIRED. This is the main game archive. Without it
                       the game will not run.

    STANDARD.HS     <- REQUIRED. Standard-game high score table.
    CAMPAIGN.HS     <- REQUIRED. Campaign high score table.

Result:

    <game folder>\HEROES.AGG
    <game folder>\STANDARD.HS
    <game folder>\CAMPAIGN.HS


---------------------------------------------------------------------------
 STEP 2 - THE MAPS  (from MAPS)
---------------------------------------------------------------------------

Create a folder called  maps  in the BASE folder, then copy the entire
contents of the source MAPS folder into it.

Two kinds of map files matter:

    *.MAP                <- Scenario (single-player / standalone) maps.
                            Copy all of them.

    CAMP1.CMP            <- The nine campaign maps. You should have all
    CAMP2.CMP               nine, numbered 1 through 9.
    CAMP3.CMP               
    CAMP4.CMP               
    CAMP5.CMP
    CAMP6.CMP
    CAMP7.CMP
    CAMP8.CMP
    CAMP9.CMP

The simplest approach: just copy EVERYTHING from the source MAPS folder
into  <game folder>\maps  and you will have all of the above.

Result:

    <game folder>\maps\AES31000.MAP   (CLAW and other *.MAP files)
    <game folder>\maps\CAMP1.CMP  ...  CAMP9.CMP


---------------------------------------------------------------------------
 STEP 3 - THE ANIMATIONS  (from ANIM)
---------------------------------------------------------------------------

Create a folder called  anim  in the BASE folder, then copy the Smacker
video files (.SMK) from the source ANIM folder into it.

    +---------------------------------------------------------------+
    | GOG ONLY: there is no loose ANIM folder. Your source is the   |
    | DANIM folder INSIDE homm1.gog (see the "GOG ONLY - OPENING    |
    | homm1.gog" section above). Copy the .SMK files out of DANIM   |
    | into the base folder's  anim  folder. Source folder is named  |
    | DANIM; destination folder is named anim.                      |
    +---------------------------------------------------------------+

The five the engine looks for are:

    LOSE1.SMK       <- Played when you lose.
    WIN01C.SMK      <- Victory animation.
    WIN02.SMK       <- Victory animation.
    NWCLOGO.SMK     <- NWC Globe spinning on sword intro video (optional).
    INTRO02C.SMK    <- Heroes marching out of the gates intro (optional).

If your source ANIM folder contains other .SMK files, copy those too - it
does no harm and future versions may use them.

NOTE: Some older GOG builds do NOT include the .SMK videos.
If you have no ANIM folder or no .SMK files, that is fine - the game still
plays, just without those cut-scenes.

Result:

    <game folder>\anim\LOSE1.SMK
    <game folder>\anim\WIN01C.SMK
    <game folder>\anim\WIN02.SMK
    <game folder>\anim\NWCLOGO.SMK
    <game folder>\anim\INTRO02C.SMK


---------------------------------------------------------------------------
 STEP 4 - THE SOUND EFFECTS  (from SOUND)
---------------------------------------------------------------------------

Create a folder called  SOUND  in the BASE folder, then copy the sound
sample files from the source SOUND folder into it.

    +---------------------------------------------------------------+
    | GOG ONLY: there is no loose SOUND folder either. Your source  |
    | is the SOUND folder INSIDE homm1.gog (see the "GOG ONLY -     |
    | OPENING homm1.gog" section above). Copy its contents into the |
    | base folder's  SOUND  folder. The GOG release typically has   |
    | .82M files only.                                              |
    +---------------------------------------------------------------+

There are up to three file types, depending on your release:

    *.82M           <- 8-bit MONO sound effects. Present in most releases,
                       including GOG, and the only sound available from the windows 95 CD. 
                       These are the basic sound effects.

    *.82S           <- 8-bit STEREO effects.  DOS CD releases and latest GOG releases.
    *.62S           <- 16-bit STEREO effects. DOS CD releases and latest GOG releases.

The files are typically named HEROES00, HEROES01, HEROES02, ... with one
of the extensions above (for example HEROES00.82M).

The simplest approach: copy EVERYTHING from the source SOUND folder into
<game folder>\SOUND. If your release only has .82M files, that is all you
need; the stereo files simply will not be present.

NOTE: On some releases the sound effects live only INSIDE HEROES.AGG and
there is no separate SOUND folder. In that case there is nothing to copy
here - the game will read the sounds from HEROES.AGG.

Result:

    <game folder>\SOUND\HEROES00.82M   (and other sound files)


---------------------------------------------------------------------------
 QUICK CHECKLIST
---------------------------------------------------------------------------

  [ ] (GOG only) opened homm1.gog to reach its DANIM and SOUND folders
  [ ] HEROES.AGG          in the base folder
  [ ] STANDARD.HS         in the base folder   
  [ ] CAMPAIGN.HS         in the base folder   
  [ ] maps\  contains     *.MAP  and  CAMP1.CMP ... CAMP9.CMP
  [ ] anim\  contains     LOSE1.SMK, WIN01C.SMK, WIN02.SMK   (from DANIM on GOG)
  [ ] SOUND\ contains     *.82M  (and *.82S / *.62S on CD releases)

Only HEROES.AGG and the maps are strictly required to start playing.

===========================================================================
