HPL2/Development Environment

In order to mod Amnesia comfortably, you will need to set up the game so you can easily test maps and reload scripts. To do that, it is recommended to have two in-game users; a regular one (for testing how the mod works for the player) and a developer one. This article is about the basic set up of a developer user.

Setting up a dev user

Follow these steps to create a developer user:

1. Enter the game (or Full Conversion mod) normally, create a profile name (e.g. MyName) and then exit.
2. Enter the save directory (My Documents/Amnesia/Main in Windows by default; ~/.frictionalgames/Amnesia/Main in Linux) and rename the user name (e.g. MyName) to "dev_user". If your mod is an FC, do this in its save folder.
3. Open main_settings.cfg and set LoadDebugMenu="true" and ShowPreMenu="false" (this will skip you some waiting on each game launch). Setting SaveConfig="false" will make sure that the in-game changes don't overwrite changes to this file, and it is recommended to do.
4. You can also set ExitMenuDirectly="true" if you wish to exit the game directly, without visiting the main menu.
5. You must set ForceCacheLoadingAndSkipSaving="false" in main_settings.cfg, or certain map changes will not show! Either way, you will sometimes need to delete the map's cache file.
6. Open user_settings.cfg (in "dev_user" folder), inside the Debug element add AllowQuickSave="true" (F4=save, F5=load) and change ScriptDebugOn="true" (more on that later).
7. In order to avoid running into "File index out of bounds" errors when designing your custom story in the level editor, edit the file resources.cfg located in the root the directory of Amnesia (i.e. where Amnesia is installed) and add the custom_stories directory to the end of the list. This will also let you see custom assets placed in maps in the editors.

You can now press F1 to open a debug menu to turn on/off various things and more importantly quick reload the map. This is probably the most important thing to do when editing. When changed a script or added entities to a map, do NOT restart the game, instead simply press "Quick reload" or F2. If a mesh or texture has been updated (e.g. in an Entity file), you need to press "Reload".

Tip: If you start the game with a syntax error in your script file, it will crash. But if you reload the script with F2 with a syntax error, it will instead give you an error description. Therefore it's a good idea to load the game before making uncertain changes to the script.

By setting ScriptDebugOn="true" you have set the script function ScriptDebugOn() to return true. This is extremly important as you can add something like this in your startup code:

if(ScriptDebugOn()) {
//Do your setup stuff
}

This will enable you to easily add all kinds of debug stuff (giving lantern, extra items, etc) wihout having to worry about removing it for the final release.

If you wish to test a map without these features, you can use your normal user profile. Alternatively, you can make another dev user, but without the script debug option - this way you can both use the debug menu and have the script debug off.

Now you should be ready to start some editing!

Loading directly into a map

The following will let you load directly into a level when starting the game:

1. Open main_settings.cfg again and set ShowMenu="false" (keep in mind this feature won't work without the next steps).
2. In user_settings.cfg, inside the Map element set Folder="" to the root folder for your maps (eg Folder="MyMaps/"), this folder MUST be located inside the maps folder in the game directory (where you put the tools).
3. In user_settings.cfg, inside the Map element set File="" to point to the map you want to load (eg File="my_map.map").

Now you can simply run Amnesia and the map will be loaded directly without any menu. This is optional, because it's only useful for things like testing player config files, and will only work if you place your maps in the mentioned folder, which is not recommended.