User Tools

Site Tools



Importing Models from HPL2

Importing models from HPL2 to HPL3 is not a complex process but will involve needing to “convert” textures to a format that HPL3 understands. There are some problems which you may face, and this tutorial is here to try and tackle some of the errors and give you a basic idea of importing models from Amnesia: The Dark Descent and Amnesia: A Machine For Pigs.

Please refrain from importing these models and releasing the entirety of them. By following this tutorial, it is assumed you have a legally purchased copy of Amnesia: The Dark Descent and/or Amnesia: A Machine For Pigs. While I cannot stop you from performing these steps, please consider some respect for the modellers and their works by purchasing the games.

Converting HPL2 Textures to HPL3

Not too long ago, Frictional released the Amnesia: The Dark Descent Asset Pack, giving us the wealth of A:TDD assets to use in HPL3, which is great news if you are an Amnesia modder looking to venture into the (albeit, semi-scary) world of HPL3 scripting. However, if you are planning on making a mod that doesn’t involve underwater stations and bloodthirsty anglerfish, then you’ll probably be pulling assets from Penumbra and Machine for Pigs as well.

When loading a Machine for Pigs asset (for example) into the HPL3 Model Viewer, you’ll likely be confronted with this:


(Assets placed into a single folder before loading the model):

Machine for Pigs\static_objects\new_church\pillar:


Machine for Pigs\static_objects\new_church:

