Jump to content

The Sexoutng Api (How-To For Modders)

Recommended Posts

NOTE by DoctaSax: LoversLab's git went the way of the dodo, so a backup of the latest API is now available for download as a separate file with the stable release of NG.


I'm transitioning this to the gitlab wiki here: http://git.loverslab.com/prideslayer/sexout/wikis/api


This thread can still serve as a Q/A or whatever, but I'm not going to be updating this post any more, and will remove the contents of the spoiler when it starts to get too out of date / incorrect.





vvvvvv NOTICE (28-Jul-2012) vvvvvv

Throughout this document, examples are given using the 'classic' calling convention, using the 'set' command on quest vars in the Sexout and SexoutNG quests. I have not yet updated the document to reflect the new calling convention.


You can, and always will be able to, use either method.


The new calling convention is, however, preferred. The more mods and scenes that use it, the less likely there will be 'races' and other odd behaviors.


Anywhere you see "set Sexout.foo to .." or "set SexoutNG.bar to ..", you can instead use the new calling convention which is 'ref.NX_SetEVF? "Sexout:Start::foo'


For example, when you see "set SexoutNG.duration to 25" you can replace that with 'actor.NX_SetEVFl "Sexout:Start::duration" 25'.

^^^^^^ NOTICE (28-Jul-2012) ^^^^^^


I'm sick of trying to keep documentation up to date in a billion places, keep the links updated and correct in the main thread, and so on. So, here is the up to date documentation for modders on how to use or create a sexout mod.


This is not a general support or how-to thread for modding, or for people having problems using sexout. Posts of that type will result in no response or a gentle rebuke.. unless I have the hulk avatar, which means I'm in a terrible mood and may lash out at the illiterate.


This is not geared towards beginning modders. I am assuming, if you are reading this, that you already know how to make a mod -- how to create quests, items, dialog, scripts, and so on. If you don't yet know how to mod, period, I suggest you read one of the many excellent tutorials on them interwebs.



Like most meta-mods (mods for use by other modders), Sexout's "API" uses a combination of quest variables, spells (aka "actor effects"), and items. Using sexout requires your mod to have Sexout.esm as a master (or extensive use of buildref). Once Sexout.esm is a master, in general, you set some sexout quest variables, and then cast the spell SexoutBegin.


More advanced features are available, such as callbacks which give control back to your script after the animation is done, and global notification hooks which tell you whenever starts and/or stops in the world.


Sexout includes roughly 500 animation files. Some are solo, most are for use with a pair of actors (most human on human, some creature on human), and a few are for threeways. In total there are probably around 200 different sex acts that can be seen.


Basic Use

Basic sexout usage is extremely simple and can be done in three or four lines of code:


The classic interface:



set SexoutNG.actorA to CraigBooneREF
set SexoutNG.actorB to playerREF
playerREF.CIOS SexoutBegin

The now and forever interface:

CraigBooneREF.NX_SetEVFl "Sexout:Start::CallVer" 1
CraigBooneREF.NX_SetEVFo "Sexout:Start::ActorA" CraigBooneREF
CraigBooneREF.NX_SetEVFo "Sexout:Start::ActorB" playerREF
CraigBooneREF.CIOS SexoutBegin

This will cause Boone to have random sex with the player, regardless of gender. The player will be the one getting penetrated (being fucked, getting a blowjob, or being eaten out) while Craig will be the one doing the fucking/eating. This distinction is made by your choice of which actor to use for actorA and which to use for actorB -- actorB is always the one being penetrated, while actorA (and actorC if present) are the ones doing the penetrating. For masturbation, you only need to set a single actor, and it does not matter which one you use.


More variables in the Sexout and SexoutNG quest are available, to give you finer control over the act. Green variables can be set by outside mods, while yellow variables are read only and altering them may break the mod and piss off players.


Sexout.dfTime : The default time for a sex act, in seconds.


Sexout.duration : Set this to alter the duration of the sex act. The player has control over the default duration, so to ensure your custom duration is shorter or longer than average, you should set this to a multiple of Sexout.dfTime, rather than a static value. "set SexoutNG.duration to 0.5 * Sexout.dfTime" for example, to have the act last half as long as the player set value.


SexoutNG.isOral (and isAnal, isVaginal) : Sextype. Set these to 1 to choose one (or several) kinds of sex. This will cause sexout to choose a type at random, but to choose a random animation appropriate to the type. Most often you will only set one of these, but during a three-way (or if a single person is doing double-penetration with a doomsday strapon or something) you might set two or even all three.


SexoutNG.noAnim : Set this to 1 to cause a sex act to happen without playing the animation. This is mainly intended for cases where the modder wants sexout to increment its counters for sex (and possibly give experience, etc.) while not wanting the sex to be seen, such as if the character is passed out, blindfolded, or whatever.


Sexout.raper : If the sex act is rape, rather than consensual, set this to the actor that is the rapist. This causes the rape counters to get adjusted if the player is involved, and also causes different sounds to be played.


SexoutNG.nVerRelN : Sexout version. If your mod requires a specific version of sexout in order to function, you can check the build number by looking at this value. It is always set to the build value (the ZZ in the version XX.YY.ZZ of sexout).


Sexout.num* : Counters. There are 9 at present: Sexout.numRaped, sexout.numRape, and sexout.numSex are the overall counters. The first is how many times the player has been raped, the second is how many times the player has raped someone else, and the last is how many times the player has had sex total. Additionally there are more specific counters; numVaginal, numAnal, numOral, numMale, numFemale, and numMonster.


Sexout.bDoKO* : Enable or disable the cum and knockdown post-sex effects. There are three of these: bDoKORapee, bDoKORapist, and bDoKOCons, and they control just what it sounds like for the rape victim, the rapist, or both/all actors during consensual acts. The default values are set by the player via MCM, these are overrides for specific acts.


Sexout.anim : Allows you to set a specific animation to be used. Must be a valid number. A complete list of values can be found in the GECK under the gameplay menu in "Idle animations" in the group "SexoutNGAnims". These are grouped by position type for human on human sex, or creature type for creature on human sex. For example, SexoutNG2pS1 is the "2 person, set 1" group. The animations themselves are named along with the numbers, such as SNG401, an oral animation. You could use this animation specifically via "set Sexout.anim to 401" -- this bypasses all checks WRT to the sextype set (or not), gender of the actors, number of actors, and the "orifice eligibility" implemented by Jaam. Primarily intended to be used with add-on mods like ZAZ when you want a specific animation type, or when you need the type to match the dialog.


SexoutNG.bDontUndressX : Set to 1 to not undress the specified actor during the act, overrides the players settings in MCM for that act. Replace 'X' with A, B, or C.


SexoutNG.bDontRedressX : Same as above, except prevents the actor from being redressed instead. Only makes sense if bDontUndress is NOT set to 1 -- if you don't undress an actor, then redressing them makes no sense.


All variables MUST be set before the sexout spell is cast, which is done with "(someref).CIOS SexoutBegin".



Intermediate Use

As your mod gets more advanced, you will find cases where you want to force an actor to complete multiple sex acts one after another, perform other actions, initiate dialog with the player, etc. This is accomplished through the SexoutNG callback system. Every actor has four types of callbacks that can be used. These are set via "set SexoutNG.CBTypeActor to (refID)", such as "set SexoutNG.CBDialogA to GREETING" to cause actor A to initiate greeting dialog with the player after the act is finished.


All of these end in a letter, either A, B, or C for one of the involved actors -- or X to use the "shadow actor". The shadow actor is simply a placeholder for cases where you want a 3rd or 4th party who is not involved in this sex animation to perform an action after the animation is complete. This letter is omitted in the following list, just tack it on at the end; e.g. "CBSpell" becomes "CBSpellB" if you want to use it on actorB.


CBDialog : Dialog topic reference. Only valid when the actor is an NPC. Will cause that actor to initiate the specified dialog with the player after sex.


CBSpell : Spell reference. Cast the supplied spell on the specified actor.


CBPack : Script Package. Only valid on NPCs. Add the specified package to the NPC, and run EVP on that actor.


CBItem : Give an item (base item only, uses 'additem') to the indicated actor. Can be used to hand out vanilla type items as rewards, or to hand out 'tokens' -- misc items that may have a script attached that you want to run.


Dialog and Item callbacks are the most commonly used by sexout mods, and Dialogs are probably the easiest, as you can pop into a complicated dialog tree at any point, which may then result in more sex via the scripts attached to the dialog.


Item callbacks are handy to take the place of dialog callbacks when the actor in question is not a human and thus has no dialog topics that can be used.


Spell callbacks are arguably the most powerful, as they can do anything a spell can do. A simple example would be to have the spell simply make another sexout call without fanfare. If you choose this option, becareful that you do not set the spell callback to point back to itself or you'll end up in an endless sex loop, e.g. don't do this in your script for "mySpell" : "set SexoutNG.CBSpellA to mySpell" unless you know what you're doing. A more powerful/complex example would be to have the spell cause a more permanent effect on the player (such as pregnancy or an STD), or to have the spell randomly choose some other side effect from a list.


I don't believe anybody is using the script/ai package callbacks, as packages are just too wonky and unreliable.


Advanced Use

The two more advanced (read: complicated to use) features of SexoutNG are the global notification hooks, and the scanner.


The notification hooks work basically the same way as callbacks, except any mod can subscribe to them, and all mods that subscribe get notified no matter how many of them there are. There are two types of notifications : pre sex and post sex.


Basic use is very simple : Create a spell, and then add that spell (through a script, not through the GECK) to one or both sexout formlists: SexoutNGFLGlobalCBStartS if you want to be notified whenever sex starts (and is in progress), and/or SexoutNGFLGlobalCBEndS if you want to be notified whenever a sex act ends. The spell is cast on actorB. This may be useful for some people, but most people want more, and to that end there are three more formlists for each of the two above.


SexoutNGFLGlobal(start or end)FL(A, O, or V) are formlists where you put a formlist of your own, which sexout will then fill with the specific actor references involved in the act. Actors doing vaginal penetration are in the list ending in V, A is for Anal, and O is for Oral. For example, if your lists are "myListAnal", "myListVaginal" and "myListOral" then a script like this (from your mod or some other mod):

set SexoutNG.ActorA to CraigBooneREF
set SexoutNG.ActorB to PlayerREF
set SexoutNG.isAnal to 1
CraigBooneREF.CIOS SexoutBegin

Will cause Craig Boone to anally fuck the player. Your "myListAnal" will have CraigBooneREF added to it, and your supplied spell will be cast on the player.


It is important when using the global notification hooks that you empty out your formlists in the script for your spell. If you don't, then the next time sexout calls your spell to notify you, you will end up with two (or three, or a dozen) more refs in the list, and you won't know which one(s) are valid for the current act. Note however that you don't have to use the lists at all. If you just want to use the notification hook, that works just fine, though you will only know that sex has started or stopped and not what actors were involved.


The scanner works on the same principle. You put a formlist into SexoutScannerListN, and a spell in SexoutScannerListS. Periodically (up to the player how often, the default is 10Hz / 10 times per second) sexout will run a "scan" on the area, add any NPCs it finds to your formlist, and then cast your spell on the player. Again it is important that whenever your spell is invoked that you empty out your formlist after you've processed it, or it will fill up with every NPC the player goes near.


These two features, global notification hooks and the scanner, are somewhat specialized and easy to use incorrectly. Start small and build up from there until you "get the hang of it." My advice is that the first thing your spell should do in either case is simply print something to the console, like the formlist contents. This will help you make sure you've added your lists and spells to the sexout lists correctly, and also give you an idea as to how often your spells will be called during gameplay.


This first step will let you quickly build the protections you need into your script before doing something extremely silly, like trying to directly call sexout from inside the scanner without doing some kind of 'lock' -- which would end up casting the sexout spell on the same actors, 10 times a second, for as long as they are nearby. That is pretty certainly not what you actually want your spell to do.



As of release 84, sexout has some built in UDFs that other mods should be using rather than whatever internal 'stuff' they are using now. At present, these are:


int fnSexoutActorInuse(ref) -- Given a reference, will return:

0 - Actor not in use by sexout

1 - Actor in use by sexout

2 - Reference invalid

3 - Reference not an actor



Link to comment
  • 1 month later...

I've updated the OP to explain, briefly, how to use the new interface as of 2.5.68, along with a notice. I will explain in more detail as I have time, but it's pretty well hashed over in the NG thread already, so here's a good reason to read the last 15 or so pages of that thread.


The NVSE extender is used now internally within sexout to track the variables used for sex acts. You can even initiate sex by setting these variables, instead of the sexout and sexoutng quest variables. You can continue to use the quest variables for a while longer -- many months, at least. I plan to eventually start throwing deprecated warnings in the console starting with the 3.x branch, and provide (but not guarantee) continued backwards compatibility once we reach 4.x.


The new interface is extremely simple to use. You use NX_SetEVFo to set form values (references), and NX_SetEVFl to set everything else (floats and ints). Every sexout and sexoutNG variable has an analogue among the NX variables, and they are named the same thing. Given any group of statements like this:



set SexoutNG.actorA to Alex

set SexoutNG.actorB to Betty

Alex.cios SexoutBegin



You can do exactly the same thing with this:


Alex.NX_SetEVFl "Sexout:Start::CallVer" 1

Alex.NX_SetEVFo "Sexout:Start::ActorA" Alex

Alex.NX_SetEVFo "Sexout:Start::ActorB" Betty

Alex.CIOS SexoutBegin



That is all there is to it. Anywhere you set a sexout or sexoutng variable, instead set the NX variable in the Sexout:Start:: namespace. The variables in NX are not case sensitive since v9. You MUST set CallVer, and right now, the only valid value is 1, which indicates "calling version 1". If the calling convention changes significantly in the future, to differentiate them and provide backwards compatible support, the version will be raised to 2.


Also note that the actor you set the NX values on MUST BE the actor you also perform the CIOS on. The spell will get everything copied to the other actors. This is normally not a problem -- if you're in a reference oriented script, like a dialog script, you don't need to specify the reference. In existing scripts, you can convert them straight over -- if you are calling the CIOS on a specific actor, be that an NPC or the player, then you must make all the initial NX calls on that same actor.

Link to comment

Dug this up from a post of yours buried in the NG thread:


The "rules":

- All of the NX vars are prefixed with "Sexout:Start::"

- You must set CallVer to 1.

- All variables have the same name as their sexout/sexoutNG counterparts. If you want to "set Sexout.anim to 123", you do that with 'NX_SetEVFl "Sexout:Start::Anim" 123'.

- Make sure you call the right NX function! Use NX_SetEVFo for forms, and use NX_SetEVFl for floats or integers.


This should probably be here too, especially the last bit.

Link to comment

I've been working on a Sexout dependent mod the last few weeks, and hopefully it will be ready for release in the next couple days. I'm new to LLabs, as I usually upload all my files to Nexus. Obviously I'm not gonnna be uploading a Sexout dependent mod there :) So how do I go about uploading a sexout prefixed .esm here?


Do I just make a thread in the sexout forums and attach the files? My mod also contains around 200 sound/lip files. Is there a file size limit for attachments? Probably I'm asking this in the wrong forum, I dunno. Feel free to chastise me or cut off my feet.

Link to comment

Hm, yes, the API thread is for how to mod for Sexout, so this is a little out of place. But I have no use for your feet.


Sharing a mod is done in the "downloads" section of Sexout. If you think it's getting kind of big, you can always upload to some site like mediafire etc & provide a link in your post. Not too sure if there's a hard size limit - people usually just take it upon themselves to spare LL some volume. A courtesy thing, really.

Link to comment

I'm properly chastised for not reading this better, and instead cluttering up your release thread.


I gleaned this from this doc and your main script:


; these three can be set to override in modder scripts

int bDoKORapee

int bDoKORapist

int bDoKOCons


I plan on using those on my dialogue results so I know sex duration better on the user end.

Link to comment

I add/remove equip/unequip items from Cheyennes and/or the players inventory based on when sex ends. Also I don't want Cheyenne doing her random masturbation animations she does in her wait/follow packages during sex. So I need to know the actual time the sex will last.


And yeah I was going to set them not read them.


Edit: Oh also I need to know the time so Mac the Rapist isn't trying to rape Cheyenne, the Player or one of the vanilla followers during Sex. I also like to shut her Sex Gun script down during sex so it can't be used.





Derp, I guess as long as I always check for getknockedstate for Mac and the gun then adding bdoKO stuff is redundant.

Link to comment

I add/remove equip/unequip items from Cheyennes and/or the players inventory based on when sex ends.


Use the callbacks' date=' that's what they are there for.


Also I don't want Cheyenne doing her random masturbation animations she does in her wait/follow packages during sex. So I need to know the actual time the sex will last.


No, you just need to know if it's currently occurring or not. The tokens or inuse flag will tell you this.


Edit: Oh also I need to know the time so Mac the Rapist isn't trying to rape Cheyenne, the Player or one of the vanilla followers during Sex.


I don't really understand this. If any actor is told to have sex with someone who is already having sex, it'll just error out and not happen. You don't have to do anything there.


I also like to shut her Sex Gun script down during sex so it can't be used.


Turn it off at start, callback to turn it back on.

Link to comment

I'm having a bit of trouble using the new calling convention. I usually go by the old one, but I need the new one for something specific. Sad to say, but beth code is all the code I know :blush:


I tried to translate

 set SexoutNG.fSurfaceAngle to SexoutNG.fSurfaceAngle + 180 

but what I came up with

 player.NX_SetEVFl "Sexout:Start::fSurfaceAngle" 180 + player.NX_GetEVFl "Sexout:Start::fSurfaceAngle" 

definitely doesn't work, and adding brackets doesn't make a difference, so I went the roundabout way by declaring a new var:

set fNewAngle to player.NX_GetEVFl "Sexout:Start::fSurfaceAngle"
player.NX_SetEVFl "Sexout:Start::fSurfaceAngle" fNewAngle 


Obviously I was doing somethin' stupid because I don't know the basics of the lingo, but how do you go about setting & getting in the same line without that detour?

Link to comment

You need the detour unfortunately. Gamebryo, for whatever reason, often does not allow an rvalue to be a return from a function -- basic expressions only. :/ I don't know what particular things fall under that rule, but it looks like this is one of them, and it's not the first time I've seen it.

Link to comment

Yeah it should probably be -1. I may have said 0 at some point a long time ago. Either way will work, but if it's the first one to get added then it'll just keep adding it over and over (well trying to, it'll only appear in the list once).


EdiT: If it's all in a getgamerestarted/loaded blcok then it doesn't matter.

Link to comment

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