In depth Guide for Slavers Of Skyrim

Chapter:	Capture System and capture procces
Modul: Capture modul
-------------------------------------------
Written for: Stage 2 
Version: Step 2 - V3
in the year of: 2024
Month: 10
Day: 27
-------------------------------------------

The system that controls how to capture actors, what actors can be captured.

Concerns: compatiblity: as making the mod unknown that mods the end user going to use.
For this reason only allow capture the actors that this mod provides, the player and its follower and marked follower.
To avoid abuse player marking known critical npcs as follower and make them captured add a No Capture faction. if a actor belong to this faction capture is not possible.
Capturing possible only using special slaver weapons. This weapon contain a enchantment, the magic effect contain the capture script.

This limits the ability of the slavers to capture only until the weapons they usuing run out of charges.
Same hold true for the player, of corse.

Palyer can chose disable at full the capture function. This case no actor able to capture anything, or limited to npcs, or followers more details on user interface section.

Allowed to capture:
-actors that member any of the fallowing factions:
--victim
--player follower ( if capture enabled )
--curent follower ( if capture enabled )
--current hiring ( if capture enabled )
--player marked follower  ( if capture enabled )
--SlaverActor-IF player owns own slaver base so player can capture the slavers!
(SLOSSlaverActorFaction)

-the actor hp below the desiginated treshold( 50% by default )
-member of playeble race
-not a child
-not dead
-its a actor keyworded

Actors that can capture others:
not all actor allowed to capture others! 
this controled by the slosTagCaptureFaction if one belong to this faction they can capture others

player can be capture other actors if meet the fallowing requirements:
-being in member of slos tag capture faction
-member of the slaver guild OR conquered a slaver base OR buy a avible slaver base

if player any way control any slaver base location AND member of slaver guild, player may chose to send new captured slaves to own slaver base. 
for this player need add itself to SLOSPlayerGetSlavesSelfFaction. this way signaling the system if possible slaves must be transported to the own slave bases if possible.
this function may avible trought the player controled locations...

player or player follower or other special captures:
some actor considered as special capture target, the moment the fallowing is considered:
-player
-player follower or hirering in the curent system
-plyer makred follower

special capture targets get own special theatment:
a capture ready type quest started to handle the event of capture. multiple same type of quest planned for this type of captures.

___________________________
THE Capture procces:
----------------------------

if target meet all requirement and hit the capture effect

-checked capture is allowed( disabled, the target type invalid )
-Check the attacker has right to capture, need belong one of this factions:
SLOSTagCaptureSlaveFaction
SLOSPlayerClaimLocationFaction

-check the target is alive, if not stop

-check the attacker is player or not, if yes:
--if player is the attacker check its own any slaver base? AND target is belong to any of the fallowing faction: 
SLOSVictimMemberFaction
SLOSSlaverActorFaction

if both statment true( player own slaver base and target belong one of the factions ):
cast spell:  SLOSCapturePlayerStorageSpell
This spell then procces the target capture by player, add the victim to player own slaver base and teleport there.

-in case player not own any slaver base OR the owened slaver base storage is full, check the player part of the slaver guild or not?
SLOSPlayerSlaverGuildMemberFaction
--target need to be the victim faction:
SLOSVictimMemberFaction

if this all true cast spell: SLOSCaptureNPCSpell
this spell used to capture the normal npcs by slavers.
after casting spell register player for 1 more capture for the guild.

end of procces.

-if not the player the caster then it must be a slaver so need run 2 checks:
1 - check the target belong to victim faction ( SLOSVictimMemberFaction )
2 - check target is player?
3 - if not belong to victim faction need check its player follower? ( SLOSTagPlayerFollowerFaction  ) or ( CurrentFollowerFaction ) or ( CurrentHireling )

if case 1 :
Cast spell: SLOSCaptureNPCSpell
if case 2 :
Cast Spell: SLOSCapturePlayerSpell
if case 3:
Cast Spell: SLOSCaptureFollowerSpell

end of procces.

as can seen the capture procces broken 2 part.
first part select the right capture spell, secund part the execution of case specific capture.
this moement we have 4 type of capture spell as can seen above, let see how this works:

Spell: SLOSCapturePlayerStorageSpell

