Introduction

This document describes in detail the Tacview flight recording public file format.

If you follow these guidelines properly, you will be able to export any flight recording you want from any flight simulator and even from real life! (e.g. from a GPS)

For compatibility reasons and because some languages like LUA do not natively support binary format, the file is in plain text format. This helps a lot when debugging the output produced. On the other hand, the file will be larger than it would have been if it was written in binary format. This is not a major issue, since Tacview text file format is rather compact and optimized.

A typical mission with hundreds of units is around 20 MB. Thanks to today's storage devices this is acceptable. However, after recording, the file size can be reduced by saving it in a compressed binary format under Tacview.

Obviously, a public binary format is planned for future versions in order to help real time recording through the network.

File Format

Tacview plain text low level format uses UTF-8 encoding, so it can contain any character from any language (Russian, European, Japanese...). To be valid, a flight recording must meet the following guidelines:

Low Level Structure

• Tacview flight recording file extension is .txt.acmi
• The file is written in true plain text UTF-8 format.
• The first 3 bytes are the UTF-8 BOM tag 0xEF 0xBB 0xBF.
• Lines are separated by a single line-feed character 0x0A.
• The file does not contain any other control character than the end-of-line one.
• There is no special final character at the end of the file.

Data Format

• The file content is case sensitive.
• Every record is as compact as possible.
• Hexadecimal numbers are not prefixed nor suffixed.
• Numbers (IDs or values) are not prefixed by leading zeros.
• IDs 0 and -1 (0xffffffff) are reserved and must not be used.
• Every data is expressed in the metric system.
• The property separator is the equals-sign 0x3D.
• The field separator is the comma 0x2C.
• The escape character is backslash 0x5C.
  Like in C programming language, it can be used to insert control characters (e.g. equals-sign, comma or line-feed) into a string.

Header

FileType=text/acmi/tacview
FileVersion=1.1
Source=Lock On: Flaming Cliffs 1.1
Recorder=Tacview 0.91
RecordingTime=2007-09-02T22:13:50Z
Author=Vyrtuoz

FileType = text/acmi/tacview (Mandatory)

Tacview flight recording plain text format identifier. It is always set to text/acmi/tacview.

FileVersion = 1.1 (Mandatory)

Flight recording plain text format version. The current version is 1.1.

Source = <Source Flight Simulator/Aircraft> (Mandatory)

This is the source flight simulator full name and version number if applicable. If the recording is from real life, then this should be the source aircraft name.

Recorder = <Software/Hardware Recorder> (Mandatory)

Hardware or software flight recorder full name including its version number if applicable.
ATTENTION: DO NOT put "Tacview" in this field, since your software/hardware is not Tacview!

RecordingTime = <Recording Start Time> (Mandatory)

Recording start time expressed in Coordinated Universal Time (UTC). The format is: YYYY-MM-DDThh:mm:ssZ. This is the effective real-life recording time, which is not necessarily the mission start time.

• YYYY: Full numeric representation of a year, 4 digits
• MM: Numeric representation of a month, with leading zeros
• DD: Day of the month, 2 digits with leading zeros
• T: date|time separator
• hh: 24-hour format of an hour with leading zeros
• mm: Minutes with leading zeros
• ss: Seconds with leading zeros
• Z: Means Zulu time which means UTC

Author= <Pilot/Operator Name> (Optional)

Pilot or operator name. It can be in any format, including callsign, nickname and rank if applicable.

Title=South of the Border
Category=Fighter Sweep
MissionTime=2002-05-30T09:30:10Z
LatitudeOffset=42
LongitudeOffset=32
Coalition=Allies,Green
Coalition=Enemies,Red
Coalition=Neutral,Blue
ProvidedEvents=Takeoff,Landing,LeftArea,Destroyed

Title = <Mission Name> (Optional)

Flight/Mission name. It can be of any form and length.

Category = <Mission Category> (Optional)

Flight/Mission type. It can be of any form and length.

MissionTime = <Mission Start Time> (Mandatory)

Mission start time expressed in Coordinated Universal Time (UTC). The format is: YYYY-MM-DDThh:mm:ssZ. This is the true mission start time, which is not necessarily the recording start time. See RecordingDate for the format.

LatitudeOffset = <North/South Offset> (Optional)
LongitudeOffset = <East/West Offset> (Optional)

These two fields are used to reduce the text file size by removing the leading numbers of each coordinate when possible. Usually, they represent the bottom/left corner of the flight area. If they are omitted, Tacview assumes that their values are 0 (which mathematically means no offset).

