Telemetry Objects

Telemetry object functions let add-ons discover, identify, and filter the objects present in telemetry.

Objects are the things Tacview knows about: aircraft, vehicles, weapons, reference points, bullseyes, effects, and many other entities. Some objects move over time. Some exist only briefly. Others are atemporal and may simply provide context for the telemetry.

Use this section when your add-on needs to answer practical questions such as:

• Which objects should I process right now?

• What kind of object is this?

• What name should I display to the user?

• Which color should I use for this object?

For object values that depend on time, such as active time, position, orientation, speed, airspeed, Mach number, or pressure altitude, see Object Data.

Active objects

A telemetry file can contain a large number of objects. Some may exist only briefly, such as projectiles or effects. Others may not exist yet at the current playback time, or may already be gone.

When your add-on only needs to process what matters now, start with active units:

• GetActiveUnitCount()

• GetActiveUnitHandle()

This gives you a smaller and more useful set of non-weapon objects active at the current playback time.

Object types and tags

In Tacview, object types are described with tags.

An object can have several tags at the same time. For example, an aircraft can be both Air and FixedWing. A tank can be Ground, Heavy, Armor, Vehicle, and Tank.

This makes tags more flexible than a single fixed type.

Use these pages to understand the available tags:

• TelemetryTags

• TelemetryTagNames

For normal add-on logic, prefer TelemetryTags. They are binary values designed for fast object filtering.

Use TelemetryTagNames only when working directly with telemetry type text, such as when creating or modifying telemetry data.

Filtering objects

Use tag tests to keep only the objects your add-on cares about.

• ObjectHasAllTags()

• ObjectHasAnyTag()

Use ObjectHasAllTags() when every requested tag must be present. For example, to find objects that are both Ground and Vehicle.

Use ObjectHasAnyTag() when one of several tags is enough. For example, to find objects that are either FixedWing or Rotorcraft.

Object identity

Use object identity helpers when you need to save, compare, or later retrieve a specific object.

• GetObjectId()

• FindObjectById()

Object handles are temporary runtime references. Object ids are more appropriate when an add-on needs to store a reference and resolve it again later.

Object names and display information

Use object name and display helpers when you need readable text or object-specific presentation data for the user.

• GetObjectLongName()

• GetObjectCallSign()

• GetObjectPilotName()

• GetCurrentObjectColor()

GetObjectLongName() is usually a good choice for reports, tooltips, analysis panels, and verbose user interface output.

For compact tactical labels, try GetObjectCallSign() first, then fall back to GetObjectPilotName() or GetObjectLongName() when needed.

Use GetCurrentObjectColor() when drawing add-on graphics that should match the effective color Tacview uses for the object.

Typical workflow

A common add-on pattern is:

local activeUnitCount = GetActiveUnitCount()

for activeUnitIndex = 0, activeUnitCount - 1 do
	local objectHandle = GetActiveUnitHandle(activeUnitIndex)

	if objectHandle ~= nil and ObjectHasAllTags(objectHandle, TelemetryTags.FixedWing) then
		local objectName = GetObjectLongName(objectHandle)
		local objectColor = GetCurrentObjectColor(objectHandle)

		-- Display or process this aircraft.
	end
end

This workflow is efficient because it starts from the active objects, filters them by type, then reads only the information needed for the objects that remain.