Starbound – Book Of Spirits Patching Manual Guide

This guide is about fixing the Starbound mod called Book of Spirits – NPC & Monster Name Displayer. The goal is to include built-in assistance for custom NPCs, Monsters, and talkative objects.

Overview

This mod is crucial, and it should be loaded before any other mods using its features. You don’t have to include it in your metadata file. The key features involve showing the name of the entity, a custom title if it has one, and for monsters, indicating if they are rare breeds (like Albino Poptop, Fire Gleap) and elite.

There are two displayers: a name displayer and a title displayer. They automatically show based on the entity’s configuration, which I’ll explain in the sections below.

Even if I say something is harmless, it means your mod will work fine even without “Book of Spirits – NPC & Monster Name Displayer” installed. It’s recommended to unpack the mod because there are files you might need to copy into your mod, helping you understand what to patch.

Naming rules for hostile NPCs: I’ve set a fixed name for generic hostile NPCs (bandits, zombies, lackeys, etc.) since in most video games, only important hostile NPCs have names to highlight their significance over regular mobs.

NPC parameters

The name displayer chooses the NPC’s name from one of these configurations:

1. The “npcname” variable.
2. The “name” variable that can be assigned within their identity table.
3. The randomly generated name assigned to them.

It’s a personal choice, but you might want to set a name for generic hostile NPCs (Zombies, Bandits, Lackeys, etc.) that function as monsters.

For the title displayer, it selects the following variable added by this mod, which is harmless:

• displayTitle

There’s also a new harmless behavior script added by this mod. If an NPC is overriding the base behavior script (like Merchants, for example), you should copy this script:

/scripts/bookofspirits/bookofspirits_interact_support.lua

This script displays the displayer when interacting (pressing ‘E’) with an NPC. If the displayer doesn’t show up during interaction, you need to add this script to your NPC.

NPC Patching-Support

The patching process is as follows, but you can add it directly to your mod for easier understanding of variable positions.

To give an NPC a title, and if it’s overriding the behavior script (for example, merchant.npctype):

[
[{ "op" : "add", "path" : "/displayTitle", "value" : "Merchant"}]
,[{ "op": "add", "path": "/scripts/-", "value": "/scripts/bookofspirits/bookofspirits_interact_support.lua" }]
]

Result:

{
  "type" : "merchant",
  "baseType" : "base",
  ...
  "displayTitle" : "Merchant",
  "scripts" : [
    "/npcs/bmain.lua"
    ,"/scripts/bookofspirits/bookofspirits_interact_support.lua" 
  ]
}

To set a fixed name for the npc(mutantminer.npctype):

[{ "op" : "add", "path" : "/identity", "value": { "name":"Mutant Miner" }}]

Result:

{
  "identity" :
  {
     "name":"Mutant Miner"
  }
}

Chatty Objects Parameters

The following variables and script are harmless additions from this mod:

For the name displayer, it uses the following object configuration as their NPC name:

• npcName

The title displayer selects the following harmless variable added by this mod:

• displayTitle

There’s also a new script that you must copy into your mod:

/scripts/bookofspirits/bookofspirits_interact_support.lua

This script displays the displayer when interacting (pressing ‘E’) with an object. If the displayer doesn’t show up during interaction, you need to add this script to your object.

Warning:

• You cannot use this feature if the object has an “interactAction” parameter.
• This feature is only applicable if the object can be made “chatty,” typically having “scripts” and “chatOptions” arrays.

Chatty Object Patching-Support

To give an object a name and title(IE: techlabscientist.object):

[
[{ "op" : "add", "path" : "/npcName", "value" : "Elliot"}]
,[{ "op" : "add", "path" : "/displayTitle", "value" : "Tech Lab Scientist"}]
,[{ "op": "add", "path": "/scripts/-", "value": "/scripts/bookofspirits/bookofspirits_interact_support.lua" }]
]

Result:

{
  "objectName" : "techlabscientist",
  "colonyTags" : ["outpost"],
  ...
  "npcName" : "Elliot",
  "displayTitle" : "Tech Lab Scientist",
  "scripts" : ["/scripts/chattyObject.lua","/scripts/bookofspirits/bookofspirits_interact_support.lua"]
}

Monster Parameters

For the name displayer, it selects the following configuration of the monster as their name:

• shortdescription

The title displayer picks the following harmless variable added by this mod, added as a statusProperties:

• displayTitle

Note: Rare monster variants have a custom title in the format (check /monsters/flyers/agrobat/iceagrobat.monstertype.patch):

^yellow; Rare Breed ^reset;

Additionally, there’s a new harmless script added by this mod. You must copy it if there’s a monster that can be set as elite or can have dynamic custom titles and dynamic names, such as Generated monsters:

/scripts/bookofspirits/bookofspirits_monster_support.lua

There’s also a new file containing additional configurations for Generated Monsters. If you’re adding new types of generated monsters, check this file for more details:

/monsters/bookofspirits_generated.config

Monster Patching-Support

To give a Monster a name, title and display it as elite if is configured as elite(IE: punchy.monstertype):

[
[{ "op" : "add", "path" : "/shortdescription", "value" : "Punchy"}]
,[{ "op" : "add", "path" : "/baseParameters/statusSettings/statusProperties/displayTitle", "value" : "Test Dummy"}]
,[{ "op" : "add", "path" : "/baseParameters/scripts/-", "value" : "/scripts/bookofspirits/bookofspirits_monster_support.lua"}]
]

Result:

{
  "type" : "punchy",
  "categories" : [],
  ...
   "shortdescription" : "Punchy",
   "baseParameters" : {
       "statusSettings" : {
          "statusProperties" : {
              "displayTitle" : "Test Dummy"
          }
       }
      ,"scripts" : [
        "/monsters/monster.lua",
       ,"/scripts/bookofspirits/bookofspirits_monster_support.lua"
      ]
   }
}

Generated Monster Parameters

Generated Monsters have a dedicated configuration file that includes parameters for setting the name and custom title based on their parts. The configuration file is located at:

/monsters/bookofspirits_generated.config

Additionally, there’s a new script at “/scripts/bookofspirits/bookofspirits_monster_support.lua” that must be copied into your mod. Make sure to add this script to the script array of the generated monster.

skillPrefixes

Here’s a JSON array of objects containing a list of skill types from the special skill of the monster. This list is used to determine the prefix of the monster name.

• name: This is the string name that will be displayed alongside the monster name.
• skillName: This is the skill name type (e.g., inkSprayAttack) that will be used to compare if the monster has that skill.
• asSuffix (optional): If set to true, the skill name will be added after the monster name.

monsterTypes

This list contains the names of monster types and their variants. It’s used to determine the monster name and title based on the head part of the monster or a specific part pattern of your choice.

• monster type (e.g., “largeflying”): The name of the list should match the “type” parameter in the .monstertype file.
• variants: In this JSON array of objects, you include different part combinations that the generated monster can have.

Variants Parameters

This JSON array of objects includes variables used to configure the generated monster name and title based on the given parts. It supports multiple part patterns, but it’s recommended to prioritize entries with just the head part first.

• name: The monster name that will be displayed.
• title (optional): The title that will be displayed.
• prefix (optional): A prefix added to the monster name.
• parts: An array of strings containing the names of folders containing the monster’s parts.
• addSkillPrefix (optional): If set to false, it won’t add a skill prefix to the monster name.

Note:

• If you want to set a specific pattern, that entry must include all the part types used by the monster type.
  • For example, if “largefish” uses 3 parts as configured in its “parts” array, the pattern should also have 3 parts..

{“name” : “SunShark”, “title” : “Large Fish Monster”, “parts” : [“shark”,”sunfish”,”sunfish”]}

Generated Monsters Patching-Support For New Types

For this example, I’ll use the “sb_hugebiped.monstertype” from Betabound, which is a new type of generated monster.

Remember to copy “/scripts/bookofspirits/bookofspirits_monster_support.lua” into your mod in the same folder path.

To provide support for a new generated monster type (add it directly to your mod or patch it if you are patching another user’s mod):

[
[{ "op" : "add", "path" : "/baseParameters/scripts/-", "value" : "/scripts/bookofspirits/bookofspirits_monster_support.lua"}]
]

Result:

{
  "type" : "sb_hugebiped",
  "categories" : ["sb_hugebiped"],
   ...
  ,"baseParameters" : {
    "scripts" : [
      "/monsters/monster.lua",
      "/monsters/sb_miniboss.lua"
     ,"/scripts/bookofspirits/bookofspirits_monster_support.lua"
     ]
   }
}

Then you must patch the file “/monsters/bookofspirits_generated.config” as a file “/monsters/bookofspirits_generated.config.patch“:

[
    {
        "op": "add",
        "path": "/monsterTypes/sb_hugebiped",
        "value": {
            "variants": [
                {
                    "name": "Birdzilla",
                    "title": "Huge Biped Monster",
                    "parts": ["beak"]
                },
                {
                    "name": "Dragonzilla",
                    "title": "Huge Biped Monster",
                    "parts": ["dragon"]
                },
                {
                    "name": "Featherzilla",
                    "title": "Huge Biped Monster",
                    "parts": ["feather"]
                },
				{
                    "name": "Rhinozilla",
                    "title": "Huge Biped Monster",
                    "parts": ["rhino"]
                }
            ]
        }
    }
]

Result:

{
  ,"monsterTypes" :
  {
   "largeflying" : {...}
    ...
    ,"sb_hugebiped" : {
      "variants" : [
        {"name" : "Birdzilla","title" : "^red;Huge Biped Monster","parts" : ["beak"]}
        ,{"name" : "Dragonzilla", "title" : "^red;Huge Biped Monster","parts" : ["dragon"]}
        ,{"name" : "Featherzilla","title" : "^red;Huge Biped Monster","parts" : ["feather"]}
        ,{"name" : "Rhinozilla","title" : "^red;Huge Biped Monster","parts" : ["rhino"]}
       ]
     }
  }
}

Generated Monster Patching-Support Existing Type

To add a new variant to an existing monster type(IE: largequadruped.monstertype), you must patch the file “/monsters/bookofspirits_generated.config” as a file “/monsters/bookofspirits_generated.config.patch“:

[
    {
	"op": "add", "path": "/monsterTypes/largequadruped/variants/-",
	"value": {"name": "New Quadruped 1","title": "Large Quadruped Monster",	"parts": ["blabla1"]}
    }
	,{
	"op": "add", "path": "/monsterTypes/largequadruped/variants/-",
	"value": {"name": "New Quadruped 2","title": "Large Quadruped Monster",	"parts": ["blabla2"]}
    }
]

Result:

  ,"monsterTypes" :
  {
    "largeflying" : {...}
   ...
    ,"largequadruped" : {
      "variants" : [
        {"name" : "Anthurix","prefix" : "Adult", "title" : "Large Quadruped Monster","parts" : ["arrow"]}
        ...
      ,{"name": "New Quadruped 1","title": "Large Quadruped Monster",	"parts": ["blabla1"]}
      ,{"name": "New Quadruped 2","title": "Large Quadruped Monster",	"parts": ["blabla2"]}