Jump to content
Locuturus

[Starbound] Modding Guide: Add Support to Sexbound API for Custom Species.

Recommended Posts

There are hundreds - if not thousands - of custom species in the Starbound universe, and it will be impossible for any one person to provide support for all of them. Players and creators may choose to take it upon themselves to provide support for their favorite custom species. This modding guide will serve as a walk-through for adding support for most custom species.

1 ) Download the Template
 
1.1 ) You will need to download the following mod template before you get started:

 

Important: The template files have been updated for Sexbound API v2.6 and up.

 

☑ Download: Custom Species Template

 

1.2 ) Download the artwork for all vanilla species (Optional):
 
☑ Download: All Artwork (Actor 1 and Actor 2)

 

1.3) Download the Sexbound Dialog Tools (Optional):

 

☑ Download: Sexbound Dialog Tools

 
2 ) Extract the Template Files into an Appropriately Named Folder.
 
2.1 ) Rename the template folder.
 
☑ You may choose to use the following naming convention for the root folder name: SexboundAPI_<SpeciesName>
 
For example, SexboundAPI_Human is good name to use for the Human species.
 
The folder should contain the following files and folders: artwork (Folder), dialog (Folder), positions (folder), sexbound.config.patch (File), _metadata (File), and changelog.txt (File).
 
3 ) Unpack the Custom Species .Pak File.
 
☑ For the species that you want to provide support. If the original custom species is provided as a .pak file then you must use the Starbound modding tools to unpack it.
 
The Starbound modding tools are automatically installed with the 32-bit version of Starbound, and you may find them located in the 'win32' folder which is located in the same folder as 'mods'.
 
In the 'win32' folder, you must use the asset_unpacker.exe file to unpack the contents of your chosen species' .pak file. Furthermore, this step requires that you have knowledge of using the Windows command prompt.
 
4 ) Determine the Correct Species Kind.
 
4.1 )  Locate the custom species' .species file.
 
☑ Navigate the unpacked files of the custom species, and you will navigate into the 'species' folder. You should see a .species file in this folder.
 
4.2 ) Open the .species file, in notepad or another text editor program.
 
4.3 )  Note the value of "kind".
 
☑ Read the JSON configuration, you must find the correct value of 'kind'. You must note the value for kind, and you must ensure to preserve any capitalization.
 
For example, the Human species has a kind value of "human". Please, notice that the kind value is in all lower-case letters.
 
5 ) Use the Kind Value (Aka. Species Name) to Replace the Text in all of the Following Template Locations.
 
5.1 ) In the _metadata file:
 
☑ Replace all [replace with species name] tags with the value of kind.
 
☑ Replace the [author_name] tag with your name too.
 
5.2 ) In the /sexbound.config.patch file:
 
☑ Replace all [replace_me_with_species_name] placeholder tags with the value of kind.
 
5.3 ) In the following folder location - /artwork/humanoid/actor1:
 
☑ Rename the '[replace_me_with_species_name]' folder to be the value of kind.
 
5.4 ) In the following folder location - /artwork/humanoid/actor2:
 
☑ Rename the '[replace_me_with_species_name]' folder to be the value of kind.

 

5.5) In the following folder location - /dialog/sexbound/en:

 

☑ Navigate inside of each position name folder (I.e. butterfly, cowgirl, etc..)

 

☑ Rename each file by replacing [replace_me_with_species_name] placeholder tag with the value of kind.

 

5.6) In the following folder location - /positions

 

☑ Open each patch file.

 

☑ Replace all [replace_me_with_species_name] placeholder tags with the value of kind.
 
6 ) Edit All Sprite Sheets to Resemble the Custom Species.
 
There are two different sets of sprite sheets, actor1 and actor2:
 
6.1 ) Edit the sprite sheets for both actor 1 and actor 2.
 
☑ You must use a sprite editor program to edit all of the sprite sheets to match the design of the custom species. You may simply choose to use Microsoft Paint.
 
Actor1 sprite sheets are in the following location:

 

/artwork/humanoid/actor1/<kind>

 

 
Actor2 sprite sheets are in the following location:
 

