DaMiT's .hfb Hacking Guide

You don't need to edit .hfb files by hand anymore, thanks to Bodydrive's editor

This page hasn't been updated since HFv20

Comments, recommendations, errata, speling missteaks, something I left out, certain passage too confusing, my HTML sucks? EMAIL ME! cecrops@sandwich.net


A token in italics means you replace that word with an appropriate value. A pipe character "|" delimits a set of values from which you choose one; If you see foo|bar|baz, you would use either foo, bar, or baz. An ellipsis ".." means that you use any value in a set; For instance, a..z would mean that you use any letter from a to z.

All information in this file is unofficial. If you want up-to-date, accurate Hell Fighter information go to the official website. In fact, there is such good data there that I link to it throughout this document. ;)

This file is intended to help you understand the technical details of creating a Hell Fighter battle file. Aside from the technicalities, a good HFB author will also take into account game balance, realism, replay value, and other considerations.

This document is hereby placed in the public domain.

What is an .hfb?

When you start Hell Fighter, it will allow you to run one of a set of pre-made battles. The battle scenarios are not a static part of the program itself, but are stored in seperate files with the extension .HFB in the Hell Fighter directory. When run, Hell Fighter searches in this directory for files with the .HFB extension and lists them for you to choose. This means that you can create your own battle scenarios, or modify the existing ones.

The files themselves are plain text. You do not need any sort of specialized software to create or edit these files, plain old Edit or Notepad will do.

What a sample Hell Fighter Battle(.hfb) file looks like:

# foo.hfb
# Generated by Hell Fighter v20.0
*ves +type wyvern +var 0 +name Bobs_Ship +des 65793 +AI 7 +pos -2790 4910 +dir 0 +side 1 +eta 0 -end
*mis +type destroy +units 33 34 0 +Mside 1 +Bside 2 +Mpts 5000 +Bpts 2500 -end

#s are comments

