LEWDCOM EXTERNAL ANIMATION ADDON GUIDE
======================================

This guide explains how to publish extra paired sex animations as a separate
XCOM 2: War of the Chosen mod. LewdCom does not need to be edited or rebuilt.


1. WHAT AN ADDON MUST PROVIDE
-----------------------------

An external animation addon needs three things:

1. A cooked UPK containing an AnimSet and its animation sequences.
2. Config/XComLewd.ini rows mapping a character template to sequence names.
3. A small X2DownloadableContentInfo class that attaches the AnimSet to the
   character templates which will play those sequences.

The INI mapping alone is not enough for a new UPK. XCOM does not automatically
search every loaded package for animation names; the AnimSet must be added to
the pawn's character template.


2. RECOMMENDED ADDON STRUCTURE
------------------------------

YourLewdAnimationAddon/
  Config/
    XComGame.ini
    XComLewd.ini
  Content/
    YourLewdAnimationPkg.upk
  Src/
    YourLewdAnimationAddon/
      Classes/
        X2DownloadableContentInfo_YourLewdAnimationAddon.uc

Use unique package, AnimSet, sequence, and DLC names to avoid conflicts with
other mods.


3. PREPARE THE ANIMSET
----------------------

Import and save the animations into an AnimSet in your UPK. Example:

  Package: YourLewdAnimationPkg
  Group:   Anim
  AnimSet: AS_YourPairedAnimation

Example sequence names:

  YourAnim_Soldier_Begin
  YourAnim_Soldier_Loop_1
  YourAnim_Soldier_End
  YourAnim_SoldierT_Begin
  YourAnim_SoldierT_Loop_1
  YourAnim_SoldierT_End

The names do not have to use "Soldier" and "SoldierT", but every name in
XComLewd.ini must exactly match a sequence in the AnimSet.

Normal role convention:

  Source = attacker
  Target = victim (often named SoldierT)

If LewdCom's "Female attacker uses Target (T) role" option is enabled, a female
attacker automatically uses the Target sequences and her victim uses Source.
The animation pair must therefore remain correctly aligned when roles reverse.

The animation skeleton must be compatible with every pawn that will play it.
An incompatible skeleton usually causes a T-pose, distorted mesh, or a
"Can't play animation" message in Launch.log.


4. DECLARE THE LEWDCOM DEPENDENCY
---------------------------------

Create Config/XComGame.ini:

  [YourLewdAnimationAddon.X2DownloadableContentInfo_YourLewdAnimationAddon]
  DLCIdentifier="YourLewdAnimationAddon"
  +RequiredMods="LewdCom"

  [YourLewdAnimationAddon CHDLCRunOrder]
  +RunAfter="LewdCom"

For a published addon, use LewdCom's Workshop published-file ID where your
release workflow requires a Workshop dependency. "LewdCom" is suitable for
local development.


5. ADD THE ANIMATION MAPPING
----------------------------

Create Config/XComLewd.ini:

  [LewdCom.LewdLib]
  +LewdAnims=(Alien="MyCustomAlien", \
      SourceBeginAnim="YourAnim_Soldier_Begin", \
      SourceLoopAnims=((TransitionAnim="",LoopAnim="YourAnim_Soldier_Loop_1")), \
      SourceEndAnim="YourAnim_Soldier_End", \
      TargetBeginAnim="YourAnim_SoldierT_Begin", \
      TargetLoopAnims=((TransitionAnim="",LoopAnim="YourAnim_SoldierT_Loop_1")), \
      TargetEndAnim="YourAnim_SoldierT_End")

Important:

* Alien= is the exact attacker X2CharacterTemplate name, not its display name,
  class name, or CharacterGroup.
* Examples include Soldier, Sectoid, AdvTrooperM1, and SkirmisherSoldier.
* Add a separate row for every attacker template that should select this pair.
* Multiple rows with the same Alien= create a random animation pool.
* LewdCom chooses one pool entry when the bind begins and keeps it for that
  bind's Begin, Loop, and End.
* Begin and End may point to the Loop sequence if separate clips do not exist.


6. ATTACH THE ANIMSET
---------------------

Create:

  Src/YourLewdAnimationAddon/Classes/
  X2DownloadableContentInfo_YourLewdAnimationAddon.uc

Example:

  class X2DownloadableContentInfo_YourLewdAnimationAddon
      extends X2DownloadableContentInfo;

  static event OnPostTemplatesCreated()
  {
      // Custom attacker: attach the AnimSet and add LewdCom's Sex ability.
      class'LewdAnimationSetup'.static.EnableLewdForTemplateName(
          'MyCustomAlien',
          "YourLewdAnimationPkg.Anim.AS_YourPairedAnimation",
          true,
          true);

      // Possible target: attach the AnimSet, but do not add the Sex ability.
      class'LewdAnimationSetup'.static.EnableLewdForTemplateName(
          'Soldier',
          "YourLewdAnimationPkg.Anim.AS_YourPairedAnimation",
          true,
          false);
  }

