Wolfe's Struggle Systems 1.0.0

NOTE:

This mod does nothing by itself. It needs to be called by another mod.

To Test:

"coc wss2"

Wolfe's Struggle Systems: 

A Fallout 4 struggle / resistance minigame framework built for Advanced Animation Framework (AAF). When triggered, the player must fight back through a real-time QTE while an AAF scene plays. Win to break free and keep your outfit. Lose and the scene escalates.

Hard requirements:
- Fallout 4
- F4SE (required for the Scaleform HUD and extended input handling)
- Mod Configuration Menu (MCM)
- Advanced Animation Framework (AAF)
- Savage Cabbage animation pack

Recommended:

- Kziitd Fetish Toolset 1.0 Beta 3

Load order:
Place this mod below AAF, F4SE-dependent plugins, and MCM. Keep your animation packs below AAF as usual.

WHAT IT DOES:

When a struggle is triggered (dialogue, another mod, or a test call), the system:

1. Snapshots the player (and partner) outfit.
2. Starts an AAF struggle scene if AAF Compatible is enabled in MCM.
3. Shows a Scaleform struggle HUD and runs one of three minigame modes:
   - Mash — spam click / attack / jump / sprint to fill the bar.
   - Keyboard — press the prompted letter or gamepad face button.
4. Resolves win or loss:
   - Win — stops the struggle scene, restores clothing after a short delay, fires outcome events / quest stages.
   - Lose — progressively strips armor and clothing as the meter falls, then plays a defeat AAF scene.

HOW ARMOR AFFECTS THE STRUGGLE:

Armor is not just cosmetic — it changes how hard the fight is.

When Armor Affects Start Progress is enabled (default), better coverage gives you more of the bar at the start:
- Light clothing on the body slot gives a modest boost.
- Each worn armor piece adds bonus starting progress based on its rating.
- A strong full set can start you much higher on the meter.

Resistance while mashing / prompting

*Worn armor also scales how much progress you gain from successful inputs. Nearly naked = very slow progress. Full coverage = noticeably faster fills.

MODDER'S RESOURCE — HOW TO LINK YOUR MOD
========================================

Quote

 

This release is intended as a reusable framework. Other mods can trigger struggles and react to outcomes without re-implementing the QTE, HUD, AAF wiring, or clothing logic.

Core script
-----------
- Script: WSS_System
- Type: Quest script
- Attach it to your struggle controller quest in the Creation Kit.

You will need a quest in your plugin with:
- Player alias (fill PlayerRef on the script)
- Optional partner alias or speaker passed at runtime
- WSS_System attached and compiled (WSS_System.pex in your mod or a master dependency)

 

Minimum CK setup (your mod)
---------------------------
1. Create a Quest (example: WSS_StruggleQuest).
2. Attach script WSS_System.
3. PlayerRef is optional. If left empty, the script uses Game.GetPlayer() automatically. A Player alias is only needed if you prefer filling PlayerRef through an alias in CK.
4. Tune AAF tags, defeat tags, quest stages, and armor properties on the script as needed.
5. Ship WSS_System.pex (and Interface\WSS_StruggleBar.swf if you bundle the HUD) or list this mod as a hard requirement.

Recommended setup for other mod authors (cleanest)
--------------------------------------------------
Do not attach WSS_System to their own quest. Instead:

1. List Wolfes Struggle Mod as a requirement.
2. On their quest script, add a property:

    WSS_System Property StruggleSystem Auto
    { Fill with the WSS_StruggleQuest from Wolfes Struggle Mod. }

3. Call it from dialogue, packages, or their own logic:

    StruggleSystem.StartStruggleWithSpeaker(akPartner, -1.0)

This keeps one central struggle controller while their mod only triggers it.

Can an activator / trigger / ObjectReference script call it?
--------------------------------------------------------------
Yes. ObjectReference scripts cannot easily use GetOwningQuest() for your quest, but they can hold a quest reference property the same way:

    WSS_System Property StruggleSystem Auto

Fill that property in CK with the Wolfes Struggle Mod quest, then call:

    StruggleSystem.StartStruggleWithSpeaker(SomeActor, -1.0)

A trigger box can use an OnTriggerEnter script; an activator can use OnActivate. The ObjectReference script calls the quest script function through the filled property. That is normal Fallout 4 Papyrus and works fine.