opens up a form list to see what player locations avible, start serach on this locations for free slots:
SLOSPlayerClaimActiveQuestList
When the first free slot found slave teleported the slaver base new capture arrival location, made a new slave and added the local storage.

Spell: SLOSCaptureNPCSpell

this spell checks for free storage slots on any slaver guild owened slaver base that active.
upon finidng the first avible slot the slave transported there and made a slave.
in case this procces fail, the slave added the infinity storage list, and actor got disabled.
evry cycle end the system check the list if find free slot ony slaver base then adds the slaves from the list this storage spots.

Spell: SLOSCapturePlayerSpell and SLOSCaptureFollowerSpell

this 2 spell work near identical only big difference they are using different form lists to determinate what to do.
follower and player capture require a ready type capture quest running and ready to used.
this type of quest stored a form list called:

SLOSReadyCapture<NAME OF LIST TYPE>

when a quest chosen from the list to used a activation signal sent to the quest ( seting stage to 10 ) this trigger the capture procces and start the quest for the player.
in case something go wrong the activation considered failed. that case nothing happen OR worst case after capture happened the quest stop it self and captured actor made free.

All capture event need to reported to the event system.
___________________________
Transformation Sub system:
----------------------------

Captured actor trasformation to slave/back to normal, here is why:
-they are salves now, so normal behavior not okay
-they need to be registered as not enemy to slavers or slave oweners or any of they allyes
-the slaves need behave like slaves for immersion reason
-need give a way to player to realise slaves if chose to do

To make slave a normal actor need to:
-store in a quest as reference alias, this alis can force new behavior on the actor
-this reference alias used to attach scripts to actor so we can detect events happen with that actor
-add salve amulet that signals the actor is a slave( SLOSSlaveAmulet )
-add slave to the SLOSTagCapturedFaction - signaling this way this actor is a slave, thus making all the slavers frendly towards them
-all quest alias that used store slaves need to add a faction that only used that type of quest:
SLOSTag<Entity Name><Quest type name>

<Entity Name> = Slaver guild or Guild in sort. maybe SlaveOwener, player or PlayerClaim
<Quest type name> = the type of quest, example: marketplace, slave trader

transformation salves need to be two way operation and integral part of the storage script!

To make slave actor to normal agin need to:
-Remove From faction: SLOSTagSlaveAttackGuildFaction
-Remove From faction: SLOSTagCapturedFaction 
-remove the amulet ( SLOSSlaveAmulet )
-Remove from the storage system

___________________________
Storage Subsystem:
----------------------------

Need a system that make captured actors, slaves and make them behave like a slave.
This system need to do:
-need to be stored in a way that they can restored to its original state if freed.
-detect when a slave got killed
-detect when a slave got freed
-ability to tell who own the slave
-ability to trade/swap the slaves betwen oweners
-ability to change the actor behavior and forve a chosen one on it
-Slaves need registered as frends to slavers so slavers not going to attack the slaves

this system need ot be flexible. any actor can be act as salve owener so the slave storage system need to built flexible.

this system mandatory to used evry where when slave handled or registered all palce need to use exact same script!
So the other modules can move or handle the slaves it self.

slave only accepted to the storage system if slave alive!

the storage system tasked to apply the trasromation sub system two way.
for this the storage can be called a special way.

All quest that contain a storage script required to meet fallowing requirements:
1 - be part of a form list that contain all of the ACTIVE same type quest. Example: all Slaver Camp quest need belong to: SLOSActiveCampQuestList
2 - the collector form lists that contain all ACTIVE quest need to be part of the fallowing form list: SLOSStorageQuestActiveList
3 - all storage type need own assigned faction! this faction only used by this storage and no else and no other use only mark the slave part of this type of quest
4 - all storage faction need to be added the fallowing list: SLOSStorageQuestFactionList
this list need contain SAME order all the factions as they representative active quest form list stored on: SLOSStorageQuestActiveList
5 - all sotred slave need to be flagged with : SLOSTagSlaveInStorageFaction
this is a safety function, if all slave flagged with this faction when inside a storage!
For this reason when a quest that store slaves not allowed to add reference alias to any slave that belong to this faction!

___________________________
Slave amulet subsystem:
----------------------------

All slave need wear a slave amulet.  this amulet used to signal the slave is a slave.
removal of the amulet by any other actor than the slave it self make the slave removed from the slave storage and freed of slavery.

if removal done by unatorized actor punihsment effect kick in that probably kill the slave and the remover.
To be authorized amulet removerr you need own the slave or wear slave master ring.

freeing salves that not belong to the actor who freed the slave need ot be reported tought the event system!

Amulet removal can be done player it self. this function nested in the SLOSdialogueGeneral quest
for this player need talk to slave and chose remove amulet option

The slave amulet removal means actor going to be removed from the storage where the slave belong.
this found out by the script on amulet a way that the script checks the SLOSTagSlaveInStorageFaction factions to the slave.
when find a faction that matches the slave faction, the system know what type of quest store this slave.
so the system use SLOSStorageQuestActiveList list, as the faction position in the faction list matches the collector list position in the active quest list.
this way only need check the fraction of all storage quest.

___________________________
EVENT - Slave amulet removal subsystem:
----------------------------

Event proccesed by: SLOSEventSlaveAmulet (Quest)

flags  the salve and amolet remover until the freed slave leave the curent location or change location.
Freed slave flagged with the fallowing faction:
SLOSTagEscapingSlaveFaction

escaping slave faction is enemy to all slaver guild member and all slave owener member!( mercanarys included )

The one who amde slave free flagged as:
SLOSTagPlayerRemovedSlaveAmuletFaction -if player
SLOSTagNPCRemovedSlaveAmuletFaction -if npc
SLOSTagSelfRemovedSlaveAmuletFaction -if removal done by self

The escaping slave flag removed from the slave if manage change location ie escape from the scane.
if the escaping slave captured before change location a new event called:

Event Capture Escaped Slave

___________________________
EVENT -  Capture Escaped Slave
----------------------------

Event Ptoccesed by: SLOSEventCaptureEscapedSlave

This event used to handle the escaping slave capture by slavers.
curent devlopment status the system only check if player done the amulet removal on slave.
if yes the:
-Slaver Guild entity
-Ring of Zenithar entity

got informed the event and appropiate action taken.

After the event proccesed, the re captured escaping slave removed from event - slave amulet.

___________________________
Capture non stadard actors
----------------------------

to handle the non standard victim capture we need capture quests.
This Ready type quest need to be started before the capture happens. this done by SLOSCore.
when a quest started register the revlant type of rady form list.
this way signaling ready to be activated.

Capture script when needed check the ready list for avible quest, if pick one send the activate signal.

The ready quest sent a activate signal by setting stage 10.
the ready quest after that check the slosCore for data on capture targets:
ReadyQuestCaptureTarget 

and the attacker who made the capture:
ReadyQuestCaptureAttacker 

then the capture quest execute the required steps make the victim a salve, add its own slave storage, plus telport the quest location where the other events play out.

this function controled by the SLOSManageCaptureQuestScript.
evry capture mission can be different. the capture quests run on location that flagged with capture keyword.
exact keyword requirement different for all capture quests. 

the capture quest can contain uniqe modules and script parts.

all subtype of capture quest need own:
SLOSManageCapture<NAME Quest TYPE>Script -- this script execute the registration changes when activated, stoped and started, and sub type specific actions.

the uniqe scritp that controls this specific quest need to depend on:
SLOSCapture<NAME Quest TYPE>EventScript

This script going to recive events that happen the captued alias, as captured alias need to be given a capture type specific alias script:
SLOSAliasCapture<NAME Quest TYPE>EventScript

all ready quest required to register on activation to this form list: 
SLOSActiveCaptureQuest<NAME Quest TYPE>List

when the capture quest finishes stops it self, unregisters from the active list.
SLOSActiveCaptureQuest<NAME Quest TYPE>List

___________________________
Special capture: Capture player
----------------------------

porpuse:
play out player captured by slaver guild event.
planned multiple of the player capture quest avible and system chose one from the list.
upon activation ( set stage 10 ) the quest take away the player to a pre defined holding cell, and from here the quest events play out.
below the quest basic requirements and functions can be seen.

Linked Quest names: SLOS_CP<XX>_CapturePlayerQuest   ( <XX> == Capture quest number of this type)

Form lists in use on this type:
SLOSActiveCaptureQuestPlayerList -- activated quests ( stage set 10 by capture effect script )
SLOSReadyCaptureQuestPlayerList -- ready to start quest list
SLOSQuestCapturePlayerList  -- list of all quest of this type

Mandatory scripts:
SLOS_CP<XX>QuestScript -- the main controler script for this quest! need to be wired into the stage 0, 10 and 900. 0 for quest start, 10 for activation , 900 to execute the stop procceses

SLOSAliasCapturePlayerEventScript  -- added to reference alias of player to foward event that happen on player

SLOSCapturePlayerEventScript  -- the quest main script need to extend this script to recive events from the player, or write uniqe script that used to procces this events
SLOSDataCapturePlayerQuestScript -- store data revelant to player capture slaver bases and locations
SLOSDataCaptureQuestScript -- store data that revelant to capture quests in general
SLOSManageCaptureQuestScript -- manage the setup,activation procces of the quest, this event from the main script need fowarded to it, if detects error report false! in false report activation need aborted!
SLOSRegisterCapturePlayerScript -- register the quest as activation ready, activated, and stopped need called from the main controller script.
SLOSStorageScript -- storage script for slaves mandatory as we store captured actor

SLOSBasicQuestScript -- its basic requirement
SLOSEventReporterScript -- in case we need report some events we need this

Optional scripts:
SLOSLockSlaverBaseScript - locks down on command the slaver base exits ( assuming all marked with "SLOSLocCaptureQSTLockBaseEntry" location ref. and feed into the script trought reference aliases )
SLOSItemCapturePlayerSupportScript - spawn support items near to player this include potions, and slaver weapons.
spawn location determianted by: 4 item spawn reference, this references need marked with : SLOSLocCaptureQSTSupplySpawn locationref
the spawn always expected close to player starting point

in case the quest stoped:
- need make sure the player removed from slavery.
-all object references made during run time need to be removed

___________________________
Special capture: Capture player follower
----------------------------
porpuse:
play out player follower captured by slaver guild event.
the quest of this type aim to provide the player opportunity by force rescue the captured  follower.
multiple of this quest planned ot be in place and system pick one of them that ready to be used.
on activation( setting stage to 10 ) the quest take away the designated character and place the holding cell that in hear of a slaver base.
from here on the quest events play out. this events and procceses can be totaly uniqe each quest.

Linked Quest names: SLOS_CF<XX>_CaptureFollowerQuest   ( <XX> == Capture quest number of this type)

Form lists in use on this type:
SLOSActiveCaptureQuestFollowerList -- activated quests ( stage set 10 by capture effect script )
SLOSReadyCaptureQuestFollowerList -- ready to start quest list
SLOSQuestCaptureFollowerList  -- list of all quest of this type

Mandatory scripts:
SLOS_CF<XX>QuestScript -- the main controler script for this quest! need to be wired into the stage 0, 10 and 900. 0 for quest start, 10 for activation , 900 to execute the stop procceses

SLOSAliasCaptureFollowerEventScript  -- added to reference alias of player to foward event that happen on player

SLOSCaptureFollowerEventScript  -- the quest main script need to extend this script to recive events from the player, or write uniqe script that used to procces this events
SLOSCaptureFollowerTakeControlScript -- special script to take control ower the follower and make it normal slave.
SLOSRegisterCaptureFollowerScript -- register the quest as activation ready, activated, and stopped need called from the main controller script.
SLOSDataCaptureQuestScript -- store data that revelant to capture quests in general
SLOSManageCaptureQuestScript -- manage the activation procces of the quest, this event from the main script need fowarded to it, if detects error report false! in false report activation need aborted!
SLOSStorageScript -- storage script for slaves mandatory as we store captured actor

SLOSBasicQuestScript -- its basic requirement
SLOSEventReporterScript -- player going to free a slave that not belong to player so this script must have!

Optional scripts:
SLOSLockSlaverBaseScript - locks down on command the slaver base exits ( assuming all marked with "SLOSLocCaptureQSTLockBaseEntry" location ref. and feed into the script trought reference aliases )