/artwork/humanoid/actor2/<kind>

 
Note: In the unpacked custom species files, you may find the original sprite sheets stored somewhere in the humanoid directory. You must use the exact same color palette used in the original custom species sprites.
 
7 ) Patch each unique NPC Type and Tenant to be Sex Enabled.
 
This step is may be difficult to write a explanation, but I will give it a try. 
 
7.1 ) Create a patch file for each unique NPC and tenant in the 'npcs' folder.
 
☑ You'll have to research which NPCs need to be patched because some will already be patched by SexboundAPI. Sometimes the configuration in the NPCType file may have a baseType, so you may choose to only patch that specified file that matches the baseType value. You'll have to hunt for that baseType file in the custom species 'npcs' folder, and if it is not in there then be sure to check the below list of default NPCTypes (aka baseType).
 
Note: SexboundAPI already patches any NPC that has a baseType of 'base', or 'merchant'. So, you shouldn't have to worry about creating a patch file for an NPC that inherits one of those two baseTypes. Always research a baseType before patching it because many baseType actually inherit from 'base'. For example, baseType 'guard' already inherits from the 'base' npctype, so you don't need to create a patch for an .npctype with baseType 'guard'. Please see the below list of NPCType (aka. baseType) that you should not need to create a patch:

 

NPCTypes / BaseTypes (Defaults)

 

 

 

airshipcaptain
airshipguard
airshipquartermaster
alpaca
alpacatenant
alpacavisitor
apexabovegroundscout
apexrebel
apexrebelvillager
apexresearchlab
apexscientist
apexscout
arenaadvisor1
arenaadvisor2
arenaadvisor3
arenabruiser
arenafighter
arenahunter
arenapyro
arenashooter
astrocrewmate
astromerchant
astronaut
astrotenant
avianairship
avianraider
aviantomb
backervisitor
bandit
baron
baronoutpost
bartender
base
blacksmith
bones
bonewildling
cabin
castlearcher
castlelord
chefmerchant
chefmerchanttenant
clanleader
colourful
colourfulvisitor
creepling
crewmember
crewmemberchemist
crewmemberchemistblue
crewmemberchemistgreen
crewmemberchemistorange
crewmemberchemistyellow
crewmemberengineer
crewmemberjanitor
crewmembermechanic
crewmembermedic
crewmemberoutlaw
crewmemberpenguin
crewmemberpenguinmerc
crewmembertailor
cultist
cultistarcher
cultistinvader
cultistknight
deadbeatbruiser
deadbeatscrounger
deadbeatthug
desertvillager
devabi
devadam
devdonna
devdoris
devgeorge
devharriet
devjay
devkyren
devlili
devmeta
devmolly
devoutvillageguard
devoutvillager
devrosie
devstephen
devtiy
devtom
devtomkat
devwilliam
divingscavenger
electrician
electricianvisitor
electronicgoodstrader
esther
evilglitchtenant
evilknight
evilknightlord
executioner
eyeguard
eyeknightvisitor
eyepatch
farm
feneroxguard
feneroxtenant
feneroxvillager
feneroxvisitor
flesh
florancannibal
florancelebrator
floranchieftain
florangladiator
floranhuntinggrounds
floranpredator
floransniper
floranspectator
follower
foodgoodstrader
foragervisitor
forestvillager
foundry
foundryguard
foundryvisitor
foundryworker
friendlycastleguard
friendlycastlelord
friendlycultist
friendlyguard
friendlyguardtenant
friendlyroyalguard
froggvisitor
frogmerchant
frogtenantmerchant
frogvillager
generictenant
geode
giantflower
glitcharcher
glitchcastle
glitchsewer
glitchthief
glow
gothic
greenfinger
guard
guardornate
guardplant
hazmat
hazmatscientist
hazmatvisitor
hiredguard
hive
hostile
humanbunker
humanprison
industrialcrewmate
industrialmerchant
industrialtenant
inventorvisitor
island
koichi
koichihologram
koichioutpost
labscientist
lana
lanafight
lanaoutpost
letheiamerchant
lunarbase
maggotmanvisitor
maskedguard
medicalgoodstrader
merchant
merchanttenant
militarygoodstrader
miner
minersurvivor
miniknogagent
miniknogassassin
miniknoggeneral
miniknogscout
miniknogvillageguard
museumapexvisitor
museumavianvisitor
museumfloranvisitor
museumglitchvisitor
museumhumanvisitor
mutantminer
nakedvillager
neon
novakidblacksmith
nuru
nurufight
nuruoutpost
oasis
outlawbandit
outlawbarbarian
outlawknight
outlawsamurai
outlawsoldier
outpostapexmechanic
outpostapexrefugee
outpostapexscientist
outpostaugmentmerchant
outpostavianexplorer
outpostavianmercenary
outpostavianrefugee
outpostbountyhunter
outpostcivilian
outpostfloranexplorer
outpostfloranfan
outpostfloranhunter
outpostglitchmechanic
outpostglitchmercenary
outpostglitchsilenttype
outposthumanexcon
outposthumanscientist
outposthumansurvivor
outposthylotlcurator
outposthylotlperformer
outposthylotlwarrior
outpostpenguinpromoter
outpostpenguinscientist
outpostundersideman
outpostvisitor
pastel
penguinscientist
penguinshipcrewmate
philanthropist
piratevisitor
poptopfarmer
prism
prisonberserker
prisonbruiser
prisongunman
prisonoutlaw
protectoratecourtyardlounger
protectoratehallstaff
protectoratehallstudent1
protectoratehallstudent2
protectoratehallstudent3
protectoratehallstudent4
protectoratehallstudent5
protectoratejanitor
protectoratelobbylounger
protectoratelobbystudent1
protectoratelobbystudent2
rebelvisitor
researchcrewmate
researchscientist
retroscifi
roguesamurai
saloon
samuraivisitor
santa
savannahchampion
savannahguard
savannahvillager
scientist
scorched
sea
seedmerchant
shadowvillager
shroomguard
shroommerchant
shroommerchanttenant
snowscientist
snowvillager
socialite
socialitevisitor
spaceengineer
spaceguardtenant
spacehero
spacemerchant
spacepioneer
spacevillager
spooky
spring
stargazer
stationtenant
steampunk
steamspring
survivor
tar
templeguard
tombguard
tonauac
tonauacoutpost
transpondervendor
tutorial
tutorialtenant
undergroundvillager
vaultkeytrader
villageguard
villageguardcaptain
villager
wanderingmerchant
wildhunter
wildhunterveteran
wizardmerchant
wizardvisitor


