Public Betabound documentation for modders by silversokolova on Discord
tinyurl.com/betadocs

(Notes to self: codeblock theme is Arta, file font is Consolas)

Table of Contents

Music Sheets (Portable/Stationary Radio)

Adding and Obtaining Music Sheets

Customizing Music Sheets

Default Tracks (Portable/Stationary Radio)

Suit Techs

Making a Suit Tech

Obtaining a Suit Tech

Adding a Recipe

Plates

Ability Modifier Items

Poisoncreep Immunity (for aquatic/robotic races)

Music Sheets (Portable/Stationary Radio)

Music sheets are obtainable items in Betabound which can be found as loot. When the player obtains a music sheet, they can listen to the track on that music sheet from a radio, even if they discard the music sheet.

When a music sheet item is created (this includes being ‘recreated,’ such as when the player drops it on the ground, relaunches the game, etc), it will be assigned a track if it does not have one (sheets can be spawned with a predetermined track by setting the music value). If it does not have a track, it will create a list of tracks from /collections/sb_music.collections:collectables, excluding any entries which have the special value set to true. In other words, special tracks will never be randomly selected. So, if you want your song to randomly be found in chests and such, don't make it a special one. To add more tracks, create a file at /collections/sb_music.collections.patch.

Music sheets aren't the only way to add tracks to the radio. Go to Default Tracks (Portable/Stationary Radio) for more information.

Adding and Obtaining Music Sheets

Here's a patch which adds a unique music sheet which unlocks 'Dead or Alive':

Of course, Betabound already has Dead or Alive in its music list, and you probably aren't looking to add a second one, so just replace dead-or-alive in the patch with whatever your song is called.

Here's an example of how to spawn a music sheet which unlocks Dead or Alive. Once in your inventory, the song will automatically be unlocked. Also, if you're in admin mode, the radio will grant you temporary access to all songs.

If your song isn't special, you can stop here. Congrats! You've added a new song to the pool. You can also add it to treasure pools, shops, or as a recipe by specifying the 'music' parameter, just like in the spawnitem command. Here's what you need in order to do so– just paste it into your treasure pool or recipe file and you're good to go! (Not really– you actually need the rest of the treasure pool or recipe file. This is just the music sheet part.)

Customizing Music Sheets

Since all music sheets are the same item with different values, you might be wondering how you can customize them. Maybe you want a CD icon for your track instead of a sheet of paper, or maybe you'd like it to be more expensive than the default price. By making a file at /collections/sb_music.config.patch, you can specify parameters for specifc tracks. These parameters will be used for the music sheet item. The below patch will visually turn every 'Dead or Alive' music sheet into a compact disc, increase the price to 9999, and change the description to reference the fact that it is now a disc.

Default Tracks (Portable/Stationary Radio)

Music sheets aren't the only way to add tracks to the radio. You can add default tracks which, as their name suggests, are available by default and do not need to be unlocked. To get started, make a file at /interface/scripted/sb_music/music.config.patch and paste the following template in:

The track will then be available at a radio, and since it doesn't need to be unlocked, it won't have a music sheet item.

Suit Techs

Betabound adds a new type of equipable tech. They use tech files and apply status effects to the player, just like armor. This section will explain how to make a suit tech, how to add it to the list of techs that are randomly selected when an sb_tech item is created, and how to add a Tech Development Console recipe for it.

Making a Suit Tech

Optional UI Parameters

There also exist optional parameters which affect how the player sees the tech in menus such as the tech selection UI and their inventory.

Obtaining a Suit Tech

Suit techs cannot be unlocked with tech unlock commands. Use this command instead:

However, if you have StarExtensions installed, you can use the `sb_unlocktech` command:

You can also spawn an sb_tech item without parameters. In that case, it will randomly pick a tech from /tech/starbound/tech.config. You can also patch the tech list like so:

This patch will add sb_enhancedhealing to the list of techs that can be randomly found when a tech unlock item is created without a specified tech. If the tech does not exist, it will not be chosen.

Adding a Recipe

