SE2Revival/INSTALL.md

# Installing SE2 Revival

SE2 Revival runs GPG's Siege Editor 2 (Dungeon Siege II Tool Kit 1.1, 2005) on the Steam release of Dungeon
Siege II, and lets it edit Broken World. It changes nothing in the registry, the game or the tool kit's files: a
plugin answers the editor's install-path and settings lookups in memory, and a small DLL lets the editor read
Broken World's scripts.

## What you need

- **Dungeon Siege II from Steam.** The plugin finds it through Steam: the Steam folder named in
  `HKEY_CURRENT_USER\Software\Valve\Steam` and every library in `steamapps\libraryfolders.vdf`, looking for
  `steamapps\common\Dungeon Siege 2` with `DungeonSiege2.exe` and `Resources\Logic.ds2res` in it.
- **GPG's Dungeon Siege II Tool Kit 1.1**, `DS2TK-1.1.zip`, free from siegetheday.org (the community site that
  still hosts it). It is not included here. SE2 Revival is made for the Siege Editor 2 in that kit
  (`SiegeEditor2.exe` 2.00.0.3931).
- **innoextract** (https://constexpr.org/innoextract/), to unpack the tool kit's installer. The installer itself
  stops with "Dungeon Siege II does not appear to be installed on this machine!" on a Steam install, so do not
  run it.
- Optional: **Broken World**. The editor looks for it in a `Broken World` folder inside the Dungeon Siege II
  folder (the layout DS2 Revival uses to start Broken World from Steam). Elsewhere works too, with
  `BrokenWorldDir=` set (see Settings).

## Download

Get `SE2-Revival.zip` from the Releases page, https://git.dsii.uk/dsii/SE2Revival/releases.
`SE2-Revival.zip.sha256` next to it holds the file's SHA-256; to check it in PowerShell:
`Get-FileHash SE2-Revival.zip`.

The zip contains:

| File | What it is |
|---|---|
| `version.dll` | Ultimate ASI Loader (x86, unmodified, renamed). Siege Editor 2 loads `version.dll` from its own folder, and the loader then loads `scripts\*.asi`. |
| `scripts\DS2Toolkit.asi` | the plugin |
| `scripts\DS2Toolkit.ini` | its settings |
| `bw\BWCompat.ds2dll` | Broken World script functions for the editor (stubs) |
| `README.txt` | this guide |
| `THIRD-PARTY-NOTICES.txt` | licences of the third-party parts |

## Install

1. **Unpack the tool kit.** Unzip `DS2TK-1.1.zip`, then unpack its installer without running it:

       innoextract DS2TK-1.1.exe

   Copy everything in the `app` folder it creates to a folder of your choice, e.g. `C:\Games\DS2Toolkit`. Choose
   a folder you can write to (not under `Program Files`): the plugin writes its log, and your choice of game if
   you ask it to remember it, next to itself. If you put the tool kit in a folder inside the Dungeon Siege II
   folder, the plugin uses that game folder without asking Steam.

   Optional: copy `userdocs\My Games\Dungeon Siege 2 Mod` into `Documents\My Games\` (the editor's favourites
   and GPG's prefabs).
2. **Extract `SE2-Revival.zip` into the same folder**, so that `version.dll` sits next to `SiegeEditor2.exe`
   and the `scripts` and `bw` folders are beside it.
3. **Start `SiegeEditor2.exe`.** When Broken World is found, it first asks which game you want to edit:
   Dungeon Siege II, or Broken World (the expansion's maps, with both games' content loaded). Tick "Remember my
   choice" to skip the question next time; hold **Shift** while the editor starts to be asked again.
4. **First time per game: convert the map to files.** Siege Editor 2 edits loose files, not the game's
   archives. Use File > Convert .ds2map to files, and pick:

   | Game | Map |
   |---|---|
   | Dungeon Siege II | `<game folder>\Maps\World.ds2map` |
   | Broken World | `<game folder>\Broken World\Maps\xDS2XWorld.ds2map` |

   Not `xDS2World.ds2map`: that file is Broken World's patch to the Dungeon Siege II world, and converting it
   overwrites the Dungeon Siege II files. The editor writes the converted files to
   `Documents\My Games\Dungeon Siege 2 Mod\Bits`; converting World.ds2map takes about 1.1 GB there.

## Broken World in the editor

In Broken World mode the plugin gives the editor:

- both games' archives and maps: its `res_paths` and `map_paths` settings become the Dungeon Siege II folder's
  `Resources` / `Maps` followed by Broken World's, the way Broken World itself loads them;
- `bw\BWCompat.ds2dll` as a script extension: stand-ins for 772 script functions that Broken World's game added,
  so Broken World's scripts compile. They do nothing: game logic does not run in the editor;
- Broken World's new enum names (the item skill types `ist_blood_assassin` and `ist_fist_of_stone`, and 32 new
  enchantment alteration types), so its content loads without errors;
- `skrit_retry=false`, so a script that still does not compile is not retried with a dialog each time.

Whatever the game, when the editor saves a map's `info\start_positions.gas` the plugin puts back the
`clothmap_rollover` lines (the journal map links of each start group) that the 2005 editor would drop.

## Settings: `scripts\DS2Toolkit.ini`

| Key | Default | What it does |
|---|---|---|
| `[Toolkit] GameDir=` | empty | The Dungeon Siege II folder (the one with `DungeonSiege2.exe`). Empty: the folder above the tool kit's if the game is there, else found through Steam. |
| `[Toolkit] BrokenWorldDir=` | empty | The Broken World folder. Empty: `Broken World` inside the game folder. Broken World counts as installed when `Resources\xTerrain.ds2res` is in it. |
| `[Toolkit] Game=` | `ask` | Which game to edit: `ask` (the question at start-up, when Broken World is installed), `ds2` or `bw`. "Remember my choice" writes `ds2` or `bw` here. |
| `[Toolkit] QuietErrors=` | `0` | Broken World mode only: `1` = no error dialogs (the editor's `report_errors=false`; errors still go to its log). |
| `[Toolkit] SkipArchives=` | empty | Archives the editor must not load, by file name, separated by `;` (e.g. third-party mods in the game's `Resources` folders). |
| `[Settings]` | none | Any Siege Editor 2 setting, answered for the editor, e.g. `bits=D:\MyBits` to keep the converted files elsewhere. |

Updating: extracting a newer release over the old one replaces `scripts\DS2Toolkit.ini`. Keep a copy if you
changed it.

## Troubleshooting

The plugin logs what it finds and every setting it answers in `scripts\DS2Toolkit.log` (rewritten at each
start). The editor's own error log is in `Documents\My Games\Dungeon Siege 2 Mod\Logs`.

- **The editor stops at start-up (e.g. on "%dstk_path%"), and no `DS2Toolkit.log` appears.** The loader did
  not run: `version.dll` must be in the same folder as `SiegeEditor2.exe`, with `scripts\DS2Toolkit.asi` below
  it.
- **The log says "no Dungeon Siege 2 folder found".** Steam's registry entry or library list did not lead to the
  game (e.g. the game was copied elsewhere). Set `GameDir=` to the folder that contains `DungeonSiege2.exe`.
- **The log names the wrong game folder.** A real registry key always wins over the plugin: if an old retail
  install left `HKLM\Software\Microsoft\Microsoft Games\DungeonSiege2` behind, the editor uses that. `GameDir=`
  sets the folder the plugin serves when the key is missing.
- **No question about Broken World at start-up.** Broken World was not found (no `Resources\xTerrain.ds2res` in
  `BrokenWorldDir`, by default `<game folder>\Broken World`), or `Game=` is set to `ds2` or `bw`: hold Shift
  while the editor starts, or set `Game=ask`.
- **"Broken World mode: no Resources\xTerrain.ds2res in ..." in the log.** Set `BrokenWorldDir=` to the Broken
  World folder.
- **"Duplicate template detected: 'party_humanoid' is already in content database" at every start.** A
  third-party archive in a `Resources` folder redefines a template; the known case is the Widescreen/FoV mod's
  `Widescreen Fix.ds2res`. Set `SkipArchives=Widescreen Fix.ds2res`; the game still uses the mod, only the
  editor skips it.
- **"Object on the chopping block: camera_quake" (or camera_stomp).** Four Dungeon Siege II regions
  (a1_05_03_desroadcav, a1_06_03_desruincav, a2_01_01x_sa_winecellar, a3_01_02x_sa_slcav) raise this on
  purpose: it is GPG's reminder in the retail content, shown by the editor only. Click it away.
- **Too many error dialogs in Broken World.** Set `QuietErrors=1`; the errors then go only to the editor's log.
- **The Dungeon Siege II files were overwritten by Broken World's.** `xDS2World.ds2map` was converted instead
  of `xDS2XWorld.ds2map`. Convert `World.ds2map` again to get them back.

## Uninstall

Delete `version.dll`, the `scripts` folder and the `bw` folder from the tool kit's folder. Nothing else was
installed: the plugin never writes to the registry, the game folder or the tool kit's files. Your converted and
edited maps stay in `Documents\My Games\Dungeon Siege 2 Mod\Bits`; delete that folder too if you no longer want
them.