Guide is in WIP state, as I'm working on my own custom story I'll try to update it as I discover new info myself.

This guide will be short as possible. Going straight to the point, without describing why it works, but rather how to make it work.

Some info will be simply copied from wiki[wiki.frictionalgames.com], providing links from where I did copy it from, simply because I want all necessary info to be in one spot and more or less structurized to create a basic mod without need to jump between many resouces. Also wiki[wiki.frictionalgames.com] lacks a lot of actual info, for The Bunker especially, since many things work in a new way.

If you're a linux user, it is also possible to work with provided tools via proton, despite them being designed for windows. Just add Non+Steam game inside your library and set compatibility to "Proton Experimental". They might work with some issues maybe, but two main ones (level & model editors) works all fine, without crashing or anything.

All games from frictional games provide all the tools for modding inside games main directory. Each editor comes with the game installation and will instantly open without need to install anything.

The best way to create, edit, and modify language entries and language files, is to use the Language Editor. Executable is called LangEditor.exe.

Main tool for creating game levels. Program you are going to spend most of your creative time in. Executable is called LevelEditor.exe.

Used for creating and editing materials(textures) for the game. If you want to add custom textures & decals, this is one. Executable is called MaterialEditor.exe.

Used for turning mesh files into game entities, or editing existing ones. Executable is called ModelEditor.exe.

Can open mesh (.DAE) and entity (.ent) files for display. You can check how your model is going to look inside of a game with different options. Executable is called ModelViewer.exe.

Create, edit and modify particles. I have not touched it yet. Executable is called ParticleEditor.exe.

... or any other raster image editor.
If you want to add custom images inside your story any editor capable to export .dds and .tga format will be needed.

Links:
Official GIMP Website[www.gimp.org]


CodeLite is a tool used for scripting and programming within the HPL3 engine, for the games SOMA, Amnesia: Rebirth and Amnesia: The Bunker.
It is very much like a text editor, but much more programming-oriented than regular one. It is the tool used officially by Frictional Games to develop their HPL3 games.

Here are some of the relevant features of CodeLite:

• Code documentation on the fly
  
• Code autocompletion and smart code suggestion
  
• Fast and easy way to navitgate through large script files
  
• The ability to run the game from CodeLite

For the scripting guide, CodeLite 12.0.0 will be used, which is the latest stable release that can work with HPL3 without any errors or bugs.

Links:
Main wiki article[wiki.frictionalgames.com]
Setting Up CodeLite[wiki.frictionalgames.com]
Official CodeLite Website[codelite.org]

You absolutely can use systems default or your favourite text editor to work with script files, but in general it is a good idea to setup CodeLite to ease your development. Just mind the following:

引用自 wiki：

You must install CodeLite on the same disk as the game you want to mod. For example, if Amnesia: The Bunker is installed on disk C:, you have to install CodeLite on C: as well.

I got some troubles installing it on linux, and cannot be bothered anymore with it. So atm I myself will stick to not using it, but for windows users I don't see reasons not to use it.

Guide below is copied from here[wiki.frictionalgames.com]

This section explains how to configure CodeLite so it can be suitable for HPL3 scripting, how to create a workspace and a project, and how to import the script files.

1. Download the optimized color theme[wiki.frictionalgames.com]
   
2. Download and install CodeLite version 12.0.0.[downloads.codelite.org]
   
3. Launch CodeLite and configure:
   
   1. Settings → Code Completion → General:
      
      • Add ;*.hps at the end of the Additional file extensions to parse list.
        
      • Enable Keep function signature un-formatted.
        
      • Enable Re-parse on workspace loaded.
   2. Settings → Code Completion → Colouring: Enable Apply context aware colouring.
      
   3. Settings → Code Completion → CTags → Search Paths: Click Add..., navigate to the game folder and select the script folder.
      
   4. Settings → Colours and Fonts...: Click on Import settings from a zip archive and select the CodeLiteColorSettings.zip file you downloaded in step 1.
      
   5. Configure the rest of CodeLite to your liking.
