UNITREF.DAT

UNITREF.DAT has a row width of 124 bytes. Each byte is unsigned. Some bytes represent bitfields.

Values are presented according to byte count (0 to 123) followed by the equivalent hex offset (00 to 7B) in bold, followed by the normal (non-hacked) range of values in italics. Most fields can be hacked up to FF, but sometimes it can make for weirdness!

Structure

0 / 00 (): Type of unit:

 0: Male/female X-Com soldier.
 1: Male/female personal armor soldier.
 2: Power/flying suit soldier.
 3: Tank.
 4: Sectoid.
 5: Snakeman.
 6: Etheral.
 7: Muton.
 8: Floater.
 9: Celatid.
10: Silacoid.
11: Chryssalid.
12: Reaper.
13: Sectopod.
14: Cyberdisc.
15: Male civilian.
16: Female civilian.
17: Zombie.
255: Unused.

Values unitref[53]/[54] (weapons in hands), unitref[115] (gender) and unitref[120] (other flags) affect the final screen image.

1 / 01 (): Inventory paperdoll image:

0: No armor.
1: Personal armour.
2: Power suit.
3: Flying suit.

If 0 or 1, unitref[115] and unitref[116] are used to determine picture.

2 / 02 (): Possible bitflags.

3 / 03 (): Possible bitflags.

4 / 04 (): Possible bitflags.

5 / 05 (): Flags 1 for units in play, 0 otherwise. Possible bitflags.

6 / 06 (): Possible bitflags.

7 / 07 (): Possible bitflags.

8 / 08 (): Observed as same for all units. (171) (11000011)

9 / 09 (): Seems to always be 0.

10 / 0A (): Unit facing:

0: North      (up right).
1: North east (right).
2: East       (down right).
3: South east (down).
4: South      (down left).
5: South west (left).
6: West       (up left).
7: North west (up).

11 / 0B (): All zeros?

12 / 0C (): Current TUs.

13 / 0D (): Current Health.

14 / 0E (): Stun level.

15 / 0F (): Current Energy.

16 / 10 (): Current Reactions.

17 / 11 (): Strength.

18 / 12 (): Current Front Armour.

19 / 13 (): Current Left Armour.

20 / 14 (): Current Right Armour.

21 / 15 (): Current Rear Armour.

22 / 16 (): Current Under Armour.

23 / 17 (): Firing accuracy. This is the original value. Current value is equal to this * unitref[013] / unitref[026].

24 / 18 (): Throwing accuracy. This is the original value. Current value is equal to this * unitref[013] / unitref[026]. Tanks (turreted units?) always have 0 throwing accuracy. They use this for turret facing, relative to unit facing. See [010] for values.

25 / 19 (): Base TUs.

26 / 1A (): Base Health.

27 / 1B (): Base Energy.

28 / 1C (): Base Reactions.

29 / 1D (): Base Front Armour.

30 / 1E (): Base Left Armour.

31 / 1F (): Base Right Armour.

32 / 20 (): Base Rear Armour.

33 / 21 (): Base Under Armour.

34 / 22 (): Always 0?

35 / 23 (): Amount of energy to recharge per turn. Will be greater for veteran troopers...

36 / 24 (): Always 0?

37 / 25 (): Psi skill. Psi stats not displayed/usable until this is greater then 0.

38 / 26 (): Item to create when unit is unconcious/dead. (Index into obdata.dat).

39 / 27 (): Value of unit (Victory Points). You gain (or lose, as the case may be) score according to this value when the unit dies.

40 / 28 (): Index in soldier.dat.

41 / 29 (): Something to do with large units. Changes during gameplay.

42 / 2A (): Rank:

For X-Com:
0: Rookie 
1: Squaddie 
2: Sergeant 
3: Captain 
4: Colonel 
5: Commander 
255: Dead/unused.

For Aliens:
1 - Commander
2 - Leader 
3 - Engineer
4 - Medic
5 - Navigator
6 - Soldier
7 - Terrorist
255: Dead/unused.

(?)For X-Com tanks:
0 - Treaded
1 - Hover

43 / 2B (): 0's or 1's.

44 / 2C (): Aggression. The higher it is, the less likely an alien will take cover. Maximum of 2.

45 / 2D (): Used to calculate energy used when walking: TUs used / 2^value.

46 / 2E (): HWP turret image. Only used by unit type 3 (X-Com tanks):

0 = Cannon.
1 = Rocket.
2 = Laser.
3 = Plasma.
4 = Blaster.