Starting a struggle from dialogue on the struggle quest itself
--------------------------------------------------------------
On a dialogue line or fragment on the same quest:

    (GetOwningQuest() as WSS_System).StartStruggleWithDialoguePartner()

Uses the current dialogue target as the partner. Optional difficulty override (0–100, higher = easier):

    (GetOwningQuest() as WSS_System).StartStruggleWithSpeaker(AKSpeaker, 50.0)

Starting from another quest or object reference
-----------------------------------------------
Fallout 4 has no Quest.GetQuest(). Use a quest reference property on your script:

    WSS_System Property StruggleSystem Auto
    { Fill with the WSS_StruggleQuest from Wolfes Struggle Mod. }

Then call:

    StruggleSystem.StartStruggleWithSpeaker(akPartner, -1.0)

Pass -1.0 for difficulty to use the MCM / default value. This works from quest scripts, dialogue fragments, activators, triggers, or any other script that can hold a filled quest property.

Other public functions
----------------------
- StartStruggleWithDialoguePartner() — partner from dialogue target.
- StartStruggleWithSpeaker(Actor akSpeaker, Float afDifficulty) — explicit partner + optional difficulty.
- StartStruggleQTEOnly(Float afDifficulty) — bar only, no AAF struggle scene.
- CancelStruggle() — abort a pending or active struggle.
- IsStruggleActive() — returns whether a struggle is running.

Test functions (console / papyrus on the quest)
-----------------------------------------------
- StartStruggleBarTestMode1() — force Mash HUD
- StartStruggleBarTestMode2() — force Pendulum HUD
- StartStruggleBarTestMode3() — force Keyboard HUD

Reacting to win / loss
----------------------

Option A — Quest stages (simplest)
Set on WSS_System in CK:
- WinQuestStage (default 10)
- LossQuestStage (default 20)

The script advances its owning quest to those stages on outcome.

Option B — Custom event (flexible)
Register on the struggle quest:

    RegisterForRemoteEvent(StruggleQuestRef as WSS_System, "OnStruggleOutcome")

Handle it:

    Event WSS_System.OnStruggleOutcome(WSS_System akSender)
        Actor player = akSender.LastOutcomePlayer
        Actor partner = akSender.LastOutcomePartner
        Bool won = akSender.LastOutcomePlayerWon
        ; your logic
    EndEvent

Readable outcome properties on WSS_System:
- LastOutcomePlayer
- LastOutcomePartner
- LastOutcomePlayerWon

Disable the custom event in CK with FireOutcomeCustomEvent = False if you only want quest stages.

AAF integration notes for modders
---------------------------------
Important script properties (AAF group):
- StruggleIncludeTags / StruggleExcludeTags — how AAF picks the struggle animation.
- StrugglePosition / StrugglePositionPool — override with your pack’s position IDs.
- DefeatPosition / DefeatIncludeTags — what plays on loss.
- PlayAAFDuringStruggle — mirrors MCM “AAF Compatible”.
- AAFStartEquipmentSet = WSS_StruggleKeep — uses AAF\WSS_Struggle_equipmentSetData.xml to avoid instant strip at scene start.
- PartnerIsActor0 — set False for typical female-player / male-partner packs.

The mod registers for AAF events (OnSceneInit, OnAnimationStart, OnAnimationChange, OnSceneEnd) automatically when AAF is available.

Clothing / armor extension
--------------------------
Useful CK properties:
- ProtectedStruggleArmorItems — forms never stripped.
- ProtectedStruggleArmorKeywords — keywords never stripped (cuffs, harnesses, etc.).
- StripArmorOnFailure — toggle progressive strip.
- KeepClothedDuringStruggle — keep outfits on during the struggle scene when possible.

Difficulty from your mod
------------------------
Pass a float 0–100 to StartStruggleWithSpeaker / StartStruggleQTEOnly. Higher = easier escape. MCM difficulty presets still apply to drain tuning unless you override per call.

File layout modders may depend on
---------------------------------
Scripts\WSS_System.pex
Scripts\Source\User\WSS_System.psc
Interface\WSS_StruggleBar.swf
AAF\WSS_Struggle_equipmentSetData.xml
MCM\Config\WolfesStruggleMod\config.json
MCM\Config\WolfesStruggleMod\settings.ini

Permissions
-----------
If you release a mod that depends on this framework, credit Wolfes Struggle Mod and link back to this page. Do not redistribute WSS_System.pex under a different name without permission. Your own quests, dialogue, and triggers are yours.