HPL3/Amnesia: Rebirth/Modding/Developer Debug Menu

When developing your mod, it is important to be able to have a fast feedback loop and have extensive set of tools which can help to test our mod. Exactly for that reason, we have the Developer Menu. This article goes in detail over the menu and all of its features.

Keyboard Shortcuts

The following keyboard shortcuts are enabled during dev mode:

Shortcut Key	Action
F1	Brings up the developer debug menu. This needs to be done in order to have full access to the developer features when running a game in debug mode.
F2	Pauses / Resumes the game world processes, basically makes the game freeze. Note that you can still noclip in this state.
F3	This makes the game run 4 times faster. It is good if you want to skip specific sections in the map.
F4	This makes the game run 4 times slower. It is good if you want to want to focus on something that happens very fast in the map.
F5	Reloads the current map.
F7	Enables / Disables spectator camera mode (noclip).
F8	Takes a screenshot of the game and saves it inside the main game folder.
F9	Quick-saves the game.
F10	Quick-loads the last save.
Insert	Starts / Stops quick input recording and saves to the file QuickRecord.sav.
Home	Starts playing back the last quick input recorded file.

Debug Menu

The debug menu is where most of the work happens. There, you can find a list of useful actions which will help you in your mod development.

ᅠ

You will find the actions and option grouped in the following categories:

Game & Script

