Jump to content

The Sexoutng Api (How-To For Modders)


Recommended Posts

Correct, there is no difference for the player.

 

GetOrientation now correctly honors the MCM preference for NPC if their orientation has not been set.

 

Caveat: If you used 'SetOrientationFl 0' on an NPC with a previous version, it will now count as unset, so you will need to call it again.

 

---

 

@zippy: No, it is actually 'hetro' (blame prideslayer for the typo ;)). I suppose I could just compare the first 2 characters and then it will work with both.

Link to comment

Me again, sorry :)

Just wondering, is there a way to know for sure whether a Sexout act has actually started or not. Everything seems to be fine with single acts, but when there are multiple in parallel or in sequence they sometimes just don't fire.
I was trying to implement a sort of a pool/queue of actors to be picked by a function which then fires fnSexoutActRunFull(...) on them. Basically the logic is this:

  1. there is a "rotating" queue of actors for a function to pick from;
  2. each picked actor is marked as "reserved" so that he can't be picked again;
  3. each actor is checked for all the usual stuff, including fnSexoutActorValid and fnSexoutActorInuse;
  4. if everyone is valid, Sexout is executed: fnSexoutActRunFull(Ar_Map "ActorA"::rActorA "ActorB"::rActorB ... "CBSpellA"::SpellA "CBSpellB"::SpellB);
  5. if the act was executed successfully, spells SpellA and SpellB are being cast, which apart from other stuff release actors from the "reserved" state so that they can be picked again;
  6. GoTo 1

Everything should work fine theoretically, but sometimes step 4 just doesn't run (especially if the same actors are being picked again), so the spells are not cast and the actors stay "reserved" forever, and the queue is never exhausted.

Is there some catch, or maybe some warmup — cooldown period between calls on the same actors?

On fnSexoutActRunFull execution are the actors being immediately marked as "in use", so that this check can be used instead of reserving them manually, or may it fail if run immediately after a Sexout call?

Link to comment

fnSexoutActRunFull: I haven't touched this yet, and it looks like it could be improved a little, but it should:

 

- Attempt to lock all actors (set InUse Flag), if one is already locked in-use the call aborts.

- Starts sex via a spell, so there will be frame or two before it kicks off.

 

fnSexoutActorInUse:

 

- Returns true if the actor is locked. So, is accurate immediately after ActRunFull is called. Actors may still be locked when the callback spells fire. Not sure.

 

----

 

It is advisable to check fnSexoutActorInUse before you make a call. I have done a similar thing to you many times in soliciting, my approach which I've found very reliable is:

 

(Take a look at TSolIndemnityQuestScript, SexoutSolDuntonBrotherSexScript, et al)

 

Use a quest script with a 1 second delay and variable stages

   if iStage == 0
       if eval (call fnSexoutActorInUse ActorA)
           return
       elseif eval (call fnSexoutActorInUse ActorB)
           return
       else
           call fnSexoutActRunFull (Ar_Map "ActorA"::ActorA, "ActorB"::ActorB....)
           let iStage := 10
       endif
    elseif iStage == 10
       ; # similar to above. I often add a few seconds minimum delay between calls,
       ; # and a timeout check in case actors never stop being InUse, just to be safe, but you shouldn't actually need to.
    ...

---

 

You shouldn't need to worry about tracking reserved states yourself, doing so is kind of reinventing the wheel.

Link to comment

Odessa, thanks, I think I'll try a few things...

The initial idea was that instead of constantly running a background script use recursive calls on actors (i.e. on act end they release themselves from locked state and fire a new act), but it looks like it may be not quite reliable.

Another thing — sometimes actors get stuck in InUse state forever even when the act doesn't fire, or sometimes on act end. May there be any particular reason to that? Is SexoutNGFinishNow for forcing them free? And for some reason the player gets stuck in that state more often than anyone else.

 

---------

EDIT

 

All right, I cheated. Right after calling fnSexoutActRunFull I cast on all participating actors a 4-seconds spell with a ScriptEffectFinish block which checks if an actor is in use by Sexout, and if not, it supposes the act has failed to start and forcibly kicks the actor out of action, releases him and places back on the queue. Works fine for now...

Link to comment