4. Create a new workspace: Create a folder inside your game directory and name it _src. Go to the Workspace menu and click on New Workspace.... Save the workspace inside the _src folder.
   
5. Create a new project: Right click on the workspace → New → New Project. Select Others → Non-code project. Give the project a name (For example: "soma"). Leave the rest as default.
   
6. Add a folder to the project: Right-click on the project and choose New Virtual Folder. Name it _api.
   
7. Add the game script files:
   
   1. Right-click on _api → Add An Existing File..., add the file hps_api.hps from the game folder (If the file does not appear in your game folder, launch the game, and the file will appear).
      
   2. Right-click on the project and choose Import Files From Directory. Navigate to the game folder and select it. In the next window, check the boxes for the folders: maps, script, mods and click ok.

Lastly, go to Workspace and click on Parse Workspace.

That should be it, you should now have three top folders in your project and a lot of sub-folders with various script files. Start typing something, for example Entity_ and a list should appear showing all the functions that begin with Entity_ and the documentation for each selected function.

If the list disappears, you can make it re-appear again by pressing ctrl-space. If you want to bring up hints when inside the () of a function, press ctrl-shift-space.

Warning: CodeLite won't update automatically the location of workspace files. If you moved them outside of CodeLite, you will need to re-add them. The same goes for creating new file after setting up a workspace

The easiest way to create a mod is to go inside Amnesia The Bunker/mods/ and duplicate MinimalCustomMap folder, then rename newly created copy to distinguish it from others. In general it does not matter how this folder is going to be named, it's just for your own convenience.

This folder we duplicated is a mod itself, made by the developer. It contains everything minimally required to be launched and work.

Main folder contains following files: entry.hpc, entry.swd, LauncherPic.png, resources.cfg.
Everything else is stored inside specific directories. Directories are relative to the main game.

So for example levels in base game are stored inside Amnesia The Bunker/maps/ . Therefore levels for your mod should be stored inside Amnesia The Bunker/mods/YourModName/maps/

You can always check how files are stored inside main game and copy its structure.

Engine works in a way, where it prioritizes files for read from the mod to overwrite main game files. For example if you put edited inventory_item_fuel.dds inside YourModName/graphics/inventory/items/, which is exactly in the same place as in main game. When playing your mod, fuel image inside of the inventory will be replaced with your custom one. While in vanilla it will be all normal.

If you followed my advice and copied the folder, you already can launch the game, go to custom story menu and see two MinimalCustomMap mods.

Wiki page describing following[wiki.frictionalgames.com]

Wiki recommends to use the HPL3 Mod Manager[wiki.frictionalgames.com] to configure everything that is listed below, but basic file is easier to setup manually.

entry.hpc is the "face" file of your mod. It is needed so that the mod can be listed by the custom stories menu or simply be started by the game. It's an XML file.


Any valid entry.hpc file (like the one shown above), should have at least the following attributes:


There are special attributes which can be added to a mod entry file in order to enable optional functionalities:


Now open entry file inside your mod directory and edit different attributes to suit your mod. After that you can launch the game, go to custom story menu and make sure you set up everything right.

If your mod is not in the custom story list, it means your entry.hpc file is corrupted or poorly formated and has a typo.

It is a banner image for your custom story that is going to be displayed inside Custom Story menu.
Create your own or edit existing LauncherPic.png.
It should be 640x300 pixels to properly displayed inside of the game.

Also you can rename it to whatever you like, but then don't forget to edit LauncherPic attribute inside of entry.hpc

In order to make the mod load our assets and maps, we need to list where exactly those resources are located. All of the resources for the mod are listed inside a single XML file, called resources.cfg. The file should be located inside the main mod folder.

The syntax for adding a resource directory is as follows:



The file lists directories in which the resources are located at in the form of relative path to the mod. That means you do not need to provide a full path for the folder.

In short - if you add files under directories in your mod, be sure to let the game know that they exist inside of this file.