Option	Description
Name	Desc
Reload	Reloads the current map.
Pause	Pauses the game
Reload	Reloads the game
Fast	This makes the game run 4 times faster. It is good if you want to skip specific sections in the map.
Slow	This makes the game run 4 times slower. It is good if you want to want to focus on something that happens very fast in the map.
Script Debug	Script Debug enables further scripting features that won't work otherwise, such as OnAction. It is also useful to make your map behave differently. In your map script file, you may want to change the behavior of your map depends if the script debug is enabled or not. For example: // This script will enable the player's flashlight only if the script debug is on. void OnStart() { if (cScript_ScriptDebugOn()) // Checks if Script Debug option is turned on or not { Player_SetFlashlightDisabled(false); } }
God Mode	Makes the player invincible and prevents from getting chased by enemies.
Spectator Cam	Enables / Disables spectator camera mode (noclip).
Slo-mo	Makes the player invincible and prevents from getting chased by enemies.
Speed	Makes the player invincible and prevents from getting chased by enemies.
SM Move	Makes the player invincible and prevents from getting chased by enemies.
SM Look	Makes the player invincible and prevents from getting chased by enemies.
Cam->Player	Desc
Player->Cam	Desc
Player-SpecCam auto-teleport	Desc
Recompile Script and Lang	Desc
Merge Lang Files	Desc
Reload script at task switch	Desc
Show Garbage Collection	Desc
Skip AI Rebuild On Reload	Desc
Fast Physics Load	Desc
Name	Desc

Map & Scene

Option	Description
Load Map	Desc
Test Change Map Save	Desc
Teleport to start pos	Desc
Map Batch	Desc
Preload Map	Desc
Start Preloaded Map	Desc
Preload Map Batch	Desc
Preload Priority	Desc Preload Time
Keep Previous Map Loaded	Desc
Export Map to Mesh	Desc
Trigger Permafail	Desc
Name	Desc

Logging

Option	Description
HPL Log	Desc
Show Error List	Desc
AI Log	Desc
Debug Log	Desc
Resource Logging	Desc
Show non-preloaded resources	Desc

Debug

Option	Description
Hide Debug Output	Desc
Module Output	Desc
Map Info	Desc
Entity Info	Desc
Light Level Info	Desc
Messages	Desc
Notes	Desc
Pause on assert	Desc
Debug Info	Desc
Hide Sleeping	Desc
Inspection Mode	Desc
GUI Debug	Desc
Hide crosshair	Desc
Hide hints	Desc
Hide popup icons	Desc
Hide tentacles	Desc
Display Safe Area	Desc
Player Collider	Desc
Physics Debug	Desc
Overlay	Desc
Light Level Grid	Desc
Deep Shadow	Desc

Graphics Debug

Option	Description
FPS	Desc
FPS Graph	Desc
Memory Usage	Desc
Rendering Info	Desc
Print Container Debug Info	Desc
Render Portal Debug	Desc
Use Portal Culling	Desc
Draw Skeletons	Desc
Offset Skeletons	Desc
Wireframe Mode	Desc
Previous Frame Occlusion	Desc
Debug Mode	Desc
Gamma	Desc
Brightness	Desc
Contrast	Desc
Disable Textures	Desc
Disable Post-Effects	Desc
Occlusion Culling	Desc
Draw Shadows	Desc
Name	Desc
Name	Desc
Name	Desc
Name	Desc
Name	Desc
Name	Desc

Resources

Option	Description
Auto reload resources	Desc
Load files in _temp folders	Desc
Find Duplicate File Names	Desc

Sound

Option	Description
Show sounds playing	Desc
Show sound params	Desc
Show sound categories	Desc
Show sound AI events	Desc

Music

Option	Description
Play Music	Desc
Stop All Music	Desc

Voices

Option	Description
Show event/voice messages	Desc
Show Missing Voice Error	Desc
Play Voice Subject	Desc
Reload Voice Data on Taskswitch	Desc
Name	Desc

Events

Option	Description
Show Event Messages	Desc
Show Event Facts	Desc
Disable Flashbacks	Desc
Name	Desc

Input

Option	Description
Gamepad Input Only	Desc
Record Input	Desc
Playback Recorded Input	Desc
Name	Desc
Name	Desc

Stress Test

Option	Description
Analyze Map	Desc
Analyze Entities	Desc
Analyze Materials	Desc
Analyze Active Entities	Desc
Print Resource Usage	Desc
Random Input	Desc
Random Physics Forces	Desc
Name	Desc

Profile

Option	Description
Show Profiler	Desc
Show GPU Profiler	Desc
Pause Profiling	Desc
Profile Longest Frame	Desc
Label	Desc

Debug UI Settings

Option	Description
Debug Lines	Desc
Pause game when open	Desc
Name	Desc
Name	Desc

Platform & Language

Option	Description
Set Suffix	Desc
Name	Desc

Debug Texts

This section is at the very top of the menu and consists of checkboxes which display different information about the game, map, physics, script, etc on in the form of text on the screen.

Texts Options

Option	Description
Show FPS	Shows the game FPS.
Show module info	Shows information about different user modules. It does not seem to be useful however, as not enough information is displayed.
Show map info	Shows the amount of entities in the map and their state.
Show entity info	Does not work.
Show sounds playing	Shows a list of all the sounds that currently play in the map, and information about them.
Show sound params	Adds additional information to the sounds playing list (distance from player)
Show sound categories	Shows a list of all the different sound level categories.
Show sound ai event	Shows a message when an Ai agent has heard a sound.
Show debug messages	Shows dev messages which are specified in the map script file.
Show event/voice messages	Does not work.
Inspection Mode	Enables inspection mode, which displays information about assets used in the map, such as texture files, location on disk, size, etc.
Occlusion Culling	Enables occlusion culling (Skips rendering polygons that are no in the view of the player ).
God Mode	Makes the player invincible and prevents from getting chased by enemies.
Draw physics debug	Displays physics bodies (pink) of static objects and entities in the map.
Overlay physics debug	Displays physics debug + normal game meshes.
Draw Gui debug	Displays pink overlay which represents intractable GUI elements.
Show TV Safe Area	Shows the safe area of a TV, surrounded by red borders.
Show Missing Voice Error	Lists voice subjects which have missing voice files.
Resource Logging	Logs game resources. [Clarify]
Show non-preloaded resources	Lists resources which are not preloaded by the game. [Clarify]
Show Memory Usage	Shows information about the game memory usage: Memory Usage: The amount of VRAM used by the renderer. This contains frame buffers, shadows, terrain and post-effects. It is greatly affected by the resolution of the window. Texture Memory Usage: The texture memory used by the level. This contains all the textures used for the materials of the objects. Texture memory is reduced by a lot with just a few changes in the config file. Vertex Memory Usage: The amount of VRAM used by meshes and decals. The imporant difference between Vertex and Texture memory is that Vertex memory can't be reduced by changing a setting. It takes up as much space on a good and a bad computer. Total Memory Usage: The sum of the above memory usage.
Show Rendering Info	Shows information about the game rendering: Draw Calls - The number of objects rendered in the current scene. Rendered Triangles / Vertices - The total number of triangles and vertices rendered per frame. Queries - A special draw call used to check if an object is occluded. It is more expensive than a draw call.
Show Garbage Collection	Shows a graph of garbage collection. [Clarify]
Show Debug Info Window	Displays a window with debug information. [Clarify]
Hide Sleeping Entities	Makes sleeping entities invisible in the map. To do: Link to source about sleeping entities
Use Portal Culling	Enables the game to use portal culling in the map. It is recommended to always leave that on, unless you want to see the difference in performance. To do: add reference link for portals

Additional Options

Brightness

The brightness slide increases / decreases the brightness of the game. Not to be confused with gamma.

---

Print Container Debug Info

This button prints container debug info to the screen.

---

Merge Lang Files

Merges two language files between the main game language file and another.

This feature doesn't seem to be useful in practice.

Map

The map section of the menu includes settings and actions which are related to maps in general, as well as the currently-loaded map.

Auto Reload Resources

This makes the map reload resources (mostly game assets) automatically, should you change or add something to the mod.

Reload Script At Task Switch

The script file for the map will be updated when a task switch has been performed. Meaning, as long as you do not go back to the game after changing the script, the new script won't be updated in the game.

Reload Script Constantly

The script file for the map will be updated constantly every time it is saved. It doesn't matter if the game task is focused or not.

Recompile Script and Lang

Leftover feature from HPL2. The button does not work.

Reload from current pos

When reloading a map, the player will retain the current position instead of starting at the beginning of the map.

Fast Physics Load

Unknown option. ^[Clarify]

Reload Game

Reloads the map. This also resets the state of the player and all the other scripts which run in the background.

Script Debug

Script Debug enables further scripting features that won't work otherwise, such as OnAction. It is also useful to make your map behave differently. In your map script file, you may want to change the behavior of your map depends if the script debug is enabled or not. For example:

// This script will enable the player's flashlight only if the script debug is on.
void OnStart()
{
  if (cScript_ScriptDebugOn()) // Checks if Script Debug option is turned on or not
  {
     Player_SetFlashlightDisabled(false);  
  } 
}

Teleport to Start Pos

Teleports the player to a specific PlayerStart Area that can be selected from the dropdown list. Useful for skipping areas in a map.

Load Map

Select a map file to load in the game. HPL3 Map File (.hpm) and HPL2 Map File (.map) are accepted.

Warning: Some things are almost guranteed to not load correctly when loading HPL2 map files, mostly related to issues with static-objects. This is due to the internal structure of the .map files and how it handles assets information.

Test Change Map Save

Unknown option. ^[Clarify]

Preload Map

Loads another map in the background so it can be loaded later much faster. Main article: Level Streaming

Start Preloaded Map

Loads the pre-loaded map. If no map has been pre-loaded, the button will do nothing.

Keep Previous Map Loaded

Keeps the previous map loaded. This is useful if you want to go quickly switch between two maps.

Preload Priority

Sets the priority of the map preload process. Ranges from paused to very high

Game

The game section of the menu includes general-purposes option which affect how you play and move in the game. It also displays debug information such as scripting errors.

Input

The Input section of the menu includes tools and option for capturing and analyzing user input.

Stress Test

This is a tool used to test the map under heavy performance conditions.

Misc

The misc section include options which don't fit anywhere else.

Graphics Debug

Debugging the graphic performance of a level is vital to understand which parts are causing the bottleneck. It can also be used to find bugged/incorrect meshes or entities. With this section of the debug menu, you will be able to find which parts of the scene take up the most performance.

Show FPS Graph

This option displays on the screen a graph that shows FPS peaks on a time scale. It's useful for finding areas in a map that reduce FPS the most.

FPS graph.

Large Light Test

Unknown option.

Previous Frame Occlusion

This option pauses the occlusion culling and renders the scene with the occlusion culling from before the checkbox was ticked. This is used to see how effective the occlusion culling is in the specific scene. After activating this you can switch to to spectator camera mode and look at the scene from another angle to see where the culling fails. Activating this will disable rendering of translucent objects since they can be unstable.

On the left, you can see what the player sees. On the right, the camera has been moved back and it is now possible to see all the objects that get rendered this frame. There are a lot more than what it looks like in the left picture.

GBuffer

Shows what the frame buffers look like. These are then used by the lights to shade the scene. It can be used to check if a model has incorrect textures or normals.

A scene in a g-buffer mode. Notice the different graphic modes.

Light Complexity

Light complexity shows how expensive the lighting of a scene is. It creates a heat map on the screen to show how much power each light takes. Overdraw of light is not very expensive, it is about twice as expensive as a translucent object. When the light has a shadow map it becomes much more expensive. The complexity of a shadow casting light is based on how many draw calls and triangles are required to generate the shadow map.

The red areas on the right image are not good. There seem to be multiple large (in screen space) shadow casting lights in this scene.

Tip: To test if most of the complexity comes from shadows or not, you can toggle the Draw Shadows checkbox in the menu. Here is what the scene complexity looks like without shadows. Here is what the scene complexity looks like without shadows:

Overdraw

Creates a heat map that shows how much translucent overdraw each pixel receives. Overdraw is how many times a pixel gets rendered to.^[Clarify]
The goal should be that no part of the screen is red. It does not matter that much if only a small part is, however.

On the left you can see the scene rendered normally. The fog particles are barely visible here. On the right the pixel overdraw is rendered. The red areas show that more than 32 translucent planes are rendered, which is not good.