HPL2/Development Environment - Revision history

Darkfire: Add a mention of AddDebugMessage

2024-07-15T10:45:10Z

Add a mention of AddDebugMessage

Darkfire: improve readability

2023-09-21T15:22:50Z

improve readability

Mudbill: Rewrote the tip to be a bit clearer

2021-10-09T18:38:58Z

Rewrote the tip to be a bit clearer

Mudbill: Added F2 hotkey note

2021-10-09T18:32:21Z

Added F2 hotkey note

Darkfire: /* Setting up a dev user */ Clarified smth

2020-08-05T15:21:40Z

Setting up a dev user: Clarified smth

Darkfire: Formatting

2020-07-19T00:35:49Z

Formatting

Darkfire: Proper code formatting

2020-07-19T00:29:18Z

Proper code formatting

Mudbill: Mudbill moved page Hpl2:Amnesia:devenvguide to HPL2/Development Environment without leaving a redirect

2020-07-18T19:42:29Z

Mudbill moved page Hpl2:Amnesia:devenvguide to HPL2/Development Environment without leaving a redirect

Darkfire: Big rewrite; separated direct map loading from the rest, lang fixes, bonus tips

2020-07-18T19:18:11Z

Big rewrite; separated direct map loading from the rest, lang fixes, bonus tips

Maintenance script: Upload from wiki

2020-07-09T13:47:46Z

Upload from wiki

New page

= Setting up Development Environment =

In order to make maps for Amnesia you will need to set up the game, so you can easily test maps and reload scripts. First of all, follow these steps to create a dev user:

## Enter the game normally, create a profile name (e.g. MyName) and then exit.
## 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".
## Open main_settings.cfg and set '''ShowMenu="false"''', '''ShowPreMenu="false"''', '''ExitMenuDirectly="true"''', '''LoadDebugMenu="true"''' (also setting '''SaveConfig="false"''' should be good).
## If Amnesia is 1.0.1 or above, you must set '''ForceCacheLoadingAndSkipSaving="false"''' main_settings.cfg, or else map changes will not show!
## Open user_settings.cfg (in "dev_user" folder), inside the '''Debug''' element add '''AllowQuickSave="true"''' (F4=save, F5=load) and change '''ScriptDebugOn="true"'''.
## 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).
## In '''user_settings.cfg''', inside the '''Map''' element set '''File=""''' to point to the map you want to load (eg File="my_map.map").
## 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 list.

Now you can simply run Amnesia and the map will be loaded directly without any menu. 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". If a mesh or texture has been updated, you need to press "Reload".

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

<syntaxhighlight lang="">if(ScriptDebugOn()) {
//Do your setup stuff
}</syntaxhighlight>

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.

Now you should be ready to start some editing!

@@ Line 27: / Line 27: @@
 }</syntaxhighlight>
-This will enable you to easily add all kinds of debug stuff (giving a lantern to the player, extra items, etc.) wihout having to worry about removing it for the final release.
+This will enable you to easily add all kinds of debug stuff (giving a lantern to the player, extra items, etc.) wihout having to worry about removing it for the final release. If you wish to test a map without this feature, you can use your normal user profile.
-If you wish to test a map without this feature, you can use your normal user profile.
+Another very useful function this mode enables is [[HPL2/Engine_Scripts|<code>AddDebugMessage</code>]] which shows a message in the bottom left corner of the screen.
 Now you should be ready to start some editing!

@@ Line 5: / Line 5: @@
 Follow these steps to create a developer user:
-#Enter the game (or Full Conversion mod) normally, create a profile name (e.g. MyName) and then exit.
+#Enter the game (or Full Conversion mod) normally and create a new profile (call it Dev, for example) and then exit. Some of the following steps can be overwritten by the game if it is left running.
-#Enter the save directory (<code>My Documents/Amnesia/Main</code> in Windows by default; <code>~/.frictionalgames/Amnesia/Main</code> 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.
+#Enter the save directory (<code>My Documents/Amnesia/Main</code> in Windows by default; <code>~/.frictionalgames/Amnesia/Main</code> in Linux). If your mod is an FC, do this in its save folder.
-#Open main_settings.cfg and set <code>LoadDebugMenu="true"</code> and <code>ShowPreMenu="false"</code> (this will skip you some waiting on each game launch). Setting <code>SaveConfig="false"</code>  will make sure that the in-game changes don't overwrite changes to this file, and it is recommended to do.
+#Open main_settings.cfg and change set the following options:
-#You can also set <code>ExitMenuDirectly="true"</code> if you wish to exit the game directly, without visiting the main menu.
+##<code>LoadDebugMenu="true"</code>
-#You must set <code>ForceCacheLoadingAndSkipSaving="false"</code> in '''main_settings.cfg''', or certain map changes will not show! Either way, you will sometimes need to delete the map's cache file.
+##<code>ShowPreMenu="false"</code> (this will skip you some waiting on each game launch)
-#Open user_settings.cfg (in "dev_user" folder), inside the '''Debug''' element add <code>AllowQuickSave="true"</code>  ('''F4'''=save, '''F5'''=load) and change <code>ScriptDebugOn="true"</code> (more on that later).
+##<code>SaveConfig="false"</code>  will make sure that the in-game option changes don't overwrite changes to this file
-#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.
+##Optional: <code>ExitMenuDirectly="true"</code> if you wish to exit the game without visiting the main menu
-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".
+You can now press '''F1''' to open the '''debug menu''' to turn on/off various things and more importantly - quick reload the map. After editing a script or a map 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.}}
+{{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 into a map before making changes to its script.}}
 <syntaxhighlight lang="cpp">if(ScriptDebugOn()) {
 //Do your setup stuff
 }</syntaxhighlight>