Wiki article about the following[wiki.frictionalgames.com]

In order to make the mod launch, we need to list some configurations and settings that affect the initialization of the mod. All of the configurations are listed inside a single XML file, called main_init.cfg. The file should be located inside the config folder of the mod.

These are the full settings that can be inside, don't copy it. It is just for you knowledge if you gonna need it later.








base_english.lang is used mainly for engine spicific localizations, like main menu buttons, key name, difficulty name, etc.
english.lang is for in-game localization itself. Notes, item names, hints, etc.

If you did copy the MinimalCustomMap mod folder, your main_init.cfg will look like this

Lets edit few parameters for the future.

• MainSaveFolder: Where save files for your custom story will be stored inside of MyDocuments/ . Usually it is you mod name typed in PascalCase.
  
• GameName: Name of the game displayed inside of taskbar and window title. Same, you can put your story name here but to look nice.
  
• And finally Inside of StartMap key we change File. It defines the first level which will be loaded when you launch your story. Let's change it to my_first_map.hpm, as in the next step we are finally going to launch LevelEditor.

Also about Pos. It is used to position player on initial level load. It is a name of an entity inside of the level itself. We're not going to change it right now.

And the result will look like this:

Amnesia: The Bunker has different syntax for the StartMap key.


Level specified under Main attribute will launch if you select No, when inside of the game it asks you to skip the intro. Same way, level defined under PostIntro attribute is launching if you select to skip intro. If you're not planning to utilize this feature, you can use old format.

Okay, finally basic setup is finished and explained. We can launch LevelEditor.exe.


This is the window you're gonna see when first launch the editor.

Yeah, don't be surprised tool is almost 15 years old, not much changed since Penumbra days.

Like many other game editors it has toolbar on the left; 4 main viewports and inspector on the right.

I'm not going to describe each tool right now. You can experiment later by yourself. Instead I will explain it in more detail once we going to use each tool.

You can hover over each tool icon for its name hint to appear.


This is the main work area with following divisions:


Next, for the sake of easing understanding of basic controls. Select Static Objects Tool. Then in the inspector, select any of these 4 arches, and place it 3D viewport by clicking LEFT MOUSE.



And with the following result; Let's look at basic movement controls.


By pressing 1 on your keyboard, you can quickly switch to Select Tool.

Hotkeys for each tool are from 1 to 0 on a keyboard, then for 11th and futher it is CTRL + number.

Clicking on any entity with Select tool will highlight it. To deselect, just click anywhere on empty space.

While object is selected you can transform it. 3 basic transform modes are available. Translation, Rotation and Scale. To switch between these modes you either use hotkeys [Q, W, E] in relative order, or select by mouse with these icons on the right.

In each mode whenever you hover over a pivot, it is going to highlight in yellow, meaning if you click, you will edit object in this axis.


To have a better look on your level you can move the camera around. You could notice that when you hover over each rectangle its border becomes red. It's the same here, red border means that next actions will take place inside this specific viewport.

You can press SPACE while hovering over needed viewport to make it full screen. Then press SPACE again to switch back. Very handy, you will use it a lot.

Before moving around camera it is good to learn another hotkey. When you have a selected object you can always press F to focus on object. It will center view inside each viewport on that object. Use it if you get lost or you need to get a closer look.

Next, while holding ALT, the border will become yellow. It means that cameras view is being manipulated inside selected viewport. With this you can:

• Rotate camera around pivot with ALT + LEFT MOUSE BUTTON (Only in 3D view)
  
• Zoom in/ out with ALT + RIGHT MOUSE BUTTON or SCROLL WHEEL UP/ DOWN
  
• Move camera's pivot to other coordinates along the grid with ALT + PRESS SCROLL WHEEL

This was 'Maya' set of controls. In addition if you open View context menu on 3D window and go to Controller, you can change it to Fly. This will allow you to move as with noclip in any other game. While holding ALT, use WASD to move & MOUSE to look around.