The way sexout currently (as of '94) works, a spell is cast on actorA and after the timer runs out, it ends the act, cleans stuff up and unlocks the actors (behind the scenes CIOS SexoutNGFinishNow essentially sets the timer to end).

 

If that spell ends prematurely, it never reaches the end phase so actors are left locked- usually this happens because the player changed cell or the NPC died, which seems to make the engine drop NPC spells. (In '95, I plan to rework the system to allow animation chaining, and make it more robust in the process).

 

Historically this was quite a bad problem with sexout, but a few versions back prideslayer added a workaround to clear invalid locks on actors which is triggered by calling fnSexoutActorInUse.

Link to comment

It just seems to me now that when there is a lot of simultaneous action going on, the game engine screws something up or something, because almost every time on the queue end the actors stay locked (InUse = true). And sometimes actors get locked on RunFull call, but nothing happens for (probably) an act duration, they just switch to their usual packages, and then I guess the actors are being released since they return back to the queue.

 

I also have some packages with idle animations added to the actors, may this be causing any problems?

(The packages which should be played theoretically pre/post/between acts, but NPCs just seem to ignore them most of the time for some reason and also ignore specific conditions inside those packages, even removing all of the packages but one doesn't seem to do the trick half of the time, I don't get it, this game is frustrating %)

 

EDIT: looks like the packages evaluate their conditions waaay slower than everything else, I've got a condition like "Quest.iStage > 50 AND Quest.iStage < 200", but the NPCs still keep running it even when iStage is 400, 500, etc. EVP doesn't help.

Link to comment

Make sure you don't have flags like Must Complete or Continue if PC Near set in the packages.

Thanks! That may have been the case for some of the issues. Also for some reason Niner (that's a companion mod) tends to be a special case: he keeps running the last assigned package even after it has been removed with "RemovePackageAt". Even ResetAI fails, only talking to him helps, that's weird.

 

Odessa, I've finally paid attention to Sexout debug output and have noticed that it gives a lot of "9.1 Black list ignored- All matching animations were black listed" errors which I believe in my case mean there is just no suitable animation combo for my flags. I've looked for a way to run this "actors animation compatible check" and found the calling function "fnSexoutGetAnimIntersect" and tried to use it, but it is dependent on another function which is dependent on another an so on. Is it somehow possible to perform the animation check prior to running "RunFull"? Otherwise the calling script just doesn't know the reason of failure and keeps trying to run the same incompatible threesome again and again instead of just kicking out ActorC :)

 

EDIT: Removing "rape" from the flags list seems to have solved about 90% of the problems... is there something special about it?

Link to comment

fnSexoutGetAnimIntersect is not part of the public API and so is subject to change without notice, please don't call it from your mod.

 

If there are no animations matching your flags, you will get "Warning! Too many flags to match any animation. Ignoring flag: XXX" messages, meaning sexout has dropped one of the calling mod's flags to try and find a match.

 

The 'black list ignored' message means that all animations matching your flags have been blacklisted by the user, so it ignores their preferences and selects from them anyway.

 

----

 

Currently the gender check is after the flags check, meaning if the flags filtered all options down to MFM but your actors are MFF you get nothing. This is probably the issue you are hitting. Fixing it has been on the todo list for a while, I'll add something to '95 beta 3, hopefully today.

 

More:

 

 

The way sexout works, fnSexoutGetAnimIntersect does:

 

1a) Deletes all unknown flags
1b) Takes the subset of animation matching flag #1, which is very fast because animations are pre-sorted by flag in an array.

1c) Takes the subset of animations matching #2, then finds the intersection with above, if this is empty, flag #2 is ignored.

1d) Repeat (1c) for next flag, until no flags remain.

2) Filter results by plugin specified. If no animations match your plugin, you get nothing :(.

3) Filter results by gender/skeleton. Creatures have their skeleton as flag #1 as a workaround, but for humans, if no animations match gender you get nothing :(.

4) Filter results by the user's anim blacklist, but if nothing remains ignore this step.

 

---

 

Okay, having typed all this out, I can see the solution: add 'sort' keys to every animdef, similar to flags but for gender/plugin. Coming soon.

 

 

Link to comment

fnSexoutGetAnimIntersect is not part of the public API and so is subject to change without notice, please don't call it from your mod.

 

If there are no animations matching your flags, you will get "Warning! Too many flags to match any animation. Ignoring flag: XXX" messages, meaning sexout has dropped one of the calling mod's flags to try and find a match.

 

The 'black list ignored' message means that all animations matching your flags have been blacklisted by the user, so it ignores their preferences and selects from them anyway.

 

----

 

Currently the gender check is after the flags check, meaning if the flags filtered all options down to MFM but your actors are MFF you get nothing. This is probably the issue you are hitting. Fixing it has been on the todo list for a while, I'll add something to '95 beta 3, hopefully today.

 

More:

 

 

The way sexout works, fnSexoutGetAnimIntersect does:

 

1a) Deletes all unknown flags

1b) Takes the subset of animation matching flag #1, which is very fast because animations are pre-sorted by flag in an array.

1c) Takes the subset of animations matching #2, then finds the intersection with above, if this is empty, flag #2 is ignored.

1d) Repeat (1c) for next flag, until no flags remain.

2) Filter results by plugin specified. If no animations match your plugin, you get nothing :(.

3) Filter results by gender/skeleton. Creatures have their skeleton as flag #1 as a workaround, but for humans, if no animations match gender you get nothing :(.

4) Filter results by the user's anim blacklist, but if nothing remains ignore this step.

 

---

 

Okay, having typed all this out, I can see the solution: add 'sort' keys to every animdef, similar to flags but for gender/plugin. Coming soon.

 

 

