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. Unit scream and movement sound effects are based on this. Gender & flying affect the sprites a little. Not turrets. Specifically: [53] & [54] (weapons in hands), [115] (gender) and [120] (other flags) affect the final screen image. If the unit is a large unit, this will also determine the appearance of the last three quarters of the unit. This does NOT affect: the flying ability of the unit, the soldier image in the inventory screen, or the special abilities for certain aliens.

     0: Male/female unarmored 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
    18: Not sure, but it made the sound of a tank? Don't use.
   255: Unused

1 / 01: Inventory paperdoll image. If 0 or 1, [115] (gender) and [116] (race) determine the picture.

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

2 / 02: Bitflags. NKF: Seems to be consistent with different character models.

     87654321
NKF: 00100100   36 Floater
     10000000  128 Personal armour
     10001100  140 Power suit/flying suits
     11101000  232 Reaper
 BB: 00010000   16 Hovertank/Plasma
     00111000   56 Psi unlocked soldier in flying suit
     00110000   48 Psi locked soldier in kevlar
     01010000   80 Aliens
     01010100   84 Cyberdisc
     
     (  1) 1: ?
     (  2) 2: ?
     (  4) 3: Common to Cyberdiscs
     (  8) 4: Common to flying suits
     ( 16) 5: Common to all units
     ( 32) 6: Common to X-COM troopers
     ( 64) 7: Common to all enemies
     (128) 8: ?

3 / 03: Bitflags:

     87654321
NKF: 00101110  46 Pers. armor
     10000101 133 Floater
     10111111 191 PS/FS
     11101100 236 Reaper
 BB: 00100100  36 Psi locked soldier in kevlar
     01010000  80 Hovertank/Plasma
     10000001 129 Cyberdisc
     10100101 165 Aliens
     10110101 181 Psi unlocked soldier in flying suit
      
     (  1) 1: ?
     (  2) 2: ?
     (  4) 3: Small units
     (  8) 4: ?
     ( 16) 5: Flying X-COM units
     ( 32) 6: Small units
     ( 64) 7: ?
     (128) 8: ?

4 / 04: Possible bitflags.

     87654321
NKF: 10010001 145 PS/FS
     10011011 155 Pers. armor
     10011011 155 Floater
     10011011 155 Reaper
 BB: 01100001  97 Hovertank/Plasma, Psi unlocked soldier in flying suit
     01100010  98 Psi locked soldier in kevlar, Cyberdisc, Aliens

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

6 / 06: Possible bitflags.

     87654321
NKF: 00000000   0 Reaper
     00010000  16 Pers. armor
     00100000  32 PS/FS
     01010000  80 Floater
 BB: 01000000  64 Psi unlocked soldier in flying suit
     01010000  80 Hovertank/Plasma
     11000100 196 Aliens
     11010100 212 Cyberdisc
     11101000 232 Psi locked soldier in kevlar
     
     (  1) 1: ?
     (  2) 2: ?
     (  4) 3: Enemies
     (  8) 4: ?
     ( 16) 5: Large units
     ( 32) 6: ?
     ( 64) 7: Always flagged?
     (128) 8: ?

7 / 07: NKF: resistance modifers?

     87654321
 BB: 00000000   0 Hovertank/Plasma
     00010000  16 Cyberdisc
     00010001  17 Psi unlocked flying suit troopers
     00101011  43 Sectoid
     00101101  45 Psi locked kevlar troopers
     
     (  1) 1: Small units
     (  2) 2: Small aliens
     (  4) 3: Psi locked kevlar troopers
     (  8) 4: ?
     ( 16) 5: ?
     ( 32) 6: ?
     ( 64) 7: ?
     (128) 8: ?

8 / 08: Same for all units? (171) (11000011)

9 / 09: Always 0?

10 / 0A: Unit facing. Does NOT control HWP turret direction; see [024].

  0: North     (up right)
  1: Northeast (right)
  2: East      (down right)
  3: Southeast (down)
  4: South     (down left)
  5: Southwest (left)
  6: West      (up left)
  7: Northwest (up)

11 / 0B: Always 0?

12 / 0C: Current TUs

13 / 0D: Current Health

14 / 0E: Current Stun level how much falloff of paralysis every turn? What determines it?

15 / 0F: Current Energy

16 / 10: Current Reactions NKF: affected by health percentage

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

"Base" means the original (total) value (as carried forward from geoscape) - Also see Note 1 re: Base soldier stat values.

23 / 17: Base Firing accuracy. Current value = this * unitref[013] / unitref[026] (percent health)

