What is "unit.psi" and why is it screwing up a spawned unit's heading?

[cfrag]

I've run into a head-scratcher, and would love someone to help me understand this.

I'm cloning an air group by taking the group's data from the mission table. Instead of simply cloning the group, I'm modifying the group data table to move the group (any waypoints) around the map, and rotate the group to come to a new heading (and rotate all waypoints accordingly.

This invariably FAILS - all units spawn with the original heading that was assigned in mission editor via the waypoints.

Now, (after banging my head hard against the table a couple of times, and some intense data analysis) I've found that a (perhaps under-documented, I have no docs on that attribute except that it's an optional attribute of type number) unit attribute called 'psi' controls this. If I simply nil each unit's 'psi' attribute, all units spawn correctly, with their heading set. I do note that the values of psi and heading coincide in the example below, so the work-around is obvious. The question is: WTF is psi and why not use heading?

Which leads me to the more polite question: what is an air craft unit's 'unit.psi' used for and why is it screwing with the unit's heading? 

Below is a group's units data table straight from the mission with the "psi" attribute in question 

["units"] = 
{
	[1] = 
	{
		["alt"] = 2000,
		["alt_type"] = "BARO",
		["livery_id"] = "104th FS Maryland ANG, Baltimore (MD)",
		["skill"] = "High",
		["speed"] = 123.33333333333,
		["AddPropAircraft"] = 
		{
		}, -- end of ["AddPropAircraft"]
		["type"] = "A-10A",
		["unitId"] = 1,
		["psi"] = 0.033100488715176,
		["y"] = 633690.14752139,
		["x"] = -278759.34381617,
		["name"] = "Aerial-1-1",
		["payload"] = 
		{
			["pylons"] = 
			{
			}, -- end of ["pylons"]
			["fuel"] = 5029,
			["flare"] = 120,
			["ammo_type"] = 1,
			["chaff"] = 240,
			["gun"] = 100,
		}, -- end of ["payload"]
		["heading"] = -0.033100488715176,
		["callsign"] = 
		{
			[1] = 1,
			[2] = 1,
			[3] = 1,
			["name"] = "Enfield11",
		}, -- end of ["callsign"]
		["onboard_num"] = "010",
	}, -- end of [1]
}, -- end of ["units"]

 

Edited October 21, 2022 by cfrag

[Grimes]

This is the only reference to it in the editor that I can find. 

 

for k,v in pairs(group.units) do
  v.heading = heading
  v.psi = -heading
end					

No idea what it is for. 

[winghunter]

I have the same issue, and found this

local function setUnitStartParameters(unit)
  if unit.boss then
    local route = unit.boss.route
    if route then
      local p1 = route.points[1]
      if p1 then
                unit.speed    = p1.speed
                unit.alt    = p1.alt
                unit.alt_type = p1.alt_type
                if p1.type.action == 'From Ground Area'  or p1.type.action == 'From Ground Area Hot' then
                    unit.psi = -unit.heading
                else
                    local p2 = route.points[2]
                    if p2 then
                        unit.psi = math.atan2(-(p2.y - p1.y), p2.x - p1.x)
                    end
                end
      end     
    end
  end
end

Edited May 10, 2023 by winghunter

[winghunter]

Hmm so these are the Euler angles

• ψ psi – heading
• θ theta – pitch angle
• Φ phi – bank angle

The reason "psi = - heading" may be due to the coordinate system.
 

Edited May 10, 2023 by winghunter