I've looked into the "fnSexoutGetAnimIntersect" function and it seem that it will return "Warning! Black list ignored- All matching animations were black listed." every time the final array is empty. I don't have anything blacklisted (haven't even touched this function) and I believe in my case it fails on "gender/species filter" when the "rape" flag is set. Probably it fails when a MMF combination is met? The function also seems to auto-blacklists ZAZ animations, I believe these are BDSM animations requiring special items? Sorry, still new here )

 

I've got my own functions which (prior to calling RunFull) check:

  • whether the actors are suitable (i.e. not dead, disabled and so on, valid for Sexout, not in use, some mod specific checks, etc.);
  • whether the actors A-B, C-B are orientation compatible and whether a particular combination (MM, FF, MF) is enabled in settings;
  • whether the actors are "scene compatible" — like creatures can only be ActorA with no threesomes and so on.

The final check I can't run externally is the "animations" compatibility, so when RunFull fails the calling script can't tell if it was because of an incompatibility or some other/random error and can't exclude an incompatible combination from its list.

 

How about making fnSexoutActRunFull return 1 if all checks passed and some -int error code on failure? This can be catched in the calling script and processed accordingly and shouldn't interfere with any existing mods I think :) And maybe like there is now a "noAnim" flag there could be also something like "CheckOnly" which will only run the checks and return true or an error code? :)

 

For now, do I have to explicitly disable any MFF and MMF combinations in my checks? Just wanted to keep it "future-compatible" and keep hardcoding stuff like that to a minimum :)

 

Link to comment

Mostly fixed/added in '95 beta 3 :)

Awesome! I'll check it out :)

I think this way I can try initiating a threesome, and if it fails, kick ActorC out and try again. \

Does false function value mean that some pre-run checks have failed, or just any kind of error?

 

***

 

Update:

Didn't even have to modify my function, RunFull now excludes the "rape" flag if no anims match participating actors :)

But in the future, will it be possible to get a function returning "animation compatibility" for an actors+flags combination? That way the incompatible combinations for a desired action can be excluded in advance, should be faster and more fail-proof than including a fully functional RunFull call inside a loop with general actor checks :)

Link to comment

Flags are filtered on in the order you specify them, with any that lead to 0 choices being ignored, so you should specify them in the order of importance.

 

Currently, ActRunFull returns 0 if any of the actors are in use or actorA is invalid, but a return of 1 doesn't guarantee it will complete- there are more checks later down the line.

 

I can add a new UDF GetAnimsForActors which returns all possible animations for a specified actor combination quite easily.

Link to comment

Flags are filtered on in the order you specify them, with any that lead to 0 choices being ignored, so you should specify them in the order of importance.

Yeah, I got that. Still, there may be no animation for a threesome even for one flag.

 

 

Currently, ActRunFull returns 0 if any of the actors are in use or actorA is invalid, but a return of 1 doesn't guarantee it will complete- there are more checks later down the line.

Oh, okay. So, I'm still keeping the timeout checks :)

 

 

I can add a new UDF GetAnimsForActors which returns all possible animations for a specified actor combination quite easily.

That would be really awesome!  :cool:

 

 

BTW, speaking about timeout checks, now I calculate the maximum act duration as:

dfTime + max(nKODurationRapee, nKODurationRapist) + 9

plus maybe a Spunk tolerance will be added later on. 9 is just randomly handpicked as an additional failsafe tolerance :) After that duration since RunFull call the actors will be forcefully kicked out of action if they are still "InUse". Is this about right, or are there any additional timings to be considered?

 

 

***

 

Update

Is it possible that Sexout kicks the PC out of movement control restraints at some point even when he isn't participating in the act? I've noticed it happens on either RunFull start or finish (most probably on start, I think, about when Sexout anims start playing) — the PC ends up with locked fighting and sneaking, everything else is unlocked (I don't use this particular combination in my scripts), and also gets kicked out any currently playing idle (he just stands there doing nothing, although PickIdle shows correct current idle in the console, but it doesn't kick in).

 

And also some small things:

  • Do "bDontRedress{?}"::1 flags work on NPCs? They seem to work fine on the Player, but any NPCs instantly redress right after the act regardless of this setting. The same is true for redressing options in the MCM — work for Player only.
  • The "bDontUndress{?}"::1 flags seem to work fine, although aren't any particular body parts supposed to, err, stick out through clothing this way? :) Or is this technically not possible (then why are there safe lists for crotchless/topless apparel?)
  • How do I mark two actors in a threesome as rapists? The "Raper"::ref flag only takes one...
Link to comment