24 / 18: Base Throwing accuracy. Current value = this * unitref[013] / unitref[026] (percent health).

Note: Tanks (turreted units?) always have 0 throwing accuracy. They use this for turret facing, relative to unit facing. 0 means it's facing forwards. Additional values are clockwise increments; see [010].

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: Energy to recharge each turn. Equals recruit initial TUs/3 (SOLDIER.DAT byte 43, not total base TUs). See TUs. BombBloke: Is this affected by damage?

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).

NKF: If you set this value to that of a usable item, the item that is created in place of the unconscious or dead soldier can be used like the ordinary item. Elerium pods, for example, can be recovered for 50 elerium each after the battle. Weapons can be used as you normally use them, etc.

For unconscious 'units', the item will be treated as the unconscious body - it will retain the name of the unconscious unit when looked at via the inventory screen. Picking up and using the 'item' will work, but when the unit wakes up, the 'item' image in the soldier's hands is not cleared, even though the item no longer 'exists' in the soldier's hands. Using this 'item' will just crash the battlescape.

Actually, I do not even want to think about what would happen if you 'prime' a grenade/stunned body.

39 / 27: "Soldier value" a.k.a. victory points. You gain (or lose, as the case may be) score at the end of combat according to this value when the unit dies.

• For X-COM units: A soldier with 42 will be worth -42 points if killed. Note this doesn't seem to apply if the soldier is killed when unconscious. The soldier just vanishes.
• For aliens: A commander with 35 will give you +35 points if killed.
• This value is the same as SOLDIER.DAT bytes 15-16 (a Word) and equals:

   20 + Missions + Rank Bonus
   
   with Rank Bonus as follows: SGT +1, CPT +3, COL +6, CDR +10

Note that although this equation holds true, the value is not actually computed per se. Instead, 1 is added directly to it each mission, as is a rank-bonus delta if you advance (e.g. COL to CDR, delta +4). In other words, hacking the Missions or Rank fields does not affect this value.