Here's an example: If the mission take place in the Falkland Islands, between 50°S to 52°S and 61°W to 57°W, then we can use the following settings to optimize the file size: LatitudeOffset=-52 and LongitudeOffset=-61. So for a unit at 51.3°S,60.5°W which is mathematically -51.3,-60.5 (11 text characters), with the offset optimization, the position can be expressed as: .7,.5 (5 text characters).

Obviously the gain is not so important in reality. But in average, the offset optimization helps to reduce the file size by 6%.

Coalition = <Name> , <Color> (Mandatory)

This statement is used to declare each coalition IDs, name and color. The declaration order matters because the coalition ID is implicit: The first declared coalition is the coalition #0, the next coalition is the #1, ...

• Name: Usually coalitions are named: Allies, Enemies and Neutral. But any other coalition name can be used.
• Color: Main color used in the 3D view and reports to represent the coalition. It can be one of the following: Red, Green, Blue or Purple.

ProvidedEvents = { Takeoff , Landing , LeftArea , Destroyed , Removed } (Optional)

This statement specifies any event that will be explicitly provided in this flight recording. Tacview will not try to guess any event of these types. This is useful to avoid any conflict between events auto-detected and the events which are directly provided by the simulator. See the event statement below for more details.

Events can be one of the following:

• Takeoff
• Landing
• LeftArea
• Destroyed
• Removed

MainAircraftID=18c3
Briefing=Luptatum eros ad eu\, vulputate ut et nulla ea tation nulla\, ad minim vero consequat et delenit [...]
Debriefing=At facilisis duis eu veniam commodo aliquip ad lobortis vel augue hendrerit ut\, consectetuer nib [...]
Comments=Tation tation enim erat luptatum\, zzril adipiscing in exerci delenit nisl duis accumsan tincidunt.

MainAircraftID = <Aircraft ID> (Optional)

This ID is expressed as a 32bits hexadecimal number. In fact, it can designate any unit in the mission: the local aircraft, the aircraft which records the mission, the aircraft which offers the most reliable data or simply what is considered as the main unit (e.g. an AWACS)...

Briefing = <FreeText> (Optional)
Debriefing = <FreeText> (Optional)
Comments = <FreeText> (Optional)

This is the usual information provided with any flight/mission. They are free text of any length. Thanks to the escape character backslash 0x5C, it is also possible to include line-feed characters 0x0A to separate each paragraph.

Frames

The file header is followed by frames. Frames are the core of any Tacview flight recording. Each of them describes units' status update and events at a specific time. Tacview automatically interpolates between frames to generate a smooth replay.

• Each frame contains update information about units and/or events.
• Data that have not changed since last update are omitted.
• Unknown information are specified by a question mark 0x3F. This data will be automatically estimated by Tacview. (This applies to values and events)
• Each unit can be updated on distinct basis as needed.

Thanks to Tacview's ability to estimate data and events, it is possible to modulate units update frequency depending on the needs. This helps a lot to optimize the flight recording size. It is also possible to let Tacview guess information and events when the data are not available for recording.

#1441.68
+102,,10,0,ru,Su-27,KO-05 RomaniaK,Avenger,4
102,2.180759,7.485877,2001.71,0,-4.2,310.5
!41,d01,?
#1441.78
1800,3.072809,1.585071,51.97,,0.9,45.2
1c00,2.990581,1.009730,,,,50.6
100,1.768936,2.623015,,,,
#1441.87
1c00,2.990676,1.009893,9999.95,,,
100,1.769046,2.622876,,,,
#1445.11
!10,d01

# <Time Offset> (Mandatory)

Time offset since the mission beginning (in seconds). This is not mandatory to start at 0 second. For example, if a local player joins an existing network session, his flight recording is not going to start at the first second.

• The frame time cannot be negative.
• It must be greater or equal to the previous frame time.
• It is useless and a waste of storage space to express times with a resolution greater than one 1/100th of a second.
• Usually 10Hz update frequency gives good results. Update frequencies lesser than 1Hz should be avoided.

+ <ObjectID> , [ParentObjectID] , <ObjectType> , [CoalitionID] , [CountryCode] , <ObjectName> , [PilotName] , [GroupName] , [RankOrder] (When applicable)

Declare a new unit/object. This statement must precede any other statement related to the specified unit.

<ObjectID> (Mandatory)

• This ID is expressed as a 32bits hexadecimal number.
• Objects IDs must remain consistent over a network in order to enable flight recordings merge/comparison.
• This is not mandatory, but objects can keep the same IDs when they respawn. Usually, this applies (but is not restricted) to players who respawn in a multiplayer session.

