Frictional Wiki - User contributions [en]

HPL3/Audition/Voice Handler Overview

2026-07-30T22:27:43Z

TiMan:

= Voice Handler =

= Overview =

The voice handler is basically a simplified way in which to play complex sound events that deal with voices. It is also a way to easily handle subtitles along with the voices and play special effects track along with them. It has a queue system and keeps track of how many times a voice has been played.

Note that while often used along with the event database, these are two completely separate systems, so they should not be confused with one another.

= Setup =

Before calling a subject the source of the sound should be set up. This is best done inside the VoiceHandler editor itself, but can also be done using the helper function Voice_SetSource(). This sets up the entity (which can be something moving) which will emit the voice coming from the specified character. It will also set up the distance that the voice can be heard. If using the function, it's best to do this in ''OnEnter'' in the map script file.
= Properties =

== Character ==
The character is the agent that is speaking the lines. Normally this is a person of some sort but it can really be whatever. It mostly used used as a way to give debug data on what character is saying what line, and also used to place the voice in the world (the position of character can be set in script).

'''ID''' Internal Id

'''Name''' Name of the character

'''EntryType''' The type of the sounds (and extrasounds) that are played for this character. Is either World, WorldClean or GUI.

'''Volume''' Volume of the sound files. Gets multiplied with other volume properties.

'''ReverbVolume''' The amount of reverb used for the sounds. Gets multiplied with other ReverbVolume properties.

== Scene ==
This does not have to mean the level that the voice are played in, but what subtext that they are used in. A scene is NOT the same as the level the voices belong to, but a level can (and should have) have many scenes. It is a way to group subjects and also to setup what voices should be in focus (by using FocusPrio).

'''ID''' Internal Id

'''Name''' Name of the scene

'''FocusPrio''' This is the priority for a voice to into focus, meaning that is subtittles are shown and any other voice playing gets its volume lowered. To beat a currently playing voice, FocusPrio must be higher. When a subject starts playing it is checked if another sound is playing and FocusPrio determines if the new subject gets into focus. Also when a subject stops playing a certain amount of time is waited (default 2 seconds) and then there is a check to see if there is any playing voice that should come into focus. If there are many playing, FocusPrio determines which one. The reason for waiting a litte while is in case there is a conversiation in one scene containing many subjects, and if so it would not sound good if the focus was constantly switched (ie unrelated subtitles popping up for a second).

'''Volume''' Volume of the sound and effect files. Gets multiplied with other volume properties.

'''ReverbVolume''' The amount of reverb used for the sounds. Gets multiplied with other ReverbVolume properties.

== Effect ==
This defines certain effect that should be played on the voice, be that echo, noise or whatnot. ''Note: Right now there is not much done with effect, so it is pretty useless''

'''ID''' Internal Id

'''Name''' Name of the effect

'''GlobalStartEffectFile''' A file that is played each time a new line starts.

'''GlobalEndEffectFile''' A file that is played each time a new line is over.

'''GlobalVoiceOffset''' Not used.

== Subject ==
A subject is what you call when you want to voice to be played. A subject is the basic data structure of the voice data and it contains sound files, subtitle texts and various options. A subject contain one or more '''Lines''' (more on these below). Normally all of these lines will be played in order, but if UseSingleRandomLine is true, only one will.

'''ID''' Internal Id

'''Name''' Name of the subject

'''UseSingleRandomLine''' If only a single random line should be used. If more than 2 lines, it is made sure that the a line is never picked two times in a row.

'''SceneId''' Id of scene connected to the subject.

'''EffectId''' Id of the effect used for the subject.
== Line ==
When a voice is called to be played the entirety of a line is always played.
The line contains one or more '''Sounds''' (more on these below) that make up what is played.

'''ID''' Internal Id

'''CharacterId''' Id of character connected to the line.

== Sound ==

This is the lowest level data structure for a subject. It contains properties for the voice, (opitonal) effect sound, and subtitle.

The file name for the voice sound is generated based on the names of the higher level structures. The syntax is: ''[map]'' /''[scene]'' _''[subject]'' _''[line index in 3 digits]'' _''[character]'' _''[sound index in 3 digits]''

Here is an example: ''01_01_castle/SwordFight_ShowMercy_002_Arthur_001'' This would be a voice sound being said in the map ''"01_01_castle"'' (no file extension!), in the Scene ''"SwordFight"''. The subject is ''"ShowMercy"'', it is the second line, it is being said by ''"Arthur"'' and it is his first sound for that line.

The lang file entry for the text is also generated, with this syntax: Category: Voices_''[map]'' Entry: ''[scene]'' _''[subject]'' _''[line index in 3 digits]'' _''[character]'' _''[sound index in 3 digits]'' (apart from no folder name, it is exactly the same as for the voice file!)

Finally, if "AutogenerateLangFiles" in "Main" is set to true in the user settings, then the lang file entries will be autogenerated with the text specified in the sound's properties.

'''Text''' The text for the voices, not really saved by added to a lang file (if AutogenerateLangFiles is true i settings, see above)

'''HasVoice''' If the sound has a voice at all. This is only meaningful false if there is an Effect filed specificed.

'''Volume''' Volume of the sound and effect file. Gets multiplied with other volume properties.

'''ReverbVolume''' The amount of reverb used for the sounds. Gets multiplied with other ReverbVolume properties.

'''VoiceOffset''' Number of seconds before voice starts to play.

'''TextOffset''' Number of seconds before the subtitles show up.

'''ExtraEffectOffset''' Number of seconds before the effect file starts to play.

'''ExtraEffectFile''' File path to an extra sound file that is played along with the voice.

'''EndsAfterExtraEffect''' If the sound should end when the extra sound file is done playing (and not the voice).

'''EndPadding''' Number of seconds of padding in the length of voice file. If this is over 0, then that means the next sound will start that many seconds earlier (while the current sound is still playing).

= Use with AI =