If you need to create a patch for a unique .npctype in your custom species support mod, then the filename must match the file name of the file which you are patching. Furthermore, the filename must end in .npctype.patch. Example:
 
File Name: comfortertenant.npctype.patch
 
You must ensure that the patch file is stored in the exact same folder location. So, if you are patching an .npctype file in the following location: /npcs/tenants then you must place the .npctype.patch file in the exact same folder location in your support mod.
 
7.2 ) You must put this exact code in each of your NPCType patch files.

[
  {
    "op" : "add",
    "path" : "/scripts/-",
    "value" : "/scripts/sexbound/override/npc.lua"
  }
]

8 ) Create Dialog Files (Optional)

 

8.1 ) Choose whether to create custom dialog or not.

 

☑ If you don't want to create custom dialog for your species support mod, then delete both the dialog and positions folder out of your template.

 

8.2 ) Choose between editing the dialog config files directly, or choose to use Microsoft Excel.

 

☑ Choose to use Microsoft Excel.

 

☑ Open the sexbound-dialog-template.xlsx

 

☑ Switch to the Species List spreadsheet.

 

☑ Change Column A - Line 11 "custom" to be the species name.

 

☑ Switch back the Dialog Editor spreadsheet.

 

8.3 ) Create a new line of dialog.

 

☑ Click each cell to receive an options dropdown menu, then choose your preferred option. In each row, every cell must have a value.

 

8.3.a ) Role (A.K.A. Actor's Role)

 

The role of the actor who speaks this dialog entry.

 

Valid options: 1 or 2

 

8.3.b ) Status

 