40 / 28: Index into SOLDIER.DAT, so game knows what to update. 255 = does not belong to anyone (i.e., it's not a soldier). NKF: This byte is critical for player controlled units. If this doesn't refer to anything, the unit ceases to exist at the end of the game. If it points to a valid soldier entry in soldier.dat, the soldier.dat entry will be updated.

41 / 29: BombBloke: Something to do with large units. Changes during gameplay. Have seen values of 2, 3, 5, 6.

42 / 2A: Rank. Affects morale loss and interface icon (hull for tanks). Only X-COM displays rank icons.

   X-COM
     0: Rookie
     1: Squaddie
     2: Sergeant
     3: Captain
     4: Colonel
     5: Commander
   255: Dead/unused
   
   Aliens
     1: Commander
     2: Leader
     3: Engineer
     4: Medic
     5: Navigator
     6: Soldier
     7: Terrorist
   255: Dead/unused
   
   Hull shape for X-COM tanks:
     0: Treaded
     1: Hover

43 / 2B: 0 or 1 - ?

44 / 2C: Alien 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. See Energy#Usage.

46 / 2E: HWP turret image. Only used (and only appears) if unit type [00]=3 (X-COM tanks):

   0: Cannon
   1: Rocket
   2: Laser
   3: Plasma
   4: Blaster
   5,6: ? Blanks

Note: For non-tanks, this controls the inventory layout. Only 0 and 1 are valid. 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. Also see [113] and [117].

47 / 2F: Always 0?

48 / 30: Size or height?

  2: Sectoids
  3: X-COM troopers, Mutons, Celatids
  4: Hovertank/Plasma / Cyberdisc (Large flying units?)

49 / 31: Standing height

50 / 32: Kneeling height

51 / 33: BombBloke: Large unit stat of some sort...

NKF: X-COM and reapers have 0, but floaters and civilians 2? Why is that?

MikeTheRed: Celatids and plasma tanks have 6! Could it be distance above floor, or to ceiling? Percent of 'cubic tile area' (including height) unused (x10)??

52 / 34: 3 for soldiers and many aliens, 4 for plasma tank, reapers, and sectopods

53 / 35 and 54 / 36: Image index for item in left and right hand, respectively. 255 for none. Indexes into obdata.dat, not obpos.dat.

NKF: If there is no item in the unit's hands, but these bytes are set, the 'image' that represents the item will still be displayed in the battlescape. If these phantom items are clicked on, the game crashes. If the image is not the right type for the real item in hand, the ammo count doesn't get displayed. Otherwise, it'll work as normal.

55 / 37: Possible bitflags.

     87654321
 BB: 00000001  1 Kevlar
     00000001  1 Sectoid
     00000011  3 Flying suit
     00000100  4 Hovertank/Plasma
     00001100  6 Cyberdisc
     (  1) 1: Small unit
     (  2) 2: Small X-Com units with flying suits
     (  4) 3: Large unit
     (  8) 4: Large enemy unit
     ( 16) 5: ?
     ( 32) 6: ?
     ( 64) 7: ?
     (128) 8: ?

56 / 38: Melee Accuracy (SOLDIER.DAT bytes 50 (initial) & 60 (increase) added together)

57 / 39: Psi Strength

58 / 3A: Current Morale. Base morale is hardcoded to 100.

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

60 / 3C: BombBloke: Always 0? NKF: Possibly part of 61 and 62, or somesuch.

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. Test this one out for values.

63 / 3F: Number of Fatal Wounds to head

64 / 40: Number of fatal wounds to torso

65 / 41: Number of fatal wounds to right arm

66 / 42: Number of fatal wounds to left arm

67 / 43: Number of fatal wounds to right leg

68 / 44: Number of fatal wounds to left leg

69 / 45: Only flags for aliens... Looks like random values

70 / 46: Only flags for aliens... Looks like random values

71 / 47: NKF: Always 16 for XCom units, 1 for cyberdisc, 0 for others?

72 / 48: Always 0? May be paired with [71].

73 / 49: Intelligence. Rated from 2 - 8. Indicates for how many turns the alien will know the location of spotted soldiers. Hey - why do humans have zero intelligence? :(

74 / 4A: NKF: Could be the unit spotted icon identifier? Could point to visible enemy units?

MikeTheRed: XCOMs always have 0, but Mutons have values of 0-3 (usually 0 or 2, and often fluctuating) in a firing squad situation.

75 / 4B: Always 0?

76 / 4C: Mission count.

77 / 4D: Always 0 but probably high byte for [76] since Missions is a Word in SOLDIER.DAT

78-79 / 4E-4F: Two byte Word (low byte then high byte) for number of kills this unit has made for ALL missions, not just this one. (Unitref[079]*256 + Unitref[078] = Kills). Note: This is the only byte known to directly carry forward into the geoscape / Soldier.Dat!

80 / 50: Reactions experience counter, for number of reaction shots. It doesn't matter if they hit the target; reactions still count. See Note 2 re: Experience counters. (Also note: Aliens do not use experience counters.)

NKF: Where does death by fire (overexposure rather than incendiary shell impact) fit into the experience counters? It becomes a non-assigned kill, I guess, like death by wounds, or death by a grenade that hasn't got an owner?

81 / 51: Firing Accuracy experience counter, for number of hits on an enemy (lethal or not, grenades or bullets). Each Autoshot hit counts as 1, so you can get 3 hits from one Autoshot burst. Likewise, grenades and blaster bombs can hit multiple targets with one explosion. Also, if you miss the intended target but hit a different alien, it still counts.

82 / 52: Melee Accuracy experience counter, for number of times stun rod has been used (not stun bombs).

83 / 53: Throwing Accuracy experience counter, for number of times unit has thrown any object.

84 / 54: Psi Skill experience counter, for number of psi attacks performed. 1 is added if attempt was unsuccessful, 3 if it was successful. Note: if this value goes over 255, all psi experience is lost. That's 85 successful psis (255/3). So be careful of maration psi'ing (a minimum of 43 turns at 2 psis/turn, 29 turns at 3/turn).

85 / 55: Bravery experience counter, for number of times unit has panicked. (Mind control too?)

86-111 / 56-6F: Unit's Name. Standard string ended by null byte. The rest can hold garbage.

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.

BombBloke: This is the only way to access tank inventories.

• Tank/Cannon has a normal inventory and uses man_1m0.spk.
• Tank/Rocket Launcher has a different layout and uses man_1m0.spk.
• Tank/Laser Cannon uses man_oe.spk, which doesn't exist normally. Providing this file still crashes. MikeTheRed: BombBloke, I couldn't read that 'oe', it was some special character - ??
• Hovertank/Plasma simply crashes.
• Hovertank/Launcher simply crashes.

Also see [46] and [117].

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

115 / 73: Gender: 0 = male, 1 = female.

116 / 74: Hair/skin colour (for inventory; all other units = 0):

  0: Blond caucasian
  1: Brunette caucasian
  2: Asian
  3: Black

117 / 75: Turret weapon. Over-rides hand held weapon. Turret images are not centered; that would be impossible because they aren't all 'objects'. (Mix of notes by BB and NKF)

     0: HWP cannon (bigobs[40])
     1: HWP rocket (bigobs[42])
           Aim 115%, TUs 75%
           Snap 55%, TUs 45%
     2: HWP laser (bigobs[54])
           Aim  85%, TUs 75%
           Snap 50%, TUs 33%
     3: HWP plasma cannon (bigobs[43])
     4: HWP blaster (bigobs[43]) (looks like ordinary cannon?)
     5: Celatid plasma cannon (bigobs[38]) (plasma pistol clip; no autofire)
     6: Cyberdisc plasma cannon (bigobs[34]) (plasma pistol clip; has autofire)
     7: Sectopod plasma cannon (bigobs[34])
    22: Invalid - Incredibly powerful armour piercing shell. Overpowering.
   255: Unused

Note: This item will take precendence over any item carried in the hand slots. It can be installed on non-tanks, but then the unit won't be able to use any carried weapons or items. This weapon is NOT affected by the kneeling modifier, but it is affected by the current unit's accuracy stat. Also note, this byte does NOT determine the turret image for HWPs in the battlescape.

Also see [46] and [113].

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

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

120 / 78: Unit bit flags, mainly re: mobility. They do NOT affect the soldier in inventory screen: (Mix of notes by BB and NKF)

   (  1) 1: 1 = Dead.
   (  2) 2: 1 = Unit can fly.
   (  4) 3: 1 = Unit is flying. (Toggles leg sprites for power armour.)
   (  8) 4: ??? Seems to flag if the unit has been selected this turn.
   ( 16) 5: 1 = Unit has been disabled for selection.
                (Stops the unit tab button from selecting this soldier.)
   ( 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 the game, at least. If he is carrying nothing, bit 6 can flag (as though the unit was using it's right hand item). But maybe it's just the order of dropped items affecting this?

Note: 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.

What if a hovertank is half on the ground, half in the air? What about a treaded tank, or large alien unit? What about units in lifts?

121 / 79: Movement related? Large unit related? Possible bitfield. NKF: Why did I get 16 for a soldier at one time?

122 / 7A: Always 0?

123 / 7B: Always 0?

Notes

1) The original/base values for soldier stats (offsets 23-28, etc.) correspond to the initial+increase bytes from Soldier.Dat (bytes 43-62). Changes to these Unitref bytes are lost when the mission ends; instead, XCOM re-reads them from Soldier at that time. This makes sense because base soldier stats don't change during a mission per se (although they might increase when the mission ends); in this way, the programmers didn't have to bother with separately storing and/or adding initial+increase during combat. (It's also why you don't see the initial+increase in the soldier stat display during combat, that you can see back at base.) On a practical note, if you are testing soldier stat increases versus experience counters, change the experience counters in Unitref, but change the soldier stats in Soldier. (IOW, it doesn't matter what the soldier stats are in the combat mission.)

The Kill count (offset 78-79) is the only Unitref value I know of that is directly carried forward into the geoscape and Soldier.dat. However, some others do indirectly carry forward, for example: experience (offsets 80-85) causes stat and rank increases, and decreased health (offset 26 - offset 13) means hospital time. And, of course, death is permanent. Heh.

2) Experience counters (offsets 80-85) determine the likelihood of soldier stat increases at the end of the combat mission, according to the formula for Primary Stats shown here. The Panic/MC counter (offset 85) affects Bravery as shown here.

Also, if at least one of the experience counters (except Throws or Panics) has a count, your secondary stats will increase, as discussed here. All you need is at least a 1 in offsets 80-82 or 84; more than 1 and/or multiple counters has no additional effect.

3) BombBloke's additional "To be Done" notes - can we cross some of these off yet?

  Need to research:
  Unconcious units and their respective items
  Stun recovery rate, does it exist?
  Unit damage modifiers
  Hand to hand attacks
  Offset of weapon from unit image?
  Firing sprite offset?
  Inventory lockout?
  Kneel lockout?
  Aliens seen?
  What else? The more to look for, the easier it is...
  
  Know 90 values.
  Unknown values (34 in total):
  [002] [003] [004] [005] [006] [007] [008] [009] [011] [034] [036] [041]
  [043] [045] [047] [048] [051] [052] [055] [060] [069] [070] [071] [072]
  [074] [075] [076] [077] [112] [119] [120] [121] [122] [123]

For More Information

• SOLDIER.DAT
• Soldier Stats
• Experience
• Hex editing

Return to Saved Game Files

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 ;
} ;