Frictional Wiki - User contributions [en]

HPL2/Development Environment

2024-07-15T10:45:10Z

Darkfire: Add a mention of AddDebugMessage

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:

#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). If your mod is an FC, do this in its save folder.
#Open main_settings.cfg and change set the following options:
##<code>LoadDebugMenu="true"</code>
##<code>ShowPreMenu="false"</code> (this will skip you some waiting on each game launch)
##<code>SaveConfig="false"</code> will make sure that the in-game option changes don't overwrite changes to this file
##Optional: <code>ExitMenuDirectly="true"</code> if you wish to exit the game without visiting the main menu
##<code>ForceCacheLoadingAndSkipSaving="false"</code>, otherwise certain map changes might not show! You will sometimes need to delete the map's cache file even with this setting
#Open user_settings.cfg (in the "Dev" folder) and set the following:
##<code>AllowQuickSave="true"</code> ('''F4'''=save, '''F5'''=load)
##<code>ScriptDebugOn="true"</code>. This makes debugging easier (more on that below)
#In order to avoid running into "File index out of bounds" errors in the Level Editor, edit the file '''resources.cfg''' located in the root the directory of Amnesia and add the ''custom_stories'' directory to the end of the list. This will also make custom assets load in the editors.

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 into a map before making changes to its script.}}

By setting <code>ScriptDebugOn="true"</code> you have set the script function <code>ScriptDebugOn()</code> to return true. This is quite useful, as you can add something like this in your startup code:
<syntaxhighlight lang="cpp">if(ScriptDebugOn()) {
//Do your setup stuff
}</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. 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.
This can make debugging much easier; in particular, if something isn't working, you can print a message to see if your code is being executed at all.

Now you should be ready to start some editing!

==Loading directly into a map==
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> (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).
##<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.

Hpl2:Tutorials:level editor:tutorial 6

2024-06-07T09:49:22Z

Darkfire: add clean up template

{{Template:Cleanup}}
= Level Editor - Useful tricks (in progress) =

While The Basics and Light tutorial are great enough to create atmospheric maps, there are some things that can easily help achieve interesting results.

== Billboards ==

[http://www.youtube.com/watch?v=Sw4du21rNqc Demonstration]

Step by step tutorial. Starting with easy way to setup and control billboards for your map, and continuing to more advanced effects.

First make sure you have read and understood [http://wiki.frictionalgames.com/hpl2/tutorials/level_editor/tutorial_1#billboards_particles this].

''' '''

'''Start off by creating a billboard and a point light and connect the billboard into the point light. ''' This helps you control the color value of every billboard you duplicate from the original connected billboard. Keep all of the billboards colors at 1 value. (That one extra point light in the picture is useless for the first parts)

[http://i1237.photobucket.com/albums/ff478/Khyrpa/WikiTutorial/BB_01.jpg?nolink&800x489]

Then align your billboards properly into your window. Some videos about creating billboards. These are done without the connection to light, but the placement should be okay:

[[http://www.youtube.com/watch?v=Jb0xJRBO2d8&t=3m37s|Office hlp2 level editor[P2] (billboards, lighting)]]

[http://www.youtube.com/watch?v=u8EhP59tmjA Billboard Action Amnesia level editor ]

[http://i1237.photobucket.com/albums/ff478/Khyrpa/WikiTutorial/BB_02.jpg?direct&800x480]

Then tinker with the color of the connected point light and adjust the lenght and width of the billboards. This is the hardest and time consuming part about billboards. Make sure to often check in game because billboards look different there and you can see if they look good from every angle.

[http://i1237.photobucket.com/albums/ff478/Khyrpa/WikiTutorial/BB_03.jpg?direct&800x482]

'''That was it for simple billboards, but if you continue, you get to the interesting parts!'''

To create nice billboards, not all of them should be of the same color, so create another point light and connect the billboards that you think need different colors to other point lights (here the billboards on the edges were picked). For simplicitys sake I keep them connected to only 2 point lights, but if you think you need more variation go for more. (Colors changed so you can see better what I did)

[http://i1237.photobucket.com/albums/ff478/Khyrpa/WikiTutorial/BB_04.jpg?direct&800x479]

'''Flicker effect'''

You can create the flickering effect with various methods. First and easiest one would be to use the point lights own flickering settings inside the level editor. Tweak the Off Color and Diffuse Color to suit your liking. Example settings:

[http://i1237.photobucket.com/albums/ff478/Khyrpa/WikiTutorial/BB_05.jpg?nolink&]

Using the level editor only is not as interesting as randomly changing colors of billboards and every light that acts as the windows shine in sync with script.

So next phase would be to set up additional lights to the window, spot light and some ambient point lights in this case. Name them so you can easily track what they are. In this case I named mine like this:

window_light_bright_1 (spot light with gobo ('''Rotate the gobo if its upside down'''), I want this bright)

window_light_bright_2 (point light close to window, bright also)

window_light_dark_1 (large point light)

[http://i1237.photobucket.com/albums/ff478/Khyrpa/WikiTutorial/BB_06.jpg?direct&800x480]

Then the rest is up to script. Example script for controlling, very simple vers. You can tweak the ideas around alot. Like this one does not change the color of the lights into same color as the billboards.

<syntaxhighlight lang="c">void FlickerTimer(string &in asTimer)
{
float ftimer = RandFloat(0.6f,1.6f);
FadeLightTo("bb_bright", RandFloat(0.2f,0.3f), RandFloat(0.2f,0.35f), RandFloat(0.3f,0.39f), 1, -1, ftimer);
FadeLightTo("bb_dark", RandFloat(0.15f,0.29f), RandFloat(0.18f,0.35f), RandFloat(0.35f,0.39f), 1, -1, ftimer);
for(int i=0;i<2;i++) FadeLightTo("window_light_bright_"+i, RandFloat(0.55f,0.7f), RandFloat(0.69f,0.8f), RandFloat(0.8f,0.9f), 1, -1, ftimer);
for(int i=0;i<2;i++) FadeLightTo("window_light_dark_"+i, RandFloat(0.4f,0.5f), RandFloat(0.5f,0.6f), RandFloat(0.6f,0.7f), 1, -1, ftimer);
AddTimer("repeat", ftimer, "FlickerTimer");
}
</syntaxhighlight>

Then here is the one I used for the demonstration video clip. (Can cause performance issues when done with lots of billboards and particles, I haven't tested…). Minor tweaking, added spawn areas for particles and finetuned the script for long. The script could be done more efficient, if someone can, please edit!

[http://i1237.photobucket.com/albums/ff478/Khyrpa/WikiTutorial/BB_07.jpg?direct&800x483]

<syntaxhighlight lang="c">void OnEnter()
{
AddTimer("start", 0, "FlickerTimer"); //Starts the loop
SetLocalVarInt("EventInt", 1); //sets the timer to loop case 1
//Spawn particles to bb_particle_+i areas and fog_particle_+i areas
for(int i=0;i<3;i++) CreateParticleSystemAtEntityExt("blue_particles", "ps_light_dust_large.ps", "bb_particle_"+i, true, 0.6f, 0.75f, 1.0f, 1, true, 1, 2, 8, 11);
for(int i=0;i<3;i++) CreateParticleSystemAtEntityExt("blue_fog_particles", "ps_area_fog.ps", "fog_particle_"+i, true, 0.6f, 0.75f, 1.0f, 0.8f, true, 1, 2, 8, 11);
}

void FlickerTimer(string &in asTimer)
{
//This stores the rand float into VarFloat so the amount can be checked later
SetLocalVarFloat("CheckBrightness", RandFloat(0.20f,0.32f));
//This takes the random float from VarFloat so it can be easily placed into functions
float fMainColor = GetLocalVarFloat("CheckBrightness");
//This is the color for the bloody red lights for case 2
float fBloodColor = RandFloat(0.3f,0.45f);
//This tells how long fading the lights in takes and when the loop timer triggers this again
float ftimer = RandFloat(0.4f,0.7f);
//This switch function is placed here so you can easily control the lights and later if necessary, add more cases to have more control
switch(GetLocalVarInt("EventInt"))
{case 1: //This part loops forever when EventInt is 1
//These 2 below are for the lights that only control billboards, billboards look brighter than the light source
FadeLightTo("bb_bright", fMainColor+0.08f, fMainColor+0.05, fMainColor+0.1, 1, -1, ftimer);
FadeLightTo("bb_dark", fMainColor+0.01f, fMainColor, fMainColor+0.04, 1, -1, ftimer);
//To get greater sync and effect, I made these to check when the billboards were bright or dark
if(GetLocalVarFloat("CheckBrightness") <0.26f){
for(int i=0;i<2;i++) FadeLightTo("window_light_bright_"+i, fMainColor+0.22f, fMainColor+0.27f, fMainColor+0.43f, 1, -1, ftimer);
for(int i=0;i<2;i++) FadeLightTo("window_light_dark_"+i, fMainColor+0.13f, fMainColor+0.19f, fMainColor+0.24f, 1, -1, ftimer);
}
//If you dont use something similar to this, the change in lights stay way too small and it can look stupid
if(GetLocalVarFloat("CheckBrightness")>= 0.26f){
for(int i=0;i<2;i++) FadeLightTo("window_light_bright_"+i, fMainColor+0.31f, fMainColor+0.36f, fMainColor+0.58f, 1, -1, ftimer);
for(int i=0;i<2;i++) FadeLightTo("window_light_dark_"+i, fMainColor+0.2f, fMainColor+0.27f, fMainColor+0.3f, 1, -1, ftimer);
}
break;
case 2: //Changes colors to red when EventInt is 2
FadeLightTo("bb_bright", fBloodColor+0.08f, fBloodColor-0.3f, fBloodColor-0.3f, 1, -1, ftimer+0.3f);
FadeLightTo("bb_dark", fBloodColor+0.02f, fBloodColor-0.3f, fBloodColor-0.3f, 1, -1, ftimer+0.3f);
for(int i=0;i<2;i++) FadeLightTo("window_light_bright_"+i, fBloodColor+0.28f, fBloodColor-0.3f, fBloodColor-0.3f, 1, -1, ftimer+0.5f);
for(int i=0;i<2;i++) FadeLightTo("window_light_dark_"+i, fBloodColor+0.15f, fBloodColor-0.3f, fBloodColor-0.3f, 1, -1, ftimer+0.5f);
break;
}
//This is the actual loop here, there is nothing that will stop this timer so it will all the time (unless RemoveTimer is used)
AddTimer("repeat", ftimer, "FlickerTimer");
}

//Below is the script I used to jump to case 2 and red lighting, (Interact callback set inside level editor)
void Touched(string &in asEntity)
{
//Sets EventInt to 2 so case 2: is triggered when the looping timer next time triggers
SetLocalVarInt("EventInt", 2);
//just a quick effect to make things look better for demonstrations sake...
StartScreenShake(0.01f, 0.9f, 0.2f, 0.2f);
//destroyParticles, removes the old light particles outta the way. Takes a long time for the fog to disappear, but I can't help that
DestroyParticleSystem("blue_particles");
DestroyParticleSystem("blue_fog_particles");
//create new ones, this had to be placed inside the callback because looping timer would just create new ones ontop each time it loops
for(int i=0;i<3;i++) CreateParticleSystemAtEntityExt("red_particles", "ps_light_dust_large.ps", "bb_particle_"+i, true, 1.0f, 0.1f, 0.1f, 1, true, 1, 2, 8, 11);
for(int i=0;i<3;i++) CreateParticleSystemAtEntityExt("red_particles", "ps_area_fog.ps", "fog_particle_"+i, true, 1.0f, 0.1f, 0.1f, 0.9f, true, 1, 2, 8, 11);
}
</syntaxhighlight>

So in the end that loop could control all the billboards and lights needed in a map. The flickering effect might be very small buff to levels looks for the headache it could cause, but keeping billboards connected into lights makes changing colors '''MILLION ''' times more pleasant. It can also be used to for example: cool scares and changing light coming from outside from day to night

HPL2/Tutorials

2024-06-07T09:42:27Z

Darkfire: /* Video tutorials */ remove link which was replaced by an inlined list

This page lists a large amount of tutorials, most of which are community-made.

Don't know where to start? Check out [https://www.youtube.com/playlist?list=PLIYfl4qBRihBjRpmQL-izQ4xdAtLblU36 Mudbill's video tutorial series].

{{tip|If you can't find a tutorial for what you need, make sure to check the [[HPL2/Tools#Editors|Editor documentation]] and [[HPL2/TDD#Documentation|Engine documentation]]. An example of this would be the Particle Editor.}}

==Text tutorials==

===Level Editor===

*[[:hpl2:tutorials:level_editor:tutorial_1|Tutorial 1]] - The minimum required to get a level that can load.
*[[:hpl2:tutorials:level_editor:tutorial_2|Tutorial 2]] - Placement of lights and advanced setup of lights.
*[[:hpl2:tutorials:level_editor:tutorial_3|Tutorial 3]] - How to make an outdoor environment. There's a [[Hpl2:Tutorials:level_editor:outdoors|newer version of i]]t available.
*[[:hpl2:tutorials:level_editor:tutorial_4|Tutorial 4]] - Explains how to make water.
*[[:hpl2:tutorials:level_editor:tutorial_5|Tutorial 5]] - Prop dimensions and detailing your map.
*[[Hpl2:Tutorials:level editor:tutorial 6|Tutorial 6]] - ???????
*[[HPL2/Tutorials/Skyboxes|Tutorial 7]] - Making skyboxes for HPL2
*[[HPL2/Tutorials/Level Design]] - Using all of the basic techniques to achieve good effects
*[[:hpl2:tutorials:level_editor:level_editor_101|Level Editor 101]] - All the basics and some more advanced techniques.

===Model Editor===

*[[:hpl2:tutorials:model_editor:tutorial_1|Basic tutorial]] - The minimum required to load a model as an entity with collision and game properties.
*[[:hpl2:tutorials:model_editor:tutorial_2|Creating Ragdoll Entities]] - How to create full physics-based entities.
*[[:hpl2:tutorials:model_editor:static_objects_jenniferorange|Making Items Static]] - How to change an items' properties to static.
*[[HPL2/Tutorials/Coin_chests | Coin chests]] - How to create chests that can be only opened with coins.

===Material Editor===

*[[:hpl2:tutorials:material_editor:tutorial_1|Tutorial 1]] - Basic materials and their properties.
*[[Hpl2:Tutorials:material editor:creating mirrors|Creating mirrors]] - make reflective surfaces using water materials

===Game files===

*[[:hpl2:tutorials:script:CustomSounds|How to create Custom Sounds]] - Teaches how to create custom sounds for your custom story.
*[[:hpl2:tutorials:script:howtomakenotes|How to Create Notes and Journal Entries]] - Explains how to make journal entries and place them in a map
*[[HPL2/Tutorials/Porting MFP Assets|Porting MFP Assets]] - explains how to copy assets from MFP to TDD and avoid issues
*[[HPL2/Tutorials/Convert HDRI to skyboxes|Convert HDRI to skyboxes]]

===Scripting tutorials===
General basics:

*[[HPL2/Tutorials/Scripts/Debugging|Make your set-up comfortable for scripting]]
*[[:hpl2:tutorials:script:entihscript_beginner|Newbie's Guide to Scripting]] - A tutorial for those new to scripting, focusing on syntax and a few helpful hints - ''By 'Entih''
*[[:hpl2:tutorials:script:tutorial_1|Tutorial 1]] - Using a tutorial level, with some objects to make basic scripts.
*[[:hpl2:tutorials:scripting:messages_jenniferorange|Activating/Using Message Pop-Ups]] - Explains how to activate a message to appear when walking into a script area.
*[[:hpl2:tutorials:scripting:triggering_monsters_on_entities|Triggering monsters on entities]] - Explains how to trigger an event after picking up an item.

Door-related script tutorials:

*[[:hpl2:tutorials:script:scripting_by_xtron_-_item_that_unlocks_a_door|Item That Unlocks a Door]] - How to make an item that unlocks a certain door.
*[[:hpl2:tutorials:script:buttons_that_open_a_door|Buttons that open door]]s - Explains how to make buttons that open doors.
*[[:hpl2:tutorials:script:events|Scary door events]] - Explains how to make scary door events.
*[[:hpl2:tutorials:scripting:crowbartutorialjenniferorange|Using A Crowbar On A Door]] - Explains how to script a crowbar to blow open a door.
*[[:hpl2:tutorials:script:adding_messages_to_locked_doors|Adding Messages To Locked Doors]] - Explains how to display a message when a player tries to open a locked door.

Useful coding practices:

*[[:hpl2:tutorials:script:forloop|The "For" loop]] - Explains how and when to use the "for" loop.
*[[:hpl2:tutorials:script:advancedtimers|Advanced Timers]] - Explains how to use multiple timers in one function.
*[[:hpl2:tutorials:script:localandglobalvariables|Local and Global Variables]] - Explains what they are and how to use them correctly.
*[[:hpl2:tutorials:script:sequences|Scripting Sequences]] - Explains how to build simple and easy to use cutscenes, or sequences for your mod.

Forces and impulses:

*[[:hpl2:tutorials:script:force|Impulse and forces]] - Explains how to use force and impulse.
*[[:hpl2:tutorials:script:pushdoorsopen|Push doors open using force]] - Explains how to use Force to open doors and entities.
*[[Hpl2:Tutorials:level_editor:dynamic_curtains|Dynamic curtains]] - Using force to simulate wind
*[[:hpl2:tutorials:script:disable_gravity_tutorial|"Disable" gravity and make objects float]] - Make entities seem to float using timer functions and forces

Other:

*[[:hpl2:tutorials:script:monsterpathnodes|Monster Path Nodes]] - Explains how to set up a monster's path and how to trigger it.
*[[:hpl2:tutorials:script:levers_and_secretshelfs|Levers and secret bookshelves]] - Explains how to make a lever that opens a bookshelf.
*[[:hpl2:tutorials:scripting:scaresbyjenniferorange|Scares]] - Explains in as much detail as possible the multiple scares you can use without having to bring out the monsters.
*[[:hpl2:tutorials:level_editor:combininghammerchipperjenniferorange|Combining The Hammer And Chipper]] - Explains how to combine your hammer and chipper in your inventory.
*[[:hpl2:tutorials:scripting:checkpoints_using_scriptarea_s|Checkpoints using Areas]] - Explains how to make a checkpoint using Areas.
*[[:hpl2:tutorials:script:tutorialsformainmenu|How to create your own Main Menu Backgrounds!]] - The usability of Amnesia's .cfg files and its Editors
*[[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] - Some notes about the ShowScreenImage() function new to ATTD in version 1.5 (and also AAMFP).

===Modeling===

*[[:hpl2:tutorials:modeling:tutorialoutsource|Modeling tutorial]] - Initially written for outsourcers.

==Video tutorials==

<del>Crossed-out videos</del> are unavailable or privated (as of June 2024).

===Sublists===

*[https://www.youtube.com/playlist?list=PLIYfl4qBRihBjRpmQL-izQ4xdAtLblU36 Large playlist of video tutorials for beginners and intermediate developers] - ''By Mudbill''
*[http://www.youtube.com/playlist?list=PLD326789BC99530C8 From Noob to Pro: Amnesia Custom Story Creation Series] - ''By YourComputer''

===By Khyrpa===

*<del>[http://www.youtube.com/watch?v=1R2F2eVmJ5k Building and Lighting in The Level Editor]</del>
*[http://www.youtube.com/watch?v=d2ShkLEgGNk Lighting in Level Editor]
*[http://www.youtube.com/watch?v=u8EhP59tmjA Billboards]
*[http://www.youtube.com/watch?v=LKxzoAIK8jA Advanced Candle Light Connecting]
*[http://www.youtube.com/watch?v=xIDCoEZ581Q Wind Scare (Part 1)]
*[http://www.youtube.com/watch?v=Kj-NFkIGafI Wind Scare (Part 2)]

===Various authors===

*[http://www.youtube.com/watch?v=0grr7uipnk0 How To Create a Custom Story] - ''By TheVegaNVega''
*[http://www.youtube.com/watch?v=uGCTwQQSZ0A How To Make Journal Entries/Notes] - ''By RussMoney''
*[http://www.youtube.com/watch?v=WfgFEG4TSCE How To Make Journal Entries/Mementos] - ''By RussMoney''
*[http://www.youtube.com/watch?v=puIfVx0lslA How To Convert a Custom Story To a Full Conversion] - ''By RussMoney''
*[http://www.youtube.com/watch?v=9uKBYVEyw1s How to convert cube map images to DDS format in the GIMP] - ''By YourComputer''
*[http://www.youtube.com/watch?v=EnCAbgTY6d8 Adding Voice to your Diaries] - ''By triadtimes''
*[http://www.youtube.com/watch?v=vQEdIAZw5gM&feature=plcp&context=C4347014VDvjVQa1PpcFNKLAyG_d-p_QR49e20E_Wo08wpqmVkJz0= How to create a custom main menu background] - ''By CTCommunity''
*[http://youtu.be/Crx5Qd7AgJ0 Using Prop Force: How Do I Know Which Coordinate To Put My Value In?] - ''By JenniferOrange''

===By MulleDK19===

*<del>[http://amnesia.treesoft.dk/tutorials/Tutorial1.wmv Make a key unlock a specific door]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/Tutorial2.wmv How to create and use Areas or Triggers]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial1.wmv Using the Level Editor (Part 1)]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial2.wmv Using the Level Editor (Part 2)]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial3.wmv Using the Level Editor (Part 3)]</del>

===By Simpanra===

*<del>[http://www.youtube.com/watch?v=CklTIT2W4g4 How To Make Level Door]</del>
*<del>[http://www.youtube.com/watch?v=ABI7NUqkXW0 How To Get a Key To Unlock a Door]</del>
*<del>[http://www.youtube.com/watch?v=v4WudNebX08 How To Make Water]</del>
*<del>[http://www.youtube.com/watch?v=ESISPLDbMWM How To Make a Custom Story Background]</del>
*<del>[http://www.youtube.com/watch?v=RmIKTH9YRqk How To Make a Functional and Interactable Ladder]</del>
*<del>[http://www.youtube.com/watch?v=riFwThqQ68k How To Name and Describe Keys]</del>
*<del>[http://www.youtube.com/watch?v=M5x_taEkP8s Simple Script Function]</del>

===By Elven===

[http://www.youtube.com/user/elvengames Youtube Channel link]

*<del>[http://www.youtube.com/watch?v=jGJluxjcGCg Basics of the Basic]</del>
*<del>[http://www.youtube.com/watch?v=IKJIT05V00Y When is it syntax and when not?]</del>
*<del>[http://www.youtube.com/watch?v=1x3mTmvbSmc Make your life easier: Notepad++ with plugin & Debugging]</del>
*<del>[http://www.youtube.com/watch?v=zDhPJByYAec So, how the duckling I install hps support?]</del>
*<del>[http://www.youtube.com/watch?v=Pv9GK5Gh4Bw Scripting Functions (intro)]</del>
*<del>[http://www.youtube.com/watch?v=yYPfWC5nCrk Timers]</del>
*<del>[http://www.youtube.com/watch?v=EhUjbK_vEhM Piano Scare (Request)]</del>
*<del>[http://www.youtube.com/watch?v=jPaRHHlepKw Adding Credits]</del>
*<del>[http://www.youtube.com/watch?v=bTzWAQJMnz8 Setting up development mode]</del>
*<del>[http://www.youtube.com/watch?v=idK5VSTqDrs Loopable timers - LIMITED EDITION (Specific amount of times)]</del>
*<del>[http://www.youtube.com/watch?v=DeoDFmcVU8U&feature=youtu.be Hallucination monster scare!]</del>

HPL2/Tutorials

2024-06-07T09:42:04Z

Darkfire: Move stuff to the intro section, add elven's tutorials as a list

This page lists a large amount of tutorials, most of which are community-made.

Don't know where to start? Check out [https://www.youtube.com/playlist?list=PLIYfl4qBRihBjRpmQL-izQ4xdAtLblU36 Mudbill's video tutorial series].

{{tip|If you can't find a tutorial for what you need, make sure to check the [[HPL2/Tools#Editors|Editor documentation]] and [[HPL2/TDD#Documentation|Engine documentation]]. An example of this would be the Particle Editor.}}

==Text tutorials==

===Level Editor===

*[[:hpl2:tutorials:level_editor:tutorial_1|Tutorial 1]] - The minimum required to get a level that can load.
*[[:hpl2:tutorials:level_editor:tutorial_2|Tutorial 2]] - Placement of lights and advanced setup of lights.
*[[:hpl2:tutorials:level_editor:tutorial_3|Tutorial 3]] - How to make an outdoor environment. There's a [[Hpl2:Tutorials:level_editor:outdoors|newer version of i]]t available.
*[[:hpl2:tutorials:level_editor:tutorial_4|Tutorial 4]] - Explains how to make water.
*[[:hpl2:tutorials:level_editor:tutorial_5|Tutorial 5]] - Prop dimensions and detailing your map.
*[[Hpl2:Tutorials:level editor:tutorial 6|Tutorial 6]] - ???????
*[[HPL2/Tutorials/Skyboxes|Tutorial 7]] - Making skyboxes for HPL2
*[[HPL2/Tutorials/Level Design]] - Using all of the basic techniques to achieve good effects
*[[:hpl2:tutorials:level_editor:level_editor_101|Level Editor 101]] - All the basics and some more advanced techniques.

===Model Editor===

*[[:hpl2:tutorials:model_editor:tutorial_1|Basic tutorial]] - The minimum required to load a model as an entity with collision and game properties.
*[[:hpl2:tutorials:model_editor:tutorial_2|Creating Ragdoll Entities]] - How to create full physics-based entities.
*[[:hpl2:tutorials:model_editor:static_objects_jenniferorange|Making Items Static]] - How to change an items' properties to static.
*[[HPL2/Tutorials/Coin_chests | Coin chests]] - How to create chests that can be only opened with coins.

===Material Editor===

*[[:hpl2:tutorials:material_editor:tutorial_1|Tutorial 1]] - Basic materials and their properties.
*[[Hpl2:Tutorials:material editor:creating mirrors|Creating mirrors]] - make reflective surfaces using water materials

===Game files===

*[[:hpl2:tutorials:script:CustomSounds|How to create Custom Sounds]] - Teaches how to create custom sounds for your custom story.
*[[:hpl2:tutorials:script:howtomakenotes|How to Create Notes and Journal Entries]] - Explains how to make journal entries and place them in a map
*[[HPL2/Tutorials/Porting MFP Assets|Porting MFP Assets]] - explains how to copy assets from MFP to TDD and avoid issues
*[[HPL2/Tutorials/Convert HDRI to skyboxes|Convert HDRI to skyboxes]]

===Scripting tutorials===
General basics:

*[[HPL2/Tutorials/Scripts/Debugging|Make your set-up comfortable for scripting]]
*[[:hpl2:tutorials:script:entihscript_beginner|Newbie's Guide to Scripting]] - A tutorial for those new to scripting, focusing on syntax and a few helpful hints - ''By 'Entih''
*[[:hpl2:tutorials:script:tutorial_1|Tutorial 1]] - Using a tutorial level, with some objects to make basic scripts.
*[[:hpl2:tutorials:scripting:messages_jenniferorange|Activating/Using Message Pop-Ups]] - Explains how to activate a message to appear when walking into a script area.
*[[:hpl2:tutorials:scripting:triggering_monsters_on_entities|Triggering monsters on entities]] - Explains how to trigger an event after picking up an item.

Door-related script tutorials:

*[[:hpl2:tutorials:script:scripting_by_xtron_-_item_that_unlocks_a_door|Item That Unlocks a Door]] - How to make an item that unlocks a certain door.
*[[:hpl2:tutorials:script:buttons_that_open_a_door|Buttons that open door]]s - Explains how to make buttons that open doors.
*[[:hpl2:tutorials:script:events|Scary door events]] - Explains how to make scary door events.
*[[:hpl2:tutorials:scripting:crowbartutorialjenniferorange|Using A Crowbar On A Door]] - Explains how to script a crowbar to blow open a door.
*[[:hpl2:tutorials:script:adding_messages_to_locked_doors|Adding Messages To Locked Doors]] - Explains how to display a message when a player tries to open a locked door.

Useful coding practices:

*[[:hpl2:tutorials:script:forloop|The "For" loop]] - Explains how and when to use the "for" loop.
*[[:hpl2:tutorials:script:advancedtimers|Advanced Timers]] - Explains how to use multiple timers in one function.
*[[:hpl2:tutorials:script:localandglobalvariables|Local and Global Variables]] - Explains what they are and how to use them correctly.
*[[:hpl2:tutorials:script:sequences|Scripting Sequences]] - Explains how to build simple and easy to use cutscenes, or sequences for your mod.

Forces and impulses:

*[[:hpl2:tutorials:script:force|Impulse and forces]] - Explains how to use force and impulse.
*[[:hpl2:tutorials:script:pushdoorsopen|Push doors open using force]] - Explains how to use Force to open doors and entities.
*[[Hpl2:Tutorials:level_editor:dynamic_curtains|Dynamic curtains]] - Using force to simulate wind
*[[:hpl2:tutorials:script:disable_gravity_tutorial|"Disable" gravity and make objects float]] - Make entities seem to float using timer functions and forces

Other:

*[[:hpl2:tutorials:script:monsterpathnodes|Monster Path Nodes]] - Explains how to set up a monster's path and how to trigger it.
*[[:hpl2:tutorials:script:levers_and_secretshelfs|Levers and secret bookshelves]] - Explains how to make a lever that opens a bookshelf.
*[[:hpl2:tutorials:scripting:scaresbyjenniferorange|Scares]] - Explains in as much detail as possible the multiple scares you can use without having to bring out the monsters.
*[[:hpl2:tutorials:level_editor:combininghammerchipperjenniferorange|Combining The Hammer And Chipper]] - Explains how to combine your hammer and chipper in your inventory.
*[[:hpl2:tutorials:scripting:checkpoints_using_scriptarea_s|Checkpoints using Areas]] - Explains how to make a checkpoint using Areas.
*[[:hpl2:tutorials:script:tutorialsformainmenu|How to create your own Main Menu Backgrounds!]] - The usability of Amnesia's .cfg files and its Editors
*[[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] - Some notes about the ShowScreenImage() function new to ATTD in version 1.5 (and also AAMFP).

===Modeling===

*[[:hpl2:tutorials:modeling:tutorialoutsource|Modeling tutorial]] - Initially written for outsourcers.

==Video tutorials==

<del>Crossed-out videos</del> are unavailable or privated (as of June 2024).

===Sublists===

*[https://www.youtube.com/playlist?list=PLIYfl4qBRihBjRpmQL-izQ4xdAtLblU36 Large playlist of video tutorials for beginners and intermediate developers] - ''By Mudbill''
*[[Hpl2:Tutorials:script:elventutorials|Elven's tutorials]]
*[http://www.youtube.com/playlist?list=PLD326789BC99530C8 From Noob to Pro: Amnesia Custom Story Creation Series] - ''By YourComputer''

===By Khyrpa===

*<del>[http://www.youtube.com/watch?v=1R2F2eVmJ5k Building and Lighting in The Level Editor]</del>
*[http://www.youtube.com/watch?v=d2ShkLEgGNk Lighting in Level Editor]
*[http://www.youtube.com/watch?v=u8EhP59tmjA Billboards]
*[http://www.youtube.com/watch?v=LKxzoAIK8jA Advanced Candle Light Connecting]
*[http://www.youtube.com/watch?v=xIDCoEZ581Q Wind Scare (Part 1)]
*[http://www.youtube.com/watch?v=Kj-NFkIGafI Wind Scare (Part 2)]

===Various authors===

*[http://www.youtube.com/watch?v=0grr7uipnk0 How To Create a Custom Story] - ''By TheVegaNVega''
*[http://www.youtube.com/watch?v=uGCTwQQSZ0A How To Make Journal Entries/Notes] - ''By RussMoney''
*[http://www.youtube.com/watch?v=WfgFEG4TSCE How To Make Journal Entries/Mementos] - ''By RussMoney''
*[http://www.youtube.com/watch?v=puIfVx0lslA How To Convert a Custom Story To a Full Conversion] - ''By RussMoney''
*[http://www.youtube.com/watch?v=9uKBYVEyw1s How to convert cube map images to DDS format in the GIMP] - ''By YourComputer''
*[http://www.youtube.com/watch?v=EnCAbgTY6d8 Adding Voice to your Diaries] - ''By triadtimes''
*[http://www.youtube.com/watch?v=vQEdIAZw5gM&feature=plcp&context=C4347014VDvjVQa1PpcFNKLAyG_d-p_QR49e20E_Wo08wpqmVkJz0= How to create a custom main menu background] - ''By CTCommunity''
*[http://youtu.be/Crx5Qd7AgJ0 Using Prop Force: How Do I Know Which Coordinate To Put My Value In?] - ''By JenniferOrange''

===By MulleDK19===

*<del>[http://amnesia.treesoft.dk/tutorials/Tutorial1.wmv Make a key unlock a specific door]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/Tutorial2.wmv How to create and use Areas or Triggers]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial1.wmv Using the Level Editor (Part 1)]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial2.wmv Using the Level Editor (Part 2)]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial3.wmv Using the Level Editor (Part 3)]</del>

===By Simpanra===

*<del>[http://www.youtube.com/watch?v=CklTIT2W4g4 How To Make Level Door]</del>
*<del>[http://www.youtube.com/watch?v=ABI7NUqkXW0 How To Get a Key To Unlock a Door]</del>
*<del>[http://www.youtube.com/watch?v=v4WudNebX08 How To Make Water]</del>
*<del>[http://www.youtube.com/watch?v=ESISPLDbMWM How To Make a Custom Story Background]</del>
*<del>[http://www.youtube.com/watch?v=RmIKTH9YRqk How To Make a Functional and Interactable Ladder]</del>
*<del>[http://www.youtube.com/watch?v=riFwThqQ68k How To Name and Describe Keys]</del>
*<del>[http://www.youtube.com/watch?v=M5x_taEkP8s Simple Script Function]</del>

===By Elven===

[http://www.youtube.com/user/elvengames Youtube Channel link]

*<del>[http://www.youtube.com/watch?v=jGJluxjcGCg Basics of the Basic]</del>
*<del>[http://www.youtube.com/watch?v=IKJIT05V00Y When is it syntax and when not?]</del>
*<del>[http://www.youtube.com/watch?v=1x3mTmvbSmc Make your life easier: Notepad++ with plugin & Debugging]</del>
*<del>[http://www.youtube.com/watch?v=zDhPJByYAec So, how the duckling I install hps support?]</del>
*<del>[http://www.youtube.com/watch?v=Pv9GK5Gh4Bw Scripting Functions (intro)]</del>
*<del>[http://www.youtube.com/watch?v=yYPfWC5nCrk Timers]</del>
*<del>[http://www.youtube.com/watch?v=EhUjbK_vEhM Piano Scare (Request)]</del>
*<del>[http://www.youtube.com/watch?v=jPaRHHlepKw Adding Credits]</del>
*<del>[http://www.youtube.com/watch?v=bTzWAQJMnz8 Setting up development mode]</del>
*<del>[http://www.youtube.com/watch?v=idK5VSTqDrs Loopable timers - LIMITED EDITION (Specific amount of times)]</del>
*<del>[http://www.youtube.com/watch?v=DeoDFmcVU8U&feature=youtu.be Hallucination monster scare!]</del>

HPL2/Tutorials

2024-06-07T09:23:41Z

Darkfire: Formatting

==Text tutorials==

This page lists a large amount of tutorials, most of which are community-made. Feel free to check them out and see if they can teach you something. If you've made a tutorial and wish to add it to this page, you can do so by editing it to the right. Just try to keep to the same format as the rest of the page.

{{tip|If you can't find a tutorial for what you need, make sure to check the [[HPL2/Tools#Editors|Editor documentation]] and [[HPL2/TDD#Documentation|Engine documentation]]. An example of this would be the Particle Editor.}}

===Level Editor===

*[[:hpl2:tutorials:level_editor:tutorial_1|Tutorial 1]] - The minimum required to get a level that can load.
*[[:hpl2:tutorials:level_editor:tutorial_2|Tutorial 2]] - Placement of lights and advanced setup of lights.
*[[:hpl2:tutorials:level_editor:tutorial_3|Tutorial 3]] - How to make an outdoor environment. There's a [[Hpl2:Tutorials:level_editor:outdoors|newer version of i]]t available.
*[[:hpl2:tutorials:level_editor:tutorial_4|Tutorial 4]] - Explains how to make water.
*[[:hpl2:tutorials:level_editor:tutorial_5|Tutorial 5]] - Prop dimensions and detailing your map.
*[[Hpl2:Tutorials:level editor:tutorial 6|Tutorial 6]] - ???????
*[[HPL2/Tutorials/Skyboxes|Tutorial 7]] - Making skyboxes for HPL2
*[[HPL2/Tutorials/Level Design]] - Using all of the basic techniques to achieve good effects
*[[:hpl2:tutorials:level_editor:level_editor_101|Level Editor 101]] - All the basics and some more advanced techniques.

===Model Editor===

*[[:hpl2:tutorials:model_editor:tutorial_1|Basic tutorial]] - The minimum required to load a model as an entity with collision and game properties.
*[[:hpl2:tutorials:model_editor:tutorial_2|Creating Ragdoll Entities]] - How to create full physics-based entities.
*[[:hpl2:tutorials:model_editor:static_objects_jenniferorange|Making Items Static]] - How to change an items' properties to static.
*[[HPL2/Tutorials/Coin_chests | Coin chests]] - How to create chests that can be only opened with coins.

===Material Editor===

*[[:hpl2:tutorials:material_editor:tutorial_1|Tutorial 1]] - Basic materials and their properties.
*[[Hpl2:Tutorials:material editor:creating mirrors|Creating mirrors]] - make reflective surfaces using water materials

===Game files===

*[[:hpl2:tutorials:script:CustomSounds|How to create Custom Sounds]] - Teaches how to create custom sounds for your custom story.
*[[:hpl2:tutorials:script:howtomakenotes|How to Create Notes and Journal Entries]] - Explains how to make journal entries and place them in a map
*[[HPL2/Tutorials/Porting MFP Assets|Porting MFP Assets]] - explains how to copy assets from MFP to TDD and avoid issues
*[[HPL2/Tutorials/Convert HDRI to skyboxes|Convert HDRI to skyboxes]]

===Scripting tutorials===
General basics:

*[[HPL2/Tutorials/Scripts/Debugging|Make your set-up comfortable for scripting]]
*[[:hpl2:tutorials:script:entihscript_beginner|Newbie's Guide to Scripting]] - A tutorial for those new to scripting, focusing on syntax and a few helpful hints - ''By 'Entih''
*[[:hpl2:tutorials:script:tutorial_1|Tutorial 1]] - Using a tutorial level, with some objects to make basic scripts.
*[[:hpl2:tutorials:scripting:messages_jenniferorange|Activating/Using Message Pop-Ups]] - Explains how to activate a message to appear when walking into a script area.
*[[:hpl2:tutorials:scripting:triggering_monsters_on_entities|Triggering monsters on entities]] - Explains how to trigger an event after picking up an item.

Door-related script tutorials:

*[[:hpl2:tutorials:script:scripting_by_xtron_-_item_that_unlocks_a_door|Item That Unlocks a Door]] - How to make an item that unlocks a certain door.
*[[:hpl2:tutorials:script:buttons_that_open_a_door|Buttons that open door]]s - Explains how to make buttons that open doors.
*[[:hpl2:tutorials:script:events|Scary door events]] - Explains how to make scary door events.
*[[:hpl2:tutorials:scripting:crowbartutorialjenniferorange|Using A Crowbar On A Door]] - Explains how to script a crowbar to blow open a door.
*[[:hpl2:tutorials:script:adding_messages_to_locked_doors|Adding Messages To Locked Doors]] - Explains how to display a message when a player tries to open a locked door.

Useful coding practices:

*[[:hpl2:tutorials:script:forloop|The "For" loop]] - Explains how and when to use the "for" loop.
*[[:hpl2:tutorials:script:advancedtimers|Advanced Timers]] - Explains how to use multiple timers in one function.
*[[:hpl2:tutorials:script:localandglobalvariables|Local and Global Variables]] - Explains what they are and how to use them correctly.
*[[:hpl2:tutorials:script:sequences|Scripting Sequences]] - Explains how to build simple and easy to use cutscenes, or sequences for your mod.

Forces and impulses:

*[[:hpl2:tutorials:script:force|Impulse and forces]] - Explains how to use force and impulse.
*[[:hpl2:tutorials:script:pushdoorsopen|Push doors open using force]] - Explains how to use Force to open doors and entities.
*[[Hpl2:Tutorials:level_editor:dynamic_curtains|Dynamic curtains]] - Using force to simulate wind
*[[:hpl2:tutorials:script:disable_gravity_tutorial|"Disable" gravity and make objects float]] - Make entities seem to float using timer functions and forces

Other:

*[[:hpl2:tutorials:script:monsterpathnodes|Monster Path Nodes]] - Explains how to set up a monster's path and how to trigger it.
*[[:hpl2:tutorials:script:levers_and_secretshelfs|Levers and secret bookshelves]] - Explains how to make a lever that opens a bookshelf.
*[[:hpl2:tutorials:scripting:scaresbyjenniferorange|Scares]] - Explains in as much detail as possible the multiple scares you can use without having to bring out the monsters.
*[[:hpl2:tutorials:level_editor:combininghammerchipperjenniferorange|Combining The Hammer And Chipper]] - Explains how to combine your hammer and chipper in your inventory.
*[[:hpl2:tutorials:scripting:checkpoints_using_scriptarea_s|Checkpoints using Areas]] - Explains how to make a checkpoint using Areas.
*[[:hpl2:tutorials:script:tutorialsformainmenu|How to create your own Main Menu Backgrounds!]] - The usability of Amnesia's .cfg files and its Editors
*[[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] - Some notes about the ShowScreenImage() function new to ATTD in version 1.5 (and also AAMFP).

===Modeling===

*[[:hpl2:tutorials:modeling:tutorialoutsource|Modeling tutorial]] - Initially written for outsourcers.

==Video tutorials==

<del>Crossed-out videos</del> are unavailable or privated (as of June 2024).

===Sublists===

*'''Recommended: [https://www.youtube.com/playlist?list=PLIYfl4qBRihBjRpmQL-izQ4xdAtLblU36 Large playlist of video tutorials for beginners and intermediate developers] - By Mudbill'''
*[[Hpl2:Tutorials:script:elventutorials|Elven's tutorials]]
*[http://www.youtube.com/playlist?list=PLD326789BC99530C8 From Noob to Pro: Amnesia Custom Story Creation Series] - ''By YourComputer''

===By Khyrpa===

*<del>[http://www.youtube.com/watch?v=1R2F2eVmJ5k Building and Lighting in The Level Editor]</del>
*[http://www.youtube.com/watch?v=d2ShkLEgGNk Lighting in Level Editor]
*[http://www.youtube.com/watch?v=u8EhP59tmjA Billboards]
*[http://www.youtube.com/watch?v=LKxzoAIK8jA Advanced Candle Light Connecting]
*[http://www.youtube.com/watch?v=xIDCoEZ581Q Wind Scare (Part 1)]
*[http://www.youtube.com/watch?v=Kj-NFkIGafI Wind Scare (Part 2)]

===Various authors===

*[http://www.youtube.com/watch?v=0grr7uipnk0 How To Create a Custom Story] - ''By TheVegaNVega''
*[http://www.youtube.com/watch?v=uGCTwQQSZ0A How To Make Journal Entries/Notes] - ''By RussMoney''
*[http://www.youtube.com/watch?v=WfgFEG4TSCE How To Make Journal Entries/Mementos] - ''By RussMoney''
*[http://www.youtube.com/watch?v=puIfVx0lslA How To Convert a Custom Story To a Full Conversion] - ''By RussMoney''
*[http://www.youtube.com/watch?v=9uKBYVEyw1s How to convert cube map images to DDS format in the GIMP] - ''By YourComputer''
*[http://www.youtube.com/watch?v=EnCAbgTY6d8 Adding Voice to your Diaries] - ''By triadtimes''
*[http://www.youtube.com/watch?v=vQEdIAZw5gM&feature=plcp&context=C4347014VDvjVQa1PpcFNKLAyG_d-p_QR49e20E_Wo08wpqmVkJz0= How to create a custom main menu background] - ''By CTCommunity''
*[http://youtu.be/Crx5Qd7AgJ0 Using Prop Force: How Do I Know Which Coordinate To Put My Value In?] - ''By JenniferOrange''

===By MulleDK19===

*<del>[http://amnesia.treesoft.dk/tutorials/Tutorial1.wmv Make a key unlock a specific door]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/Tutorial2.wmv How to create and use Areas or Triggers]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial1.wmv Using the Level Editor (Part 1)]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial2.wmv Using the Level Editor (Part 2)]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial3.wmv Using the Level Editor (Part 3)]</del>

===By Simpanra===

*<del>[http://www.youtube.com/watch?v=CklTIT2W4g4 How To Make Level Door]</del>
*<del>[http://www.youtube.com/watch?v=ABI7NUqkXW0 How To Get a Key To Unlock a Door]</del>
*<del>[http://www.youtube.com/watch?v=v4WudNebX08 How To Make Water]</del>
*<del>[http://www.youtube.com/watch?v=ESISPLDbMWM How To Make a Custom Story Background]</del>
*<del>[http://www.youtube.com/watch?v=RmIKTH9YRqk How To Make a Functional and Interactable Ladder]</del>
*<del>[http://www.youtube.com/watch?v=riFwThqQ68k How To Name and Describe Keys]</del>
*<del>[http://www.youtube.com/watch?v=M5x_taEkP8s Simple Script Function]</del>

HPL2/Tutorials

2024-06-07T08:59:08Z

Darkfire: highlight mudbill's tutorials

=Text tutorials=

This page lists a large amount of tutorials, most of which are community-made. Feel free to check them out and see if they can teach you something. If you've made a tutorial and wish to add it to this page, you can do so by editing it to the right. Just try to keep to the same format as the rest of the page.

{{tip|If you can't find a tutorial for what you need, make sure to check the [[HPL2/Tools#Editors|Editor documentation]] and [[HPL2/TDD#Documentation|Engine documentation]]. An example of this would be the Particle Editor.}}

==Level Editor==

*[[:hpl2:tutorials:level_editor:tutorial_1|Tutorial 1]] - The minimum required to get a level that can load.
*[[:hpl2:tutorials:level_editor:tutorial_2|Tutorial 2]] - Placement of lights and advanced setup of lights.
*[[:hpl2:tutorials:level_editor:tutorial_3|Tutorial 3]] - How to make an outdoor environment. There's a [[Hpl2:Tutorials:level_editor:outdoors|newer version of i]]t available.
*[[:hpl2:tutorials:level_editor:tutorial_4|Tutorial 4]] - Explains how to make water.
*[[:hpl2:tutorials:level_editor:tutorial_5|Tutorial 5]] - Prop dimensions and detailing your map.
*[[Hpl2:Tutorials:level editor:tutorial 6|Tutorial 6]] - ???????
*[[HPL2/Tutorials/Skyboxes|Tutorial 7]] - Making skyboxes for HPL2
*[[HPL2/Tutorials/Level Design]] - Using all of the basic techniques to achieve good effects
*[[:hpl2:tutorials:level_editor:level_editor_101|Level Editor 101]] - All the basics and some more advanced techniques.

==Model Editor==

*[[:hpl2:tutorials:model_editor:tutorial_1|Basic tutorial]] - The minimum required to load a model as an entity with collision and game properties.
*[[:hpl2:tutorials:model_editor:tutorial_2|Creating Ragdoll Entities]] - How to create full physics-based entities.
*[[:hpl2:tutorials:model_editor:static_objects_jenniferorange|Making Items Static]] - How to change an items' properties to static.
*[[HPL2/Tutorials/Coin_chests | Coin chests]] - How to create chests that can be only opened with coins.

==Material Editor==

*[[:hpl2:tutorials:material_editor:tutorial_1|Tutorial 1]] - Basic materials and their properties.
*[[Hpl2:Tutorials:material editor:creating mirrors|Creating mirrors]] - make reflective surfaces using water materials

==Game files==

*[[:hpl2:tutorials:script:CustomSounds|How to create Custom Sounds]] - Teaches how to create custom sounds for your custom story.
*[[:hpl2:tutorials:script:howtomakenotes|How to Create Notes and Journal Entries]] - Explains how to make journal entries and place them in a map
*[[HPL2/Tutorials/Porting MFP Assets|Porting MFP Assets]] - explains how to copy assets from MFP to TDD and avoid issues
*[[HPL2/Tutorials/Convert HDRI to skyboxes|Convert HDRI to skyboxes]]

==Scripting tutorials==
General basics:

*[[HPL2/Tutorials/Scripts/Debugging|Make your set-up comfortable for scripting]]
*[[:hpl2:tutorials:script:entihscript_beginner|Newbie's Guide to Scripting]] - A tutorial for those new to scripting, focusing on syntax and a few helpful hints - ''By 'Entih''
*[[:hpl2:tutorials:script:tutorial_1|Tutorial 1]] - Using a tutorial level, with some objects to make basic scripts.
*[[:hpl2:tutorials:scripting:messages_jenniferorange|Activating/Using Message Pop-Ups]] - Explains how to activate a message to appear when walking into a script area.
*[[:hpl2:tutorials:scripting:triggering_monsters_on_entities|Triggering monsters on entities]] - Explains how to trigger an event after picking up an item.

Door-related script tutorials:

*[[:hpl2:tutorials:script:scripting_by_xtron_-_item_that_unlocks_a_door|Item That Unlocks a Door]] - How to make an item that unlocks a certain door.
*[[:hpl2:tutorials:script:buttons_that_open_a_door|Buttons that open door]]s - Explains how to make buttons that open doors.
*[[:hpl2:tutorials:script:events|Scary door events]] - Explains how to make scary door events.
*[[:hpl2:tutorials:scripting:crowbartutorialjenniferorange|Using A Crowbar On A Door]] - Explains how to script a crowbar to blow open a door.
*[[:hpl2:tutorials:script:adding_messages_to_locked_doors|Adding Messages To Locked Doors]] - Explains how to display a message when a player tries to open a locked door.

Useful coding practices:

*[[:hpl2:tutorials:script:forloop|The "For" loop]] - Explains how and when to use the "for" loop.
*[[:hpl2:tutorials:script:advancedtimers|Advanced Timers]] - Explains how to use multiple timers in one function.
*[[:hpl2:tutorials:script:localandglobalvariables|Local and Global Variables]] - Explains what they are and how to use them correctly.
*[[:hpl2:tutorials:script:sequences|Scripting Sequences]] - Explains how to build simple and easy to use cutscenes, or sequences for your mod.

Forces and impulses:

*[[:hpl2:tutorials:script:force|Impulse and forces]] - Explains how to use force and impulse.
*[[:hpl2:tutorials:script:pushdoorsopen|Push doors open using force]] - Explains how to use Force to open doors and entities.
*[[Hpl2:Tutorials:level_editor:dynamic_curtains|Dynamic curtains]] - Using force to simulate wind
*[[:hpl2:tutorials:script:disable_gravity_tutorial|"Disable" gravity and make objects float]] - Make entities seem to float using timer functions and forces

Other:

*[[:hpl2:tutorials:script:monsterpathnodes|Monster Path Nodes]] - Explains how to set up a monster's path and how to trigger it.
*[[:hpl2:tutorials:script:levers_and_secretshelfs|Levers and secret bookshelves]] - Explains how to make a lever that opens a bookshelf.
*[[:hpl2:tutorials:scripting:scaresbyjenniferorange|Scares]] - Explains in as much detail as possible the multiple scares you can use without having to bring out the monsters.
*[[:hpl2:tutorials:level_editor:combininghammerchipperjenniferorange|Combining The Hammer And Chipper]] - Explains how to combine your hammer and chipper in your inventory.
*[[:hpl2:tutorials:scripting:checkpoints_using_scriptarea_s|Checkpoints using Areas]] - Explains how to make a checkpoint using Areas.
*[[:hpl2:tutorials:script:tutorialsformainmenu|How to create your own Main Menu Backgrounds!]] - The usability of Amnesia's .cfg files and its Editors
*[[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] - Some notes about the ShowScreenImage() function new to ATTD in version 1.5 (and also AAMFP).

==Modeling==

*[[:hpl2:tutorials:modeling:tutorialoutsource|Modeling tutorial]] - Initially written for outsourcers.

=Video tutorials=
Sublists:

*'''Recommended:''' [https://www.youtube.com/playlist?list=PLIYfl4qBRihBjRpmQL-izQ4xdAtLblU36 Large playlist of video tutorials for beginners and intermediate developers] - ''By Mudbill''
*[[Hpl2:Tutorials:script:elventutorials|Elven's tutorials]]
*[http://www.youtube.com/playlist?list=PLD326789BC99530C8 From Noob to Pro: Amnesia Custom Story Creation Series] - ''By YourComputer''

==By Simpanra==

*<del>[http://www.youtube.com/watch?v=CklTIT2W4g4 How To Make Level Door]</del>
*<del>[http://www.youtube.com/watch?v=ABI7NUqkXW0 How To Get a Key To Unlock a Door]</del>
*<del>[http://www.youtube.com/watch?v=v4WudNebX08 How To Make Water]</del>
*<del>[http://www.youtube.com/watch?v=ESISPLDbMWM How To Make a Custom Story Background]</del>
*<del>[http://www.youtube.com/watch?v=RmIKTH9YRqk How To Make a Functional and Interactable Ladder]</del>
*<del>[http://www.youtube.com/watch?v=riFwThqQ68k How To Name and Describe Keys]</del>
*<del>[http://www.youtube.com/watch?v=M5x_taEkP8s Simple Script Function]</del>

==By Khyrpa==

*<del>[http://www.youtube.com/watch?v=1R2F2eVmJ5k Building and Lighting in The Level Editor]</del>
*[http://www.youtube.com/watch?v=d2ShkLEgGNk Lighting in Level Editor]
*[http://www.youtube.com/watch?v=u8EhP59tmjA Billboards]
*[http://www.youtube.com/watch?v=LKxzoAIK8jA Advanced Candle Light Connecting]
*[http://www.youtube.com/watch?v=xIDCoEZ581Q Wind Scare (Part 1)]
*[http://www.youtube.com/watch?v=Kj-NFkIGafI Wind Scare (Part 2)]

==By MulleDK19==

*<del>[http://amnesia.treesoft.dk/tutorials/Tutorial1.wmv Make a key unlock a specific door]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/Tutorial2.wmv How to create and use Areas or Triggers]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial1.wmv Using the Level Editor (Part 1)]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial2.wmv Using the Level Editor (Part 2)]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial3.wmv Using the Level Editor (Part 3)]</del>

==By others==

*[http://www.youtube.com/watch?v=0grr7uipnk0 How To Create a Custom Story] - ''By TheVegaNVega''
*[http://www.youtube.com/watch?v=uGCTwQQSZ0A How To Make Journal Entries/Notes] - ''By RussMoney''
*[http://www.youtube.com/watch?v=WfgFEG4TSCE How To Make Journal Entries/Mementos] - ''By RussMoney''
*[http://www.youtube.com/watch?v=puIfVx0lslA How To Convert a Custom Story To a Full Conversion] - ''By RussMoney''
*[http://www.youtube.com/watch?v=9uKBYVEyw1s How to convert cube map images to DDS format in the GIMP] - ''By YourComputer''
*[http://www.youtube.com/watch?v=EnCAbgTY6d8 Adding Voice to your Diaries] - ''By triadtimes''
*[http://www.youtube.com/watch?v=vQEdIAZw5gM&feature=plcp&context=C4347014VDvjVQa1PpcFNKLAyG_d-p_QR49e20E_Wo08wpqmVkJz0= How to create a custom main menu background] - ''By CTCommunity''
*[http://youtu.be/Crx5Qd7AgJ0 Using Prop Force: How Do I Know Which Coordinate To Put My Value In?] - ''By JenniferOrange''

HPL2/Tutorials

2024-06-07T08:55:45Z

Darkfire: update crossed out link formatting, move a playlist to top of video tutorials

=Text tutorials=

This page lists a large amount of tutorials, most of which are community-made. Feel free to check them out and see if they can teach you something. If you've made a tutorial and wish to add it to this page, you can do so by editing it to the right. Just try to keep to the same format as the rest of the page.

{{tip|If you can't find a tutorial for what you need, make sure to check the [[HPL2/Tools#Editors|Editor documentation]] and [[HPL2/TDD#Documentation|Engine documentation]]. An example of this would be the Particle Editor.}}

==Level Editor==

*[[:hpl2:tutorials:level_editor:tutorial_1|Tutorial 1]] - The minimum required to get a level that can load.
*[[:hpl2:tutorials:level_editor:tutorial_2|Tutorial 2]] - Placement of lights and advanced setup of lights.
*[[:hpl2:tutorials:level_editor:tutorial_3|Tutorial 3]] - How to make an outdoor environment. There's a [[Hpl2:Tutorials:level_editor:outdoors|newer version of i]]t available.
*[[:hpl2:tutorials:level_editor:tutorial_4|Tutorial 4]] - Explains how to make water.
*[[:hpl2:tutorials:level_editor:tutorial_5|Tutorial 5]] - Prop dimensions and detailing your map.
*[[Hpl2:Tutorials:level editor:tutorial 6|Tutorial 6]] - ???????
*[[HPL2/Tutorials/Skyboxes|Tutorial 7]] - Making skyboxes for HPL2
*[[HPL2/Tutorials/Level Design]] - Using all of the basic techniques to achieve good effects
*[[:hpl2:tutorials:level_editor:level_editor_101|Level Editor 101]] - All the basics and some more advanced techniques.

==Model Editor==

*[[:hpl2:tutorials:model_editor:tutorial_1|Basic tutorial]] - The minimum required to load a model as an entity with collision and game properties.
*[[:hpl2:tutorials:model_editor:tutorial_2|Creating Ragdoll Entities]] - How to create full physics-based entities.
*[[:hpl2:tutorials:model_editor:static_objects_jenniferorange|Making Items Static]] - How to change an items' properties to static.
*[[HPL2/Tutorials/Coin_chests | Coin chests]] - How to create chests that can be only opened with coins.

==Material Editor==

*[[:hpl2:tutorials:material_editor:tutorial_1|Tutorial 1]] - Basic materials and their properties.
*[[Hpl2:Tutorials:material editor:creating mirrors|Creating mirrors]] - make reflective surfaces using water materials

==Game files==

*[[:hpl2:tutorials:script:CustomSounds|How to create Custom Sounds]] - Teaches how to create custom sounds for your custom story.
*[[:hpl2:tutorials:script:howtomakenotes|How to Create Notes and Journal Entries]] - Explains how to make journal entries and place them in a map
*[[HPL2/Tutorials/Porting MFP Assets|Porting MFP Assets]] - explains how to copy assets from MFP to TDD and avoid issues
*[[HPL2/Tutorials/Convert HDRI to skyboxes|Convert HDRI to skyboxes]]

==Scripting tutorials==
General basics:

*[[HPL2/Tutorials/Scripts/Debugging|Make your set-up comfortable for scripting]]
*[[:hpl2:tutorials:script:entihscript_beginner|Newbie's Guide to Scripting]] - A tutorial for those new to scripting, focusing on syntax and a few helpful hints - ''By 'Entih''
*[[:hpl2:tutorials:script:tutorial_1|Tutorial 1]] - Using a tutorial level, with some objects to make basic scripts.
*[[:hpl2:tutorials:scripting:messages_jenniferorange|Activating/Using Message Pop-Ups]] - Explains how to activate a message to appear when walking into a script area.
*[[:hpl2:tutorials:scripting:triggering_monsters_on_entities|Triggering monsters on entities]] - Explains how to trigger an event after picking up an item.

Door-related script tutorials:

*[[:hpl2:tutorials:script:scripting_by_xtron_-_item_that_unlocks_a_door|Item That Unlocks a Door]] - How to make an item that unlocks a certain door.
*[[:hpl2:tutorials:script:buttons_that_open_a_door|Buttons that open door]]s - Explains how to make buttons that open doors.
*[[:hpl2:tutorials:script:events|Scary door events]] - Explains how to make scary door events.
*[[:hpl2:tutorials:scripting:crowbartutorialjenniferorange|Using A Crowbar On A Door]] - Explains how to script a crowbar to blow open a door.
*[[:hpl2:tutorials:script:adding_messages_to_locked_doors|Adding Messages To Locked Doors]] - Explains how to display a message when a player tries to open a locked door.

Useful coding practices:

*[[:hpl2:tutorials:script:forloop|The "For" loop]] - Explains how and when to use the "for" loop.
*[[:hpl2:tutorials:script:advancedtimers|Advanced Timers]] - Explains how to use multiple timers in one function.
*[[:hpl2:tutorials:script:localandglobalvariables|Local and Global Variables]] - Explains what they are and how to use them correctly.
*[[:hpl2:tutorials:script:sequences|Scripting Sequences]] - Explains how to build simple and easy to use cutscenes, or sequences for your mod.

Forces and impulses:

*[[:hpl2:tutorials:script:force|Impulse and forces]] - Explains how to use force and impulse.
*[[:hpl2:tutorials:script:pushdoorsopen|Push doors open using force]] - Explains how to use Force to open doors and entities.
*[[Hpl2:Tutorials:level_editor:dynamic_curtains|Dynamic curtains]] - Using force to simulate wind
*[[:hpl2:tutorials:script:disable_gravity_tutorial|"Disable" gravity and make objects float]] - Make entities seem to float using timer functions and forces

Other:

*[[:hpl2:tutorials:script:monsterpathnodes|Monster Path Nodes]] - Explains how to set up a monster's path and how to trigger it.
*[[:hpl2:tutorials:script:levers_and_secretshelfs|Levers and secret bookshelves]] - Explains how to make a lever that opens a bookshelf.
*[[:hpl2:tutorials:scripting:scaresbyjenniferorange|Scares]] - Explains in as much detail as possible the multiple scares you can use without having to bring out the monsters.
*[[:hpl2:tutorials:level_editor:combininghammerchipperjenniferorange|Combining The Hammer And Chipper]] - Explains how to combine your hammer and chipper in your inventory.
*[[:hpl2:tutorials:scripting:checkpoints_using_scriptarea_s|Checkpoints using Areas]] - Explains how to make a checkpoint using Areas.
*[[:hpl2:tutorials:script:tutorialsformainmenu|How to create your own Main Menu Backgrounds!]] - The usability of Amnesia's .cfg files and its Editors
*[[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] - Some notes about the ShowScreenImage() function new to ATTD in version 1.5 (and also AAMFP).

==Modeling==

*[[:hpl2:tutorials:modeling:tutorialoutsource|Modeling tutorial]] - Initially written for outsourcers.

=Video tutorials=
Sublists:

*[https://www.youtube.com/playlist?list=PLIYfl4qBRihBjRpmQL-izQ4xdAtLblU36 Large playlist of video tutorials for beginners and intermediate developers] - ''By Mudbill''
*[[Hpl2:Tutorials:script:elventutorials|Elven's tutorials]]
*[http://www.youtube.com/playlist?list=PLD326789BC99530C8 From Noob to Pro: Amnesia Custom Story Creation Series] - ''By YourComputer''

==By Simpanra==

*<del>[http://www.youtube.com/watch?v=CklTIT2W4g4 How To Make Level Door]</del>
*<del>[http://www.youtube.com/watch?v=ABI7NUqkXW0 How To Get a Key To Unlock a Door]</del>
*<del>[http://www.youtube.com/watch?v=v4WudNebX08 How To Make Water]</del>
*<del>[http://www.youtube.com/watch?v=ESISPLDbMWM How To Make a Custom Story Background]</del>
*<del>[http://www.youtube.com/watch?v=RmIKTH9YRqk How To Make a Functional and Interactable Ladder]</del>
*<del>[http://www.youtube.com/watch?v=riFwThqQ68k How To Name and Describe Keys]</del>
*<del>[http://www.youtube.com/watch?v=M5x_taEkP8s Simple Script Function]</del>

==By Khyrpa==

*<del>[http://www.youtube.com/watch?v=1R2F2eVmJ5k Building and Lighting in The Level Editor]</del>
*[http://www.youtube.com/watch?v=d2ShkLEgGNk Lighting in Level Editor]
*[http://www.youtube.com/watch?v=u8EhP59tmjA Billboards]
*[http://www.youtube.com/watch?v=LKxzoAIK8jA Advanced Candle Light Connecting]
*[http://www.youtube.com/watch?v=xIDCoEZ581Q Wind Scare (Part 1)]
*[http://www.youtube.com/watch?v=Kj-NFkIGafI Wind Scare (Part 2)]

==By MulleDK19==

*<del>[http://amnesia.treesoft.dk/tutorials/Tutorial1.wmv Make a key unlock a specific door]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/Tutorial2.wmv How to create and use Areas or Triggers]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial1.wmv Using the Level Editor (Part 1)]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial2.wmv Using the Level Editor (Part 2)]</del>
*<del>[http://amnesia.treesoft.dk/tutorials/EditorTutorial3.wmv Using the Level Editor (Part 3)]</del>

==By others==

*[http://www.youtube.com/watch?v=0grr7uipnk0 How To Create a Custom Story] - ''By TheVegaNVega''
*[http://www.youtube.com/watch?v=uGCTwQQSZ0A How To Make Journal Entries/Notes] - ''By RussMoney''
*[http://www.youtube.com/watch?v=WfgFEG4TSCE How To Make Journal Entries/Mementos] - ''By RussMoney''
*[http://www.youtube.com/watch?v=puIfVx0lslA How To Convert a Custom Story To a Full Conversion] - ''By RussMoney''
*[http://www.youtube.com/watch?v=9uKBYVEyw1s How to convert cube map images to DDS format in the GIMP] - ''By YourComputer''
*[http://www.youtube.com/watch?v=EnCAbgTY6d8 Adding Voice to your Diaries] - ''By triadtimes''
*[http://www.youtube.com/watch?v=vQEdIAZw5gM&feature=plcp&context=C4347014VDvjVQa1PpcFNKLAyG_d-p_QR49e20E_Wo08wpqmVkJz0= How to create a custom main menu background] - ''By CTCommunity''
*[http://youtu.be/Crx5Qd7AgJ0 Using Prop Force: How Do I Know Which Coordinate To Put My Value In?] - ''By JenniferOrange''

HPL2/Tutorials

2024-06-07T08:51:31Z

Darkfire: Crossed out dead links

=Text tutorials=

This page lists a large amount of tutorials, most of which are community-made. Feel free to check them out and see if they can teach you something. If you've made a tutorial and wish to add it to this page, you can do so by editing it to the right. Just try to keep to the same format as the rest of the page.

{{tip|If you can't find a tutorial for what you need, make sure to check the [[HPL2/Tools#Editors|Editor documentation]] and [[HPL2/TDD#Documentation|Engine documentation]]. An example of this would be the Particle Editor.}}

==Level Editor==

*[[:hpl2:tutorials:level_editor:tutorial_1|Tutorial 1]] - The minimum required to get a level that can load.
*[[:hpl2:tutorials:level_editor:tutorial_2|Tutorial 2]] - Placement of lights and advanced setup of lights.
*[[:hpl2:tutorials:level_editor:tutorial_3|Tutorial 3]] - How to make an outdoor environment. There's a [[Hpl2:Tutorials:level_editor:outdoors|newer version of i]]t available.
*[[:hpl2:tutorials:level_editor:tutorial_4|Tutorial 4]] - Explains how to make water.
*[[:hpl2:tutorials:level_editor:tutorial_5|Tutorial 5]] - Prop dimensions and detailing your map.
*[[Hpl2:Tutorials:level editor:tutorial 6|Tutorial 6]] - ???????
*[[HPL2/Tutorials/Skyboxes|Tutorial 7]] - Making skyboxes for HPL2
*[[HPL2/Tutorials/Level Design]] - Using all of the basic techniques to achieve good effects
*[[:hpl2:tutorials:level_editor:level_editor_101|Level Editor 101]] - All the basics and some more advanced techniques.

==Model Editor==

*[[:hpl2:tutorials:model_editor:tutorial_1|Basic tutorial]] - The minimum required to load a model as an entity with collision and game properties.
*[[:hpl2:tutorials:model_editor:tutorial_2|Creating Ragdoll Entities]] - How to create full physics-based entities.
*[[:hpl2:tutorials:model_editor:static_objects_jenniferorange|Making Items Static]] - How to change an items' properties to static.
*[[HPL2/Tutorials/Coin_chests | Coin chests]] - How to create chests that can be only opened with coins.

==Material Editor==

*[[:hpl2:tutorials:material_editor:tutorial_1|Tutorial 1]] - Basic materials and their properties.
*[[Hpl2:Tutorials:material editor:creating mirrors|Creating mirrors]] - make reflective surfaces using water materials

==Game files==

*[[:hpl2:tutorials:script:CustomSounds|How to create Custom Sounds]] - Teaches how to create custom sounds for your custom story.
*[[:hpl2:tutorials:script:howtomakenotes|How to Create Notes and Journal Entries]] - Explains how to make journal entries and place them in a map
*[[HPL2/Tutorials/Porting MFP Assets|Porting MFP Assets]] - explains how to copy assets from MFP to TDD and avoid issues
*[[HPL2/Tutorials/Convert HDRI to skyboxes|Convert HDRI to skyboxes]]

==Scripting tutorials==
General basics:

*[[HPL2/Tutorials/Scripts/Debugging|Make your set-up comfortable for scripting]]
*[[:hpl2:tutorials:script:entihscript_beginner|Newbie's Guide to Scripting]] - A tutorial for those new to scripting, focusing on syntax and a few helpful hints - ''By 'Entih''
*[[:hpl2:tutorials:script:tutorial_1|Tutorial 1]] - Using a tutorial level, with some objects to make basic scripts.
*[[:hpl2:tutorials:scripting:messages_jenniferorange|Activating/Using Message Pop-Ups]] - Explains how to activate a message to appear when walking into a script area.
*[[:hpl2:tutorials:scripting:triggering_monsters_on_entities|Triggering monsters on entities]] - Explains how to trigger an event after picking up an item.

Door-related script tutorials:

*[[:hpl2:tutorials:script:scripting_by_xtron_-_item_that_unlocks_a_door|Item That Unlocks a Door]] - How to make an item that unlocks a certain door.
*[[:hpl2:tutorials:script:buttons_that_open_a_door|Buttons that open door]]s - Explains how to make buttons that open doors.
*[[:hpl2:tutorials:script:events|Scary door events]] - Explains how to make scary door events.
*[[:hpl2:tutorials:scripting:crowbartutorialjenniferorange|Using A Crowbar On A Door]] - Explains how to script a crowbar to blow open a door.
*[[:hpl2:tutorials:script:adding_messages_to_locked_doors|Adding Messages To Locked Doors]] - Explains how to display a message when a player tries to open a locked door.

Useful coding practices:

*[[:hpl2:tutorials:script:forloop|The "For" loop]] - Explains how and when to use the "for" loop.
*[[:hpl2:tutorials:script:advancedtimers|Advanced Timers]] - Explains how to use multiple timers in one function.
*[[:hpl2:tutorials:script:localandglobalvariables|Local and Global Variables]] - Explains what they are and how to use them correctly.
*[[:hpl2:tutorials:script:sequences|Scripting Sequences]] - Explains how to build simple and easy to use cutscenes, or sequences for your mod.

Forces and impulses:

*[[:hpl2:tutorials:script:force|Impulse and forces]] - Explains how to use force and impulse.
*[[:hpl2:tutorials:script:pushdoorsopen|Push doors open using force]] - Explains how to use Force to open doors and entities.
*[[Hpl2:Tutorials:level_editor:dynamic_curtains|Dynamic curtains]] - Using force to simulate wind
*[[:hpl2:tutorials:script:disable_gravity_tutorial|"Disable" gravity and make objects float]] - Make entities seem to float using timer functions and forces

Other:

*[[:hpl2:tutorials:script:monsterpathnodes|Monster Path Nodes]] - Explains how to set up a monster's path and how to trigger it.
*[[:hpl2:tutorials:script:levers_and_secretshelfs|Levers and secret bookshelves]] - Explains how to make a lever that opens a bookshelf.
*[[:hpl2:tutorials:scripting:scaresbyjenniferorange|Scares]] - Explains in as much detail as possible the multiple scares you can use without having to bring out the monsters.
*[[:hpl2:tutorials:level_editor:combininghammerchipperjenniferorange|Combining The Hammer And Chipper]] - Explains how to combine your hammer and chipper in your inventory.
*[[:hpl2:tutorials:scripting:checkpoints_using_scriptarea_s|Checkpoints using Areas]] - Explains how to make a checkpoint using Areas.
*[[:hpl2:tutorials:script:tutorialsformainmenu|How to create your own Main Menu Backgrounds!]] - The usability of Amnesia's .cfg files and its Editors
*[[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] - Some notes about the ShowScreenImage() function new to ATTD in version 1.5 (and also AAMFP).

==Modeling==

*[[:hpl2:tutorials:modeling:tutorialoutsource|Modeling tutorial]] - Initially written for outsourcers.

=Video tutorials=
Sublists:

*[https://www.youtube.com/playlist?list=PLIYfl4qBRihBjRpmQL-izQ4xdAtLblU36 Large playlist of video tutorials for beginners and intermediate developers] - ''By Mudbill''
*[[Hpl2:Tutorials:script:elventutorials|Elven's tutorials]]

==By Simpanra==

*[http://www.youtube.com/watch?v=CklTIT2W4g4 <s>How To Make Level Door</s>]
*[http://www.youtube.com/watch?v=ABI7NUqkXW0 <s>How To Get a Key To Unlock a Door</s>]
*[http://www.youtube.com/watch?v=v4WudNebX08 <s>How To Make Water</s>]
*[http://www.youtube.com/watch?v=ESISPLDbMWM <s>How To Make a Custom Story Background</s>]
*[http://www.youtube.com/watch?v=RmIKTH9YRqk <s>How To Make a Functional and Interactable Ladder</s>]
*[http://www.youtube.com/watch?v=riFwThqQ68k <s>How To Name and Describe Keys</s>]
*[http://www.youtube.com/watch?v=M5x_taEkP8s <s>Simple Script Function</s>]

==By Khyrpa==

*[http://www.youtube.com/watch?v=1R2F2eVmJ5k <s>Building and Lighting in The Level Editor</s>]
*[http://www.youtube.com/watch?v=d2ShkLEgGNk Lighting in Level Editor]
*[http://www.youtube.com/watch?v=u8EhP59tmjA Billboards]
*[http://www.youtube.com/watch?v=LKxzoAIK8jA Advanced Candle Light Connecting]
*[http://www.youtube.com/watch?v=xIDCoEZ581Q Wind Scare (Part 1)]
*[http://www.youtube.com/watch?v=Kj-NFkIGafI Wind Scare (Part 2)]

==By MulleDK19==

*[http://amnesia.treesoft.dk/tutorials/Tutorial1.wmv Make a key unlock a specific door]
*[http://amnesia.treesoft.dk/tutorials/Tutorial2.wmv How to create and use Areas or Triggers]
*[http://amnesia.treesoft.dk/tutorials/EditorTutorial1.wmv Using the Level Editor (Part 1)]
*[http://amnesia.treesoft.dk/tutorials/EditorTutorial2.wmv Using the Level Editor (Part 2)]
*[http://amnesia.treesoft.dk/tutorials/EditorTutorial3.wmv Using the Level Editor (Part 3)]

==By others==

*[http://www.youtube.com/watch?v=0grr7uipnk0 How To Create a Custom Story] - ''By TheVegaNVega''
*[http://www.youtube.com/watch?v=uGCTwQQSZ0A How To Make Journal Entries/Notes] - ''By RussMoney''
*[http://www.youtube.com/watch?v=WfgFEG4TSCE How To Make Journal Entries/Mementos] - ''By RussMoney''
*[http://www.youtube.com/watch?v=puIfVx0lslA How To Convert a Custom Story To a Full Conversion] - ''By RussMoney''
*[http://www.youtube.com/watch?v=9uKBYVEyw1s How to convert cube map images to DDS format in the GIMP] - ''By YourComputer''
*[http://www.youtube.com/playlist?list=PLD326789BC99530C8 From Noob to Pro: Amnesia Custom Story Creation Series] - ''By YourComputer''
*[http://www.youtube.com/watch?v=EnCAbgTY6d8 Adding Voice to your Diaries] - ''By triadtimes''
*[http://www.youtube.com/watch?v=vQEdIAZw5gM&feature=plcp&context=C4347014VDvjVQa1PpcFNKLAyG_d-p_QR49e20E_Wo08wpqmVkJz0= How to create a custom main menu background] - ''By CTCommunity''
*[http://youtu.be/Crx5Qd7AgJ0 Using Prop Force: How Do I Know Which Coordinate To Put My Value In?] - ''By JenniferOrange''

HPL2/Tools

2024-06-05T19:36:20Z

Darkfire: Add introduction section

[[Category:Entry pages]]
{| class="wikitable" style="margin:auto"
! colspan="2" scope="row" |Editors
|-
|'''[[HPL2/Tools/Level Editor|Level Editor]]'''||Everything that you do in the other editors comes to use here.
|-
|'''[[HPL2/Tools/Model Editor|Model Editor]]'''||Makes your 3D models come to life with ingame functions.
|-
|'''[[HPL2/Tools/Particle Editor|Particle Editor]]'''||Create fire, smoke and other particles to spice up levels and models.
|-
|'''[[HPL2/Tools/Material Editor|Material Editor]]'''||Should a texture come with normal, specular or illumination maps? Should the material be transparent or sound like metal?
|-
|[[HPL2/Tools/HplLangTool|'''HPL Language Tool''']]||Helper tool to build,edit, and translate language files
|-
! colspan="2" scope="row" |Viewers
|-
|'''[[HPL2/Tools/Map Viewer|Map Viewer]]'''||Gives extra information about the level and allows viewing without running the game. A useful tool for optimization.
|-
|'''[[HPL2/Tools/Model Viewer|Model Viewer]]'''||See how your model will look ingame without having to start the game or make game specific files. Useful for porting assets.
|}

==Introduction==

The editors come in 3 versions now:
* The classic 1.3 editors (note: this version has the outdated color picker)
* The [[#Community tools | community edition]] - based on the stable 1.3 version, they provide quality-of-life improvements and a dark theme
* The 1.5 editors - based on patched versions of HPL2, these come prepackaged with the game on some platforms now

{{warning|Keep in mind that these tools, while having been used to produce actual content and a lot of effort has been put on making them as stable as possible, can have bugs.
Make sure to back up your work often, and it is highly recommended to use a versioning system (e.g. [[Setting_up_an_Online_Repository|Git]]). }}

==Installation Instructions==

Make sure to click the download links as copying the link will result in an error. If clicking the link also results in an error, try downloading in another browser.

===Windows===

Download the Windows HPL Editor Suite for Amnesia (click the link, it won't work if you copy it into a tab):

*[https://fricpub.s3.amazonaws.com/tools/hpl2/amnesia_tdd_1.3_editor_suite.zip Version 1.3 and later]
*[https://fricpub.s3.amazonaws.com/tools/hpl2/hpl_editor_suite.zip Version 1.2 and earlier].

This file must be unpacked into the folder where you find Amnesia.exe, all .dll files and folders with game data. This may be one of two locations depending on which version of the game you have.

* '''For Steam users''': This will be your game installation directory, usually <code>C:\Program Files\Steam\steamapps\common\Amnesia - The Dark Descent\</code>
* '''For retail/other users''': This will be inside the "redist" folder inside your installation directory, for example <code>C:\Program Files\Amnesia - The Dark Descent\redist\</code>

When reporting crashes and bugs, always include a description of the problem and any log output from the editors themselves. Logs are located in your <code><Documents>\HPL2\</code> folder.

===Linux===

Download the Linux HPL Editor Suite for Amnesia:

*[https://fricpub.s3.amazonaws.com/tools/hpl2/hpl2_editor_suite-linux-2015-03-04.zip Version 1.3 and later]
*[https://fricpub.s3.amazonaws.com/tools/hpl2/hpl_editor_suite_linux.zip Version 1.2.1 and earlier]

'''Updated 2011-02-19''' Updated to fix crashes when selecting enemies.

Extract the zip and run the installer (<code>hpl_editor_suite.sh</code>).

The installer should automatically find your currently installed copy of Amnesia if you installed it in one of the common installation locations. If not, simply select the Amnesia folder where you installed the game.

'''Note:''' No menu items are created by the installer, it simply installs the editor data files and executables for your platform.

'''Note:''' The HplLangTool.exe is included in the Linux HPL editor suite, it is a .NET application that does run under wine/mono.

When reporting crashes and bugs, always include a description of the problem and any log output from the editors themselves. Logs are located in your <code>~/.frictionalgames/HPL2</code> folder.

===Mac OS X===

Download the Mac OS X HPL Editor Suite:

*[https://fricpub.s3.amazonaws.com/tools/hpl2/HPL2-EditorSuite-OSX-2015-03-04.dmg Version 1.3 and later]
*[https://fricpub.s3.amazonaws.com/tools/hpl2/hpl2editorsuite.dmg Version 1.2.1 and earlier]
*[https://fricpub.s3.amazonaws.com/tools/hpl2/hpl2editorsuite-manual.dmg Manual Install for version 1.2.1 and earlier]. (Use the Manual Install only if you have issues with the automated installer, and be ''SURE'' to read the directions)

Extract the zip and run the installer (''HPL2 Editor Suite Installer''). The installer should automatically find your currently installed copy of Amnesia no matter where you purchased it (including Steam). After installing the tools, simply run Amnesia and select the "Editor Suite" tab in the launcher to run the tools.

Notes:

*This{{clarify}} currently is not for the Mac [http://www.proleadsoft.com/mobile-app-development/| App Store] release, as updates to Amnesia will completely remove the Editor suite. Please read [http://support.frictionalgames.com/entry/103/ this] for more information.
*'''Update 2011-02-19''' Includes fixes for crashes and "hangs"
*'''Update 2011-03-19''' Includes fixes for a crash that occurs when selecting entities to add to a level
*You must install the [http://support.frictionalgames.com/entry/100/ Amnesia 1.0.1.2 Mac OS X Patch] (this is a Mac-only patch). Steam users will get the update directly from the Steam client.

When reporting crashes and bugs, always include a description of the problem and any log output from the editors themselves. Logs are located in your <code>~/Library/Application Support/Frictional Games/HPL2</code> folder.

== Community tools ==

HPL2 is now open source and a community edition of the editors is being worked on. They are '''available for Windows and Linux.'''

===Features===
The new features include:
* A much more comfortable color picker (compared to the classic editors; this picker is included in 1.5 versions too)
* Dark theme (installed by default, but the original one can be reinstated)
* Keyboard shortcuts for common utilities (e.g. grid snapping)
* Ability to load MFP maps and assets without errors
* Other small improvements

===Installation===
# Go to [https://github.com/TiManGames/AmnesiaTheDarkDescent/releases this Github page] to download the latest version of the community tools.
# Download the archive in the format of your choice (.7z is smaller than .zip but requires [https://www.7-zip.org/ 7zip] or Winrar to open).
# Extract the contents into the main directory of Amnesia.
# Merge and overwrite all when asked.

HPL2/Tools

2024-06-05T19:22:34Z

Darkfire: Make the git link point to our article on it

[[Category:Entry pages]]
{| class="wikitable" style="margin:auto"
! colspan="2" scope="row" |Editors
|-
|'''[[HPL2/Tools/Level Editor|Level Editor]]'''||Everything that you do in the other editors comes to use here.
|-
|'''[[HPL2/Tools/Model Editor|Model Editor]]'''||Makes your 3D models come to life with ingame functions.
|-
|'''[[HPL2/Tools/Particle Editor|Particle Editor]]'''||Create fire, smoke and other particles to spice up levels and models.
|-
|'''[[HPL2/Tools/Material Editor|Material Editor]]'''||Should a texture come with normal, specular or illumination maps? Should the material be transparent or sound like metal?
|-
|[[HPL2/Tools/HplLangTool|'''HPL Language Tool''']]||Helper tool to build,edit, and translate language files
|-
! colspan="2" scope="row" |Viewers
|-
|'''[[HPL2/Tools/Map Viewer|Map Viewer]]'''||Gives extra information about the level and allows viewing without running the game. A useful tool for optimization.
|-
|'''[[HPL2/Tools/Model Viewer|Model Viewer]]'''||See how your model will look ingame without having to start the game or make game specific files. Useful for porting assets.
|}

==Installation Instructions==
Keep in mind that these tools, while having been used to produce actual content and a lot of effort has been put on making them as stable as possible, can have bugs.
Make sure to back up your work often, and it is highly recommended to use a versioning system (e.g. [[Setting_up_an_Online_Repository|Git]]).

Make sure to click the download links as copying the link will result in an error. If clicking the link also results in an error, try downloading in another browser.

===Windows===

Download the Windows HPL Editor Suite for Amnesia (click the link, it won't work if you copy it into a tab):

*[https://fricpub.s3.amazonaws.com/tools/hpl2/amnesia_tdd_1.3_editor_suite.zip Version 1.3 and later]
*[https://fricpub.s3.amazonaws.com/tools/hpl2/hpl_editor_suite.zip Version 1.2 and earlier].

This file must be unpacked into the folder where you find Amnesia.exe, all .dll files and folders with game data. This may be one of two locations depending on which version of the game you have.

* '''For Steam users''': This will be your game installation directory, usually <code>C:\Program Files\Steam\steamapps\common\Amnesia - The Dark Descent\</code>
* '''For retail/other users''': This will be inside the "redist" folder inside your installation directory, for example <code>C:\Program Files\Amnesia - The Dark Descent\redist\</code>

When reporting crashes and bugs, always include a description of the problem and any log output from the editors themselves. Logs are located in your <code><Documents>\HPL2\</code> folder.

===Linux===

Download the Linux HPL Editor Suite for Amnesia:

*[https://fricpub.s3.amazonaws.com/tools/hpl2/hpl2_editor_suite-linux-2015-03-04.zip Version 1.3 and later]
*[https://fricpub.s3.amazonaws.com/tools/hpl2/hpl_editor_suite_linux.zip Version 1.2.1 and earlier]

'''Updated 2011-02-19''' Updated to fix crashes when selecting enemies.

Extract the zip and run the installer (<code>hpl_editor_suite.sh</code>).

The installer should automatically find your currently installed copy of Amnesia if you installed it in one of the common installation locations. If not, simply select the Amnesia folder where you installed the game.

'''Note:''' No menu items are created by the installer, it simply installs the editor data files and executables for your platform.

'''Note:''' The HplLangTool.exe is included in the Linux HPL editor suite, it is a .NET application that does run under wine/mono.

When reporting crashes and bugs, always include a description of the problem and any log output from the editors themselves. Logs are located in your <code>~/.frictionalgames/HPL2</code> folder.

===Mac OS X===

Download the Mac OS X HPL Editor Suite:

*[https://fricpub.s3.amazonaws.com/tools/hpl2/HPL2-EditorSuite-OSX-2015-03-04.dmg Version 1.3 and later]
*[https://fricpub.s3.amazonaws.com/tools/hpl2/hpl2editorsuite.dmg Version 1.2.1 and earlier]
*[https://fricpub.s3.amazonaws.com/tools/hpl2/hpl2editorsuite-manual.dmg Manual Install for version 1.2.1 and earlier]. (Use the Manual Install only if you have issues with the automated installer, and be ''SURE'' to read the directions)

Extract the zip and run the installer (''HPL2 Editor Suite Installer''). The installer should automatically find your currently installed copy of Amnesia no matter where you purchased it (including Steam). After installing the tools, simply run Amnesia and select the "Editor Suite" tab in the launcher to run the tools.

Notes:

*This{{clarify}} currently is not for the Mac [http://www.proleadsoft.com/mobile-app-development/| App Store] release, as updates to Amnesia will completely remove the Editor suite. Please read [http://support.frictionalgames.com/entry/103/ this] for more information.
*'''Update 2011-02-19''' Includes fixes for crashes and "hangs"
*'''Update 2011-03-19''' Includes fixes for a crash that occurs when selecting entities to add to a level
*You must install the [http://support.frictionalgames.com/entry/100/ Amnesia 1.0.1.2 Mac OS X Patch] (this is a Mac-only patch). Steam users will get the update directly from the Steam client.

When reporting crashes and bugs, always include a description of the problem and any log output from the editors themselves. Logs are located in your <code>~/Library/Application Support/Frictional Games/HPL2</code> folder.

== Community tools ==

After the HPL2 games went open-source, the community managed to compile newer editors with a few quality-of-life improvements. They are '''available for Windows and Linux.'''

===Features===
The new features include:
* A much more comfortable color picker
* Dark theme (installed by default, but the original one can be reinstated)
* Keyboard shortcuts for common utilities (e.g. grid snapping)
* Ability to load MFP maps and assets without errors
* Other small improvements

===Installation===
#Install the original editors first (not all files and editors are included in the community version).
#Go to [https://github.com/TiManGames/AmnesiaTheDarkDescent/releases this Github page] to download the latest version of the community tools.
#Download the archive in the format of your choice (.7z is smaller than .zip but requires [https://www.7-zip.org/ 7zip] or Winrar to open).
#Extract the contents into the main directory of Amnesia.
#Merge and overwrite all when asked.

HPL2/Changelog

2024-05-30T17:45:32Z

Darkfire: corrected factual errors and added some info

{{DISPLAYTITLE:Changelog}}

This article is about Amnesia: The Dark Descent's updates, focusing on modding features.

Please note that updates tend to come to Steam first (before other platforms such as GOG) and reside in a beta branch before being pushed to the main one.

To check what version you're on, check the <code>hpl.log</code> file in your Documents folder. The engine version should be at the top of the file.

== Version 1.2 ==

{{stub}}

The Justine update.

* Added the Justine expansion which includes many new assets

== Version 1.3 ==

This patch backports a bunch of features from Amnesia: The Machine For Pigs. Original, full patch notes are available [[HPL2/1.3 Changelog.txt|here]].

* Added support for FBX files and Collada models exported in 3D Max
* Added Enemy_ManPig entity type
* Added many new script functions (note: the list of the new functions in the [[HPL2/1.3 Changelog.txt|original changelog]] appears to be incomplete)
* F2 now does a quick map reload when Debug menu is loaded
* F3 now fast forwards (x3 speed) the game when Debug menu is loaded
* Errors and warnings can now be seen in-game by checking a box in the debug menu

== Version 1.4 ==

{{stub}}

This update added Hard Mode and achievements.

* Added a free camera mode when Debug menu is loaded

== Version 1.5 ==

# Ability to provide a custom story with full conversion capabilities [[HPL2/custom_story_settings.cfg | by specifying InitCfgFile in custom_story_settings.cfg]]. In other words, Full Conversions can now be installed and launched like Custom Stories. This also means you will be able to convert your existing full conversion mods into "extended" custom stories, and upload them to the Steam Workshop.
# Fixed a crash caused by using more than 216 (65,535) callbacks (the crash happened when changing levels and would usually be caused by overusing Timers)
# Added an option to [[HPL2/menu.cfg | menu.cfg]] to allow specifying colors for menu text
# Added an option to [[HPL2/main_init.cfg | main_init.cfg]] to specify how custom stories are loaded within a custom story (including if they show up at all)
# New scripting features (documentation [[HPL2/Engine_Scripts | here]]):
## Added new script function: ShowScreenImage
## Added new script callback: OnUpdate
## Added <code>#include</code> for <code>.hps</code> files
# Fixed skybox cubemaps rendering incorrectly. This removes the need for players patching a dll manually.
# Fixed "Chest" type entity changing the required coin number to zero after loading a save, [[HPL2/Tutorials/Coin_chests | making thalers actually usable]]
# Added navigation of custom story menu with gamepad
# Restored old custom story window behaviour when loading an entry (the game now starts the story immediately like in the earlier game versions, instead of having to go through a pseudo-modded menu and starting the game there)
# Fixed option to specify multiple slime types for SlimeAreas (see [[HPL2/game.cfg#Slime |Slime section in <code>game.cfg</code>]]; slime types can be added and then selected in the entity editor for Slime type entities)
# Improved color picker in editors (this only applies to the Windows version; the editors will now be included in the game files by default. Community editors still can be used, but might be overwritten by updates if you don't rename the exe files; config files will be overwritten by the update or verifying game files, so the dark theme will be removed if you use it)
# "Other fixes"

HPL2/Changelog

2024-05-30T15:42:34Z

Darkfire: Update article with other changelogs/versions

{{DISPLAYTITLE:Changelog}}

This article is about Amnesia: The Dark Descent's updates, focusing on modding features.

Please note that updates tend to come to Steam first (before other platforms such as GOG) and reside in a beta branch before being pushed to the main one.

To check what version you're on, check the <code>hpl.log</code> file in your Documents folder. The engine version should be at the top of the file.

== Version 1.3 ==

The Justine update. The original, full patch notes are available [[HPL2/1.3 Changelog.txt|here]].

* Added the Justine expansion which includes many new assets
* Added support for FBX files and Collada models exported in 3D Max
* Added Enemy_ManPig entity type
* Added many new script functions (note: the list of the new functions in the [[HPL2/1.3 Changelog.txt|original changelog]] appears to be incomplete)
* F2 now does a quick map reload when Debug menu is loaded
* F3 now fast forwards (x3 speed) the game when Debug menu is loaded
* Errors and warnings can now be seen in-game by checking a box in the debug menu

== Version 1.4 ==

{{stub}}

The achievement update.

== Version 1.5 ==

# Ability to provide a custom story with full conversion capabilities [[HPL2/custom_story_settings.cfg | by specifying InitCfgFile in custom_story_settings.cfg]]. In other words, Full Conversions can now be installed and launched like Custom Stories. This also means you will be able to convert your existing full conversion mods into "extended" custom stories, and upload them to the Steam Workshop.
# Fixed a crash caused by using more than 216 (65,535) callbacks (the crash happened when changing levels and would usually be caused by overusing Timers)
# Added an option to [[HPL2/menu.cfg | menu.cfg]] to allow specifying colors for menu text
# Added an option to [[HPL2/main_init.cfg | main_init.cfg]] to specify how custom stories are loaded within a custom story (including if they show up at all)
# New scripting features (documentation [[HPL2/Engine_Scripts | here]]):
## Added new script function: ShowScreenImage
## Added new script callback: OnUpdate
## Added <code>#include</code> for <code>.hps</code> files
# Fixed skybox cubemaps rendering incorrectly. This removes the need for players patching a dll manually.
# Fixed "Chest" type entity changing the required coin number to zero after loading a save, [[HPL2/Tutorials/Coin_chests | making thalers actually usable]]
# Added navigation of custom story menu with gamepad
# Restored old custom story window behaviour when loading an entry (the game now starts the story immediately like in the earlier game versions, instead of having to go through a pseudo-modded menu and starting the game there)
# Fixed option to specify multiple slime types for SlimeAreas (see [[HPL2/game.cfg#Slime |Slime section in <code>game.cfg</code>]]; slime types can be added and then selected in the entity editor for Slime type entities)
# Improved color picker in editors (this only applies to the Windows version; the editors will now be included in the game files by default. Community editors still can be used, but might be overwritten by updates if you don't rename the exe files; config files will be overwritten by the update or verifying game files, so the dark theme will be removed if you use it)
# "Other fixes"

HPL2/Changelog

2024-05-30T15:26:02Z

Darkfire: Darkfire moved page HPL2/1.5 Update to HPL2/Changelog: More updates are coming and it would be good to record the old ones as well.

{{DISPLAYTITLE:1.5 Update}}

This article is about Amnesia: The Dark Descent's 2023 update.

At the moment these changes are available only on Steam.

== Changelog ==

# Ability to provide a custom story with full conversion capabilities [[HPL2/custom_story_settings.cfg | by specifying InitCfgFile in custom_story_settings.cfg]]. In other words, Full Conversions can now be installed and launched like Custom Stories. This also means you will be able to convert your existing full conversion mods into "extended" custom stories, and upload them to the Steam Workshop.
# Fixed a crash caused by using more than 216 (65,535) callbacks (the crash happened when changing levels and would usually be caused by overusing Timers)
# Added an option to [[HPL2/menu.cfg | menu.cfg]] to allow specifying colors for menu text
# Added an option to [[HPL2/main_init.cfg | main_init.cfg]] to specify how custom stories are loaded within a custom story (including if they show up at all)
# New scripting features (documentation [[HPL2/Engine_Scripts | here]]):
## Added new script function: ShowScreenImage
## Added new script callback: OnUpdate
## Added <code>#include</code> for <code>.hps</code> files
# Fixed skybox cubemaps rendering incorrectly. This removes the need for players patching a dll manually.
# Fixed "Chest" type entity changing the required coin number to zero after loading a save, [[HPL2/Tutorials/Coin_chests | making thalers actually usable]]
# Added navigation of custom story menu with gamepad
# Restored old custom story window behaviour when loading an entry (the game now starts the story immediately like in the earlier game versions, instead of having to go through a pseudo-modded menu and starting the game there)
# Fixed option to specify multiple slime types for SlimeAreas (see [[HPL2/game.cfg#Slime |Slime section in <code>game.cfg</code>]]; slime types can be added and then selected in the entity editor for Slime type entities)
# Improved color picker in editors (this only applies to the Windows version; the editors will now be included in the game files by default. Community editors still can be used, but might be overwritten by updates if you don't rename the exe files; config files will be overwritten by the update or verifying game files, so the dark theme will be removed if you use it)
# "Other fixes"

HPL2/1.5 Update

2024-05-30T15:26:02Z

Darkfire: Darkfire moved page HPL2/1.5 Update to HPL2/Changelog: More updates are coming and it would be good to record the old ones as well.

#REDIRECT [[HPL2/Changelog]]

Blender

2024-04-21T16:27:08Z

Darkfire: Added info about HPL plugins

Blender is an open source 3D content creation suite that has built-in support for the file format COLLADA that the HPL engine uses to import most 3D models.

Unlike Maya, models exported from Blender don't require deprecated versions of the software to work with HPL. However, this is at a cost of lower compability (i.e. problems with exporting armatures and the inconvience of using a different up axis).

==Tutorial - Blender 2.8==
{{Note|'''Note:''' ''This tutorial was written and tested on HPL2. HPL1 and HPL3 were not tested but most likely will work as well.''}}

This tutorial goes over the most crucial practices which will make a Blender export work in HPL.

The following applies both to new models and edits of existing models. When importing a .dae model from any FG game, one has to reconstruct the materials - for some reason, they aren't imported into Blender.

Following this tutorial will make any model load in-game, but models with armatures will most likely have errors and their animations will be corrupted. See the Animation section for more information.

===General rules===

First, a few things to have in mind while making or editing a model:

#Make sure that your model has unwrapped UVs.
#Redundant textures and materials in the export will cause issues. Be careful not to add any unnecessary ones.
#HPL allows only one material with one texture per object (submesh). No more, no less.

===Importing===
Importing the COLLADA file:

Simply click File>Import>Collada. Usually this will be enough.

However, you might find that nothing actually gets imported into the program. In that case, an often issue is the <code>library_effects</code> section of the .dae file made by Maya. Copy the file, edit it with a text editor, and delete all of the contents between and including the <code>library_effects</code> tags. Doing that should fix the issue and the file should import normally.

===Exporting===

#'''Select a submesh''' and go to the '''Materials tab'''.
#Make sure that the shader is set to Principled BSDF. Other shaders don't necessarily have to cause issues, but this one has been used with success.
#Click on the circle next to the '''“Base Color”''' setting.
#Pick '''“Image Texture”''' from the pop-up menu.
#Click on '''“Open”''' and pick your texture file.
#*From now on, if you need to open the texture somewhere (e.g. for UV unwrapping), click on the square icon with a triangle and a dot and select the texture from the drop menu. This way you won't be cloning the texture. If you need to apply the created material/texture to another object or reapply it to the current one, make sure to use this method as well.
#Repeat the previous steps until all submeshes have an assigned material with a texture.
#Export the object as COLLADA (.dae) or, alternatively, as FBX. See the next section for more details.
#Before exporting, make sure to remove all non-mesh components, like lights and cameras, as well as unused textures, materials and images. This is most easily done in the tree viewer, after setting it to the "Blender file" mode. Make sure to delete the duplicate and orphaned data as well if there are any issues.
#Make sure that in export settings the '''“Geometry→Triangulate”''' option is marked.
#If the object has an armature, or is supposed to be a StaticObject (not an Entity - those can be rotated in the Model Editor), you will need to set the export "up" axis to be the Y axis (Blender uses Z as up, HPL uses Y). In case that doesn't work, you can rotate the model manually to have +Y axis as up and to face the correct axis. See notes on Blender 2.5 for more help.
#'''Open the exported file with the ModelViewer''' - it is the best of the HPL editors for quick checks and prototyping. If you've succeeded, the model will show up as textured. A .mat file will be created, to which you can add normalmaps and such. If you were editing an existing model, it should load the existing material from the original model.
#*If the viewer crashes, you probably didn't assign materials properly or didn't triangulate the model. Another cause could be that the "one material per object, one texture per material" rule wasn't followed.
#*If the model loads, but isn't textured correctly, there probably are redundant images and/or materials in the blend file.

==Blender to HPL==
===General===
HPL supports COLLADA (.dae) and FBX. COLLADA is the "go-to" format used by FG. FBX is valid too, but seems to be more likely to crash the ModelViewer if anything is incorrect.

First thing to take into account when exporting is '''UV mapping the texture'''. Adding a texture to a material without UV mapping will NOT work, it will just crash the Model Viewer (or any other HPL instance).

It is recommended that 1 unit is set to equal 1 meter.

HPL uses Y as the up axis. Blender uses Z. As of 2.8, the export option to change the up axis seems to not work for HPL, so it is recommended to rotate the object manually before exporting. This is only necessary for static objects (anything designated to be an entity can be rotated in the Model Editor) and objects with armatures (which sometimes can't be rotated in HPL).

Make sure to save your project files (.blend) in the same folder as your textures and exports - this will simplify porting to HPL, and moving the file in general. Blender should by default use relative paths, but if you used absolute paths - change that setting because it will break the model on other computers, and probably won't even load in the Model Viewer.

===Animations===

Rotation/location/scale animations can be exported without a problem, however there is no known way of exporting shape animations correctly into the .dae format.

As of now, there is no known and tested way to properly export armatures from Blender in a way for HPL to read them properly.

{{messageBox|text=Already tested solutions include: Multiple COLLADA plugins, the FBX format and various export options. None of them worked, which might hint that the issue lies within the armature set-up itself. For a potential fix (untested on newer releases), check "Notes on 2.6".}}
===Textures===

Keep in mind that HPL culls all backfaces - in other words, textures are visible from only one side of the model. If the exported model has a texture on the "inside", you need to go back to Blender and flip the normals before exporting again.

It is highly recommended to use textures with power-of-two sizes (256×256, 512×512, 128×1024 etc.). Otherwise the model might crash your Model Viewer, look awkward or result in run-time errors and slightly worse performance.

===Materials===

Each submesh can, and must, have only one material! It's been also reported that if a material gets linked to 2 different geometries/datablocks/vertex groups/etc., it will crash in HPL. However, using the same material for multiple objects should work normally.

The in-game material is an XML file (.mat) that contains information on what images (.dds, .jpg, .tga and other formats) are used in the material to create the in-game look. Always set the diffuse texture of the Blender-material to have the same name as the engine-material (.mat) you want it to have. All other textures (normalmaps, etc.) can be later added in the Material Editor.

For more information about materials, check the General section in [[Hpl3:Engine:model export|the HPL3 model export guide]]. The information there is also applicable to older HPL engine iterations.

==Plugins==

There are two plugins for HPL3 in Blender. They both are meant for making/prototyping maps in Blender,
but their features and level of documentation varies.

* [[HPL3/Blender HPL3 export plugin| HPL3 plugin from Cadely]]
* [https://github.com/rbx775/HplParser HPL3 plugin from rbx775] - might be more comprehensive as it matures

==Deprecated==

{{Note|'''''Note:''' Subsequent updates and the Blender 2.8 UI rehaul have deprecated the following sections. However, they are kept here in order to preserve any potentially useful information.''}}

===Notes on Blender 2.5===
When exporting to .dae, there will be a few issues you may notice upon importing your work into the Model Editor of Amnesia. These issues include your model appearing to be missing “pieces,” being incomplete and full of holes. The COLLADA plug-in of Blender 2.5 automatically exports everything as triangles. When it comes to converting quads (i.e. faces with four sides) it does a bad job at it. In Blender 2.5, when you convert a quad into a triangle (Ctrl + T) you'll notice the quad becomes two triangles forming a shape of a quad. However, the COLLADA plug-in when it faces a quad and converts it to a triangle it'll only provide one triangle in the place of the quad (or screw up the vertices of the second triangle). To avoid this issue, you must convert all your quads to triangles in Blender before exporting to .dae format.

Another issue you might run across is when you import your mesh into the Model Editor of Amnesia you notice that your object(s) are rotated (though in Blender it looks perfectly fine). This is caused by the local axis of the object(s) conflicting with the global axis of the environment. To fix this, in Blender, in Object mode, select the object you want to correct and in the menu on the bottom of the 3D View go to Object > Apply > Rotation. This will align the local axis of the object to the global axis of the object. Now when you import your mesh again in the Model Editor everything will be on their proper axis. Do the same for location and scale if need be.

Exporting of object names is also not currently supported in Blender 2.5. This may cause some issues when creating your own entities from your custom models. When attaching a body to your model in the Model Editor of Amnesia and the object doesn't have a name, the game will not be able to properly attach the model to the body. This may result in half of the model located at the exact center of the map, while another part having been properly attached to the model's body. The current workaround is to edit the .dae file and manually add names to your meshes. Under <library_visual_scenes>, each mesh from your model will be represented by a node tag. Simply edit the node tag by adding a name attribute with the value being the object's desired name.

For example:
<node id="Cube" type="NODE" name="Cube">
There are also issues with armatures, but full armature export support is scheduled for Blender 2.6.

===Notes on Blender 2.6===
Blender 2.6 is capable of exporting armatures to where the ModelView and Model Editor doesn't crash; however, this only after one minor tweak to the exported .dae file. It would appear that the HPL engine is not capable of finding the bones of the controller (armature) when they are parented to an armature node in the .dae file. Current workaround is to either remove the armature parent node or change its type from “NODE” to “JOINT”. Do note, though, that this only prevents the ModelView from erroring out with “Bone '%s' does not exist;” there is no guarantee that your model will look and work exactly as it does in Blender.

As of Blender 2.64 you no longer have to insert a name attribute to the node element (as shown in the notes for Blender 2.5).

As of Blender 2.68 (probably earlier), you no longer need to triangulate the mesh in edit mode before exporting. There is now a triangulate option in the COLLADA export options.

Blender armatures (though not for '''really''' complex rigs) and their animations now work with the 1.3 (Machine for Pigs compatibility) update. (This was tested with Blender 2.68, but earlier versions may work too.)

===Tutorial - Blender 2.7 and lower===

The following is intended to quickly give a sure step by step process to successfully export an object and get it to display within the game engine:

#When Blender launches it creates a default cube.
#Save the Blender project ('''Ctrl + S'''; '''File → Save''').
#Select the default cube and click on the '''Materials''' button in the ''Properties'' panel. Make sure a material is applied to the mesh (default material will work fine).
#Click on the '''Textures''' button in the ''Properties'' panel. If there is no texture applied to the material, click on '''New''' or the default texture from the list if any. Set ''Type'' to '''Image or Movie''', and in the ''Image'' menu click '''Open''' and select a texture (the .dds/.jpg/.tga/.png not the .mat file). It is best if the texture is in the same directory as the .blend file. In the ''Mapping'' menu, make sure '''UV''' is set for ''Coordinates''.
#With the cube selected, press '''TAB''' to go to ''Edit Mode''. Make sure all the faces of the mesh is selected. You can do so by pressing '''A''' on the keyboard. Press '''U''' on the keyboard and select '''Unwrap''' ('''Reset''' if you haven't created seams for the default cube).
#With all the faces still selected, convert all quads to tris either by '''Ctrl + T''' or '''Mesh → Faces → Quads to Tris'''.
#Go to the '''UV/Image Editor''' and in the pop-up menu to the right of the ''UVs'' menu, select the previously loaded texture from the list.
#Go back to '''3D View''', change draw mode (i.e. Viewport Shading) to ''Textured'' and you can see that the model is textured. You'll know it is ready for exporting if both Textured draw mode and the rendered image both show the cube textured.
#Delete the default camera and default light.
#Go to '''File → Export → COLLADA (.dae)'''. In the left panel, at the bottom, there will be export options for COLLADA, specifically texture options. If you're using external textures, then you'd want to make sure '''Include UV Textures''' is checked. If you're using internal textures, then you'd want to make sure '''Include Material Textures''' is checked. If you want to copy (or overwrite) the textures over to the save location (this should be done at least once), make sure '''Copy''' is checked.
#Save the file as “filename.dae” in a folder within one of Amnesia's directories (preferably the custom_stories directory).
#Using the model viewer you should now see the newly created cube fully textured.

Hpl2:HPL2/Tutorials/CustomSounds

2024-04-13T15:03:43Z

Darkfire: fix header error

= Adding custom sounds =
== Preparing the sounds ==

First you'll need a sound-editting program; [https://www.audacityteam.org/ Audacity] is a common choice - it is free and will suit most needs.

The sounds need to be in '''.ogg ''' format. If your sound files are formatted as '''.MP3''', '''.WAV''' or anything else, you need to use one your audio editing software of choice to convert your sound file to an '''.ogg''' file format. In Audacity, you just need to drag the file into the program and then export as '''.ogg'''.

{{tip|It is recommended to use mono files. Stereo should only be used for music and ambient tracks, because it will play directly at the player rather than play in 3D.}}

If you only want to play this sound as music, you can skip the next few steps and jump right to the custom music section.

== Managing sound files ==

In your mod's (FC or CS, doesn't matter) folder, create a folder for sounds. It can be called however you want, but '''sounds''' would probably be the best.

{{tip|If your mod has a lot of custom sounds, make sure to organise them into subfolders!}}

Place the tutorial.ogg file in the created (sub)folder.

== Creating the sound entity file ==

The behaviour of the sound in the game is determined by a "sound entity" file. These files have a '''.snt''' extension.

For the fastest workflow, copy an existing sound file that works similarly to how you want and change its name. Then alter the contents of that file rather than writing them from scratch.

{{tip|If using Notepad++, right-click a .snt file and pick Notepad++ to edit the file.}}

Alternatively, you can do the following:

Create a '''.txt''' file and name it what you want (same as the .ogg file is common), open it with any text editor you use.[[Notepad%2B%2B | Notepad++]] is recommended. When you finish editing the file, change the extension to the correct one. I named my file '''tutorial.snt'''.

{{tip|Other extensions might work, but it is recommended to give sound files the .snt extension used by the main game. This will allow your sound to be placed in a level without scripting.}}

In the file, you can edit quite a few things, and among them is..''Adding your sound-file into the script!'' And since my sound file is '''door''''''.ogg''', It shall go to the '''MAIN''' section. Random soundfiles will be covered later on.
<syntaxhighlight lang="xml">
<SOUNDENTITY>
<SOUNDS>
<Main>
<Sound File="door.ogg" />
</Main>
</SOUNDS>
<PROPERTIES Volume="5" MinDistance="1" MaxDistance="50" Random="0" Interval="0" FadeEnd="False" FadeStart="False" Stream="False" Loop="False" Use3D="false" Blockable="False" BlockVolumeMul="0.7" Priority="5" />
</SOUNDENTITY>
</syntaxhighlight>

Format explanation:

<'''SOUNDENTITY'''> is the start marker of the sound file

<'''SOUNDS'''> indicates the sound list

<'''Main'''> is the list of sounds the file will play.

<'''Sound File'''="''YourFileName''.ogg" /> is the way to add a file to the sound. Adding multiple files will play them randomly.

<'''PROPERTIES'''> Are all the options you may use to decide how the sound will behave in-game.

==Properties==

===The basics===

* '''Volume''' is how loud the sound should play. '''Volume=1''' would make the sound play at the normal volume of the sound file. '''Volume=0.5''' would half as loud. '''Volume=2''' would amplify the sound to twice its normal volume.

* '''MinDistance''' and '''MaxDistance''' are used for attenuation, which means how the sound fades out over distance. Within the '''MinDistance''' the sound will be at the full '''Volume''' level. As the player moves from '''MinDistance''' to '''MaxDistance''' away from the sound, the volume will fade towards silence. Outside of '''MaxDistance''' it does not play at all.

* '''Loop''' should be set to '''"true"''' if the sound should loop.

* '''Use3D''' should be set to '''"true"''' if the sound should originate from a point in the game world. Otherwise it will be all around the player and will not fade with distance.

Well thats it! You now created your very own sound! Place it in the map with the Level Editor or use it with <code>PlaySoundAtEntity();</code> in your level script (check [http://wiki.frictionalgames.com/hpl2/amnesia/script_functions Engine scripts] for details).

===More advanced .snt properties===

* '''Loop''', '''Random''' and '''Interval''' are all used together to define whether and how the sound should loop. '''Loop=true''' will make the sound repeat. If '''Interval''' is 0 then the sound will loop continuously, but if '''Interval''' is set to a value > 0, then that becomes a delay inserted between the repeitions. If '''Random''' is set to a value > 0 and < 1, then it defines the random chance of the sound playing on that interval. If '''Random''' is <=0 or >=1, then the sound will always play every interval.
For example, an ambient background track that should play continuously with no gaps should have:
<syntaxhighlight lang="xml">Random="1" Interval="0" Loop="true"</syntaxhighlight>
A sound that should repeat periodically, with a 25% chance of playing again every 15 seconds would be defined like this:
<syntaxhighlight lang="xml">Random="0.25" Interval="15" Loop="true"</syntaxhighlight>

* '''Random''' does ''not'' affect the random variant sounds listed in the .snt file. Those each have an equal chance of playing, although the engine will try to stop them from playing twice in a row if possible.

* '''Use3D''' causes the sound to originate from a point in space, and move between the left and right stereo channels, but it is also required for attenuation. If '''Use3D''' is false, then the sound will have no stereo separation but it will also not fade over distance. Only mono sounds can be used as 3D. Stereo sounds retain the the left/right channel in the sound file and always behave as '''Use3d="false"'''.

* '''Stream''' defines whether the sound can be preloaded. '''Stream="false"''' is the normal behaviour for short sounds that are loaded into memory and played when needed. '''Stream="true"''' makes the sound play from the disk. This is slower but saves memory, so should be used for large sound files that are played rarely.

* '''FadeEnd''' and '''FadeStart''', if true, will cause looping sounds to fade in or out on their first or last repetition.

* '''Blockable''', '''BlockVolumeMul''', and '''Priority''' do not seem to be implemented in the engine. ''('''Blockable''' and '''BlockVolumeMul''' may have been intended to define how the sounds are muffled by world geometry, and '''Priority''' may have been intended to be used when culling sounds. Although all three properties are read from the .snt file, they do not seem to be referenced in any other code.)'' {{confirm}}

* '''<SOUNDS>''' categories: as well as '''<Main>''' the engine will also read lists of sounds from '''<Start>''' and '''<Stop>''' nodes. These may provide alternate sounds for the beginning and end of a loop. {{confirm}}

==Adding custom music==

Custom music only needs to be a file in the '''.ogg''' format. It won't need an '''.snt''' file to be played with <code>PlayMusic();</code> or at the credits, but you won't be able to use <code>PlaySoundAtEntity();</code> with this file.

Just like with sounds, it is good to create a folder for music in the mod's main folder, e.g. '''music'''. Put the '''.ogg''' file there.

See [http://wiki.frictionalgames.com/hpl2/amnesia/script_functions Engine scripts] to learn how to use <code>PlayMusic();</code>.

Keep in mind that only one music file can play at a time. For ambient sound, it is better to create a sound file (like described earlier). That way you can layer ambient sound with actual music when needed.

Setting up an Online Repository

2024-03-24T11:30:48Z

Darkfire: /* HPL Engine Specifics */ update formatting and info

This article is about '''version control'''. It describes the process of setting up an online Git repository, and discusses the workflow.

{{Note|The sole purpose of the article is to explain how to set a repository up and running. '''Check "See Also" in order to learn how to actually operate and maintain the repository.'''}} 

==Introduction==
===Version control===
Version control is the process of maintaing a history of project versions which can be compared and reverted to, if anything goes wrong. A version control system basically gives you the ability to quickly create a back-up of your changes with a few clicks (this is called a "commit"). Because only the changes from the last commit (version) are recorded, this process if very quick. Loading a commit also loads all of the previous ones, so the project is always preserved in its entirety.

Changes to each file have to be added to a commit before one is created, so if something e.g. gets accidentally deleted, this change can be discarded and the file is restored (this is a much simpler and way faster process than restoring a regular back-up).

===Why do I need an online repository?===
A repository is what records all the changes in a project. Creating a repository ("repo" for short) basically means that you start to monitor changes in a project. It can be stored locally (the repo is essentially a hidden folder in your project folder), but it can also be uploaded online.

'''The biggest benefit of an online repo is the ability to easily combine changes made by all members of a mod team into a single "current" copy.''' It also allows team members to check out the versions of the project that other members are working on.

Another important benefit is having an off-site back-up of your project. If you permanently delete your project folder, the repo (which is stored inside the project folder) will be gone along with it. An online repo lets you get back all your work within minutes, if something like that happens.

If you're working on a mod by yourself, you probably don't need to put your repository online. However, for the reason stated above, it can be safer to have an online one.

==Terminology==
[[File:Git-branch-demonstration.png|alt=|thumb|Git branches are useful to separate your version from the main project version, and later be merged when your work is done. The master branch is blue, and the side branch is green.]]
{| class="wikitable"
|Repository
|The data structure that stores each commit; it is often used as a substitute for the folder which holds the project.
|-
|Commit
|A set of project changes. Commits have to be labelled (this is called a commit message) and each commit should describe what it added or changed. Commits allow to revert unwanted changes and any accidents, as well as see what was changed and when. When something breaks, this possibility makes it much easier to fix. On the graph below, individual dots are commits.
|-
|Check out
|Changing the current version of the project to a specific commit, i.e. "check out a commit".
|-
|Gitlab, Github
|Both are online services that offer to store your repos. At base level they are almost identical, although Github is more popular.
|-
|Branch
|A separate chain of commits; think of it as making your own version of the project, while others make their own ones. You can also have multiple branches made for different purposes. For example, it is advised to create a new branch when you want to test something that might break the project but can't be done in a single commit.
|-
|Clone
|"Download" a repository from the Internet.
|-
|Pull
|"Download" commits from a branch in the online repository. You pull in order to update the project on your end. The action of just downloading commits is called fetching, and pull also tries to automatically merge (see below) the changes.
|-
|Push
|"Upload" your local commits to the online repository. You push in order to update the project on the repository.
|-
|Remote
|The online version of the repository (i.e. what's on Github or Gitlab). Its online address is called an origin.
|-
|Merge
|This means joining two branches. A branch is always merged into another branch (called the target), so only one ends up having all the changes in it. Merging creates a new commit in the target branch.
|-
|Master/Main/Default Branch
|The main version of the project (note: Github and Gitlab now use "main" as the default branch). It is customary to only put stable versions of the project in the master branch. The name master comes from the default branch created along with a fresh repository, but the default branch can be set to any other branch in your online repo; in local repos, the master/main/default branch is essentially the same as any other branch.
|-
|Pull/Merge request
|If you're not an admin on the repo, you won't have the permission to push to the master branch. To have your work merged into the master, you will need to push your branch to the online repo, and then request the merge. This is called a Merge Request on Gitlab and (a bit confusingly) Pull Request on Github.
|-
|Revert
|This basically means "uncommiting" changes; reverting a commit creates a new commit that's the "opposite" of another one. It is also used as a way of saying "check out an older commit (before something was broken) and work from there".
|}

==Getting Started==
The easiest way of starting with git is to use Gitlab or Github.

You will also need a git client (i.e. a program which does all git stuff).
You can use terminal commands (it is not hard but might be challenging if you have never used a terminal before) or [https://git-scm.com/downloads/guis a GUI client].
With many of the GUI apps, you will need to first [https://git-scm.com/ install command line git] anyway.
* If you are using [[Visual Studio Code]] for developing your mod, it has an intuitive GUI for git built-in. It does not have a graph view, but it can be added using a VS Code extension.
* GitKraken - possibly the most intuitive GUI for git, but the free version is limited (your repository on Gitlab/Github cannot be private).
* GitHub Desktop and SourceTree - two other intuitive GUIs.
* Git Cola - a fully free but a bit less intuitive GUI

{{note| The following is an overview meant to be applicable to any git client. If it gets confusing, check out the Gitlab+Gitkraken tutorial below.}}

If you're only starting a mod, create a repo on Gitlab/Github, pull it to your game folder (or custom story folder) and start working on the mod in the newly created repo folder (note that the folder is called the same as your online repo).

What's more likely is that you already have some work put into the mod; you can enable an online repo in two ways then. In both methods you should end up with the repo folder being called the same as your mod folder to avoid issues with your mod.

===The hacky way===

# Create a repository on Gitlab/Github. To make things easier, name the repository the same way as your mod folder.
# Rename your local mod folder to something else (e.g. add a "2" at the end).
# Clone the repo to your game install. For example, to clone a custom story you should clone from the <code>custom_stories</code> folder. This will create a folder named the same as your repo.
# If you did not name the repo same as your mod folder, you can later rename it to anything you want. This will not affect how git works.
# Copy paste your mod contents into the repo folder.
# Add .gitignore (see below).
# Commit all the files and push.

===The proper way===

This method avoids unnecessarily copy-pasting your entire mod, but is a bit more involved on the git side.

Make sure to make the online repo empty when you're creating it on Github/Gitlab. This will display the commands you need to run to create and "sync" a local repo.
The following is a slightly expanded version of what those commands do:
# Initialize a local repository in your mod folder. You should change the initial branch to be called "main", but if you don't, this can be fixed later.
# Add .gitignore (see below).
# Add and commit all your files.
# Add your remote origin repo to the repository. The origin is a link akin to <code>git@github.com:yourusername/yourmod.git</code>.
# If you accidentally added a Readme file, pull from the repo. There should be no conflicts and the branches should merge automatically.
# Push your changes to the repo.

==Workflows==

A popular workflow is to create separate branches for new features (e.g. a new map) and merge them into the master branch when the feature in question is finished.
This way of working can be a bit inconvenient for something like modding where you can rarely separate "features" when making a game.
It can be useful when making sweeping changes to the whole mod which might break it though, like renaming asset folders.

Another workflow is:
* make your changes on the master branch
* when ready to push, pull from the repo first
* resolve conflicts (if any) locally
* fix your local changes if anything broke (e.g. a sound file you're using in a script got renamed; you'll need to change it in the script)
* push your changes

If you're properly coordinating with your teammates, conflicts should be rare.
If working solo, just using the main branch is ok.

==GitKraken and GitLab tutorial==

{{note| The set-up process might seem long and complicated, but you only need to do it once and it will save you a lot of work once you start using version control.}}

#[https://gitlab.com/ Register a free account at GitLab]
#[https://www.gitkraken.com/ Download and install GitKraken Git GUI]

===Creating the Project on GitLab===

# In your dashboard, click the green '''New project''' button or use the plus icon in the navigation bar. This opens the '''New project''' page.
# On the New project page, choose '''blank project.'''
# On the '''Blank project''' tab, provide the following information:
#* The name of your project in the '''Project name''' field. When adding the name, the '''Project slug''' will auto populate. The slug is what the GitLab instance will use as the URL path to the project. If you want a different slug, input the project name first, then change the slug after.
#* The '''Project description (optional)''' field enables you to enter a description for your project’s dashboard, which will help others understand what your project is about. Though it’s not required, it’s a good idea to fill this in.
#* Changing the '''Visibility Level''' modifies the project’s viewing and access rights for users.
#* (Optional) Selecting the Initialize repository with a README option creates a README file so that the Git repository is initialized, has a default branch, and can be cloned.
# Click '''Create project.'''

{{note|Usually, you may want to initialize your project with a '''README''' file, but if you already have an existing mod folder you want to push to git, do not initialize your project with a '''README''' file. Save the project and follow the instructions inside for '''pushing an existing folder'''.}}

===Setting up GitKraken===

#Open GitKraken.
#Go to '''File->Preferences->Authentication'''.
#Select '''GitLab''' and click on '''Connect to GitLab'''.
#Approve the connection.
#It is recommended to generate an SSH key and add it to your GitLab account. [https://www.youtube.com/watch?v=z7jVOenqFYk Here's a guide].

===Cloning the Project using GitKraken===

#Open a new tab if there isn't one open already, and click on '''Clone a Repo''' and then '''GitLab'''
#In '''Where to clone to, n'''avigate to the directory in which you want to place the mod folder at.
#Select the '''Repository to clone''' and click on '''Clone the repo!'''
#Wait until the files are copied. When it's done, a prompt will show up to open the repo in the app - click on it to open the repository window.
#You can now create branches, commit, pull and push your changes via GitKraken!

==HPL Engine Specifics==
When it comes to modding on the HPL engine, the following files should be added to the [https://git-scm.com/docs/gitignore .gitignore file]:

<pre>
*.map_cache
*.preload_cache
</pre>

The files on the gitignore list won't show up in your changes list between commits, making it much less cluttered.
However, remember that you should still include these files in your mod release.

Another thing to note is that unlike HPL3, HPL2's map format is not designed with version control in mind.
This means that if you and your teammate both change the same map, the changes might be impossible to merge.
As such, you should avoid working on the same maps at the same time.

==See Also==

Videos:
* [https://youtu.be/hwP7WQkmECE?si=nu8cDNFgEoXaO-_G Git explained in 100 seconds]
* [https://www.youtube.com/watch?v=HVsySz-h9r4 Git Tutorial: Command-line Fundamentals]
* [https://www.youtube.com/watch?v=ub9GfRziCtU GitKraken Tutorial For Beginners]

[[Category:Modding]]

Visual Studio Code

2024-03-24T10:51:29Z

Darkfire: Correct information about VS Code, add tutorial link

Visual Studio Code is a lightweight code and config editor.
Featuring an integrated project folder browser and a simple but powerful interface, it is one of the best tools for developing HPL2 mods (for HPL3 it works well too, but [[CodeLite]] might be a better option).

While VS Code is open-source, its releases still contain Microsoft's telemetry and tracking.
[https://vscodium.com/ VSCodium] is a "clean" version without those elements. It is functionally identical to VS Code.

== HPL2 ==

* Check out the built-in tutorial and the [https://code.visualstudio.com/docs/introvideos/basics online tutorial]. Some particularly useful features are:
** Ctrl+Shift+F to search text in the entire project folder
** Alt+Up/Down arrows to move lines of code
** Ctrl+Shift+Alt+Up/Down to copy lines of code
** Built-in git version control interface (if you already have git installed). This is one of the more convenient ways of using git. Read more about version control [[Setting up an Online Repository | here]] and more about git in VS Code [https://code.visualstudio.com/docs/sourcecontrol/intro-to-git here].
* Open your mod folder.
* Add highlighting for HPL2 file types; Open the settings menu (Ctrl+,) and search "file associations". You can do this in the User tab (global) or the Workspace tab (will only apply to this project folder). Then add:
** <code>*.hps</code> with a value of <code>cpp</code>
** <code>*.lang</code> with a value of <code>xml</code>
** <code>*.cfg</code> with a value of <code>xml</code>
** You can also add associations for other HPL files, such as: .ent, .dae, .snt and so on. Pretty much all files in HPL2 use XML.
** This will also add auto-completion for various things (like function names) that have been written anywhere else in the project.

Unlike HPL3, using a C++ extension will make things worse for you, as HPL2's style of scripting is not fully compatible with C++ standards (mainly; built-in functions don't have to and can't be included, and the <code>&in</code> <code>&out</code> syntax).
There do exist a few AngelScript plugins for VS Code, but none of them are suitable (and several of them are abandoned).
As such, there is no good way of adding hints for built-in HPL2 script functions at the moment.

== HPL3 ==

''Main article: [[HPL3/Scripting/Scripting Guide/Setting up Visual Studio Code | Setting up Visual Studio Code]]''

Visual Studio Code

2024-03-23T17:52:49Z

Darkfire: fix formatting, clarify notes about extensions

Visual Studio Code is a lightweight code and config editor based on Microsoft's full IDE Visual Studio.
Featuring an integrated project folder browser and a simple but powerful interface, it is one of the best tools for developing HPL2 mods (for HPL3 it works well too, but [[CodeLite]] might be a better option).

An open-source version is available: [https://vscodium.com/ VSCodium]. It is functionally identical to VS Code.

== HPL2 ==

* Open your mod folder
* Check out the built-in VS Code tutorial. Some particularly useful features are:
** Ctrl+Shift+F to search text in the entire project folder
** Alt+Up/Down arrows to move lines of code
** Ctrl+Shift+Alt+Up/Down to copy lines of code
** Built-in git version control interface (if you already have git installed). This is one of the more convenient ways of using git. Read more about version control [[Setting up an Online Repository | here]] and more about git in VS Code [https://code.visualstudio.com/docs/sourcecontrol/intro-to-git here].
* Add highlighting for HPL2 file types; Open the settings menu (Ctrl+,) and search "file associations". You can do this in the User tab (global) or the Workspace tab (will only apply to this project folder). Then add:
** <code>*.hps</code> with a value of <code>cpp</code>
** <code>*.lang</code> with a value of <code>xml</code>
** <code>*.cfg</code> with a value of <code>xml</code>
** You can also add associations for other HPL files, such as: .ent, .dae, .snt and so on. Pretty much all files in HPL2 use XML.
** This will also add auto-completion for various things (like function names) that have been written anywhere else in the project.

Unlike HPL3, using a C++ extension will make things worse for you, as HPL2's style of scripting is not fully compatible with C++ standards (mainly; built-in functions don't have to and can't be included, and the <code>&in</code> <code>&out</code> syntax).
There do exist a few AngelScript plugins for VS Code, but none of them are suitable (and several of them are abandoned).
As such, there is no good way of adding hints for built-in HPL2 script functions at the moment.

== HPL3 ==

''Main article: [[HPL3/Scripting/Scripting Guide/Setting up Visual Studio Code | Setting up Visual Studio Code]]''

Setting up an Online Repository

2024-03-23T17:38:31Z

Darkfire: Add new content, make a few things more understandable

This article is about '''version control'''. It describes the process of setting up an online Git repository, and discusses the workflow.

{{Note|The sole purpose of the article is to explain how to set a repository up and running. '''Check "See Also" in order to learn how to actually operate and maintain the repository.'''}} 

==Introduction==
===Version control===
Version control is the process of maintaing a history of project versions which can be compared and reverted to, if anything goes wrong. A version control system basically gives you the ability to quickly create a back-up of your changes with a few clicks (this is called a "commit"). Because only the changes from the last commit (version) are recorded, this process if very quick. Loading a commit also loads all of the previous ones, so the project is always preserved in its entirety.

Changes to each file have to be added to a commit before one is created, so if something e.g. gets accidentally deleted, this change can be discarded and the file is restored (this is a much simpler and way faster process than restoring a regular back-up).

===Why do I need an online repository?===
A repository is what records all the changes in a project. Creating a repository ("repo" for short) basically means that you start to monitor changes in a project. It can be stored locally (the repo is essentially a hidden folder in your project folder), but it can also be uploaded online.

'''The biggest benefit of an online repo is the ability to easily combine changes made by all members of a mod team into a single "current" copy.''' It also allows team members to check out the versions of the project that other members are working on.

Another important benefit is having an off-site back-up of your project. If you permanently delete your project folder, the repo (which is stored inside the project folder) will be gone along with it. An online repo lets you get back all your work within minutes, if something like that happens.

If you're working on a mod by yourself, you probably don't need to put your repository online. However, for the reason stated above, it can be safer to have an online one.

==Terminology==
[[File:Git-branch-demonstration.png|alt=|thumb|Git branches are useful to separate your version from the main project version, and later be merged when your work is done. The master branch is blue, and the side branch is green.]]
{| class="wikitable"
|Repository
|The data structure that stores each commit; it is often used as a substitute for the folder which holds the project.
|-
|Commit
|A set of project changes. Commits have to be labelled (this is called a commit message) and each commit should describe what it added or changed. Commits allow to revert unwanted changes and any accidents, as well as see what was changed and when. When something breaks, this possibility makes it much easier to fix. On the graph below, individual dots are commits.
|-
|Check out
|Changing the current version of the project to a specific commit, i.e. "check out a commit".
|-
|Gitlab, Github
|Both are online services that offer to store your repos. At base level they are almost identical, although Github is more popular.
|-
|Branch
|A separate chain of commits; think of it as making your own version of the project, while others make their own ones. You can also have multiple branches made for different purposes. For example, it is advised to create a new branch when you want to test something that might break the project but can't be done in a single commit.
|-
|Clone
|"Download" a repository from the Internet.
|-
|Pull
|"Download" commits from a branch in the online repository. You pull in order to update the project on your end. The action of just downloading commits is called fetching, and pull also tries to automatically merge (see below) the changes.
|-
|Push
|"Upload" your local commits to the online repository. You push in order to update the project on the repository.
|-
|Remote
|The online version of the repository (i.e. what's on Github or Gitlab). Its online address is called an origin.
|-
|Merge
|This means joining two branches. A branch is always merged into another branch (called the target), so only one ends up having all the changes in it. Merging creates a new commit in the target branch.
|-
|Master/Main/Default Branch
|The main version of the project (note: Github and Gitlab now use "main" as the default branch). It is customary to only put stable versions of the project in the master branch. The name master comes from the default branch created along with a fresh repository, but the default branch can be set to any other branch in your online repo; in local repos, the master/main/default branch is essentially the same as any other branch.
|-
|Pull/Merge request
|If you're not an admin on the repo, you won't have the permission to push to the master branch. To have your work merged into the master, you will need to push your branch to the online repo, and then request the merge. This is called a Merge Request on Gitlab and (a bit confusingly) Pull Request on Github.
|-
|Revert
|This basically means "uncommiting" changes; reverting a commit creates a new commit that's the "opposite" of another one. It is also used as a way of saying "check out an older commit (before something was broken) and work from there".
|}

==Getting Started==
The easiest way of starting with git is to use Gitlab or Github.

You will also need a git client (i.e. a program which does all git stuff).
You can use terminal commands (it is not hard but might be challenging if you have never used a terminal before) or [https://git-scm.com/downloads/guis a GUI client].
With many of the GUI apps, you will need to first [https://git-scm.com/ install command line git] anyway.
* If you are using [[Visual Studio Code]] for developing your mod, it has an intuitive GUI for git built-in. It does not have a graph view, but it can be added using a VS Code extension.
* GitKraken - possibly the most intuitive GUI for git, but the free version is limited (your repository on Gitlab/Github cannot be private).
* GitHub Desktop and SourceTree - two other intuitive GUIs.
* Git Cola - a fully free but a bit less intuitive GUI

{{note| The following is an overview meant to be applicable to any git client. If it gets confusing, check out the Gitlab+Gitkraken tutorial below.}}

If you're only starting a mod, create a repo on Gitlab/Github, pull it to your game folder (or custom story folder) and start working on the mod in the newly created repo folder (note that the folder is called the same as your online repo).

What's more likely is that you already have some work put into the mod; you can enable an online repo in two ways then. In both methods you should end up with the repo folder being called the same as your mod folder to avoid issues with your mod.

===The hacky way===

# Create a repository on Gitlab/Github. To make things easier, name the repository the same way as your mod folder.
# Rename your local mod folder to something else (e.g. add a "2" at the end).
# Clone the repo to your game install. For example, to clone a custom story you should clone from the <code>custom_stories</code> folder. This will create a folder named the same as your repo.
# If you did not name the repo same as your mod folder, you can later rename it to anything you want. This will not affect how git works.
# Copy paste your mod contents into the repo folder.
# Add .gitignore (see below).
# Commit all the files and push.

===The proper way===

This method avoids unnecessarily copy-pasting your entire mod, but is a bit more involved on the git side.

Make sure to make the online repo empty when you're creating it on Github/Gitlab. This will display the commands you need to run to create and "sync" a local repo.
The following is a slightly expanded version of what those commands do:
# Initialize a local repository in your mod folder. You should change the initial branch to be called "main", but if you don't, this can be fixed later.
# Add .gitignore (see below).
# Add and commit all your files.
# Add your remote origin repo to the repository. The origin is a link akin to <code>git@github.com:yourusername/yourmod.git</code>.
# If you accidentally added a Readme file, pull from the repo. There should be no conflicts and the branches should merge automatically.
# Push your changes to the repo.

==Workflows==

A popular workflow is to create separate branches for new features (e.g. a new map) and merge them into the master branch when the feature in question is finished.
This way of working can be a bit inconvenient for something like modding where you can rarely separate "features" when making a game.
It can be useful when making sweeping changes to the whole mod which might break it though, like renaming asset folders.

Another workflow is:
* make your changes on the master branch
* when ready to push, pull from the repo first
* resolve conflicts (if any) locally
* fix your local changes if anything broke (e.g. a sound file you're using in a script got renamed; you'll need to change it in the script)
* push your changes

If you're properly coordinating with your teammates, conflicts should be rare.
If working solo, just using the main branch is ok.

==GitKraken and GitLab tutorial==

{{note| The set-up process might seem long and complicated, but you only need to do it once and it will save you a lot of work once you start using version control.}}

#[https://gitlab.com/ Register a free account at GitLab]
#[https://www.gitkraken.com/ Download and install GitKraken Git GUI]

===Creating the Project on GitLab===

# In your dashboard, click the green '''New project''' button or use the plus icon in the navigation bar. This opens the '''New project''' page.
# On the New project page, choose '''blank project.'''
# On the '''Blank project''' tab, provide the following information:
#* The name of your project in the '''Project name''' field. When adding the name, the '''Project slug''' will auto populate. The slug is what the GitLab instance will use as the URL path to the project. If you want a different slug, input the project name first, then change the slug after.
#* The '''Project description (optional)''' field enables you to enter a description for your project’s dashboard, which will help others understand what your project is about. Though it’s not required, it’s a good idea to fill this in.
#* Changing the '''Visibility Level''' modifies the project’s viewing and access rights for users.
#* (Optional) Selecting the Initialize repository with a README option creates a README file so that the Git repository is initialized, has a default branch, and can be cloned.
# Click '''Create project.'''

{{note|Usually, you may want to initialize your project with a '''README''' file, but if you already have an existing mod folder you want to push to git, do not initialize your project with a '''README''' file. Save the project and follow the instructions inside for '''pushing an existing folder'''.}}

===Setting up GitKraken===

#Open GitKraken.
#Go to '''File->Preferences->Authentication'''.
#Select '''GitLab''' and click on '''Connect to GitLab'''.
#Approve the connection.
#It is recommended to generate an SSH key and add it to your GitLab account. [https://www.youtube.com/watch?v=z7jVOenqFYk Here's a guide].

===Cloning the Project using GitKraken===

#Open a new tab if there isn't one open already, and click on '''Clone a Repo''' and then '''GitLab'''
#In '''Where to clone to, n'''avigate to the directory in which you want to place the mod folder at.
#Select the '''Repository to clone''' and click on '''Clone the repo!'''
#Wait until the files are copied. When it's done, a prompt will show up to open the repo in the app - click on it to open the repository window.
#You can now create branches, commit, pull and push your changes via GitKraken!

==HPL Engine Specifics==
When it comes to modding with the HPL engine, the following files should be added to the [https://git-scm.com/docs/gitignore .gitignore] list:

*<code>*.map_cache</code>
*<code>*.preload_cache</code>

The files on the gitignore list won't show up in your changes list between commits, making it much less cluttered.

Another thing to note is that HPL2's map format is not designed with version control in mind.
This means that if you and your teammate change the same map, the changes might be impossible to merge in reasonable time.
As such, you should avoid working on the same maps at the same time.

HPL3 maps should work fine with git.

==See Also==

Videos:
* [https://youtu.be/hwP7WQkmECE?si=nu8cDNFgEoXaO-_G Git explained in 100 seconds]
* [https://www.youtube.com/watch?v=HVsySz-h9r4 Git Tutorial: Command-line Fundamentals]
* [https://www.youtube.com/watch?v=ub9GfRziCtU GitKraken Tutorial For Beginners]

[[Category:Modding]]

Visual Studio Code

2024-03-23T13:57:46Z

Darkfire: comment out faulty tutorial (for now) and add info about linter

Visual Studio Code is a lightweight code and config editor based on Microsoft's full IDE Visual Studio.
Featuring an integrated project folder browser and a simple but powerful interface, it is one of the best tools for developing HPL2 mods (for HPL3 it works well too, but [[CodeLite]] might be a better option).

An open-source version is available: [https://vscodium.com/ VSCodium]. It is functionally identical to VS Code.

== HPL2 ==

* Open your mod folder
* Check out the built-in VS Code tutorial. Some particularly useful features are:
** Ctrl+Shift+F to search text in the entire project folder
** Alt+Up/Down arrows to move lines of code
** Ctrl+Shift+Alt+Up/Down to copy lines of code
** Built-in git version control interface (if you already have git installed). This is one of the more convenient ways of using git. Read more about version control [[Setting up an Online Repository | here]] and more about git in VS Code [https://code.visualstudio.com/docs/sourcecontrol/intro-to-git here].
* Add highlighting for HPL2 file types; Open the settings menu (Ctrl+,) and search "file associations". You can do this in the User tab (global) or the Workspace tab (will only apply to this project folder).
Then add:
** <code>*.hps</code> with a value of <code>cpp</code>
** <code>*.lang</code> with a value of <code>xml</code>
** <code>*.cfg</code> with a value of <code>xml</code>
** You can also add associations for other HPL files, such as: .ent, .dae, .snt and so on. Pretty much all files in HPL2 use XML.
** This will also add auto-completion for various things (like function names) that have been written anywhere else in the project.

At the moment, there is no dedicated way of adding autocompletion for HPL2 script function signatures.

Unlike HPL3, using a C++ extension will make things worse for you, as HPL2's style of scripting is not fully compatible with C++ standards.
There do exist a few AngelScript plugins for VS Code, but none of them are any good (and several of them are abandoned).



== HPL3 ==

''Main article: [[HPL3/Scripting/Scripting Guide/Setting up Visual Studio Code | Setting up Visual Studio Code]]''

Visual Studio Code

2024-03-23T13:19:48Z

Darkfire: Expand article to feature HPL2 config

Visual Studio Code is a lightweight code and config editor based on Microsoft's full IDE Visual Studio.
Featuring an integrated project folder browser and a simple but powerful interface, it is one of the best tools for developing HPL2 mods (for HPL3 it works well too, but [[CodeLite]] might be a better option).

An open-source version is available: [https://vscodium.com/ VSCodium]. It is functionally identical to VS Code.

== HPL2 ==

* Open your mod folder
* Check out the built-in VS Code tutorial. Some particularly useful features are:
** Ctrl+Shift+F to search text in the entire project folder
** Alt+Up/Down arrows to move lines of code
** Ctrl+Shift+Alt+Up/Down to copy lines of code
** Built-in git version control interface (if you already have git installed). This is one of the more convenient ways of using git. Read more about version control [[Setting up an Online Repository | here]] and more about git in VS Code [https://code.visualstudio.com/docs/sourcecontrol/intro-to-git here].
* Add highlighting for HPL2 file types; Open the settings menu (Ctrl+,) and search "file associations". You can do this in the User tab (global) or the Workspace tab (will only apply to this project folder).
Then add:
** <code>*.hps</code> with a value of <code>cpp</code>
** <code>*.lang</code> with a value of <code>xml</code>
** <code>*.cfg</code> with a value of <code>xml</code>
** You can also add associations for other HPL files, such as: .ent, .dae, .snt and so on. Pretty much all files in HPL2 use XML.

Optional: Install the [https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools cpptools] extension to get better error detection and other helpful features for scripting.
This step is optional, as VS Code will still give you hints about code that you have already written once anywhere in the project.
Note that using this extension will require some extra configuration because HPL's AngelScript is not pure C++.
If you're using VSCodium, you will have to [https://stackoverflow.com/questions/42017617/how-to-install-vs-code-extension-manually install the extension manually].

You can also check out the HPL3 section, as certain parts of it are also relevant to HPL2.

== HPL3 ==

''Main article: [[HPL3/Scripting/Scripting Guide/Setting up Visual Studio Code | Setting up Visual Studio Code]]''

HPL2/Third party tools

2024-03-23T12:51:41Z

Darkfire: Reorganised sections, linked to VS code page

Information on some of the third-party tools that can be used to create models, graphics and art for the game and what specific things you will need to setup to make it all work.

===Text/Script coding programs===

# [[Visual Studio Code]] is pretty much the best option for developing mods.
#[[Notepad%2B%2B|Notepad++]]: An advanced text editor.
#[[Geany|Geany]]: An alternative for Notepad++.

Mac OS X alternatives:

#[[:hpl2:third_party_tools:text:textwrangler|TextWrangler]]: A good alternative to Notepad++ on Windows.
#[[TextMate|TextMate]]: A nice and smooth code editor with many customization options.

===3D programs===

All 3D models regardless of program used must be exported to the [http://collada.org Collada] format or [http://en.wikipedia.org/wiki/FBX FBX] format (note that FBX support was added in Amnesia version 1.3).

#[[Blender]] - Open-source 3D modeling program that comes with built-in support for [http://collada.org Collada].
#[[Autodesk_Maya|Autodesk Maya]] - Professional 3D modeling program with [https://collada.org/mediawiki/index.php/OpenCOLLADA OpenCOLLADA] plugin support.

===2D programs===

#[[GIMP]] - Open-source 2D GNU Image Manipulation Program.
#[https://krita.org/ Krita] - a free and open source image editing program with focus on painting. It is more similar to Photoshop than GIMP.
#[[Adobe_Photoshop|Adobe Photoshop]] - Professional image editing software.
#[[Paint.NET|Paint.net]]

===Audio programs===

#[[Audacity]] - a general-use audio recording and manipualtion tool.
#[https://lmms.io/ LMMS] - a free and open source program for making music.

==Community resources==



===Script packages===

#[[HPL2/HPL2_Helper_Scripts|HPL2 Helper Scripts]] is a package of .hps files containing script classes and functions that may be useful in advanced HPL2 scripts. Requires ATDD version 1.5 to work.

===Asset packs===

The following are available as Steam Workshop dependencies (requires TDD version 1.5), but can also be used as regular asset packs:

#[[AMFP_Asset_pack_installation_and_usage|AMFP Asset pack installation and usage]] - A complete package of assets unique to The Machine For Pigs, with minimal overhauls and quality of life improvements.
#[[Amadeus_Asset_pack_installation_and_usage| Amadeus asset pack installation and usage]]
#[[LucysEyes_Asset_pack_installation_and_usage| In Lucy's Eyes asset pack installation and usage]]

HPL2/Third party tools

2024-01-31T17:03:22Z

Darkfire: Clean up, add LMMS to the audio program list

Information on some of the third-party tools that can be used to create models, graphics and art for the game and what specific things you will need to setup to make it all work.

===3D programs===

All 3D models regardless of program used must be exported to the [http://collada.org Collada] format or [http://en.wikipedia.org/wiki/FBX FBX] format (note that FBX support was added in Amnesia version 1.3).

#[[Blender]] - Open-source 3D modeling program that comes with built-in support for [http://collada.org Collada].
#[[Autodesk_Maya|Autodesk Maya]] - Professional 3D modeling program with [https://collada.org/mediawiki/index.php/OpenCOLLADA OpenCOLLADA] plugin support.

===2D programs===

#[[GIMP]] - Open-source 2D GNU Image Manipulation Program.
#[https://krita.org/ Krita] - a free and open source image editing program with focus on painting. It is more similar to Photoshop than GIMP.
#[[Adobe_Photoshop|Adobe Photoshop]] - Professional image editing software.
#[[Paint.NET|Paint.net]]

===Audio programs===

#[[Audacity]] - a general-use audio recording and manipualtion tool.
#[https://lmms.io/ LMMS] - a free and open source program for making music.

===Text/Script coding programs===

#[[Notepad%2B%2B|Notepad++]]: An advanced text editor.
# [https://vscodium.com/ VSCodium], an open version of VSCode. Has much better editing, search and autocomplete capabilities than Notepad++. You will need to add .hps as a C++ extension and .lang as an XML extension to get syntax highlighting.
#[[Geany|Geany]]: An alternative for Notepad++.

Mac OS X alternatives:

#[[:hpl2:third_party_tools:text:textwrangler|TextWrangler]]: A good alternative to Notepad++ on Windows.
#[[TextMate|TextMate]]: A nice and smooth code editor with many customization options.

==Community resources==



===Script packages===

#[[HPL2/HPL2_Helper_Scripts|HPL2 Helper Scripts]] is a package of .hps files containing script classes and functions that may be useful in advanced HPL2 scripts. Requires ATDD version 1.5 to work.

===Asset packs===

The following are available as Steam Workshop dependencies (requires TDD version 1.5), but can also be used as regular asset packs:

#[[AMFP_Asset_pack_installation_and_usage|AMFP Asset pack installation and usage]] - A complete package of assets unique to The Machine For Pigs, exactly as they work in aforementioned game, with minimal overhauls and quality of life improvements.
#[[Amadeus_Asset_pack_installation_and_usage| Amadeus asset pack installation and usage]]
#[[LucysEyes_Asset_pack_installation_and_usage| In Lucy's Eyes asset pack installation and usage]]

HPL2/Changelog

2023-10-25T19:28:53Z

Darkfire: remove mention of Steam beta branch

HPL2/Changelog

2023-10-25T13:03:02Z

Darkfire: clarified the part about editor overwriting

{{DISPLAYTITLE:1.5 Update}}

This article is about Amnesia: The Dark Descent's 2023 update.

At the moment these changes are available only on a Steam beta release of the game.

{{tip|On Steam, right click Amnesia > Properties... > Betas > Select "Public total conversion beta" in Beta participation. Be warned that this can overwrite community editors.}}

== Changelog ==

# Ability to provide a custom story with full conversion capabilities [[HPL2/custom_story_settings.cfg | by specifying InitCfgFile in custom_story_settings.cfg]]. In other words, Full Conversions can now be installed and launched like Custom Stories. This also means you will be able to convert your existing full conversion mods into "extended" custom stories, and upload them to the Steam Workshop.
# Fixed a crash caused by using more than 216 (65,535) callbacks (the crash happened when changing levels and would usually be caused by overusing Timers)
# Added an option to [[HPL2/menu.cfg | menu.cfg]] to allow specifying colors for menu text
# Added an option to [[HPL2/main_init.cfg | main_init.cfg]] to specify how custom stories are loaded within a custom story (including if they show up at all)
# New scripting features (documentation [[HPL2/Engine_Scripts | here]]):
## Added new script function: ShowScreenImage
## Added new script callback: OnUpdate
## Added <code>#include</code> for <code>.hps</code> files
# Fixed skybox cubemaps rendering incorrectly. This removes the need for players patching a dll manually.
# Fixed "Chest" type entity changing the required coin number to zero after loading a save, [[HPL2/Tutorials/Coin_chests | making thalers actually usable]]
# Added navigation of custom story menu with gamepad
# Restored old custom story window behaviour when loading an entry (the game now starts the story immediately like in the earlier game versions, instead of having to go through a pseudo-modded menu and starting the game there)
# Fixed option to specify multiple slime types for SlimeAreas (see [[HPL2/game.cfg#Slime |Slime section in <code>game.cfg</code>]]; slime types can be added and then selected in the entity editor for Slime type entities)
# Improved color picker in editors (this only applies to the Windows version; the editors will now be included in the game files by default. Community editors still can be used, but might be overwritten by updates if you don't rename the exe files; config files will be overwritten by the update or verifying game files, so the dark theme will be removed if you use it)
# "Other fixes"

HPL2/Changelog

2023-10-25T13:00:49Z

Darkfire: added missing entries to the changelog

HPL2/Engine Scripts

2023-09-28T10:38:37Z

Darkfire: /* Main */ explain the OnUpdate afStep argument

{{TocRight}}

This page documents all scripts available in Amnesia: The Dark Descent.

{{note|'''Note''': Some of the functions require the Amnesia 1.3 or 1.5 update. Steam and other online store copies should be automatically updated. Other copies can get 1.3 [http://www.frictionalgames.com/forum/thread-24334.html here].}}

== Directives ==

First off, <code>#include "file.hps"</code> can be used to programmatically merge together multiple separate files to make organizing scripts easier.

{{ReqVer|1.5}}

==Engine scripts==
===Main===

The following functions are the main hps functions that the HPL2 engine looks to run on certain events - similar to the C++ int main() function.

<syntaxhighlight lang="cpp">
void OnStart();
</syntaxhighlight>

The function that runs when the map is loaded for the first time.

<syntaxhighlight lang="c++">
void OnEnter();
</syntaxhighlight>

The function that runs whenever the player enters a map.

<syntaxhighlight lang="c++">
void OnLeave();
</syntaxhighlight>

The function that runs when the player leaves a map.

<syntaxhighlight lang="c++">
void OnGameStart();
</syntaxhighlight>

This function is found in the global.hps file and the inventory.hps file, and is run when the game is first started by the player (ie via "Start New Game").

<syntaxhighlight lang="c++">
void OnUpdate(float afStep);
</syntaxhighlight>
{{ReqVer|1.5}}

This function is executed for every game update or "tick". Can be used for rapid-firing updates instead of looping timers. Keep in mind that this can affect game performance if not used with care.

#''afStep''- time elapsed since the last frame. Multiply speeds, distances etc. by this argument to avoid framerate dependence issues (for example: if you move something in this function with constant speed, it will move faster on computers which run the game with high FPS and slower on computers with low FPS).

===General===

<syntaxhighlight lang="c++">
float RandFloat(float afMin, float afMax);
</syntaxhighlight>

Generates a random float.

#''afMin ''- minimum value
#''afMax ''- maximum value
<syntaxhighlight lang="c++">
int RandInt(int alMin, int alMax);
</syntaxhighlight>

Generates a random int. Note: the maximum value is ''inclusive'' - the RandInt() function may return this value.

#''alMin ''- minimum value
#''alMax ''- maximum value
<syntaxhighlight lang="c++">
bool StringContains(string& asString, string& asSubString);
</syntaxhighlight>

Checks whether a string contains the specified string. Example: searching for "hello" in "hello world" would return '''true'''.

#''asString ''- the string to check
#''asSubString ''- the string to search for
<syntaxhighlight lang="cpp">
string& StringSub(string& asString, int alStart, int alCount);
</syntaxhighlight>

Returns the substring in a string. Example: in the string "frictional games rocks", using 4 as ''alStart'' and 6 as ''alCount'' would return '''"tional"'''.

#''asString ''- the string
#''alStart ''- start position in the string
#''alCount ''- amount of characters
<syntaxhighlight lang="c++">
int StringToInt(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns an integer converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
float StringToFloat(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a float converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
bool StringToBool(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a boolean converted from a string, else returns false.

#''asString'' - String to convert.

===Mathematical Operations===

<syntaxhighlight lang="c++">
float MathSin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathCos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathTan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAsin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAcos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan2(float afX, float afY);
</syntaxhighlight>

{{ReqVer|1.3}}

Calculates and returns the arc tangent of the specified values.

#''afX'' - First value to operate.
#''afY'' - Second value to operate.
<syntaxhighlight lang="c++">
float MathSqrt(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the square root of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathPow(float afBase, float afExp);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the value of afBase raised to the power of afExp.

#''afBase'' - The base value.
#''afExp'' - Value to calculate the base with.
<syntaxhighlight lang="c++">
float MathMin(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the lowest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathMax(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the highest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathClamp(float afX, float afMin, float afMax);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns afX clamped between afMin and afMax. If afX < afMin, returns afMin, and if afX > afMax, returns afMax.

#''afX'' - The value to clamp.
#''afMin'' - The minimum value to clamp afX with.
#''afMax'' - The maximum value to clamp afX with.
<syntaxhighlight lang="c++">
float MathAbs(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the absolute value.

#''afX'' - Value to operate.

===Debugging===

<syntaxhighlight lang="cpp">
void Print(string& asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string& asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a string to the debug console.

#''asString ''- the string to print
#''abCheckForDuplicates ''- if true, the string won't be printed more than once on screen until it disappears
<syntaxhighlight lang="c++">
void ProgLog(string& asLevel, string& asMessage);
</syntaxhighlight>

Prints an entry to the ProgLog (progression log). ProgLog is a file created in Documents/Amnesia/main (or an FC folder if one is being used). It logs certain events, such us opening the menu or picking up the lantern, as well as the player's state (Health, Sanity, Oil, Tinderboxes, Coins), for the purpose of documenting a tester's playstyle. This function allows to log custom messages.The messages in the ProgLog file are sorted by time elapsed since a map was loaded.

ProgLog has to be enabled for a player profile in ''user_settings.cfg'' before it starts working.

#''asLevel ''- can be "Low", "Medium" or "High". It's a tag which appears in each log entry, for event prioritising.
#''asMessage ''- The custom message to be printed to the log.
<syntaxhighlight lang="c++">
bool ScriptDebugOn();
</syntaxhighlight>

Checks whether the debug mode is enabled. See [[HPL2/Development_Environment|"Setting up Development Environment"]] to setup debug mode on your own computer.

===Variables===
{{warning|Regular variables (int, float, etc.) are '''not''' saved by the game. Using them in important parts of yor script will break it upon loading a game save. In HPL, those variables should only be used for disposable counters, like spawning objects in a "for" loop. For variables which need to be saved, use the wrappers as described below.}}

====Local====

Local variables can be used throughout the same script file.

<syntaxhighlight lang="cpp">
void SetLocalVarInt(string& asName, int alVal);
void AddLocalVarInt(string& asName, int alVal);
int GetLocalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string& asName, float afVal);
void AddLocalVarFloat(string& asName, float afVal);
float GetLocalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string& asName, const string& asVal);
void AddLocalVarString(string& asName, string& asVal);
string& GetLocalVarString(string& asName);
</syntaxhighlight>

====Global====

Global variables can be used throughout several maps and can be accessed by several script files.

<syntaxhighlight lang="c++">
void SetGlobalVarInt(string& asName, int alVal);
void AddGlobalVarInt(string& asName, int alVal);
int GetGlobalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string& asName, float afVal);
void AddGlobalVarFloat(string& asName, float afVal);
float GetGlobalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string& asName, const string& asVal);
void AddGlobalVarString(string& asName, string& asVal);
string& GetGlobalVarString(string& asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string& asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS);
</syntaxhighlight>

Creates a particle system on an entity.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntityExt(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS,
float afR, float afG, float afB, float afA, bool abFadeAtDistance, float afFadeMinEnd, float afFadeMinStart,
float afFadeMaxStart, float afFadeMaxEnd);
</syntaxhighlight>

Creates a particle system on an entity, extended method with more options.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''abFadeAtDistance ''- determines whether a particle system fades from a certain distance on
#''afFadeMinEnd ''- minimum distance at which the particle system stops fading
#''afFadeMinStart ''- minimum distance at which the particle system starts fading
#''afFadeMaxStart ''- maximum distance at which the particle system starts fading
#''afFadeMaxEnd ''- maximum distance at which the particle system stops fading
<syntaxhighlight lang="c++">
void DestroyParticleSystem(string& asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string& asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load. Extension: .snt
<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string& asSoundName, string& asSoundFile, string& asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound on an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use + extension .snt
#''asEntity ''- the entity to create the sound at, can be "Player"
#''afFadeTime ''- time in seconds the sound needs to fade. Avoids enemies hearing the sound if afFadeTime is at least 0.1f
#''abSaveSound ''- if ''true'', a looping sound will "remember" its playback state (currently playing/stopped), and that state will be restored the next time the level is entered. If ''true'', the sound is never attached to the entity! Note that saving should only be used on ''looping sounds''!
<syntaxhighlight lang="c++">
void FadeInSound(string& asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- ?
<syntaxhighlight lang="c++">
void StopSound(string& asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediatly stop the sound
<syntaxhighlight lang="c++">
void PlayMusic(string& asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music to play + extension .ogg
#''abLoop ''- determines whether a music track should loop
#''afVolume ''- volume of the music
#''afFadeTime ''- time in seconds until music reaches full volume
#''alPrio ''- priority of the music. Note that only the music with the highest priority can be heard! 0 - lowest, 1 - higher, etc.
#''abResume'' - if ''true'', playback will be continued from where the track stopped after the call to StopMusic(); if ''false'', the track will be restarted.
<syntaxhighlight lang="c++">
void StopMusic(float afFadeTime, int alPrio);
</syntaxhighlight>

Stops music.

#''afFadeTime ''- time in seconds until music stops
#''alPrio ''- the priority of the music that should stop
<syntaxhighlight lang="c++">
void FadeGlobalSoundVolume(float afDestVolume, float afTime);
</syntaxhighlight>

Influences the global sound volume, that means everything you can hear '''from the world'''. This does not affect music of GUI sounds.

#''afDestVolume ''- desired volume
#''afTime ''- time in seconds until volume reaches desired volume
<syntaxhighlight lang="c++">
void FadeGlobalSoundSpeed(float afDestSpeed, float afTime);
</syntaxhighlight>

Influences the global sound speed.

#''afDestSpeed ''- desired speed
#''afTime ''- time in seconds until volume reaches desired speed

===Lights===

<syntaxhighlight lang="c++">
void SetLightVisible(string& asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string& asLightName, float afR, float afG, float afB, float afA, float afRadius, float afTime);
</syntaxhighlight>

Changes the properties of a light.

#''asLightName ''- internal name
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''afRadius ''- radius of the light. -1 means keeping the radius
#''afTime ''- time in seconds until change is done
<syntaxhighlight lang="c++">
void SetLightFlickerActive(string& asLightName, bool abActive);
</syntaxhighlight>

Activates flickering on a light.

#''asLightName'' - The internal light name
#''abActive'' - true = active, false = inactive

==Game scripts==

===General===

<syntaxhighlight lang="c++">
void StartCredits(string& asMusic, bool abLoopMusic, string& asTextCat, string& asTextEntry, int alEndNum);
</syntaxhighlight>

Starts the end credits screen.

#''asMusic ''- the music to play (including .ogg)
#''abLoopMusic ''- determines whether the music should loop
#''asTextCat ''- the category to be used in the .lang file
#''asTextEntry ''- the entry in the .lang file
#''alEndNum ''- Amnesia has 3 different endings and displays a code at the bottom. Determines which code is displayed. 0-2 will display codes, any other integer will not.
<syntaxhighlight lang="c++">
void StartDemoEnd();
</syntaxhighlight>

Starts the end images that are used in the demo, images are named "demo_end01.jpg", increase the number for each image you want to use. (NEEDS VERIFICATION)

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Save the game to the auto save.

<syntaxhighlight lang="c++">
void CheckPoint (string& asName, string& asStartPos, string& asCallback, string& asDeathHintCat, string& asDeathHintEntry);
</syntaxhighlight>

Sets a checkpoint at which the player will respawn in case he dies. Callback syntax: <code>void MyFunc(string &in asName, int alCount)</code> Count is 0 on the first checkpoint load!

#''asName ''- the internal name
#''asStartPos ''- the name of the StartPos in the editor
#''asCallback ''- the function to call when the player dies/respawns
#''asDeathHintCat ''- the category of the death hint message to be used in the .lang file
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string& asMapName, string& asStartPos, string& asStartSound, string& asEndSound);
</syntaxhighlight>

Immediatly loads another map.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos on the next map
#''asStartSound ''- the sound that is played when the change starts
#''asEndSound ''- the sound that is played when the new map is loaded
<syntaxhighlight lang="c++">
void ClearSavedMaps();
</syntaxhighlight>

Clears the "history" of the save, useful to do when you know the player will not be able to go back anymore. Makes the next save much smaller in size.

<syntaxhighlight lang="c++">
void CreateDataCache();
void DestroyDataCache();
</syntaxhighlight>

This caches all current textures and models and they are not released until destroy is called. If there is already cached data it is destroyed.
Create caches to enable faster loading when going back to a map. Destroy the cache if you know the player won't go back to that map.

<syntaxhighlight lang="c++">
void SetMapDisplayNameEntry(string& asNameEntry);
</syntaxhighlight>

Sets the map name shown in save file names. If none is set NULL is assumed.

#''asNameEntry ''- the entry to display, category must be "Levels"!
<syntaxhighlight lang="c++">
void SetSkyBoxActive(bool abActive);
</syntaxhighlight>

Enables/Disables the skybox.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetSkyBoxTexture(string& asTexture);
</syntaxhighlight>

Sets the texture of the skybox.

#''asTexture'' - The texture file to set. Extension: .dds
<syntaxhighlight lang="c++">
void SetSkyBoxColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the solid color of the skybox rather than a texture.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogActive(bool abActive);
</syntaxhighlight>

Enables/Disables the global fog.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetFogColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the color to use for the global fog.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogProperties(float afStart, float afEnd, float afFalloffExp, bool abCulling);
</syntaxhighlight>

Sets the properties for the global fog.

#''afStart ''- how many meters from the camera should the fog begin
#''afEnd ''- how many meters from the camera should the fog reach full thickness
#''afFalloffExp ''- the amount by which the thinkness increases
#''abCulling ''- whether occlusion culling is active for the fog; this prevents objects behind the fog from being loaded
<syntaxhighlight lang="c++">
void SetupLoadScreen(string&asTextCat, string&asTextEntry, int alRandomNum, string&asImageFile);
</syntaxhighlight>

Determines which loading screen will be shown when changing maps.

#''asTextCat ''- the category of the loading text in the .lang file to be shown on the loading screen
#''asTextEntry ''- the entry in the .lang file
#''alRandomNum ''- if greater 1, then it will randomize between 1 and alRandom for each LoadScreen giving entry the suffix XX (eg 01). If < =1 then no suffix is added
#''asImageFile ''- the image to be shown (optional)

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string& asName, float afTime, string& asFunction);
</syntaxhighlight>

Creates a timer which calls a function when it expires. Callback syntax: <code>void MyFunc(string &in asTimer)</code>

#''asName ''- the name of the timer
#''afTime ''- time in seconds
#''asFunction ''- the function to call
<syntaxhighlight lang="c++">
void RemoveTimer(string& asName);
</syntaxhighlight>

Removes a timer, no matter how much time is left.

#''asName'' - the internal name of the timer.
<syntaxhighlight lang="c++">
float GetTimerTimeLeft(string& asName);
</syntaxhighlight>

Returns the time left on a timer.

#''asName'' - the internal name of the timer.

===Screen Effects===

<syntaxhighlight lang="c++">
void FadeOut(float afTime);
</syntaxhighlight>

Fades the screen to black.

''afTime ''- time in seconds until the screen is completly black

<syntaxhighlight lang="c++">
void FadeIn(float afTime);
</syntaxhighlight>

Fades the screen back to normal.

''afTime ''- time in seconds until the screen back to normal

<syntaxhighlight lang="c++">
void FadeImageTrailTo(float afAmount, float afSpeed);
</syntaxhighlight>

Applies the image trail effect to the screen.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeSepiaColorTo(float afAmount, float afSpeed);
</syntaxhighlight>

Makes the screen go dark red.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeRadialBlurTo(float afSize, float afSpeed);
</syntaxhighlight>

Applies radial blur effects to the screen.

''afSize ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void SetRadialBlurStartDist(float afStartDist);
</syntaxhighlight>

Determines at which distance the radial blur effects appear.

''afStartDist ''- the distance at which the effect starts

<syntaxhighlight lang="c++">
void StartEffectFlash(float afFadeIn, float afWhite, float afFadeOut);
</syntaxhighlight>

Fades the screen to white.

''afFadeIn ''- time in seconds until screen is white ''afWhite ''- determines to which percentage the screen fades to white (1.0 = completly white) ''afFadeOut ''- time in seconds until screen is back to normal again

<syntaxhighlight lang="c++">
void StartEffectEmotionFlash(string& asTextCat, string& asTextEntry, string& asSound);
</syntaxhighlight>

Fades the screen to white and shows a text message.

''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''asSound ''- the sound to play while fading

<syntaxhighlight lang="c++">
void AddEffectVoice(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry,
bool abUsePosition, string& asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an effect to be played. It is okay to call this many times in order to play many voices in a row. The EffectVoiceOverCallback is not called until ALL voices have finished.

''asVoiceFile ''- the voice to play ''asEffectFile ''- the effect to play ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''abUsePosition ''- plays using 3D from the entity, or without 3D ''asPosEntity ''- the entity at which the effect appears ''afMinDistance ''- minimum distance to see the effect ''afMaxDistance ''- maximum distance to see the effect

<syntaxhighlight lang="c++">
void StopAllEffectVoices(float afFadeOutTime);
</syntaxhighlight>

Stops all voices and calls the EffectVoiceOverCallback.

<syntaxhighlight lang="c++">
bool GetEffectVoiceActive();
</syntaxhighlight>

Checks whether EffectVoices are still active.

<syntaxhighlight lang="c++">
void SetEffectVoiceOverCallback(string& asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<syntaxhighlight lang="c++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string& asSPSFile);
void StopPlayerSpawnPS();
</syntaxhighlight>

Continuously spawn regular particle systems (''.ps'') around the player. Particles created by this script carry over from map to map. ''asSPSFile'' - the ''.sps'' file to use. Exemplary ''.sps'' files are located in the ''/misc'' folder in the main game directory. Custom ''.sps'' files can be created by hand in a text editor (see existing ones and mimic how those are written). Since ''StopPlayerSpawnPS()'' doesn't seem to work, to stop an SPS you must create an ''.sps'' file with an empty particle field field and override the old SPS by calling ''StartPlayerSpawnPS'' again.

<syntaxhighlight lang="c++">
void PlayGuiSound(string& asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

''asSoundFile ''- the sound to play (extension is .snt) ''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void StartScreenShake(float afAmount, float afTime, float afFadeInTime, float afFadeOutTime);
</syntaxhighlight>

Shakes the screen.

''afAmount ''- intensity of the shake ''afTime ''- duration of the shake ''afFadeInTime ''- time in seconds until full intensity is reached ''afFadeOutTime ''- time until screen is back to normal

<syntaxhighlight lang="c++">
void SetInDarknessEffectsActive(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the sanity drain and night vision effects while in the darkness.

''bool abX'' - Enable/disable effects.

<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

{{ReqVer|1.5}}

Displays an image file directly onto the screen.

''asImageName'' - The image file to render (.jpg, .png, .tga, .dds)

''afX'' - The X position of the image

''afY'' - The Y position of the image

''afScale'' - The scale of the image (default 1.0f)

''abUseRelativeCoordinates'' - Whether or not to use relative coordinates for positioning. Use false for absolute.

''afDuration'' - The duration that the image is displayed for.

''afFadeIn'' - The time, in seconds, to fade in the image.

''afFadeOut'' - The time, in seconds, to fade out the image.

===Insanity===

<syntaxhighlight lang="c++">
void SetInsanitySetEnabled(string& asSet, bool abX);
</syntaxhighlight>

Determines which InsanitySets are enabled.

''asSet ''- the set ''abX ''- enabled or not

<syntaxhighlight lang="c++">
void StartInsanityEvent(string &in asEventName);
</syntaxhighlight>

{{ReqVer|1.3}}

Starts a specified insanity event.

''asEventName ''- Insanity event to play.

<syntaxhighlight lang="c++">
void StartRandomInsanityEvent();
</syntaxhighlight>

Starts a random insanity event from the available sets.

<syntaxhighlight lang="c++">
void StopCurrentInsanityEvent();
</syntaxhighlight>

{{ReqVer|1.3}}

Stops the currently playing insanity event.

<syntaxhighlight lang="c++">
void InsanityEventIsActive();
</syntaxhighlight>

Checks whether an insanity event is currently in effect… Or so it was supposed to be, but as it doesn't return a value, we can never know [http://wiki.frictionalgames.com/lib/images/smileys/icon_smile.gif?nolink&15x15]

===Player===

Note that the player's maximum health and sanity is 100.

<syntaxhighlight lang="c++">
void SetPlayerActive(bool abActive);
</syntaxhighlight>

Enabled/Disable player controlled movement.

<syntaxhighlight lang="c++">
void ChangePlayerStateToNormal();
</syntaxhighlight>

Sets certain effects back to normal. It can for example make the player drop an item.

<syntaxhighlight lang="c++">
void SetPlayerCrouching(bool abCrouch);
</syntaxhighlight>

Forces the player to crouch.

<syntaxhighlight lang="c++">
void AddPlayerBodyForce(float afX, float afY, float afZ, bool abUseLocalCoords);
</syntaxhighlight>

Pushes the player into a certain direction. Note that you need values above ~2000 to see any effects.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''abUseLocalCoords ''- If true, axes are based on where the player is facing, not the world.

<syntaxhighlight lang="c++">
void ShowPlayerCrossHairIcons(bool abX);
</syntaxhighlight>

Enables/Disables the icons when a player has something in focus.

<syntaxhighlight lang="c++">
void SetPlayerSanity(float afSanity);
void AddPlayerSanity(float afSanity);
float GetPlayerSanity();
</syntaxhighlight>

Modifies/returns the sanity of the player.

<syntaxhighlight lang="c++">
void SetPlayerHealth(float afHealth);
void AddPlayerHealth(float afHealth);
float GetPlayerHealth();
</syntaxhighlight>

Modifies/returns the health of the player.

<syntaxhighlight lang="c++">
void SetPlayerLampOil(float afOil);
void AddPlayerLampOil(float afOil);
float GetPlayerLampOil();
</syntaxhighlight>

Modifies/returns the lamp oil of the player.

<syntaxhighlight lang="c++">
float GetPlayerSpeed();
float GetPlayerYSpeed();
</syntaxhighlight>

Returns the current speed of the player.

<syntaxhighlight lang="c++">
void SetSanityDrainDisabled(bool abX);
</syntaxhighlight>

Enables/Disables sanity drain from darkness, monsters, etc.

<syntaxhighlight lang="c++">
void GiveSanityBoost();
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a fixed amount.

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

''afAmount ''- amount of sanity damage done ''abUseEffect ''- determines whether an effect is played when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string& asType, bool abSpinHead, bool abLethal);
</syntaxhighlight>

Reduces the health of the player.

''afAmount ''- amount of damage done to health ''asType ''- plays a certain effect on the screen when the damage is dealt (BloodSplat, Claws or Slash) ''abSpinHead ''- changes the camera view when damage is dealt ''abLethal ''- set to true if player can die from given damage

<syntaxhighlight lang="c++">
void FadePlayerFOVMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the field of view of the player. A shorter FOV will create a zoom effect.

''afX ''- multiplier of default FOV (1 is default) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerAspectMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the aspect ratio of the player. Basically stretches or narrows the screen horizontally.

''afX ''- multiplier of default aspect (default is 1) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerRollTo(float afX, float afSpeedMul, float afMaxSpeed);
</syntaxhighlight>

Rotates the position of the camera on the player's body.

''afX ''- angle of rotation of head, positive being counter-clockwise ''afSpeedMul ''- speed (possibly acceleration) multiplier of the rotation (default 1, which is really slow) ''afMaxSpeed ''- maximum speed of rotation

<syntaxhighlight lang="c++">
void MovePlayerHeadPos(float afX, float afY, float afZ, float afSpeed, float afSlowDownDist);
</syntaxhighlight>

Changes the position of the camera on the player's body.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''afSpeed ''- speed at which the change happens ''afSlowDownDist ''- distance at which to start slowing down (prevents the head from abruptly stopping)

<syntaxhighlight lang="c++">
void StartPlayerLookAt(string& asEntityName, float afSpeedMul, float afMaxSpeed, string& asAtTargetCallback);
void StopPlayerLookAt();
</syntaxhighlight>

Forces the player to look at a certain entity until StopPlayerLookAt is used.

''asEntityName ''- the entity to look at ''afSpeedMul ''- how fast should the player look at the entity ''afMaxSpeed ''- maximum speed allowed ''asAtTargetCallback ''- function to call when player looks at target

<syntaxhighlight lang="c++">
void SetPlayerMoveSpeedMul(float afMul);
void SetPlayerRunSpeedMul(float afMul);
void SetPlayerLookSpeedMul(float afMul);
</syntaxhighlight>

Changes the player's move/run/look speed. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpForceMul(float afMul);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the player's jump multiplier. Higher values = higher jumps. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpDisabled(bool abX);
void SetPlayerCrouchDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to jump/crouch.

<syntaxhighlight lang="c++">
void TeleportPlayer(string& asStartPosName);
</syntaxhighlight>

Instantly teleports the player to the target StartPos.

<syntaxhighlight lang="c++">
void SetLanternActive(bool abX, bool abUseEffects);
</syntaxhighlight>

Makes the player use his lantern.

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player currently uses his lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use his lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string& asCallback);
</syntaxhighlight>

Sets the function to call when the player uses his lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Displays a message on the screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- determines how long the message is displayed. If time is < =0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void SetDeathHint(string& asTextCategory, string& asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="c++">
void DisableDeathStartSound();
</syntaxhighlight>

Disables the death sound when the player dies. This must be called directly before player is killed! The variable as soon as player dies too.

<syntaxhighlight lang="">
void MovePlayerForward(float afAmount)
</syntaxhighlight>

"REQUIRES THE 1.2 PATCH: JUSTINE" Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<syntaxhighlight lang="c++">
void SetPlayerFallDamageDisabled(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the player's ability to take fall damage.

<syntaxhighlight lang="c++">
void SetPlayerPos(float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the player's position within the level.

''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c++">
float GetPlayerPosX();
float GetPlayerPosY();
float GetPlayerPosZ();
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the player's position within the level on the specified axis.

===Journal===

<syntaxhighlight lang="c++">
void AddNote(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a note to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _Name and _Text and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void AddDiary(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a diary to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _NameX and _TextY whereas X and Y are numbers of the parts (_Name1: first diary, _Text1: first page) and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void ReturnOpenJournal(bool abOpenJournal);
</syntaxhighlight>

Only called in the pickup diary callback! If true the journal displays the entry else not.

===Quests===

<syntaxhighlight lang="c++">
void AddQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos.

''asName ''- the internal name to be used ''asNameAndTextEntry ''- entry in the .lang file. Must start with "Quest_<texthere>_Text”, and be in category “Journal”!

<syntaxhighlight lang="c++">
void CompleteQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Completes a quest.

''asName ''- the internal name of the quest ''asNameAndTextEntry ''- entry in the .lang file. Must start with " Quest_<texthere>_Text ”, and be in category “Journal”!

<syntaxhighlight lang="c++">
bool QuestIsCompleted(string& asName);
bool QuestIsAdded(string& asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map.

''alNumberOfQuests ''- Amount of Quests

<syntaxhighlight lang="c++">
void GiveHint(string& asName, string& asMessageCat, string& asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

''asName ''- the internal name ''asMessageCat ''- the category in the .lang file ''asMessageEntry ''- the entry in the .lang file ''afTimeShown ''- time in seconds until the message disappears. If time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void BlockHint(string& asName);
void UnBlockHint(string& asName);
void RemoveHint(string& asName);
</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels.

"Removing" a hint actually removes it from the list of already given hints, thus allowing it to show up again.

''asName ''- the internal name. Basic game hints use the same name as their respective lang entries, with the exception of "numbered" hints. For example, <code>EntityGrab</code> blocks the <code>EntityGrab01</code> and <code>EntityGrab02</code> entries.

===Inventory===

<syntaxhighlight lang="c++">
void ExitInventory();
</syntaxhighlight>

Exits the inventory by force.

<syntaxhighlight lang="c++">
void SetInventoryDisabled(bool abX);
</syntaxhighlight>

Disables the player's ability to open his inventory.

<syntaxhighlight lang="c++">
void SetInventoryMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Adds a message at the bottom of the inventory screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- time in seconds until the message disappears. If life time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void GiveItem(string& asName, string& asType, string& asSubTypeName, string& asImageName, float afAmount);
</syntaxhighlight>

Adds an item to the inventory of the player. Note that the item does not have to exist as entity in the world to be able to do this.

''asName ''- internal name ''asType ''- item type to give, Available types are: 

*Puzzle
*Lantern
*Health
*Sanity
*LampOil
*Tinderbox

''asSubTypeName ''- item name for .lang file ''asImageName ''- the image which will appear in inventory. For example: <code>void GiveItem("chemical_container_full_1", "Puzzle", "chemical_container_full", "chemical_container_full.tga", 1);</code> will use the image from <code>graphics/item/chemical_container_full.tga</code>

''afAmount ''- amount the item gives, - For example: Oil potions will fill the oil meter by this amount, Health potions will heal by this amount, etc.

<syntaxhighlight lang="c++">
void RemoveItem(string& asName);
</syntaxhighlight>

Removes an item from the player's inventory.

<syntaxhighlight lang="c++">
bool HasItem(string& asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

<syntaxhighlight lang="c++">
void GiveItemFromFile(string& asName, string& asFileName);
</syntaxhighlight>

Adds a single item to the player's inventory. This is meant to be used for debug mostly as it creates the actual item and then destroys it.

''asName ''- internal name ''asFileName ''- item to give + extension (.ent)

<syntaxhighlight lang="c++">
void AddCombineCallback(string& asName, string& asItemA, string& asItemB, string& asFunction, bool abAutoRemove);
</syntaxhighlight>

Allows the player to combine items in his inventory. Callback syntax: <code>void MyFunc(string &in asItemA, string &in asItemB)</code>

''asName ''- internal name for the callback ''asItemA ''- internal name of first item ''asItemB ''- internal name of second item ''asFunction ''- the function to call ''abAutoRemove ''- determines whether the callback should be removed when the items are combined

<syntaxhighlight lang="c++">
void RemoveCombineCallback(string& asName);
</syntaxhighlight>

Removes a combine callback. ''asName'' - the internal name of the callback to be removed (as specified in AddCombineCallback)

<syntaxhighlight lang="c++">
void AddUseItemCallback(string& asName, string& asItem, string& asEntity, string& asFunction, bool abAutoDestroy);
</syntaxhighlight>

Allows the player to use items on the world. Callback syntax: <code>void MyFunc(string &in asItem, string &in asEntity)</code>

''asName ''- internal name ''asItem ''- internal name of the item ''asEntity ''- entity to be able to use the item on ''asFunction ''- function to call ''abAutoDestroy ''- determines whether the item is destroyed when used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string& asName);
</syntaxhighlight>

Removes an item callback.

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string& asName, bool abActive);
</syntaxhighlight>

Activates/deactivates an entity.

<syntaxhighlight lang="c">
void SetEntityVisible(string &in asName, bool abVisible);
</syntaxhighlight>

{{ReqVer|1.3}}

Activates/deactivates an entity's visual mesh. The collision body remains.

''asName'' - Name of the entity. ''abActive'' - Activate/deactivate mesh.

<syntaxhighlight lang="c">
bool GetEntityExists(string& asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string& asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

''asName ''- internal name ''asCrossHair ''- desired crosshair, can be: Default (uses default), Grab, Push, Ignite, Pick, LevelDoor, Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string& asEntityName, string& asEntityFile, string& asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes(using for example ShowEnemyPlayerPosition).

''asEntityName ''- internal name ''asEntityFile ''- entity to be used extension .ent ''asAreaName ''- the area to create the entity at ''abFullGameSave ''- determines whether an entity "remembers" its state

<syntaxhighlight lang="c">
void ReplaceEntity(string &in asName, string &in asBodyName, string &in asNewEntityName, string &in asNewEntityFile, bool abFullGameSave);
</syntaxhighlight>

{{ReqVer|1.3}}

Removes an entity and places a new one in its place.

''asName'' - Name of the entity to replace. ''asBodyName'' - Name of the body of the entity to place the new entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''asNewEntityName'' - Name of the new entity. ''asNewEntityFile'' - Name of the new entity file. Extension .ent. ''abFullGameSave'' - Whether ALL properties of this entity should be saved throughout levels.

<syntaxhighlight lang="c++">
void PlaceEntityAtEntity(string &in asName, string &in asTargetEntity, string &in asTargetBodyName, bool abUseRotation);
</syntaxhighlight>

{{ReqVer|1.3}}

Places an entity at the position of another entity. Does not work for enemies, use TeleportEnemyToEntity instead.

''asName'' - Name of the entity to place. ''asTargetEntity'' - Name of the other entity to place the first entity at. ''asTargetBodyName'' - Name of the body of the entity to place the first entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''abUseRotation'' - Whether the entity should be rotated like the target entity.

<syntaxhighlight lang="c">
void SetEntityPos(string &in asName, float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Moves an entity to a position in the level.

''asName'' - Name of the entity to move. ''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c">
float GetEntityPosX(string &in asName);
float GetEntityPosY(string &in asName);
float GetEntityPosZ(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns an entity's position in the level on the specified axis.

''asName'' - Name of the entity.

<syntaxhighlight lang="c">
void SetEntityPlayerLookAtCallback(string& asName, string& asCallback, bool abRemoveWhenLookedAt);
</syntaxhighlight>

Calls a function when the player looks at a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code> alState: 1 = looking, -1 = not looking

''asName ''- internal name ''asCallback ''- function to call ''abRemoveWhenLookedAt ''- determines whether the callback should be removed when the player looked at the entity

<syntaxhighlight lang="c">
void SetEntityPlayerInteractCallback(string& asName, string& asCallback, bool abRemoveOnInteraction);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity)</code>

''asName ''- internal name ''asCallback ''- function to call ''abRemoveOnInteraction ''- determines whether the callback should be removed when the player interacts with the entity

<syntaxhighlight lang="c">
void SetEntityCallbackFunc(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in type)</code> Type depends on entity type and includes: "OnPickup", "Break", "OnIgnite", etc

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string& asName, string& asCallback);
</syntaxhighlight>

A callback called when ever the connection state changes (button being switched on, lever switched, etc). Callback syntax: <code>void Func(string &in asEntity, int alState)</code> alState: -1 = off, 0 = between, 1 = on

<syntaxhighlight lang="c">
void SetEntityInteractionDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string& asName);
</syntaxhighlight>

Breaks a joint. Do not use this on joints in SwingDoors, Levers, Wheels, etc. where the joint is part of an interaction. That will make the game crash.

<syntaxhighlight lang="c">
void AddEntityCollideCallback(string& asParentName, string& asChildName, string& asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entites collide. Callback syntax: <code>void MyFunc(string &in asParent, string &in asChild, int alState)</code> alState: 1 = enter, -1 = leave

''asParentName ''- internal name of main object ''asChildName ''- internal name of object that collides with main object (asterix (<nowiki>*</nowiki>) NOT supported!) ''asFunction ''- function to call ''abDeleteOnCollide ''- determines whether the callback after it was called ''alStates ''- 1 = only enter, -1 = only leave, 0 = both

<syntaxhighlight lang="c">
void RemoveEntityCollideCallback(string& asParentName, string& asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string& asEntityA, string& asEntityB);
</syntaxhighlight>

Checks whether two entites collide. This function does NOT support asterix (<nowiki>*</nowiki>) or "Player"!

<syntaxhighlight lang="c">
void SetBodyMass(string &in asName, float afMass);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to set.

<syntaxhighlight lang="c">
float GetBodyMass(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to get.

====Props====

<syntaxhighlight lang="c">
void SetPropEffectActive(string& asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Can be used on coal to give it the black color it should have.

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string& asName, bool abActive, float afFadeTime);
</syntaxhighlight>

Activates/deactivates a prop.

''asName ''- internal name ''abActive ''- nothing to add ''afFadeTime ''- time in seconds until prop fully fades

<syntaxhighlight lang="c">
void SetPropStaticPhysics(string& asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string& asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string& asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string& asOffsetArea);
</syntaxhighlight>

Rotates the prop up to a set speed.

''asName ''- internal name ''afAcc ''- acceleration ''afGoalSpeed ''- desired speed ''afAxisX ''- rotation around X axis ''afAxisY ''- rotation around Y axis ''afAxisZ ''- rotation around Z axis ''abResetSpeed ''- determines whether the speed is resetted after goal speed is reached ''asOffsetArea ''- the area to rotate around, if empty, then the center of the body is used Note: The entity you want to rotate MUST be a "StaticObject" entity!

<syntaxhighlight lang="cpp">
void StopPropMovement(string& asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

a''sPropName''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

{{bug|''afRotZ '' is used for both the ZX rotation and the Z position of the attached prop. Unwanted rotation can be avoided by using: ''AddAttachedPropToProp(asPropName, asAttachName, asAttachFile, afPosX, afPosY, '''0''', afPosZ, '''90.0f''', afPosZ)''}}

{{bug|Attaching a breakable prop to a physically active prop, and then breaking the attached prop, will cause the game to crash, should the parent object be moved or reset.}}

<syntaxhighlight lang="cpp">
void AttachPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Attaches a prop to another prop. Fixed version of AddAttachedPropToProp.

''asPropName ''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

<syntaxhighlight lang="cpp">
void RemoveAttachedPropFromProp(string& asPropName, string& asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string& asName, float afHealth);
void AddPropHealth(string& asName, float afHealth);
float GetPropHealth(string& asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string& asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string& asProp, string& asAnimation, float afFadeTime, bool abLoop, string& asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function. Callback syntax: <code>void MyFunc(string &in asProp)</code>

''asProp ''- internal name of the prop ''asAnimation ''- animation to play ''afFadeTime ''- ? ''abLoop ''- determines whether the animation loops ''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddPropImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
</syntaxhighlight>

These functions push objects. Note that rather high values are needed when applying ''forces'' (on the order of ~100 (weak) to ~10000 (strong)), but not impulses (values less than 10 can be appropriate). Forces are external influences, and will have different effect depending on the mass of the object they are being applied to; impulses disregard mass, and can cause objects to break, as if hit. A "Body" is a physics-related helper object, to which a force or an impulse can be applied. Entities can consist of several bodies, interconnected in various ways (you can create/examine bodies in the model editor).

''asName ''- the object to push; for bodies, use this format: "''entityName''_''bodyName''" ''afX ''- magnitude along the X-axis ''afY ''- magnitude along the Y-axis ''afZ ''- magnitude along the Z-axis ''asCoordSystem ''- determines which coordinate system is used, usually "world" All of these functions are ''additive'' - when called consecutively, for each call, the vectors defined by (afX, afY, afZ) will be added together, and a resultant force/impulse will be calculated ''before'' any physics simulation is applied to the target object.

====Connections====

<syntaxhighlight lang="cpp">
void InteractConnectPropWithRope(string& asName, string& asPropName, string& asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (ie. turn wheel to move rope).

''asName ''- connection name ''asPropName ''- name of prop ''asRopeName ''- name of rope ''abInteractOnly ''- ? ''afSpeedMul ''- speed multiplier of how quickly the rope moves ''afToMinSpeed ''- the slowest the rope will move when moving the prop ''afToMaxSpeed ''- the fastest the rope will move when moving the prop ''abInvert ''- whether to invert the direction the rope moves ''alStatesUsed ''- which states of the prop can interact with the rope?

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string& asName, string& asPropName, string& asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondance to prope "amount" and the moveobject open amount. It is best used for Wheel-door connections!

<syntaxhighlight lang="cpp">
void ConnectEntities(string& asName, string& asMainEntity, string& asConnectEntity, bool abInvertStateSent, int alStatesUsed, string& asCallbackFunc);
</syntaxhighlight>

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> State is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string& asName, bool abLit, bool abEffects);
</syntaxhighlight>

(Un)lits a lamp.

''asName ''- Name of the lamp ''abLit ''- Set true if you want the lamp to be lit, set to false if you want the lamp to be unlit ''abEffects ''- If you want to have the lamp fade in/out when it gets (un)lit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string& asName, bool abLocked, bool abEffects);
void SetSwingDoorClosed(string& asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Locks/closes a swing door.

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string& asName);
bool GetSwingDoorClosed(string& asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string& asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string& asName);
</syntaxhighlight>

Returns an integer depending on how far the door is opened. -1 = angle is close to 0°, 1 = angle is 70% or higher of max, 0 = inbetween -1 and 1.

<syntaxhighlight lang="cpp">
void SetLevelDoorLocked(string& asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string& asName, string& asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string& asName, string& asTextCat, string& asTextEntry);
</syntaxhighlight>

Displays a message when interacting with a locked level door.

''asName ''- internal name ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="cpp">
void SetMoveObjectState(string& asName, float afState);
</syntaxhighlight>

Moves an object to a certain state.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween (and above, for example, the bridge_metal_vert) are valid too!

<syntaxhighlight lang="cpp">
void SetMoveObjectStateExt(string& asName, float afState, float afAcc, float afMaxSpeed, float afSlowdownDist, bool abResetSpeed);
</syntaxhighlight>

Moves an object to a certain state, extended method.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween are valid too! ''afAcc ''- acceleration ''afMaxSpeed ''- maximum speed ''afSlowdownDist ''- Distance to the target state before decceleration occurs. ''abResetSpeed ''- Set to True if the prop's speed should be reset before performing the movement, else the prop will accelerate from it's current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string& asName, int alState);
void SetWheelStuckState(string& asName, int alState, bool abEffects);
void SetLeverStuckState(string& asName, int alState, bool abEffects);
</syntaxhighlight>

Makes a prop<nowiki>\</nowiki>wheel<nowiki>\</nowiki>lever stuck in a certain state.

''asName ''- internal name ''alState ''- 0 = not stuck, 1 = at max, -1 = at min ''abEffects ''- use effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string& asName, float afAngle, bool abAutoMove);
</syntaxhighlight>

Moves a wheel to a certain angle.

''asName ''- internal name ''afAngle ''- angle ''abAutoMove ''- determines whether the wheel should move on its own

<syntaxhighlight lang="cpp">
void SetWheelInteractionDisablesStuck(string& asName, bool abX);
void SetLeverInteractionDisablesStuck(string& asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string& asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string& asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when state changes. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code>

<syntaxhighlight lang="cpp">
void SetButtonSwitchedOn(string& asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entites to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string& asAreaName, string& asProp);
void AttachBodyToStickyArea(string& asAreaName, string& asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string& asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====Enemies====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string& asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Activates the npc

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string& asName, bool abX);
</syntaxhighlight>

Sets an NPC's head to follow the player's movement's.

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string& asName, bool abX);
</syntaxhighlight>

Makes an enemy a hallucination. Hallucinations fade to smoke when they get near the player.

<syntaxhighlight lang="cpp">
void FadeEnemyToSmoke(string& asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string& asName);
</syntaxhighlight>

Makes the enemy run to the player, no matter where he is.

<syntaxhighlight lang="cpp">
void AlertEnemyOfPlayerPresence(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gives the specified enemy the player's current position and makes it search the area.

<syntaxhighlight lang="cpp">
void SetEnemyDisableTriggers(string& asName, bool abX);
</syntaxhighlight>

Enables or disables enemy triggers. If disabled, enemy will not react to player or attack.

<syntaxhighlight lang="cpp">
void AddEnemyPatrolNode(string& asName, string& asNodeName, float afWaitTime, string& asAnimation);
</syntaxhighlight>

Adds a patrol node to the enemy's path.

''asName ''- internal name of the enemy ''asNodeName ''- path node ''afWaitTime ''- time in seconds that the enemy waits at the path node before continuing ''asAnimation ''- the animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string& asEnemyName);
</syntaxhighlight>

Clears the current path of patrol nodes of the enemy.

<syntaxhighlight lang="cpp">
void SetEnemySanityDecreaseActive(string &in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether an enemy activates the player's sanity drain when stared at.

''asName ''- Internal name of the enemy ''abX ''- Enabled/disabled

<syntaxhighlight lang="cpp">
void TeleportEnemyToNode(string &in asEnemyName, string &in asNodeName, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific PathNode.

''asEnemyName ''- Internal name of the enemy ''asNodeName ''- Internal name of the node to teleport to ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="cpp">
void TeleportEnemyToEntity(string &in asEnemyName, string &in asTargetEntity, string &in asTargetBody, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific entity.

''asEnemyName ''- Internal name of the enemy ''asTargetEntity ''- Internal name of the entity to teleport to ''asTargetBody''- Internal name of the entity's body name to teleport to. If empty, the first body will be used (might be unstable, recommended to input a body anyway) ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="c">
void ChangeManPigPose(string&in asName, string&in asPoseType);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the pose a specified ManPig.

''asName ''- Internal name of the enemy ''asPoseType''- Name of the ManPig pose to use. Can be "Biped" or "Quadruped"

<syntaxhighlight lang="c">
void SetTeslaPigFadeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should fade the player's view in and out.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigSoundDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should play the proximity sounds.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigEasyEscapeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should be easier to escape from when hunted.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string&in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a TeslaPig to be visible for a short time.

''asName ''- Internal name of the enemy

<syntaxhighlight lang="c">
string& GetEnemyStateName(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the name of the state a specified enemy is current in. States can be Hunt, Search, Patrol, Wait, Alert, Investigate, Track and BreakDoor.

''asName ''- Internal name of the enemy

HPL2/Changelog

2023-09-24T21:03:04Z

Darkfire: Add tutorial link

HPL2/Tutorials/Coin chests

2023-09-24T21:00:55Z

Darkfire: clarified what window

Amnesia has an unused coins mechanic that is actually functional. The player can collect coins and then open special chests by spending these coins. These chests show a special GUI window for this mechanic.

{{warning | The coin mechanic has a bug in the older versions of the game where the required amount of coins gets reset to zero after loading a game save. If you use this mechanic, it would be good to inform the players that they need the [[HPL2/1.5_Update | 1.5 update]].}}

The entities that add coins to the player's "purse" are 3 variants of pouches with thalers and can be either placed in a level through the editor (they can be found in the items folder under entities) or by specifying them as the item that appears when breaking vases, pots etc. The entity property for the latter is called "ContainedItem".

However, there is no coin chest entity in the game's files. To make use of this mechanic, you will need to create one:
# Start the Model Editor
# <code>File > Open</code>
# Navigate to and open <code>/entities/gameplay/chest_small/chest_small.ent</code>, for example. You can change other chests (e.g. the treasure chest) and even doors to work as a coin chest.
# Save as a new file in your mod folder, e.g. <code>/custom_stories/MyMod/entities/chest_small_coins.ent</code>
# Open <code>Settings > User defined variables</code>
# Change the Type to "Chest" at the top of the newly opened window
# You can also customise the speed at which the chest opens when the player spends money for it if you want
# Close the properties window and save the file

Now you can place the chest in your mod and set the number of coins needed to open the chest.

{{idea| An easy way of placing custom entities is to place the original version, select it and then just swap the entity file under the general tab of entity properties.}}

HPL2/Tutorials/Coin chests

2023-09-24T21:00:28Z

Darkfire: added a few details

Amnesia has an unused coins mechanic that is actually functional. The player can collect coins and then open special chests by spending these coins. These chests show a special GUI window for this mechanic.

{{warning | The coin mechanic has a bug in the older versions of the game where the required amount of coins gets reset to zero after loading a game save. If you use this mechanic, it would be good to inform the players that they need the [[HPL2/1.5_Update | 1.5 update]].}}

The entities that add coins to the player's "purse" are 3 variants of pouches with thalers and can be either placed in a level through the editor (they can be found in the items folder under entities) or by specifying them as the item that appears when breaking vases, pots etc. The entity property for the latter is called "ContainedItem".

However, there is no coin chest entity in the game's files. To make use of this mechanic, you will need to create one:
# Start the Model Editor
# <code>File > Open</code>
# Navigate to and open <code>/entities/gameplay/chest_small/chest_small.ent</code>, for example. You can change other chests (e.g. the treasure chest) and even doors to work as a coin chest.
# Save as a new file in your mod folder, e.g. <code>/custom_stories/MyMod/entities/chest_small_coins.ent</code>
# Open <code>Settings > User defined variables</code>
# Change the Type to "Chest" at the top of the newly opened window
# You can also customise the speed at which the chest opens when the player spends money for it if you want
# Close the window and save the file

Now you can place the chest in your mod and set the number of coins needed to open the chest.

{{idea| An easy way of placing custom entities is to place the original version, select it and then just swap the entity file under the general tab of entity properties.}}

HPL2/Tutorials

2023-09-24T20:56:23Z

Darkfire: /* Model Editor */ add the coin chest tutorial

=Text tutorials=

This page lists a large amount of tutorials, most of which are community-made. Feel free to check them out and see if they can teach you something. If you've made a tutorial and wish to add it to this page, you can do so by editing it to the right. Just try to keep to the same format as the rest of the page.

{{tip|If you can't find a tutorial for what you need, make sure to check the [[HPL2/Tools#Editors|Editor documentation]] and [[HPL2/TDD#Documentation|Engine documentation]]. An example of this would be the Particle Editor.}}

==Level Editor==

* [[:hpl2:tutorials:level_editor:tutorial_1|Tutorial 1]] - The minimum required to get a level that can load.
* [[:hpl2:tutorials:level_editor:tutorial_2|Tutorial 2]] - Placement of lights and advanced setup of lights.
* [[:hpl2:tutorials:level_editor:tutorial_3|Tutorial 3]] - How to make an outdoor environment. There's a [[Hpl2:Tutorials:level_editor:outdoors|newer version of i]]t available.
* [[:hpl2:tutorials:level_editor:tutorial_4|Tutorial 4]] - Explains how to make water.
* [[:hpl2:tutorials:level_editor:tutorial_5|Tutorial 5]] - Prop dimensions and detailing your map.
*[[Hpl2:Tutorials:level editor:tutorial 6|Tutorial 6]] - ???????
*[[HPL2/Tutorials/Skyboxes|Tutorial 7]] - Making skyboxes for HPL2
*[[HPL2/Tutorials/Level Design]] - Using all of the basic techniques to achieve good effects
* [[:hpl2:tutorials:level_editor:level_editor_101|Level Editor 101]] - All the basics and some more advanced techniques.

==Model Editor==

* [[:hpl2:tutorials:model_editor:tutorial_1|Basic tutorial]] - The minimum required to load a model as an entity with collision and game properties.
* [[:hpl2:tutorials:model_editor:tutorial_2|Creating Ragdoll Entities]] - How to create full physics-based entities.
* [[:hpl2:tutorials:model_editor:static_objects_jenniferorange|Making Items Static]] - How to change an items' properties to static.
* [[HPL2/Tutorials/Coin_chests | Coin chests]] - How to create chests that can be only opened with coins.

==Material Editor==

* [[:hpl2:tutorials:material_editor:tutorial_1|Tutorial 1]] - Basic materials and their properties.
* [[Hpl2:Tutorials:material editor:creating mirrors|Creating mirrors]] - make reflective surfaces using water materials

==Game files==
* [[:hpl2:tutorials:script:CustomSounds|How to create Custom Sounds]] - Teaches how to create custom sounds for your custom story.
* [[:hpl2:tutorials:script:howtomakenotes|How to Create Notes and Journal Entries]] - Explains how to make journal entries and place them in a map
* [[HPL2/Tutorials/Porting MFP Assets|Porting MFP Assets]] - explains how to copy assets from MFP to TDD and avoid issues
* [[HPL2/Tutorials/Convert HDRI to skyboxes|Convert HDRI to skyboxes]]

==Scripting tutorials==
General basics:

*[[HPL2/Tutorials/Scripts/Debugging|Make your set-up comfortable for scripting]]
* [[:hpl2:tutorials:script:entihscript_beginner|Newbie's Guide to Scripting]] - A tutorial for those new to scripting, focusing on syntax and a few helpful hints - ''By 'Entih''
* [[:hpl2:tutorials:script:tutorial_1|Tutorial 1]] - Using a tutorial level, with some objects to make basic scripts.
* [[:hpl2:tutorials:scripting:messages_jenniferorange|Activating/Using Message Pop-Ups]] - Explains how to activate a message to appear when walking into a script area.
* [[:hpl2:tutorials:scripting:triggering_monsters_on_entities|Triggering monsters on entities]] - Explains how to trigger an event after picking up an item.

Door-related script tutorials:

* [[:hpl2:tutorials:script:scripting_by_xtron_-_item_that_unlocks_a_door|Item That Unlocks a Door]] - How to make an item that unlocks a certain door.
* [[:hpl2:tutorials:script:buttons_that_open_a_door|Buttons that open door]]s - Explains how to make buttons that open doors.
* [[:hpl2:tutorials:script:events|Scary door events]] - Explains how to make scary door events.
* [[:hpl2:tutorials:scripting:crowbartutorialjenniferorange|Using A Crowbar On A Door]] - Explains how to script a crowbar to blow open a door.
* [[:hpl2:tutorials:script:adding_messages_to_locked_doors|Adding Messages To Locked Doors]] - Explains how to display a message when a player tries to open a locked door.

Useful coding practices:

* [[:hpl2:tutorials:script:forloop|The "For" loop]] - Explains how and when to use the "for" loop.
* [[:hpl2:tutorials:script:advancedtimers|Advanced Timers]] - Explains how to use multiple timers in one function.
* [[:hpl2:tutorials:script:localandglobalvariables|Local and Global Variables]] - Explains what they are and how to use them correctly.
* [[:hpl2:tutorials:script:sequences|Scripting Sequences]] - Explains how to build simple and easy to use cutscenes, or sequences for your mod.

Forces and impulses:

* [[:hpl2:tutorials:script:force|Impulse and forces]] - Explains how to use force and impulse.
* [[:hpl2:tutorials:script:pushdoorsopen|Push doors open using force]] - Explains how to use Force to open doors and entities.
* [[Hpl2:Tutorials:level_editor:dynamic_curtains|Dynamic curtains]] - Using force to simulate wind
* [[:hpl2:tutorials:script:disable_gravity_tutorial|"Disable" gravity and make objects float]] - Make entities seem to float using timer functions and forces

Other:

* [[:hpl2:tutorials:script:monsterpathnodes|Monster Path Nodes]] - Explains how to set up a monster's path and how to trigger it.
* [[:hpl2:tutorials:script:levers_and_secretshelfs|Levers and secret bookshelves]] - Explains how to make a lever that opens a bookshelf.
* [[:hpl2:tutorials:scripting:scaresbyjenniferorange|Scares]] - Explains in as much detail as possible the multiple scares you can use without having to bring out the monsters.
* [[:hpl2:tutorials:level_editor:combininghammerchipperjenniferorange|Combining The Hammer And Chipper]] - Explains how to combine your hammer and chipper in your inventory.
* [[:hpl2:tutorials:scripting:checkpoints_using_scriptarea_s|Checkpoints using Areas]] - Explains how to make a checkpoint using Areas.
* [[:hpl2:tutorials:script:tutorialsformainmenu|How to create your own Main Menu Backgrounds!]] - The usability of Amnesia's .cfg files and its Editors

==Modeling==

* [[:hpl2:tutorials:modeling:tutorialoutsource|Modeling tutorial]] - Initially written for outsourcers.

=Video tutorials=
Sublists:
*[https://www.youtube.com/playlist?list=PLIYfl4qBRihBjRpmQL-izQ4xdAtLblU36 Large playlist of video tutorials for beginners and intermediate developers] - ''By Mudbill''
*[[Hpl2:Tutorials:script:elventutorials|Elven's tutorials]]

==By Simpanra==
* [http://www.youtube.com/watch?v=CklTIT2W4g4 How To Make Level Door]
* [http://www.youtube.com/watch?v=ABI7NUqkXW0 How To Get a Key To Unlock a Door]
* [http://www.youtube.com/watch?v=v4WudNebX08 How To Make Water]
* [http://www.youtube.com/watch?v=ESISPLDbMWM How To Make a Custom Story Background]
* [http://www.youtube.com/watch?v=RmIKTH9YRqk How To Make a Functional and Interactable Ladder]
* [http://www.youtube.com/watch?v=riFwThqQ68k How To Name and Describe Keys]
* [http://www.youtube.com/watch?v=M5x_taEkP8s Simple Script Function]
==By Khyrpa==
* [http://www.youtube.com/watch?v=1R2F2eVmJ5k Building and Lighting in The Level Editor]
* [http://www.youtube.com/watch?v=d2ShkLEgGNk Lighting in Level Editor]
* [http://www.youtube.com/watch?v=u8EhP59tmjA Billboards]
* [http://www.youtube.com/watch?v=LKxzoAIK8jA Advanced Candle Light Connecting]
* [http://www.youtube.com/watch?v=xIDCoEZ581Q Wind Scare (Part 1)]
* [http://www.youtube.com/watch?v=Kj-NFkIGafI Wind Scare (Part 2)]
==By MulleDK19==
* [http://amnesia.treesoft.dk/tutorials/Tutorial1.wmv Make a key unlock a specific door]
* [http://amnesia.treesoft.dk/tutorials/Tutorial2.wmv How to create and use Areas or Triggers]
* [http://amnesia.treesoft.dk/tutorials/EditorTutorial1.wmv Using the Level Editor (Part 1)]
* [http://amnesia.treesoft.dk/tutorials/EditorTutorial2.wmv Using the Level Editor (Part 2)]
* [http://amnesia.treesoft.dk/tutorials/EditorTutorial3.wmv Using the Level Editor (Part 3)]
==By others==
* [http://www.youtube.com/watch?v=0grr7uipnk0 How To Create a Custom Story] - ''By TheVegaNVega''
* [http://www.youtube.com/watch?v=uGCTwQQSZ0A How To Make Journal Entries/Notes] - ''By RussMoney''
* [http://www.youtube.com/watch?v=WfgFEG4TSCE How To Make Journal Entries/Mementos] - ''By RussMoney''
* [http://www.youtube.com/watch?v=puIfVx0lslA How To Convert a Custom Story To a Full Conversion] - ''By RussMoney''
* [http://www.youtube.com/watch?v=9uKBYVEyw1s How to convert cube map images to DDS format in the GIMP] - ''By YourComputer''
* [http://www.youtube.com/playlist?list=PLD326789BC99530C8 From Noob to Pro: Amnesia Custom Story Creation Series] - ''By YourComputer''
* [http://www.youtube.com/watch?v=EnCAbgTY6d8 Adding Voice to your Diaries] - ''By triadtimes''
* [http://www.youtube.com/watch?v=vQEdIAZw5gM&feature=plcp&context=C4347014VDvjVQa1PpcFNKLAyG_d-p_QR49e20E_Wo08wpqmVkJz0= How to create a custom main menu background] - ''By CTCommunity''
* [http://youtu.be/Crx5Qd7AgJ0 Using Prop Force: How Do I Know Which Coordinate To Put My Value In?] - ''By JenniferOrange''

HPL2/Tutorials/Coin chests

2023-09-24T20:54:59Z

Darkfire: Created

Amnesia has an unused coins mechanic that is actually functional. The player can collect coins and then open special chests by spending these coins.

{{warning | The coin mechanic has a bug in the older versions of the game where the required amount of coins gets reset to zero after loading a game save. If you use this mechanic, it would be good to inform the players that they need the [[HPL2/1.5_Update | 1.5 update]].}}

The entities that add coins to the player's "purse" are 3 variants of pouches with thalers and can be either placed in a level through the editor (they can be found in the items folder under entities) or by specifying them as the item that appears when breaking vases, pots etc. The entity property for the latter is called "ContainedItem".

However, there is no coin chest entity in the game's files. To make use of this mechanic, you will need to create one:
# Start the Model Editor
# <code>File > Open</code>
# Navigate to and open <code>/entities/gameplay/chest_small/chest_small.ent</code>, for example. You can change other chests (e.g. the treasure chest) and even doors to work as a coin chest.
# Save as a new file in your mod folder, e.g. <code>/custom_stories/MyMod/entities/chest_small_coins.ent</code>
# Open <code>Settings > User defined variables</code>
# Change the Type to "Chest" at the top of the newly opened window
# Close the window and save the file

Now you can place the chest in your mod and set the number of coins needed to open the chest.

{{idea| An easy way of placing custom entities is to place the original version, select it and then just swap the entity file under the general tab of entity properties.}}

HPL2/Development Environment

2023-09-21T15:22:50Z

Darkfire: improve readability

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:

#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). If your mod is an FC, do this in its save folder.
#Open main_settings.cfg and change set the following options:
##<code>LoadDebugMenu="true"</code>
##<code>ShowPreMenu="false"</code> (this will skip you some waiting on each game launch)
##<code>SaveConfig="false"</code> will make sure that the in-game option changes don't overwrite changes to this file
##Optional: <code>ExitMenuDirectly="true"</code> if you wish to exit the game without visiting the main menu
##<code>ForceCacheLoadingAndSkipSaving="false"</code>, otherwise certain map changes might not show! You will sometimes need to delete the map's cache file even with this setting
#Open user_settings.cfg (in the "Dev" folder) and set the following:
##<code>AllowQuickSave="true"</code> ('''F4'''=save, '''F5'''=load)
##<code>ScriptDebugOn="true"</code>. This makes debugging easier (more on that below)
#In order to avoid running into "File index out of bounds" errors in the Level Editor, edit the file '''resources.cfg''' located in the root the directory of Amnesia and add the ''custom_stories'' directory to the end of the list. This will also make custom assets load in the editors.

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 into a map before making changes to its script.}}

By setting <code>ScriptDebugOn="true"</code> you have set the script function <code>ScriptDebugOn()</code> to return true. This is quite useful, as you can add something like this in your startup code:
<syntaxhighlight lang="cpp">if(ScriptDebugOn()) {
//Do your setup stuff
}</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.

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 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> (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).
##<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.

HPL2/Third party tools

2023-09-21T14:52:38Z

Darkfire: /* 2D programs */ add Krita

=Third Party Tools=

Information on some of the third-party tools that can be used to create models, graphics and art for the game and what specific things you will need to setup to make it all work.

==COLLADA==

All 3D models regardless of program used must be able to export to the [http://collada.org Collada] format.

Note: The 1.3 patch for Amnesia allows support for [http://en.wikipedia.org/wiki/FBX FBX] formats.

==3D Programs==

#[[Blender]] - Open-source 3D modeling program that comes with built-in support for [http://collada.org Collada].
#[[Autodesk_Maya|Autodesk Maya]] - Professional 3D modeling program with [https://collada.org/mediawiki/index.php/OpenCOLLADA OpenCOLLADA] plugin support.

==2D programs==

#[[GIMP]] - Open-source 2D '''G'''NU '''I'''mage '''M'''anipulation '''P'''rogram.
# [https://krita.org/ Krita] - a free and open source image editing program with focus on painting. It is more similar to Photoshop than GIMP.
#[[Adobe_Photoshop|Adobe Photoshop]] - Professional image editing software.
#[[Paint.NET|Paint.net]]

==Audio programs==

#[[Audacity]]

==Text/Script coding programs==

#[[Notepad%2B%2B|Notepad++]]: Advanced text editor, crucial for script writing.
#[[Geany|Geany]]: An alternative for Notepad++.

'<nowiki/>''Mac OS X alternatives'<nowiki/>''''':'''

#[[:hpl2:third_party_tools:text:textwrangler|TextWrangler]]: A good alternative to Notepad++ on Windows.
#[[TextMate|TextMate]]: A nice and smooth code editor with many customization options.

HPL2/Community Resources

2023-09-21T14:48:30Z

Darkfire: move the script preprocessor where it belongs

=Resources=

This section contains a set of community created resources for aiding in development.

Many additional tools, assets and other resources can be found in the [https://www.frictionalgames.com/forum/forum-42.html Development Resources section of the forum].

==Tools==

*[[HPL2/Improved Notepad++ Support|Improved Notepad++ HPS support]]
*[[HPL2/Lang Editor Tool|Language Editor Tool]]

==Script Modules==
{{warning|Except for fringe cases, the built-in functions are enough for HPL2. Using the following will most likely result in over-engineered and obfuscated code, so proceed with caution. They are kept for archival purposes.}}

*[[Hpl2:Resources:script modules:coordsys|Global coord system]]
*[[Hpl2:Resources:script_modules:math|Custom math functions]] (keep in mind some of these have been implemented as [[HPL2/Engine_Scripts#Mathematical_Operations|Script Functions]] in later patches)
*[[Hpl2:Resources:script modules:smallvars|Small variables (debugging API)]]
*[[Hpl2:Resources:script_modules:stringlist|String list]]
*[[Hpl2:Resources:script modules:stringparsing|Parsing strings into variables]]
*[[Hpl2:Resources:script modules:vector3d|3D Vectors]]
*[[HPL2/Script Pre-Processor|Script Preprocessor]]

HPL2/Getting started

2023-09-21T14:43:02Z

Darkfire: add tutorials and clean up the reading experience a bit

This page will guide you through the basic steps you want to make to get started modding HPL2. This guide will have you use '''Amnesia – The Dark Descent''' (TDD), not '''Amnesia – A Machine For Pigs''' (AMFP), as TDD is the one that is officially supported for modding.

==Prerequisites==
Before you get started, you should already have the following installed:

#A legal copy of '''Amnesia – The Dark Descent'''. All platforms should work, including Steam, GOG and retail DVDs, on Windows, Mac OS X (versions EARLIER than 10.15 Catalina), and most Linux distros.
#Your code editor of choice.
##[https://code.visualstudio.com/ VS Code] or its free/open version, [https://vscodium.com/ VS Codium], are recommended due to their convenient autocompletion and search features.
##If you're old-school, [https://notepad-plus-plus.org/ Notepad++] also works.

==Setting up your game==
[[File:Level Editor.png|alt=The initial view of the HPL2 level editor.|thumb|The view of the level editor]]
Before you dive in, you should set up a few things:

#[[HPL2/Tools#Installation Instructions|Install the development tools]] for your platform.
#Configure your game to use the [[HPL2/Development Environment|development environment]] (optional, but highly recommended).
#Bookmark the [[HPL2/Engine Scripts|Script Functions]] page. This page is a great reference for when you create your scripts.

You are now ready to start [[HPL2/TDD/Creating a Custom Story|'''setting up your first custom story''']]!

==Additional steps==
Here are a few other useful things you can do:

#Check out the [[HPL2/Glossary|HPL2 glossary]] for an explanations of the engine's modding jargon.
#Check out some [[HPL2/Tutorials | Tutorials]].
#Join the official [https://discord.com/invite/frictionalgames Discord server] and its modding channels to ask questions if you need help.

HPL2/Getting started

2023-09-21T14:38:00Z

Darkfire: Remove Atom (end of support was in 2022), added VSCodium

This page will guide you through the basic steps you want to make to get started modding HPL2. This guide will have you use '''Amnesia – The Dark Descent''' (TDD), not '''Amnesia – A Machine For Pigs''' (AMFP), as TDD is the one that is officially supported for modding.

==Prerequisites==
Before you get started, you should already have the following:

#A legal copy of '''Amnesia – The Dark Descent''' installed. All platforms should work, including Steam, GOG and retail DVDs, on Windows, Mac OS X (versions EARLIER than 10.15 Catalina), and most Linux distros.
#Your code editor of choice installed.
##[https://code.visualstudio.com/ VS Code] or its free/open version, [https://vscodium.com/ VS Codium], are recommended due to their convenient autocompletion and search features.
##If you're old-school, [https://notepad-plus-plus.org/ Notepad++] also works.

==Setting up your game==
[[File:Level Editor.png|alt=The initial view of the HPL2 level editor.|thumb|The view of the level editor]]
Before you dive in, you should set up a few things:

#[[HPL2/Tools#Installation Instructions|Install the development tools]] for your platform.
#Configure your game to use the [[HPL2/Development Environment|development environment]] (optional, but highly recommended).
#Bookmark the [[HPL2/Engine Scripts|Script Functions]] page. This page is a great reference for when you create your scripts.

==Additional reading==
Here are a few additional things you can do that are very useful to check out:

#Check out the [[HPL2/Glossary|HPL2 glossary]] for explanations of various phrases.
#Join the official [https://discord.com/invite/frictionalgames Discord server] and ask questions if you need help.

You are now ready to start [[HPL2/TDD/Creating a Custom Story|'''setting up your first custom story''']]!

HPL2/Changelog

2023-09-20T21:36:25Z

Darkfire: Add the coin chest stuff

HPL2/custom story settings.cfg

2023-09-19T20:55:09Z

Darkfire: Add a note about file locality

{{DISPLAYTITLE:custom_story_settings.cfg}}

This file is used to configure a custom story, and is found in the root of the custom story, residing inside a subfolder of <code>/custom_stories</code> in the Amnesia folder. This file only applies to TDD, not AMFP. Below are all configurable fields for this file and what each does. All of the fields are XML attributes applied to an element named <code>Main</code>.

{| class="wikitable"
!Field name
!Description
|-
|Name
|The name of your custom story as it will appear in the game menu.
|-
|Author
|Your name which appears under the title.
|-
|ImgFile
|The name of an image file to use as the background image in the game menu.
|-
|MapsFolder
|The folder where your levels are loaded from. Recommended to keep as "maps/".
|-
|StartMap
|The name of the first level that is loaded upon clicking "Start new game" in the main menu.
|-
|StartPos
|The internal name of a PlayerStart type area within the above level. If empty or not matching, the game will use the first alphabetical start area.
|-
|ExtraLangFilePrefix
|A prefix applied to all language files that this story uses. If unspecified, it falls back to the default "extra_". This field can include forward slashes to represent folders.
|-
|DefaultExtraLangFile
|The default language file to load. This is appended to the above prefix, making the default language file "extra_english.lang".
|-
|InitCfgFile
|A relative path to a main_init.cfg file. Specifying this field transforms the custom story into a full conversion mod. (Coming soon)
|}

Note that the files are specified in relation to your mod folder. For example, <code>InitCfgFile="YourMod/config/main_init.cfg"</code> will not be found; instead, use <code>InitCfgFile="config/main_init.cfg"</code>.

HPL2/Engine Scripts

2023-09-15T18:02:05Z

Darkfire: /* Quests */ update the hint func descriptions

{{TocRight}}

This page documents all scripts available in Amnesia: The Dark Descent.

{{note|'''Note''': Some of the functions require the Amnesia 1.3 or 1.5 update. Steam and other online store copies should be automatically updated. Other copies can get 1.3 [http://www.frictionalgames.com/forum/thread-24334.html here].}}

== Directives ==

First off, <code>#include "file.hps"</code> can be used to programmatically merge together multiple separate files to make organizing scripts easier.

{{ReqVer|1.5}}

==Engine scripts==
===Main===

The following functions are the main hps functions that the HPL2 engine looks to run on certain events - similar to the C++ int main() function.

<syntaxhighlight lang="cpp">
void OnStart();
</syntaxhighlight>

The function that runs when the map is loaded for the first time.

<syntaxhighlight lang="c++">
void OnEnter();
</syntaxhighlight>

The function that runs whenever the player enters a map.

<syntaxhighlight lang="c++">
void OnLeave();
</syntaxhighlight>

The function that runs when the player leaves a map.

<syntaxhighlight lang="c++">
void OnGameStart();
</syntaxhighlight>

This function is found in the global.hps file and the inventory.hps file, and is run when the game is first started by the player (ie via "Start New Game").

<syntaxhighlight lang="c++">
void OnUpdate(float afStep);
</syntaxhighlight>
{{ReqVer|1.5}}

This function is executed for every game update or "tick". Can be used for rapid-firing updates instead of looping timers. Keep in mind that this can affect game performance if not used with care.

===General===

<syntaxhighlight lang="c++">
float RandFloat(float afMin, float afMax);
</syntaxhighlight>

Generates a random float.

#''afMin ''- minimum value
#''afMax ''- maximum value
<syntaxhighlight lang="c++">
int RandInt(int alMin, int alMax);
</syntaxhighlight>

Generates a random int. Note: the maximum value is ''inclusive'' - the RandInt() function may return this value.

#''alMin ''- minimum value
#''alMax ''- maximum value
<syntaxhighlight lang="c++">
bool StringContains(string& asString, string& asSubString);
</syntaxhighlight>

Checks whether a string contains the specified string. Example: searching for "hello" in "hello world" would return '''true'''.

#''asString ''- the string to check
#''asSubString ''- the string to search for
<syntaxhighlight lang="cpp">
string& StringSub(string& asString, int alStart, int alCount);
</syntaxhighlight>

Returns the substring in a string. Example: in the string "frictional games rocks", using 4 as ''alStart'' and 6 as ''alCount'' would return '''"tional"'''.

#''asString ''- the string
#''alStart ''- start position in the string
#''alCount ''- amount of characters
<syntaxhighlight lang="c++">
int StringToInt(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns an integer converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
float StringToFloat(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a float converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
bool StringToBool(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a boolean converted from a string, else returns false.

#''asString'' - String to convert.

===Mathematical Operations===

<syntaxhighlight lang="c++">
float MathSin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathCos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathTan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAsin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAcos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan2(float afX, float afY);
</syntaxhighlight>

{{ReqVer|1.3}}

Calculates and returns the arc tangent of the specified values.

#''afX'' - First value to operate.
#''afY'' - Second value to operate.
<syntaxhighlight lang="c++">
float MathSqrt(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the square root of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathPow(float afBase, float afExp);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the value of afBase raised to the power of afExp.

#''afBase'' - The base value.
#''afExp'' - Value to calculate the base with.
<syntaxhighlight lang="c++">
float MathMin(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the lowest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathMax(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the highest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathClamp(float afX, float afMin, float afMax);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns afX clamped between afMin and afMax. If afX < afMin, returns afMin, and if afX > afMax, returns afMax.

#''afX'' - The value to clamp.
#''afMin'' - The minimum value to clamp afX with.
#''afMax'' - The maximum value to clamp afX with.
<syntaxhighlight lang="c++">
float MathAbs(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the absolute value.

#''afX'' - Value to operate.

===Debugging===

<syntaxhighlight lang="cpp">
void Print(string& asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string& asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a string to the debug console.

#''asString ''- the string to print
#''abCheckForDuplicates ''- if true, the string won't be printed more than once on screen until it disappears
<syntaxhighlight lang="c++">
void ProgLog(string& asLevel, string& asMessage);
</syntaxhighlight>

Prints an entry to the ProgLog (progression log). ProgLog is a file created in Documents/Amnesia/main (or an FC folder if one is being used). It logs certain events, such us opening the menu or picking up the lantern, as well as the player's state (Health, Sanity, Oil, Tinderboxes, Coins), for the purpose of documenting a tester's playstyle. This function allows to log custom messages.The messages in the ProgLog file are sorted by time elapsed since a map was loaded.

ProgLog has to be enabled for a player profile in ''user_settings.cfg'' before it starts working.

#''asLevel ''- can be "Low", "Medium" or "High". It's a tag which appears in each log entry, for event prioritising.
#''asMessage ''- The custom message to be printed to the log.
<syntaxhighlight lang="c++">
bool ScriptDebugOn();
</syntaxhighlight>

Checks whether the debug mode is enabled. See [[HPL2/Development_Environment|"Setting up Development Environment"]] to setup debug mode on your own computer.

===Variables===
{{warning|Regular variables (int, float, etc.) are '''not''' saved by the game. Using them in important parts of yor script will break it upon loading a game save. In HPL, those variables should only be used for disposable counters, like spawning objects in a "for" loop. For variables which need to be saved, use the wrappers as described below.}}

====Local====

Local variables can be used throughout the same script file.

<syntaxhighlight lang="cpp">
void SetLocalVarInt(string& asName, int alVal);
void AddLocalVarInt(string& asName, int alVal);
int GetLocalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string& asName, float afVal);
void AddLocalVarFloat(string& asName, float afVal);
float GetLocalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string& asName, const string& asVal);
void AddLocalVarString(string& asName, string& asVal);
string& GetLocalVarString(string& asName);
</syntaxhighlight>

====Global====

Global variables can be used throughout several maps and can be accessed by several script files.

<syntaxhighlight lang="c++">
void SetGlobalVarInt(string& asName, int alVal);
void AddGlobalVarInt(string& asName, int alVal);
int GetGlobalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string& asName, float afVal);
void AddGlobalVarFloat(string& asName, float afVal);
float GetGlobalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string& asName, const string& asVal);
void AddGlobalVarString(string& asName, string& asVal);
string& GetGlobalVarString(string& asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string& asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS);
</syntaxhighlight>

Creates a particle system on an entity.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntityExt(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS,
float afR, float afG, float afB, float afA, bool abFadeAtDistance, float afFadeMinEnd, float afFadeMinStart,
float afFadeMaxStart, float afFadeMaxEnd);
</syntaxhighlight>

Creates a particle system on an entity, extended method with more options.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''abFadeAtDistance ''- determines whether a particle system fades from a certain distance on
#''afFadeMinEnd ''- minimum distance at which the particle system stops fading
#''afFadeMinStart ''- minimum distance at which the particle system starts fading
#''afFadeMaxStart ''- maximum distance at which the particle system starts fading
#''afFadeMaxEnd ''- maximum distance at which the particle system stops fading
<syntaxhighlight lang="c++">
void DestroyParticleSystem(string& asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string& asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load. Extension: .snt
<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string& asSoundName, string& asSoundFile, string& asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound on an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use + extension .snt
#''asEntity ''- the entity to create the sound at, can be "Player"
#''afFadeTime ''- time in seconds the sound needs to fade. Avoids enemies hearing the sound if afFadeTime is at least 0.1f
#''abSaveSound ''- if ''true'', a looping sound will "remember" its playback state (currently playing/stopped), and that state will be restored the next time the level is entered. If ''true'', the sound is never attached to the entity! Note that saving should only be used on ''looping sounds''!
<syntaxhighlight lang="c++">
void FadeInSound(string& asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- ?
<syntaxhighlight lang="c++">
void StopSound(string& asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediatly stop the sound
<syntaxhighlight lang="c++">
void PlayMusic(string& asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music to play + extension .ogg
#''abLoop ''- determines whether a music track should loop
#''afVolume ''- volume of the music
#''afFadeTime ''- time in seconds until music reaches full volume
#''alPrio ''- priority of the music. Note that only the music with the highest priority can be heard! 0 - lowest, 1 - higher, etc.
#''abResume'' - if ''true'', playback will be continued from where the track stopped after the call to StopMusic(); if ''false'', the track will be restarted.
<syntaxhighlight lang="c++">
void StopMusic(float afFadeTime, int alPrio);
</syntaxhighlight>

Stops music.

#''afFadeTime ''- time in seconds until music stops
#''alPrio ''- the priority of the music that should stop
<syntaxhighlight lang="c++">
void FadeGlobalSoundVolume(float afDestVolume, float afTime);
</syntaxhighlight>

Influences the global sound volume, that means everything you can hear '''from the world'''. This does not affect music of GUI sounds.

#''afDestVolume ''- desired volume
#''afTime ''- time in seconds until volume reaches desired volume
<syntaxhighlight lang="c++">
void FadeGlobalSoundSpeed(float afDestSpeed, float afTime);
</syntaxhighlight>

Influences the global sound speed.

#''afDestSpeed ''- desired speed
#''afTime ''- time in seconds until volume reaches desired speed

===Lights===

<syntaxhighlight lang="c++">
void SetLightVisible(string& asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string& asLightName, float afR, float afG, float afB, float afA, float afRadius, float afTime);
</syntaxhighlight>

Changes the properties of a light.

#''asLightName ''- internal name
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''afRadius ''- radius of the light. -1 means keeping the radius
#''afTime ''- time in seconds until change is done
<syntaxhighlight lang="c++">
void SetLightFlickerActive(string& asLightName, bool abActive);
</syntaxhighlight>

Activates flickering on a light.

#''asLightName'' - The internal light name
#''abActive'' - true = active, false = inactive

==Game scripts==

===General===

<syntaxhighlight lang="c++">
void StartCredits(string& asMusic, bool abLoopMusic, string& asTextCat, string& asTextEntry, int alEndNum);
</syntaxhighlight>

Starts the end credits screen.

#''asMusic ''- the music to play (including .ogg)
#''abLoopMusic ''- determines whether the music should loop
#''asTextCat ''- the category to be used in the .lang file
#''asTextEntry ''- the entry in the .lang file
#''alEndNum ''- Amnesia has 3 different endings and displays a code at the bottom. Determines which code is displayed. 0-2 will display codes, any other integer will not.
<syntaxhighlight lang="c++">
void StartDemoEnd();
</syntaxhighlight>

Starts the end images that are used in the demo, images are named "demo_end01.jpg", increase the number for each image you want to use. (NEEDS VERIFICATION)

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Save the game to the auto save.

<syntaxhighlight lang="c++">
void CheckPoint (string& asName, string& asStartPos, string& asCallback, string& asDeathHintCat, string& asDeathHintEntry);
</syntaxhighlight>

Sets a checkpoint at which the player will respawn in case he dies. Callback syntax: <code>void MyFunc(string &in asName, int alCount)</code> Count is 0 on the first checkpoint load!

#''asName ''- the internal name
#''asStartPos ''- the name of the StartPos in the editor
#''asCallback ''- the function to call when the player dies/respawns
#''asDeathHintCat ''- the category of the death hint message to be used in the .lang file
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string& asMapName, string& asStartPos, string& asStartSound, string& asEndSound);
</syntaxhighlight>

Immediatly loads another map.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos on the next map
#''asStartSound ''- the sound that is played when the change starts
#''asEndSound ''- the sound that is played when the new map is loaded
<syntaxhighlight lang="c++">
void ClearSavedMaps();
</syntaxhighlight>

Clears the "history" of the save, useful to do when you know the player will not be able to go back anymore. Makes the next save much smaller in size.

<syntaxhighlight lang="c++">
void CreateDataCache();
void DestroyDataCache();
</syntaxhighlight>

This caches all current textures and models and they are not released until destroy is called. If there is already cached data it is destroyed.
Create caches to enable faster loading when going back to a map. Destroy the cache if you know the player won't go back to that map.

<syntaxhighlight lang="c++">
void SetMapDisplayNameEntry(string& asNameEntry);
</syntaxhighlight>

Sets the map name shown in save file names. If none is set NULL is assumed.

#''asNameEntry ''- the entry to display, category must be "Levels"!
<syntaxhighlight lang="c++">
void SetSkyBoxActive(bool abActive);
</syntaxhighlight>

Enables/Disables the skybox.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetSkyBoxTexture(string& asTexture);
</syntaxhighlight>

Sets the texture of the skybox.

#''asTexture'' - The texture file to set. Extension: .dds
<syntaxhighlight lang="c++">
void SetSkyBoxColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the solid color of the skybox rather than a texture.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogActive(bool abActive);
</syntaxhighlight>

Enables/Disables the global fog.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetFogColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the color to use for the global fog.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogProperties(float afStart, float afEnd, float afFalloffExp, bool abCulling);
</syntaxhighlight>

Sets the properties for the global fog.

#''afStart ''- how many meters from the camera should the fog begin
#''afEnd ''- how many meters from the camera should the fog reach full thickness
#''afFalloffExp ''- the amount by which the thinkness increases
#''abCulling ''- whether occlusion culling is active for the fog; this prevents objects behind the fog from being loaded
<syntaxhighlight lang="c++">
void SetupLoadScreen(string&asTextCat, string&asTextEntry, int alRandomNum, string&asImageFile);
</syntaxhighlight>

Determines which loading screen will be shown when changing maps.

#''asTextCat ''- the category of the loading text in the .lang file to be shown on the loading screen
#''asTextEntry ''- the entry in the .lang file
#''alRandomNum ''- if greater 1, then it will randomize between 1 and alRandom for each LoadScreen giving entry the suffix XX (eg 01). If < =1 then no suffix is added
#''asImageFile ''- the image to be shown (optional)

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string& asName, float afTime, string& asFunction);
</syntaxhighlight>

Creates a timer which calls a function when it expires. Callback syntax: <code>void MyFunc(string &in asTimer)</code>

#''asName ''- the name of the timer
#''afTime ''- time in seconds
#''asFunction ''- the function to call
<syntaxhighlight lang="c++">
void RemoveTimer(string& asName);
</syntaxhighlight>

Removes a timer, no matter how much time is left.

#''asName'' - the internal name of the timer.
<syntaxhighlight lang="c++">
float GetTimerTimeLeft(string& asName);
</syntaxhighlight>

Returns the time left on a timer.

#''asName'' - the internal name of the timer.

===Screen Effects===

<syntaxhighlight lang="c++">
void FadeOut(float afTime);
</syntaxhighlight>

Fades the screen to black.

''afTime ''- time in seconds until the screen is completly black

<syntaxhighlight lang="c++">
void FadeIn(float afTime);
</syntaxhighlight>

Fades the screen back to normal.

''afTime ''- time in seconds until the screen back to normal

<syntaxhighlight lang="c++">
void FadeImageTrailTo(float afAmount, float afSpeed);
</syntaxhighlight>

Applies the image trail effect to the screen.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeSepiaColorTo(float afAmount, float afSpeed);
</syntaxhighlight>

Makes the screen go dark red.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeRadialBlurTo(float afSize, float afSpeed);
</syntaxhighlight>

Applies radial blur effects to the screen.

''afSize ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void SetRadialBlurStartDist(float afStartDist);
</syntaxhighlight>

Determines at which distance the radial blur effects appear.

''afStartDist ''- the distance at which the effect starts

<syntaxhighlight lang="c++">
void StartEffectFlash(float afFadeIn, float afWhite, float afFadeOut);
</syntaxhighlight>

Fades the screen to white.

''afFadeIn ''- time in seconds until screen is white ''afWhite ''- determines to which percentage the screen fades to white (1.0 = completly white) ''afFadeOut ''- time in seconds until screen is back to normal again

<syntaxhighlight lang="c++">
void StartEffectEmotionFlash(string& asTextCat, string& asTextEntry, string& asSound);
</syntaxhighlight>

Fades the screen to white and shows a text message.

''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''asSound ''- the sound to play while fading

<syntaxhighlight lang="c++">
void AddEffectVoice(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry,
bool abUsePosition, string& asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an effect to be played. It is okay to call this many times in order to play many voices in a row. The EffectVoiceOverCallback is not called until ALL voices have finished.

''asVoiceFile ''- the voice to play ''asEffectFile ''- the effect to play ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''abUsePosition ''- plays using 3D from the entity, or without 3D ''asPosEntity ''- the entity at which the effect appears ''afMinDistance ''- minimum distance to see the effect ''afMaxDistance ''- maximum distance to see the effect

<syntaxhighlight lang="c++">
void StopAllEffectVoices(float afFadeOutTime);
</syntaxhighlight>

Stops all voices and calls the EffectVoiceOverCallback.

<syntaxhighlight lang="c++">
bool GetEffectVoiceActive();
</syntaxhighlight>

Checks whether EffectVoices are still active.

<syntaxhighlight lang="c++">
void SetEffectVoiceOverCallback(string& asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<syntaxhighlight lang="c++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string& asSPSFile);
void StopPlayerSpawnPS();
</syntaxhighlight>

Continuously spawn regular particle systems (''.ps'') around the player. Particles created by this script carry over from map to map. ''asSPSFile'' - the ''.sps'' file to use. Exemplary ''.sps'' files are located in the ''/misc'' folder in the main game directory. Custom ''.sps'' files can be created by hand in a text editor (see existing ones and mimic how those are written). Since ''StopPlayerSpawnPS()'' doesn't seem to work, to stop an SPS you must create an ''.sps'' file with an empty particle field field and override the old SPS by calling ''StartPlayerSpawnPS'' again.

<syntaxhighlight lang="c++">
void PlayGuiSound(string& asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

''asSoundFile ''- the sound to play (extension is .snt) ''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void StartScreenShake(float afAmount, float afTime, float afFadeInTime, float afFadeOutTime);
</syntaxhighlight>

Shakes the screen.

''afAmount ''- intensity of the shake ''afTime ''- duration of the shake ''afFadeInTime ''- time in seconds until full intensity is reached ''afFadeOutTime ''- time until screen is back to normal

<syntaxhighlight lang="c++">
void SetInDarknessEffectsActive(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the sanity drain and night vision effects while in the darkness.

''bool abX'' - Enable/disable effects.

<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

{{ReqVer|1.5}}

Displays an image file directly onto the screen.

''asImageName'' - The image file to render (.jpg, .png, .tga, .dds)

''afX'' - The X position of the image

''afY'' - The Y position of the image

''afScale'' - The scale of the image (default 1.0f)

''abUseRelativeCoordinates'' - Whether or not to use relative coordinates for positioning. Use false for absolute.

''afDuration'' - The duration that the image is displayed for.

''afFadeIn'' - The time, in seconds, to fade in the image.

''afFadeOut'' - The time, in seconds, to fade out the image.

===Insanity===

<syntaxhighlight lang="c++">
void SetInsanitySetEnabled(string& asSet, bool abX);
</syntaxhighlight>

Determines which InsanitySets are enabled.

''asSet ''- the set ''abX ''- enabled or not

<syntaxhighlight lang="c++">
void StartInsanityEvent(string &in asEventName);
</syntaxhighlight>

{{ReqVer|1.3}}

Starts a specified insanity event.

''asEventName ''- Insanity event to play.

<syntaxhighlight lang="c++">
void StartRandomInsanityEvent();
</syntaxhighlight>

Starts a random insanity event from the available sets.

<syntaxhighlight lang="c++">
void StopCurrentInsanityEvent();
</syntaxhighlight>

{{ReqVer|1.3}}

Stops the currently playing insanity event.

<syntaxhighlight lang="c++">
void InsanityEventIsActive();
</syntaxhighlight>

Checks whether an insanity event is currently in effect… Or so it was supposed to be, but as it doesn't return a value, we can never know [http://wiki.frictionalgames.com/lib/images/smileys/icon_smile.gif?nolink&15x15]

===Player===

Note that the player's maximum health and sanity is 100.

<syntaxhighlight lang="c++">
void SetPlayerActive(bool abActive);
</syntaxhighlight>

Enabled/Disable player controlled movement.

<syntaxhighlight lang="c++">
void ChangePlayerStateToNormal();
</syntaxhighlight>

Sets certain effects back to normal. It can for example make the player drop an item.

<syntaxhighlight lang="c++">
void SetPlayerCrouching(bool abCrouch);
</syntaxhighlight>

Forces the player to crouch.

<syntaxhighlight lang="c++">
void AddPlayerBodyForce(float afX, float afY, float afZ, bool abUseLocalCoords);
</syntaxhighlight>

Pushes the player into a certain direction. Note that you need values above ~2000 to see any effects.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''abUseLocalCoords ''- If true, axes are based on where the player is facing, not the world.

<syntaxhighlight lang="c++">
void ShowPlayerCrossHairIcons(bool abX);
</syntaxhighlight>

Enables/Disables the icons when a player has something in focus.

<syntaxhighlight lang="c++">
void SetPlayerSanity(float afSanity);
void AddPlayerSanity(float afSanity);
float GetPlayerSanity();
</syntaxhighlight>

Modifies/returns the sanity of the player.

<syntaxhighlight lang="c++">
void SetPlayerHealth(float afHealth);
void AddPlayerHealth(float afHealth);
float GetPlayerHealth();
</syntaxhighlight>

Modifies/returns the health of the player.

<syntaxhighlight lang="c++">
void SetPlayerLampOil(float afOil);
void AddPlayerLampOil(float afOil);
float GetPlayerLampOil();
</syntaxhighlight>

Modifies/returns the lamp oil of the player.

<syntaxhighlight lang="c++">
float GetPlayerSpeed();
float GetPlayerYSpeed();
</syntaxhighlight>

Returns the current speed of the player.

<syntaxhighlight lang="c++">
void SetSanityDrainDisabled(bool abX);
</syntaxhighlight>

Enables/Disables sanity drain from darkness, monsters, etc.

<syntaxhighlight lang="c++">
void GiveSanityBoost();
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a fixed amount.

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

''afAmount ''- amount of sanity damage done ''abUseEffect ''- determines whether an effect is played when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string& asType, bool abSpinHead, bool abLethal);
</syntaxhighlight>

Reduces the health of the player.

''afAmount ''- amount of damage done to health ''asType ''- plays a certain effect on the screen when the damage is dealt (BloodSplat, Claws or Slash) ''abSpinHead ''- changes the camera view when damage is dealt ''abLethal ''- set to true if player can die from given damage

<syntaxhighlight lang="c++">
void FadePlayerFOVMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the field of view of the player. A shorter FOV will create a zoom effect.

''afX ''- multiplier of default FOV (1 is default) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerAspectMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the aspect ratio of the player. Basically stretches or narrows the screen horizontally.

''afX ''- multiplier of default aspect (default is 1) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerRollTo(float afX, float afSpeedMul, float afMaxSpeed);
</syntaxhighlight>

Rotates the position of the camera on the player's body.

''afX ''- angle of rotation of head, positive being counter-clockwise ''afSpeedMul ''- speed (possibly acceleration) multiplier of the rotation (default 1, which is really slow) ''afMaxSpeed ''- maximum speed of rotation

<syntaxhighlight lang="c++">
void MovePlayerHeadPos(float afX, float afY, float afZ, float afSpeed, float afSlowDownDist);
</syntaxhighlight>

Changes the position of the camera on the player's body.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''afSpeed ''- speed at which the change happens ''afSlowDownDist ''- distance at which to start slowing down (prevents the head from abruptly stopping)

<syntaxhighlight lang="c++">
void StartPlayerLookAt(string& asEntityName, float afSpeedMul, float afMaxSpeed, string& asAtTargetCallback);
void StopPlayerLookAt();
</syntaxhighlight>

Forces the player to look at a certain entity until StopPlayerLookAt is used.

''asEntityName ''- the entity to look at ''afSpeedMul ''- how fast should the player look at the entity ''afMaxSpeed ''- maximum speed allowed ''asAtTargetCallback ''- function to call when player looks at target

<syntaxhighlight lang="c++">
void SetPlayerMoveSpeedMul(float afMul);
void SetPlayerRunSpeedMul(float afMul);
void SetPlayerLookSpeedMul(float afMul);
</syntaxhighlight>

Changes the player's move/run/look speed. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpForceMul(float afMul);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the player's jump multiplier. Higher values = higher jumps. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpDisabled(bool abX);
void SetPlayerCrouchDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to jump/crouch.

<syntaxhighlight lang="c++">
void TeleportPlayer(string& asStartPosName);
</syntaxhighlight>

Instantly teleports the player to the target StartPos.

<syntaxhighlight lang="c++">
void SetLanternActive(bool abX, bool abUseEffects);
</syntaxhighlight>

Makes the player use his lantern.

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player currently uses his lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use his lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string& asCallback);
</syntaxhighlight>

Sets the function to call when the player uses his lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Displays a message on the screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- determines how long the message is displayed. If time is < =0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void SetDeathHint(string& asTextCategory, string& asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="c++">
void DisableDeathStartSound();
</syntaxhighlight>

Disables the death sound when the player dies. This must be called directly before player is killed! The variable as soon as player dies too.

<syntaxhighlight lang="">
void MovePlayerForward(float afAmount)
</syntaxhighlight>

"REQUIRES THE 1.2 PATCH: JUSTINE" Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<syntaxhighlight lang="c++">
void SetPlayerFallDamageDisabled(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the player's ability to take fall damage.

<syntaxhighlight lang="c++">
void SetPlayerPos(float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the player's position within the level.

''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c++">
float GetPlayerPosX();
float GetPlayerPosY();
float GetPlayerPosZ();
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the player's position within the level on the specified axis.

===Journal===

<syntaxhighlight lang="c++">
void AddNote(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a note to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _Name and _Text and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void AddDiary(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a diary to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _NameX and _TextY whereas X and Y are numbers of the parts (_Name1: first diary, _Text1: first page) and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void ReturnOpenJournal(bool abOpenJournal);
</syntaxhighlight>

Only called in the pickup diary callback! If true the journal displays the entry else not.

===Quests===

<syntaxhighlight lang="c++">
void AddQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos.

''asName ''- the internal name to be used ''asNameAndTextEntry ''- entry in the .lang file. Must start with "Quest_<texthere>_Text”, and be in category “Journal”!

<syntaxhighlight lang="c++">
void CompleteQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Completes a quest.

''asName ''- the internal name of the quest ''asNameAndTextEntry ''- entry in the .lang file. Must start with " Quest_<texthere>_Text ”, and be in category “Journal”!

<syntaxhighlight lang="c++">
bool QuestIsCompleted(string& asName);
bool QuestIsAdded(string& asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map.

''alNumberOfQuests ''- Amount of Quests

<syntaxhighlight lang="c++">
void GiveHint(string& asName, string& asMessageCat, string& asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

''asName ''- the internal name ''asMessageCat ''- the category in the .lang file ''asMessageEntry ''- the entry in the .lang file ''afTimeShown ''- time in seconds until the message disappears. If time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void BlockHint(string& asName);
void UnBlockHint(string& asName);
void RemoveHint(string& asName);
</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels.

"Removing" a hint actually removes it from the list of already given hints, thus allowing it to show up again.

''asName ''- the internal name. Basic game hints use the same name as their respective lang entries, with the exception of "numbered" hints. For example, <code>EntityGrab</code> blocks the <code>EntityGrab01</code> and <code>EntityGrab02</code> entries.

===Inventory===

<syntaxhighlight lang="c++">
void ExitInventory();
</syntaxhighlight>

Exits the inventory by force.

<syntaxhighlight lang="c++">
void SetInventoryDisabled(bool abX);
</syntaxhighlight>

Disables the player's ability to open his inventory.

<syntaxhighlight lang="c++">
void SetInventoryMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Adds a message at the bottom of the inventory screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- time in seconds until the message disappears. If life time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void GiveItem(string& asName, string& asType, string& asSubTypeName, string& asImageName, float afAmount);
</syntaxhighlight>

Adds an item to the inventory of the player. Note that the item does not have to exist as entity in the world to be able to do this.

''asName ''- internal name ''asType ''- item type to give, Available types are: 

*Puzzle
*Lantern
*Health
*Sanity
*LampOil
*Tinderbox

''asSubTypeName ''- item name for .lang file ''asImageName ''- the image which will appear in inventory. For example: <code>void GiveItem("chemical_container_full_1", "Puzzle", "chemical_container_full", "chemical_container_full.tga", 1);</code> will use the image from <code>graphics/item/chemical_container_full.tga</code>

''afAmount ''- amount the item gives, - For example: Oil potions will fill the oil meter by this amount, Health potions will heal by this amount, etc.

<syntaxhighlight lang="c++">
void RemoveItem(string& asName);
</syntaxhighlight>

Removes an item from the player's inventory.

<syntaxhighlight lang="c++">
bool HasItem(string& asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

<syntaxhighlight lang="c++">
void GiveItemFromFile(string& asName, string& asFileName);
</syntaxhighlight>

Adds a single item to the player's inventory. This is meant to be used for debug mostly as it creates the actual item and then destroys it.

''asName ''- internal name ''asFileName ''- item to give + extension (.ent)

<syntaxhighlight lang="c++">
void AddCombineCallback(string& asName, string& asItemA, string& asItemB, string& asFunction, bool abAutoRemove);
</syntaxhighlight>

Allows the player to combine items in his inventory. Callback syntax: <code>void MyFunc(string &in asItemA, string &in asItemB)</code>

''asName ''- internal name for the callback ''asItemA ''- internal name of first item ''asItemB ''- internal name of second item ''asFunction ''- the function to call ''abAutoRemove ''- determines whether the callback should be removed when the items are combined

<syntaxhighlight lang="c++">
void RemoveCombineCallback(string& asName);
</syntaxhighlight>

Removes a combine callback. ''asName'' - the internal name of the callback to be removed (as specified in AddCombineCallback)

<syntaxhighlight lang="c++">
void AddUseItemCallback(string& asName, string& asItem, string& asEntity, string& asFunction, bool abAutoDestroy);
</syntaxhighlight>

Allows the player to use items on the world. Callback syntax: <code>void MyFunc(string &in asItem, string &in asEntity)</code>

''asName ''- internal name ''asItem ''- internal name of the item ''asEntity ''- entity to be able to use the item on ''asFunction ''- function to call ''abAutoDestroy ''- determines whether the item is destroyed when used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string& asName);
</syntaxhighlight>

Removes an item callback.

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string& asName, bool abActive);
</syntaxhighlight>

Activates/deactivates an entity.

<syntaxhighlight lang="c">
void SetEntityVisible(string &in asName, bool abVisible);
</syntaxhighlight>

{{ReqVer|1.3}}

Activates/deactivates an entity's visual mesh. The collision body remains.

''asName'' - Name of the entity. ''abActive'' - Activate/deactivate mesh.

<syntaxhighlight lang="c">
bool GetEntityExists(string& asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string& asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

''asName ''- internal name ''asCrossHair ''- desired crosshair, can be: Default (uses default), Grab, Push, Ignite, Pick, LevelDoor, Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string& asEntityName, string& asEntityFile, string& asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes(using for example ShowEnemyPlayerPosition).

''asEntityName ''- internal name ''asEntityFile ''- entity to be used extension .ent ''asAreaName ''- the area to create the entity at ''abFullGameSave ''- determines whether an entity "remembers" its state

<syntaxhighlight lang="c">
void ReplaceEntity(string &in asName, string &in asBodyName, string &in asNewEntityName, string &in asNewEntityFile, bool abFullGameSave);
</syntaxhighlight>

{{ReqVer|1.3}}

Removes an entity and places a new one in its place.

''asName'' - Name of the entity to replace. ''asBodyName'' - Name of the body of the entity to place the new entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''asNewEntityName'' - Name of the new entity. ''asNewEntityFile'' - Name of the new entity file. Extension .ent. ''abFullGameSave'' - Whether ALL properties of this entity should be saved throughout levels.

<syntaxhighlight lang="c++">
void PlaceEntityAtEntity(string &in asName, string &in asTargetEntity, string &in asTargetBodyName, bool abUseRotation);
</syntaxhighlight>

{{ReqVer|1.3}}

Places an entity at the position of another entity. Does not work for enemies, use TeleportEnemyToEntity instead.

''asName'' - Name of the entity to place. ''asTargetEntity'' - Name of the other entity to place the first entity at. ''asTargetBodyName'' - Name of the body of the entity to place the first entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''abUseRotation'' - Whether the entity should be rotated like the target entity.

<syntaxhighlight lang="c">
void SetEntityPos(string &in asName, float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Moves an entity to a position in the level.

''asName'' - Name of the entity to move. ''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c">
float GetEntityPosX(string &in asName);
float GetEntityPosY(string &in asName);
float GetEntityPosZ(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns an entity's position in the level on the specified axis.

''asName'' - Name of the entity.

<syntaxhighlight lang="c">
void SetEntityPlayerLookAtCallback(string& asName, string& asCallback, bool abRemoveWhenLookedAt);
</syntaxhighlight>

Calls a function when the player looks at a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code> alState: 1 = looking, -1 = not looking

''asName ''- internal name ''asCallback ''- function to call ''abRemoveWhenLookedAt ''- determines whether the callback should be removed when the player looked at the entity

<syntaxhighlight lang="c">
void SetEntityPlayerInteractCallback(string& asName, string& asCallback, bool abRemoveOnInteraction);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity)</code>

''asName ''- internal name ''asCallback ''- function to call ''abRemoveOnInteraction ''- determines whether the callback should be removed when the player interacts with the entity

<syntaxhighlight lang="c">
void SetEntityCallbackFunc(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in type)</code> Type depends on entity type and includes: "OnPickup", "Break", "OnIgnite", etc

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string& asName, string& asCallback);
</syntaxhighlight>

A callback called when ever the connection state changes (button being switched on, lever switched, etc). Callback syntax: <code>void Func(string &in asEntity, int alState)</code> alState: -1 = off, 0 = between, 1 = on

<syntaxhighlight lang="c">
void SetEntityInteractionDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string& asName);
</syntaxhighlight>

Breaks a joint. Do not use this on joints in SwingDoors, Levers, Wheels, etc. where the joint is part of an interaction. That will make the game crash.

<syntaxhighlight lang="c">
void AddEntityCollideCallback(string& asParentName, string& asChildName, string& asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entites collide. Callback syntax: <code>void MyFunc(string &in asParent, string &in asChild, int alState)</code> alState: 1 = enter, -1 = leave

''asParentName ''- internal name of main object ''asChildName ''- internal name of object that collides with main object (asterix (<nowiki>*</nowiki>) NOT supported!) ''asFunction ''- function to call ''abDeleteOnCollide ''- determines whether the callback after it was called ''alStates ''- 1 = only enter, -1 = only leave, 0 = both

<syntaxhighlight lang="c">
void RemoveEntityCollideCallback(string& asParentName, string& asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string& asEntityA, string& asEntityB);
</syntaxhighlight>

Checks whether two entites collide. This function does NOT support asterix (<nowiki>*</nowiki>) or "Player"!

<syntaxhighlight lang="c">
void SetBodyMass(string &in asName, float afMass);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to set.

<syntaxhighlight lang="c">
float GetBodyMass(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to get.

====Props====

<syntaxhighlight lang="c">
void SetPropEffectActive(string& asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Can be used on coal to give it the black color it should have.

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string& asName, bool abActive, float afFadeTime);
</syntaxhighlight>

Activates/deactivates a prop.

''asName ''- internal name ''abActive ''- nothing to add ''afFadeTime ''- time in seconds until prop fully fades

<syntaxhighlight lang="c">
void SetPropStaticPhysics(string& asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string& asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string& asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string& asOffsetArea);
</syntaxhighlight>

Rotates the prop up to a set speed.

''asName ''- internal name ''afAcc ''- acceleration ''afGoalSpeed ''- desired speed ''afAxisX ''- rotation around X axis ''afAxisY ''- rotation around Y axis ''afAxisZ ''- rotation around Z axis ''abResetSpeed ''- determines whether the speed is resetted after goal speed is reached ''asOffsetArea ''- the area to rotate around, if empty, then the center of the body is used Note: The entity you want to rotate MUST be a "StaticObject" entity!

<syntaxhighlight lang="cpp">
void StopPropMovement(string& asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

a''sPropName''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

{{bug|''afRotZ '' is used for both the ZX rotation and the Z position of the attached prop. Unwanted rotation can be avoided by using: ''AddAttachedPropToProp(asPropName, asAttachName, asAttachFile, afPosX, afPosY, '''0''', afPosZ, '''90.0f''', afPosZ)''}}

{{bug|Attaching a breakable prop to a physically active prop, and then breaking the attached prop, will cause the game to crash, should the parent object be moved or reset.}}

<syntaxhighlight lang="cpp">
void AttachPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Attaches a prop to another prop. Fixed version of AddAttachedPropToProp.

''asPropName ''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

<syntaxhighlight lang="cpp">
void RemoveAttachedPropFromProp(string& asPropName, string& asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string& asName, float afHealth);
void AddPropHealth(string& asName, float afHealth);
float GetPropHealth(string& asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string& asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string& asProp, string& asAnimation, float afFadeTime, bool abLoop, string& asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function. Callback syntax: <code>void MyFunc(string &in asProp)</code>

''asProp ''- internal name of the prop ''asAnimation ''- animation to play ''afFadeTime ''- ? ''abLoop ''- determines whether the animation loops ''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddPropImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
</syntaxhighlight>

These functions push objects. Note that rather high values are needed when applying ''forces'' (on the order of ~100 (weak) to ~10000 (strong)), but not impulses (values less than 10 can be appropriate). Forces are external influences, and will have different effect depending on the mass of the object they are being applied to; impulses disregard mass, and can cause objects to break, as if hit. A "Body" is a physics-related helper object, to which a force or an impulse can be applied. Entities can consist of several bodies, interconnected in various ways (you can create/examine bodies in the model editor).

''asName ''- the object to push; for bodies, use this format: "''entityName''_''bodyName''" ''afX ''- magnitude along the X-axis ''afY ''- magnitude along the Y-axis ''afZ ''- magnitude along the Z-axis ''asCoordSystem ''- determines which coordinate system is used, usually "world" All of these functions are ''additive'' - when called consecutively, for each call, the vectors defined by (afX, afY, afZ) will be added together, and a resultant force/impulse will be calculated ''before'' any physics simulation is applied to the target object.

====Connections====

<syntaxhighlight lang="cpp">
void InteractConnectPropWithRope(string& asName, string& asPropName, string& asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (ie. turn wheel to move rope).

''asName ''- connection name ''asPropName ''- name of prop ''asRopeName ''- name of rope ''abInteractOnly ''- ? ''afSpeedMul ''- speed multiplier of how quickly the rope moves ''afToMinSpeed ''- the slowest the rope will move when moving the prop ''afToMaxSpeed ''- the fastest the rope will move when moving the prop ''abInvert ''- whether to invert the direction the rope moves ''alStatesUsed ''- which states of the prop can interact with the rope?

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string& asName, string& asPropName, string& asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondance to prope "amount" and the moveobject open amount. It is best used for Wheel-door connections!

<syntaxhighlight lang="cpp">
void ConnectEntities(string& asName, string& asMainEntity, string& asConnectEntity, bool abInvertStateSent, int alStatesUsed, string& asCallbackFunc);
</syntaxhighlight>

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> State is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string& asName, bool abLit, bool abEffects);
</syntaxhighlight>

(Un)lits a lamp.

''asName ''- Name of the lamp ''abLit ''- Set true if you want the lamp to be lit, set to false if you want the lamp to be unlit ''abEffects ''- If you want to have the lamp fade in/out when it gets (un)lit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string& asName, bool abLocked, bool abEffects);
void SetSwingDoorClosed(string& asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Locks/closes a swing door.

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string& asName);
bool GetSwingDoorClosed(string& asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string& asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string& asName);
</syntaxhighlight>

Returns an integer depending on how far the door is opened. -1 = angle is close to 0°, 1 = angle is 70% or higher of max, 0 = inbetween -1 and 1.

<syntaxhighlight lang="cpp">
void SetLevelDoorLocked(string& asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string& asName, string& asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string& asName, string& asTextCat, string& asTextEntry);
</syntaxhighlight>

Displays a message when interacting with a locked level door.

''asName ''- internal name ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="cpp">
void SetMoveObjectState(string& asName, float afState);
</syntaxhighlight>

Moves an object to a certain state.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween (and above, for example, the bridge_metal_vert) are valid too!

<syntaxhighlight lang="cpp">
void SetMoveObjectStateExt(string& asName, float afState, float afAcc, float afMaxSpeed, float afSlowdownDist, bool abResetSpeed);
</syntaxhighlight>

Moves an object to a certain state, extended method.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween are valid too! ''afAcc ''- acceleration ''afMaxSpeed ''- maximum speed ''afSlowdownDist ''- Distance to the target state before decceleration occurs. ''abResetSpeed ''- Set to True if the prop's speed should be reset before performing the movement, else the prop will accelerate from it's current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string& asName, int alState);
void SetWheelStuckState(string& asName, int alState, bool abEffects);
void SetLeverStuckState(string& asName, int alState, bool abEffects);
</syntaxhighlight>

Makes a prop<nowiki>\</nowiki>wheel<nowiki>\</nowiki>lever stuck in a certain state.

''asName ''- internal name ''alState ''- 0 = not stuck, 1 = at max, -1 = at min ''abEffects ''- use effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string& asName, float afAngle, bool abAutoMove);
</syntaxhighlight>

Moves a wheel to a certain angle.

''asName ''- internal name ''afAngle ''- angle ''abAutoMove ''- determines whether the wheel should move on its own

<syntaxhighlight lang="cpp">
void SetWheelInteractionDisablesStuck(string& asName, bool abX);
void SetLeverInteractionDisablesStuck(string& asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string& asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string& asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when state changes. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code>

<syntaxhighlight lang="cpp">
void SetButtonSwitchedOn(string& asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entites to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string& asAreaName, string& asProp);
void AttachBodyToStickyArea(string& asAreaName, string& asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string& asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====Enemies====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string& asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Activates the npc

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string& asName, bool abX);
</syntaxhighlight>

Sets an NPC's head to follow the player's movement's.

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string& asName, bool abX);
</syntaxhighlight>

Makes an enemy a hallucination. Hallucinations fade to smoke when they get near the player.

<syntaxhighlight lang="cpp">
void FadeEnemyToSmoke(string& asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string& asName);
</syntaxhighlight>

Makes the enemy run to the player, no matter where he is.

<syntaxhighlight lang="cpp">
void AlertEnemyOfPlayerPresence(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gives the specified enemy the player's current position and makes it search the area.

<syntaxhighlight lang="cpp">
void SetEnemyDisableTriggers(string& asName, bool abX);
</syntaxhighlight>

Enables or disables enemy triggers. If disabled, enemy will not react to player or attack.

<syntaxhighlight lang="cpp">
void AddEnemyPatrolNode(string& asName, string& asNodeName, float afWaitTime, string& asAnimation);
</syntaxhighlight>

Adds a patrol node to the enemy's path.

''asName ''- internal name of the enemy ''asNodeName ''- path node ''afWaitTime ''- time in seconds that the enemy waits at the path node before continuing ''asAnimation ''- the animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string& asEnemyName);
</syntaxhighlight>

Clears the current path of patrol nodes of the enemy.

<syntaxhighlight lang="cpp">
void SetEnemySanityDecreaseActive(string &in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether an enemy activates the player's sanity drain when stared at.

''asName ''- Internal name of the enemy ''abX ''- Enabled/disabled

<syntaxhighlight lang="cpp">
void TeleportEnemyToNode(string &in asEnemyName, string &in asNodeName, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific PathNode.

''asEnemyName ''- Internal name of the enemy ''asNodeName ''- Internal name of the node to teleport to ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="cpp">
void TeleportEnemyToEntity(string &in asEnemyName, string &in asTargetEntity, string &in asTargetBody, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific entity.

''asEnemyName ''- Internal name of the enemy ''asTargetEntity ''- Internal name of the entity to teleport to ''asTargetBody''- Internal name of the entity's body name to teleport to. If empty, the first body will be used (might be unstable, recommended to input a body anyway) ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="c">
void ChangeManPigPose(string&in asName, string&in asPoseType);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the pose a specified ManPig.

''asName ''- Internal name of the enemy ''asPoseType''- Name of the ManPig pose to use. Can be "Biped" or "Quadruped"

<syntaxhighlight lang="c">
void SetTeslaPigFadeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should fade the player's view in and out.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigSoundDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should play the proximity sounds.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigEasyEscapeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should be easier to escape from when hunted.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string&in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a TeslaPig to be visible for a short time.

''asName ''- Internal name of the enemy

<syntaxhighlight lang="c">
string& GetEnemyStateName(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the name of the state a specified enemy is current in. States can be Hunt, Search, Patrol, Wait, Alert, Investigate, Track and BreakDoor.

''asName ''- Internal name of the enemy

HPL2/Engine Scripts

2023-09-15T17:59:33Z

Darkfire: /* Quests */ update about managing hints

{{TocRight}}

This page documents all scripts available in Amnesia: The Dark Descent.

{{note|'''Note''': Some of the functions require the Amnesia 1.3 or 1.5 update. Steam and other online store copies should be automatically updated. Other copies can get 1.3 [http://www.frictionalgames.com/forum/thread-24334.html here].}}

== Directives ==

First off, <code>#include "file.hps"</code> can be used to programmatically merge together multiple separate files to make organizing scripts easier.

{{ReqVer|1.5}}

==Engine scripts==
===Main===

The following functions are the main hps functions that the HPL2 engine looks to run on certain events - similar to the C++ int main() function.

<syntaxhighlight lang="cpp">
void OnStart();
</syntaxhighlight>

The function that runs when the map is loaded for the first time.

<syntaxhighlight lang="c++">
void OnEnter();
</syntaxhighlight>

The function that runs whenever the player enters a map.

<syntaxhighlight lang="c++">
void OnLeave();
</syntaxhighlight>

The function that runs when the player leaves a map.

<syntaxhighlight lang="c++">
void OnGameStart();
</syntaxhighlight>

This function is found in the global.hps file and the inventory.hps file, and is run when the game is first started by the player (ie via "Start New Game").

<syntaxhighlight lang="c++">
void OnUpdate(float afStep);
</syntaxhighlight>
{{ReqVer|1.5}}

This function is executed for every game update or "tick". Can be used for rapid-firing updates instead of looping timers. Keep in mind that this can affect game performance if not used with care.

===General===

<syntaxhighlight lang="c++">
float RandFloat(float afMin, float afMax);
</syntaxhighlight>

Generates a random float.

#''afMin ''- minimum value
#''afMax ''- maximum value
<syntaxhighlight lang="c++">
int RandInt(int alMin, int alMax);
</syntaxhighlight>

Generates a random int. Note: the maximum value is ''inclusive'' - the RandInt() function may return this value.

#''alMin ''- minimum value
#''alMax ''- maximum value
<syntaxhighlight lang="c++">
bool StringContains(string& asString, string& asSubString);
</syntaxhighlight>

Checks whether a string contains the specified string. Example: searching for "hello" in "hello world" would return '''true'''.

#''asString ''- the string to check
#''asSubString ''- the string to search for
<syntaxhighlight lang="cpp">
string& StringSub(string& asString, int alStart, int alCount);
</syntaxhighlight>

Returns the substring in a string. Example: in the string "frictional games rocks", using 4 as ''alStart'' and 6 as ''alCount'' would return '''"tional"'''.

#''asString ''- the string
#''alStart ''- start position in the string
#''alCount ''- amount of characters
<syntaxhighlight lang="c++">
int StringToInt(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns an integer converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
float StringToFloat(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a float converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
bool StringToBool(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a boolean converted from a string, else returns false.

#''asString'' - String to convert.

===Mathematical Operations===

<syntaxhighlight lang="c++">
float MathSin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathCos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathTan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAsin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAcos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan2(float afX, float afY);
</syntaxhighlight>

{{ReqVer|1.3}}

Calculates and returns the arc tangent of the specified values.

#''afX'' - First value to operate.
#''afY'' - Second value to operate.
<syntaxhighlight lang="c++">
float MathSqrt(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the square root of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathPow(float afBase, float afExp);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the value of afBase raised to the power of afExp.

#''afBase'' - The base value.
#''afExp'' - Value to calculate the base with.
<syntaxhighlight lang="c++">
float MathMin(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the lowest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathMax(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the highest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathClamp(float afX, float afMin, float afMax);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns afX clamped between afMin and afMax. If afX < afMin, returns afMin, and if afX > afMax, returns afMax.

#''afX'' - The value to clamp.
#''afMin'' - The minimum value to clamp afX with.
#''afMax'' - The maximum value to clamp afX with.
<syntaxhighlight lang="c++">
float MathAbs(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the absolute value.

#''afX'' - Value to operate.

===Debugging===

<syntaxhighlight lang="cpp">
void Print(string& asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string& asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a string to the debug console.

#''asString ''- the string to print
#''abCheckForDuplicates ''- if true, the string won't be printed more than once on screen until it disappears
<syntaxhighlight lang="c++">
void ProgLog(string& asLevel, string& asMessage);
</syntaxhighlight>

Prints an entry to the ProgLog (progression log). ProgLog is a file created in Documents/Amnesia/main (or an FC folder if one is being used). It logs certain events, such us opening the menu or picking up the lantern, as well as the player's state (Health, Sanity, Oil, Tinderboxes, Coins), for the purpose of documenting a tester's playstyle. This function allows to log custom messages.The messages in the ProgLog file are sorted by time elapsed since a map was loaded.

ProgLog has to be enabled for a player profile in ''user_settings.cfg'' before it starts working.

#''asLevel ''- can be "Low", "Medium" or "High". It's a tag which appears in each log entry, for event prioritising.
#''asMessage ''- The custom message to be printed to the log.
<syntaxhighlight lang="c++">
bool ScriptDebugOn();
</syntaxhighlight>

Checks whether the debug mode is enabled. See [[HPL2/Development_Environment|"Setting up Development Environment"]] to setup debug mode on your own computer.

===Variables===
{{warning|Regular variables (int, float, etc.) are '''not''' saved by the game. Using them in important parts of yor script will break it upon loading a game save. In HPL, those variables should only be used for disposable counters, like spawning objects in a "for" loop. For variables which need to be saved, use the wrappers as described below.}}

====Local====

Local variables can be used throughout the same script file.

<syntaxhighlight lang="cpp">
void SetLocalVarInt(string& asName, int alVal);
void AddLocalVarInt(string& asName, int alVal);
int GetLocalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string& asName, float afVal);
void AddLocalVarFloat(string& asName, float afVal);
float GetLocalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string& asName, const string& asVal);
void AddLocalVarString(string& asName, string& asVal);
string& GetLocalVarString(string& asName);
</syntaxhighlight>

====Global====

Global variables can be used throughout several maps and can be accessed by several script files.

<syntaxhighlight lang="c++">
void SetGlobalVarInt(string& asName, int alVal);
void AddGlobalVarInt(string& asName, int alVal);
int GetGlobalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string& asName, float afVal);
void AddGlobalVarFloat(string& asName, float afVal);
float GetGlobalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string& asName, const string& asVal);
void AddGlobalVarString(string& asName, string& asVal);
string& GetGlobalVarString(string& asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string& asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS);
</syntaxhighlight>

Creates a particle system on an entity.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntityExt(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS,
float afR, float afG, float afB, float afA, bool abFadeAtDistance, float afFadeMinEnd, float afFadeMinStart,
float afFadeMaxStart, float afFadeMaxEnd);
</syntaxhighlight>

Creates a particle system on an entity, extended method with more options.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''abFadeAtDistance ''- determines whether a particle system fades from a certain distance on
#''afFadeMinEnd ''- minimum distance at which the particle system stops fading
#''afFadeMinStart ''- minimum distance at which the particle system starts fading
#''afFadeMaxStart ''- maximum distance at which the particle system starts fading
#''afFadeMaxEnd ''- maximum distance at which the particle system stops fading
<syntaxhighlight lang="c++">
void DestroyParticleSystem(string& asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string& asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load. Extension: .snt
<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string& asSoundName, string& asSoundFile, string& asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound on an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use + extension .snt
#''asEntity ''- the entity to create the sound at, can be "Player"
#''afFadeTime ''- time in seconds the sound needs to fade. Avoids enemies hearing the sound if afFadeTime is at least 0.1f
#''abSaveSound ''- if ''true'', a looping sound will "remember" its playback state (currently playing/stopped), and that state will be restored the next time the level is entered. If ''true'', the sound is never attached to the entity! Note that saving should only be used on ''looping sounds''!
<syntaxhighlight lang="c++">
void FadeInSound(string& asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- ?
<syntaxhighlight lang="c++">
void StopSound(string& asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediatly stop the sound
<syntaxhighlight lang="c++">
void PlayMusic(string& asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music to play + extension .ogg
#''abLoop ''- determines whether a music track should loop
#''afVolume ''- volume of the music
#''afFadeTime ''- time in seconds until music reaches full volume
#''alPrio ''- priority of the music. Note that only the music with the highest priority can be heard! 0 - lowest, 1 - higher, etc.
#''abResume'' - if ''true'', playback will be continued from where the track stopped after the call to StopMusic(); if ''false'', the track will be restarted.
<syntaxhighlight lang="c++">
void StopMusic(float afFadeTime, int alPrio);
</syntaxhighlight>

Stops music.

#''afFadeTime ''- time in seconds until music stops
#''alPrio ''- the priority of the music that should stop
<syntaxhighlight lang="c++">
void FadeGlobalSoundVolume(float afDestVolume, float afTime);
</syntaxhighlight>

Influences the global sound volume, that means everything you can hear '''from the world'''. This does not affect music of GUI sounds.

#''afDestVolume ''- desired volume
#''afTime ''- time in seconds until volume reaches desired volume
<syntaxhighlight lang="c++">
void FadeGlobalSoundSpeed(float afDestSpeed, float afTime);
</syntaxhighlight>

Influences the global sound speed.

#''afDestSpeed ''- desired speed
#''afTime ''- time in seconds until volume reaches desired speed

===Lights===

<syntaxhighlight lang="c++">
void SetLightVisible(string& asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string& asLightName, float afR, float afG, float afB, float afA, float afRadius, float afTime);
</syntaxhighlight>

Changes the properties of a light.

#''asLightName ''- internal name
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''afRadius ''- radius of the light. -1 means keeping the radius
#''afTime ''- time in seconds until change is done
<syntaxhighlight lang="c++">
void SetLightFlickerActive(string& asLightName, bool abActive);
</syntaxhighlight>

Activates flickering on a light.

#''asLightName'' - The internal light name
#''abActive'' - true = active, false = inactive

==Game scripts==

===General===

<syntaxhighlight lang="c++">
void StartCredits(string& asMusic, bool abLoopMusic, string& asTextCat, string& asTextEntry, int alEndNum);
</syntaxhighlight>

Starts the end credits screen.

#''asMusic ''- the music to play (including .ogg)
#''abLoopMusic ''- determines whether the music should loop
#''asTextCat ''- the category to be used in the .lang file
#''asTextEntry ''- the entry in the .lang file
#''alEndNum ''- Amnesia has 3 different endings and displays a code at the bottom. Determines which code is displayed. 0-2 will display codes, any other integer will not.
<syntaxhighlight lang="c++">
void StartDemoEnd();
</syntaxhighlight>

Starts the end images that are used in the demo, images are named "demo_end01.jpg", increase the number for each image you want to use. (NEEDS VERIFICATION)

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Save the game to the auto save.

<syntaxhighlight lang="c++">
void CheckPoint (string& asName, string& asStartPos, string& asCallback, string& asDeathHintCat, string& asDeathHintEntry);
</syntaxhighlight>

Sets a checkpoint at which the player will respawn in case he dies. Callback syntax: <code>void MyFunc(string &in asName, int alCount)</code> Count is 0 on the first checkpoint load!

#''asName ''- the internal name
#''asStartPos ''- the name of the StartPos in the editor
#''asCallback ''- the function to call when the player dies/respawns
#''asDeathHintCat ''- the category of the death hint message to be used in the .lang file
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string& asMapName, string& asStartPos, string& asStartSound, string& asEndSound);
</syntaxhighlight>

Immediatly loads another map.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos on the next map
#''asStartSound ''- the sound that is played when the change starts
#''asEndSound ''- the sound that is played when the new map is loaded
<syntaxhighlight lang="c++">
void ClearSavedMaps();
</syntaxhighlight>

Clears the "history" of the save, useful to do when you know the player will not be able to go back anymore. Makes the next save much smaller in size.

<syntaxhighlight lang="c++">
void CreateDataCache();
void DestroyDataCache();
</syntaxhighlight>

This caches all current textures and models and they are not released until destroy is called. If there is already cached data it is destroyed.
Create caches to enable faster loading when going back to a map. Destroy the cache if you know the player won't go back to that map.

<syntaxhighlight lang="c++">
void SetMapDisplayNameEntry(string& asNameEntry);
</syntaxhighlight>

Sets the map name shown in save file names. If none is set NULL is assumed.

#''asNameEntry ''- the entry to display, category must be "Levels"!
<syntaxhighlight lang="c++">
void SetSkyBoxActive(bool abActive);
</syntaxhighlight>

Enables/Disables the skybox.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetSkyBoxTexture(string& asTexture);
</syntaxhighlight>

Sets the texture of the skybox.

#''asTexture'' - The texture file to set. Extension: .dds
<syntaxhighlight lang="c++">
void SetSkyBoxColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the solid color of the skybox rather than a texture.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogActive(bool abActive);
</syntaxhighlight>

Enables/Disables the global fog.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetFogColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the color to use for the global fog.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogProperties(float afStart, float afEnd, float afFalloffExp, bool abCulling);
</syntaxhighlight>

Sets the properties for the global fog.

#''afStart ''- how many meters from the camera should the fog begin
#''afEnd ''- how many meters from the camera should the fog reach full thickness
#''afFalloffExp ''- the amount by which the thinkness increases
#''abCulling ''- whether occlusion culling is active for the fog; this prevents objects behind the fog from being loaded
<syntaxhighlight lang="c++">
void SetupLoadScreen(string&asTextCat, string&asTextEntry, int alRandomNum, string&asImageFile);
</syntaxhighlight>

Determines which loading screen will be shown when changing maps.

#''asTextCat ''- the category of the loading text in the .lang file to be shown on the loading screen
#''asTextEntry ''- the entry in the .lang file
#''alRandomNum ''- if greater 1, then it will randomize between 1 and alRandom for each LoadScreen giving entry the suffix XX (eg 01). If < =1 then no suffix is added
#''asImageFile ''- the image to be shown (optional)

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string& asName, float afTime, string& asFunction);
</syntaxhighlight>

Creates a timer which calls a function when it expires. Callback syntax: <code>void MyFunc(string &in asTimer)</code>

#''asName ''- the name of the timer
#''afTime ''- time in seconds
#''asFunction ''- the function to call
<syntaxhighlight lang="c++">
void RemoveTimer(string& asName);
</syntaxhighlight>

Removes a timer, no matter how much time is left.

#''asName'' - the internal name of the timer.
<syntaxhighlight lang="c++">
float GetTimerTimeLeft(string& asName);
</syntaxhighlight>

Returns the time left on a timer.

#''asName'' - the internal name of the timer.

===Screen Effects===

<syntaxhighlight lang="c++">
void FadeOut(float afTime);
</syntaxhighlight>

Fades the screen to black.

''afTime ''- time in seconds until the screen is completly black

<syntaxhighlight lang="c++">
void FadeIn(float afTime);
</syntaxhighlight>

Fades the screen back to normal.

''afTime ''- time in seconds until the screen back to normal

<syntaxhighlight lang="c++">
void FadeImageTrailTo(float afAmount, float afSpeed);
</syntaxhighlight>

Applies the image trail effect to the screen.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeSepiaColorTo(float afAmount, float afSpeed);
</syntaxhighlight>

Makes the screen go dark red.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeRadialBlurTo(float afSize, float afSpeed);
</syntaxhighlight>

Applies radial blur effects to the screen.

''afSize ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void SetRadialBlurStartDist(float afStartDist);
</syntaxhighlight>

Determines at which distance the radial blur effects appear.

''afStartDist ''- the distance at which the effect starts

<syntaxhighlight lang="c++">
void StartEffectFlash(float afFadeIn, float afWhite, float afFadeOut);
</syntaxhighlight>

Fades the screen to white.

''afFadeIn ''- time in seconds until screen is white ''afWhite ''- determines to which percentage the screen fades to white (1.0 = completly white) ''afFadeOut ''- time in seconds until screen is back to normal again

<syntaxhighlight lang="c++">
void StartEffectEmotionFlash(string& asTextCat, string& asTextEntry, string& asSound);
</syntaxhighlight>

Fades the screen to white and shows a text message.

''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''asSound ''- the sound to play while fading

<syntaxhighlight lang="c++">
void AddEffectVoice(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry,
bool abUsePosition, string& asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an effect to be played. It is okay to call this many times in order to play many voices in a row. The EffectVoiceOverCallback is not called until ALL voices have finished.

''asVoiceFile ''- the voice to play ''asEffectFile ''- the effect to play ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''abUsePosition ''- plays using 3D from the entity, or without 3D ''asPosEntity ''- the entity at which the effect appears ''afMinDistance ''- minimum distance to see the effect ''afMaxDistance ''- maximum distance to see the effect

<syntaxhighlight lang="c++">
void StopAllEffectVoices(float afFadeOutTime);
</syntaxhighlight>

Stops all voices and calls the EffectVoiceOverCallback.

<syntaxhighlight lang="c++">
bool GetEffectVoiceActive();
</syntaxhighlight>

Checks whether EffectVoices are still active.

<syntaxhighlight lang="c++">
void SetEffectVoiceOverCallback(string& asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<syntaxhighlight lang="c++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string& asSPSFile);
void StopPlayerSpawnPS();
</syntaxhighlight>

Continuously spawn regular particle systems (''.ps'') around the player. Particles created by this script carry over from map to map. ''asSPSFile'' - the ''.sps'' file to use. Exemplary ''.sps'' files are located in the ''/misc'' folder in the main game directory. Custom ''.sps'' files can be created by hand in a text editor (see existing ones and mimic how those are written). Since ''StopPlayerSpawnPS()'' doesn't seem to work, to stop an SPS you must create an ''.sps'' file with an empty particle field field and override the old SPS by calling ''StartPlayerSpawnPS'' again.

<syntaxhighlight lang="c++">
void PlayGuiSound(string& asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

''asSoundFile ''- the sound to play (extension is .snt) ''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void StartScreenShake(float afAmount, float afTime, float afFadeInTime, float afFadeOutTime);
</syntaxhighlight>

Shakes the screen.

''afAmount ''- intensity of the shake ''afTime ''- duration of the shake ''afFadeInTime ''- time in seconds until full intensity is reached ''afFadeOutTime ''- time until screen is back to normal

<syntaxhighlight lang="c++">
void SetInDarknessEffectsActive(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the sanity drain and night vision effects while in the darkness.

''bool abX'' - Enable/disable effects.

<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

{{ReqVer|1.5}}

Displays an image file directly onto the screen.

''asImageName'' - The image file to render (.jpg, .png, .tga, .dds)

''afX'' - The X position of the image

''afY'' - The Y position of the image

''afScale'' - The scale of the image (default 1.0f)

''abUseRelativeCoordinates'' - Whether or not to use relative coordinates for positioning. Use false for absolute.

''afDuration'' - The duration that the image is displayed for.

''afFadeIn'' - The time, in seconds, to fade in the image.

''afFadeOut'' - The time, in seconds, to fade out the image.

===Insanity===

<syntaxhighlight lang="c++">
void SetInsanitySetEnabled(string& asSet, bool abX);
</syntaxhighlight>

Determines which InsanitySets are enabled.

''asSet ''- the set ''abX ''- enabled or not

<syntaxhighlight lang="c++">
void StartInsanityEvent(string &in asEventName);
</syntaxhighlight>

{{ReqVer|1.3}}

Starts a specified insanity event.

''asEventName ''- Insanity event to play.

<syntaxhighlight lang="c++">
void StartRandomInsanityEvent();
</syntaxhighlight>

Starts a random insanity event from the available sets.

<syntaxhighlight lang="c++">
void StopCurrentInsanityEvent();
</syntaxhighlight>

{{ReqVer|1.3}}

Stops the currently playing insanity event.

<syntaxhighlight lang="c++">
void InsanityEventIsActive();
</syntaxhighlight>

Checks whether an insanity event is currently in effect… Or so it was supposed to be, but as it doesn't return a value, we can never know [http://wiki.frictionalgames.com/lib/images/smileys/icon_smile.gif?nolink&15x15]

===Player===

Note that the player's maximum health and sanity is 100.

<syntaxhighlight lang="c++">
void SetPlayerActive(bool abActive);
</syntaxhighlight>

Enabled/Disable player controlled movement.

<syntaxhighlight lang="c++">
void ChangePlayerStateToNormal();
</syntaxhighlight>

Sets certain effects back to normal. It can for example make the player drop an item.

<syntaxhighlight lang="c++">
void SetPlayerCrouching(bool abCrouch);
</syntaxhighlight>

Forces the player to crouch.

<syntaxhighlight lang="c++">
void AddPlayerBodyForce(float afX, float afY, float afZ, bool abUseLocalCoords);
</syntaxhighlight>

Pushes the player into a certain direction. Note that you need values above ~2000 to see any effects.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''abUseLocalCoords ''- If true, axes are based on where the player is facing, not the world.

<syntaxhighlight lang="c++">
void ShowPlayerCrossHairIcons(bool abX);
</syntaxhighlight>

Enables/Disables the icons when a player has something in focus.

<syntaxhighlight lang="c++">
void SetPlayerSanity(float afSanity);
void AddPlayerSanity(float afSanity);
float GetPlayerSanity();
</syntaxhighlight>

Modifies/returns the sanity of the player.

<syntaxhighlight lang="c++">
void SetPlayerHealth(float afHealth);
void AddPlayerHealth(float afHealth);
float GetPlayerHealth();
</syntaxhighlight>

Modifies/returns the health of the player.

<syntaxhighlight lang="c++">
void SetPlayerLampOil(float afOil);
void AddPlayerLampOil(float afOil);
float GetPlayerLampOil();
</syntaxhighlight>

Modifies/returns the lamp oil of the player.

<syntaxhighlight lang="c++">
float GetPlayerSpeed();
float GetPlayerYSpeed();
</syntaxhighlight>

Returns the current speed of the player.

<syntaxhighlight lang="c++">
void SetSanityDrainDisabled(bool abX);
</syntaxhighlight>

Enables/Disables sanity drain from darkness, monsters, etc.

<syntaxhighlight lang="c++">
void GiveSanityBoost();
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a fixed amount.

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

''afAmount ''- amount of sanity damage done ''abUseEffect ''- determines whether an effect is played when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string& asType, bool abSpinHead, bool abLethal);
</syntaxhighlight>

Reduces the health of the player.

''afAmount ''- amount of damage done to health ''asType ''- plays a certain effect on the screen when the damage is dealt (BloodSplat, Claws or Slash) ''abSpinHead ''- changes the camera view when damage is dealt ''abLethal ''- set to true if player can die from given damage

<syntaxhighlight lang="c++">
void FadePlayerFOVMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the field of view of the player. A shorter FOV will create a zoom effect.

''afX ''- multiplier of default FOV (1 is default) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerAspectMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the aspect ratio of the player. Basically stretches or narrows the screen horizontally.

''afX ''- multiplier of default aspect (default is 1) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerRollTo(float afX, float afSpeedMul, float afMaxSpeed);
</syntaxhighlight>

Rotates the position of the camera on the player's body.

''afX ''- angle of rotation of head, positive being counter-clockwise ''afSpeedMul ''- speed (possibly acceleration) multiplier of the rotation (default 1, which is really slow) ''afMaxSpeed ''- maximum speed of rotation

<syntaxhighlight lang="c++">
void MovePlayerHeadPos(float afX, float afY, float afZ, float afSpeed, float afSlowDownDist);
</syntaxhighlight>

Changes the position of the camera on the player's body.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''afSpeed ''- speed at which the change happens ''afSlowDownDist ''- distance at which to start slowing down (prevents the head from abruptly stopping)

<syntaxhighlight lang="c++">
void StartPlayerLookAt(string& asEntityName, float afSpeedMul, float afMaxSpeed, string& asAtTargetCallback);
void StopPlayerLookAt();
</syntaxhighlight>

Forces the player to look at a certain entity until StopPlayerLookAt is used.

''asEntityName ''- the entity to look at ''afSpeedMul ''- how fast should the player look at the entity ''afMaxSpeed ''- maximum speed allowed ''asAtTargetCallback ''- function to call when player looks at target

<syntaxhighlight lang="c++">
void SetPlayerMoveSpeedMul(float afMul);
void SetPlayerRunSpeedMul(float afMul);
void SetPlayerLookSpeedMul(float afMul);
</syntaxhighlight>

Changes the player's move/run/look speed. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpForceMul(float afMul);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the player's jump multiplier. Higher values = higher jumps. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpDisabled(bool abX);
void SetPlayerCrouchDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to jump/crouch.

<syntaxhighlight lang="c++">
void TeleportPlayer(string& asStartPosName);
</syntaxhighlight>

Instantly teleports the player to the target StartPos.

<syntaxhighlight lang="c++">
void SetLanternActive(bool abX, bool abUseEffects);
</syntaxhighlight>

Makes the player use his lantern.

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player currently uses his lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use his lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string& asCallback);
</syntaxhighlight>

Sets the function to call when the player uses his lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Displays a message on the screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- determines how long the message is displayed. If time is < =0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void SetDeathHint(string& asTextCategory, string& asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="c++">
void DisableDeathStartSound();
</syntaxhighlight>

Disables the death sound when the player dies. This must be called directly before player is killed! The variable as soon as player dies too.

<syntaxhighlight lang="">
void MovePlayerForward(float afAmount)
</syntaxhighlight>

"REQUIRES THE 1.2 PATCH: JUSTINE" Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<syntaxhighlight lang="c++">
void SetPlayerFallDamageDisabled(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the player's ability to take fall damage.

<syntaxhighlight lang="c++">
void SetPlayerPos(float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the player's position within the level.

''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c++">
float GetPlayerPosX();
float GetPlayerPosY();
float GetPlayerPosZ();
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the player's position within the level on the specified axis.

===Journal===

<syntaxhighlight lang="c++">
void AddNote(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a note to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _Name and _Text and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void AddDiary(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a diary to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _NameX and _TextY whereas X and Y are numbers of the parts (_Name1: first diary, _Text1: first page) and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void ReturnOpenJournal(bool abOpenJournal);
</syntaxhighlight>

Only called in the pickup diary callback! If true the journal displays the entry else not.

===Quests===

<syntaxhighlight lang="c++">
void AddQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos.

''asName ''- the internal name to be used ''asNameAndTextEntry ''- entry in the .lang file. Must start with "Quest_<texthere>_Text”, and be in category “Journal”!

<syntaxhighlight lang="c++">
void CompleteQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Completes a quest.

''asName ''- the internal name of the quest ''asNameAndTextEntry ''- entry in the .lang file. Must start with " Quest_<texthere>_Text ”, and be in category “Journal”!

<syntaxhighlight lang="c++">
bool QuestIsCompleted(string& asName);
bool QuestIsAdded(string& asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map.

''alNumberOfQuests ''- Amount of Quests

<syntaxhighlight lang="c++">
void GiveHint(string& asName, string& asMessageCat, string& asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

''asName ''- the internal name ''asMessageCat ''- the category in the .lang file ''asMessageEntry ''- the entry in the .lang file ''afTimeShown ''- time in seconds until the message disappears. If time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void BlockHint(string& asName);
void UnBlockHint(string& asName);
void RemoveHint(string& asName);
</syntaxhighlight>

Blocking a hint prevents it from being shown.
"Removing" a hint actually removes it from the list of already given hints, thus allowing it to show up again.

''asName ''- the internal name. Basic game hints use the same name as their respective lang entries, with the exception of "numbered" hints. For example, <code>EntityGrab</code> blocks the <code>EntityGrab01</code> and <code>EntityGrab02</code> entries.

===Inventory===

<syntaxhighlight lang="c++">
void ExitInventory();
</syntaxhighlight>

Exits the inventory by force.

<syntaxhighlight lang="c++">
void SetInventoryDisabled(bool abX);
</syntaxhighlight>

Disables the player's ability to open his inventory.

<syntaxhighlight lang="c++">
void SetInventoryMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Adds a message at the bottom of the inventory screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- time in seconds until the message disappears. If life time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void GiveItem(string& asName, string& asType, string& asSubTypeName, string& asImageName, float afAmount);
</syntaxhighlight>

Adds an item to the inventory of the player. Note that the item does not have to exist as entity in the world to be able to do this.

''asName ''- internal name ''asType ''- item type to give, Available types are: 

*Puzzle
*Lantern
*Health
*Sanity
*LampOil
*Tinderbox

''asSubTypeName ''- item name for .lang file ''asImageName ''- the image which will appear in inventory. For example: <code>void GiveItem("chemical_container_full_1", "Puzzle", "chemical_container_full", "chemical_container_full.tga", 1);</code> will use the image from <code>graphics/item/chemical_container_full.tga</code>

''afAmount ''- amount the item gives, - For example: Oil potions will fill the oil meter by this amount, Health potions will heal by this amount, etc.

<syntaxhighlight lang="c++">
void RemoveItem(string& asName);
</syntaxhighlight>

Removes an item from the player's inventory.

<syntaxhighlight lang="c++">
bool HasItem(string& asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

<syntaxhighlight lang="c++">
void GiveItemFromFile(string& asName, string& asFileName);
</syntaxhighlight>

Adds a single item to the player's inventory. This is meant to be used for debug mostly as it creates the actual item and then destroys it.

''asName ''- internal name ''asFileName ''- item to give + extension (.ent)

<syntaxhighlight lang="c++">
void AddCombineCallback(string& asName, string& asItemA, string& asItemB, string& asFunction, bool abAutoRemove);
</syntaxhighlight>

Allows the player to combine items in his inventory. Callback syntax: <code>void MyFunc(string &in asItemA, string &in asItemB)</code>

''asName ''- internal name for the callback ''asItemA ''- internal name of first item ''asItemB ''- internal name of second item ''asFunction ''- the function to call ''abAutoRemove ''- determines whether the callback should be removed when the items are combined

<syntaxhighlight lang="c++">
void RemoveCombineCallback(string& asName);
</syntaxhighlight>

Removes a combine callback. ''asName'' - the internal name of the callback to be removed (as specified in AddCombineCallback)

<syntaxhighlight lang="c++">
void AddUseItemCallback(string& asName, string& asItem, string& asEntity, string& asFunction, bool abAutoDestroy);
</syntaxhighlight>

Allows the player to use items on the world. Callback syntax: <code>void MyFunc(string &in asItem, string &in asEntity)</code>

''asName ''- internal name ''asItem ''- internal name of the item ''asEntity ''- entity to be able to use the item on ''asFunction ''- function to call ''abAutoDestroy ''- determines whether the item is destroyed when used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string& asName);
</syntaxhighlight>

Removes an item callback.

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string& asName, bool abActive);
</syntaxhighlight>

Activates/deactivates an entity.

<syntaxhighlight lang="c">
void SetEntityVisible(string &in asName, bool abVisible);
</syntaxhighlight>

{{ReqVer|1.3}}

Activates/deactivates an entity's visual mesh. The collision body remains.

''asName'' - Name of the entity. ''abActive'' - Activate/deactivate mesh.

<syntaxhighlight lang="c">
bool GetEntityExists(string& asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string& asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

''asName ''- internal name ''asCrossHair ''- desired crosshair, can be: Default (uses default), Grab, Push, Ignite, Pick, LevelDoor, Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string& asEntityName, string& asEntityFile, string& asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes(using for example ShowEnemyPlayerPosition).

''asEntityName ''- internal name ''asEntityFile ''- entity to be used extension .ent ''asAreaName ''- the area to create the entity at ''abFullGameSave ''- determines whether an entity "remembers" its state

<syntaxhighlight lang="c">
void ReplaceEntity(string &in asName, string &in asBodyName, string &in asNewEntityName, string &in asNewEntityFile, bool abFullGameSave);
</syntaxhighlight>

{{ReqVer|1.3}}

Removes an entity and places a new one in its place.

''asName'' - Name of the entity to replace. ''asBodyName'' - Name of the body of the entity to place the new entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''asNewEntityName'' - Name of the new entity. ''asNewEntityFile'' - Name of the new entity file. Extension .ent. ''abFullGameSave'' - Whether ALL properties of this entity should be saved throughout levels.

<syntaxhighlight lang="c++">
void PlaceEntityAtEntity(string &in asName, string &in asTargetEntity, string &in asTargetBodyName, bool abUseRotation);
</syntaxhighlight>

{{ReqVer|1.3}}

Places an entity at the position of another entity. Does not work for enemies, use TeleportEnemyToEntity instead.

''asName'' - Name of the entity to place. ''asTargetEntity'' - Name of the other entity to place the first entity at. ''asTargetBodyName'' - Name of the body of the entity to place the first entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''abUseRotation'' - Whether the entity should be rotated like the target entity.

<syntaxhighlight lang="c">
void SetEntityPos(string &in asName, float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Moves an entity to a position in the level.

''asName'' - Name of the entity to move. ''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c">
float GetEntityPosX(string &in asName);
float GetEntityPosY(string &in asName);
float GetEntityPosZ(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns an entity's position in the level on the specified axis.

''asName'' - Name of the entity.

<syntaxhighlight lang="c">
void SetEntityPlayerLookAtCallback(string& asName, string& asCallback, bool abRemoveWhenLookedAt);
</syntaxhighlight>

Calls a function when the player looks at a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code> alState: 1 = looking, -1 = not looking

''asName ''- internal name ''asCallback ''- function to call ''abRemoveWhenLookedAt ''- determines whether the callback should be removed when the player looked at the entity

<syntaxhighlight lang="c">
void SetEntityPlayerInteractCallback(string& asName, string& asCallback, bool abRemoveOnInteraction);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity)</code>

''asName ''- internal name ''asCallback ''- function to call ''abRemoveOnInteraction ''- determines whether the callback should be removed when the player interacts with the entity

<syntaxhighlight lang="c">
void SetEntityCallbackFunc(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in type)</code> Type depends on entity type and includes: "OnPickup", "Break", "OnIgnite", etc

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string& asName, string& asCallback);
</syntaxhighlight>

A callback called when ever the connection state changes (button being switched on, lever switched, etc). Callback syntax: <code>void Func(string &in asEntity, int alState)</code> alState: -1 = off, 0 = between, 1 = on

<syntaxhighlight lang="c">
void SetEntityInteractionDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string& asName);
</syntaxhighlight>

Breaks a joint. Do not use this on joints in SwingDoors, Levers, Wheels, etc. where the joint is part of an interaction. That will make the game crash.

<syntaxhighlight lang="c">
void AddEntityCollideCallback(string& asParentName, string& asChildName, string& asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entites collide. Callback syntax: <code>void MyFunc(string &in asParent, string &in asChild, int alState)</code> alState: 1 = enter, -1 = leave

''asParentName ''- internal name of main object ''asChildName ''- internal name of object that collides with main object (asterix (<nowiki>*</nowiki>) NOT supported!) ''asFunction ''- function to call ''abDeleteOnCollide ''- determines whether the callback after it was called ''alStates ''- 1 = only enter, -1 = only leave, 0 = both

<syntaxhighlight lang="c">
void RemoveEntityCollideCallback(string& asParentName, string& asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string& asEntityA, string& asEntityB);
</syntaxhighlight>

Checks whether two entites collide. This function does NOT support asterix (<nowiki>*</nowiki>) or "Player"!

<syntaxhighlight lang="c">
void SetBodyMass(string &in asName, float afMass);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to set.

<syntaxhighlight lang="c">
float GetBodyMass(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to get.

====Props====

<syntaxhighlight lang="c">
void SetPropEffectActive(string& asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Can be used on coal to give it the black color it should have.

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string& asName, bool abActive, float afFadeTime);
</syntaxhighlight>

Activates/deactivates a prop.

''asName ''- internal name ''abActive ''- nothing to add ''afFadeTime ''- time in seconds until prop fully fades

<syntaxhighlight lang="c">
void SetPropStaticPhysics(string& asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string& asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string& asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string& asOffsetArea);
</syntaxhighlight>

Rotates the prop up to a set speed.

''asName ''- internal name ''afAcc ''- acceleration ''afGoalSpeed ''- desired speed ''afAxisX ''- rotation around X axis ''afAxisY ''- rotation around Y axis ''afAxisZ ''- rotation around Z axis ''abResetSpeed ''- determines whether the speed is resetted after goal speed is reached ''asOffsetArea ''- the area to rotate around, if empty, then the center of the body is used Note: The entity you want to rotate MUST be a "StaticObject" entity!

<syntaxhighlight lang="cpp">
void StopPropMovement(string& asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

a''sPropName''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

{{bug|''afRotZ '' is used for both the ZX rotation and the Z position of the attached prop. Unwanted rotation can be avoided by using: ''AddAttachedPropToProp(asPropName, asAttachName, asAttachFile, afPosX, afPosY, '''0''', afPosZ, '''90.0f''', afPosZ)''}}

{{bug|Attaching a breakable prop to a physically active prop, and then breaking the attached prop, will cause the game to crash, should the parent object be moved or reset.}}

<syntaxhighlight lang="cpp">
void AttachPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Attaches a prop to another prop. Fixed version of AddAttachedPropToProp.

''asPropName ''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

<syntaxhighlight lang="cpp">
void RemoveAttachedPropFromProp(string& asPropName, string& asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string& asName, float afHealth);
void AddPropHealth(string& asName, float afHealth);
float GetPropHealth(string& asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string& asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string& asProp, string& asAnimation, float afFadeTime, bool abLoop, string& asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function. Callback syntax: <code>void MyFunc(string &in asProp)</code>

''asProp ''- internal name of the prop ''asAnimation ''- animation to play ''afFadeTime ''- ? ''abLoop ''- determines whether the animation loops ''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddPropImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
</syntaxhighlight>

These functions push objects. Note that rather high values are needed when applying ''forces'' (on the order of ~100 (weak) to ~10000 (strong)), but not impulses (values less than 10 can be appropriate). Forces are external influences, and will have different effect depending on the mass of the object they are being applied to; impulses disregard mass, and can cause objects to break, as if hit. A "Body" is a physics-related helper object, to which a force or an impulse can be applied. Entities can consist of several bodies, interconnected in various ways (you can create/examine bodies in the model editor).

''asName ''- the object to push; for bodies, use this format: "''entityName''_''bodyName''" ''afX ''- magnitude along the X-axis ''afY ''- magnitude along the Y-axis ''afZ ''- magnitude along the Z-axis ''asCoordSystem ''- determines which coordinate system is used, usually "world" All of these functions are ''additive'' - when called consecutively, for each call, the vectors defined by (afX, afY, afZ) will be added together, and a resultant force/impulse will be calculated ''before'' any physics simulation is applied to the target object.

====Connections====

<syntaxhighlight lang="cpp">
void InteractConnectPropWithRope(string& asName, string& asPropName, string& asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (ie. turn wheel to move rope).

''asName ''- connection name ''asPropName ''- name of prop ''asRopeName ''- name of rope ''abInteractOnly ''- ? ''afSpeedMul ''- speed multiplier of how quickly the rope moves ''afToMinSpeed ''- the slowest the rope will move when moving the prop ''afToMaxSpeed ''- the fastest the rope will move when moving the prop ''abInvert ''- whether to invert the direction the rope moves ''alStatesUsed ''- which states of the prop can interact with the rope?

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string& asName, string& asPropName, string& asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondance to prope "amount" and the moveobject open amount. It is best used for Wheel-door connections!

<syntaxhighlight lang="cpp">
void ConnectEntities(string& asName, string& asMainEntity, string& asConnectEntity, bool abInvertStateSent, int alStatesUsed, string& asCallbackFunc);
</syntaxhighlight>

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> State is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string& asName, bool abLit, bool abEffects);
</syntaxhighlight>

(Un)lits a lamp.

''asName ''- Name of the lamp ''abLit ''- Set true if you want the lamp to be lit, set to false if you want the lamp to be unlit ''abEffects ''- If you want to have the lamp fade in/out when it gets (un)lit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string& asName, bool abLocked, bool abEffects);
void SetSwingDoorClosed(string& asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Locks/closes a swing door.

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string& asName);
bool GetSwingDoorClosed(string& asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string& asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string& asName);
</syntaxhighlight>

Returns an integer depending on how far the door is opened. -1 = angle is close to 0°, 1 = angle is 70% or higher of max, 0 = inbetween -1 and 1.

<syntaxhighlight lang="cpp">
void SetLevelDoorLocked(string& asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string& asName, string& asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string& asName, string& asTextCat, string& asTextEntry);
</syntaxhighlight>

Displays a message when interacting with a locked level door.

''asName ''- internal name ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="cpp">
void SetMoveObjectState(string& asName, float afState);
</syntaxhighlight>

Moves an object to a certain state.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween (and above, for example, the bridge_metal_vert) are valid too!

<syntaxhighlight lang="cpp">
void SetMoveObjectStateExt(string& asName, float afState, float afAcc, float afMaxSpeed, float afSlowdownDist, bool abResetSpeed);
</syntaxhighlight>

Moves an object to a certain state, extended method.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween are valid too! ''afAcc ''- acceleration ''afMaxSpeed ''- maximum speed ''afSlowdownDist ''- Distance to the target state before decceleration occurs. ''abResetSpeed ''- Set to True if the prop's speed should be reset before performing the movement, else the prop will accelerate from it's current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string& asName, int alState);
void SetWheelStuckState(string& asName, int alState, bool abEffects);
void SetLeverStuckState(string& asName, int alState, bool abEffects);
</syntaxhighlight>

Makes a prop<nowiki>\</nowiki>wheel<nowiki>\</nowiki>lever stuck in a certain state.

''asName ''- internal name ''alState ''- 0 = not stuck, 1 = at max, -1 = at min ''abEffects ''- use effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string& asName, float afAngle, bool abAutoMove);
</syntaxhighlight>

Moves a wheel to a certain angle.

''asName ''- internal name ''afAngle ''- angle ''abAutoMove ''- determines whether the wheel should move on its own

<syntaxhighlight lang="cpp">
void SetWheelInteractionDisablesStuck(string& asName, bool abX);
void SetLeverInteractionDisablesStuck(string& asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string& asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string& asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when state changes. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code>

<syntaxhighlight lang="cpp">
void SetButtonSwitchedOn(string& asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entites to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string& asAreaName, string& asProp);
void AttachBodyToStickyArea(string& asAreaName, string& asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string& asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====Enemies====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string& asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Activates the npc

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string& asName, bool abX);
</syntaxhighlight>

Sets an NPC's head to follow the player's movement's.

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string& asName, bool abX);
</syntaxhighlight>

Makes an enemy a hallucination. Hallucinations fade to smoke when they get near the player.

<syntaxhighlight lang="cpp">
void FadeEnemyToSmoke(string& asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string& asName);
</syntaxhighlight>

Makes the enemy run to the player, no matter where he is.

<syntaxhighlight lang="cpp">
void AlertEnemyOfPlayerPresence(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gives the specified enemy the player's current position and makes it search the area.

<syntaxhighlight lang="cpp">
void SetEnemyDisableTriggers(string& asName, bool abX);
</syntaxhighlight>

Enables or disables enemy triggers. If disabled, enemy will not react to player or attack.

<syntaxhighlight lang="cpp">
void AddEnemyPatrolNode(string& asName, string& asNodeName, float afWaitTime, string& asAnimation);
</syntaxhighlight>

Adds a patrol node to the enemy's path.

''asName ''- internal name of the enemy ''asNodeName ''- path node ''afWaitTime ''- time in seconds that the enemy waits at the path node before continuing ''asAnimation ''- the animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string& asEnemyName);
</syntaxhighlight>

Clears the current path of patrol nodes of the enemy.

<syntaxhighlight lang="cpp">
void SetEnemySanityDecreaseActive(string &in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether an enemy activates the player's sanity drain when stared at.

''asName ''- Internal name of the enemy ''abX ''- Enabled/disabled

<syntaxhighlight lang="cpp">
void TeleportEnemyToNode(string &in asEnemyName, string &in asNodeName, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific PathNode.

''asEnemyName ''- Internal name of the enemy ''asNodeName ''- Internal name of the node to teleport to ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="cpp">
void TeleportEnemyToEntity(string &in asEnemyName, string &in asTargetEntity, string &in asTargetBody, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific entity.

''asEnemyName ''- Internal name of the enemy ''asTargetEntity ''- Internal name of the entity to teleport to ''asTargetBody''- Internal name of the entity's body name to teleport to. If empty, the first body will be used (might be unstable, recommended to input a body anyway) ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="c">
void ChangeManPigPose(string&in asName, string&in asPoseType);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the pose a specified ManPig.

''asName ''- Internal name of the enemy ''asPoseType''- Name of the ManPig pose to use. Can be "Biped" or "Quadruped"

<syntaxhighlight lang="c">
void SetTeslaPigFadeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should fade the player's view in and out.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigSoundDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should play the proximity sounds.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigEasyEscapeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should be easier to escape from when hunted.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string&in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a TeslaPig to be visible for a short time.

''asName ''- Internal name of the enemy

<syntaxhighlight lang="c">
string& GetEnemyStateName(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the name of the state a specified enemy is current in. States can be Hunt, Search, Patrol, Wait, Alert, Investigate, Track and BreakDoor.

''asName ''- Internal name of the enemy

HPL2/Tools/Level Editor/Combine Editmode

2023-09-14T12:53:24Z

Darkfire: /* Testing */ remove a silly adjective

= Combine EditMode =
This mode is used to create combinations of static geometry (combos).

{{warning|This feature is essentially useless - see the testing section. The following statement is kept for archival purposes.}}

It is useful for optimising, as it creates groups of static geometry that will be loaded by the engine as a whole.

[[File:combineeditmodewin.jpg|right]]
* '''Show all combos''': when enabled, all created combos will be displayed.
* '''Combinations''': this ComboBox is used to pick the currently edited combo.
* '''Add/Rem''' buttons: used to add a new combo / remove the currently edited combo.
* '''Add/Remove|Toggle''' checkboxes: this selects the way the current combo will be edited. Moving the mouse on the viewport will highlight geometry objects.
**'''Add''': will add geometry objects to the combo when clicking on them.
**'''Remove''': will remove geometry objects from the combo when clicking on them (and they were part of the combo).
**'''Toggle''': will switch clicked objects between added or not added.
* '''Color''': this determines the tint that the objects in a combo will display.
* '''Geometry objects list''': will display a list of all the object names added to the currently edited combo.
[[File:combine02.jpg]]

==Use cases==
Combos were used only in the following maps:
*02_entrance_hall.map
*20_sewer.map (the combo contains only a single object)
*22_torture_chancel.map
*27_torture_chancel_redux.map
Except for the sewer, all cases are the only combos in the entire map. They were used to combine big rooms.

==Testing==

The feature was tested using the '''02_entrance_hall.map''' and '''22_torture_chancel.map''' maps. Tests were done on a laptop which runs the base game in about 24 FPS. Frame time statistics were measured using the MapViewer with and without the big combos.

'''There was no improvement in performance.''' The only noticeable change was the number of objects loaded into the viewer (which decreased, most likely by the number of objects in the combo).
The maps' load times didn't seem to be affected either. Considering the hardware used to run these tests, if the feature really improved performance, it would have been at least noticeable.

'''The conclusion of the test is that the feature is essentially useless - at least until proven otherwise.'''

HPL2/Changelog

2023-09-14T12:49:39Z

Darkfire: Elaborate on the cubemap fix

HPL2

2023-09-14T12:45:46Z

Darkfire: Add a link to the 1.5 update notes and small clean up

<div style="text-align:center;">
'''Welcome to the HPL2 documentation hub.''' Here you can find extensive documentation about the engine and the games below, including downloads for various tools and tutorials on how to create your own [[HPL2/TDD/Modding|custom stories]].
</div>

<div style="text-align:center;">
[[File:Hpl2 logo.png|250px|link=|HPL2]]
'''[[HPL2/Tools|Development Tools]] | [[HPL2/Troubleshooting|Troubleshooting]] | [https://wiki.frictionalgames.com/page/Special:PrefixIndex?prefix=HPL2%2F&namespace=0&hideredirects=1 All Pages]'''</div>
----

<div style="text-align:center;">

[[File:Note icon.png|frameless|link=]]
[[HPL2/1.5_Update | Notes about the 1.5 update]]


</div>

{{:HPL2/TDD}}

----

<div style="text-align:center;">

[[File:Note icon.png|frameless|link=]]
Because The Dark Descent and A Machine for Pigs are quite similar, most of the documentation from TDD applies to MFP.


</div>
{{:HPL2/AMFP}}

[[Category:Entry pages]]
[[Category:English]]

__NOTOC____NOEDITSECTION__

HPL2/Changelog

2023-09-14T12:09:05Z

Darkfire: Created

HPL2/TDD/Creating a Custom Story

2023-09-14T11:41:03Z

Darkfire: Add link to the config file article in the relevant place

{{TocRight}}
Creating a working custom story is a relatively simple process. This page will explain what you need to set up to do so, but it will not go into how you create engaging content as that is a much more invested topic.

To get started, browse to your Amnesia TDD installation directory. This is often called the ''Amnesia root directory'', and where it is located depends on the system and platform you are using. Here are some common locations:
{| class="wikitable"
|Steam @ Windows
|<code>C:\Program Files (x86)\Steam\steamapps\common\Amnesia The Dark Descent</code>
|-
|Retail @ Windows
|<code>C:\Program Files (x86)\Amnesia</code>
|-
|Steam @ Mac
|<code>~/Library/Application Support/Steam/steamapps/common/Amnesia The Dark Descent</code>
|}

==Setting up a custom story==
{{note|The simplest way of starting a Custom Story is downloading a [https://www.mediafire.com/file/m0yw9ro94yruzk6/Custom_Story.zip/file template]. The following tutorial will help with understanding what those files do.}}{{todo|Reupload the template to the wiki}}

Depending on your version, you may have a folder called "redist" inside your root directory. If you do, you will be working from inside this folder. If you do not have the "redist" folder, you will be working from the root directory itself.

#Navigate to <code>custom_stories/</code>
#Create a new folder for your custom story. This folder can be named pretty much anything, for example "My First Story".
#Enter your new folder and create a new plain text file named <code>custom_story_settings.cfg</code>. Open this file in your favorite code editor and paste in the following XML configuration:<syntaxhighlight lang="xml">
<Main
Name="My First Story"
Author="Lovecraft Himself"
ImgFile="cool_bg.png"

MapsFolder="maps/"
StartMap="level_01.map"
StartPos="PlayerStartArea_1"

ExtraLangFilePrefix="extra_"
DefaultExtraLangFile="english.lang"
/>
</syntaxhighlight>You can change any fields you like, for instance the name and author, but you may want to come back to this later. [[HPL2/custom_story_settings.cfg | See this article]] for a full explanation of this file and additional options that can be added.
[[File:Custom story empty example.png|alt=A bare minimum custom story configuration|thumb|A bare minimum custom story configuration]]

#The next requirement before the story will appear in the game's menu is a valid map file. Open the level editor and create a simple room – or at the very least create a floor using the Plane tool, place down a Box Light to cover the area, and place a PlayerStart area. Save the map file into <code>custom_stories/My First Story/maps/level_01.map</code>, or whatever matches the setup you've used. Don't forget to create the "maps" folder as it is written in your config file.
#At this point, if you launch Amnesia, your story should appear in the list of custom stories as seen in the image to the right. Feel free to test this to ensure everything works so far. If you click "Start" you should load into your level.
#Optional: Add the image file as specified by the <code>ImgFile</code>attribute above. Match the name and extension and place the file next to your config, and it should render as the background image in the game menu.

==Displaying text==
Now that you have a functional custom story, it's time to add some other essential files. In the image to the right you may notice it says "No description." This is the fallback text that appears if you do not have a functional language file, so let's create that now.

#Start by creating a new plain text file in your custom story folder named <code>extra_english.lang</code>.
#Open the language file. This is another XML file that stores ALL text that will be displayed in your story. This includes things like descriptions, pop-up text, notes, item names, level names etc. You can start by pasting in the following:<syntaxhighlight lang="xml">
<LANGUAGE>
<CATEGORY Name="CustomStoryMain">
<Entry Name="Description">Hello, this is the description of my story.</Entry>
</CATEGORY>
</LANGUAGE>
</syntaxhighlight>There are a few rules to keep in mind when it comes to this file:
##All text within this file is CASE SENSITIVE, meaning if you write "language" instead of "LANGUAGE" it will not work.
##The file MUST start with the opening <code><LANGUAGE></code> tag and it MUST end with the closing <code></LANGUAGE></code> tag. This element should only occur once in the entire file.
##Inside the LANGUAGE element, you can place as many CATEGORY elements as you wish, but ensure that every opening tag is always accompanied by a closing tag.
##Certain CATEGORY tags require a specific value in the "Name" attribute. For instance, the main menu description is required to be within a category named <code>CustomStoryMain</code>.
##You can place as many Entry elements as you wish inside each CATEGORY element. The actual text that appears in the game will be written between the opening and closing tag for the Entry. Similarly to CATEGORY tags, certain Entry tags require specific values in their name attribute for the game to pick it up. In the above example, the description must have the name <code>Description</code>.
##If any errors are encountered while the game parses this file, the entire file will fail to load and no custom text will appear in your story. You will know that it failed to load if you see "No description" in the game menu.

==Moving on==
You have now set up the basic configuration for a custom story. What's left to do now is to create your levels using the level editor, create scripts for your levels using any code editor, and optionally add extra assets you wish to use to additional folders inside your custom story directory. These topics are very expansive and are not covered here, but you can follow the links below for more information on them.

Your final results from following this guide should leave you with a custom story folder that has this structure:<pre>
My First Story/
|- maps/
| |- level_01.map
|
|- cool_bg.png
|- custom_story_settings.cfg
|- extra_english.lang</pre>

==See also==

*[[HPL2/custom story settings.cfg|Explanation of the custom_story_settings.cfg file]]
*[[HPL2/Tools/Level Editor|How to navigate the Level Editor]]
*[[HPL2/Tutorials/Level Design|Using the level editor to design maps]]
*[[HPL2/ScriptReference|Introduction to AngelScript and level scripting]]

Making a Mod - Best Practices

2021-12-08T12:50:21Z

Darkfire: /* Online Presence */ minor

{{note|This article is long, but taking the time to read it might help you save a lot of time when making a mod.}}This article is designed to give modders things to keep in mind while creating their project. Remember that these are just guidelines intended to help you – you don't have to follow them, but they may teach you something useful.
==Starting Out==

===Scoping Out Your Project===
In order to make sure your mod gets released, it is '''extremely''' important to make it under a manageable scope. This means that you must avoid being overly ambitious. Creating a project that is too massive will likely end up getting cancelled. Many modders may come up with interesting and big ideas that sound doable on paper, but later realize that it is a lot more work than first anticipated.

The best way to combat this is to create a limited scope from the start. It is much better to be conservative and create a project that is smaller than what you think you can do. A small project is better than a cancelled project.

If you would like to create a big project, it is best to first create a small one, which will give you an idea of how big you can go in the next project. Two small projects will teach you more than a single big one.

{{tip|Don't plan your project with play time or the number of levels in mind. This will end up in having a lot of content left to make and no ideas for it. Instead, gather your gameplay ideas and design around that. It is easier to add onto a complete project than fill an unfinished one.}}

And remember: quality over quantity. Players will enjoy a unique and well crafted mod even if it is short more than one that is artificially expanded just to be long. You will also have much more fun and satisfaction if you can finish a project before it bores you.

===Collaboration===

You will need to decide if you are going to work in a team or not. This will influence the scope of the project, so it is be done when starting a mod. A team can of course be brought on after working alone for some time, but that comes with additional challenges.

Working on a mod alone is entirely possible, but working in a team will make it much more bearable. That said, do not assume working in a team is always easier than working alone; there are upsides and downsides. Having a team requires managing it and making sure work is actually getting done, which is a considerable challenge.

{{Idea|If you are going to work in a team, '''make sure to create the mod idea together.''' An unfortunately popular phenomenon is people joining a team, getting a sneak-peek at the mod and losing interest. '''Creating the mod premise together can help keep the members invested.'''}}

'''Remember, even having someone to only give you feedback is very helpful.''' Furthermore, participating in public discussions about modding can help you and others learn. This can be done in the modding channels on [https://discord.com/invite/frictionalgames the Frictional Games Discord server]. Share your work and ask questions!

''Main article: [[Efficient_Teamwork | Efficient Teamwork]]''

==Mod Design==
Ask yourself "Why should someone play my mod?". It's a hard question, but if you can answer it well, your mod design has good potential. Think about what other mods are out there, and what they offer. Does your mod offer something new to the players? Is what you offer enough to interest players? Even if you cannot answer these questions, just thinking about it will probably help you come up with ideas.

===Understand the Engine===
You should really read the documentation of the game you want to mod.

By doing that, you will learn two important things: 
What things you can do with the engine and how to do them so they work well. There will be multiple ways to achieve what you want, but sometimes only one will work without code problems, affecting the performance too much, and other risky stuff. Reading the documentation will also ensure you are not recreating something that is already in the engine and is much easier to use.


===Compete With Gameplay and Story===
Remember that most mods cannot compete on a complexity and scale level with commercial products. They were made by teams of artists and developers with years of experience. It can take years to make a mod that has 30% the amount of content that the base games have. Instead of making big mods with dozens of maps, try to come up with engaging gameplay and a story that will be shorter but effective.

==Managing development==
When working on a mod, it is important to keep track of your and other's work, while making sure everyone knows what left to be done, what is already done and more. The following section provides tips, links to useful tools and guides which will help you to manage the project.

'''Keep in mind these are very important even for one-person projects!''' Keeping track of work always gets one far - it helps you plan and remember things.

===Setting up a Scrum Board===
In short, a scrum board is a group of lists used for keeping track of the team's development progress. It is used for:

*Creating tasks
*Assigning tasks
*Tracking what is already done
*Tracking what needs to be done
*Tracking what is being worked on
*Tracking bugs

One of the free tools which provide that is [https://trello.com/guide Trello].

===Version control===
There is nothing worse than not being able to track your work or recover older versions of your project.

Systems such as [https://git-scm.com/ '''Git'''] help to keep track of changes and back them up. Whenever you ''commit'' your work, a snapshot of the work is saved. In case something goes wrong, you will be able to go back to any older commit. Commits are stored inside a ''repository''.

'''One of the most important feature of Git is collaboration.''' Working on all sorts of files with multiple people will get messy very fast if you just send them back and forth. Git allows multiple people to work on the same project simultaneously, and (after setting up) requires only a few clicks to upload your work and update the work of others. It also helps you resolve any conflicts when multiple people edit the same file.

'''Read more about [[Setting up an Online Repository]].'''

==Online Presence==
You will most likely start sharing your creations before the mod is published. It is recommended to make sure you have something to show off before you create mod pages. Therefore, you should prepare a set of media to preview the mod, as well as coming up with an intriguing description to catch the eye. All of these should make you stay relevant for some amount of time at the very least.

You will receive feedback and criticism from other users or from your own team about your work. It's important to accept and learn from them, instead of denying, attacking or ignoring such feedback. You grow all the time during development, and your mod's success will be affected by how you react to feedback and criticism.

''Main article: [[Online_Presence|Online Presence]]''

==Finishing==
Before the mod gets released, it should undergo a series of procedures which will make sure the players have the best experience possible. '''Remember, first impressions matter - having something broken on release can impact the way your mod is received.'''

===Playtesting===
'''Make sure your mod was tested by other people just before release.''' It might be surprising, but sometimes things will break even if you can play the entire mod without bugs on your set-up. You can also install a clean version of the game and check if your mod behaves properly there before getting playtesters.

Playtests should be performed on the final versions of the mod. ''Don't let team members play from their personal versions of the mod!'' Many hours can be wasted on finding bugs caused by incompatible versions, or realizing the reported bug is already fixed and the playtester had an outdated version.

{{tip|Ask Playtesters to take notes. This will get you more bits of feedback. }}

===Bugs and Changes===
A complete list of all bugs and changes should be maintained along with their current status. Preferably this should be done in services like Trello. After each playtest, new bugs and necessary changes should be added, and assigned to team members. When a team member has fixed a bug or change, they should submit the new content to the team leader, who should verify that it is fixed and then update the status on the bug list.

===Cut or Defer Broken Features===
The hardest and unfortunately necessary part of publishing a mod is cutting features. Don't be scared to remove unfinished features - often it can be easier to do that and make sure it doesn't break anything than actually make the feature work.

Beware of feature creep. Make sure feature ideas actually add to the design of the mod and aren't there just because they are cool. It can be surprisingly easy to keep adding features to already existing work instead of actually pushing the development forward.

Cutting features will save you unnecessary time wastes and stress.

==Post-Release==
So you have released your mod, and soon enough rating and reviews started popping up. Your mod may or may not have been successful, but what comes next is up to you. The best approach is to learn from the feedback you get, see what worked and what didn't, and improve it for the next time. Talk with players, get involved in how they experienced your mod. Don't be afraid if it takes more time than usual to make your next big mod. Good ideas take time to brew, especially for horror games.

Knowing what to fix, what to change, and how to listen to your community is a continuous learning process.

Good luck!

[[Category:Modding]]
[[Category:English]]

Making a Mod - Best Practices

2021-12-08T12:47:07Z

Darkfire: /* Compete With Gameplay and Story */ removed off-topic rambling and refactored the important data

{{note|This article is long, but taking the time to read it might help you save a lot of time when making a mod.}}This article is designed to give modders things to keep in mind while creating their project. Remember that these are just guidelines intended to help you – you don't have to follow them, but they may teach you something useful.
==Starting Out==

===Scoping Out Your Project===
In order to make sure your mod gets released, it is '''extremely''' important to make it under a manageable scope. This means that you must avoid being overly ambitious. Creating a project that is too massive will likely end up getting cancelled. Many modders may come up with interesting and big ideas that sound doable on paper, but later realize that it is a lot more work than first anticipated.

The best way to combat this is to create a limited scope from the start. It is much better to be conservative and create a project that is smaller than what you think you can do. A small project is better than a cancelled project.

If you would like to create a big project, it is best to first create a small one, which will give you an idea of how big you can go in the next project. Two small projects will teach you more than a single big one.

{{tip|Don't plan your project with play time or the number of levels in mind. This will end up in having a lot of content left to make and no ideas for it. Instead, gather your gameplay ideas and design around that. It is easier to add onto a complete project than fill an unfinished one.}}

And remember: quality over quantity. Players will enjoy a unique and well crafted mod even if it is short more than one that is artificially expanded just to be long. You will also have much more fun and satisfaction if you can finish a project before it bores you.

===Collaboration===

You will need to decide if you are going to work in a team or not. This will influence the scope of the project, so it is be done when starting a mod. A team can of course be brought on after working alone for some time, but that comes with additional challenges.

Working on a mod alone is entirely possible, but working in a team will make it much more bearable. That said, do not assume working in a team is always easier than working alone; there are upsides and downsides. Having a team requires managing it and making sure work is actually getting done, which is a considerable challenge.

{{Idea|If you are going to work in a team, '''make sure to create the mod idea together.''' An unfortunately popular phenomenon is people joining a team, getting a sneak-peek at the mod and losing interest. '''Creating the mod premise together can help keep the members invested.'''}}

'''Remember, even having someone to only give you feedback is very helpful.''' Furthermore, participating in public discussions about modding can help you and others learn. This can be done in the modding channels on [https://discord.com/invite/frictionalgames the Frictional Games Discord server]. Share your work and ask questions!

''Main article: [[Efficient_Teamwork | Efficient Teamwork]]''

==Mod Design==
Ask yourself "Why should someone play my mod?". It's a hard question, but if you can answer it well, your mod design has good potential. Think about what other mods are out there, and what they offer. Does your mod offer something new to the players? Is what you offer enough to interest players? Even if you cannot answer these questions, just thinking about it will probably help you come up with ideas.

===Understand the Engine===
You should really read the documentation of the game you want to mod.

By doing that, you will learn two important things: 
What things you can do with the engine and how to do them so they work well. There will be multiple ways to achieve what you want, but sometimes only one will work without code problems, affecting the performance too much, and other risky stuff. Reading the documentation will also ensure you are not recreating something that is already in the engine and is much easier to use.


===Compete With Gameplay and Story===
Remember that most mods cannot compete on a complexity and scale level with commercial products. They were made by teams of artists and developers with years of experience. It can take years to make a mod that has 30% the amount of content that the base games have. Instead of making big mods with dozens of maps, try to come up with engaging gameplay and a story that will be shorter but effective.

==Managing development==
When working on a mod, it is important to keep track of your and other's work, while making sure everyone knows what left to be done, what is already done and more. The following section provides tips, links to useful tools and guides which will help you to manage the project.

'''Keep in mind these are very important even for one-person projects!''' Keeping track of work always gets one far - it helps you plan and remember things.

===Setting up a Scrum Board===
In short, a scrum board is a group of lists used for keeping track of the team's development progress. It is used for:

*Creating tasks
*Assigning tasks
*Tracking what is already done
*Tracking what needs to be done
*Tracking what is being worked on
*Tracking bugs

One of the free tools which provide that is [https://trello.com/guide Trello].

===Version control===
There is nothing worse than not being able to track your work or recover older versions of your project.

Systems such as [https://git-scm.com/ '''Git'''] help to keep track of changes and back them up. Whenever you ''commit'' your work, a snapshot of the work is saved. In case something goes wrong, you will be able to go back to any older commit. Commits are stored inside a ''repository''.

'''One of the most important feature of Git is collaboration.''' Working on all sorts of files with multiple people will get messy very fast if you just send them back and forth. Git allows multiple people to work on the same project simultaneously, and (after setting up) requires only a few clicks to upload your work and update the work of others. It also helps you resolve any conflicts when multiple people edit the same file.

'''Read more about [[Setting up an Online Repository]].'''

==Online Presence==
You will most likely start sharing your creations before the mod is published. It is recommended to make sure you have something to show off before you create mod pages. Therefore, you should prepare a set of media to preview the mod, as well as coming up with an intriguing description to catch the eye. All of these should make you stay relevant for some amount of time at the very least.

You will receive feedback and criticism from other users or from your own team about your work. It's important to accept and learn from them, instead of denying, attacking or ignoring such feedback. You grow all the time during development, and your online presence will be affected by how you react to feedback and criticism.

''Main article: [[Online_Presence|Online Presence]]''

==Finishing==
Before the mod gets released, it should undergo a series of procedures which will make sure the players have the best experience possible. '''Remember, first impressions matter - having something broken on release can impact the way your mod is received.'''

===Playtesting===
'''Make sure your mod was tested by other people just before release.''' It might be surprising, but sometimes things will break even if you can play the entire mod without bugs on your set-up. You can also install a clean version of the game and check if your mod behaves properly there before getting playtesters.

Playtests should be performed on the final versions of the mod. ''Don't let team members play from their personal versions of the mod!'' Many hours can be wasted on finding bugs caused by incompatible versions, or realizing the reported bug is already fixed and the playtester had an outdated version.

{{tip|Ask Playtesters to take notes. This will get you more bits of feedback. }}

===Bugs and Changes===
A complete list of all bugs and changes should be maintained along with their current status. Preferably this should be done in services like Trello. After each playtest, new bugs and necessary changes should be added, and assigned to team members. When a team member has fixed a bug or change, they should submit the new content to the team leader, who should verify that it is fixed and then update the status on the bug list.

===Cut or Defer Broken Features===
The hardest and unfortunately necessary part of publishing a mod is cutting features. Don't be scared to remove unfinished features - often it can be easier to do that and make sure it doesn't break anything than actually make the feature work.

Beware of feature creep. Make sure feature ideas actually add to the design of the mod and aren't there just because they are cool. It can be surprisingly easy to keep adding features to already existing work instead of actually pushing the development forward.

Cutting features will save you unnecessary time wastes and stress.

==Post-Release==
So you have released your mod, and soon enough rating and reviews started popping up. Your mod may or may not have been successful, but what comes next is up to you. The best approach is to learn from the feedback you get, see what worked and what didn't, and improve it for the next time. Talk with players, get involved in how they experienced your mod. Don't be afraid if it takes more time than usual to make your next big mod. Good ideas take time to brew, especially for horror games.

Knowing what to fix, what to change, and how to listen to your community is a continuous learning process.

Good luck!

[[Category:Modding]]
[[Category:English]]

User:Darkfire

2021-12-02T15:31:08Z

Darkfire: Update

{{ConstructionNotice|Dorkflame is working very hard (not really) on making this article less stuck-up.|align=center|width=30%}}
I've been around the community since 2014, mostly invested in modding. You can see my contributions on this page.
I was also involved in cleaning up this wiki before it was made public and I moderate it since.

==HPL2==
I spent most of my time in the community working with HPL2.

===Mod assets===
*[https://www.moddb.com/mods/improved-lantern Improved Lantern]
*[https://www.moddb.com/games/amnesia-the-dark-descent/addons/mfp-inventory-gui MFP inventory for TDD mods]
*[https://www.mediafire.com/file/szr9jdfba470qoh/DarkfireNatureAssets.rar/file Nature asset pack]

===Tutorials===
*[[Hpl2:Tutorials:level editor:outdoors|Making outside levels in HPL2]]
*[[HPL2/Tutorials/Level Design |Level Design in HPL2]]
*[[HPL2/Tutorials/Porting_MFP_Assets|Porting MFP assets to TDD]]
*[[HPL2/Tutorials/Convert HDRI to skyboxes|Converting HDRI to skyboxes]]

===Other contributions===
I have also:
* implemented/ported most of the features and fixes in the [[HPL2/Tools#Community_tools|community editors]]
* discovered how to use the <code>StartPlayerSpawnPS();</code> function. See the documentation [[HPL2/Engine_Scripts#General_2|here]].
* inquired about and later tested the obscure feature of [[HPL2/Tools/Level Editor/Combine Editmode|static object combos]].

===Amnesia: A Machine For Pigs===
I reverse engineered a considerable part of the MFP editor config files. This has allowed me to create custom config files, which allow editing MFP files without errors. I have also reverse-engineered the Infection system and wrote the majority of the MFP articles. Funnily enough, I don't like MFP much.

*MFP compability is available in the [[HPL2/Tools#Community_tools|community editors]]
*[[HPL2/AMFP/Introduction#Modding_MFP|MFP recompiled with Custom Story support]]


*The articles which I wrote can be found [[HPL2/AMFP|here]].

==My mods==

===SOMA===
"Life Freezes Over" is [https://frictionalgames.com/2020-02-winner-showcase-of-frictional-winter-modding-jam-2019/ a winning entry in the Frictional Games Winter Fan Jam] for which I wrote a bulk of the script, co-designed the levels and helped with making them (a little).

*[https://www.moddb.com/mods/life-freezes-over Life Freezes Over (on ModDb)]
*[https://steamcommunity.com/sharedfiles/filedetails/?id=1979207413 Life Freezes Over (on Steam)]

===Amnesia===
*[https://www.moddb.com/mods/amnesia-chromanin Chromanin]
*[https://www.moddb.com/mods/sdp SDP]
*[https://www.moddb.com/mods/eldritch-cove Eldritch Cove (Full Conversion)]

===Amnesia side projects===
*[https://www.moddb.com/mods/obturaculum Obturaculum] - a feature-length parody mod
*[https://www.moddb.com/mods/td T.D.] - a short retelling of P.T. on the HPL2 engine
*[https://www.moddb.com/mods/community-event-a-week-of-modding A week of modding] - a small community event, which was won by my entry