The status that corresponds with the actor in the chose role.

 

Valid options: default, climaxing, or pregnant

 

8.3.c ) Other Species

 

If you set the Actor Role to 1, then this is species of Actor 2. Otherwise, this is the species of Actor 1. 'default' is actually recognized as any species.

 

Valid options: default, apex, avian, fenerox, floran, glitch, human, hylotl, novakid, or (custom)

 

8.3.d ) Other Gender

 

If you set the Actor Role to 1, then this is gender of Actor 2. Otherwise, this is the gender of Actor 1. 'default' is actually recognized as any gender.

 

Valid options: default, male, or female

 

8.3.e ) Other Status

 

If you set the Actor Role to 1, then this is status of Actor 2. Otherwise, this is the status of Actor 1. 'default' is actually recognized as any status.

 

Valid options: default, climaxing, or pregnant

 

8.3.f ) Dialog Text

 

The dialog string that is spoken by the actor in the chosen role.

 

Valid entry: A string of text.

 

8.4 ) Export the spreadsheet as a .csv file.

 

☑ Exported spreadsheet as a CSV file.

 

8.5 ) Convert the exported CSV file into a dialog config file

 

☑ Drag 'n' drop the exported .csv file on to the included DialogCSVToConfigConvertor.exe tool, then a .config file will be outputted into the same folder as the exe.

 

8.6 ) Copy the contents of this file into your chosen position dialog file.

 

☑ You may choose to overwrite the already existing .config file in the /dialog/sexbound/en/<position> folder. Ensure that your file uses the proper naming convention too.

 

Or

 

☑ you may choose to open the converted .config file in notepad and copy-paste its contents into the corresponding dialog template file.

 

9) Test Your New Species Support Mod.
 
9.1 ) Ensure that Sexbound API can correctly display the correct animations for your custom species.
 

☑ Tested successfully.


10 ) Distribute Your Custom Species Support Mod.
 
10.1 ) Pack your mod for distribution (Optional).
 
☑ In the 'win32' folder, you must use the asset_packer.exe file to pack the contents of your custom species support mod.
 
10.2 ) Archive the file and make it available for download.

Share this post


Link to post

Great stuff, the tutorials simple and easy to follow, and it works great!

 

However, is there some additional steps we need for races that use the facial mask? I've been trying to set up support a couple of custom races that use them, and they load fine except they're missing the facial mask.

Share this post


Link to post
Guest

Great stuff, the tutorials simple and easy to follow, and it works great!

 

However, is there some additional steps we need for races that use the facial mask? I've been trying to set up support a couple of custom races that use them, and they load fine except they're missing the facial mask.

 

There should not have been additional steps for facial masks, facial hair, emotes, or hair. What custom species are you creating? I may have to change the code to automatically find the facial masks.

Share this post


Link to post
Guest

I'm attempting to add support for this race https://community.playstarbound.com/resources/demon-race-2017.5014/ . I also tested it with the Carodonts  from https://community.playstarbound.com/resources/super-sbg-race-mod.2858/ to see if it was just the mod in particular and had the same issue of the facial mask not appearing.

 

Could you please package and send the deman race mod to me via PM? I will use it to test the code that I am changing.

Share this post


Link to post
Guest

 

 

I'm attempting to add support for this race https://community.playstarbound.com/resources/demon-race-2017.5014/ . I also tested it with the Carodonts  from https://community.playstarbound.com/resources/super-sbg-race-mod.2858/ to see if it was just the mod in particular and had the same issue of the facial mask not appearing.

 

Could you please package and send the deman race mod to me via PM? I will use it to test the code that I am changing.

 

 

 I already have a support ready for the ningen race, How do I upload it?

 

 

You'll need to click the Downloads button at the top of the page, then there will be an Upload File button at the top of the next page.

 

http://www.loverslab.com/index.php?app=downloads&module=post&section=submit&c=

 

I've been putting mods for Starbound in the "Other > Adult Mods" category, but hopefully Starbound will get its own category in the future.

Share this post


Link to post