When using voice with AI it is best always through the [http://wiki.frictionalgames.com/hpl3/game/scripting/entity_components#barkmachine BarkMachine component] using ''BarkMachine_PlayVoice(...)''. That way it is sure to be played in the right place even if there are multiple agents that use voices from the same character. When using the BarkMachine, the source set up directly before the line is played.

The voices for all agents should also have "AgentBark" as scene, this way it makes it possible to see to that there is only one dialog line from an Agent at a time. Should there be some special line that does not apply to this, then by all means do not do this.

If you want to have longer specific dialog on agents, then the best way to set that up is to have the piece of a dialog as a single subject with two unique Characters attached to the lines. Then set up these characters as voice sources specifically in the script and start the dialog using ''Voice_Play''. The scene must be AgentBark as described above and the prio must be less than what the default barks use. What then happens is that the dialog will continue until some AI event triggers default sounds to be played and the specific dialog will automatically be stopped.

= Best Practices =

Here are a few practices that should be used when adding voices in the game:

'''- Sound effects are between *:s ''' When adding sound effects, like *gasp*, *pants*, *cries*, etc then always put them between *:s. This way we can easily remove them for people that do not want the hearing impaired option.

'''- Pure sound effects is a separate line''' When implementing a subject that contains parts where there is only (non character related) sound effects playing you shall add this as Line on its own. The character containing it shall be called "_SoundEffect". If the sound effects need to come from special position in the world, then do add a "_" followed by a prefix to the name, for instance "_SoundEffect_Trees" (this should be pretty rare though and these sort of effects are better added through callback functions, but there might be some rare instance that require it).

Important note is that this only meant for sound effects that are not specific to a character voice. Examples: Do '''NOT''' use it for: *cough*, *clears throat*, *spits*, etc. '''DO''' use it for: *steps are heard coming down the stairs*, *large metal door opens*, *Anne carefully steps on the creaking floor*, etc. 
'''- All protagonist dialog come from the character "Player"''' Make sure that all the dialog that the player is supposed to say outloud comes from the character "Player", as this allow the game to not play breathing, etc when a voice over from the player character is playing.

'''- Use proper prefix for subjects''' Have prefixes on the subjects that give some hint where they belong and make it easier to sort. For instance a blackbox subject should start with "Blackbox_", eg "Blackbox_FriedRobot". Another examples would be a situation that many subjects belong. Say Simon meets a farmer and there is a lot of subjects related to this, then use the prefix "SimonMeetsFarmer_", eg "SimonMeetsFarmer_Intro".

This is also true for special characters, for instance when a certain character speak in a recording. So for instnace a character that appears in a SOMA blackbox message (that does not come from a world position), should have "Blackbox_" as prefix, eg "Blackbox_Amy".

'''- Write temp dialog in square brackets''' If you add some writing that is only temporary then add this between square brackets. Also briefly summarize what is supposed to be going on, or what the is supposed to be expressed. Examples: [Player gets his finger caught in bear trap] [Hint that the screw needs to be bigger] 
If you need to have further info that feels wrong to show in-game then you can add extra info under the line direction, but make sure to start the line with INFO:, so it is not confused with proper line direction. Examples: INFO: The player tries to hold the pain inside. INFO: The solution is to use the file on the screw, can have slight hint for that. = File Format =

(You shouldn't need this - everything can be edited using the VoiceHandler exe!)

<syntaxhighlight lang="xml">
<VoiceData>
<Characters>
<Character [Properties] />
...
</Characters>
<Effects>
<Effect [Properties] />
...
</Effects>
<Scenes>
<Scene [Properties] />
...
</Scenes>
<Subjects>
<Subject [Properties] >
<Line [Properties] >
<Sound [Properties] />
...
</Line>
...
</Subject>
</Subjects>
</VoiceData>
</syntaxhighlight>

For information on the Properties that can be used, see Properties section above.

HPL3/Audition/Voice Handler Overview

2026-07-30T22:26:52Z

TiMan:

The voice handler is basically a simplified way in which to play complex sound events that deal with voices. It is also a way to easily handle subtitles along with the voices and play special effects track along with them. It has a queue system and keeps track of how many times a voice has been played.

Note that while often used along with the event database, these are two completely separate systems, so they should not be confused with one another.

= Setup =

Before calling a subject the source of the sound should be set up. This is best done inside the VoiceHandler editor itself, but can also be done using the helper function Voice_SetSource(). This sets up the entity (which can be something moving) which will emit the voice coming from the specified character. It will also set up the distance that the voice can be heard. If using the function, it's best to do this in ''OnEnter'' in the map script file.

HPL3/Audition/Voice Handler Overview

2026-07-30T22:26:48Z

TiMan: Created page with " The voice handler is basically a simplified way in which to play complex sound events that deal with voices. It is also a way to easily handle subtitles along with the voice..."

HPL3/SOMA/Audition

2026-07-30T22:26:37Z

TiMan: /* Voice Handler */

HPL3/SOMA/Audition/Audition Overview

2026-07-30T22:25:31Z

TiMan: Created page with "= Best Practices = Here are a few practices that should be used when adding voices in the game: '''- Sound effects are between *:s ''' When adding sound effects, like *..."

= Best Practices =

Here are a few practices that should be used when adding voices in the game:

'''- Sound effects are between *:s ''' When adding sound effects, like *gasp*, *pants*, *cries*, etc then always put them between *:s. This way we can easily remove them for people that do not want the hearing impaired option.

'''- Pure sound effects is a separate line''' When implementing a subject that contains parts where there is only (non character related) sound effects playing you shall add this as Line on its own. The character containing it shall be called "_SoundEffect". If the sound effects need to come from special position in the world, then do add a "_" followed by a prefix to the name, for instance "_SoundEffect_Trees" (this should be pretty rare though and these sort of effects are better added through callback functions, but there might be some rare instance that require it).

Important note is that this only meant for sound effects that are not specific to a character voice. Examples: Do '''NOT''' use it for: *cough*, *clears throat*, *spits*, etc. '''DO''' use it for: *steps are heard coming down the stairs*, *large metal door opens*, *Anne carefully steps on the creaking floor*, etc. 
'''- All protagonist dialog come from the character "Player"''' Make sure that all the dialog that the player is supposed to say outloud comes from the character "Player", as this allow the game to not play breathing, etc when a voice over from the player character is playing.

'''- Use proper prefix for subjects''' Have prefixes on the subjects that give some hint where they belong and make it easier to sort. For instance a blackbox subject should start with "Blackbox_", eg "Blackbox_FriedRobot". Another examples would be a situation that many subjects belong. Say Simon meets a farmer and there is a lot of subjects related to this, then use the prefix "SimonMeetsFarmer_", eg "SimonMeetsFarmer_Intro".

This is also true for special characters, for instance when a certain character speak in a recording. So for instnace a character that appears in a SOMA blackbox message (that does not come from a world position), should have "Blackbox_" as prefix, eg "Blackbox_Amy".

'''- Write temp dialog in square brackets''' If you add some writing that is only temporary then add this between square brackets. Also briefly summarize what is supposed to be going on, or what the is supposed to be expressed. Examples: [Player gets his finger caught in bear trap] [Hint that the screw needs to be bigger] 
If you need to have further info that feels wrong to show in-game then you can add extra info under the line direction, but make sure to start the line with INFO:, so it is not confused with proper line direction. Examples: INFO: The player tries to hold the pain inside. INFO: The solution is to use the file on the screw, can have slight hint for that. = File Format =

(You shouldn't need this - everything can be edited using the VoiceHandler exe!)

<syntaxhighlight lang="xml">
<VoiceData>
<Characters>
<Character [Properties] />
...
</Characters>
<Effects>
<Effect [Properties] />
...
</Effects>
<Scenes>
<Scene [Properties] />
...
</Scenes>
<Subjects>
<Subject [Properties] >
<Line [Properties] >
<Sound [Properties] />
...
</Line>
...
</Subject>
</Subjects>
</VoiceData>
</syntaxhighlight>

For information on the Properties that can be used, see Properties section above.

HPL3/SOMA/Audition

2026-07-30T22:25:02Z

TiMan:

HPL3/Sound/Playing Sounds

2026-07-30T22:23:08Z

TiMan: Created page with "= Sound Browser window = This window helps when having to pick sounds. It can work in two different modes: * Sound Entity File:sound_entity.png ''' '''Full path input''..."

= Sound Browser window =
This window helps when having to pick sounds. It can work in two different modes:

* Sound Entity

[[File:sound_entity.png]]

''' '''Full path input''': This input will display the current full path, will show each step in the path as a row in the open list. Clicking on a row will make the dialog navigate to that folder.
''' '''Up button''': will make the dialog navigate to the parent folder.
''' '''Directory and file listing'''

* Sound Event

[[File:sound_event.png]]
''' Two boxes will show up, left one will list available '''Sound Projects''' (or sound banks) and '''Sound Groups''' (pretty much like subdirectories) in a tree fashion. The one at the right will show '''Sound Events''' (sounds actually) present inside the picked Group. To use one of them, just select it there.

These are common for both modes.
* '''Play button''': will play a sample of the picked sound.
* '''Load file name''': The name of the file to load.
* '''Load button''': Will try to load the given file name and close.
* '''Cancel button''': Will just close the dialog.

=Sound EditMode=

This EditMode is used to create Sound Entities in the map. These are used to add ambience sound, static sounds like water flowing, or pretty much any sound you want.

To create a Sound Entity, just click on the grid when this EditMode is active. This will create an "empty" Sound Entity, meaning it is just a container.
Optionally, you can set up the .snt file that will be used by the newly created Sound Entity, in the only input that shows on the EditMode window.

Have into account that these options will be valid for objects created right after changing them, so any Sound Entity that is already created will keep its settings.

More on sounds [[HPL2/Sounds|here]].

HPL3/Sound/Working with FMod Designer 2010

2026-07-30T22:22:42Z

TiMan: Created page with "= Sound = == FMOD == HPL3 uses FMOD to handle all sound playback. See [http://fmod.org|fmod.org]] for more details, documentation and help. When working with sounds it is ma..."

= Sound =

== FMOD ==

HPL3 uses FMOD to handle all sound playback. See [http://fmod.org|fmod.org]] for more details, documentation and help. When working with sounds it is mainly the [http://www.fmod.org/download/|FMOD Ex Designer tool] that will be of interest, the easiest way to learn how it works is to check the tutorials in [[http://www.youtube.com/user/FMODTV FMOD's YouTube channel].

==== General ====

It is important to plan and think through how to split up your sounds into different projects. The game will load sounds based on this, it will help you find your sounds, it will ease preloading if you need to use that and so on.

===== Project =====

Create a project for large chunks of sound types, for example a project for each character, level or for physics. Each project can contain many groups of sound events, preferably a hierarchy of 1-2 sub-groups will make it organized and easy to work with when for example optimizing. More details about this is found under FMOD Designer Events. Some type of sounds need to follow a special structure and naming convention! See the sections below, for example physics and footsteps.

===== Banks =====

A bank stores all the sounds for a project, you can have many banks but you should normally only need two. One bank for sounds that you load into memory to play and one bank that streams sounds from the harddrive and plays them. Special cases where you need to have more banks would be if you have sounds that are localized to different languages, where you have one bank for each language.

Sounds to be streamed are usually longer sounds, such as a looping ambient track or voices. Be cautious with using streamed sounds, streams depend on the speed of the harddrive, so what works well for you might not be so for another user. Try to keep the number of simultaneous streams to something low, perhaps max 6 streams. Remember that music and dialog streams, so could easily be 3 streams if you have a cross-fade of music going when a voice is played.

===== Example files =====

Our releases always have all the final FMOD project files in the game sound/ folder. The actual source sound files are not included, but you can view the projects and see how they are organized and what settings are used for reference.

==== FMOD Designer Sound Defs ====

A sound def is the settings for a sound (or set of sounds for variation) that you can use in your Multi-track events. There is nothing specific to keep in mind for these, do as suitable and follow the FMOD documentation.

==== FMOD Designer Events ====

The Events are what you actually use when playing sounds in the engine. The events are what replaces our old system of playing a SNT file, which essentially worked in the same way as Simple Events. When working with events there are a few things to keep in mind, mainly to organize events into easy to navigate groups and to use categories to send the events to be processed (or not processed) by the proper global effects.

===== Simple Event =====

Nothing in particular to keep in mind beyond the basic usage as specified by the FMOD documentation. Just check our general important notes for events and performance concerns for info on why you should use simple events and any minor specific setting you might need to set.

===== Multi-track Event =====

These events allow for parameters to affect the sound in a detailed manner, for example changing the sound of an impact depending on the speed of the object or much more advanced mixes. Make sure to view Performance concerns for Events to not overdo it. These events replace what previously was set with a lot of parameters in the snt editor, model editor and level editor for sounds. The move to FMOD makes it possible for a sound designer to do much more without any engine specific knowledge or assistance from a programer/scripter.

Following is a quick overview of events, for more details check FMOD documentation and tutorials.

An event is created with layers, a layer can contain one or many Sound Defs. At first glance it is much like any sound editor, but as you begin to make your first event you notice that what normally is a representation of time is not so in the context of making FMOD Events.

To be able to move your sounds around you will need to right-click the top of the event and add a parameter. The parameter can represent numerous things, such as time or the engine sending in a value with the speed of an object. These parameters can be used to make envelope mixes and different sound def play depending on the value of a parameter or mix of parameters. For example see physics, the engine sends in the speed and mass of an object, the speed sets the volume and what type of sound def to play and the mass is used to change the pitch of the sounds (increased mass = lower pitched sound).

Let's say we have a machine in the game and the player will be able to start and stop this machine. A single event can be created to be used for this, where we first play a sound as the machine starts up, then loops a sound while it is running and finally plays a sound as it stops.

## Right-click the top and add a parameter to the event, the name does not matter.
## Right-click the parameter and choose parameter properties, set Velocity to 1. This will make the event play like in a typical sound editor.
## Right click on your layer and add in three sounds defs. This should be a start sound, a loop sound and a stop sound.
## Right-click on the start and stop sound defs and choose Sound instance properties… Set Loop mode to oneshot (as in do not loop).
## Play the event, make sure it plays the start, loop and then stop sounds in correct order as you like. If you like, drag the sound defs a bit over each other and they will automatically cross-fade.
## To test envelopes, right-click the section to the left (where it says layer00) and Add effect. Choose Volume.
## Right-click on the red envelope line to add points that you can use to fade the sound. Play the sound and notice that it fades the sound after the envelope, just like in a sound editor.
## Right-click the "timeline" (parameter value line) and add a sustain point somewhere in the looping sound. Play the sound and notice that it stays and loops the looping sound at the sustain point.
## Press the key off button and notice how the event move along and plays the stop sound and then ends.
## To make it work in game, add a User Property (right-click anywhere in the property section) called KeyOffParamName, type text and add a value with the name of the parameter containing the sustain point.

From this simple example you can see (hear) the possibilities that are available to you as the sound designer to create interesting and easy to use sound events. This event would allow the person scripting to simply play the sound as the player starts the machine, it would automatically begin to loop for as long as the machine is running and then as the player stops the machine the script would stop the sound (which triggers key off) and the sound stops with playing the stop sound as you designed it.

'''Envelopes, volume and 3D parameters''' There are three special parameters for 3D that you can use for events, right-click the parameter bar and you'll see Add 3D … parameter. These allow you to do typical things, such as fading a sound depending on the distance from the source. This you most of the time don't want to do, you rather simply use the 3D Min Distance and 3D Max Distance values for the event as a whole. But say you want a sound that fades out, but as it reaches a certain distance it stays at a certain volume, for this you have to do your own envelopes.

If you make your own envelopes you have to change 3D Rolloff to Custom or else the envelopes for Volume and/or Occlusion will not be used. You can also leave the 3D Min/Max distance values as they are, they are not used.

Don't forget to change the parameter property to have the correct value for the distance you want, the default is 0 to 1, which ingame would mean that the sound only reaches 1 meter. Right-click on the distance parameter, choose Parameter Properties and set the Minimum/Maximum value to what you want them to be.

'''Sustain Points''' A sustain point can be added to a parameter, this makes the game play a sound and when it reaches the sustain point it stays and loops there. Then when you stop the sound it will continue playing the event from the sustain point to the end. See the above list for making a multi-track event for an example of the usage.

Important. To use sustain points you must add a User Property to the sound event. You do this by right-clicking in the property sections, Add/Edit user properties and then create a property with these specifications.

{| class="wikitable sortable" border=1
| Name: || || KeyOffParamName || || The name of the parameter that the engine will look for when checking if a sustain points exists. ||
|-
| Description: || || blank || || Only a description, no need to fill in. ||
|-
| Type: || || text || || The name of the parameter that has the sustain point, typically param00. ||
|-
|}

If using script to play and stop the sound event, you must set the fade on Sound_Stop() to 0 to have the event continue playing and doing the stop sequence. If you have a fade time, the sound will stop and fade with the loop at the sustain point location instead.

===== Groups =====

Groups are almost only for organizing your project. However it is useful to think it through how to group and sub-group your events, as you can use a script function to preload group(s). Preloading is useful if you for example notice that you want to play many sounds at the same time and the game stutters from this. By preloading the sounds the engine have the sounds ready in memory for usage.

===== Categories =====

All sounds must be in one of two categories. These categories you have to create in each new project you make. It is only a matter of making a new category and naming it properly, there are no specific settings needed.

''' "world" - All sounds that should be affected by global effects, such as a reverb. For example if the player goes below surface then all the sounds around him should change.
''' "gui" - All sounds that should not be affected by global effects. Simply no matter where the player is or what he does, these sounds are always the same. For example button clicking sounds for the menu.

===== FMOD files & how engine access them =====

When you have a project of sounds that you want to use in the game you use the Build… option in the project menu. You can uncheck everything except that banks that you want to build. After building the project you take the .fsb (bank) files and the .fev (project) file and put them in the games sound/ folder at a suitable location.

Most of the time sounds will be picked from menus, using the tools for the engine (that is the plan, at the time of this writing this functionality does not exist.). If you manually have to specify a sound to be played, in for example a config file, a script file or in a input field allowing only to type in text this is how you do it.

Specify the full path to the sound, where it begins with the name of the project (the .fev file) and ends with the name of the event. For example for a physics impact that would be "physics/metal/compact/impact". Footsteps defined in the material.cfg file has an exception from this! See the Footstep sounds section.

===== Important notes for Events =====

''' Make sure that all events that should be looped are set to "Oneshot" '''false'''. If not, there might be all sort of strangeness in the sound playback.
''' Use unique names for all projects, as the .fev file it creates with the same name, must be unique for it to work correctly.
''' For looping (non "Oneshot") sounds that are to be in the environment, like fire from a torch, always use "just fail if quietest" max playback behavior. This will make sure that if there are many sounds of the same type around the player, it will be the loudest once that are heard. Other options are possible, but using any of the "steal" ones are almost always a bad choice.
''' Must use gui or world category, see categories section.

===== Performance concerns for Events =====

''' Use simple events as much as possible, they are faster than multi-track events.
''' Keep Max Playbacks to as few as possible, often the default 1 should suffice.
''' Do not add lots of effects to all events, it takes CPU. In particular never use reverb or similar, those should only be global and amount used by setting the dry/wet mix values (or use envelopes for dry/wet).
''' Preload projects/groups if needed to remove ingame stuttering when trying to play multiple sounds simultaneous.

==== Physics sound ====

The physics system lets the sound system (FMOD) handle any mixing/effects for the sounds played. This is done by sending one or more parameters to the Multi-track Event for a sound. These are as follows:

'''Scrape''' The event must have ONE param, name does not matter. The physics sends the linear speed to this param. Normal values 0 - 10. Is looping.

'''Roll''' The event must have ONE param, name does not matter. The physics sends the angular speed to this param. Normal values 0 - 10. Is looping.

'''Impact''' The event must have two params named "mass" and "speed". "Speed" is sent the speed of impact (normal values 0 - 20). "Mass" is sent mass of the colliding object (normal values 0 - 200, but rarely over ~30) Note that mass is 0 for any static object no matter their size.

'''Joint''' Move and Impact must have ONE param, where the speed is sent. Normal values are 0 - 5.

===== Materials.cfg =====

This file is located in the root (top) folder of the game installation, next to the game executable. The file can be edited in a text editor and it lists all the different types of material available to use by textures and objects in the game (ie makes something that looks like gravel behave and sound like gravel).

Parameters that are for a sound that you can define are always ending with SoundName = "". Currently there are three sounds: Roll, Scrape and Impact. As you can see they are specified by giving the full path to a sound event, beginning with the project name and ending with the event name.

The parameter called StepType has the same value as the name of the event to play. For this to work you have to make sure that the footstep events are put in the correct project, in the correct groups and with the correct names. See Footstep sounds section.

===== Specific settings for physics =====

There are some specific parameter values to keep in mind for physics sounds.

'''General'''

''' Max playbacks should be 2, possibly higher if you experience issues with sounds cutting out. Keep as low as possible.
''' Mode is 3D.
''' Min, Max Distance values should not be very far. Min: 0.5, Max: at most 30.
''' Priority should be low for physics, it is not important to have sounds from physics if channels run out, things like voices are much more important.

'''Scrape'''

''' Fade in/Fade out Time must be 100-300ms to avoid stuttering sounds.

'''Roll'''

''' Fade in/Fade out Time must be 300-500ms to avoid stuttering sounds.

==== Footstep sounds ====

Footsteps are defined in the material.cfg file, with the StepType parameter. The footsteps and script for it has been designed to work in the following manner:

''' Events are in a "player" project.
''' At the top there is an event group called "footsteps", in it are event groups called "barefoot", "sneaker" and "default".
''' Events for each type of material, with the same name as the StepType parameter value are located as needed in each type of foot type (barefoot, sneaker, default).
''' A parameter called movement in each event, with a value from 0 to 3.
''' Sound defs for sneak, walk and run.
''' The three step types has been laid out evenly, sounds should be reaching like this: sneak 0-1, walk 1-2 and run 2-3.

The engine checks what material the player is in contact with and what type of footwear the player has. This is then put together to a string and appends the value of the StepType parameter from the materials.cfg file. It sends the string, which is the location for a footstep event (ie player/footsteps/barefoot/stone), and also checks the current player movement (sneak, walk or run) value and sends that as the parameter value. This allows FMOD to play the different movement sounds for that particular material.

''Note: This is game specific and can be easily changed by editing the script files for the player's current move state''

HPL3/SOMA/Sound

2026-07-30T22:22:26Z

TiMan: /* Sound */

FMod Designer 2010

2026-07-30T22:21:55Z

HPL3/SOMA/Sound

2026-07-30T22:21:24Z

TiMan:

HPL3/Scripting/Scripting Guide/Setting up Visual Studio Code

2026-07-30T22:18:53Z

TiMan:

{{Hpl3ScriptingGuideMenuBasic}}
{{shortPageTitle}}

== Visual Studio Code language support ==

[https://marketplace.visualstudio.com/items?itemName=TiManGames.hpl3-language-tools HPL3 Language Tools] is a community-made Visual Studio Code extension that provides language support for HPL3 <code>.hps</code> scripts.

It supports:

* ''SOMA''
* ''Amnesia: Rebirth''
* ''Amnesia: The Bunker''

The extension treats HPL3 scripts as their own AngelScript-based language instead of C++. This prevents unrelated C++ diagnostics and enables HPL3-specific completion, validation, navigation, mod overlays, and callback checking.

HPL3 Language Tools is not affiliated with or endorsed by Frictional Games. The game compiler remains the final authority when validating scripts.

=== Installation ===

==== Visual Studio Marketplace ====

# Open Visual Studio Code.
# Open the '''Extensions''' view.
# Search for '''HPL3 Language Tools'''.
# Select the extension published by '''TiManGames'''.
# Click '''Install'''.



==== Local VSIX ====

The extension can also be installed manually:

# Download the latest <code>.vsix</code> package from the [https://github.com/TiManGames/hpl3-language-tools/releases GitHub releases page].
# Open the Visual Studio Code Command Palette with <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>.
# Run '''Extensions: Install from VSIX...'''
# Select the downloaded file.
# Reload Visual Studio Code if prompted.

=== Opening an HPL3 project ===

The simplest setup is to open the game installation folder as the Visual Studio Code workspace:

<pre>
C:\Program Files (x86)\Steam\steamapps\common\SOMA
C:\Program Files (x86)\Steam\steamapps\common\Amnesia Rebirth
C:\Program Files (x86)\Steam\steamapps\common\Amnesia The Bunker
</pre>

When the game folder is open, the extension normally detects the game automatically by locating:

* <code>hps_api.hps</code>
* <code>resources.cfg</code>
* The <code>script</code> directory

It is also possible to open an individual mod folder or another folder beneath the game installation.

If automatic detection fails:

# Open the Command Palette.
# Run '''HPL3: Select Game Root'''.
# Select the root folder of the appropriate HPL3 game.

The selected folder should be the main game folder, not its <code>mods</code>, <code>maps</code>, or <code>script</code> subdirectory.

=== HPS language association ===

Files ending in <code>.hps</code> should use the '''HPL3 HPS''' language mode.

The current language mode is displayed in the lower-right corner of Visual Studio Code. If it displays '''C++''', click it and select '''HPL3 HPS'''.

Some existing setups explicitly associate HPS files with C++:

<syntaxhighlight lang="json">
"files.associations": {
"*.hps": "cpp"
}
</syntaxhighlight>

Remove that association if it prevents the extension from selecting HPL3 HPS. The extension may display a one-time warning about this configuration, but it will not modify the user's settings automatically.

=== Selecting an active mod ===

By default, <code>hpl3.activeMod</code> is set to <code>auto</code>.

In automatic mode, the extension selects the mod containing the currently opened script. To select a mod explicitly:

# Open the Command Palette.
# Run '''HPL3: Select Active Mod'''.
# Select the desired mod.

The active mod controls script overlays, include resolution, completion, definitions, and project validation.

Resolution generally follows this priority:

# The directory containing the current file
# The active mod
# Direct mod dependencies
# Deeper transitive dependencies
# The base game
# Additional configured resource roots

An active-mod file shadows a dependency or base-game file using the same virtual resource path.

=== Mod dependencies ===

The extension reads each mod's <code>entry.hpc</code> file and resolves dependencies through their exact <code>Content.UID</code> values.

When mod X depends on mod Y, selecting mod X indexes:

* Scripts belonging to mod X
* Scripts belonging to mod Y
* Reachable transitive dependencies
* Base-game scripts and API declarations

Unrelated mods are excluded.

Missing dependencies, duplicate UIDs, malformed manifests, and dependency cycles are reported through the HPL3 status tooltip and output channel. Valid and unambiguous dependencies continue to be indexed when possible.

=== Language features ===

HPL3 Language Tools provides:

* Engine and project API completion
* Class and inherited-member completion
* Enum-value completion
* Array and handle type inference
* Include-path completion
* Hover documentation
* Function signature help
* Go to definition
* Document and workspace symbols
* Include navigation
* Incremental analysis while editing
* Automatic reindexing when scripts are changed or saved
* Semantic highlighting for HPL3 types, members, enums, and keywords

Documentation and engine declarations are primarily loaded from the selected game's <code>hps_api.hps</code> file.

=== Diagnostics ===

The extension reports likely script or engine failures, including:

* Malformed HPL3 or AngelScript syntax
* Unresolved or ambiguous includes
* Unknown variables, functions, types, or members
* Duplicate declarations in the same scope
* Invalid assignments and primitive conversions
* Invalid return values
* Incorrect constructor arguments
* Missing function arguments
* Invalid overload calls
* Callback names that cannot be resolved
* Callback signature mismatches
* Unsupported dialect operations such as <code>array.clear()</code>

Callback and mutable-global checks that can be valid in dynamic HPL3 code are generally displayed as warnings.

The extension intentionally does not enforce:

* C++ formatting conventions
* Naming conventions
* Include guards
* Pointer style
* Unused-variable rules
* Other C++-specific style diagnostics

To validate every indexed script rather than only open or affected files, run '''HPL3: Validate Workspace'''.

=== Running the current map ===

A '''Run Map''' CodeLens and editor-title play button appear when an HPS map script has a matching <code>.hpm</code> or legacy <code>.map</code> asset.

To launch the map:

# Open the map's <code>.hps</code> script.
# Click '''Run Map''' above the map class, or click the play icon in the editor title.
# The extension saves modified workspace files.
# The selected game starts in developer mode with the resolved map and mod arguments.

The map is resolved through the active-mod, dependency, and base-game overlays. A script-only mod override can therefore launch a map asset supplied by a dependency or the base game.

Launch details are written to the '''HPL3 Map Launcher''' output channel.

The extension directly launches the game executable. It does not create or modify development batch files.

=== Commands ===

{| class="wikitable"
! Command
! Description
|-
| '''HPL3: Select Game Root'''
| Selects the SOMA, Rebirth, or Bunker installation used for indexing.
|-
| '''HPL3: Select Active Mod'''
| Selects the active mod and its dependency profile.
|-
| '''HPL3: Rebuild Language Index'''
| Discards existing caches and reindexes the API, resources, and scripts.
|-
| '''HPL3: Validate Workspace'''
| Runs diagnostics across the complete indexed project.
|-
| '''HPL3: Run Current Map'''
| Launches the map associated with the current script.
|}

=== Settings ===

{| class="wikitable"
! Setting
! Default
! Description
|-
| <code>hpl3.gameRoot</code>
| Automatic
| Absolute path to a supported HPL3 game installation.
|-
| <code>hpl3.activeMod</code>
| <code>auto</code>
| Automatically detected or explicitly selected active mod.
|-
| <code>hpl3.extraResourceRoots</code>
| <code>[]</code>
| Additional read-only resource roots searched after mod and base-game resources.
|-
| <code>hpl3.diagnostics.maxPerFile</code>
| <code>100</code>
| Maximum number of diagnostics displayed in one file.
|-
| <code>hpl3.trace.server</code>
| <code>off</code>
| Controls language-server protocol logging.
|-
| <code>hpl3.launch.executable</code>
| Automatic
| Optional game executable override.
|-
| <code>hpl3.launch.user</code>
| <code>Dev</code>
| Developer user passed to the game.
|-
| <code>hpl3.launch.config</code>
| <code>config/main_init_dev.cfg</code>
| Developer configuration passed to the game.
|-
| <code>hpl3.launch.extraArgs</code>
| <code>[]</code>
| Additional arguments appended to the map-launch command.
|}

=== Troubleshooting ===

==== Completion is not displayed ====

* Confirm that the file language mode is '''HPL3 HPS'''.
* Remove any explicit <code>"*.hps": "cpp"</code> file association.
* Verify that the correct game and mod appear in the HPL3 status tooltip.
* Run '''HPL3: Rebuild Language Index'''.

==== The project is marked as degraded ====

Open '''View: Toggle Output''' and select the '''HPL3 Language Server''' channel.

A degraded project can be caused by:

* A missing or malformed <code>hps_api.hps</code>
* A malformed <code>entry.hpc</code>
* Missing or duplicate dependency UIDs
* Dependency cycles
* Invalid resource configuration

When API indexing is degraded, the extension suppresses unreliable unknown-engine-symbol diagnostics to avoid excessive false errors.

==== The wrong helper definition is selected ====

Use '''HPL3: Select Active Mod''' and confirm the intended top-level mod. The active mod shadows dependency and base-game resources using the same virtual path.

==== Run Map is unavailable ====

Confirm that:

* The current file is an HPS map script.
* A matching <code>.hpm</code> or <code>.map</code> asset exists.
* The map is reachable through the selected mod profile.
* The correct game root is selected.

=== Platform support ===

Windows is the officially supported platform.

Language-server features may work on Linux when <code>hpl3.gameRoot</code> points to a Steam/Proton installation. Linux is not currently tested, and '''Run Map''' is Windows-only because it directly detects and launches the Windows game executables.

=== Source code and bug reports ===

Source code, releases, and issue tracking are available at:

* [https://github.com/TiManGames/hpl3-language-tools TiManGames/hpl3-language-tools]
* [https://github.com/TiManGames/hpl3-language-tools/issues Report a bug or request a feature]

{{NavBar|HPL3/Scripting/Scripting_Guide/What is scripting in HPL3?|What is scripting in HPL3?|HPL3/Scripting/HPL3 Scripting Guide|HPL3 Scripting Guide|HPL3/Scripting/Scripting_Guide/Scripting Workflow and Structure|Scripting Workflow and Structure}}

[[Category:HPL3 Scripting]]
[[Category:English]]

Visual Studio Code

2026-07-30T22:18:15Z

TiMan:

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 and HPL3 mods.

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]]''

HPL3/SOMA/Third Party Tools

2026-07-30T22:17:41Z

TiMan: /* Programming Tools */

'''These tools have been created by third parties, some which are members of the community, and are not affiliated with Frictional Games.'''

{{CategoryHeader}}
{{CategoryNewcolumn}}

== Community-Made Tools ==
* [[HPL3/Third_Party_Tools/HPL3 Mod Manager|HPL3 Mod Manager]]
* [[HPL3/SOMA/Third_Party_Tools/SOMA Text Search Tool|SOMA Text Search Tool]]
* [[HPL3/Blender_HPL3_export_plugin|Blender HPL3 export plugin]]

== Programming Tools ==
* [[Visual Studio Code|Visual Studio Code]]
* [[CodeLite|CodeLite]]

{{CategoryNewcolumn}}

== 3D Design Tools ==
* [[Autodesk Maya|Autodesk Maya]]
* [[Modo|Modo]]
* [[Blender|Blender]]

== 2D Design Tools ==
* [[GIMP|GIMP]]
* [[Adobe Photoshop|Adobe Photoshop]]

== Audio Tools ==
* [[FMod Designer 2010|FMod Designer 2010]]
* [[Audacity|Audacity]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/SOMA/Audition/Lip Sync

2026-07-30T22:17:24Z

TiMan: Created page with "= Animation - Lipsync = === Introduction === This tutorial was written for anybody working on animations that want a character to automatically lipsync. Lipsyncing is a te..."

= Animation - Lipsync =

=== Introduction ===

This tutorial was written for anybody working on animations that want a character to automatically lipsync. Lipsyncing is a technique used to move the mouth of a character to match the dialogue it is speaking. How the mouth should move is calculated in the code using the voice recording of the dialogue as well as a written transcript. This takes the line and converts it into phonemic characters. These are then converted into visemes which are used to move the mouth. The visemes has to be created by hand and that is what this tutorial will detail.

=== Visemes ===

A viseme is a position that the mouth has when making a sound. We use a 3rd party imlementation from Annosoft. They have three different viseme mappings that can be used, each of different quality. The best quality comes from using 17 Visemes.

These pages show which visemes are needed and how to rig them.

[http://www.annosoft.com/docs/Visemes17.html http://www.annosoft.com/docs/Visemes17.html]

[http://www.annosoft.com/docs/Visemes12.html http://www.annosoft.com/docs/Visemes12.html]

[http://www.annosoft.com/docs/Visemes9.html http://www.annosoft.com/docs/Visemes9.html]

The visemes should be saved in "entity/animations/visemes/"

'''Setting up'''

When the visemes are created they need to be setup in the ModelEditor.

''' Open the entitiy file in the ModelEditor
''' Click on Entity Settings > Animations
''' Add a new animation for each Viseme
''' Select the .dae_anim file for a Viseme
''' Name the animation after the number of visemes and the order of the annosoft website documentation. Using the naming convention Visemes_<Quality>_<ID>
''' Ex) [http://www.annosoft.com/docs/Visemes17.html http://www.annosoft.com/docs/Visemes17.html] Frame 1 (AA) should be named Visemes_17_1
''' When all of the visems has been setup the engine takes care of the rest

=== Lipsync Tool ===

Can be used to edit the anno files. More to come…

HPL3/Particles/Working with Particles

2026-07-30T22:16:53Z

TiMan:

{{merge2|HPL2/Particle Systems}}
=Particle Systems=
General Parameters:

*'''Name''': Name for the PS. Should be unique for all objects in map.
*'''Active'''
*'''Position''': 3D Vector storing the position in world.
*'''Rotation''': 3D Vector storing the rotation. Will only be used if the Particle System uses local coordinates.
*'''Scale'''

Specific Parameters:

*'''Particle System file''': .ps file to be spawned.
*'''Color''': color that the PS will be tinted with.
*'''Fade at distance''': if active, the particles will be faded if the camera is either too close or too far away according to the following parameters.

<pre> Fading Full Color Fading
<) |----------|-------------------------|-----------|
Camera Min End Min Start Max Start Max End
</pre>

'''Min End''': close distance in which the particles will be completely faded out.
'''Min Start''': close distance in which the particles will start to fade.
'''Max Start''': far distance in which the particles will start to fade.
'''Max End''': far distance in which the particles will be completely faded out.

=Particle Systems EditMode=

This EditMode helps in creating Particle systems on the map. These can be used to simulate effects like fire, smoke and many more.

To create a Particle System, just click on the grid when this EditMode is active. This will create an "empty" particle system, meaning it is just a container and no real particles are shown (yet)
Optionally, there are two parameters one can set up prior to placing Particle Systems on maps. These are:

*'''PS File''': sets up the Particle System that the object will be created with, in a .ps file format that is created with the ParticleEditor. If a .ps file is selected here, then the created Particle System will not be a container, but a proper Particle System.
*'''Color''': just sets up the color parameter for the created Particle Systems.

Have into account that these options will be valid for objects created right after changing them, so any Particle System that is already created will keep its settings.

More on Particle Systems [[HPL2/Particle Systems|here]].

HPL3/Particles/Working with Particles

2026-07-30T22:16:40Z

TiMan: Created page with "{{merge2|HPL2/Particle Systems}} =Particle Systems= General Parameters: *'''Name''': Name for the PS. Should be unique for all objects in map. *'''Active''' *'''Position''':..."

HPL3/Particles/Particle General

2026-07-30T22:16:18Z

TiMan: Created page with "=== General === * '''Name''': The name of the emitter currently selected. * '''Max Particles''': The maximum number of particles that can be alive at once. When this limit is..."

=== General ===

* '''Name''': The name of the emitter currently selected.
* '''Max Particles''': The maximum number of particles that can be alive at once. When this limit is reached no more particles will be created.
* '''Particles per Second''': The number of particles per second that will be created.
* '''Start time offset''': Time offset in seconds before the emitter starts.
* '''Respawn dead particles''': If dead particles should be respawned.
* '''Warm up time''': Time that the emitter gets to warm up. This is useful when doing a a stream of something (like a fire or waterfall) and the particles should not be shown “starting up”.
* '''Pause''': A pause is a break during which no particles are created. Particles are updated though.
* '''Pause Length''': The length of the pauses, 0 and 0 means that there are no pauses.
* '''Pause Interval''': The length between pauses. 0 and 0 means that there are no pauses.
* '''Offset position''': How the emitter is offset relative to its starting position.
* '''Offset angle''': How the particle system is offset relative to its start angles.

HPL3/Particles/Emitter Management

2026-07-30T22:16:12Z

TiMan:

HPL3/Particles/Particle Collision

2026-07-30T22:15:56Z

TiMan: Created page with "=== Collision === * '''Use Collision''': If collision detection should be used. * '''Update Rate''': How many times a second collision is check for each particle. * '''Maximu..."

=== Collision ===

* '''Use Collision''': If collision detection should be used.
* '''Update Rate''': How many times a second collision is check for each particle.
* '''Maximum Collisions''': The maximum amount of collisions can have before dying.
* '''Bounce Amount''': How much of the speed is retained when bouncing. 0.5 means half of the speed. 2 means that the speed doubles when bouncing.

HPL3/Particles/Particle Rotation

2026-07-30T22:15:47Z

TiMan: Created page with "=== Rotation === * '''Use Particle Spinning''': If enabled, particles will rotate around themselves. * '''Spin Type''': Type for the particle spinning. Can be: ''' '''Constant..."

=== Rotation ===
* '''Use Particle Spinning''': If enabled, particles will rotate around themselves.
* '''Spin Type''': Type for the particle spinning. Can be:
''' '''Constant''': A value will be picked from the spin velocity range at random.
''' '''Movement''': The rotation will be linked to how fast the particle is moving.
* '''Particle spin velocity range (rad/s)''': Spin velocity for constant spin type.
* '''Use Revolution''': If enabled, particles will rotate around some axis.
* '''Revolution speed''': 3D Vector that will determine the axis and rotation speed for particles.

HPL3/Particles/Particle Color

2026-07-30T22:15:38Z

TiMan: Created page with "=== Color === '''NOTE''': all of the color channels have values from 0 -1. * '''Color''': This sets the color of the particle. * '''Fading''': Settings for fading the color...."

=== Color ===

'''NOTE''': all of the color channels have values from 0 -1.

* '''Color''': This sets the color of the particle.
* '''Fading''': Settings for fading the color. See foreword for fading.

=== Life ===

* '''Lifespan''': Time in seconds that the particle will live.
* '''Death Type''': type of death for the particles. Currently only age can be selected.
* '''PS created at death''': Particle system to be spawned when the particle dies.

HPL3/Particles/Particle Rendering

2026-07-30T22:15:25Z

TiMan: Created page with "=== Rendering === * '''Draw Type''': The different ways in which the particles can be draw to screen. ''' '''Point''': The particle is a point and will always be pointing tow..."

=== Rendering ===

* '''Draw Type''': The different ways in which the particles can be draw to screen.
''' '''Point''': The particle is a point and will always be pointing towards the camera.
''' '''Line''': The particle is aligned in the direction in which the particle is travelling.
* '''Multiply RGB with Alpha''': Some materials does not fade out the image when alpha is decreased (for example Additive) in this case it can be good to check this.
* '''Size''': The size of the particle. This is the value used in the fading.
* '''Size Fading''': See 1.2 for instructions on fading.

HPL3/Particles/Particle Movement

2026-07-30T22:15:18Z

TiMan: Created page with " === Movement === * '''Velocity type''': The way in which the starting velocity is generated. * '''Box velocity''': The same as box start but with velocity instead. * '''Sphe..."

=== Movement ===

* '''Velocity type''': The way in which the starting velocity is generated.
* '''Box velocity''': The same as box start but with velocity instead.
* '''Sphere Velocity''': The same as sphere start but with velocity instead.
* '''Coord system''': The way in which the particles are related to the world and the object the system is attached to (if any). In world all the particles have an individual postion that does change depending on the parent object. In local however the particle position is dependant on the parent object so if that the particle moves and turns along with the parent.
* '''Uses direction''': If the direction of the start velocity depends on the way the particle system is “facing” (with no rotation it faces up). This is useful for systems like steam where the system has a direction.
* '''Gravity Type''': The type of gravity being applied to the particles.
''' '''None''': No gravity it applied.
''' '''Vector''': The gravity acceleration is applied.
''' '''Centre''': The particles are drawn towards the centre of the particle system with Gravity Acceleration Y as acceleration.
* '''Gravity Acceleration''': Used differently according by the gravity type.
* '''Acceleration''': Acceleration applied to all bodies.
* '''Speed multiplier''': How much the speed is multiplied by each second. For example, 0.5 means that the speed halfed each second. 2 means it is doubled each second.
* '''Maximum speed''': The maximum speed that the particles can reach.

HPL3/Particles/Particle Start

2026-07-30T22:15:07Z

TiMan: Created page with "=== Start === * '''Start type''': Sets what method to use to generate the start position of the particles in the emitter. * '''Box start''': A box start is created using an x..."

=== Start ===

* '''Start type''': Sets what method to use to generate the start position of the particles in the emitter.
* '''Box start''': A box start is created using an x, y and z min and max value. The collection of particles will get the shape of a box.
* '''Sphere start''': The positions are generated using an angle interval and the min and max value for the radius. You can think of it like this; an arrow start pointing up. This arrow is then rotated around the X axis (red) using a value between min and max. After that the arrow is rotated by the y axis (blue). The arrow will now be pointing in a specific direction and in this direction a position is created at a distance from center according to a number generated from min/max radius.
[[File:spherestart.jpg]]

HPL3/Particles/Emitter Management

2026-07-30T22:14:41Z

TiMan: Created page with "== Emitter management controls == These controls help to add, duplicate and remove particle emitters. The Add button will create a new particle emitter and select it (i.e. pic..."

== Emitter management controls ==
These controls help to add, duplicate and remove particle emitters. The Add button will create a new particle emitter and select it (i.e. pick it in the combo box), the Copy button will create a copy emitter out of the selected one, and the Delete button will delete the selected emitter.

When a particle emitter is selected, all its parameters will be shown in the tab frame below.

== Emitter parameters tab frame ==

=== General ===

* '''Name''': The name of the emitter currently selected.
* '''Max Particles''': The maximum number of particles that can be alive at once. When this limit is reached no more particles will be created.
* '''Particles per Second''': The number of particles per second that will be created.
* '''Start time offset''': Time offset in seconds before the emitter starts.
* '''Respawn dead particles''': If dead particles should be respawned.
* '''Warm up time''': Time that the emitter gets to warm up. This is useful when doing a a stream of something (like a fire or waterfall) and the particles should not be shown “starting up”.
* '''Pause''': A pause is a break during which no particles are created. Particles are updated though.
* '''Pause Length''': The length of the pauses, 0 and 0 means that there are no pauses.
* '''Pause Interval''': The length between pauses. 0 and 0 means that there are no pauses.
* '''Offset position''': How the emitter is offset relative to its starting position.
* '''Offset angle''': How the particle system is offset relative to its start angles.

HPL3/Particles/Particle Editor View

2026-07-30T22:13:51Z

TiMan:

= Particle Editor =
The Particle Editor is used to create Particle Systems to be used in maps or entities.

== Foreword ==

=== Min and Max values ===
A lot of values in this editor have both a min and max. This means that when the value is applied to a particle a value between min and max is randomly selected.

=== Fading ===
Fading can be used to fade in and/or out some property like size or colour. The fading works like this. There are three relative values that are relative to the start value of the particle. The names for these values are start, middle and end and are used in that order. There are also two times that are relative to the life of the particle, for example if a particle has 2 seconds life time and the middle time is 0.5 then this occurs after 1 second (0.5 * 2). The first time is called middle time and this is when the start value is entirely faded from start to middle. The middle length is how long the middle value lasts. After middle time + middle length the middle value is faded to the end value.

== Overview ==
When run, the first screen we get to see is like this:

[[File:particle_editor.png]]

Each part of the screen has a specific function, as follows:

== Main Menu ==
This is a menu bar, just like in any other windowed application. Available options for this particular editor are as follows:

* '''File'''
''' '''New''': This command will reset the Particle System to an empty one, and the editor to a default state as well.
''' '''Open''': This will load a Particle System file (.ps) in the editor.
''' '''Save''': Use this to save your work to a file in disk. Will ask for a file name when no file has been created.
''' '''Save As''': This will also save your work, but will ask for a file name everytime it is called.
''' '''Open Recent''': This will show a list of up to 10 files that have been recently loaded or saved.
''' '''Quit''': This will exit the program.
* '''Edit'''
* '''View'''

HPL3/Particles/Particle Editor View

2026-07-30T22:13:31Z

TiMan: Created page with "= Particle Editor = The Particle Editor is used to create Particle Systems to be used in maps or entities. == Foreword == === Min and Max values === A lot of values in this..."

HPL3/Materials/Material Specific Variables

2026-07-30T22:12:09Z

TiMan: Blanked the page

HPL3/Materials/Types/Translucent

2026-07-30T22:12:02Z

TiMan: Created page with "= Translucent Material = == Overview == Here it will be explained how to set up an entity with a translucent material. There is a lot of differetn techniques and programs th..."

= Translucent Material =

== Overview ==

Here it will be explained how to set up an entity with a translucent material. There is a lot of differetn techniques and programs that can be used to make the images used in this tutorial, so the focus will be mainly on using the engine's tools.

== Steps ==

=== 1) Setting up the model. ===
First of all the model needs to be be set up and have a diffuse texture set to it (more info [[hpl3:engine:model_export#modelling|here]]). The file we have are: ''transbox.dae'' ''transbox.dds'' Now we open transbox.dae up in the modelviewer and will see: [[File:material_trans01.jpg]] The files we have are now:
''transbox.dae'' ''transbox.dds'' ''transbox.mat'' ''transbox.msh'' the ".mat"-file is generated by the modelviewer and is a solid material based upon the name of the diffuse texture (here "transbox"). Modelviewer can add further texture such as normalmaps, specular, etc if the files have the proper prefixes (for a list of those see [[hpl3:engine:materials#solid_diffuse|here]]). The "msh"-file is a binary version of the dae file that is much faster to load. No need to worry about that one in this tutorial.

=== 2) Changing to Translucent. ===
Now open up MaterialEditor (leave modelviewer open) and open "transbox.mat". Here change the type to "translucent" and the blend mode to "mul" (you can use other blend modes, but mul is often the best when dealing with translucent surfaces). [[File:material_trans02.jpg]] Chose "Save" in the file menu. You can now simply task switch to the modelviewer (no need to close and open) and the changes will appear). [[File:material_trans03.jpg]] 

=== 3) Adding Reflection ===
The material looks a bit more translucent, but there is still a lot more that can be done. The next thing is to add a cubemap that will form an environment map for the material. 
First of all a cubemap needs to be created and converted to the dds format. This is best done using ATI's CubeMapGen (found [http://developer.amd.com/archive/gpu/cubemapgen/pages/default.aspx here]) or a similar tool. When creating the normal, just use some environment that looks sort of like what the object can be found in and blur it a lot (as long as it looks good in the modelviewer, it does not matter that much). When generating the cubemap it is very, very important to use a an edge fix, and to use an generator that can do this for mipmaps, or else there will be ugly visible lines in the seams between the six faces. Also make sure that the dds file contains mipmaps! Cubemaps are placed in "textures\environment" and NOT in the same folder as the dae, mat, etc files! This because one cubemap can be used for many different materials. Name the environment map like this: [environment]_env, eg: "livingroom_env.dds" 
Now in the MaterialEditor, check the CubeMap checkbox and then select the cubemap you have created. You will now see that box has gotten a reflection: [[File:material_trans04.jpg]] You can now play around the the frensel properties to change how the reflection changes depedning on the slope of the surfaces. The default values are pretty good in most cases though. More importantly, if you have a rounded objects (unlike this cube) try changing the two RimLight parameters to get a nice glow around the edges that enchances the shape of the objects. Finally the AffectedByLightLevel parameter should be checked if you know that the object will be in an environment where the general light level change a lot. What it does is to make the opacity of the model depedning on the average light the model is in and makes it not seem glowing when in darkness. Can keep this off as default as it takes a bit cpu resources and turn on if it turns out it is needed.

=== 4) Adding Refraction ===
Still the model does not look as much as translucent as it could be. What you want to add then is refraction. To do this, simply check the boxe saying "Refraction". What this does is that it gives the background a bit of an offest simulating that light refracts through the material (not that visible on this cube). Also play with "RefractionScale" which changes how much the background is distorted (do not overdo this since the model might look strange up close if too high). [[File:material_trans05.jpg]] Switch to the Modelviewer (again no need to restart) and the effect is quite visible: [[File:material_trans06.jpg]]

Sometimes the geometry of the mesh is not enough to give proper refraction and in that case, you need to add a normalmap. So now the file "transbox_nrm.dds" is added to the same folder as transbox.dae, etc. Open the MaterialEditor, select NMap and pick the texture: [[File:material_trans07.jpg]] You also want to check the parameter "RefractionNormals". With this on, the normalmap normals are rotated according to mesh normals, creating a better refractive feel. In some cases this is not wanted, but for most objects it is! And as always simply save and task switch to the modelviewer to see the texture with your model: [[File:material_trans08.jpg]]

Note that refraction is quite demanding, especially when there are a lot of objects with it in view at the same time. So if you want to have lots of glass shards or similar, then skip it for them. For most objects it should be no problem. Also another trick is that whenever possible make sure that as many objects as possible are combined when they have refraction. For example, if a model has three windows, each with refraction, do NOT add these as three submeshes. Instead combine them all into one submesh, and that can lead to nice speed-ups!

HPL3/Materials/Engine Materials

2026-07-30T22:11:27Z

TiMan: Created page with "=== Materials === ---- === General === The size of texture simply means in relation to other textures of the material. 100% means that it is max size (which is normal whate..."

=== Materials ===

----

=== General ===

The size of texture simply means in relation to other textures of the material. 100% means that it is max size (which is normal whatever size diffuse) has, while 50% means half of the max, size and so on. This information just general outlines though. It is nothing that needs to be followed, but is good for optimization needs.

File format is also just a guideline, although some formats like 3DC (for luminence-alpha), are almost requirements.

The suffix means how the file name should be. The base for the name should always be the name of the mat file if possible (unless shared). Then prefix means: basename_[prefix].ext, for example: "mytexture_nrm.dds".

----

=== Mipmaps ===

All textures that can (all textures in the dds format basically) must have pregenerated mipmaps in them. In the exporter tool (like [http://code.google.com/p/nvidia-texture-tools/ Nvidia Texture Tools]) it should be possible to do this. Having mipmaps is crucial as it improves the graphical qualtiy and makes loading faster. Also, for all the compressed formats (which means pretty much all that are used) it is not possible generate mipmaps in the application, making it even more important that the created dds textures have mipmaps in them!

The filer used to generate the mipmaps is also important. Normally "box" filter is good enough, but when there are many smaller details, these can easily become too blurred or strange aliasing patterns might arise. It is then better to use something like "bessel", "cubic", "catrom" or similar. In the texture export tools there should be a list of these to chose from under mipmap generation. Best is to zoom out so it looks OK, and only if there are any strangeness do you have to think closer about what filter is being used. As said normally it is not a problem.

A list of all filters along with images of resizing can be found [http://www.wunderboy.org/images/articles/vtf_mipmap_filters4.jpg here]:
=== Optimizing ===

The engine works by having many different hard-coded material types, that are changed by setting different textures and changing variables. Depending on this, the engine will generate a fitting shader to do the job. Because of this, artists do not have to worry about optimizing their materials as much as if another system would be used. However, there are still optimizations needed. Here is a few basic guidelines:

* Never add a texture unless it adds to the final material. For example, do not use black specular, flat blue normal maps, and so on. It is almost always better to just not set the texture at all.
* For textures that only use alpha, it is a good idea to embed it in the alpha of a texture. That way a single texture can fill up two texture slots. However, take note that if a texture with alpha is used in many materials and/or can have a lower resolution than the one it is part of, it might be good to keep it separate.

----

=== Alpha ===

Some of the texture types below will have the channel as alpha. There are two ways of doing this texture:

# It can simply be the alpha channel for a texture. If you have a DDS texture remember that DXT1 only has alpha that is either 1 or 0, so only use this if you do not want any gradients. (This is for instance OK with transparency for the solid material that does not support gradients anyway.)
# Use a single channel (grayscale) texture. The engine will always load single channel texture as if the texture only consist of an alpha channel (even though the image editor might name it an red channel or similar).

If possible, it often is faster and saves space to have it as an alpha in a texture, so use that when possible.

----
=== Solid diffuse ===

==== Overview ====
This is the most common material used and is basically an all-round solid (as in non-transparent) surface shader. It works nicely for metals, plastics, wood, organic (that do not require anything special), etc.

Important Notes: * A material having alpha and parallax on a mesh that where IsOccluder is true, will NOT be displayed correctly.
* An mesh MUST be set with IsOccluder=true for the dissolve effect to work!

==== Blend Modes ====

Not used.

==== Variables ====

'''HeightMapScale''' | This controls the amount how much the max depth (pure white) will offset the pixel. '''HeightMapBias''' | Currently not used. 
'''FrenselBias''' | Bias for Fresnel term. values: 0-1. Higher means that more of reflection is seen when looking straight at object. '''FrenselPow''' | The higher the 'sharper' the reflection is, meaning that it is only clearly seen at sharp angles. 
'''AlphaDissolveFilter'''| Currently not used.

'''DetailUvMul''' | The amount the UV maps are multiplied with. The higer the more the detail maps are repeated '''DetailWeight_Diffuse''' | Weight for the diffuse detail. Valid values: 0 - 2.0 '''DetailWeight_Specular''' | Weight for the specular detail. Valid values: 0 - 2.0 '''DetailWeight_Normal''' | Weight for the normalmap detail. Valid values: 0 - 2.0 (inf really, but not recommended) '''DetailFadeStart''' | When the details start fading out
'''DetailFadeEnd''' | When details have completely faded out

'''SwayActive''' | If the model should sway according to wind properties. NOTE: Heightmap must be used to set the sway amount for each model part. '''SwayForceFieldAffected''' | If the model is affected by force fields '''SwayFreq''' | The frequency of the sway movement. '''SwayAmplitude''' | How much the sway offsets the model at maximum (in meters). '''SwaySpeed''' | The speed of the sway '''SwayOctaveMuls''' | The sway consists of the three (high - low) different freq movements, this is the factor for each. '''SwayYFreqMul''' | This can be used so that sway changes along the y-axis. The higher value the more change. 0=off '''SwayForceFieldMul''' | Factor for the force field induced sway. '''SwayForceFieldMax''' | The max offset (after adding factor) can that be added from a force field. 
'''IlluminationBrightness''' | The brightness of the illumination texture. Multiplies with the illumination map, used to make the illumination brighter than 1.0 
'''LiquidTrickleColor''' | The color and alpha of the liquid '''LiquidTrickleSpecular''' | Specular color and power of the liquid (RGB, Power). If set to (0,0,0,0) the original specular map value will be used '''LiquidTrickleLoopFade''' | If the liquid animation should loop and fade in again after it has faded out '''LiquidTrickleFadeSpeed''' | How fast the liquid fades in and then stays before fading out again. Unit is in seconds (Fade In, Fade Out) '''LiquidTrickleEdgeSize''' | The size of the normal map edge generated by the trickling liquid '''LiquidTrickleDryness''' | How long the generated liquid normal map should stay before drying back to the original normal map '''LiquidTrickleBlendMode''' | Which blend mode that should be used when combining the liquid with the color. Specular always uses Alpha blending. With Illumination blend mode the liquid is added to the illumination output 
==== Diffuse ====
'''Size:''' 100% '''Channels:''' RGB '''Type:''' 2D '''File format:''' dds, dxt1 or dxt5. (use dxt1 if it looks okay!) '''Suffix:''' None. This is simply the color and is needed for as good as all materials. Note that diffuse is a perfect texture for adding some other map (that only use alpha) in the Alpha channel. For example: Alpha, Height and Translucency map.

==== Normal map ====
'''Size:''' 100% (50% possible for very large and blurry features) '''Channels:''' G and Alpha (must use special exporter for this!) '''Type:''' 2D '''File format:''' dds, 3dc (aka DXN, BC5). '''Suffix:''' “nrm”. The normal map for the material and uses the standard format rgb = xyz and is in tangent space. Note that this needs to be converted to a format of XY only though!

==== Specular map ====
'''Size:''' 100% - 50% (50% should work in most cases, but 100% might be needed for slimy objects and similar) '''Channels:''' RGBA '''Type:''' 2D '''File format:''' dds, dxt5. '''Suffix:''' “spec”. The specular map handles the specular intensity and power for each pixel. The intensity uses the R,G and B channel and the power in the Alpha channel. Intensity sets the amount of specularity (for each color channel) applied to a pixel, the higher value of the channel, the higher intensity. Power sets the sharpness of the specular highlight, a low value give a dull and diffuse look, while a high value give a wet/shiny look.

==== Alpha ====
'''Size:''' 100% - 50% (the smaller version only if alpha features are very large) '''Channels:''' Alpha '''Type:''' 2D '''File format:''' tga, single channel '''Suffix:''' “alpha”. Sets the alpha for each texture and for any lit surface this is a simply 0 or 1 decision per pixel since a lit pixel can never be half transparent, only fully visible or invisible. Note that because of this, it is okay to use the Alpha channel of a DXT1 texture for this!

==== Height map ====
'''Size:''' 100% - 50% (depends on the amount of small details needed) '''Channels:''' Alpha '''Type:''' 2D '''File format:''' tga, single channel (greyscale). '''Suffix:''' “height”. ("sway" when used for sway) Height map is more like a depth map actually. White = largest depth, Black = no depth and this is important to remember when creating it. This map is also used for sway, so when sway is active, normal parallax does NOT work. During sway it act has a factor for the sway. Black = no sway, White = full sway and all inbetween for greyscale of course. So if doing a swaying plant, make it black at the base of the plant and whiter as it comes nearer the top.

==== Illumination map ====
'''Size:''' 100% - 50% (only use 100% if very sharp features are required. Most illumination then to be blurry) '''Channels:''' RGB '''Type:''' 2D '''File format:''' dds, dxt1. (dxt5 if alpha is required for extra map) '''Suffix:''' “illum”. This map will be added additively on top of the model when rendering and will not be affected by lighting. It is useful for creating glowing surfaces such as lightbulb, ember, etc. Like diffuse, Illumination is a perfect texture for adding some other map (that only use alpha) in the Alpha channel. For example: Alpha, Height and Translucency map. Especially so if the size of the other map is 50% or so (as this is normally what the illumination map is).

==== Dissolve Alpha Map ====
'''Size:''' 100% - 50% '''Channels:''' Alpha '''Type:''' 2D '''File format:''' tga, single channel (greyscale). '''Suffix:''' “diss_alpha”. When dissolving a mesh, this map sets how fast each part of the mesh does this. White = fastest, Black = slowest Because of the way rendering works, it is almost always best to have this as separate texture (and as alpha inside another)

==== Environment Map (CubeMap) ====
'''Size:''' NA, cubemaps take a lot of memory, so try and keep them small. Usually they are blurry and can be kept very small. '''Channels:''' RGB '''Type:''' CubeMap '''File format:''' dds, dxt1 or dxt5 cube (as the map is usually blurry and distorted, dx1 should work fine in most cases) '''Suffix:''' “env”. This will apply a cube to the mesh as if it is was reflecting it (hence called "environment map").

==== Environment Alpha Map (CubeMapAlpha) ====
'''Size:''' 100% - 50% '''Channels:''' Alpha '''Type:''' 2D '''File format:''' tga, single channel (greyscale). '''Suffix:''' “env_alpha”. Determines how much of each pixel on mesh should reflect. White=max reflection, Black = no reflection.

==== Detail Diffuse Map ====
'''Size:''' NA, this is entirely up to how the texture is repeated '''Channels:''' RGB '''Type:''' 2D '''File format:''' dds, dxt1 '''Suffix:''' “detail_diff”. A detail map is special in that it uses differnt UV coordinates from the rest of the textures (see variables). This map blends with the diffuse and specular (each according to weights, see variables section). The way it mixes, Grey (127) means that nothing is changed, darker (126 or below) makes the result darker, and brighter (128 or above) makes the result brighter). There is a variable for fading this out at a distance, but in some special cases this might not look good. In that case use dxt5 and have custom mipmaps that fade to gray in an appropriate way. Only use this if really needed though!

==== Detail Normal Map ====
'''Size:''' NA, this is entirely up to how the texture is repeated '''Channels:''' G and Alpha (must use special exporter for this!) '''Type:''' 2D '''File format:''' dds, 3dc (aka DXN, BC5). '''Suffix:''' “detail_nrm”. Detail normal works basically like the diffuse version, but on the normal map.

==== Translucency Map ====
'''Size:''' 100% - 50% '''Channels:''' Alpha '''Type:''' 2D '''File format:''' tga, single channel (greyscale). '''Suffix:''' “trans”. This allows part of the texture to shine through to the backside when lit. This is good for thin organic shapes like nose-wings, leaves and fish-fins. Note that for this to work, the mesh must not cast a shadow or it must be thin enough (how thin depends on shadow settings). White means that all light from the front comes out back and black means that no light does.

==== Liquid Map ====
'''Size:''' 100% - 25% '''Channels:''' G and Alpha (must use special exporter for this!) '''Type:''' 2D '''File format:''' dds, 3dc (aka DXN, BC5), tga for high quality. '''Suffix:''' “liquid”. This texture shows how liquid should fade in, move and fade out over an object. The red channel contains a mask for how liquid should fade in on the image, the brighter a pixel is the earlier the liquid will cover it. The green channel contains a mask for how the liquid should fade out. If a 3dc compressed texture produces poor results then a RGBA tga should be used with the red channel stored in the alpha channel and the green channel stored in the blue channel.
If the liquid is very thin then the mip-map filter should be set to "Point" when exporting the texture.

----
=== Translucent ===

==== Overview ====
This material is used for any transparent surface, such as glass, some forms of water, etc. It is generally not affected by lighting and when, only mildly so by setting the variable AffectedByLightLevel to true (more on that below).

==== Blend Modes ====

All available blend modes work for Translucent.

==== Variables ====

'''Refraction''' | If the material has refraction (distortion of bg). Uses NMap and/or normals of mesh. '''RefractionEdgeCheck''' | If true, there is no bleeding with foreground objects, but takes some extra power. This usually makes object look a lot better so should generally be used, but have in mind that removing it when there are several object with refraction, it can speed things up quite a bit. '''RefractionNormals''' | If normals should be used when refracting. If no NMap is set this is forced true! If this is false (and NMap is set), then the material will only read from the NMap and use that as distortion. This can be quite nice fort certain effects such as animated water, magical portals and the like. '''RefractionScale''' | The amount refraction offsets the background. 
'''FrenselBias''' | Bias for Fresnel term. values: 0-1. Higher means that more of reflection is seen when looking straight at the surface. '''FrenselPow''' | The higher the 'sharper' the reflection is, meaning that it is only clearly seen at sharp angles. '''RimLightMul''' | The amount of rim light based on the reflection. This gives an edge to the object. Values: 0 - inf (although 1.0f should be used for max. '''RimLightPow''' | The sharpness of the rim lighting. 
'''AffectedByLightLevel''' | The the material alpha is affected by the light level. This is especially useful for objects that are in an environment where the lightlevel changes. How this works that for each light that intersect the Bounding box of the mesh, a light level variable is increased (according to color and attenuation). The final light level variable is then used to control the alpha. 
'''SwayActive''' | If the model should sway according to wind properties. NOTE: Heightmap must be used to set the sway amount for each model part. '''SwayForceFieldAffected''' | If the model is affected by force fields '''SwayFreq''' | The frequency of the sway movement. '''SwayAmplitude''' | How much the sway offsets the model at maximum (in meters). '''SwaySpeed''' | The speed of the sway '''SwayOctaveMuls''' | The sway consists of the three (high - low) different freq movements, this is the factor for each. '''SwayYFreqMul''' | This can be used so that sway changes along the y-axis. The higher value the more change. 0=off '''SwayForceFieldMul''' | Factor for the force field induced sway. '''SwayForceFieldMax''' | The max offset (after adding factor) can that be added from a force field. 
'''ScrollingNoiseActive''' | If the alpha of the model should be affected by noise moving in the air '''ScrollingNoiseSpeed''' | The speed of the scrolling noise '''ScrollingNoiseScale''' | The size of the scrolling noise particles '''ScrollingNoiseDetail''' | How detailed the scrolling noise is. The higher the value the more the alpha gets affected 
'''AngleFadeActive''' | If the triangles should fade out at steep viewing angles 
'''SoftParticleActive''' | Removes hard edges where the particle intersects geometry '''SoftPartSphereBillboard''' | If the billboard should be thicker in the middle and thinner near the edges (Only works for billboards '''SoftPartThickness''' | The percived thickness of the particle, measured in meters '''SoftPartAlphaBasedThickness''' | The percived thickness of the particle based on the alpha channel of the particle, measured in meters '''SoftPartDepthBias''' | Moves the soft particle closer to or further away from the camera (Negative value only work for point billboards) 
'''LiquidTrickleColor''' | The color and alpha of the liquid '''LiquidTrickleLoopFade''' | If the liquid animation should loop and fade in again after it has faded out '''LiquidTrickleFadeSpeed''' | How fast the liquid fades in and then stays before fading out again. Unit is in seconds (Fade In, Fade Out) '''LiquidTrickleEdgeSize''' | The size of the normal map edge generated by the trickling liquid (Only used with refraction or EnvMap) '''LiquidTrickleDryness''' | How long the generated liquid normal map should stay before drying back to the original normal map (Only used with refraction or EnvMap) 
==== Diffuse Map ====
'''Size:''' 100% '''Channels:''' RGB '''Type:''' 2D '''File format:''' dds, dxt1 or dxt5. (use dxt1 if it looks okay!) '''Suffix:''' None. This is simply the color and is needed for as good as all materials. Note that diffuse is a perfect texture for adding some other map (that only use alpha) in the Alpha channel. For example: Cube Alpha map..

==== Normal Map ====
'''Size:''' 100% (50% possible for very large and blurry features) '''Channels:''' G and Alpha (must use special exporter for this!) '''Type:''' 2D '''File format:''' dds, 3dc (aka DXN, BC5). '''Suffix:''' “nrm”. Instead of changing the way light is shaded (like with solid material), here the normal map is used to distort the background (if refraction is set to true) and/or to change the way reflection is calculated. The normal map for the material and uses the standard format rgb = xyz and is in tangent space. Note that this needs to be converted to a format of XY only though! 
==== Environment Map (CubeMap) ====
'''Size:''' NA, cubemaps take a lot of memory, so try and keep them small. Usually they are blurry and can be kept very small. '''Channels:''' RGB '''Type:''' CubeMap '''File format:''' dds, dxt1 or dxt5 cube (as the map is usually blurry and distorted, dx1 should work fine in most cases) '''Suffix:''' “env”. This will apply a cube to the mesh as if it is was reflecting it (hence called "environment map").

==== Environment Alpha Map (CubeMapAlpha) ====
'''Size:''' 100% - 50% '''Channels:''' Alpha '''Type:''' 2D '''File format:''' tga, single channel (greyscale). '''Suffix:''' “env_alpha”. Determines how much of each pixel on mesh should reflect. White=max reflection, Black = no reflection.

==== Height map ====
'''Size:''' 100% - 50% (depends on the amount of small details needed) '''Channels:''' Alpha '''Type:''' 2D '''File format:''' tga, single channel (greyscale). '''Suffix:''' “sway” (do NOT use "height"). This map is used for sway, so when sway is active and NOT for any parallax stuff. It act as a factor for the sway. Black = no sway, White = full sway and all in between for greyscale of course. So if doing a swaying plant, make it black at the base of the plant and whiter as it comes nearer the top.

==== Liquid Map ====
'''Size:''' 100% - 25% '''Channels:''' G and Alpha (must use special exporter for this!) '''Type:''' 2D '''File format:''' dds, 3dc (aka DXN, BC5), tga for high quality. '''Suffix:''' “liquid”. This texture shows how liquid should fade in, move and fade out over an object. The red channel contains a mask for how liquid should fade in on the image, the brighter a pixel is the earlier the liquid will cover it. The green channel contains a mask for how the liquid should fade out. If a 3dc compressed texture produces poor results then a RGBA tga should be used with the red channel stored in the alpha channel and the green channel stored in the blue channel.
If the liquid is very thin then the mip-map filter should be set to "Point" when exporting the texture.

----
----
=== Decal ===

==== Overview ====
Decals work a bit different from other materials in that they never write to the Z-buffer. Instead they simply write to the renderers G-buffer directly and what this means is that they need have have some solid geometry behind them to be visible. This make them useful as a sort clutter to add to add extra details. As the resulting image is affected by lighting it can be easily used to add dirt to floor, blood stainds, etc.

Important notes:
* The material require Alpha blend mode if normalmaps shall work!

==== Blend Modes ====

All available blend modes work for Decal. However, alpha blending mode is best (if not needed!) to use if anything else but diffuse map is in the material.

==== Variables ====

'''HeightMapScale''' | The scale of the height map. '''HeightMapBias''' | Not used. 
'''FrenselBias''' | Not used. '''FrenselPow''' | Not used. 
'''DetailUvMul''' | The amount the UV maps are multiplied with. The higer the more the detail maps are repeated '''DetailWeight''' | Weight for the diffuse detail. Valid values: 0 - 2.0 '''DetailFadeStart''' | When the details start fading out. '''DetailFadeEnd''' | When details have completely faded out 
==== Diffuse Map ====
'''Size:''' 100% '''Channels:''' RGB '''Type:''' 2D '''File format:''' dds, dxt1 or dxt5. (use dxt1 if it looks okay!) '''Suffix:''' None. This is simply the color and is needed for as good as all materials. Note that diffuse is a perfect texture for adding some other map (that only use alpha) in the Alpha channel. For example: Cube Alpha map..

==== Normal Map ====
'''Size:''' 100% (50% possible for very large and blurry features) '''Channels:''' G and Alpha (must use special exporter for this!) '''Type:''' 2D '''File format:''' dds, 3dc (aka DXN, BC5). '''Suffix:''' “nrm”. Instead of changing the way light is shaded (like with solid material), here the normal map is used to distort the background (if refraction is set to true) and/or to change the way reflection is calculated. The normal map for the material and uses the standard format rgb = xyz and is in tangent space. Note that this needs to be converted to a format of XY only though! 
==== Specular Map ====
'''Size:''' 100% - 50% (50% should almost always work) '''Channels:''' RGB '''Type:''' 2D '''File format:''' dds, dxt1 or dxt5 '''Suffix:''' “spec”. This will only apply the specular color/intensity and NOT the power. Because of this only 3 channels are needed!

==== Height Map ====
'''Size:''' 100% - 50% (depends on the amount of small details needed) '''Channels:''' Alpha '''Type:''' 2D '''File format:''' tga, single channel (greyscale). '''Suffix:''' “height”. Height map is more like a depth map actually. White = largest depth, Black = no depth and this is important to remember when creating it.

==== Detail Diffuse ====
'''Size:''' NA, this is entirely up to how the texture is repeated '''Channels:''' RGB '''Type:''' 2D '''File format:''' dds, dxt1 '''Suffix:''' “detail_diff”. A detail map is special in that it uses differnt UV coordinates from the rest of the textures (see variables). This map blends with the diffuse and specular (each according to weights, see variables section). The way it mixes, Grey (127) means that nothing is changed, darker (126 or below) makes the result darker, and brighter (128 or above) makes the result brighter). There is a variable for fading this out at a distance, but in some special cases this might not look good. In that case use dxt5 and have custom mipmaps that fade to gray in an appropriate way. Only use this if really needed though!

----
=== Water ===

==== Overview ====

Water is a special shader that not only can render the world reflection, but also contain a special algorithm to simulate ripples.

Important notes: * When using world refection, it is extremely demanding, so make sure there is not more than one visible at any time.
* Must be applied to a flat (or at least almost completely flat) and one-sided mesh.

==== Variables ====

'''RefractionScale''' The amount reflection and refraction is offset by ripples in water.

'''FrenselBias''' Bias for Fresnel term. values: 0-1. Higher means that more of reflection is seen when looking straight at object.

'''FrenselPow''' The higher the 'sharper' the reflection is, meaning that it is only clearly seen at sharp angles.

'''WaveSpeed''' The speed of the waves.

'''WaveAmplitude''' The size of the waves.

'''WaveFreq''' The frequency of the waves.

'''ReflectionFadeStart''' Where the reflection starts fading.

'''ReflectionFadeEnd''' Where the reflection stops fading. 0 or less means no fading.

'''HasReflection''' If a reflection should be shown or not.

'''OcclusionCullWorldReflection''' If occlusion culling should be used on reflection.

'''LargeSurface''' If the water will cover a large surface and will need special sorting when rendering other transperant objects

'''HasVertexWaves"''' If the vertices are animated.

'''VertexWaveSpeed''' The speed of the vertex waves.

'''VertexWaveAmplitude''' The size of the vertex waves.

'''VertexWaveFreq''' The frequency of the vertex waves.

'''FadeWhenShallowMul''' This determines when the water should start fading when in shallow water. In meters.

'''FadeWhenShallowPow''' How fast the shallow water drops off, higher means faster, lower means slower.

==== Blend Modes ====

A modulative blend mode is forced.

==== Diffuse Map ====
'''Size:''' 100% '''Channels:''' RGB '''Type:''' 2D '''File format:''' dds, dxt1 or dxt5. (use dxt1 if it looks okay!) '''Suffix:''' None. This is the basic texture that act as a base for the water surface. It is always modulatively blended with the background.

==== Normal Map ====
'''Size:''' 100% (50% possible for very large and blurry features) '''Channels:''' G and Alpha (must use special exporter for this!) '''Type:''' 2D '''File format:''' dds, 3dc (aka DXN, BC5). '''Suffix:''' “nrm”. Instead of changing the way light is shaded (like with solid material), here the normal map is used to distort the background (if refraction is set to true) and/or to change the way reflection is calculated. The normal map for the material and uses the standard format rgb = xyz and is in tangent space. Note that this needs to be converted to a format of XY only though!

==== Environment Map (CubeMap)====
'''Size:''' NA, cubemaps take a lot of memory, so try and keep them small. Usually they are blurry and can be kept very small. '''Channels:''' RGB '''Type:''' CubeMap '''File format:''' dds, dxt1 or dxt5 cube (as the map is usually blurry and distorted, dx1 should work fine in most cases) '''Suffix:''' “env”. This will apply a cube to the mesh as if it is was reflecting it (hence called “environment map”). It will be used instead of the world reflection, thus making the water rendering ALOT faster!

HPL3/Materials

2026-07-30T22:11:21Z

TiMan: /* Getting Started */

{{constructionNotice|This category is undergoing major editing, as information about different articles is still being gathered and researched. More pages and information will gradually be added.}}

'''This category deals with the HPL3 Material Editor and deals with creating and using materials.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/Materials/Materials Overview|Materials Overview]]
* [[HPL3/Materials/Engine Materials|Engine Materials]]

== General ==
* [[HPL3/Materials/Working with Materials|Working with Materials]]
* [[HPL3/Materials/Texture Maps|Texture Maps]]
* [[HPL3/Materials/Physics Material|Physics Material]]

== Material Editor ==
* [[HPL3/Materials/Materials Editor View|Materials Editor View]]
* [[HPL3/Materials/UV Animations|UV Animations]]
* [[HPL3/Materials/Texture Units|Texture Units]]
* [[HPL3/Materials/Material Specific Variables|Material Specific Variables]]

{{CategoryNewcolumn}}

== Material Types ==
* [[HPL3/Materials/Types/Decal|Decal]]
* [[HPL3/Materials/Types/Projected UV|Projected UV]]
* [[HPL3/Materials/Types/Solid Diffuse|Solid Diffuse]]
* [[HPL3/Materials/Types/Terrain|Terrain]]
* [[HPL3/Materials/Types/Terrain Decal|Terrain Decal]]
* [[HPL3/Materials/Types/Translucent|Translucent]]
* [[HPL3/Materials/Types/Water|Water]]

== Blending Modes ==
* [[HPL3/Materials/Blending Modes/Add|Add]]
* [[HPL3/Materials/Blending Modes/Mul|Mul]]
* [[HPL3/Materials/Blending Modes/Mulx2|Mulx2]]
* [[HPL3/Materials/Blending Modes/Alpha|Alpha]]
* [[HPL3/Materials/Blending Modes/PremulAlpha|PremulAlpha]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/Materials/Material Specific Variables

2026-07-30T22:10:44Z

HPL3/Materials

2026-07-30T22:10:24Z

TiMan: /* Material Editor */

{{constructionNotice|This category is undergoing major editing, as information about different articles is still being gathered and researched. More pages and information will gradually be added.}}

'''This category deals with the HPL3 Material Editor and deals with creating and using materials.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/Materials/Materials Overview|Materials Overview]]

== General ==
* [[HPL3/Materials/Working with Materials|Working with Materials]]
* [[HPL3/Materials/Texture Maps|Texture Maps]]
* [[HPL3/Materials/Physics Material|Physics Material]]

== Material Editor ==
* [[HPL3/Materials/Materials Editor View|Materials Editor View]]
* [[HPL3/Materials/UV Animations|UV Animations]]
* [[HPL3/Materials/Texture Units|Texture Units]]
* [[HPL3/Materials/Material Specific Variables|Material Specific Variables]]

{{CategoryNewcolumn}}

== Material Types ==
* [[HPL3/Materials/Types/Decal|Decal]]
* [[HPL3/Materials/Types/Projected UV|Projected UV]]
* [[HPL3/Materials/Types/Solid Diffuse|Solid Diffuse]]
* [[HPL3/Materials/Types/Terrain|Terrain]]
* [[HPL3/Materials/Types/Terrain Decal|Terrain Decal]]
* [[HPL3/Materials/Types/Translucent|Translucent]]
* [[HPL3/Materials/Types/Water|Water]]

== Blending Modes ==
* [[HPL3/Materials/Blending Modes/Add|Add]]
* [[HPL3/Materials/Blending Modes/Mul|Mul]]
* [[HPL3/Materials/Blending Modes/Mulx2|Mulx2]]
* [[HPL3/Materials/Blending Modes/Alpha|Alpha]]
* [[HPL3/Materials/Blending Modes/PremulAlpha|PremulAlpha]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/Materials/Materials Editor View

2026-07-30T22:10:16Z

TiMan: Created page with "= Material Editor = The Material Editor helps out in creating new materials to be used in games. It can be run as a standalone app or can be invoked from file inputs in othe..."

= Material Editor =

The Material Editor helps out in creating new materials to be used in games. It can be run as a standalone app or can be invoked from file inputs in other editors when pressing the '+' button.

== Overview ==

When run, the first screen we get to see is like this:

[[File:material_editor.png]]

Each part of the screen has a specific function, as follows:

== Main Menu ==

This is a menu bar, just like in any other windowed application. Available options for this particular editor are as follows:

''' '''File'''
'''* '''New''': This command will reset the material to an empty one, and the editor to a default state as well.
'''* '''Open''': This will load a map file in the editor.
'''* '''Save''': Use this to save your work to a file in disk. Will ask for a file name when no file has been created.
'''* '''Save As''': This will also save your work, but will ask for a file name everytime it is called.
'''* '''Quit''': This will exit the program.
== General Settings ==

This group contains inputs to control basic properties for the currently edited material.

''' '''Material Type''': This combo box will show the available engine material types. Currently these are:
'''* [[hpl3:engine:materials#decal|Decal]]: set this type when you want to create a material to be used by regular decals.
'''* [[hpl3:engine:materials#projecteduv|ProjectedUV]]: this material type does a normal projection of textures over objects.
'''* [[hpl3:engine:materials#soliddiffuse|Soliddifuse]]: use this for your regular solid objects.
'''* [[hpl3:engine:materials#terrain|Terrain]]: this type applies to the materials you will paint on a terrain.
'''* [[hpl3:engine:materials#terraindecal|Terraindecal]]: special type of material only to be used by terrain decals.
'''* [[hpl3:engine:materials#translucent|Translucent]]: for non opaque objects.
'''* [[hpl3:engine:materials#water|Water]]: to simulate liquid objects.
''' '''Depth Test''': if the material should be affected by depth test.
''' '''Blend mode''': blending mode to be used by the material.
''' '''Physics Material''': the physics material that will be associated to this material. For example, if you create a metallic looking material, it should be logical to associate it to a metal physics material (these being defined in the materials.cfg file located in the redist folder)
''' '''UV SubDivisions''': this sets up in how many parts the way the material will be split
== UV Animation Settings ==

This group contains controls to add and edit UV texture coordinate animations. Displacements, rotations, etc can be done using these.

''' '''UV Animation''': currently selected animation. Any edition will be done on this particular one.
''' '''Create''' / '''Delete'''buttons: will add a new animation / remove the currently selected one.
''' '''Anim Type''': animation type for the current animation. Possible values are:
'''* '''Translate''': will perform a linear displacement over the texture along the given axis and at the given speed.
'''* '''Sin''': will add an oscillating movement over the texture along the given axis, with the given amplitude and at the given speed.
'''* '''Rotate''': will rotate the texture around the selected axis and at the given speed.
''' '''Axis''' / '''Speed''' / '''Amplitude''': used to set the parameters used for the previously explained setting.
== Texture Units ==

This group is one vital part of the material edition process. All texture data that is going to be used by the material in the engine will be set here. It is divided in two different parts:

''' '''Available Texture Units''': here we will see a list of the texture units that this material can use. If you want a material to use a determinate unit, you need to enable it in this list. To do so, just check the box right at the side of it. Each type of material will show its own set of units, see each material type for details.
''' '''Texture Unit Panels''': here we will see details for every texture unit that we have enabled from the available units listing. Along with a thumbnail, we will have the following inputs:
'''* '''File''': texture file for the unit. Must be in a valid format (jpg, png, bmp…)
'''* '''Wrap Mode''': this will set the texture behaviour when the surface it is applied onto has texture coordinates that exceed the 0.0-1.0 range. Available modes are
'''''' '''Repeat'''
'''''' '''Clamp'''
'''''' '''ClampToEdge'''
'''''' '''ClampToBorder'''
'''* '''Use Mip Maps''': sets if MipMapping should be enabled for the texture.
'''* '''Animation Mode''': sets if the texture data should be loaded as an animation. A special formatting on file names is required for this to work. Available modes are:
'''''' '''None''': no animation at all.
'''''' '''Loop''': the animation will show over and over, "rewinding" itself everytime the end is reached.
'''''' '''Oscillate''': the animation will play forward and then backwards when the end is reached.
'''* '''Frame Time''': time in seconds that frames will be displayed.
== Preview Window ==

This window will show a realtime preview of how the material would look ingame. Following there is a description of each control:

''' '''Viewport''': the actual material showcase. It should show a simple model using the material, a background and two lights. The current point of view can be controlled with the mouse. Left mouse button + movement will orbit the camera around the model, scrolling wheel up and down will zoom in and out respectively. Pressing the right mouse button + movement will move one of the lights around.
''' '''Model''': this combobox will show a set of preview models that you can select. Currently available there is a Box, a Cylinder, a Sphere and a Plane.
''' '''Rotate Model''': when checked, the model will rotate around its own Y axis (upward one).
''' '''Background Type''': use this to select a cubemapped background or a flat colored one.
''' '''Cubemap File''': background file that will be shown when the cubemap background type is selected.
''' '''Background Color''': color that will be shown when the flat background type is selected.
''' '''Fixed Light Color''': diffuse color for the non-movable light.
''' '''Movable Light Color''': diffuse color for the moveable light.
== Material Specific Variables ==

This group will show controls that are specific to a material type. Descriptions for them should show when moving the mouse over them.

HPL3/SOMA/Entities

2026-07-30T22:02:32Z

TiMan: /* General */

{{constructionNotice|This category and its sub-pages are undergoing major editing, as some information in this category and all the sub pages is currently in the process of being formatted or re-written from scratch to achieve a higher standard of formatting, or not everything is yet available. More pages and information will gradually be added.}}

'''This category deals with the HPL3 Model Editor, entities and related topics.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/Entities/Entities Overview|Entities Overview]]

== General ==
* [[HPL3/Entities/Model Editor Controls|Model Editor Controls]]
* [[HPL3/Entities/Model Editor View|Model Editor View]]
* [[HPL3/Entities/Model Editor Preferences|Model Editor Preferences]]
* [[HPL3/Entities/Entity Settings|Entity Settings]]
* [[HPL3/Entities/Entity Notes|Entity Notes]]
* [[HPL3/Entities/Entity Mesh|Entity Mesh]]
* [[HPL3/Entities/Entity Rig|Entity Rig]]
* [[HPL3/Entities/Entity Types|Entity Types]]

== Model Preview / Animations ==
* [[HPL3/Entities/Model Preview Settings|Model Preview Settings]]
* [[HPL3/Entities/Adding Animations to Entities|Adding Animations to Entities]]

{{CategoryNewcolumn}}

== Physics Bodies ==
* [[HPL3/Entities/Working with Physics Bodies|Working with Physics Bodies]]
* [[HPL3/Entities/Physics Body Properties|Physics Body Properties]]

== Joints ==
* [[HPL3/SOMA/Entities/Working with Joints|Working with Joints]]

== Shapes ==
* [[HPL3/Entities/Working with Shapes|Working with Shapes]]

{{CategoryEnd}}

__NOTOC__

[[Category:English]]
[[Category:Entry pages]]

HPL3/Entities/Entity Settings

2026-07-30T22:02:12Z

TiMan: Created page with "= Entity Class window = With this window, one can set up properties for the entity. First, a class shall be picked from the combo box at the top of the window. When this is do..."

= Entity Class window =
With this window, one can set up properties for the entity. First, a class shall be picked from the combo box at the top of the window. When this is done, a list of variables will appear below them.

[[File:window_entityclass.png]]

If defined, you can get information on a variable by moving the mouse over it.

[[File:window_entityclass_tooltip.png]]

NOTE: These variables are game-specific.

HPL3/Entities/Entity Rig

2026-07-30T22:00:58Z

TiMan: Created page with "= Bones = If the imported mesh has a skeleton, its component bones will be created along with the submeshes. Subentities can be attached to bones. General parameters: * '''Na..."

= Bones =
If the imported mesh has a skeleton, its component bones will be created along with the submeshes. Subentities can be attached to bones.

General parameters:
* '''Name''': Name of the bone. Cannot be edited.

Attachments Tab:

Just like with bodies, stuff can be attached to a bone. To do so, just set up the filter and press the attach button, then click on objects you want to attach.

HPL3/SOMA/Entities

2026-07-30T21:59:59Z

TiMan: /* Joints */

{{constructionNotice|This category and its sub-pages are undergoing major editing, as some information in this category and all the sub pages is currently in the process of being formatted or re-written from scratch to achieve a higher standard of formatting, or not everything is yet available. More pages and information will gradually be added.}}

'''This category deals with the HPL3 Model Editor, entities and related topics.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/Entities/Entities Overview|Entities Overview]]

== General ==
* [[HPL3/Entities/Model Editor Controls|Model Editor Controls]]
* [[HPL3/Entities/Model Editor View|Model Editor View]]
* [[HPL3/Entities/Model Editor Preferences|Model Editor Preferences]]
* [[HPL3/Entities/Model Editor Outline|Model Editor Outline]]
* [[HPL3/Entities/Entity Settings|Entity Settings]]
* [[HPL3/Entities/Entity Notes|Entity Notes]]
* [[HPL3/Entities/Entity Mesh|Entity Mesh]]
* [[HPL3/Entities/Entity Rig|Entity Rig]]
* [[HPL3/Entities/Entity Types|Entity Types]]

== Model Preview / Animations ==
* [[HPL3/Entities/Model Preview Settings|Model Preview Settings]]
* [[HPL3/Entities/Adding Animations to Entities|Adding Animations to Entities]]

{{CategoryNewcolumn}}

== Physics Bodies ==
* [[HPL3/Entities/Working with Physics Bodies|Working with Physics Bodies]]
* [[HPL3/Entities/Physics Body Properties|Physics Body Properties]]

== Joints ==
* [[HPL3/SOMA/Entities/Working with Joints|Working with Joints]]

== Shapes ==
* [[HPL3/Entities/Working with Shapes|Working with Shapes]]

{{CategoryEnd}}

__NOTOC__

[[Category:English]]
[[Category:Entry pages]]

HPL3/SOMA/Entities/Working with Joints

2026-07-30T21:59:51Z

TiMan: Created page with "= Joints = Joints are used to constrain the movement between to bodies. They are a very powerful tool and can be used to do a lot of stuff such as lamps that can sway back and..."

= Joints =
Joints are used to constrain the movement between to bodies. They are a very powerful tool and can be used to do a lot of stuff such as lamps that can sway back and forth, drawers that can be interacted with and even a car with wheels and suspenders.

All joints are made up from an anchor (also called pivot point) and an axis (also called pin direction), these have different meanings for the different joint types and describe the constraint. All bodies also have some limits to limit the constraint. If all of these values are set to 0 the limit is disabled. It can also be set if the two bodies on the joint will collide or not.

General Parameters:
* '''Name'''
* '''Position'''
* '''Rotation'''

Base Joint Parameters:
* '''Set Parent Body button''': Press and click on a body to set it as parent body for the joint.
* '''Set Child Body button''': Press and click on a body to set it as child body for the joint. Note that a joint must always have a child body.
* '''Sticky Min Limit'''
* '''Sticky Max Limit'''
* '''Limit Step Count'''
* '''Breakable''': Set if the joint should break.
* '''Break Force''': Force that should be applied on the joint for it to break (if Breakable is set).

Joint Sound Parameters:
* '''Move Type'''
* '''Move Sound'''
* '''Min Speed'''
* '''Min Freq'''
* '''Min Freq Speed'''
* '''Min Volume'''
* '''Max Speed'''
* '''Max Freq'''
* '''Max Freq Speed'''
* '''Max Volume'''
* '''Middle Speed'''
* '''Middle Volume'''
* '''Break Sound'''
* '''Min Limit Sound'''
* '''Min Speed'''
* '''Max Speed'''
* '''Max Limit Sound'''
* '''Min Speed'''
* '''Max Speed'''

Specific Parameters for Ball Joint:

[[ball-and-socket.jpg]]

* '''Max Cone Angle''': This is the maximum angle between Body1(Parent) and the axis. Has value from 0 – 180.
* '''Max Twist Angle''': This is the maximum angle that bodies can twist relative to each other. Has a value from 0 – 180.

Specific Parameters for Hinge Joint:

[[hinge.jpg]]

* '''Min Angle''' & '''Max Angle''': Maximum and minimum angle between the bodies relative to the start position. Max angle is in the positive direction and min in the negative. To get the positive direction place your thumb on your right hand in the direction of the axis. Now bend your fingers towards your palm, the direction in which you fingers are pointing is the direction of the positive angle. In mathematics this is called the right hand rule. Valid values are 0 – 179.

Specific Parameters for Slider Joint:

[[slider.jpg]]

* '''Min Distance''' & '''Max Distance''': Picture the anchor as attached to Body1(Parent). When the anchor is moved in the distance of the axis the distance gets larger and when it moves in the other way it gets negative (and smaller). At the start position the distance is 0.

Specific Parameters for Screw Joint:
* '''Min Distance''' & '''Max Distance''': This joint works exactly as the slider but it can spin around the axis.

= Joint EditMode =

To build more complex physics setups, you will need to add joints to your models. This way you will be able to create stuff like doors, tables with drawers, levers and so on.

There are four types of joints that can be created at the moment:
* Ball
* Hinge
* Screw
* Slider

HPL3/Entities/Working with Shapes

2026-07-30T21:59:19Z

TiMan: Created page with "= Shapes = General Parameters: ''' '''Name''': Name of the shape. ''' '''Position''': Position of the shape in the world. ''' '''Rotation''': 3D Vector storing the shape rot..."

= Shapes =

General Parameters:

''' '''Name''': Name of the shape.
''' '''Position''': Position of the shape in the world.
''' '''Rotation''': 3D Vector storing the shape rotation.
''' '''Scale''': 3D Vector storing the scale of the shape.
Shape Specific:

''' '''Create body''': will create a body out of the shape. Also works when multiple shapes are selected, thus creating a multishape body.
''' '''Detach from body''': the shape will be removed from the body it is part of.
Best Practices:

''' Keep the Scale in all axis larger than 0.04 to make the collisions stable

= Shape EditMode =

This EditMode is used to create Shapes that will help in physics body creation. At the moment you can create four types of shapes:

* Box
* Cylinder
* Sphere
* Capsule

HPL3/SOMA/Entities

2026-07-30T21:58:59Z

TiMan:

{{constructionNotice|This category and its sub-pages are undergoing major editing, as some information in this category and all the sub pages is currently in the process of being formatted or re-written from scratch to achieve a higher standard of formatting, or not everything is yet available. More pages and information will gradually be added.}}

'''This category deals with the HPL3 Model Editor, entities and related topics.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/Entities/Entities Overview|Entities Overview]]

== General ==
* [[HPL3/Entities/Model Editor Controls|Model Editor Controls]]
* [[HPL3/Entities/Model Editor View|Model Editor View]]
* [[HPL3/Entities/Model Editor Preferences|Model Editor Preferences]]
* [[HPL3/Entities/Model Editor Outline|Model Editor Outline]]
* [[HPL3/Entities/Entity Settings|Entity Settings]]
* [[HPL3/Entities/Entity Notes|Entity Notes]]
* [[HPL3/Entities/Entity Mesh|Entity Mesh]]
* [[HPL3/Entities/Entity Rig|Entity Rig]]
* [[HPL3/Entities/Entity Types|Entity Types]]

== Model Preview / Animations ==
* [[HPL3/Entities/Model Preview Settings|Model Preview Settings]]
* [[HPL3/Entities/Adding Animations to Entities|Adding Animations to Entities]]

{{CategoryNewcolumn}}

== Physics Bodies ==
* [[HPL3/Entities/Working with Physics Bodies|Working with Physics Bodies]]
* [[HPL3/Entities/Physics Body Properties|Physics Body Properties]]

== Joints ==
* [[HPL3/SOMA/Entities/Working with Joints|Working with Joints]]
* [[HPL3/SOMA/Entities/Joint Properties|Joint Properties]]

== Shapes ==
* [[HPL3/Entities/Working with Shapes|Working with Shapes]]

{{CategoryEnd}}

__NOTOC__

[[Category:English]]
[[Category:Entry pages]]

HPL3/SOMA/Entities

2026-07-30T21:57:37Z

TiMan: /* Physics Bodies */

{{constructionNotice|This category and its sub-pages are undergoing major editing, as some information in this category and all the sub pages is currently in the process of being formatted or re-written from scratch to achieve a higher standard of formatting, or not everything is yet available. More pages and information will gradually be added.}}

'''This category deals with the HPL3 Model Editor, entities and related topics.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/Entities/Entities Overview|Entities Overview]]

== General ==
* [[HPL3/Entities/Model Editor Controls|Model Editor Controls]]
* [[HPL3/Entities/Model Editor View|Model Editor View]]
* [[HPL3/Entities/Model Editor Preferences|Model Editor Preferences]]
* [[HPL3/Entities/Model Editor Outline|Model Editor Outline]]
* [[HPL3/Entities/Entity Settings|Entity Settings]]
* [[HPL3/Entities/Entity Notes|Entity Notes]]
* [[HPL3/Entities/Entity Mesh|Entity Mesh]]
* [[HPL3/Entities/Entity Rig|Entity Rig]]
* [[HPL3/Entities/Entity Types|Entity Types]]

== Model Preview / Animations ==
* [[HPL3/Entities/Model Preview Settings|Model Preview Settings]]
* [[HPL3/Entities/Adding Animations to Entities|Adding Animations to Entities]]

{{CategoryNewcolumn}}

== Physics Bodies ==
* [[HPL3/Entities/Working with Physics Bodies|Working with Physics Bodies]]
* [[HPL3/Entities/Physics Body Properties|Physics Body Properties]]

== Joints ==
* [[HPL3/SOMA/Entities/Working with Joints|Working with Joints]]
* [[HPL3/SOMA/Entities/Joint Properties|Joint Properties]]

{{CategoryEnd}}

__NOTOC__

[[Category:English]]
[[Category:Entry pages]]

HPL3/Entities/Adding Animations to Entities

2026-07-30T21:57:07Z

TiMan: Created page with "With this tool you will be able to add, delete and edit animations for the current entity. Animation related controls ''' '''Add new animation''' this button will add an..."

With this tool you will be able to add, delete and edit animations for the current entity.

Animation related controls

''' '''Add new animation''' this button will add an animation with empty parameters.
''' '''Hide visemes'''this button will toggle the showing of special animations known as "visemes" which are used for facial animation.
''' '''Animation list''' Every animation set up for the current entity will show up here (unless it is a viseme and Hide visemes is toggled)
''' '''Delete animation ''' this button will delete the animation that is currently selected on the Animation list
''' '''Name'''
''' '''File'''
''' '''Layer'''
''' '''Speed'''
''' '''TImeline''': The timeline for the animation editor will have different functionality, depending on which elements (events or transitions) are being edited at the moment.
''' Animation elements tab frame:
'''* Event tab
'''''' '''New''': this button will add a new event to the currently selected animation, at the current time position in the timeline. A marker will be added to the timeline, drag this marker along the timeline to modify the event's time parameter.
'''''' '''Event list''': Shows the events that are set up for the current animation.
'''''' Delete: Deletes the currently selected event.
'''''' Name: name of the current event.
'''''' Time: position in seconds in the animation when the event will be triggered.
'''''' Type: The type for the current event. There is an extra value that is used depending on what the type is, as follows.
''''''* PlaySound
: The event will play the sound picked with the File control.
''''''*
Step:
''''''*
ScriptCallback:
''''''*
Message:

''' Transition Tab
'''* New: this button will add a new transition to the currently selected animation
'''*
Transition list: Shows every transition defined for the current animation

.
'''* Delete: Deletes the currently selected transition.
'''* Name: name of the current transition.
'''* PrevAnimation: lets you choose the previous animation for the transition (meaning the transition will be triggered when choosing to play the current animation while the previous is playing in the game) from a combo box. If "Any" is chosen, the transition will be played in any case. * Min and Max time: time interval in the previous animation where triggering the transition is okay. These only work when a previous animation other than "Any" is chosen. The interval will be shown with draggable markers on the timeline as well.
'''* Transition: animation that will be played as a "bridge" between the previous and the currently selected (base) animation.
'''''' Play transition preview: toggle to enable preview of the transition.
'''''' Start time: for tweaking the min and max time on the previous animation, one can choose at which time position the transition is to start. Also has an associated draggable marker on the timeline.

Notes on the timeline workings: event markers will only be shown when the event tab is selected. The timeline will play transition previews and will show transition markers when a transition on the Transition tab is picked, otherwise the current animation will be played.

HPL3/Entities/Model Preview Settings

2026-07-30T21:56:11Z

TiMan: Created page with "= Entity Preview/Animation Editor window = When you have your entity all set up with bodies, joints and such, it is time to test how it would look in the game. That's what t..."

= Entity Preview/Animation Editor window =

When you have your entity all set up with bodies, joints and such, it is time to test how it would look in the game. That's what the Entity Preview window is for. In this window you will be able to see how the entity would look ingame, meaning it will be physically simulated. In it you will also get to edit the entity's animations, if any. To start the preview, just press the "Toggle preview" button (the one with cogwheels) in lower toolbar.

The window behaves just like a regular viewport. You can move and orbit the camera around the model the same way. Added to this, you can use the mouse pointer to actually "pick" and drag physical objects in the scene.

'''Animation controls'''

''' '''Animation''': With this control you can select the animation to play, if there is any available. When selected, it will be looped on and on.
''' '''Autoplay''': when this is checked, pressing the play button will not be needed when selecting an animation on the Animation selector.
''' '''Play button'''
''' '''Loop button'''
''' '''Step backward/forward button'''
''' '''Time display'''
''' '''Timeline'''
'''Visualization controls''':

''' '''Ph ''' Toggles drawing of physical objects information. Bodies will be shown as wireframe objects, with a cross indicating their center of mass and joints will appear as green spheres.
''' '''Sk'''If a skeleton is present, it will be drawn draw it as red lines for bones and spheres for joints when this button is pressed.
''' '''BV ''' Toggles showing of Bounding Volume for the meshes on screen.
''' '''Fl ''' Will set the floor object to visible when pressed.
''' '''Am/Ma/Bk ''' Toggles Ambient, Main and Back lights on the scene respectively.
The buttons below the previous ones work as follows:

''' '''Edit Animations''' When pressed, the Animation Editor pane will be shown, more on this later.
''' '''Exit Preview''' When pressed, the preview window will be dismissed.
Buoyancy controls

''' '''Buoyancy''': Toggles buoyancy active, along with a plane representing a liquid surface.
''' '''B. Density''': Buoyancy density.
''' '''S. Height''': Height of the liquid surface.
''' '''B. A. viscosity''': Buoyancy angular viscosity.
''' '''B. L. viscosity''': Buoyancy linear viscosity.
Animation Editor pane

With this tool you will be able to add, delete and edit animations for the current entity.

Animation related controls

''' '''Add new animation''' this button will add an animation with empty parameters.
''' '''Hide visemes'''this button will toggle the showing of special animations known as "visemes" which are used for facial animation.
''' '''Animation list''' Every animation set up for the current entity will show up here (unless it is a viseme and Hide visemes is toggled)
''' '''Delete animation ''' this button will delete the animation that is currently selected on the Animation list
''' '''Name'''
''' '''File'''
''' '''Layer'''
''' '''Speed'''
''' '''TImeline''': The timeline for the animation editor will have different functionality, depending on which elements (events or transitions) are being edited at the moment.
''' Animation elements tab frame:
'''* Event tab
'''''' '''New''': this button will add a new event to the currently selected animation, at the current time position in the timeline. A marker will be added to the timeline, drag this marker along the timeline to modify the event's time parameter.
'''''' '''Event list''': Shows the events that are set up for the current animation.
'''''' Delete: Deletes the currently selected event.
'''''' Name: name of the current event.
'''''' Time: position in seconds in the animation when the event will be triggered.
'''''' Type: The type for the current event. There is an extra value that is used depending on what the type is, as follows.
''''''* PlaySound
: The event will play the sound picked with the File control.
''''''*
Step:
''''''*
ScriptCallback:
''''''*
Message:

''' Transition Tab
'''* New: this button will add a new transition to the currently selected animation
'''*
Transition list: Shows every transition defined for the current animation

.
'''* Delete: Deletes the currently selected transition.
'''* Name: name of the current transition.
'''* PrevAnimation: lets you choose the previous animation for the transition (meaning the transition will be triggered when choosing to play the current animation while the previous is playing in the game) from a combo box. If "Any" is chosen, the transition will be played in any case. * Min and Max time: time interval in the previous animation where triggering the transition is okay. These only work when a previous animation other than "Any" is chosen. The interval will be shown with draggable markers on the timeline as well.
'''* Transition: animation that will be played as a "bridge" between the previous and the currently selected (base) animation.
'''''' Play transition preview: toggle to enable preview of the transition.
'''''' Start time: for tweaking the min and max time on the previous animation, one can choose at which time position the transition is to start. Also has an associated draggable marker on the timeline.

Notes on the timeline workings: event markers will only be shown when the event tab is selected. The timeline will play transition previews and will show transition markers when a transition on the Transition tab is picked, otherwise the current animation will be played.

HPL3/SOMA/Entities

2026-07-30T21:55:41Z

TiMan: /* Model Preview / Animations */

{{constructionNotice|This category and its sub-pages are undergoing major editing, as some information in this category and all the sub pages is currently in the process of being formatted or re-written from scratch to achieve a higher standard of formatting, or not everything is yet available. More pages and information will gradually be added.}}

'''This category deals with the HPL3 Model Editor, entities and related topics.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/Entities/Entities Overview|Entities Overview]]

== General ==
* [[HPL3/Entities/Model Editor Controls|Model Editor Controls]]
* [[HPL3/Entities/Model Editor View|Model Editor View]]
* [[HPL3/Entities/Model Editor Preferences|Model Editor Preferences]]
* [[HPL3/Entities/Model Editor Outline|Model Editor Outline]]
* [[HPL3/Entities/Entity Settings|Entity Settings]]
* [[HPL3/Entities/Entity Notes|Entity Notes]]
* [[HPL3/Entities/Entity Mesh|Entity Mesh]]
* [[HPL3/Entities/Entity Rig|Entity Rig]]
* [[HPL3/Entities/Entity Types|Entity Types]]

== Model Preview / Animations ==
* [[HPL3/Entities/Model Preview Settings|Model Preview Settings]]
* [[HPL3/Entities/Adding Animations to Entities|Adding Animations to Entities]]

{{CategoryNewcolumn}}

== Physics Bodies ==
* [[HPL3/SOMA/Entities/Working with Physics Bodies|Working with Physics Bodies]]
* [[HPL3/SOMA/Entities/Physics Body Properties|Physics Body Properties]]

== Joints ==
* [[HPL3/SOMA/Entities/Working with Joints|Working with Joints]]
* [[HPL3/SOMA/Entities/Joint Properties|Joint Properties]]

{{CategoryEnd}}

__NOTOC__

[[Category:English]]
[[Category:Entry pages]]

HPL3/Entities/Entity Mesh

2026-07-30T21:54:57Z

TiMan: Created page with "= SubMeshes = Whenever a Mesh is imported into the ModelEditor, it will spawn one or several submeshes. These can be attached to bodies. General Parameters: * '''Name''': Nam..."

= SubMeshes =
Whenever a Mesh is imported into the ModelEditor, it will spawn one or several submeshes. These can be attached to bodies.

General Parameters:
* '''Name''': Name of the shape.
* '''Position''': Position of the shape in the world. If the mesh has a skeleton, no transformations can be applied.
* '''Rotation''': 3D Vector storing the shape rotation. If the mesh has a skeleton, no transformations can be applied.
* '''Scale''': 3D Vector storing the scale of the shape. If the mesh has a skeleton, no transformations can be applied.

= SubMesh Reassign Dialog =

[[File:model_editor_submesh_reassign.png]]

This window allows the user to keep existing submesh data in the event of importing a new mesh or updating of the current one.

On the left, a list with the new submeshes will be displayed, as well as a selector for pairing with a previous submesh for each. The "Use new data" item will ignore any present parameters.

On the right, submeshes that are currently unassigned will be listed.

The Best Match button will try to find the best pairing for each submesh. At the time of writing, only triangle count will be taken into consideration.

When done, pressing the OK button will close the dialog and use the chosen parameters in the new mesh.

HPL3/Entities/Entity Types

2026-07-30T21:54:16Z

HPL3/SOMA/Entities

2026-07-30T21:53:49Z

TiMan: /* General */

{{constructionNotice|This category and its sub-pages are undergoing major editing, as some information in this category and all the sub pages is currently in the process of being formatted or re-written from scratch to achieve a higher standard of formatting, or not everything is yet available. More pages and information will gradually be added.}}

'''This category deals with the HPL3 Model Editor, entities and related topics.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/Entities/Entities Overview|Entities Overview]]

== General ==
* [[HPL3/Entities/Model Editor Controls|Model Editor Controls]]
* [[HPL3/Entities/Model Editor View|Model Editor View]]
* [[HPL3/Entities/Model Editor Preferences|Model Editor Preferences]]
* [[HPL3/Entities/Model Editor Outline|Model Editor Outline]]
* [[HPL3/Entities/Entity Settings|Entity Settings]]
* [[HPL3/Entities/Entity Notes|Entity Notes]]
* [[HPL3/Entities/Entity Mesh|Entity Mesh]]
* [[HPL3/Entities/Entity Rig|Entity Rig]]
* [[HPL3/Entities/Entity Types|Entity Types]]

== Model Preview / Animations ==
* [[HPL3/SOMA/Entities/Model Preview Settings|Model Preview Settings]]
* [[HPL3/SOMA/Entities/Adding Animations to Entities|Adding Animations to Entities]]

{{CategoryNewcolumn}}

== Physics Bodies ==
* [[HPL3/SOMA/Entities/Working with Physics Bodies|Working with Physics Bodies]]
* [[HPL3/SOMA/Entities/Physics Body Properties|Physics Body Properties]]

== Joints ==
* [[HPL3/SOMA/Entities/Working with Joints|Working with Joints]]
* [[HPL3/SOMA/Entities/Joint Properties|Joint Properties]]

{{CategoryEnd}}

__NOTOC__

[[Category:English]]
[[Category:Entry pages]]

HPL3/SOMA/Entities

2026-07-30T21:53:22Z

TiMan: /* General */

{{constructionNotice|This category and its sub-pages are undergoing major editing, as some information in this category and all the sub pages is currently in the process of being formatted or re-written from scratch to achieve a higher standard of formatting, or not everything is yet available. More pages and information will gradually be added.}}

'''This category deals with the HPL3 Model Editor, entities and related topics.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/Entities/Entities Overview|Entities Overview]]

== General ==
* [[HPL3/Entities/Model Editor Controls|Model Editor Controls]]
* [[HPL3/Entities/Model Editor View|Model Editor View]]
* [[HPL3/Entities/Model Editor Toolbar|Model Editor Toolbar]]
* [[HPL3/Entities/Model Editor Preferences|Model Editor Preferences]]
* [[HPL3/Entities/Model Editor Outline|Model Editor Outline]]
* [[HPL3/Entities/Entity Settings|Entity Settings]]
* [[HPL3/Entities/Entity Notes|Entity Notes]]
* [[HPL3/Entities/Entity Mesh|Entity Mesh]]
* [[HPL3/Entities/Entity Rig|Entity Rig]]
* [[HPL3/Entities/Entity Types|Entity Types]]

== Model Preview / Animations ==
* [[HPL3/SOMA/Entities/Model Preview Settings|Model Preview Settings]]
* [[HPL3/SOMA/Entities/Adding Animations to Entities|Adding Animations to Entities]]

{{CategoryNewcolumn}}

== Physics Bodies ==
* [[HPL3/SOMA/Entities/Working with Physics Bodies|Working with Physics Bodies]]
* [[HPL3/SOMA/Entities/Physics Body Properties|Physics Body Properties]]

== Joints ==
* [[HPL3/SOMA/Entities/Working with Joints|Working with Joints]]
* [[HPL3/SOMA/Entities/Joint Properties|Joint Properties]]

{{CategoryEnd}}

__NOTOC__

[[Category:English]]
[[Category:Entry pages]]