WAX File Generator

Video Tutorial:

While everything you need has been documented on this wiki, many prefer to follow along the process in video tutorial form:

Overview:

Enemies and other sprites in Dark Forces are in the WAX file format. Effectively they are a series of bitmap images, adhering to a set palette, with position data and ordered in to sequences - ie Walking Side Left, Ranged Attack Front, and so on. Editing these or creating a new one from scratch has generally been a very time consuming process. Especially with early tools available to the mod community. The goal of the Wax File Generator is to streamline that process with a purpose built collection of rigged 3D models, easy customisation options and templates for the various enemy types in the game, with added idle loop options for animated background characters.

While it is a Blender based tool, it has been created to be simple for users with no prior 3D knowledge required. All the core functionality is in a custom UI panel on the right hand side of the main 3D view-port. Switching enemy animations, randomising full outfits, selecting a specific alien species or Imperial armour type - it's all there.

Before we begin, there are a few things to download.

Download Requirements:

Before we get started, there are some tools to download:

1) Blender: https://www.blender.org/download/ - current version (4.4 at time of writing, multi platform)

           or if need be https://download.blender.org/release/ for any and all previous releases.

2) WAX/FME Convertor (by Jereth Kok): https://df-21.net/downloads/utilities/waxconverter/waxconverter.zip (Windows specific)

          Note: Requires .NET 6.0 - Version 3.2 - June 2024 Release

3) The template files, available here: (Insert link here when files complete)

The template files consist of one main Blender file and a 'Render' subfolder. Inside the 'Render' are a series of specifically named _***_Template folders. Please do not rename these as the folder naming structure is referenced by both Blender and Wax Convertor for this process to be as smooth as possible.

The general process is as follows:

• Load the Blender file and use the script to create a character combination you want for your level
• Render out the frames - the script should select which render sub folder for you automatically
• Run the Photoshop / Gimp script to trim the images before loading Wax Convertor
• Open the render sub folder - for example \Render\_TROOP_LH_Template - and open _TROOP_LH_Template.wproj in Wax Convertor
• (Optional) Make any minor tweaks required to position / colour palette file selection, defaults should generally be fine
• Click 'Create WAX!'

Initial Blender Setup:

First things first, install Blender on your machine. This can be as simple as downloading the .zip option and extracting to a folder on your desktop if you don't intend to use Blender often. Once that is done, there are two settings to check in the preferences to make the process smoother.

Go to 'Edit - Preferences' from the top menu bar. Select 'System' on the left, then choose a Cycles Render Device up the top if available. Cycles will run fine on a CPU only, but it's significantly faster if one of these options are available.

Select 'Save & Load' on the left, then check 'Auto Run Python Scripts'. If not selected, you will need to run the rig ui script and character ui script each time you load the Blender file.

Blender will automatically save these preferences for future use, so you can now load the Blender file.

Dark Forces "WAX File Generator" UI:

The core of what you will be doing to create a character for use in the game is in the Blender UI, with the custom scripted panel. If you don't see the custom panel on the right of the screen with the obvious Dark Forces Character Creator title art when loading the file, please see the above section about enabling auto run of Python Scripts, or manually set the script running from Blender's Text Editor.

The UI is split in to six main sections. Each can be collapsed or expanded with the arrow on the top left of the sub panel, next to the title. Each UI option has a tool tip written if you hover over with the mouse, but hopefully the buttons are pretty straight forward in most cases.

Panel 1: Character Animation Options:

First and foremost is the 'Select Animation Set' drop down menu. This changes the animation on the character (and importantly the frame range of the render) to give you an equivalent Dark Forces enemy type. Most options have a left handed and right handed (LH / RH) option, just for visual variety. Functionally they are the same. All animation sets now work with 8x view angles for melee attacks, ranged attacks, pain / hit reactions and idle animations. This is to support the newer 'teams' feature, where enemies can fight other enemies within a set of rules defined by the mod creator.

Current Animation Set / Enemy Type Options:

