Decal System

From HEWIKI
Jump to: navigation, search

Decals are small pieces of geometry that are dynamically stamped into the world, typically used for things such as damage indicators, like bullet marks. Decals are created and managed via a few simple CLIENT-SIDE HSL external functions. Decals are not affected by lighting, thus appearing in full color regardless of lighting conditions.

Contents

Requirements

The Decal System requires a new data asset be present in the repository to run:

KeyValueSpec

Since there are quite a few parameters needed to define the behavior of a Decal, including randomized values, the existing Key Value Spec API system is used. The key/value specification for a decal is as follows:

KeyValueSpec to define a decal
Key
Type
Sample Values Used Below
Purpose
diffuse
string
/Engine/CleanGame/Decals/bulletholes_concrete_4x.dds
The FQN of the diffuse texture for the decal
normalMap
string
null.dds
The FQN of the normal map for the decal (not currently used)
heightMap
string
null.dds
The FQN of the heightmap of the decal surface (not currently used)
tileCount
integer
4
The number of tiled frames in the decal.  Minimum is 1, maximum is 16 (4x4)
spacing
float
0.25
How close two identical decals (same material) can be next to each other
decalSize
gaussian
0.05
The randomized size of the decal; a single value means no variation.
decalRotation
gaussian
0
The randomized rotation of the decal, between 0 and 360 degrees; a single value means no variation.
killTime
gaussian
60
The randomized time, in seconds, to delete a decal once created; a single value means no variation.
killWhileVisible boolean false By defaults decals are never deleted while visible
 

CreateKeyValueSpec("Decal","")           // Creates a named KeyValueSpec called 'Decal'

 AddKeyValueSpec("Decal","diffuse      = string,/Engine/CleanGame/Decals/bulletholes_concrete_4x.dds       # The diffuse texture to use for the decal")

 AddKeyValueSpec("Decal","normalMap    = string,null.dds       # The normal map to use for the decal")

 AddKeyValueSpec("Decal","heightMap    = string,null.dds       # The heightmap to use for parallax mapping")

 AddKeyValueSpec("Decal","tileCount    = integer,4,1,16           # The number of tiles in the source texture 2x2=4 3x3=9, 4x4=16")

 AddKeyValueSpec("Decal","spacing      = float,0.25,0.001,10   # How close two decals of this type can be next to each other")

 AddKeyValueSpec("Decal","decalSize    = gaussian,0.05         # The randomized size of the decal, as a gaussian number")

 AddKeyValueSpec("Decal","decalRotation = gaussian,0           # The randomized rotation of the decal, as a gaussian number and in degrees")

 AddKeyValueSpec("Decal","killTime     = gaussian,60            # Number of seconds to keep the decal")

 AddKeyValueSpec("Decal","killWhileVisible = boolean,false     # By default, never kill a decal if it is currently visible.")

KeyValueData

decal1 as ID

decal2 as ID

decal1 = CreateKeyValueData("Decal","diffuse=/World/decal1.dds")

decal2 = CreateKeyValueData("Decal","diffuse=/World/decal2.dds") 

Creating a Decal

Example script to create a decal

The following HSL sample script will create a decal at the impact location of a ray projected from the current camera position.

function decalTest()

 CreateKeyValueSpec("Decal","")           // Creates a named KeyValueSpec called 'Decal'

 AddKeyValueSpec("Decal","diffuse      = string,/Engine/CleanGame/Decals/bulletholes_concrete_4x.dds       # The diffuse texture to use for the decal")

 AddKeyValueSpec("Decal","normalMap    = string,null.dds       # The normal map to use for the decal")

 AddKeyValueSpec("Decal","heightMap    = string,null.dds       # The heightmap to use for parallax mapping")

 AddKeyValueSpec("Decal","tileCount    = integer,4,1,16           # The number of tiles in the source texture 2x2=4 3x3=9, etc")

 AddKeyValueSpec("Decal","spacing      = float,0.25,0.001,10   # How close two decals of this type can be next to each other")

 AddKeyValueSpec("Decal","decalSize    = gaussian,0.05         # The randomized size of the decal, as a gaussian number")

 AddKeyValueSpec("Decal","decalRotation = gaussian,0           # The randomized rotation of the decal, as a gaussian number and in degrees")

 AddKeyValueSpec("Decal","killTime     = gaussian,60            # Number of seconds to keep the decal")

 AddKeyValueSpec("Decal","killWhileVisible = boolean,false     # By default, never kill a decal if it is currently visible.")


 data as ID

 data = GetKeyValueSpecDefaultData("Decal") // Get the data ID containing the default values.


 eyePosition as Vector3

 eyeDirection as Vector3

 endPosition as Vector3

 GetEyeVector(eyePosition,eyeDirection) // Get the current eye position and eye direction vector


 endPosition = eyePosition + (eyeDirection*10) // compute an end position to raycast too


 intercept as Vector3

 normal as Vector3

 hitNode as ID


 hitGroup as String

 hitMaterial as String

 hitName as String

 hit as Boolean


 hit = RaycastPhysXDetailed(eyePosition,endPosition,"CGF_GRAPHICS_ONLY","CGF_NONE",intercept,normal,hitNode,hitGroup,hitMaterial,hitName) // Perform a detailed raycast


 if hit // if the raycast hit the world

   println("intercept " + intercept )

   println("normal" + normal )

   println("hitNode " + hitNode )

   println("hitGroup " + hitGroup )

   println("hitMaterial " + hitMaterial )

   println("hitName " + hitName )

   decalId as Integer

   decalId = CreateDecal(data,intercept,eyeDirection,normal,false) // create the decal at the impact location

   println("Decal Id is " + decalId )

 .