[ParentObjectID] (Optional)

• Parent IDs are usually used to associate a weapon (e.g. AIM-120C) to its parent (e.g. F-15C).
• If this does not apply, this field must be empty.
• If you can't know the parent of a weapon, put a question mark 0x3F. Tacview will guess who is the parent depending on ranges and objects types.

<ObjectType> (Mandatory)
The object type is expressed as an 8bits hexadecimal number. It must be one of the following:

• 10: Aeroplanes (including fixed-wing drones)
• 18: Helicopters (including rotary-wing drones)
• 20: Anti-aircraft warfare (usually: SAM and AAA)
• 24: Armored fighting vehicle
• 28: Light/Unarmed vehicles
• 30: Armed Watercraft (including submarines)
• 34: Aircraft carrier (including Helicopter carrier)
• 38: Light/Unarmed Watercraft
• 40: Missile (guided missiles)
• 44: Rocket (unguided missiles)
• 46: Shrapnel (e.g. cluster-bomb fragments, exploded plane parts, ...)
• 48: Shell
• 49: Bullet
• 4c: Bomb (guided and unguided)
• 50: Chaff (obviously a chaff cluster)
• 54: Flare
• 80: Aerodrome (specific to this mission). This is a special case, see below.
• 88: Building (specific to this mission). This is a special case, see below.

[CoalitionID] (Optional)

• The coalition ID is an integer.
• This is the index of one of the coalitions declared in the file header (0 to n-1).
• The coalition ID can be omitted (empty field) when the object has a valid parent. In that case, it will be automatically inherited from its parent.

[CountryCode] (Optional)

• This is the ISO 3166-1 alpha-2 object country code.
• It must be expressed in lower case.
• Like coalition ID, the country code can be omitted (empty field) when the object has a valid parent. In that case, it will be automatically inherited from its parent.

<ObjectName> (Mandatory) (Optional for the following object types: 0x48, 0x49, 0x50, 0x54, 0x88)
The object name must be (as much as possible) composed like this: [Complete but short official weapon/aircraft designation] [Space Separator] [NATO code]. You can find an excellent documentation of military designation on Designation-Systems.Net. This rule also applies as much as possible to civilian aircrafts and other objects.

Here a sample:

• F-15E Eagle
• F/A-18 Hornet
• AIM-9M Sidewinder
• MiG-29K Fulcrum-D
• R-73 Archer
• FIM-92 Stinger
• C172R Skyhawk
• M998 Avenger
• SSN Akula
• Eurofighter Typhoon
• Mirage 2000-5
• R91 Charles de Gaulle

[PilotName] (Optional)
The pilot name can be in any format, including callsign, nickname and rank if applicable. If the aircraft is piloted by a crew, each crew member names are separated by a slash 0x2f and ordered by rank (starting with the higher one).

[GroupName] (Optional)

• If the object is a member of a group/team then this field contains the group name.
• It can be any string (e.g. Sierra-Tango) including (but not restricted to) a numerical group ID (e.g. 201).
• It is advisable (but not a mandatory) to keep it simple and short.
• If the object is not a member of a group, this field remains empty.
• If the object has a parent and this field is empty then the group ID will be automatically inherited.

[RankOrder] (Optional)

• This field is filled only if the object is a member of a group. (i.e. When GroupName is explicitly or implicitly valid)
• This is an integer code (from 0 to n-1) which specifies the object rank / order in the group.
• Each object in a group has a distinct rank order.

+ <ObjectID> , , 80 , [CoalitionID] , [CountryCode] , <AerodromeName> , <Length> , <Width> (When applicable)

This statement is used to declare any aerodrome specific to the mission. It can be anything from a heliport, airport to a water aerodrome. Even if the aerodrome name will be visible in Tacview, no shape will be displayed. To model a specific aerodrome shape, it is possible to declare some objects of type 0x88 which can be destructible or to declare static objects outside of the flight recording.

Obviously, this statement is followed by an update statement which defines aerodrome position and orientation. See below for more details about object position updates.

<AerodromeName> (Mandatory)
Aerodrome name which will be displayed in Tacview 3D view and logs.

<Length> (Mandatory)
<Width> (Mandatory)
These are the average length and width of the aerodrome. For airports, these are usually the main runway dimensions.

+ <ObjectID> , , 88 , [CoalitionID] , [CountryCode] , [BuildingName] , <Length> , <Width> , <Height> (When applicable)

This statement declares any building specific to the mission (civilian or military). This building will be destructible. If CoalitionID and CountryCode are omitted, then the building will be displayed in neutral grey colors (useful for civilian buildings). Obviously, this statement is followed by an update statement which defines the building position and orientation. See below for more details about objects position update.

To efficiently declare static (not destroyable) buildings into Tacview world, it is advisable to use the dedicated functionality.

[BuildingName] (Optional)
This is the building name which will be displayed in Tacview 3D view and logs. In order to avoid display cluttering, the name should be omitted if the building has no real importance in the mission.

<Length> (Mandatory)
<Width> (Mandatory)
<Height> (Mandatory)
These are the average length, width and height of the building.

<ObjectID> , [Latitude] , [Longitude] , [Altitude] , [Roll] , [Pitch] , [Yaw] (When applicable)

This is the most common statement found in a flight recording. It declares/updates an object's position and rotation. When a component has not changed since the last time, it is simply omitted.

<ObjectID> (Mandatory)
This is the usual ID expressed as a 32bits hexadecimal number.

[Latitude] (Optional)
[Longitude] (Optional)

• Geographical coordinates of the specified object in degrees.
• Latitude = y (-90=South Pole, 0=Equator, +90=North pole)
• Longitude = x (-180=West, 0=Greenwich, +180=East)
• Previously defined LatitudeOffset and LongitudeOffset must be applied to switch between effective and compacted coordinates.
• Any of these fields can be left blank if their value didn't change since last update.
• For best results, it is suggested to use a resolution of 6 digits (or more) after the comma.

[Altitude] (Optional)

• This is the current altitude expressed in meters, relative to the sea level.
• It is suggested to use a resolution of one 1/100th of a meter.
• Any of these fields can be left blank if their value didn't change since last update.

[Roll] (Optional)
[Pitch] (Optional)
[Yaw] (Optional)

• All of these components are expressed in degrees.
• Usually, a resolution of 1/10th of degrees gives good results.
• Any of these components can be replaced by a question mark 0x3F. In that case, Tacview will interpolate/guess the component depending on object movement and other components.
• Roll angle is negative when rolling to the left. Range is -180° to +180°.
• Pitch angle is negative when diving. Range is -90° to +90°.
• Yaw angle is the bearing relative to the true geographical North Pole. Range is 0° to 360°.
• Object local orientation is calculated by applying these three components in the following order: Roll, then Pitch, then Yaw.
• Any of these fields can be left blank if their value didn't change since last update.

! <EventID> , {Parameters} (When applicable)

This statement describes a specific event which happens at the current frame time. To avoid conflict with Tacview's auto-detection of events, any type of event declared like the following should be specified in the ProvidedEvents statement.

! 20 , <ObjectID> (Avoid this event as much as possible)
REMOVED: The specified object has been removed from the world for an unknown reason. It can be because it has simply left the area or because it was destroyed. Tacview will try to guess the reason depending on the circumstances. This event must be avoided because of its imprecision. More precise events like LEFT_AREA (28) or DESTROYED (2C) must be used instead.

! 28 , <ObjectID>
LEFT_AREA: This statement is used to remove an object from the world because it has left the area for any reason (e.g. a plane has entered a hangar and was dismissed).

! 2C , <ObjectID> , [HitObject]
DESTROYED: This event is used to remove an object from the world because of its destruction (e.g. a missile has exploded). The optional field <HitObject> can be used to specify an object which has been hit by the destruction.

• If no object has been affected by the destruction of the specified object, <HitObject> field can be omitted.
• When the objects affected by the destruction are unknown, this field contains a question mark 0x3F. In that case, Tacview will evaluate affected objects depending on types and ranges.
• This event must be repeated for each hit object (e.g. when a bomb has destroyed several units).

! 40 , <ObjectID> , [AerodromeID]
TAKEOFF: The specified ObjectID has taken off from the given AerodromeID. Usually AerodromeID is replaced by a question mark 0x3F to let Tacview guess the aerodrome. It can also be left blank if the aircraft has taken off from nowhere...

! 41 , <ObjectID> , [AerodromeID]
LANDED: The specified ObjectID has landed at the given AerodromeID. Usually AerodromeID is replaced by a question mark 0x3F to let Tacview guess the aerodrome. It can also be let empty when the aircraft has landed in the middle of nowhere...

Summary of Key Points

• Flight recordings must be written in UTF-8 text format. Including the heading BOM tag 0xEF 0xBB 0xBF.
• Use a single line-feed character 0x0A to separate lines in order to reduce the file size.
• Use a question mark 0x3F to specify any unknown information and let Tacview guess it.
• Don't forget that some fields can be left blank if their value didn't change since last update to reduce flight recording size (especially useful for position/rotation fields).