Note: For non-tanks, this controls the inventory layout. 
Valid values are 0 and 1 only. 
0 is the standard layout seen on all soldiers.
1 is an alternate layout that may have been intended for custom tank equipment.
Larger values only crash the game due to missing files. 

47 / 2F (): Always 0?

48 / 30 ():

49 / 31 (): Standing height.

50 / 32 (): Kneeling height.

51 / 33 (): Large unit stat of some sort...

52 / 34 ():

53 / 35 (): Item in left hand. 255 for none. Indexes into obdata.dat, not obpos.dat.

54 / 36 (): Item in right hand. 255 for none. Indexes into obdata.dat, not obpos.dat.

55 / 37 (): Possible bitflags.

56 / 38 (): Melee Accuracy.

57 / 39 (): Psi Strength.

58 / 3A (): Morale.

59 / 3B (): Bravery = 110 - (value * 10)

60 / 3C (): Always 0?

61 / 3D (): Unitref[062] will increment by this amount whenever the unit moves.

62 / 3E (): Visibility via motion scanner. The bigger it is, the bigger the blip.

63 / 3F (): Number of fatal head wounds.

64 / 40 (): Number of fatal torso wounds.

65 / 41 (): Number of fatal right arm wounds.

66 / 42 (): Number of fatal left arm wounds.

67 / 43 (): Number of fatal right leg wounds.

68 / 44 (): Number of fatal left leg wounds.

69 / 45 (): Only flags for aliens... (Random values)

70 / 46 (): Only flags for aliens... (Random values)

71 / 47 (): Possible bitflags.

72 / 48 (): Always 0?

73 / 49 (): Intelligence. Rated from 2 - 8. Indicates for how many turns the alien will know the location of spotted soldiers.

74 / 4A (): Always 0?

75 / 4B (): Always 0?

76 / 4C (): Mission count.

77 / 4D (): Always 0?

78 / 4E (): This plus 256 times unitref[079] equals number of kills unit has made during ALL missions.

79 / 4F (): This times 256 plus unitref[078] equals number of kills unit has made during ALL missions.

80 / 50 (): Number of reaction shots this unit has made during the current mission. It doesn't matter if they hit the target; reactions still count. Used for Reaction increase at end of mission.