You’ll notice that the lighting reacts very strangely when using “Keylight on Camera” and that an odd green sheen can be seen tween the edges in the scene. This is because of a change over the way that specular textures ( and normal textures ( are interpreted in HPL3.

This section will present a guide of how to convert these specular and normal textures from HPL2 format to HPL3 format using Photoshop CS6 with the Nvidia DDS Exporter plugin . GIMP users can also follow the manual process below provided the GIMP DDS exporter is installed.

Converting a Specular Texture

Method 1: Photoshop Script

  1. Save the following block of code in an administrative-level text editor as HPL2specConvert.jsx under

C:\Program Files\Adobe\Adobe Photoshop CS6 (64 Bit)\Presets\Scripts\ (or wherever your Photoshop installation is…)

if (documents.length> 0) {
alert("Document is open, press ok to convert.");
var theImage = app.activeDocument;
// Unlock background layer
var layers = activeDocument.layers;
var layer = layers[layers.length - 1];
// rename Background layer
if (layer.isBackgroundLayer) { = 'Background';
// Save channel names
var red = theImage.channels.getByName("Red");
var green = theImage.channels.getByName("Green");
var blue = theImage.channels.getByName("Blue");
if (theImage.channels.length> 3){ // If there are 4 channels, alpha is probably last one
var alpha = theImage.channels[theImage.channels.length - 1]
var alpha = theImage.channels.add(); = "Alpha 1";
var aChannelArray = new Array();
// Set only GREEN channel active
aChannelArray = new Array();
aChannelArray[0] = green;
theImage.activeChannels = aChannelArray;
// Select all
// Copy
// Set alpha channel active
aChannelArray = new Array();
aChannelArray[0] = alpha;
theImage.activeChannels = aChannelArray;
// Paste
// Set only RED channel active
aChannelArray = new Array();
aChannelArray[0] = red;
theImage.activeChannels = aChannelArray;
// Select all
// Copy
// Set GREEN active and paste
aChannelArray = new Array();
aChannelArray[0] = green;
theImage.activeChannels = aChannelArray;
// Set BLUE active and paste
aChannelArray = new Array();
aChannelArray[0] = blue;
theImage.activeChannels = aChannelArray;
aChannelArray = new Array();
aChannelArray[0] = red;
aChannelArray[1] = green;
aChannelArray[2] = blue;
// now activate them for realz
theImage.activeChannels = aChannelArray;
else {
alert("No doc open");

2. Open the specular texture in Photoshop and run the script from File > Scripts > HPL2specConvert

3. Save as a .DDS file of type DXT5, preferably with “_spec” still appended to the end of the filename

Method 2: Manual

  1. Open the specular texture in Photoshop.


An HPL2 image such as this AAMFP texture will appear as green, because HPL2 relies on the individual channels for specular information, where Red = Intensity, Green = Power, and Blue = Unused (black) . The HPL3 format relies on Red, Green, and Blue for Intensity, and relies on the Alpha channel for Power.

For more information, look at the HPL3 Modeling Tutorial

Our goal is to create a copy of the intensity channel on the Red, Green, and Blue channels, and move the power channel to the Alpha channel.

2. Go to the “Channels” tab next to Layers, and select only the green channel. Select with Ctrl-A and copy the channel to the clipboard.

3. If an “Alpha” channel already exists, select it, otherwise create a new channel using the button at the bottom of the pane and paste into the Alpha layer.


4. Select the Red channel, Ctrl-A, copy, then select the Green channel and Blue channel individually, pasting the same (red channel) clipboard image each time


5. Save as a .DDS file of type DXT5, preferably with “_spec” still appended to the end of the filename


Converting a Normal Texture

  1. Simply open the normal texture (typically _nrm appended to filename) and save using the NVIDIA exporter in the 3DC format . Do not forget to switch this back to DXT5 when exporting other DDS textures.


If all is well and good, you should have an asset with working lighting and proper specular highlights, ready for you to place in your HPL3 map.

Note that if the object is an entity, you might have to open the .ent file with the Model Editor and save the file again, then test to see that the entity is still functioning properly and make adjustments- see the below sections .

Importing to the Level Editor

How can I import Static Objects?

Static Objects are arguably, very easy to import. After converting the textures, it is more or less just a copy and paste of the static_objects in question (plus their textures) into SOMA's static_objects folder, or your mod's directory. For the sake of examples, I will use mansionbase, since mansionbase is probably the most common.

Create a new folder in your SOMA's static_objects directory and call it amnesia. If you are using Steam on a Windows system, this is the directory you should be making:

C:\Program Files (x86)\Steam\steamapps\common\SOMA\static_objects\amnesia

Paste any Amnesia static_object folder(s) into there, then modify the textures. In my particular case, I have only added mansionbase, thus I have this layout right now.

That should be it! However, some static_objects may not work correctly; for example, their texture may not appear in the editor or in game. Check out the troubleshooting heading below for how to fix those kinds of problems!

How can I import Entities?

Entities are imported by a similar method to static_objects, however there is an additional step. For this example, I will use the furniture > bath model from Amnesia: A Machine For Pigs.

Create a new folder in your SOMA's entities directory and call it amnesia. If you are using Steam on a Windows system, this is the directory you should be making:

C:\Program Files (x86)\Steam\steamapps\common\SOMA\entities\amnesia

Paste any Amnesia entity folder(s) into there. In my particular case, I have enemies and the furniture, thus I have this layout right now. Within furniture, I have the bath entity. Just like the static objects however, you may have problems with textures loading incorrectly, check the troubleshooting below.

Now because you are dealing with entities, you can specify the behaviour it has. You can define if you can grab the entity, push it, make it an item or even into an enemy (with no animations).

To get started, open it up with the Model Editor. You can do this by running the Model Editor from the SOMA folder and using File > Open to open the .ent file of the imported model(s). For this particular example, I opened the bath model.


In the top left corner, click Entity settings > Class. It will load up a window similar to the one in the next image.

To show off what you can do to any entity in the game, I decided to make the bath a prop_grab. Which means, I can hold the bath like if it were a chair in SOMA. I also added the bloody bath model to show that I cannot grab it (because it is a StaticProp object, which, most entities will be by default when imported).


Then I created a terrible map to test it with. Notice how I have both Amnesia: The Dark Descent mansionbase static objects and Amnesia: A Machine For Pigs entities?


Then I tested the map and I have a bath which I can lift with one hand, and one I cannot lift at all.


And that's how you import Entities into the game! Have fun!

How can I import Enemies?

Editing the enemies to have their own sounds requires making a new class for those enemies in SOMA's Script folder. In the below tutorial, the Brute will mimic the Construct sounds.

Import the enemies just like in the entity tutorial above until you get to the Model Editor step. Load up the enemy. You may get a prompt when loading up the enemy. Just press OK and you should be good to go. In the case of Amnesia's notorious Servant Brute, we will load it up and be greeted by this.


Load up the Class prompt by clicking Entity Settings > Class. For now, change the Class to Agent_Infected_Robot as it is the closest class to the Brute's (and the grunt for that matter) behaviour. If you are importing one of the suitors from Justine, to keep them blind, use the Agent_Puppet class.


In the bottom, click on the gears, then in the bottom left corner, click Edit Animations. We will get a window like this:


SOMA does not use all of these animations. It uses only a few of them. What we have to do is show SOMA where these animations can be found. Using the Entity > Class window, scroll down to CharMover and expand the tab. Fill it with the animation entries as they appear on the right side - case sensitive. And if you want, and understand how head turning works, you can try editting the options below.


Exporting in a Campaign or Mod

Just make sure to include them in your mod in some way. The filename of the model has to match the “mesh filename” which you can see in the Level Editor, which should be okay if you don't suddenly change the file names. Make sure the folder you put the assets in is referenced in the resources.cfg file.


My Model is not appearing correctly. Why?


This will generically be caused by one of two things:

  1. The model cannot find all connected submeshes.
    This means that there is a model or .dae file missing. You will know this is the case if when you place down a model and it does not appear in the editor (see the image above), and upon clicking where it is placed, does not actually select the model. To fix this, you'll need to open the model in the HPL2 Model Editor and locate where the referenced models are located in The Dark Descent or in Machine For Pigs. Make sure you copy all of them over into your SOMA directory, and it would be a good idea to try and keep them as close to the original directory as possible.
  2. The model has all of its components but not its material (or all of its textures).
    This means you do not have the material or the textures (or even just the diffuse texture) in a recognisable location for your entity or static object. An example that comes to mind is the towels in A Machine For Pigs, as they base their texture off a carpet material file. To check what material it uses, you can open up the model in the HPL2 Model Editor and press the [+] button next to the mesh. It should show you the name of the .dds textures. Most of the time, all the materials and .dds files will appear there, but you can get all of them.

When testing my level, my model appears at XYZ = 0.

This is a problem caused by the meshes of some Amnesia: A Machine For Pigs models. I do not know if these problems will persist in HPL3, but if it does, the simplest way is to delete the .msh and the .anm files if there are any included with that particular model. That will generate a new .msh file which HPL3 can recognise.

Other problems? Questions?

If you have any questions or face other problems, please, feel free to start a thread in the Frictional Games Discord Server

hpl3/community/other/hpl2_import.txt · Last modified: 2020/02/11 19:43 by timan