-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.
+This will enable you to easily add all kinds of debug stuff (giving a lantern to the player, 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.
+If you wish to test a map without this feature, you can use your normal user profile.
 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:
+The following config will let you load directly into a level when starting the game. This will only work if you place your maps in the main game's maps folder, which is not recommended, so this feature has very limited usage.
-#Open '''main_settings.cfg''' again and set <code>ShowMenu="false"</code> (keep in mind this feature won't work without the next steps).
+#Open '''main_settings.cfg''' again and set <code>ShowMenu="false"</code> (this feature doesn't work without the next steps).
-#In '''user_settings.cfg''', inside the '''Map''' element set <code>Folder=""</code> to the root folder for your maps (eg <code>Folder="MyMaps/"</code>), this folder MUST be located inside the maps folder in the game directory (where you put the tools).
+#In '''user_settings.cfg''', inside the '''Map''' element set:
-#In '''user_settings.cfg''', inside the '''Map''' element set <code>File=""</code>  to point to the map you want to load (eg <code>File="my_map.map"</code>).
+##<code>Folder=""</code> to the root folder for your maps (eg <code>Folder="MyMaps/"</code>), this folder MUST be located inside the maps folder in the game directory (where you put the tools).
-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.
+Now you can simply run Amnesia and the map will be loaded directly without any menu.

@@ Line 15: / Line 15: @@
 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|Don't change a map script before you load the map. Doing that with any mistakes in the script will make the game crash when loading that map. Instead, load the map before editing the script.}}
+{{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 <code>ScriptDebugOn="true"</code> you have set the script function <code>ScriptDebugOn()</code> to return true. This is extremly important as you can add something like this in your startup code:

@@ Line 5: / Line 5: @@
 Follow these steps to create a developer user:
-# Enter the game (or Full Conversion mod) normally, create a profile name (e.g. MyName) and then exit.
+#Enter the game (or Full Conversion mod) normally, create a profile name (e.g. MyName) and then exit.
-# Enter the save directory (<code>My Documents/Amnesia/Main</code> in Windows by default; <code>~/.frictionalgames/Amnesia/Main</code> 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.
+#Enter the save directory (<code>My Documents/Amnesia/Main</code> in Windows by default; <code>~/.frictionalgames/Amnesia/Main</code> 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.
-# Open main_settings.cfg and set <code>LoadDebugMenu="true"</code> and <code>ShowPreMenu="false"</code> (this will skip you some waiting on each game launch). Setting <code>SaveConfig="false"</code>  will make sure that the in-game changes don't overwrite changes to this file, and it is recommended to do.
+#Open main_settings.cfg and set <code>LoadDebugMenu="true"</code> and <code>ShowPreMenu="false"</code> (this will skip you some waiting on each game launch). Setting <code>SaveConfig="false"</code>  will make sure that the in-game changes don't overwrite changes to this file, and it is recommended to do.
-# You can also set <code>ExitMenuDirectly="true"</code> if you wish to exit the game directly, without visiting the main menu.
+#You can also set <code>ExitMenuDirectly="true"</code> if you wish to exit the game directly, without visiting the main menu.
-# You must set <code>ForceCacheLoadingAndSkipSaving="false"</code> in '''main_settings.cfg''', or certain map changes will not show! Either way, you will sometimes need to delete the map's cache file.
+#You must set <code>ForceCacheLoadingAndSkipSaving="false"</code> in '''main_settings.cfg''', or certain map changes will not show! Either way, you will sometimes need to delete the map's cache file.
-# Open user_settings.cfg (in "dev_user" folder), inside the '''Debug''' element add <code>AllowQuickSave="true"</code>  ('''F4'''=save, '''F5'''=load) and change <code>ScriptDebugOn="true"</code> (more on that later).
+#Open user_settings.cfg (in "dev_user" folder), inside the '''Debug''' element add <code>AllowQuickSave="true"</code>  ('''F4'''=save, '''F5'''=load) and change <code>ScriptDebugOn="true"</code> (more on that later).
-# 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.
+#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". If a mesh or texture has been updated (e.g. in an Entity file), you need to press "Reload".
+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|Don't change a map script before you load the map. Doing that with any mistakes in the script will make the game crash when loading that map. Instead, load the map before editing the script.}}
@@ Line 31: / Line 31: @@
 The following will let you load directly into a level when starting the game:
-# Open '''main_settings.cfg''' again and set <code>ShowMenu="false"</code> (keep in mind this feature won't work without the next steps).
+#Open '''main_settings.cfg''' again and set <code>ShowMenu="false"</code> (keep in mind this feature won't work without the next steps).
-# In '''user_settings.cfg''', inside the '''Map''' element set <code>Folder=""</code> to the root folder for your maps (eg <code>Folder="MyMaps/"</code>), this folder MUST be located inside the maps folder in the game directory (where you put the tools).
+#In '''user_settings.cfg''', inside the '''Map''' element set <code>Folder=""</code> to the root folder for your maps (eg <code>Folder="MyMaps/"</code>), this folder MUST be located inside the maps folder in the game directory (where you put the tools).
-# In '''user_settings.cfg''', inside the '''Map''' element set <code>File=""</code>  to point to the map you want to load (eg <code>File="my_map.map"</code>).
+#In '''user_settings.cfg''', inside the '''Map''' element set <code>File=""</code>  to point to the map you want to load (eg <code>File="my_map.map"</code>).
 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.

@@ Line 13: / Line 13: @@
 # 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". If a mesh or texture has been updated, you need to press "Reload".
+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". If a mesh or texture has been updated (e.g. in an Entity file), you need to press "Reload".
 {{tip|Don't change a map script before you load the map. Doing that with any mistakes in the script will make the game crash when loading that map. Instead, load the map before editing the script.}}

@@ Line 1: / Line 1: @@
-=Setting up 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.
-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.
+==Setting up a dev user==
 Follow these steps to create a developer user:

← Older revision	Revision as of 19:42, 18 July 2020
(No difference)

@@ Line 1: / Line 1: @@
-= Setting up Development Environment =
+=Setting up Development Environment=
-In order to make maps for Amnesia you will need to set up the game, so you can easily test maps and reload scripts. First of all, follow these steps to create a dev user:
+Follow these steps to create a developer user:
-## Enter the game normally, create a profile name (e.g. MyName) and then exit.
+# Enter the game (or Full Conversion mod) normally, create a profile name (e.g. MyName) and then exit.
-## 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".
+# 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.
-## Open main_settings.cfg and set '''ShowMenu="false"''', '''ShowPreMenu="false"''', '''ExitMenuDirectly="true"''', '''LoadDebugMenu="true"'''  (also setting '''SaveConfig="false"'''  should be good).
+# 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.
-## If Amnesia is 1.0.1 or above, you must set '''ForceCacheLoadingAndSkipSaving="false"'''  main_settings.cfg, or else map changes will not show!
+# You can also set '''ExitMenuDirectly="true"''' if you wish to exit the game directly, without visiting the main menu.
-## Open user_settings.cfg (in "dev_user" folder), inside the '''Debug''' element add '''AllowQuickSave="true"'''  (F4=save, F5=load) and change '''ScriptDebugOn="true"'''.
+# 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.
-## 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).
+# 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).
-## In '''user_settings.cfg''', inside the '''Map''' element set '''File=""'''  to point to the map you want to load (eg File="my_map.map").
+# 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.
-Now you can simply run Amnesia and the map will be loaded directly without any menu. 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". If a mesh or texture has been updated, you need to press "Reload".
+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". If a mesh or texture has been updated, you need to press "Reload".
-By setting '''ScriptDebugOn="true"''' you have set the script function ScriptDebugOn() to return true. This is extremly important as you can add in your startup code something like:
+{{tip|Don't change a map script before you load the map. Doing that with any mistakes in the script will make the game crash when loading that map. Instead, load the map before editing the script.}}
-<syntaxhighlight lang="">if(ScriptDebugOn()) {
+<syntaxhighlight lang="cpp">if(ScriptDebugOn()) {
 //Do your setup stuff
 }</syntaxhighlight>
 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.
 Now you should be ready to start some editing!