Skip to content
This repository has been archived by the owner on Mar 6, 2023. It is now read-only.

Developer Guide

Jump to bottom
SlimeCubed edited this page Nov 6, 2021 · 15 revisions

Developer Guide

Getting Started

The core of any SlugBase character is its SlugBaseCharacter instance. Your mod will create a class that inherits from this, then register it with PlayerManager.RegisterCharacter(SlugBaseCharacter).

Here is a simple example with only abstract members implemented:

public class MySlugcat : SlugBaseCharacter
{
    public MySlugcat() : base("My Slugcat", FormatVersion.V1, 0, true) {}

    public override string Description => "My slugcat's description.";

    protected override void Disable() {}
    protected override void Enable() {}
}

RegisterCharacter must be called before it appears as an option to select:

PlayerManager.RegisterCharacter(new MySlugcat());

After it is registered, a new character called "My Slugcat" will appear on the select screen. It will copy the Survivor's world, as indicated by the 0 in base("My Slugcat", FormatVersion.V1, 0, true).

Gameplay

Most character-dependent gameplay changes are customizable through virtual members of SlugBaseCharacter:

  • StartRoom: Change where the player starts in a new game.
  • GetStats: Change the player's speed, combat skills, etc. Changes made to SlugcatStats.maxFood and SlugcatStats.foodToHibernate may not show up on the select menu, so GetFoodMeter should be overridden instead.
  • GetFoodMeter: Change the amount of food used while sleeping and the maximum amount of food stored.
  • CanEatMeat: Change whether or not the player can eat most creatures.
  • QuarterFood: Change whether or not the player receives 1/4th the food from non-meat sources.
  • GatesPermanentlyUnlock: Change whether or not gates stay open for this player like they do for the Monk.
  • GetCycleLength: Change the duration of cycles.
  • CanSkipTempleGuards: Change whether or not the temple guards are affected by flashbangs.
  • HasDreams: Change whether or not dreams appear for this character.

Any other gameplay changes can be made manually, such as through hooks. Any changes made this way should be enabled in your mod's override of SlugBaseCharacter.Enable and disabled in your mod's override of SlugBaseCharacter.Disable. If a change must be applied before the RainWorldGame instance is created then it may be done in SlugBaseCharacter.Prepare. Instead of using Enable and Disable, you can check if your modifications should be applied using SlugBaseCharacter.Enabled.

Upgrading from v1.1.X

SlugBaseCharacters in versions below 1.2.0 only support having one character active at a time. Versions at or above 1.2.0 may mix and match any combination of vanilla and modded slugcats via other mods such as Jolly Coop. Characters that support this are called multi-instance. Firstly, to mark your character as multi-instance, pass true to the multiInstance parameter of your SlugBaseCharacter's constructor. Next, you must change your hooks to only affect Players that are an instance of your character. Some methods are provided for this:

  • SlugBaseCharacter.IsMe(Player player): Check if the given player is an instance of this character.
  • SlugBaseCharacter.IsMe(RainWorldGame game): Check if the given game was started from this character's save file.

Display

Some character-specific visuals can be changed be overriding members of SlugBaseCharacter:

  • DisplayName: Change this character's name when displayed to the user.
  • Description: Change this character's description on the select screen.
  • SlugcatColor: Change this character's color in-game and on the UI.
  • SlugcatEyeColor: Change this character's eye color in-game.

Saves

The core of a SlugBase character's save file is the CustomSaveState class. You may add information on to this by inheriting from CustomSaveState, then overriding SlugBaseCharacter.CreateNewSave to instantiate your new class. The CustomSaveState has some members you can override to add your own data to the save file:

  • Save: Add values to be saved.
  • Load: Load saved values.
  • SavePermanent: Add values to be saved that will not be reverted on death.
  • LoadPermanent: Load saved values that will not be reverted on death.

SlugBaseEx also contains some helper methods related to saves:

  • TryGetSave: Retrieve a SaveState. This is an extension method of Player and RainWorldGame.

Data saved using CustomSaveState will be cleared when starting a new game. If you need information to carry over between resets you can use the following:

  • SaveManager.GetGlobalData: Gets a dictionary that persists between sessions until the save slot is reset.
  • SaveManager.GetCharacterData: Functions similarly to GetGlobalData but returns a unique dictionary for each unique string passed in.
  • SaveManager.WriteDataToDisk: Save the updated dictionaries immediately. This is only useful if you really want to stop save scumming, since the dictionaries are automatically saved whenever the game saves normally.