Cool, I didn't know about that. Although, looks like prideslayer did and it doesn't help :(. I guess the spell continues but further CIOS don't work?

 

@nkAlex:

 

Your timeout check isn't reliable if an act sets the time manually, although you can find this using: SexActor.NX_GetEVFl "Sexout:Started::duration"

 

I believe if you set a duration manually, spunk does not adjust it. You can also force an act to end early using: SexActor.CIOS SexoutNGFinishNow

 

Controls being enabled/disabled when player not involved: it is possible, definitely a bug if so, will look into it.

 

bDontRedress on NPCs: I've noticed this doesn't work too, might be an engine issue but I will check it sexout side.

 

bDontUndress on males: The way the engine works, most clothing (slot 2) contains a body, so there is nothing to stick out. It would be possible to achieve this using a penis prop (like the strap on) for males.

 

Multiple actors flagged as rapist: Checking now, if you set A or C as raper in a 3P then both are counted as such, and B as rapee. If you set B as raper, then A and C are counted as rapee.

Link to comment

 


I guess the spell continues but further CIOS don't work?

The spell continues, I know that for sure. But I don't really know if you can CIOS after death, sincerely. But why should you CIOS more? is it the same spell or is it different?

Link to comment

Your timeout check isn't reliable if an act sets the time manually, although you can find this using: SexActor.NX_GetEVFl "Sexout:Started::duration"

Thanks! But if I start the act myself with RunFull the duration should be default, right?

 

I believe if you set a duration manually, spunk does not adjust it. You can also force an act to end early using: SexActor.CIOS SexoutNGFinishNow

Yeah, I use it as a final failsafe measure in case something went wrong (or somebody comes in and starts shooting at everyone mid-act. Maybe also an OnDeath event may be required).

 

Controls being enabled/disabled when player not involved: it is possible, definitely a bug if so, will look into it.

That may be probably intertwined somehow with an animation reset or something, since the PC gets kicked out of the idles. Restraining right after RunFull doesn't help, that behavior is a bit delayed and is triggered by some spell, I think. Most probably about the time the animations start playing.

Also, do I need to urestrain the PC before RunFull?

 

bDontRedress on NPCs: I've noticed this doesn't work too, might be an engine issue but I will check it sexout side.

May be a bug, since there are mods which undress NPCs and they stay naked.

 

bDontUndress on males: The way the engine works, most clothing (slot 2) contains a body, so there is nothing to stick out. It would be possible to achieve this using a penis prop (like the strap on) for males.

So those "safe" clothes are supposed to bind to another slots or not contain a body? Is there maybe some tutorial or an article or something on game mechanics in this department? :)

 

Multiple actors flagged as rapist: Checking now, if you set A or C as raper in a 3P then both are counted as such, and B as rapee. If you set B as raper, then A and C are counted as rapee.

Ok, thanks :)
Link to comment

@AJ: it is a different spell. I guess I'll have to rewrite that one as UDF or something.

 

@nkAlex: sexout should check the restrained state of actors/player controls (if player involved) and reset it to that when its finished.

 

There is a penis prop floating around the forum somewhere which you may be able to use over the top of clothing, made by Amra for futa if I recall correctly.

Link to comment

sexout should check the restrained state of actors/player controls (if player involved) and reset it to that when its finished.

I've just made a few checks and there's definitely a bug somewhere (maybe the PC gets restrained prematurely?). If I start RunFull on a restrained PC (I had movement, pipboy, fighting and sneaking disabled, to be specific), the act runs fine, but the PC ends up in a funny pose, which looks like a hang up animation, and acts as if everything but looking around is off. Well, he can also go to 1st person POV. GetPlayerControlsDisabled returns the states I've assigned before, EnablePlayerControls sets everything to enabled, but the PC is still stuck. Here's a screenshot, you can see the pose there:

 

 

006ba3962f9ft.jpg

 

AJ told me in another thread that you can assign a package to the PC, and after executing RemoveScriptPackage on him he is somewhat reset to a default standing pose and can be unrestrained as expected. So I guess something inside Sexout maybe forgets to cleanup a package?

I can unrestrain the PC pre-act and restrain him back in a post-act spell as a workaround, which works fine, but still doesn't solve the issue when he gets unrestrained without actually participating in the act.

 

 

There is a penis prop floating around the forum somewhere which you may be able to use over the top of clothing, made by Amra for futa if I recall correctly.

That... is something I'll maybe leave for the future for now  :)

 

***

 

Update

 

I'm using AJ's advice on resetting stuck animations with a reset.kf I've found in Sexout (there are several, I've picked the one with the most recent date: "Characters\_Male\IdleAnims\XXXAnims\reset.kf"), and it works fine.

