Add OnGetPawnArchetypeString Event

[SurferJay]

Fixes #1521

[SurferJay]

Do I need to do anything else? I see no check next to the issue name from the main list. Did I skip something by accident?

[robojumper]

This needs a documentation entry (search for ```event to find some examples for event documentation).

[SurferJay]

Thanks @robojumper. Does this look right?

I'm holding off on the addition until anyone validates if this is the correct direction or not, since this is my first rodeo with such documentation.

// Start Issue #1521
/// HL-Docs: feature:OnGetPawnArchetypeString; issue:1521; tags:strategy,tactical
/// Triggers a 'OnGetPawnArchetypeString' event that allows listeners to override
/// the archetype path used during visualizations by setting the OverrideString.
/// Listeners can also observe the OriginalString and optionally react to or set the
/// CurrentPriority for use in per-spawn priority-based cross-mod arbitration.
///
/// ```event
/// EventID: OnGetPawnArchetypeString,
/// EventData: [inout String OverrideString, out String OriginalString, inout int CurrentPriority],
/// EventSource: XComGameState_Unit,
/// NewGameState: none

[Tedster59]

You'll want to convert this event to a helper function. For example, 58ef4c5 as well as many others in XComGameState_Unit that will appear if you search for "TriggerOverride"

[chrishayesmu]

@SurferJay When publishing Tedster's requested change, please include your proposed documentation comment as well. I have some thoughts but I'd prefer to go line-by-line on them. It's also just helpful to see the docs in the same context as someone would be after the merge.

[Tedster59]

Pending this for now after discussion with SurferJay

[SurferJay]

Here are my changes, which include:

1. Moving the tuple to a helper at Ted's request
2. The event documentation.

I just don't have the time to re-figure out how to sync my folder via pure command line prompt spam and then struggle to sort out the convoluted command line squash commands to push everything here. Busy with other things and can't bring myself to deal with GitHub's nonsensical (lack of) GUI right now, sorry.

// NOTE: bottom of GetPawnArchetypeString function
    // Start Issue #1521, Allow runtime override of SelectedArchetype (kUnit is NOT none for ELD_Immediate)
    TriggerOverrideSelectedArchetype(SelectedArchetype, kUnit, ReanimatedFromUnit);
    // End Issue #1521

    return SelectedArchetype;
}

/// HL-Docs: feature:OnGetPawnArchetypeString; issue:1521; tags:strategy,tactical
/// Triggers a 'OnGetPawnArchetypeString' event to override archetype path used in
/// visualizations. Listeners should determine their reskin outcome at runtime using
/// the kUnit and then check the tuple's priority to decide to override or not. If
/// their priority exceeds it, they should set BOTH the tuple's OverrideString AND
/// its OverridePriority to their corresponding values to inform everone else.
///
/// The primary use-case difference between a listener's priority and the tuple's
/// priority is that the latter can be randomized at runtime, allowing diverse and
/// unique per-spawn outcomes, rather than rigidity created at launch-time. For
/// instance, you can now implement ultra-rare skins or random skins (think Lost).
///
/// ex:
/// CurrentPriority = tuple[1].i;
/// GetMyReskinData(kUnit, outArchetypePath, outPriority);
/// if (outPriority > CurrentPriority)
/// {
///    tuple[0].s = outArchetypePath;
///    tuple[1].i = outPriority;
/// }
///
/// \`\`\`event
/// EventID: OnGetPawnArchetypeString,
/// EventData: [inout String OverrideString, inout int OverridePriority, out String OriginalString, out int ReanimatedUnitID],
/// EventSource: XComGameState_Unit,
/// NewGameState: none
static private function string TriggerOverrideSelectedArchetype(out string SelectedArchetype, XComGameState_Unit kUnit, XComGameState_Unit ReanimatedFromUnit)
{
    Tuple = new class'XComLWTuple';
    Tuple.Id = 'OnGetPawnArchetypeString';
    Tuple.Data.Add(4);
    Tuple.Data[0].kind = XComLWTVString;
    Tuple.Data[0].s    = "";                          // [0] OverrideString: listeners may supply a custom archetype string (leave empty to abstain).
    Tuple.Data[1].kind = XComLWTVInt;
    Tuple.Data[1].i    = -1;                          // [1] OverridePriority: integer priority for listeners to read/set (higher wins by convention).
    Tuple.Data[2].kind = XComLWTVString;
    Tuple.Data[2].s    = SelectedArchetype;           // [2] OriginalString: the pre-hook SelectedArchetype (reference only; do not modify).
    Tuple.Data[3].kind = XComLWTVInt;
    Tuple.Data[3].b    = ReanimatedFromUnit.ObjectID; // [3] ReanimatedUnitID: the ObjectID of the ReanimatedFromUnit argument.
    
    `XEVENTMGR.TriggerEvent(Tuple.Id, Tuple, kUnit, none); // Listeners may set [0].s (and optionally [2].i).
    
    // Adopt listener-supplied result only if provided (non-empty); otherwise, keep the original.
    if (Tuple.Data[0].s != "")
        SelectedArchetype = Tuple.Data[0].s;
    }
}