===== 3. Creating maps =====
Maps in the HPL-Engine are created using rooms and portals to limit the amount of objects being rendered and the system works something like this:
1. First it is check what rooms the camera (player) is in. This is checked by using the bounding boxes of the rooms. A bounding box is generated by the engine by the making an axis aligned box that exactly covers all the vertices of the main room geometry. Axis aligned means that the height is parallel to the y-axis, width to the x-axis and depth to the z-axis. The boxes are **not** rotated in any way. The bounding boxes can be seen when pressing 2 in the sceneviewer. The rooms camera are in a placed in a render list.
2. When the engine has determined what rooms the camera is in then it starts checking what portals can be seen in these rooms. This checking only checks the field of view and cannot see if any object is blocking a portal.
3. For each portal that can be seen, the engine checks what room the portal connects to and then it places this room in a render list (if the room is all ready in the list, it is skipped).
4. In the connected room the engine checks what portals the portal that lead to this room can see, then checks if they are in the field of view of the camera. If a portal is claimed visible then it is looped from point 3. This continues until no portals are left to check.
==== 3.1 Rooms ====
When making maps you must divide the entire map into rooms. A room can be an outdoor area, a corridor, several rooms, a room (off course), etc. To make a room in Maya all the main objects (more on this later) in the room should be grouped in a “_room#” group, # being a string of characters, for example: “_room1C”, “_room3F4”,”_roomDeath”, etc. Note that the “_” character is **forbidden to use in the name except as a starting character, which is a must.**
The easiest way to do this is to create all the main geometry for the room with the prefix “room” + room number + “_” (i.e. room1_pBox22) and then place all these under a “_room#” node in the hyper graph editor. **Do not** name the objects with the prefix “_room”. All names starting with “_” are special objects and the importer deals with these in a special way.
If all object names in a room has the same prefix it is easy to see in the hyper graph editor if some objects are placed under the wrong node and so on. So do it like this to avoid confusion and more work then needed. In the hyper graph nodes can just be placed under the right room by dragging them with the middle mouse button.
To make this as simple as possible the only things that are needed to be in a room is the **geometry** (no lights allowed) defining the room. This means most likely the walls in the room. All other stuff (except the portals) do **NOT** have to be placed in the “_room#” group. They will be added to the rooms they are in at load time. //See below for example.//
[[https://wiki.frictionalgames.com/_detail/hpl1/documentation/room_example.jpg?id=hpl1:documentation:content.creation.document.chap3|{{https://wiki.frictionalgames.com/_media/hpl1/documentation/room_example.jpg?nolink&}}]]\\
Note that objects that are in two or more rooms at the same time demand some extra cpu power at runtime so avoid this when it is not needed. Note that static geometry can be placed either in a “_room#” group or not (it does not have to be considered main geometry). However, lights and references are **forbidden** in room groups!\\
Another **very** important thing is that the bounding boxes of the rooms should not overlap and if it is must then the boxes should overlap as little as possible. Overlapping bounding boxes = major speed loss. //See below for example.//
[[https://wiki.frictionalgames.com/_detail/hpl1/documentation/bounding_example.jpg?id=hpl1:documentation:content.creation.document.chap3|{{https://wiki.frictionalgames.com/_media/hpl1/documentation/bounding_example.jpg?nolink&}}]]
==== 3.2 Portals ====
A Portal is a rectangle that defines the connection between two rooms. A portal must be a one-sided rectangle and cover the hole between two rooms completely. It is not a problem if the portal is bigger than the hole, but it should fit a good as possible. This means that a hole between two rooms can be a round, triangular or any arbitrary form. A rectangle must still be used even if the hole is not rectangular and the hole must be covered 100% even if the fit does not get perfect.\\
[[https://wiki.frictionalgames.com/_detail/hpl1/documentation/portal01.jpg?id=hpl1:documentation:content.creation.document.chap3|{{https://wiki.frictionalgames.com/_media/hpl1/documentation/portal01.jpg?nolink&}}]]\\
\\
The portal must be placed in the “_room#” group that it belongs to. The normal of the rectangle must be facing the center of the room it belongs to and **not** the room it connects to.\\
[[https://wiki.frictionalgames.com/_detail/hpl1/documentation/portal02.jpg?id=hpl1:documentation:content.creation.document.chap3|{{https://wiki.frictionalgames.com/_media/hpl1/documentation/portal02.jpg?nolink&}}]]\\
\\
Portals are named “_portal#_room#” + “_#” for each portal that can be seen from this portal.
The first # is the number of the portal; this must be exclusive inside the room the portal is in (i.e. there cannot be two “_portal55” under “_room4”). Two or more rooms may have portals with the same number though (i.e. There may be a “_portal4” under “_room4”, “_room2” and “_room1”).
The next # is the number of the room that the portal connect to, so a portal name could be “_portal2_room4”. This is a portal with the number 2 that connects to “_room4”.
The following optional texts are numbers of portals which can be seen from this portal. I.e.: “_portal4_room3_2_34” connects to “_room3” and in room 3 the portals 2 and 34 can be seen. “Can be seen” means that if you where to peak through the portal there is someway that these portals could be visible.\\
[[https://wiki.frictionalgames.com/_detail/hpl1/documentation/portal03.jpg?id=hpl1:documentation:content.creation.document.chap3|{{https://wiki.frictionalgames.com/_media/hpl1/documentation/portal03.jpg?nolink&}}]]
In the image above the circumstances are as follows:
* Room 2 - Portal 1 can see portal 2.
* Room 3 - Portal 1 can see portal 1 and 3.
* Room 4 - Portal 1 can see portal 2.
* The portals in room 1 can see no other portals.
The names for the portals will be the following:
* **Room 2 - Portal 1:** “_portal1_room1_2”
* **Room 3 - Portal 1:** “_portal1_room1_1_3”
* **Room 4 - Portal 1:** “_portal1_room1_2”
The portals in room 1 will have the following names:
* **Portal 1:** _portal1_room2
* **Portal 2:** _portal2_room3
* **Portal 3:** _portal3_room4
Note that the sketch of the portal connections does not have a good design since the bounding boxes of the rooms overlap! This should be avoided if possible (and in the currently version overlapping bounding boxes will probably lead to bugs.)
When placing portals it is important that they are that the edge of the room or where two or more room bounding boxes overlap. \\ [[https://wiki.frictionalgames.com/_detail/hpl1/documentation/portal04.jpg?id=hpl1:documentation:content.creation.document.chap3|{{https://wiki.frictionalgames.com/_media/hpl1/documentation/portal04.jpg?nolink&}}]]
The red rectangle above marks where the portals for both rooms should be placed when two rooms lies side by side. Not that the portals are much thicker then what they are in the engine. The reason for this is that player should not be able to be in for example Room 1, be looking at Room 2 and not see the portal belonging to Room1. This means that Room 2 will not be rendered. \\ [[https://wiki.frictionalgames.com/_detail/hpl1/documentation/portal05.jpg?id=hpl1:documentation:content.creation.document.chap3|{{https://wiki.frictionalgames.com/_media/hpl1/documentation/portal05.jpg?nolink&}}]]
As seen in the image above the player is symbolized by the black dot and has sight into the purple room; however the portal is behind the player so the purple room cannot be seen. However if the two rooms overlap so that the edge of the purple room is close to the portal then it is okay! \\ [[https://wiki.frictionalgames.com/_detail/hpl1/documentation/portal06.jpg?id=hpl1:documentation:content.creation.document.chap3|{{https://wiki.frictionalgames.com/_media/hpl1/documentation/portal06.jpg?nolink&}}]]
As seen in the image above the player is inside the bounding box of the purple room as well so it doesn’t have to have to see the portal. The dark yellow rectangle is where the portal in the purple would be placed.
Note that that the three images above all show bounding boxes and **not** room geometry! Another thing to note is that overlapping bounding boxes should be avoided when possible since it can result in a lot of unnecessary rooms being rendered. When creating maps remember to press 2 in the map viewer to debug and optimize portals and rooms.
==== 3.3 Lights ====
=== 3.3.1 General ===
If the light should be dynamic (this means attenuation, angle or position changes, NOT color change), use the prefix “dynamic” on the light name. I.e.: “dynamic_PointLight1” will be a dynamic light.
Note that lights should not be part of room group hierarchy.
=== 3.3.2 Point Lights ===
Point Lights have the following attributes:
|**Attenuation** |The range of the light. |
|**Color** |The color it casts. |
|**Specular** |How much specular light it emits. 0 – 1. |
|**CastsShadow** |If the light casts shadows or not. |
|**FalloffImage** |The rate at which the light goes from full color to black. Default = linear. This is represented as a 1D image (meaning height is 1). The far left is the max light intensity and the far right is the lowest (should be black). The width must be a power of 2. |
Color is set as normally in the 3D editor, but because the collada exporter handles light very badly, attenuation and specular has to be set using the **scale** of the light. This means scale X = attenuation and scale Y = specular. Attenuation has a value from 0 to eternity specular has a value from 0 to 1.
If the light casts shadows or not is also set by the scale. Scale Z 0 means no shadows are cast and 1 means the light casts shadows.
Falloff is set in the light entity file ([[:hpl1:documentation:content.creation.document.chap6#light|light]]).
=== 3.3.3 Spot Lights ===
Spot lights have a few more properties than point lights, these are all of point light’s plus:
|**FieldOfView** |The size in degrees of the cone that casts the light. 0 – 180. |
|**Aspect** |How much larger /smaller the width of the cone is when compared to it’s height. 1 = same size, 0.5 = half size, 2 = double size, etc. |
|**NearClipPlane** |Objects under this distance will not be lit. 0 – inf. Normally around 0.1. |
|**ProjectionImage** |This is the image that the light projects, RGB channel represent color of the light and it must have an alpha channel that decides the specular influence. The borders of this must be 100% black and it must have power of 2 size. |
|**ProjectionAnimMode** |If the projection image is an animation and if so the mode used. If it is an animation then the syntax for image is: \\ [name].[ext]. And then the textures in the animation must be named [name]01.[ext], [name]02.[ext], etc. \\ Values can be “None”, “Loop” and “Oscillate”. |
|**ProjectionFrameTime** |The time in seconds each frame is shown if it is an animation. |
Color and Field of View are set as normal. Attenuation is set using scale X. The rest of the attributes are set in the light entity file, [[:hpl1:documentation:content.creation.document.chap6#light|light]].
**MAYA TIP:** In the light’s locator scale to 55.5 and then set all the scale directions when setting attenuation. Now the arrow of the locator will show the length that light reaches.
=== 3.3.4 Light Entity file ===
Light entity file lets you set some general properties for a light. The syntax is like this:
The extension of these files must be “lnt”.
The properties in the file will over-write previous values (such as those set in the editor). All of the properties, except ProjectionImage, can be excluded and will then be given default values.
To set a light entity file to a light use the following syntax when naming the light in the editor:
**[dynamic (optional)] [ _ ] [entityfile] [ _ ] [lightname]**
|**dynamic** |Add “dynamic” infront of the name if the light is going to cross other portals other than the one it starts in. |
|**entityfile** |The name of the light entity file. May contain “_” in the file name. |
|**lightname** |The name of the light. |
Examples: \\ **dynamic_mylight** \\ Will create a light that is going to move and does not have any entity file.
**dynamic_my_light_file_mylight** \\ This is a dynamic light that loads data from “my_light_file.lnt” and is named “mylight”.
**my_light_file_mylight** \\ This is a static light that loads data from “my_light_file.lnt” and is named “mylight”.
==== 3.4 References ====
References are used to add external objects to the map.
When referencing to an object you **must** use a special reference file and it is **very important** that the file only contains **one** object. If not the referencing will fail. This special reference file will be called **reference object** (and nothing else) for the duration of this chapter.
Another extremely important thing is that the reference object looks exactly the same in size and placement as the file you want to reference to. It may not contain any rotation, scale or translation and if the model needs to have an offset the it is very important that the pivot is at (0,0,0) in the reference object. When you reference to a file the engine will place the referenced file with its origo at the reference object’s pivot. This is one reason why you should always try to center your object in the model file.
__**Maya references**__ \\
In the options for “create reference” lock and group must be unchecked. When creating further copies of the reference remember to have set to instancing in “duplicate” options. Also turn off namespaces and be sure to name the node in the reference object correctly and with a unique name!
__**Max Xref**__ \\
Simply create an xref to the reference object.
__**Naming**__ \\
NOTE: When naming the several grouped objects, it is the group that must be named! You can also create references by just importing normal geometry and naming it correctly (note that the imported geometry only should be one object or several objects in group). The syntax is the following:\\
**_ref_[file]_[name]**
|**file** |The entity file to load. This may contain “_” and must not contain any extension (i.e. “.ent”). |
|**name** |The name of the object in the game world. |
Example:\\
**_ref_wooden_box01_Box01** \\
This will create an entity for the file “wooden_box01.ent” and it will have the name “Box01”.
Below are descriptions of the different reference types. (Read this as if there is only one type of object you can reference to and that is the **entity**.)
**//See the [[:hpl1:tutorials:tutorial_1_-_introduction#tutorial_1_4_references|following tutorial]] for an explanation of entities, how they work and why.// **
=== 3.4.1 Static models ===
**Do not read this! This is only for the programmer’s reference. Ignore as if it didn’t exist!** \\
//The name of the reference has the prefix “static_”. This should only be used for animated static geometry on the map such as fans, machinery, etc. For non animated static geometry normal geometry should be used. The animation for these models must not change during run time and they must be placed in such a way that they never touch more rooms during animation then they do in bind pose. The referenced Maya .mb file must have the same name as the model file (.msh, .dae, etc) that you want added to the map.//
=== 3.4.2 Entities ===
The name of the reference doesn’t need any prefix. Any name will do. These are things like monsters, item, etc. It is what ever the game wants them to be. These references (the referenced .mb file name) do not refer to model files but rather an entity file. The entity has the extension “.ent” and is a simple text XML file. This xml file can contain info that is mostly game specific.
//As an example//, a _ref_my_woodbox01_box01 reference added in the 3D editor does **not** point to a model file named my_woodbox01.dae/.mb/.3ds etc, it points to a .ent file named my_woodbox01.ent and this file contains the properties, special functions AND also contains information on what model file to use for the reference!
More on this in [[:hpl1:documentation:content.creation.document.chap6#entity_files|entity files]].
==== 3.5 Name parameters ====
Because some options are unavailable (or unexportable) in 3D editors, some settings have to be set by adding certain text to the names of objects. A parameter is written with a “_” in front of it and **can not** be the first text in the name. For example:
“Ball04_noshadow_nocollide”\\
“Ball04_noshadow_”\\
are both legal.\\
\\
“_nocollide_Ball04” is **not legal!** But you can write ““nocollide_Ball04” by **exluding the _**.\\
The following is a list of the parameters all objects types can have.
Geometry / References:
|**noshadow** |No shadows are cast from this object. |
|**nodraw** |The object will not be visible but it's mesh will be used as a collider. |
|**nocollide** |Nothing will collide with this object. |
|**nocharcollide** |Objects will collide with it but not the player. |
|**nosoundblock** |Sound will be unaltered through this object |
|**soundblock** |Sound will be lower through this object. |
Colliders:
|**soundblock** |Sound will be lower through this collider, example: _collider_box_collider1_soundblock. |
\\
==== 3.6 Animations ====
Never use animations directly in maps, instead reference to static object or to entities with animations.
==== 3.7 Colliders ====
Colliders are added in exactly the same way as described in [[:hpl1:documentation:content.creation.document.chap2#colliders|chapter 2.4]]. There are some differences though. One is that all geometry will be turned in to collideable meshes unless the “nocollide” parameter is specified, so if you want to simplify, for example, a statue mesh, the statue mesh must have the “nocollide” argument.
Another difference is that colliders in a scene (static, imported models) are not linked with any entity like ones in a model file (referenced models) and therefore do not have any physics material linked to them. This means that if you want the collider to have a physics material other than “Default” you **must** assign a material (a material with texture and stuff) to it. This material should then have the physics material you want to use. For example if you want to make a simplified collider for a statue (or maybe several colliders) you should assign the same material as the statue to the collider(s).
When creating maps there is an **additional collider called “_charcollider”** that can be used. This collider will collide only with the player character, which can be useful if you want to block the players path but not have objects bounce of something invisible.
==== 3.8 Sound Entities ====
Sound entities are use to place sounds on the map. To palce one is really easy. Just name any node (geometry or dummy object):
**_sound_[entity file]_[name]**
|**entity file** |An “snt”-file containing data for the sound. More about this in the [[:hpl1:documentation:content_creation_document#hplhelper|HPLHelper chapter]]. Note that this name may have “_” in it! And DO NOT specify the extension (.snt). |
|**name** |This is what the sound entity will be called in game. |
Examples: \\ **_sound_test_drops_mysound1**
This will create a sound entity named “mysound1” that uses the file “test_drops.snt”.
==== 3.9 Sound blockers ====
Sound is blocked by certain bodies in the world. When the sound is blocked by something it gets lower just like in the real world. These are the “rules” that apply for sound blockers:
* All geometry that is collideable and part of a room group is automatically set as a sound blocker. This is all the geometry that defines a rooms bounding box. If one of these objects should not be a sound blocker then the parameter “nosoundblock” must be used!
* All other objects and entities that are not apart of the room group are automatically assigned as **none** sound blocking. If you want one of these object to block sound you must use the “soundblock” parameter or set “BlocksSound” in the entity file to “true”.
* As default Scene colliders (not colliders in models) are **none** sound blocking. Setting the parameter “soundblock” will turn sound blocking on.
==== 3.10 Start positions ====
These are used to set where in the world the player/camera should start. Any object can be used to specify a start position the only important thing is the naming which has to be:
**_start_[name]**
|**name** |The in game name of the start position. May contain “_”. |
Example: **_start_my_start1**
This creates a start position with the name “my_start1”.
To specify direction just rotate the object, scale may not be used! If no rotation is set the player/camera will look down the negative z-axis (y-axis for 3ds users).
==== 3.11 Areas ====
Areas can be used for several engine and game specific tasks. The syntax is:
**_area_[type (optional)]_[name]**
|**type** |This is game specific information, should be “script” mostly though. See [[:hpl1:documentation:script_reference|script reference]] for scripts that uses specific types. |
|**name** |This is the area the start will have when you try to access it. |
**Types**
* script - The regular area type for most scripts.
* damage - Specfic area to be used with certain scripts dealing with damage to player, entites and objects. Properties set by script.
* liquid - Specific area for setting up liquids(water and so on). Properties set by script.
* stick - An area that will let other objects “stick” to it, used for specific stick scripts. Properties set by script.
* force - An area that will apply a force to the player, entities and objects in it. Properties set by script.
* link - An area that will trigger the loading of a new level/same level with a new starting point.
* save - Will save the game when the player interacts with it.
* ladder - Attaches the player when he interacts with it, the positioning, size and rotation gives the ladder it's main functions. Specific sounds and such is set by script.
* mess - An area that displays an examination message. This can also be done by script on a normal area/entity.
special syntax for this area: **_area_mess_cat_entry_name**
cat = translation file category.
entry = translation file entry.
name = optional, for uses of scripting "cat_entry_name" is used.
An area is created in exactly the same way as you would create a box collider. Mostly the area doesn’t need the material though.
If the area does not have a type then it is only considered an engine area and will not have any game specific propose.
==== 3.12 Billboards ====
Billboards are rectangles that always faces the camera, these can be used for a lot of things like light flares, grass, etc. The syntax for placing a billboard is the following:
**_bb_[entity file]_[name]**
|**entity file** |Entity file containing data about the billboard, may contain “_”. |
|**name** |The name that will be used in game. |
Scale x is width, scale y height and scale z offset (might help to use a 1,1,1 box has place holder to get a hunch in the editor how it will look in game). The orientation (rotation) defines the axis of the billboard (this is only used for Axis-billboards).
The entity file looks like this and is a file with the extension “.bnt”:
It may contain the following variables:
|**Material** |The material (.mat file) that the billboard has. //String// |
|**Type** |The type of billboard. “Point” or “Axis”. Point means the billboard is rotated around its center and axis means that it is rotated round its axis. //String// |
|**UseOffset** |If the billboard should be offset closer to the camera when rendering. //Boolean//. |
|**IsHalo** |If the billboards is a halo. This means that it will loose strength if the source is blocked from view. //Boolean// |
|**HaloSourceIsParent** |If the parent entity of the billboard (must be a submesh) will act as light halo source. //Boolean// |
|**HaloSourceSize** |If the parent is not source then this will use as size of the source. Center of the source is the position of the billboard. //Vector3// |
Important halo information: There can only be **one** billboard attached per submesh!
==== 3.13 Beams ====
Beams is a flat image that is repeated from a start to an end point creating for example a laser beam. The syntax for placing a beam is the following:
**_beam_[file]_[name]** \\ **_beamend_[name]**
|**file** |The entity file containing data about the beam, may contain “_” in the name. |
|**name** |The name that will be used in game. |
A beam is made up of two parts in the editor, one _beam for the start position and one _beamend for the end position. It's important that the beamend has the same name as the beam.
The entity file looks like this and is a file with the extension “.beam”:
It may contain the following variables:
|**Material** |The material (.mat file) that the beam has. //String// |
|**Size** |“X Y”.X= the thickness of the line, width of texture used. Y = the length that one texture height takes. //Vector2// |
|**TileHeight** |If Size.x should be used and texture tiled. //Boolean// |
|**MultiplyAlphaWithColor** |If the color should be multiplied by alpha. Makes some things simpler. //Boolean// |
|**StartColor** |“R G B A” Color at start. //Vector4// |
|**EndColor** |“R G B A” Color at end. //Vector4// |
==== 3.14 Particle systems ====
Particle systems are used for effect such as fire, smoke, etc. The syntax for placing a particle system is:
**_ps_[particle system name]_[name]**
|**particle system name** |Entity file containing data about the billboard, may contain “_”. |
|**name** |The name that will be used in game. |
Particle systems are created with the Particle Editor, which is [[:hpl1:documentation:particle_editor_document|documented here]] and a tutorial is [[:hpl1:tutorials:tutorial_4_-_particles|available here]].
\\
==== 3.15 Workflow ====
What follows is a suggestion on the workflow used when creating a map for the HPL engine.
[MORE ON THIS LATER]
==== 3.16 Optimizations ====
The following “tips” are very important to follow as good as possible since they can improve the framerate quite a lot.
* Set small objects to “noshadow”, since shadows on smaller objects are not noticeable.
* Set “noshadow” on objects that cannot cast a shadow on anything. This is for example a floor if there is no floor below. Think about this when designing maps and quite some framerate can be gained.
* Do not let several large objects that are not close together be apart of the same mesh object. This is for example the 4 walls in a room. Separate these so they are 4 individual objects instead of **one**.
* While it is bad to put many BIG objects together. It is really good to put many small together. If you have 20 static cans spread over the floor in a room it is a lot better to collapse them all together to a single object (**beware**: grouping is **not** the same as collapsing, Maya word for this is unify). However do not collapse several small objects that are spread over an entire level. The objects should be close together (like on the same floor in a room.
* The number of lights is not the biggest problem. The biggest problem is **overlapping** lights. Overlapping means that the bounding boxes from 2 lights intersect. Try to have at most 3 overlapping lights and mostly 2 lights overlapping. If the lights don’t cast shadows it is okay if more lights overlap.
* Highpoly meshes should have collisions turned off and use colliders to simulate the shape.
==== 3.17 Issues ====
* If a room is totally self contained (like a cube with the sides inverted) then the shadows will be messed up. You can fix this by detaching one of the walls or just turn off shadows for the room. Since no shadows will be visible from the room turning of the shadows is the best bet.
* Two faces in the same object may **not** share the same vertices, even if the order is inverted! This means that double sided polygons are not supported! This only applies to geometry that cast shadows though.
* An edge may only have **one** or **two** faces! If this is not followed shadows will be messed up.
\\