Function arguments:

  EnableLewdForTemplateName(
      TemplateName,
      AnimSetArchetypePath,
      bFemaleUsesSameSet,
      bAddSexAbility)

Set bFemaleUsesSameSet=true when the same AnimSet is valid for female pawns.
This adds it to both AdditionalAnimSets and AdditionalAnimSetsFemale.

Attach the AnimSet to EVERY character template that may play either half of
the animation. For example, if MyCustomAlien attacks Soldier, both templates
need the AnimSet. If Soldier can attack MyCustomAlien, add a LewdAnims row for
Alien="Soldier" as well.

EnableLewdForTemplateName applies to all difficulty variants returned for that
exact template name. Different template names still require separate calls.


7. OPTIONAL RUNTIME REGISTRATION
--------------------------------

Instead of defining mappings in XComLewd.ini, an addon may construct
LEWDAnimInfo values in UnrealScript and call:

  class'LewdAnimationSetup'.static.RegisterLewdAnimInfo(Info);

or:

  class'LewdAnimationSetup'.static.RegisterLewdAnimInfos(Infos);

INI mapping is recommended for simple addons because users can inspect and
override it without recompiling.

Available attachment API:

  RegisterLewdAnimInfo(Info)
  RegisterLewdAnimInfos(Infos)
  EnableLewdForTemplate(Template, AnimSetPath, FemaleSameSet, AddSexAbility)
  EnableLewdForTemplateName(Name, AnimSetPath, FemaleSameSet, AddSexAbility)

LEWDAnimInfo and LEWDLoopAnimInfo are declared in LewdLib.uc.


8. BUILD AND PACKAGE
--------------------

1. Build the addon in ModBuddy.
2. Confirm the cooked mod contains:
   * Config/XComGame.ini
   * Config/XComLewd.ini
   * Content/YourLewdAnimationPkg.upk
   * The addon's compiled script package
3. Enable both LewdCom and the addon.
4. Make sure the addon loads after LewdCom.
5. Restart XCOM 2 after changing AnimSets or template attachment code.

If ModBuddy cannot resolve LewdAnimationSetup while compiling, make sure
LewdCom is installed in the SDK environment and configured as a required
dependency. The compiler must be able to see LewdCom's compiled script package.


9. TESTING
----------

Start tactical and use these console commands:

  LewdPrintAllAnimsForAlien MyCustomAlien
      Lists all INI and runtime mappings for that attacker template.

  LewdPrintAllAnims
      Dumps every merged mapping.

  LewdPrintAnimVariant
      Shows the selected unit's active random variant.

Trigger the Sex ability several times and inspect Launch.log for [LewdCom].

Expected:

* The new mapping appears in the attacker's pool.
* The same variant is used for Begin, Loop, and End.
* Source plays the Source sequence.
* Target plays the Target sequence.
* With female-role reversal enabled, a female Source plays Target and her
  victim plays Source.


10. TROUBLESHOOTING
-------------------

"Can't play animation" / unit T-poses
  The sequence name is wrong, the AnimSet was not attached to that pawn, or
  the animation skeleton is incompatible.

Mapping appears but animation does not
  XComLewd.ini loaded correctly, but the AnimSet attachment is missing. Check
  the addon X2DownloadableContentInfo and load order.

No mapping appears
  Alien= does not exactly match the attacker's character template, or the
  external XComLewd.ini was not packaged.

Works for male but not female
  Pass true for bFemaleUsesSameSet and verify the sequence supports the female
  pawn skeleton.

Attacker animates but target T-poses
  Attach the AnimSet to the target's character template too.

Wrong animation pair selected
  Multiple LewdAnims rows with the same Alien= are randomized by design.

Begin works but Loop/End fails
  Check every sequence name independently. All referenced names must exist.

Units move or disappear
  Inspect root-motion/location keys and RMA data in the exported FBX. This is
  an animation-export problem, not an INI registration problem.


11. WHAT DOES NOT REQUIRE LEWDCOM CHANGES
-----------------------------------------

An addon does not need to:

* Edit X2DownloadableContentInfo_LewdCom.uc.
* Add hard-coded RegisterYourAnimation functions to LewdCom.
* Put its UPK inside LewdCom.
* Rebuild or redistribute LewdCom.

Keep the addon independent: its own UPK, INI mapping, and tiny template
attachment hook are sufficient.