Note that viewport remains selected even when you move cursor outside, all while ALT is held.

I'm lazy atm. Instead of writing everything down. Look at this 32 minute long video from dev instead, he will explain how to create a simple box. Later I'll maybe edit this section to suit everything else.

Everything he explains and does is actual to Amnesia: The Bunker. Only difference is it was shown on SOMA base with different models and textures, no big deal. Also maybe skip scripting section for now. Imho no need to do it before you have a basic final layout of your map.

TLDR; Select Static Object Tool, on right side in the inspector open bunker folder, then select bunker_wall. Choose from any of the objects and place inside the level, experiment, have creative fun. Then try different directories with other objects.

Soon, very important to explain.

Since creating a mod takes a lot of time testing, to someone it might be a nice idea to launch NoSteam version of the game. it is located inside main game folder with name: AmnesiaTheBunker_NoSteam.exe. You can add it into steam library to get a quick access.

As well, instead of launching the game, then going through custom story menu each time, I recommend to setup few launch options. Right-click your game inside steam library, select Properties.... There in the launch options field add:

• -mod local:YourModFolderName
  
  • this will begin to launch your mod from the start, instead of loading vanilla at first
• -map "mods/YourModFolderName/maps/map_to_launch.hpm"
  
  • this will launch specified map from the start, it overwrites one set in main_init.cfg

Or for windows users, you can create a .bat file:


Developer Launch Commands[wiki.frictionalgames.com]

...

Before continuing, consider using LangEditor.exe for easier and safe editing of language files. Otherwise regular text editor is a viable option.

Every text that you see in game is set inside of this file. It is quite simple, you set a KEY and its VALUE. Then inside other scripts you adress the KEY and script comes to .lang for result.

Your .lang file does not need to contain everything from vanilla game. Better insert only your custom additions inside, or if you want to overwrite original labels.

To begin adding a new note:

1. Open config/lang/english.lang (or other .lang files if you have different default). Inside
   
2. Add/ Find category key of "NotesUI"
   
3. Inside of this category add entry key, then define its name and content
   
   • NAME is set inside opening tag, like this <Entry Name="NameHere">
     
   • CONTENT is set between tags <Entry>Content Here, any characters and numbers that games font supports!!</Entry>

Since The Bunker has feature to filter notes by author and dates, we also define special keys for each author or date we might have in the game, you will see later how they are used.

When adding entries for notes MAKE SURE that names for title and description contain "_Name" & "_Desc" suffixes accordingly, at the end.

[br] tag moves text to the next line. Use two of them in a row, you have empty line between paragraphs.

Language files update on the fly when you reload your map. If something is not showing correctly in the game, or is not updating, then your language file is probably corrupted and cannot be read by the engine. Check for any typos or wrong characters.


Now we need readables.cfg file. It containts entries for every note and photos that you can open inside of your story. If inside language we defined what player would see, in this one we put info for the engine. Fastest way is to duplicate vanilla file and edit it. You can delete each entry between <Notes> tags. But keep commented section above where it describes what each attribute does. Other way you can find them all below:



It is not needed to add each attribute, these 3 should do the job most of the times.

Last step is to open your level inside level editor. Select Entity Tool, inside seach type note, select any of the paper entities (or find your own made) and put inside the level. Then select it, and in the Entity tab in the inspector (right menu), open Readable dropdown menu. There, inside of ID field, type ID of the note from readable.cfg which you decide to pick up.

That should be it, load/ reload level and check the results. Via text guide it might look complex, but it is really, very simple order of actions.

Soon

Main source of different info chunks besides trying things out myself:
Frictional Games Wiki[wiki.frictionalgames.com]

Not everything is going to work in The Bunker, but still base is the same as games use same engine version - HPL3.
TechOFreak128's Amnesia: Rebirth Custom Story Creation Tuturials Playlist

Channel has modding sections for each of FG games, so you can try asking for help there anytime:
Frictional Games Discord[discord.com]