Resources

Resources, such as images for scenes, are read from files by default. For more information on how they are formatted, see the File Formats guide. You can change how these resources are loaded by overriding a handful of virtual fields on SlugBaseCharacter:

  • GetResource: Change how the resource stream is acquired, such as loading from embedded resources.
  • BuildScene: Change how scenes are loaded, if they must vary from the default format.
  • HasScene: Change how a scene's existence is checked for.
  • BuildSlideshow: Change how slideshows are loaded, if they must vary from the default format.
  • HasSlideshow: Change how a slideshow's existence is checked for.

Menu illustrations can be loaded from a SlugBase character's resources by setting the scene folder to "SlugBase Resources" and the image name to "PlayerName\Folder\AnotherFolder\Image.png". For example, to load an image called "MyImage.png" from the character "ExampleSlugcat":

new Menu.MenuIllustration(menu, owner, "SlugBase Resources", "ExampleSlugcat\\MyImage.png", pos, true, false);

Other Useful Members

  • ArenaAdditions.GetSelectedArenaCharacter: Returns a PlayerDescriptor that represents the character that will be used in arena mode.
  • SlugBaseCharacter.WorldCharacter: Returns the slugcat index used for the world, such as placed object filters and creature spawns. A value of 0 copies Survivor's world, 1 copies Monk's, and 2 copies Hunter's.

Region Maker Guide

Filtering Creature Spawns

SlugBase allows you to filter creature spawns based on the active character. Character filters can be either whitelists and blacklists. Whitelists are made of a comma-separated list of character names inside of square brackets (e.g. [Name1, Name2, ...]). Blacklists are the same, but have an exclamation mark before each name (e.g. [!Name1, !Name2, ...]). Don't mix and match names with and without exclamation marks. Names with exclamation marks will be ignored and a warning will be logged each time spawns are loaded.

Filters in world files may only be applied to lines in the "CREATURES" section. Filters may be placed at the start of a line, but after the vanilla filter. They may also be placed somewhere after the creature name separated by :. Filters at the start will cause the line to be discarded if SlugBase is not installed, while filters at the end will be keep. Use filters at the start whenever possible. End-of-line filters may be discarded if another region adds creatures to the same den through CRS.

Ex: Add another cicada to SU_B02 for the SlugBase character "Sprinter". Note that this is placed at the start, making the spawn not appear if SlugBase isn't installed.

[Sprinter]SU_B02 : 4-CicadaA

Ex: Add another cicada to SU_B02 for all characters except Sprinter and Example. Note that this is placed at the end, making the spawn still appear if SlugBase isn't installed.

SU_B02 : 4-CicadaA : [!Sprinter, !Example]

Ex: Add another cicada to SU_B02 for Survivor, but not Sprinter (who normally uses Survivor's spawns).

(0)SU_B02 : 4-CicadaA : [!Sprinter]

Ex: Add another cicada to SU_B02 for Monk, Hunter, and Sprinter. If you put both an index filter (using parenthesis) and name filter (using square brackets) on a line, both must pass for the line to be kept. If you need the line to be kept if either pass, just add two separate lines, each with a filter.

(1,2)SU_B02 : 4-CicadaA
[Sprinter]SU_B02 : 4-CicadaA

Changing Existing Spawns

Existing spawns may be replaced by appending _REPLACE to the room name. Using None instead of a creature type will clear the den. Multiple lines marked with _REPLACE can be applied to the same den. The original contents will be removed and all replacement spawns will share the den.

Ex: Remove the cicadas in SU_B02 for Sprinter.

[Sprinter]SU_B02_REPLACE : 4-None, 5-None

Ex: Replace the cicadas in SU_B02 with noodleflies for Sprinter and Example.

[Sprinter, Example]SU_B02_REPLACE : 4-BigNeedleWorm, 5-SmallNeedleWorm-3

Filtering Placed Objects

SlugBase also allows you to filter placed objects depending on which character you are playing as. The Filter placed object will have another button per character you have installed. When the button is white, the filter acts as normal. When it is green and has a + before the name, the objects in the filter will remain active for that character. When it is red and has a - before the name, the objects in the filter will be disabled for that character.

The filters are saved in a file alongside each room called ROOMNAME_Settings_SlugBase.txt so that they will not interfere with the game if SlugBase is not installed.

Clone this wiki locally