Enemy	Notes
TROOP	Standard Stormtrooper replacement. There is an added melee rifle butt attack as an option if using custom logic.
REEYEES	Gran (Ree-Yees) logic replacement. Includes both melee and Thermal Detonator attacks.
IDLE 1-4	Four options for Idle animations, for use with static NPC characters. This also includes hit reactions, acknowledging the player (ie, attack with no damage through custom logic) and death if the level author chooses. Otherwise use 'ANIM' in the level editor as in existing / older levels.
PROBE DROID	Template for flying enemies. Best with a custom logic, but can be a replacement for vanilla Probe Droid. Also largely works for the Dark Trooper Phase 2, but may cause some hitbox / projectile alignment issues.
BOBA FETT	Speaks for itself - animation to work with Boba Fett vanilla logic, but with more frames for an animated jetpack and a large rocket launcher that is somewhat more believable than a pistol with infinite rocket ammo.
GAMGUARD	Replacement for Gamorrean Guards with an animated shock stick. There is an added ranged pistol attack as an option.
UNARMED WALK	Through custom logics, you can create an NPC that casually walks around the area without really acknowledging the player. Logic example included in the files.
FUSION CUTTER	Similar to 'TROOP', but with the Fusion Cutter visibly used as the weapon. This includes a melee attack with the weapon.
MORTAR	Similar to 'TROOP', but with the Mortar visibly used as the weapon. This includes a melee attack with the weapon. There is a sprite replacement included for WSHELL.WAX to work both directions, as the vanilla Mortar was only ever fired from the player's view.
CONCUSSION (BOSSK)	Replacement for the BOSSK logic, with an added option for a melee attack with the weapon. There is a sprite replacement included for CONCEXP.WAX as well as a concussion rifle projectile. There is also a custom projectiles.json to make use of the custom projectile.
PISTOL (OFFICER)	Officer logic replacement. There is an added melee animation as an option.
REPEATER	Similar to 'TROOP', but with the Repeater visibly used as the weapon. This includes a melee attack with the weapon. Mod makers may want to make use of the 'Burst Fire' options with the custom logics.

The next drop down menu for 'Select Shorter Animation Set' is for certain animations to be rendered with less frames. This is faster to render and more in line with Vanilla sprites, because secondary attacks (except REEYEES) and animated idle states are left off.

'Generate Random Alien' was the base of the whole script initially. It keeps the animation type and randomises all the visual elements of the character. This is generally spilt to head, torso, legs, armour and the respective colours for each. Given how many expanded colour palette options are now available, true 'random' can generate some pretty stark colour combinations, so some further tweaking is expected by the user. (Mostly found later in the 'Civilian Mercenary Options' panel). Random heads and random colours only should be self explanatory.

Humanoid Head options are for humans and aliens with human heads but for example - blue skin tone like the Chiss. This allows for shared hair and facial hair options between them. This will disable any other alien heads or headgear / helmets for other options when generating a whole head, but beard options on an Imperial officer can be changed without losing the hat. Random Imperial Enemy is included in this panel as a quick option, further Imperial options are located later in their own panel.

Current Species Head Options:

Twilek	Duros	Rodian	Sullustan	Twilek (Alt)	Ithorian
Mon Calamari	Gran (Ree-Yees)	Quarren	Bith	Devaronian	Arcona
Trandoshan	Kubaz (Garindan)	Pyke (Syndicate)	Bothan	Chagrian	Gand (Zuckuss)
Wequay	Togruta	Aqualish (Ponda Baba)	Yarkora	Human	Falleen (Xizor)
Mirialan	Chiss (Thrawn)

Panel 2: Rendering Options:

By default - you don't need to touch any of these, but they are there if needed.

NOTE - Render Character Animation will lock up the UI until the render is done. Using the normal render animation option in the Blender UI won't and you can view a progress bar per frame. It's only an ease of use option so you don't need to know any of Blender's native UI. Either way works, just know that Blender isn't broken while it's rendering.

Render quality should be on 100 by default. More samples means less noise and higher render times. This can be set in the regular Blender UI, but I have included some easy presets. Rim light is on mid (50) by default and is purely an aesthetic choice to help certain characters stand out more against the background. Barrel Glow means a glowing point inside the weapon visible at all times, defaulted to off.

Also, in order to see any of the colour changes on the meshes, you will need to turn viewport rendering on, which is the fourth of four spheres in the top right of the viewport, just above the script.

Panel 3: Civilian / Mercenary Options:

It's the bulkiest panel of options, but hopefully it's pretty easy to understand. For working with aliens and humans that are not Imperial or Rebel. Random Clothes keeps the same colour scheme and changes the body meshes. Clothing Colours does the reverse - keeps the body meshes and randomises the clothing colours. Because there are quite a variety of colours in the extended palette (included in the download as X-GENERIC.PAL and .CMP, recommended) and it is a true random, many of the colour combinations don't work too well. Options to specifically dial in the colours have been added.

Any options where 'Col1, Col2, etc' are provided, a drop down menu will appear with a list of 20 colours. The later options are marked (Extra) because they use the extended palette. As in the base game of Dark Forces doesn't have purple in most levels by default. The other colours (White through Dark Blue) will work in effectively any level palette as they are only using the common colours that all levels of the base game use and the vast majority of custom missions.

The options for Solid Torso Colour or Solid Legs Colour will change all colour slots on the Torso and Legs respectively.

Cloth and Belt Width options are more for troubleshooting corner cases with robe style cloth on the Legs. Use as needed if you see intersection issues on the legs, which should be minimal.

Civilian Armour Options control the shoulder pads, shin guards and so on for civilian characters. Imperial and other categories have their own specific armour such as Stormtroopers and their variants.

Finally in this panel we have options for creating Mandalorians with the RandoMando TM button and colour options, as well as Tusken Raiders. Tuskens will always adhere to the standard Dark Forces colour palette and there are only so many combinations, which is why no further colour tweaking options are implemented at this point.

Female variations are planned further down the track, but not yet included.

Panel 4: Imperial Options:

Given that Imperial troopers and personnel are very distinct and a very important part of a game where you fight the Empire... they get their own section. The base game obviously has Stormtroopers and other Imperials already. Now you can give them different weapons, adjust their rank, damage the armour and generally change things up. We have all seen enough of the standard trooper right? Selecting (or randomising) an Imperial gives you options for the following.

Current Imperial Personnel Options:

ATAT Pilot	Imperial Army Trooper	Imperial Navy Commando	Imperial Officer	Juggernaut Transport Driver
Patrol Trooper	Sandtrooper	Scout Trooper	Shore Trooper	Snowtrooper
Stormtrooper (Standard)	Swap Trooper	Tie Pilot

Base colour in some cases randomises the amount of grime and wear more than the colour options themselves. Some units like the Officer have a few different colour combinations that should line up to Star Wars lore and this will cycle between them. ISB officer white tunic, olive green (though more saturated than the films) and so on. Trim colour allows for some amount of colour to appear on (most) uniforms, similar to the colouring of the Clone Troopers in the prequels. This trim can be selected, randomised or turned off completely. Could be used for highlighting trooper disciplines like Mortar, different squads of troops guarding the Red or Blue key area or to help illustrate some specific story points.

For units like the Commando that have a shoulder pauldron, this can have a colour selected, the pauldron can be hidden, or reselecting a colour will turn the pauldron back on. This does not apply to all Imperial units.

Panel 5: Rebel Options:

Why would you need Rebel Alliance Wax files you might ask?

A few reasons, considering the new options now available to mod makers in The Force Engine. Firstly, you can now have teams for the different Wax logics. This means dynamic battles are now possible similar to the demon in-fighting seen in DOOM. Except you have options that a certain team will always be on the player's side, always against any side that isn't their team number, etc.

Secondly, if you wanted to have a Rebel controlled area - say the start or end of the mission story wise, these characters can be given idle or non combat animations to detail up a cantina, city or Rebel Base. At any rate, the options are clearly labelled for the six main options. Backpacks can be toggled on or off for the relevant troops in case you want to give one of them a jet pack animation set. Random alien head simply duplicates the options in the earlier panel, it's in this panel for ease of use and to remind mod makers that works. You can also have aliens as Imperial units too! The main colour options are for the Rebel Pilot Jumpsuit as the colours on other options are pretty set. This also works with the various heads for civilian / mercenary / NPC pilots as the jumpsuit is fairly common in the Star Wars galaxy.

Panel 6: Droid Options:

Hoping to add more options later on, but for now it's pretty straight forward. Three types of droid - HK Assassin, Protocol and KX Series - with relevant colour selection options. A word on the KX series though - you will probably want to scale them up in the WAX convertor file, which may or may not look out of place if you also give them a weapon.

IMPORTANT - Trimming frames in Photoshop / Gimp:

If you skip this step, your character will be broken in game. Blender renders an image sequence with all frames the same dimensions. Which for rendering animations is what you would want and makes sense in general.