81 / 51 (): Number of hits this unit has made on an enemy (lethal or not, grenades or bullets) this mission. (It doesn't matter if they were killed or not.) Each Autoshot hit counts as 1, so you can get 3 hits from one Autoshot burst. Also, if you miss the intended target but hit a different alien, it still counts. Used for Firing Accuracy increase at end of mission.

82 / 52 (): Number of times stun rod has been used (as opposed to stun bombs) during this mission. Used for melee / close combat accuracy increase at end of mission.

83 / 53 (): Number of times unit has thrown any object during the mission. Used for Throwing Accuracy increase at end of mission.

84 / 54 (): Number of psi attacks performed during the mission. 1 is added if mind control attempt was unsuccessful, 3 if it was successful. So psi rookies get some experience towards skill increase, but not as much as veterans. Also note: if this value goes over 255, it starts again at 0 (all psi experience is lost). That's 85 successful psis (255/3). So be careful of long, intensive psi'ing (a minimum of 43 combat turns if doing 2 psis per turn, or 29 if doing 3 per turn).

85 / 55 (): Number of times unit has panicked during the mission. Used for Bravery increase at end of mission.

86-111 / 56-6F (A-Z): Unit's name.

112 / 70 (): Flags 1 sometimes for aliens.

113 / 71 (): If 1, then you can't use the inventory button. Aliens don't use this, but the button disables anyway.

114 / 72 (): If not 0, then unit is on fire, and will (presumably) burn for this amount of turns.

115 / 73 (): Gender:

0 = Unit is male
1 = unit is female.

116 / 74 (): Hair/skin colour (for inventory): 0: Blond caucasian. 1: Brunette caucasian. 2: Asian. 3: Black.

117 / 75 (): Turret weapon. Over-rides hand held weapon:

0: HWP cannon. (bigobs[40])
1: HWP rocket. (bigobs[42])
2: HWP laser. (bigobs[54])
3: HWP plasma cannon. (bigobs[43])
4: HWP blaster. (bigobs[43])
5: Celatid plasma cannon (bigobs[38]).
6: Cyberdisc plasma cannon (bigobs[34]).
7: Sectopod plasma cannon (bigobs[34]).
255: Unused.

Turret images are not centered.

118 / 76 (): Ammo for turret weapon (unitref[117]).

119 / 77 (): Movement related? Large unit related? Possible bitfield.

120 / 78 (): Some bit flags. Bits (from left to right, 87654321):

(  1) 1: 1 = Dead.
(  2) 2: 1 = Unit can fly.
(  4) 3: 1 = Unit is flying.
(  8) 4: ??? Seems to flag if the unit has been selected this turn.
( 16) 5: 1 = Unit has been disabled for selection.
( 32) 6: 0 = Unit has left hand object selected, 1 = right hand object selected.
( 64) 7: 1 = Unit is kneeling.
(128) 8: 1 = Unit is wearing power/flying suit. (Can't be stunned by smoke flag? Seems to work for fire, too.)

If a unit is carrying something in either hand, it is impossible to get him to appear as if he is carrying nothing - in game, at least.

If he is carrying nothing, bit 6 can flag (as though the unit was using it's right hand item). But that might just be the order of dropped items affecting that?

A unit is only considered as flying if it is not on the ground. For example, a hover tank is not always considered as flying.

121 / 79 (): Movement related? Large unit related? Possible bitfield.

122 / 7A (): Always 0?

123 / 7B (): Always 0?

Notes

Add note here...

For More Information

Add more info here...

Addendum: Hex Workshop Structure Library

The following can be used to make an XCOMUFO.hsl file that will work with Hex Workshop (v4.23) available from www.BPSoft.com. This allows one to overlay a structure while viewing/editing UNITREF.DAT and work in a more organized fashion.

Tip: Set the data view window to 62 bytes wide, and each UNITREF record will take exactly two display lines. (It won't let you set it to higher than 64, unfortunately.)

#include "standard-types.hsl"

// UNITREF.DAT
struct UNITREF_DAT 
{
  UBYTE Unit_Type ;
  UBYTE Paper_Doll ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Facing ;
  UBYTE Unknown ;
  UBYTE TUs_Current ;
  UBYTE HPs_Current ;
  UBYTE Stun ;
  UBYTE EUs_Current ;
  UBYTE React_Current ;
  UBYTE Strength ;
  UBYTE F_Armor_Current ;
  UBYTE L_Armor_Current ;
  UBYTE R_Armor_Current ;
  UBYTE B_Armor_Current ;
  UBYTE U_Armor_Current ;
  UBYTE Firing_Acc ;
  UBYTE Throw_Acc ;
  UBYTE TUs_Max ;
  UBYTE HPs_Max ;
  UBYTE EUs_Max ;
  UBYTE React_Max ;
  UBYTE F_Armor_Max ;
  UBYTE L_Armor_Max ;
  UBYTE R_Armor_Max ;
  UBYTE B_Armor_Max ;
  UBYTE U_Armor_Max ;
  UBYTE Unknown ;
  UBYTE EU_Recharge ;
  UBYTE Unknown ;
  UBYTE Psi_Skill ;
  UBYTE obdata_index ;
  UBYTE VPs ;
  UBYTE soldier_index ;
  UBYTE Unknown ;
  UBYTE Rank ;
  UBYTE Unknown ;
  UBYTE Aggression ;
  UBYTE EU_Usage ;
  UBYTE HWP_Turret ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Stand_Height ;
  UBYTE Crouch_Height ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE L_Hand_Item ;
  UBYTE R_Hand_Item ;
  UBYTE Unknown ;
  UBYTE Close_Acc ;
  UBYTE Psi_Strength ;
  UBYTE Morale ;
  UBYTE Bravery ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Scanner_Blip ;
  UBYTE Head_Fatal ;
  UBYTE Torso_Fatal ;
  UBYTE R_Arm_Fatal ;
  UBYTE L_Arm_Fatal ;
  UBYTE R_Leg_Fatal ;
  UBYTE L_Leg_Fatal ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Intelligence ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Mission_Count ;
  UBYTE Unknown ;
  USHORT Kills ;
  UBYTE React_Count ;
  UBYTE Shot_Count ;
  UBYTE Rod_Count ;
  UBYTE Throw_Count ;
  UBYTE Psi_Count ;
  UBYTE Panic_Count ;
  CHAR Name[26] ;
  UBYTE Unknown ;
  UBYTE Inventory_Access ;
  UBYTE On_Fire ;
  UBYTE Gender ;
  UBYTE Race ;
  UBYTE Turret_Weapon ;
  UBYTE Turret_Ammo ;
  UBYTE Unknown ;
  UBYTE Bitflags ;
  UBYTE Unknown ;
  UBYTE Unknown ;
  UBYTE Unknown ;
} ;