HPL1/Content Creation Chapter 9

9 Heads-Up Display files

9.1 Intro

The Hud Object Editor is a tool that aids you with creating items that can be wielded in-game, this can be anything from a custom lantern, throwable object or even a custom weapon for defending yourself.

Heads-Up Display files are XML files and before editing them it is suggested to read some quick tutorial on XML files. Only very basic XML understanding is needed to edit these files.

The files are divided into different sections, some sections are in all hud files and some are only present in certain hud types.

Prior to editing Heads-Up Display (*.hud) files make sure that the language is set to XML in Notepad++.

The following values are used, note that all types have "" around the value:

String	A string of letters. "MyName" or "My_Name"
Float	A decimal number. "1.04" or "1.04f"
Integer	A number without decimals "-15"
Vector3	Three numbers in a row separated by space: "1 1 1".
Boolean	A data type using "true" or "false" values.

9.1.1 Prerequisite

In order to use the Hud Object Editor you need the fmod library and the Verdana font. You can download these things from the Getting Started page. The prerequisites archive also contains an offline version of this document as well as some other last minute information, should the wiki ever go down for whatever reason.

Toss the fmod Dynamic Library Link (*.dll) into the redistributable directory of Penumbra and the Verdana TrueType Font into the fonts folder.

Depending on where you installed Penumbra the Drive letter and directory might differ from the following example:

The fmod.dll file goes into
C:\penumbra2\redist
And the TrueType Font goes into
C:\penumbra2\redist\fonts

The program can only be called via Windows' Command Prompt. Grip never made a GUI for the program, you must also be in the redistributable directory when calling the program.

9.1.2 Invocation

In the Windows Command Prompt, change the directory to the folder and drive where you have penumbra installed.

cd C:\penumbra2\redist

Then, load the Collada file (*.dae) while invoking the program. File extension isn't necessary.

hudobjecteditor my_model

The program will then fire up while using the HPL engines resource configuration file to search and index all directories currently written to it. Your model file and the accompanying materials for it can be placed anywhere you like so long as it's within the reach of the resource.cfg file.
Use the HPL Helper program to add new directories or type them out manually with something like Notepad++.

9.2 Hud Object Editor

When you first fire up the program, you'll notice that it's very similar to the Model Viewer program. The controls are the same asides from a few minor changes.

Left Mouse Button:	Dolly around.
Middle Mouse Button:	Zoom in/out.
1:	Switch to viewer camera.
2:	Switch to Player camera.
A and Z:	Rotate models along the X axis. (A rotates up Z rotates down)
S and X:	Rotate models along the Y axis. (S rotates counter-clockwise X rotates clockwise)
D and C:	Rotate models along the Z axis. (D rotates left C rotates right)
P:	Prints the axis information to the Hud Object Editor log file to be used when creating the Heads-up Display (*.hud) file.
Arrow keys:	Moves the model in the respective directions. (Up, Left, Right, Down etc.)
Page Up:	Move item forward.
Page Down:	Move item backward.

9.2.1 Heads-Up Display reference file

Below you will find a sample that will help you define a HUD file.

Use the Hud Object Editor to print the XYZ axis position and rotation values and then paste it to the Equip and Unequip roations and positions.
You can print multiple axis values without having to close the program down each time.
The Sound Entity (*.snt), Particle System (*.ps) and Entity (*.ent) files don't need their extensions when being referenced.

MAIN must always be present to define and reference the items to be used.
THROW is used for items with the Throw type.
MELEE is used for miscellanous stuff, not needed.
ATTACK is only used for WeaponMelee types. It defines various weapon information like how much damage it can deal, starting position and so forth.
For example: if the item is a "Throw" type, you get rid of the ATTACK tags.

When you're finished, create a new text file and rename the extension from .txt to .hud and then copypaste the stuff below into it to be used in-game.

<HUD_MODEL>
	<MAIN
		Name = "String, name of the item (for example: Meat, Lantern)"
		Type = "Valid types are Throw and WeaponMelee, remove this line if object is neither"

		ModelFile = "String, name of a valid Collada (*.dae) file to be used, must include extension as well when referencing (I.E banana.dae)"
		EquipTime = Float, how long it takes to draw the item.
		UnequipTime = Float, how long it takes to holster the item.

		EquipPose_Pos = "Vector3, XYZ position of the item when drawn"
		EquipPose_Rot = "Vector3, XYZ rotation of the item when drawn"

		UnequipPose_Pos = "Vector3, XYZ position of the item when holstered"
		UnequipPose_Rot = "Vector3, XYZ rotation of the item when holstered"

		EquipSound = "String, name of the Sound Entity (*.snt) file to be used when drawing the item"
		UnequipSound = "String, name of the Sound Entity (*.snt) file to be used when holstering the item"
	/>
	<MELEE
	 	DrawDebug = "Boolean, whether or not to display debug information for the Haptic hardware"

	 	HapticSize = "Vector3, this was meant to be utilized by the Novint Falcon controller with Reachin Technologies' HaptX API but remains unused"
	/>
	<ATTACK
	 	Name = "String, name of the item (for example: SwingLeft, SwingRight, Poke)"
	 	
	 	StartPose_Pos = "Vector3, XYZ position of the item when being positioned to strike"
		StartPose_Rot =	"Vector3, XYZ rotation of the item when being positioned to strike"
		
		EndPose_Pos = "Vector3, XYZ position of the item when being positioned to strike"
		EndPose_Rot = "Vector3, XYZ rotation of the item when being positioned to strike"
		
		AttackLength = "Float, how fast or slow the attack animation should play"
		ChargeLength = "Float, how fast or slow the charge animation should play"
		
		TimeOfAttack = "Float, how long it takes before the attack begins"
		
		MaxImpulse = "Integer, maximum impulse"
		MinImpulse = "Integer, minimum impulse"
		
		MinMass = "Integer, minimum mass"
		MaxMass = "Integer, maximum mass"
	
		MinDamage = "Integer, minimum damage dealt"
		MaxDamage = "Integer, maximum damage dealt"
		
		SpinMul = "Vector3, If the weapon spinning should be multiplied to the forward/backward force when moving the mouse up/down"

		DamageRange = "Float, how far the damage can be dealt"
		DamageSize = "Vector3, how large the damage area is in XYZ axis format (0 0 0)"
		
		AttackRange = "Float, how far the attack range is"
		
		AttackSpeed = "Integer, speed of the attack"
		AttackStrength = "Integer, strength of the attack"
		
		HitPS = "String, the Particle System (*.ps) file to be used when the weapon hits something"
		HitPSPrio = Integer, set Particle priority
		
		SwingSound = "String, name of the Sound Entity (*.snt) file to be used when swinging the weapon"
		ChargeSound = "String, name of the Sound Entity (*.snt) file to be used when charging the weapon"
		HitSound = "String, name of the Sound Entity (*.snt) file to be used when the weapon hits something"
	/>
	<THROW
	 	ChargePose_Pos = "Vector3, XYZ position of the item when being prepared to be thrown"
	 	ChargePose_Rot = "Vector3, XYZ rotation of the item when being prepared to be thrown"

		ChargeTime = "Integer, how long it takes to prepare the item to be thrown"
		MinImpulse = "Integer, minimum impulse given when thrown"
		MaxImpulse = "Integer, maximum impulse given when thrown"

		ReloadTime = "Float, how fast it takes to draw another batch"

		Torque = "Vector3, set rotation"

		ThrowEntity = "String, the entity (*.ent) file to be used when the item is thrown"

		ChargeSound = "String, name of the Sound Entity (*.snt) file to be used when charging the item"
		ThrowSound = "String, name of the Sound Entity (*.snt) file to be used when throwing the item"
	/>
</HUD_MODEL>