Dark Forces doesn't have fancy ray based hit detection for sprites, so transparent pixels in a sprite count as a hit from weapons, walls and doors. Solution is to trim the frames a bit.

Provided in the main download is a Photoshop action script. Run this on the rendered character frames in the Wax Convertor Template folder (ie, the right subfolder inside 'Render') and it will trim the excess pixels per frame.

DFCharCreator.atn

If you are using GIMP, there is an equivalent method. Naturally, it's a bit less straight forward.

https://kamilburda.github.io/batcher/docs/installation/ - Batcher, batch script for GIMP similar to Photoshop with recorded actions.

This is covered in the video tutorial at the top of the page. You will need to install Batcher, then run a batch to trim the pixels.

You will probably notice some black alignment pixels have been left in. Wax Convertor (in the next step) will convert anything true black (0,0,0 RGB) to be transparent in game so this is ok. They are there to give a little padding as certain armour options are a touch wider than others and would otherwise need to be realigned most times you made a character. Avoiding that is one of the main goals of this process.

After the batch trimming is complete in either Photoshop or Gimp (or your tool of choice to trim transparent pixels from top, left right), you can safely load the Wax Convertor file to continue with exporting in to a WAX file for use in the game.

Wax Convertor Template:

Wax Convertor is the program that will take the sequence of png images rendered out of Blender, give them placement coordinates and assign images to sequences, and sequences inside actions. This should already be set up and ready to go for you! However, some background information on how it all works in case you need to make minor adjustments.

The process is covered in the video tutorial at the top of the page. Firstly you will need select Create - Build WAX manually, which will load another UI for creating a WAX. Then, navigate to \Render\_TROOP_LH_Template to load for example, the left handed TROOP character you just rendered. Each template has different pixel offsets and in some cases, different frame ranges. Which is why having all these templates is important instead of just the one.

The following lengthy chart is only for reference of how the frames and actions are generally laid out. You shouldn't need to worry about changing them!

TROOP Replacement Template - Frame Ranges:

Sequence	Frames	Action		Sequence	Frames	Action
0	0-7	Walking Front		34	132-135	Dying v2
1	8-15	Walking Front Angle Left		35	136	Idle (single frame) Front
2	16-23	Walking Side Left		36	137	Idle (single frame) Front Angle Left
3	24-31	Walking Rear Angle Left		37	138	Idle (single frame) Side Left
4	32-39	Walking Rear		38	139	Idle (single frame) Rear Angle Left
5	40-47	Walking Rear Angle Right		39	140	Idle (single frame) Rear
6	48-55	Walking Side Right		40	141	Idle (single frame) Rear Angle Right
7	56-63	Walking Front Angle Right		41	142	Idle (single frame) Side Right
8	64-66	Ranged Attack Front		42	143	Idle (single frame) Front Angle Right
9	67-69	Ranged Attack Recoil Front		43	144-146	Melee Attack Front
10	70-71	Ranged Attack Front Angle Left		44	147-149	Melee Attack Recoil Front
11	72-75	Ranged Attack Recoil Front Angle Left		45	150-152	Melee Attack Front Angle Left
12	76-78	Ranged Attack Side Left		46	153-155	Melee Attack Recoil Front Angle Left
13	79-81	Ranged Attack Recoil Side Left		47	156-158	Melee Attack Side Left
14	82-84	Ranged Attack Rear Angle Left		48	159-161	Melee Attack Recoil Side Left
15	85-87	Ranged Attack Recoil Rear Angle Left		49	162-164	Melee Attack Rear Angle Left
16	88-90	Ranged Attack Rear		50	165-167	Melee Attack Recoil Rear Angle Left
17	91-93	Ranged Attack Recoil Rear		51	168-170	Melee Attack Rear
18	94-96	Ranged Attack Rear Angle Right		52	171-173	Melee Attack Recoil Rear
19	97-99	Ranged Attack Recoil Rear Angle Right		53	174-176	Melee Attack Rear Angle Right
20	100-102	Ranged Attack Side Right		54	177-179	Melee Attack Recoil Rear Angle Right
21	103-105	Ranged Attack Recoil Side Right		55	180-182	Melee Attack Side Right
22	106-108	Ranged Attack Front Angle Right		56	183-185	Melee Attack Recoil Side Right
23	109-111	Ranged Attack Recoil Front Angle Right		57	186-188	Melee Attack Front Angle Right
24	112-113	Pain Front		58	189-191	Melee Attack Recoil Front Angle Right
25	114-115	Pain Front Angle Left		59	192-203	Idle (animated) Front
26	116-117	Pain Side Left		60	204-215	Idle (animated) Front Angle Left
27	118-119	Pain Rear Angle Left		61	216-227	Idle (animated) Side Left
28	120-121	Pain Rear		62	228-239	Idle (animated) Rear Angle Left
29	122-123	Pain Rear Angle Right		63	240-251	Idle (animated) Rear
30	124-125	Pain Side Right		64	252-263	Idle (animated) Rear Angle Right
31	126-127	Pain Front Angle Right		65	264-275	Idle (animated) Side Right
32	128-130	Dying v1		66	276-287	Idle (animated) Front Angle Right
33	131	Dead (Corpse frame)