Maybe you don't want your tech to be randomly found in chests and instead want the player to use the Tech Development Console to 'craft' it by combining other techs (the player can use tech cards at a tech station to create tech unlock items of techs they have).

Don't worry; this is probably the most straightforward part. All you need to do is swap out some values. You don't even have to unlock the recipe since the Tech Development Console doesn't check the player's known recipes! Here's a recipe file for a suit tech.

As you can see, it accepts two tech items– one with the sb_health tech and one with the sb_regeneration tech. These are the two techs the player will use to make your new tech! Change them to whatever techs you want them to be. This recipe outputs one tech item for sb_enhancedhealing.

Under groups, you may notice sb_tech_4. Each tech slot has a numeric value. Head is 1, body is 2, legs are 3, and suit is 4. Change the number to match the slot your tech goes in, and the player will be able to filter by tech slot in the Tech Development Console interface! So, if your tech is a head tech, set it to sb_tech_1, and if it's a body tech, change that sucker to sb_tech_2, etc etc.

Maybe you don't want the player to have to combine techs and instead want a more traditional crafting recipe. In that case, go for it! It's a crafting recipe, after all. Just change the input values.

Plates

Betabound adds craftable plates which can display items. Their item ID is sb_plate. Items are stripped of the following colors to remove their border (because vanilla has inconsistent border colors):

Unfortunately, there is no 'hey please remove the border' image operation, so if the item icon uses those colors elsewhere, they will be removed.

By default, only generic and consumable items are accepted onto the plate. You can use the /eval root.itemType("copperbar") command to view what type an item is. The command checks the type of the copper bar item, so make sure to change it because. If you have a non-generic non-consumable item and want to display it on a plate, keep reading!

Consumable-type items have file names ending in '.consumable', and generic-type items end in '.item'.

Plates check the item put on them for the sb_plate table. Below is an example of plate values, in an item file. All values are optional, though it is generally recommended to have an image for your item if it is to go on a plate.

You can add 'sb_forcePlate' to your item itself or to its item tags to have the plate accept it, regardless if it is a generic or consumable item. Please test your item, because it may not display properly if it is something like a weapon or sapling.

Ability Modifier Items

Betabound adds an item which can change the special (or primary!) ability on weapons. The item's buildscript picks a random ability from the /sb_abilitymods.config file's 'ability' section, or from the item's 'abilityList' parameter. The file at /treasure/sb_abilitymods.treasurepools contains treasure pools for certain types of abilities, such as basic sword abilities, elemental gun abilities, etc. These pools are then put into the vanilla weapon treasure pool, so the player cannot get a wand ability on a tier 1 planet, as no wands spawn in tier 1 treasure pools. Please note that as of 25/Feb/2024, Betabound contains no treasure pool with an ability mod item which does not have its own abilityList.

However, treasure chests are not the only way to obtain ability mods. The player can craft a Metalwork Station with tier 2 materials, allowing them to craft any ability mod with an associated recipe file. The Metalwork Station does not care if the player has the recipes unlocked, so there is no need to add a way to unlock the recipe for your ability.

All ability mods, by default, are crafted with a platinum bar (unused vanilla item enabled by Betabound) and a diamond. You can change the ability value to any ability in the game, regardless if it is present in the /sb_abilitymods.config file.

Valid categories are sb_melee, sb_gun, and sb_staff. Staff is also used for wand abilities because they can go on staves.

The /sb_abilitymods.config file allows you to add certain values to change how your ability is applied. You can patch it like this.

Weapon name groups:

It is simply that easy.

Poisoncreep Immunity (for aquatic/robotic races)

Betabound adds a new crop called Poisoncreep. It's poisonous to anyone but those of aquatic disposition, but those that have Glitch-like digestive systems are also unaffected. It heals those who are unaffected but poisons those who are.

If you want your race to be immune to Poisoncreep's poison, add a statusEffects list to your species file and add the 'sb_poisoncreepimmunity' effect. You can check out the novakid species file for a more direct example.

(This is currently not in the public release of Betabound! It will come soon though)

If you want to patch a species to be immune, use this (note that you MUST have square brackets at the start and end of your patch UNLESS they are already present! They are present in this example.):