I've also found a "Characters\_Male\IdleAnims\Expressions\reset.kf" which is I suppose for resetting NPC's facial expressions (they've got those ugly faces when kicked out of combat sometimes), but it has a 50/50 chance of making an NPC stuck instead. Is there something special about how to use it?

 

***

 

Update 2

 

NX_GetEVFl "Sexout:Started::Duration" always returns 0.0000 for me, does it mean "use default MCM duration"?. Other variables look right, and I'm reading them from a spell added to the SexoutNGFLGlobalCBStartS list.

Link to comment
  • 2 months later...
  • 1 month later...

(from 'new' loverslab)

 

Yes, the loverslab gitlab seems to have been down for a while :(.

 

I have a version of it from June (so, its missing new stuff) which is below. The new features are mentioned in the beta change log.

 

Obviously this isn't ideal though, hopefully gitlab will be back up soon.

 

API guide from June 13:

 

 

# Introduction
Sexout is a "meta-mod", or a mod primarily for other modders.  Players need to have it installed if they wish to use any Sexout mods, but on its own, it does not do anything for players.  For modders, it provides a simple interface to start and stop sex acts between actor references, notification of sex acts when they are initiated and when they complete, and other such features.

There are over 500 animation files in sexout used in combinations of 1 to 3 per act, with the total count of animated acts of all types being around 150 or 200.

This documentation is primarily for modders or those interested in becoming modders.  Players should read the main wiki page and the main download post for requirements and installation.

Everything modders and players need in order to get started is included in the two fomods, CORE which contains the two ESMs (Sexout.esm and SexoutSlavery.esm), the animation files, backups of earlier versions of sexout, sounds and textures -- and DATA which includes the T6M nude female model and texture, and the Breezes male nude model and textures.

# Basic Usage

call fnSexoutActRunFull (Ar_Map "ActorA"::EasyPeteREF, "ActorB"::SunnyREF)

The above will start a random sex animation with Easy Pete (EasyPeteREF) as actor A, and Sunny Smiles (SunnyREF) as actor B. You can change the actor REFs as desired.

This is the recommended interface for sexout; it supports all features and is future proof.

----

ActorA is the 'giver' in a sexout animation, and ActorB is the 'reciever'. Assuming further options are unspecified, Sexout will automatically pick an appropriate animation and sextype (Oral, Anal, Vaginal or None) to play based on the number of actors, their effective gender and species, and player MCM preferences.  

# Dialog Usage

Sometimes, modders may wish to start sex via dialog without knowing one of the specific actors, for example one may wish to use the same topic to start sex with any speaker. Using variables and GetSelf within dialog scripts sometimes works, but can unreliable; as such, sexout provides the following workaround:

call fnSexoutActRunFull (Ar_Map "ActorA"::0, "ActorB"::PlayerREF)

By passing the number zero for an actor, sexout will attempt replace it with the conversation subject. This workaround should not be used outside of dialog scripts.

# Flags

To tailor the animation sexout chooses to your vision, a powerful flags system is provided:
 

array_var Flags

...

let Flags := Ar_List "fast", "doggy", "vaginal"

call fnSexoutActRunFull (Ar_Map "ActorA"::TheKingREF, "ActorB"::PlayerREF, "Flags"::Flags)

The above will makes The King bone the player, using a random animation approprate for 'fast doggy style vaginal'.

Other flag examples include: "oral", "anal", "blow" (blow job), "eat" (cunnilingus), "rape", "miss" (missionary), "cowgirl", "69", "kiss", "handjob", "oyster", "bend", "acrobatic", "stand", "kneel", "lay", "squat", "fist", "spitroast", "dp", and more- take a peak into the scripts 'fnSexoutAddInternalAnimsA-H' for more examples.

# Specific Animations

Sometimes, you have a specific animation in mind:
 

call fnSexoutActRunFull (Ar_Map "ActorA"::TheKingREF, "ActorB"::PlayerREF, "Plugin"::"Sexout-Amra.esp", "Anim"::401)

The above will player sexout-Amra's animation #401 for the King and the player. Appropriate sex type will be set automatically. If you leave the "Plugin" option blank it will default to "Sexout.esm".

Sexout validates calls like this, and will fall back to the random picker if your options are impossible (for example, because 'Sexout-Amra.esp' is not loaded, does not have an anim #401, or the actors don't match those required for it).

# Validating Actors

If you attempt to start sex with actors that are not valid, it will fail- this is harmless as far as sexout is concerned, but probably not for your plans, especially if you are using callbacks.

To check if an actor is already sexout in use, use:
 

if eval (call fnSexoutActorInUse ActorREF)

; Wait. ActorREF is already having sex, so any call will fail

else

; Safe to proceed, make your sexout call

endif
 

# Legacy Interfaces

You may notice that many plugins do not use the ActRunFull interface described thus far. This is likely because they were created before this interface existed.

Sexout includes 3 legacy interfaces that are functional, but support less features and are less reliable. Options have the same name across all interfaces.

- Multi UDF (call fnSexoutActPrep, callfnSexoutActSetRef "actorA", ActorREF....). This does not support setting flags or plugins.
- Classic (quest) interface. This doesn't support much and is unreliable. (Before my time, I don't even know how to use default_wink.png -Odessa). Don't use it.
- NX, this interface supports setting plugins but not flags. It is convenient for in game testing via the console, but otherwise redundant.

 

ActorREF.NX_SetEVFl "Sexout:Start::CallVer", 1
ActorREF.NX_SetEVFo "Sexout:Start::ActorA", PlayerREF
ActorREF.NX_SetEVFo "Sexout:Start::ActorB", SunnyREF
ActorREF.NX_SetEVSt "Sexout:Start::Plugin", "ZAZ"
ActorREF.NX_SetEVFl "Sexout:Start::Anim", 301
ActorREF.CIOS SexoutNGBegin

----

The new UDF interfaces are completely immune to interference by other scripts, even in your own mod, if it is used correctly.  The classic and NX interfaces are more prone to errors arising from different scripts trying to use the same actors.  The NX interface can fail or misbehave if two different scripts simultaneously attempt to use the same actor as the target, since they will both be setting NX vars on that actor, with the second one to run overwriting the first one.

The classic interface is even worse, since it uses the shared sexout quest (two of them, actually).

Please use the fnSexoutActRunFull udf interface for all new acts, and convert old acts whenever possible.  Every quest variable and NX variable pertaining to starting an act is available in every interface, for the most part.  For example, "Sexout:Start::CBDialogA" is available in the udf interface as simply "CBDialogA", just like actorA and actorB in the example above.

See the variables section for documentation on what other variables can be set when starting an act.

The UDF interfaces uses the formid of the calling script as a key.  The multi UDF interface has an extra rule, that the Prep, Sets, and Run (or Reset) must all be issued by the same script.  You should NOT just prep an act and wait around, but doing so shouldn't cause much harm -- this functionality is there to avoid collisions with other mods (and other scripts in your own mod), not to help lazy modders.

## A note on actors
Sexout provides support for up to four actors; Actors A - C, and actor X.  When setting up acts, use unique actors in every slot.  In a single act, sexout will automatically remove any duplicate actors it finds before starting the act, preferring to keep A, then B, then C.  For multiple simultaneous acts, only the first one will function; the second will fail if it uses any actors already assigned to the first.

## A note on dialog callbacks
It is popular in existing mods to use dialog result scripts to start new acts.  This works, but its use is discouraged, due to the problems it causes and fragile workarounds built into sexout.

A better solution is to start the acts in your own spell or script, and use the dialog callback to control variables (or quest stages) that your script is watching.

# Advanced Features
More complex mods will want to do more than simply start a random act between two actors.  Sexout providers for this, allowing the calling mod to do everything from choose the sextype and animation itself, to being notified when the act has started or completed, to giving packages, starting conversations, or casting spells on particular actors after the act is finished.

## A note on sexout formlists
Sexout provides many formlists for modders to use.  Some it populates itself, others it relies on mods to populate.  Throughout this document, when I refer to a formlist within the Sexout ESM, it is important that it is never edited in the GECK.  If you need to add or remove items from it, do it from a script, to avoid directly modifying the sexout records -- since modifying the records will at best introduce load order issues, and at worst completely screw up sexout.

## Global Notification
Sexout can notify your mod whenever an act starts or is completed.  It does this by casting a mod-provided spell on the player.  For additional details, such as who the actors involved were, your mod can also provide a formlist which sexout will populate with actors.  Here are the formlists provided by sexout, which you can add your own formlists and spells to.

| List | Contains | What it does |
| ---- | -------- | ------------ |
| SexoutNGFLGlobalCBStartS  | Spells | Every spell here is cast on "actor b" when a new sexact starts |
| SexoutNGFLGlobalStartFLA  | formlist | The actors involved doing anal penetration.  A for Anal. |
| SexoutNGFLGlobalStartFLO  | formlist | The actors involved doing oral penetration.  O for Oral. |
| SexoutNGFLGlobalStartFLV  | formlist | The actors involved doing vaginal penetration.  V for Vaginal. |

The above four lists also have an post-sex version; simply replace "Start" in the list name with "End".

It is important that in your spell script, you clear the formlists you provided to sexout.  Sexout does not do this for you, so if the formlists are not empty the next time it casts your notification spell, the lists will contain actors from the previous act as well as the new act.

## Per-call post-act hooks
For each actor involved in an act, sexout allows for several per-act callbacks that you can provide, for a total of 16.  These callbacks are:

| Name | Contains | What it does |
| ---- | -------- | ------------ |
| CBDialogA | A reference to a dialog topic | Starts the given conversation between the player. |
| CBSpellA  | A spell | Casts the given spell on actor A |
| CBPackA   | A package | Adds the script package to actor A |
| CBItemA   | An Item | Adds the given item to actor As inventory |
| refMoveATo | A reference | Moves actorA to the specified ref |

All of these tasks are done when the act completes, and the trailing letter can be either A, B, C or X for the given actor.

ActorX is a special case.  This actor is not undressed or involved in the animation, but can be involved in these callbacks.  An example use is to set A and B to two NPCs such as Boone and Cass, and X to a third NPC such as Veronica, and CBDialogX to one of Veronicas conversation topics.  When the sex act between Boone and Cass completes, the conversation between Veronica and the player will be started.  Use your imagination.

## The scanner
The scanner works identically to the global notifications, but with only two lists involved.  SexoutScannerListS is the sexout formlist you add your spell to, and SexoutScannerListN is the sexout formlist you add your own formlist to.  Every time the scanner runs, it populates all lists, and then casts all spells.

You do not need to provide both.  If you provide only the spell but no formlist, you will be notified when the scanner runs, but not what it found.  If you provide only the formlist and not the spell, sexout will update the formlist, but not notify you that it has done so.  As with the notifications, it is important that you clear your scanner list out yourself once you've gone through it.  If you don't, it will accumulate every actor the player has encountered, ever.

# API specification
The above information should be enough to get you started.  What follows is a (hopefully) complete list of the API features.  Once you've mastered the basics, you'll find using these additional features to be fairly easy and self explanatory.

## per-Act settings
These are the act variables that can be set via the appropriate UDF, or as NX vars in the NX interface.  The NX "Sexout:Start::" prefix is left off for brevity, and is not needed in the UDF interface

| Name | Type | Purpose |
| ---- | ---- | ------- |
| actor{?} | Ref | The four actor vars.  ActorA - ActorC, ActorX |
| flags | array | This is a regular (Ar_List) array containing all flags describing desired act |
| plugin | String | The plugin to choose the animation from, eg: 'ZAZ' or 'Sexout-Amra.esp' |
| anim | int | Set this to specify a particular animation # rather than using the sexout random picker. |
| bDontUndress{?} | int | Set to 1 to indicate, for this act, sexout should not undress actor ? (A, B, C) no matter the MCM settings |
| bDontRedress{?} | int | Set to 1 to indicate, for this act, sexout should not redress actor ? (A, B, C) no matter the MCM settings |
| CBDialog{?} | ref | Start the referenced dialog between actor ? (A, B, C, X) and player, after sex |
| CBItem{?} | ref | Give the referenced item to actor ? (A, B, C, X) after sex |
| CBPack{?} | ref | Put the specified package on actor ? (A, B, C, X) after sex |
| CBSpell{?} | ref | Cast the referenced spell on actor ? (A, B, C, X) after sex |
| CBItem{?} | ref | Give the referenced item to actor ? (A, B, C, X) after sex |
| noAnim | int | Set to 1 to have sexout do all normal things (callbacks, counters, etc) but not un/redress actors or play an animation. |
| raper | ref | Set to one of the involved actors to indicate they are a rapist in the act.  Affects counters and sounds. |
| refSurface | ref | A surface, such as a bed, to perform the sex act on. |
| fSurfaceX | float | The X offset to use with the surface. |
| fSurfaceY | float | The Y offset to use with the surface. |
| fSurfaceZ | float | The Z offset to use with the surface. |
| sextype | int | (Legacy, use flags) Set this to specify a sex type (anal, oral, vaginal). |
| isAnal | int | (Legacy, use flags) Set to 1 to indicate the act has an 'anal component' |
| isOral | int | (Legacy, use flags) Set to 1 to indicate the act has an 'oral component' |
| isVaginal | int | (Legacy, use flags) Set to 1 to indicate the act has an 'vaginal component' |
| nUseZAZ | int | (Legacy, use "plugin"::"ZAZ") Set to 1 to indicate the act should use the ZAZ. |

## Formlists
In addition to the notification formlists, several other formlists are provided for mods to modify through scripts.

| Name | Contains | Purpose |
| ---- | -------- | ------- |
| SexoutBannedActorsWithPlayer       | actor refs | Sexout will not allow sex between the player and these actors.  |
| SexoutBannedActorsWithCompanions   | actor refs | Sexout will not allow sex between companions and these actors. |
| SexoutListBannedActor              | actor refs | Sexout will not allow sex between anyone and these actors. |
| SexoutNGListBi                     | actor refs | Known bisexual actors can be added to this list. |
| SexoutNGListGay                    | actor refs | Known gay actors can be added to this list. |
| SexoutNGListStraight               | actor refs | Known straight actors can be added to this list. |
| SexoutNGNudeBodies                 | armor and clothing refs | Items that when worn should be treated as nude. |
| SexoutNGSafeClothes                | armor and clothing refs | Unisex items that do not need to be removed for sex, like crotchless things. |
| SexoutNGSafeClothesF               | armor and clothing refs | Female items that do not need to be removed for sex, like crotchless things. |
| SexoutNGSafeClothesM               | armor and clothing refs | Male items that do not need to be removed for sex, like crotchless things. |

## UDFs
Sexout provides many features via UDFs since version 84.

| Name | Args | Purpose |
| ---- | ---- | ------- |
| fnSexoutActorInuse | ref:actor | Returns 1 if the actor reference is currently in use by sexout, 0 if not or if invalid |
| fnSexoutActorValid | ref:actor | Returns 1 if the actor reference is valid, -1 if not a ref, -2 if not an actor, -3 if dead, -4 or -5 if a child. |
| fnSexoutActPrep | none | Preps a new act to be run.  After calling this you must can fnSexoutActRun or fnSexoutActReset before calling it again from the same script. |
| fnSexoutActSetFloat | string:name float:val | Sets the named float param to the given value for the currently prepped act. |
| fnSexoutActSetRef | string:name ref:val | Sets the named ref param to the given value for the currently prepped act. |
| fnSexoutActSetInt | string:name int:val | Sets the named int param to the given value for the currently prepped act. |
| fnSexoutActRun | none | Runs the act currently prepped and set by this script. |
| fnSexoutActReset | none | Resets (abandons) the act currently prepped and set by this script, without running it. |
| fnSexoutActRunFull | map:params | Runs an entire act in one shot.  Construct an array in a variable or just use ar_map.  Passing in an integer value such as 0 in place of any actor var will cause the UDF to call Getfelf for you in places where you cannot, like dialog scripts.  Do not use that feature in places where getself would not actually work, such as in a quest script. |

Other UDFs are present in sexout and I may have even mentioned them, but if not documented here, they shouldn't be used without close cooperation with me, as their arguments or functionality may change without notice.

## Spells
This is a list of 'public' spells that modders can use in their mods.  If it's not listed here, do not use it.  It may change how it behaves or even be removed.

| Spell | Function |
| ----- | -------- |
| SexoutBegin   | The classic and NX interface 'start' command.  Superceded by the UDF interface. |
| SexoutNGPause | Pauses the timer on a running animation so it will not expire.  Cast on any actor involved. |
| SexoutNGResume | Resumes a previously paused act.  Cast on any actor involved. |
| SexoutNGFinishNow | Forcibly expires the timer on any running act.  Cast on any actor involved. |

## Read only vars
Sexout maintains many variables intended for modders to read (but not modify) in its quests, and as NX variables assigned either to the player, or to individual actors during a scene.  This list should cover most of them, if not all.

### Quest vars
There are two quests that hold data mods can access.  With the exception of the classic interface vars, all of these should be considered read only.

Any vars not mentioned here should not be used by mods.

| Quest | Variable | Purpose |
| ----- | -------- | ------- |
| Sexout | numRaped | How many times the player has been raped |
| Sexout | numRape | How many times the player has raped others |
| Sexout | numSex | Total number of times player has had sex |
| Sexout | numVaginal | Number of times player has had vaginal sex |
| Sexout | numAnal | ... anal sex |
| Sexout | numOral | ... oral sex |
| Sexout | dfTime | How many seconds long is a default (player set) sex scene |

| Quest | Variable | Purpose |
| ----- | -------- | ------- |
| SexoutNG | bSexoutReady | Resets to 0 on game load or new game, then changes to 1 when sexout is ready to be used |
| SexoutNG | nVerMaj | Sexout major version number, the W in W.X.YbZ |
| SexoutNG | nVerMin | Sexout minor version number, the X in W.X.YbZ |
| SexoutNG | nVerRelN | Sexout release number, the Y in W.X.YbZ |
| SexoutNG | iBetaN | Sexout beta number, if > 0 he Z in W.X.YbZ |

### Global NX vars (on player)
### Per act NX vars

During the lifetime of an act, The NX namespace "Sexout:Started::" exists on each actor involved and contains a great number of variables, including all those set to start the act in the "Sexout:Start::" namespace.  The best way to use these variables is to copy them with a global pre-sex notification hook.  Accessing them in a post-sex hook is unreliable since they are cleared soon after the hooks are called.

A subset of these variables are also set, on each actor, in the "Sexout:Core:" namespace.  These variables remain on the actor until the next time sex involving the actors occurs.  Currently this namespace holds the following variables -- there may be others but they are used internally by sexout and may change names or disappear.

| Variable | Purpose |
| -------- | ------- |
| Sextype:Vaginal | Set to 1 if the act involves vaginal sex. |
| Sextype:Anal    | ... anal ... |
| Sextype:Oral    | ... oral ... |
| Actors:Count   | Number of actors involved in the act |
| Partners:A     | ActorA ref, if present |
| Partners:B     | ActorB ref, if present |
| Partners:C     | ActorC ref, if present |

 

 

 

 

-----

 

@Swyke: You should be able to use flags in dialog scripts, the call looks fine- I would need a debug log to say what happened. Otherwise, all I can think of is that variables can be unreliable in dialog scripts, try:

 

call fnSexoutActRunFull (Ar_Map "ActorA"::0, "ActorB"::PlayerREF "flags"::(Ar_List "kiss"))

To use callbacks, you just include them in the parameters, something like:

 

 

... "CBDialogA"::MyTopic, "CBItemB"::MyItem, "CBSpellC"::MySpell ...




Link to comment
  • 5 years later...
  • 2 months later...

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
  • Recently Browsing   0 members

    • No registered users viewing this page.
×
×
  • Create New...

Important Information

We have placed cookies on your device to help make this website better. You can adjust your cookie settings, otherwise we'll assume you're okay to continue. For more information, see our Privacy Policy & Terms of Use