(Note: If making animations to be compatible with the original game, avoid re-using individual frames.)

Most of the frame ranges on the different ground based options are the same as the above, with the actions being in the same order also. The main reason for the sheer amount of frames compared to the base game is that the characters now work in eight different view directions fully and also have animated idles rather than static frames.

Once a project is loaded, click the Position frames button and give the character a quick once over. Some adjustments will be needed from time to time. Mostly if the character is taller like an Ithorian or Mon Calamari. The quick solution for this (don't save, unless saving as a copy!) is to use the % of height option and set to about 4% for all frames. Then check the Dead (Corpse) frame, which is usually frame 131 and tweak if needed.

Leave the width ones alone unless individual ones need tweaking, don't batch move them!

Next, load the palette you are using for your level if it is not the usual SECBASE.PAL, which you will need to do if you used any of the (EXTRA) colours like purple or teal in the provided X-GENERIC palette files. This is done in the top left with the Load PAL button.

All that should be left to do is select 'Compress cells' and directly below it, 'Create WAX!' There will be a dialogue box asking about PAL options, check 'Use full-bright colours (1-23) - by alpha value' for glowing elements (which are present in basically all WAX files. If you are not using the (EXTRA) colours and custom palette, check 'Only use common PAL colours'. Then click 'Proceed'.

Congratulations - you have created a custom character for Dark Forces!

Using in game with Custom Logics for TFE:

To go with all the custom artwork for new enemies and NPC characters - The Force Engine now supports custom logics to drive the characters actions. For the full write up, please see: https://df-21.net/wiki/?title=TFE_Custom_Logics

It can be a bit daunting if you are not used to scripting, so I have included a full set of examples in TROOPERS.zip You can place a copy in your ...TFE/Mods/ directory and load it as a custom test mission to test things out. Inside the zip file you will find ...logics/logics.json which can be edited with free text editing software like Notepad++ https://notepad-plus-plus.org/downloads/ or your tool of choice.

 Let's have a quick look at two examples from the full list.

	{
            "logicName": "TROOPER_FULL",
            "data": {
                "hitpoints": 20,
                "dropItem": "RIFLE",
                "projectile": "RIFLE_BOLT",
                "rangedAttackDelay": 1,
		"fireSpread": 6,
		"hasMeleeAttack": true,
		"hasRangedAttack": true,
		"meleeDamage": 15,
		"meleeRange": 14,
                "speed": 10
            }
        },
	{
            "logicName": "TROOPER_SHORT",
            "data": {

                "hitpoints": 20,
                "dropItem": "RIFLE",
                "projectile": "RIFLE_BOLT",
                "rangedAttackDelay": 1,
		"fireSpread": 6,
                "speed": 10
            }

The main difference is TROOPER_FULL has a melee attack and TROOPER_SHORT does not. So the melee details are left out. They could also be in there and set to false or 0 where applicable. Not every setting needs to be specified in a custom logic, but the more you add, the more you can dial in the behaviour of your character.

You can also use as many custom logics as you like in a level to add variety throughout the map.

When you are done, it is recommended to use something like https://jsonlint.com/ as a free service to verify your .json file, as a comma in the wrong spot and so on will break the process outright.

Adding a custom character to the rig:

So you might have noticed a Lando Calrissian model in the main download file, with a texture. I have made this model for the following tutorial, which shows you how to add a model and texture to the Blender file and create a .WAX from it!