. 

Decal-related HSL external functions

These are the HSL external functions which are available to manipulate decals.

external function GetEyeVector(eyePosition references Vector3,eyeDirection references Vector3) as Boolean

external function RaycastPhysXDetailed(v1 as Vector3,v2 as Vector3,includeFlags as String,excludeFlags as String,intercept references Vector3,normal references Vector3,hitNode references ID,hitGroup references String,hitMaterial references String,hitName references String) as Boolean

external function CreateDecal(specData as ID,position as Vector3,eyeDirection as Vector3,hitDirection as Vector3,uniqueId as Boolean) as Integer

external function ReleaseDecal(decalId as Integer)

external function ClearDecalsInBox(bmin as Vector3,bmax as Vector3) as Integer

external function ClearDecalsSpec(specData as ID) as Integer 


Collision Group Flags

This section lists the available collision group flags:

CGF_GENERAL  : items that have not yet been classified into any particular group.

CGF_COLLIDE_ONLY  : Geometry marked only for collision, not for display.

CGF_TRANSPARENT  : Geometry marked as transparent

CGF_IGNORE_CAMERA  : Geometry flagged to indicate that the camera should not collide with it.

CGF_PLAYER  : this surface is flagged to indicate that the object represents a 'player'

CGF_NPC  : this surface is flagged to indicate that the object

CGF_SELECTED  : this surface is flagged as a currently selected item

CGF_INACTIVE  : This surface is marked as currently inactive

CGF_WATER  : this surface is flagged as water

CGF_NO_COLLIDE  : this surface is flagged as 'don't' collide.

CGF_IGNORE_FOR_PLAYER  : This object is marked as ignore for player

CGF_IGNORE_FOR_NPC  : this object is marked as ignore for NPC

CGF_DYNAMIC  : This object is being dynamically simulated

CGF_KINEMATIC  : This object is under kinematic control.

CGF_PLAYER_COLLIDE  : This object is flagged as being the player collision volume.

CGF_RAYCAST_ONLY  : This geometry is only used for graphics, not for collision purposes

CGF_HEIGHTFIELD  : This geometry is part of a heigthfield.

CGF_NO_PHYSICS  : This geometry is excluded from the physics/collision system.

CGF_PATHFINDING_NODE  : The geometry is part of a pathfinding node.

CGF_IGNORE_FOR_PATH_FINDING : This object is marked as being ignored for path finding.

CGF_BLOCK_ONLY  : This object only blocks for path finding

CGF_REGION_NODE  : This object is a region node.

CGF_SELECTED_NO_COLLIDE  : This is a non-colliding but currently selected object.

CGF_OCCLUDER  : This is an occluder.

CGF_CHARACTER_COLLISION  : This geometry is part of the character collision representation.

CGF_CLOTHING  : This geometry is part of the character/cloth collision model.

CGF_DYNAMIC_MOTION  : Indicates a dynamic object that is currently in motion (not at rest)

CGF_DEFAULT  : The collection of bit flags that form the default collision behavior

CGF_EVERYTHING  : Turns on all collision bits

CGF_CAMERA  : The collection of flags describing what the character collides with.

CGF_HIT_CHECK  : The default flags to collide with both the world and the characters.

CGF_SELECTION  : Default flags for objects that can be selected.

CGF_NO_WATER  : Default collision flags but without water.

CGF_PLAYER_COLLISION  : Default collision flags for players.

CGF_PATH_COLLISION  : Default collision flags for path generation.

CGF_IGNORE_FOR_PATH_FINDING  : 

CGF_GRAPHICS_ONLY  : Only the graphics components, use this for decals.


Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox