Adding a voxel unit ingame

This guide was created 2013-09-09 and works for the 20180923 release.

This will be a step by step in depth guide on how to add a voxel unit to your game. As with all my guides I recommend using Notepad++ to edit the yaml file. I will not write a guide how you make a voxel, just how you add a finished voxel into the game. In this guide, I will add a voxel Apache helicopter and we will add it to a mod based on Red Alert.

The files we will edit are.

• A unit yaml file (i.ex. rules/aircraft.yaml)
• A Sequence yaml file (i.ex. sequences/aircraft.yaml)
• voxels.yaml (i.ex. sequences/voxels.yaml)
• palettes.yaml
• mod.yaml

All these files should be added to the mod.yaml file. Otherwise our game will crash when we try out the unit.

Unit Files

Before we start editing our unit (i.ex. our helicopter) we need to add the voxel to the game. Put the finished vxl into the bits folder. We also need a cameo (icon) for our unit, it should be named the same as the unit with icon writen at the end. Finally, we need color palette files so the unit and cameo can be colored properly.

Example:

• apache.vxl
• apache.hva
• apchicon.shp
• unittem.pal
• cameo.pal

All of the above files can be found in the Tiberian Sun content files. You will need to place these in the bits/ directory of your RA installation so the game can load them.

Unit YAML

Lets start with the code for the unit. Open up our unit yaml file, in this example we would open the aircraft.yaml inside the rules folder. For simplicity you can just add this code at the bottom of the file. The most important part is that the name APACHE is the same name as the voxel.

APACHE:
	Inherits: ^Helicopter
	-SpawnActorOnDeath:
	-WithShadow:
	-WithFacingSpriteBody:
	Valued:
		Cost: 2000
	Tooltip:
		Name: Apache Longbow
	Buildable:
		Queue: Aircraft
		BuildAtProductionType: Helicopter
		BuildPaletteOrder: 20
		IconPalette: tscameo
		Prerequisites: hpad, atek
		Description: Helicopter gunship armed\nwith dual chainguns.\n  Strong vs Infantry, Light armor\n  Weak vs Tanks, Aircraft
		Owner: allies
	Selectable:
		Bounds: 30,24
	Aircraft:
		RearmBuildings: hpad
		LandWhenIdle: false
		InitialFacing: 224
		TurnSpeed: 4
		Speed: 112
	Health:
		HP: 200
	Armor:
		Type: Light
	RevealsShroud:
		Range: 12
	Armament@PRIMARY:
		Weapon: HellfireAA
		LocalOffset: 0,-213,-85
	Armament@SECONDARY:
		Weapon: HellfireAG
		LocalOffset: 0,213,-85
	AttackHeli:
		FacingTolerance: 20
	AmmoPool:
		Ammo: 24
		PipCount: 6
		ReloadDelay: 8
		AmmoCondition: ammo
	AutoTarget:
	WithIdleOverlay@ROTORAIR:
		Sequence: rotor
		Offset: 85,0,384
	BodyOrientation:
		QuantizedFacings: 0
	RenderSprites:
	RenderVoxels:
		PlayerPalette: tibsun
		Scale: 8
		LightAmbientColor: 0.2, 0.2, 0.2
		LightDiffuseColor: 0.6, 0.6, 0.6
	WithVoxelBody:

It's important that the code name of the unit is the same name as the voxel. Thats it for the unit, you might need to play around with the Scale trait to get your unit in the right size, and play around with the rotor offset to get the rotor(s) in the correct position. Everything else here should be straight forward. If something is unclear you can always check my creating a new unit guide here.

What have we accomplished?

Added the base code for the unit. Which building does it come from, how much should it cost, what weapon to use et.c. We also disabled some inherited traits (WithShadow, WithFacingSpriteBody) that expect the unit to use sprites.

Save the file and close it down. Time to move on.

Sequences yaml

Now lets open up the Aircraft.yaml file in the sequences folder for our Apache Helicopter.

We need to add this line of code inside the aircraft.yaml (at the top, bottom or somewhere in the middle. Your choice)

apache:
	icon: apchicon
		Start: 0
	rotor: lrotor
		Start: 0
		Length: 4
	slow-rotor: lrotor
		Start: 4
		Length: 8

What have we accomplished?

Added the icon (cameo) for our unit and gave it a rotor so it wont look stupid when it flies. :)

Save the aircraft.yaml file in sequences and close it down. Lets head on.

Voxels.yaml

Create a new file if you do not have a voxels.yaml and name it exactly that. Adding voxel is a rather new function and this file is needed for voxel. in the voxels.yaml you add all your voxels. If we did a tank we would add the tank voxel first, then bind it together with the turret voxel and the turret voxel with the barrel voxel.

Luckily for us, we aren't doing a tank, we are doing a helicopter so all we need to add is this.

apache:
	idle:

If you are interested in how the code for a tank should look like then here's an example.

4tnk:
	idle:
	turret: 4tnktur
	barrel: 4tnkbarl

That would be the code for Tiberian Sun Mammoth tank.

What have we accomplished?

We just made the game understand that our helicopter is a voxel and not a shp. If we made a tank we also made it understand what is what. (what voxel is the body, the turret and the barrel)

Save and close voxels.yaml down. It's time to move on.

Palettes YAML

The absolute first thing we will do is to insert the palette under the ^Palettes: trait. Insert this code:

PaletteFromFile@tibsun:
	Name: tibsun
	Filename: unittem.pal
	ShadowIndex: 4
	AllowModifiers: false
VoxelNormalsPalette@normals:
	Name: normals
	Type: TiberianSun
PaletteFromFile@tscameo:
	Name: tscameo
	Filename: cameo.pal
	AllowModifiers: false
PlayerColorPalette@tibsun:
	BasePalette: tibsun
	BaseName: tibsun
	RemapIndex: 16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31

Your code should look something like this in palettes.yaml (From the beginning of the file):

^Palettes:
	PaletteFromFile@tibsun:
		Name: tibsun
		Filename: unittem.pal
		ShadowIndex: 4
		AllowModifiers: false
	VoxelNormalsPalette@normals:
		Name: normals
		Type: TiberianSun
	PaletteFromFile@tscameo:
		Name: tscameo
		Filename: cameo.pal
		AllowModifiers: false
	PlayerColorPalette@tibsun:
		BasePalette: tibsun
		BaseName: tibsun
		RemapIndex: 16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31
	PaletteFromFile@player:
		Name: player
		Filename: temperat.pal
		ShadowIndex: 4

What have we accomplished?

We added the unit color palette from Tiberan Sun and fixed the normals palette so your voxel unit wont turn up colored like a rainbow... And thats a good thing.

We also added the cameo color palette from Tiberian Sun so that the unit cameo would be colored properly. You can read more about palettes here.

Lets save the palettes.yaml file and close it down. Almost done here.

Mod.yaml

The Mod.yaml file is a very important file, the game reads this and the file tells the game what files to read, so you need to add all the files that are new. Search after sequences, something like this should pop up:

Sequences:
	mods/yourmod/sequences/ships.yaml
	mods/yourmod/sequences/vehicles.yaml
	mods/yourmod/sequences/structures.yaml
	mods/yourmod/sequences/infantry.yaml
	mods/yourmod/sequences/aircraft.yaml
	mods/yourmod/sequences/misc.yaml
	mods/yourmod/sequences/decorations.yaml

Create this under sequences but above cursors:

ModelSequences:
	mods/yormod/sequences/voxels.yaml

You will also need to change ModelSequenceFormat to support voxels.

ModelSequenceFormat: VoxelModelSequence

What have we accomplished?

We added the voxels sequences file to the mod.yaml file. The game will now load that file when it starts up!

Save and close down mod.yaml.

What now?

Start the game and test your new voxel unit.

My voxel has incorrect scaling / bounds

See #4113:

The Scale variable in the VXL header is ignored in the Westwood engine while OpenRA acknowledges it. While ra2ff.txt notes Scale is usually 0.083, community-made voxels have this as 0.83 because of a bad default value in VXLSE.

See this post on Project Perfect Mod on how to fix the issue.