Out of curiosity for the viera race i'm currently on. Since it haves 5 folders and .species files. Does that mean i'll have to add all 5 in METADATA file?

 

Share this post


Link to post
Guest

Out of curiosity for the viera race i'm currently on. Since it haves 5 folders and .species files. Does that mean i'll have to add all 5 in METADATA file?

 

Nah, just one. I think Viera is the name for the collective species, so that should be good. 

Share this post


Link to post

 

Out of curiosity for the viera race i'm currently on. Since it haves 5 folders and .species files. Does that mean i'll have to add all 5 in METADATA file?

 

Nah, just one. I think Viera is the name for the collective species, so that should be good. 

 

 

I did everything but i still keep getting obstructed in it. Every time i shoot a arrow at one of them. :l

Share this post


Link to post
Guest

 

 

Out of curiosity for the viera race i'm currently on. Since it haves 5 folders and .species files. Does that mean i'll have to add all 5 in METADATA file?

 

Nah, just one. I think Viera is the name for the collective species, so that should be good. 

 

 

I did everything but i still keep getting obstructed in it. Every time i shoot a arrow at one of them. :l

 

 

Are they tenants? 

 

Edit: The custom species modding tutorial has been updated to explain how to patch any custom npctypes which may not be SexEnabled.

Share this post


Link to post

Any plans to work at Avali or the slime race? Both are pretty high up there in species used,with avali actually being the top species mod iirc. 

Share this post


Link to post
Guest

 

ok, so i'm not all that great with sprite and scriptwork, so... if anyone wants to make a compatibility patch for my Umbreon race (https://community.playstarbound.com/resources/umbreon-race.3557/ here) feel free to do so!

 

Already working on it. having a slight error

 

 

 

Is there an error in the Starbound.log file? I've recently changed the tutorial because the /scripts/sexbound/default.config file was moved into the root folder. The patch file is now placed in the root folder, and it should be called sexbound.config.patch

Share this post


Link to post

 

 

ok, so i'm not all that great with sprite and scriptwork, so... if anyone wants to make a compatibility patch for my Umbreon race (https://community.playstarbound.com/resources/umbreon-race.3557/ here) feel free to do so!

 

Already working on it. having a slight error

 

 

 

Is there an error in the Starbound.log file? I've recently changed the tutorial because the /scripts/sexbound/default.config file was moved into the root folder. The patch file is now placed in the root folder, and it should be called sexbound.config.patch

 

 

don't worry. i fixed it. i already uploaded it.

here's the link: http://www.loverslab.com/files/file/4661-umbreon-race-patch-for-sexbound-api/

Share this post


Link to post

 

 

 

ok, so i'm not all that great with sprite and scriptwork, so... if anyone wants to make a compatibility patch for my Umbreon race (https://community.playstarbound.com/resources/umbreon-race.3557/ here) feel free to do so!

Already working on it. having a slight error

 

Is there an error in the Starbound.log file? I've recently changed the tutorial because the /scripts/sexbound/default.config file was moved into the root folder. The patch file is now placed in the root folder, and it should be called sexbound.config.patch

don't worry. i fixed it. i already uploaded it.

here's the link: http://www.loverslab.com/files/file/4661-umbreon-race-patch-for-sexbound-api/

Did some testing to be sure. It works perfectly, thank you! Now I just need to fund some help making furniture and tiles for the race so people can reliably spawn Umbreon tennants, lol.

Share this post


Link to post

edit: also the unpacked custom species im making has like...3 different kinds. inside theres simply Viera.species, then theres also femalefeolviera and femaleveenaravaviera (and the male vers of them). yet they all use the exact same sprites for body it seems like.

 

See now, heres something i dont quite get...

Im working on adding support for a race i use alot, but...

Isn't there an option to change skin color and such when making a new character?

yet the template is only one color...?

 

Perhaps im just trippin / new at modding, but that doesnt add up to me x3

Share this post


Link to post
7 minutes ago, Dag42568 said:

It has been a long time since Loxodon replied, i'm getting worried(?)

prob just busy.

Share this post


Link to post

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...