All lines in a .hfb beginning with a hash mark (#) are comments. Comments don't affect the gameplay at all; They are only there as information for a person reading the file.

The in-game HFB generator will insert lines similar to the two comments above when saving a file. The first comment is the name of the file, and the second is a note saying what version of the game made the file.

Besides comments, there are two kinds of lines in an .hfb: *ves(vessels) and *mis(missions), both of which begin with an asterisk and end with the string -end.

*ves (Vessels)

The line for each craft in an hfb begins with *ves. This tells the program that you are inputting information for a vessel. For the purpose of the game, fighters, capships, bases, and jumpgates all count as vessels. The first vessel in a HFB is the one piloted by the player.

+type shiptype

The +type attribute specifies what type of ship the vessel is. After +type, you input the name of the craft such as: +type shrike. Ship types must be in all lowercase. The following are valid ships, the links leading to the Dracova page which has more detailed information:

Ship Notes:

Stick to using ships that actually exist, or else Bad Things will happen. When writing your .hfbs you should take into account how common a ship is and its cost(unless you have a specific idea). It was once said that there are maybe twelve Spectres in the entire HFiverse, and a ragtag group of rebels is unlikely to get their hands on a Cruiser much less a Dreadnought. The Super Hell Fighter exists only to placate munchkins demanding a "best" fighter, and its use is strongly discouraged.

For information regarding common fleet formation and organization, look at Terran Alliance Space Navy Organization on the Dracova site and this email from PS, and study existing .hfbs.

+var 0...maxvar

The +var attribute defines variations in a craft's configuration. As an example: Starfighters are normally equipped with mass drivers (+var 0), but if you use the setting +var 1, the Starfighter will be equipped with bolt cannons. In the current version of Hell Fighter, your craft's ammunition display will be blank for anything other than the standard configuration, but the different vars do work. HFv19's mission editor would tell you what the variations were. The standard config is always +var 0.

Var notes:

+name shipname

+name is for giving the ship a name. This attribute you can leave off with no problems. Fighters are not normally named although there's nothing stopping you(I am quite fond of naming the player "Our_Hero"), but if a capship isn't given a +name then the game will automatically pull one out of the names.dat file. If you want a space in your ship's name, you have to use an underscore, and it will be rendered as a space in-game.

+des number

The Designation(+des) attribute is a decimal(that's base-10) representation of a 4-byte number. Counting from the least significant byte, the first byte is the ship number, the second byte is the squadron's letter designation, the third byte is the squadron's colour, and the fourth byte is unused.

    Unused     Colour     Letter    Number
  00000000   00000000   00000000  00000000   <- Least significant
         |          |          |         |
    2^24 -    65536 -      256 -       1 -

If you're lost already, you can use the +des calculator and skip to +AI

The basic formula for a designation is (2^16 * Colour)+(2^8 * Letter) + Number.

The Unused byte is unused, and it is recommended you don't mess with it, as the effects of having anything in it are undefined.

The Colours byte decides your squadron's colour. Valid colours are from 1 to 11, where (1..11)==(R,O,Y,G,B,I,V,gold,white,grey,black). The effects of Colours below 1 or over 11 is undefined.

The Letter byte contains a number between 1 and 26, determining your squad's letter. If you can read this, you know enough english to figure out the letters. As with colours, the effects of letters below 1 or over 26 is undefined.

The Number byte you would expect to be the number your ship gets in the game. However, it doesn't work out that way. What the game does is merely look at the squad colour and letter, and as it reads from the hfb it will incrementally reassign numbers to the ships from 1-255. This means that even if you wrote the +des so a ship would be RU-18, if it's the third ship in RU it will be assigned the designation RU-3. The numbers are assigned independently for each side; If there are 3 GoodGuys and 4 BadGuys, the Goods will be RU-1..3 and the Bads will be RU-1..4.

Some sample designations:

#Red Alpha 1
+des 65793 (65536 + 256 + 1)
In base two, this is:
1 00000001 00000001

#Red Beta 1
+des 66049 (That's Red Alpha 1 plus 256)

1 00000010 00000001

#Red Zeta 1
+des 72193

1 00011010 00000001
The middle number is 26, that's the number of letters in the English
alphabet. (Z is the last letter)

#Orange Alpha 1
+des 131329 (Red Alpha 1 plus 65536)

10 00000001 00000001
|         |        |-- 1 == Ship #1.
|         |
|         |-- 1 == Alpha
|-- 2 == Orange                 

Giving several ships the same des doesn't seem to cause any problems(yet), due to the game reordering the numbers. HFBs without the des attribute will still work -- In fact, some of the hfbs that come with HF are from older versions where the des attribute apparently did not exist. It works because the game doesn't yet care about the number.

The des does not seem to affect gameplay, although in future versions it is expected to affect computer AI regarding squadrons.

It is highly recommended that you keep to using valid designations. The parser will detect some invalid colour settings and set the ships to what appears to be the default squadron Orange Alpha. However, it is not able to always "fix" invalid letters or anything in the unused byte. Anything screwy or neat that you get by fooling around with this is unlikely to remain in later versions of the game.

Appropriate Colours:
Different colours typify different types of ships.

HF +des generator <- pointy-clicky calculator.

+AI 1...7

The +AI (in uppercase) attribute sets the skill of the artificial intelligence for computer-controlled craft, and the accuracy of automated turrets in both human and computer controlled craft. Acceptable values are from 1(Training Drone) to 7(Legendary Ace) with 4(Seasoned) being the game's default average, although many players prefer to use 5(Veteran) as an average value.

+pos x y

+pos sets the ship's position on the map. While most other attributes have one argument, +pos uses two. The first is the ship's X or horizontal position on the map. The number may be negative or not, negative numbers placing the ship farther to the left, positive placing the ship farther to the right.

The second number is the vertical(Y) position. A negative number is towards the top of the map, positive is towards the bottom.

              ^ -y
-x <----------+----------> +x
              v +y
Position notes:

+dir 0...384

Hell Fighter uses a circle that is 384 degrees around, due to the ease of dividing this number by multiples of two. +dir is the direction the ship is facing, expressed as a number of degrees in the 384-degree circle, counting clockwise.

Relative Angles: (Thanks to Greg/Phantom)

 240  288  366            256 | 320
    \  |  /            224    |    352
192--Center--0       192 ---Center--- 0
    /  |  \            160    |    32
 144   96   48            128 |  64

+side 1|2

+side denotes what side the ship is on. Side 1 is the Terran Alliance, which has green/red ships. Side 2 is the Stepping Stone Alliance, which has grey/blue ships. There is no side 0, and there are no other sides implemented yet.

The side that a jumpgate "belongs to" can have certain effects upon gameplay. Computer controlled ships seem to like to fire upon "enemy" jumpgates(AI bug, will be fixed), and a jumpgate's side might effect the AI of unarmed craft in future versions. Currently, unarmed ships will just head towards the first jumpgate in the HFB file.

+eta number

ETA is the Estimated Time of Arrival for ships jumping in. +eta 0 is used for ships that are already present at the time the battle begins. Each unit is one 12.8th of a second, so +eta 128 would be ten seconds into the battle.

Fighters will "latch" onto nearby carriers with the same ETA, bombers won't. ETA seems to be slightly effected by a ship's speed; Given bombers and a capship with the same ETA, the bombers tend to arrive a few seconds earlier. Also, player controlled ships land behind their position, as they don't jump at as fast a speed as computer controlled ships.

One odd note: The computer's AI is able to see and reacts to ships that have not jumped in yet. It is not uncommon to see a group of fighters circling around the area where a ship is programmed to jump in.

*mis (Missions)

Missions are special objectives for you(or the enemy) to complete in a battle, adding a bit of flavour to the game. You can have several missions in a single battle. Though version 20 does not display battle reports in-game, you can still see the results of the battle in victory.rep and the other .rep files scattered in the Hellfighter directory, that are created at the conclusion of each battle.

+type destroy|disengage

+type denotes the type of mission that you are adding to the battle. The mission type can be either destroy or disengage. The meaning of "destroy" is obvious, "disengage" means the ships effected by the mission(see +units) must reach a jump point and jump out for the mission to be successful.

+units firstunit secondunit ... lastunit 0

+units is a list of units that are effected by the mission. The list is a space delimited list of numbers that correspond to the ships in the hfb, the first ship in the hfb being number 1. In addition, this list must end with a 0, or the mission scoring will not be handled properly.

The +units tag is one of the last things you should code into your HFB, the reason being that you are likely to be jumbling around the order of craft in your file, and the numbers won't point to the right ships anymore.

+Mside side +Bside side

The +Mside and +Bside tags are used to determine which side is supposed to complete the mission, and which side is supposed to stop the first side from succeeding. I like to say that the Mside side has to Make the mission, and the Bside side has to Block the mission.

+Mpts amount +Bpts amount

Mpts and Bpts are the number of victory points that Mside and Bside get for completing a missions. Missions can be partially completed, in which case each side gets the percentage of their victory points equal to the percentage of targets for which the mission was a success.

For instance, in the above scenario,

*mis +type destroy +units 33 34 0 +Mside 1 +Bside 2 +Mpts 5000 +Bpts 2500 -end

Side 1 will get 2500(5000/2) points for just destroying ship 33 or 34, or 5000 points for destroying them both. Side 2, however, will only get 1250 points for saving each ship, or 2500 points for saving them both.

Closing Notes

Remember, there must an -end at the end of each *ves and *mis line.

There must be a space before the plus(+) for each element in the list, otherwise the attribute names may not be recognized and the values will not be read. For instance, if you say "+des 67890+pos 123 456", without a space between 67890 and +pos, the parser will not see +pos and the ship's position will be undefined.

On Jumpgates and Jumping: When a ship jumps, it is considered to have left the battle, travelling at faster than light speed to destinations unknown. You can't "get back" ships that have jumped out. Jumpgates cannot be destroyed.

Thanks go out to Skant and Jace for making such a great game, Patrick "Not the Bald Guy" Stewart for introducing me to it, HP for helping me clarify some passages, and all the newbies on the Hell Fighter Mailing List for giving me a reason to write this.