Skip to content

Creating a Character

modargo edited this page Nov 14, 2026 · 18 revisions

Creating a character is an involved process with many steps. This guide covers everything from initial setup to coding to visuals. It is split into sections by topic and roughly ordered starting with the most essential tasks, but you can jump around between sections based on your own priorities.

This guide assumes you have followed the Setup instructions and created a new project using the character template. You will also need most of the information from the next steps on the Setup page, so be ready to read those pages as needed and/or bookmark them to come back later.

There will be a lot of coding involved. If you get stuck on writing or understanding code, you may also want to give the C# resources linked at the top of Setup another look.

Before starting: character design

This guide is about how to implement a character, but it's worth saying a few things about character design first.

Standard character content

If you want to make a character that matches the base game characters, you will want the following card distribution:

  • Your starting deck: usually 4 Strikes, 4 Defends, and two unique starters (sometimes varies, e.g. for Ironclad/Silent/Fool)
  • Standard card pool: 20 common, 35 uncommon, and 25 rare
  • Ancient cards: one for Archaic Tooth and one for Dusty Tome
  • Multiplayer cards: 3 uncommon, 2 rare

You can design your cards at the same time as you're implementing everything, but many people find it more effective to design cards ahead of time, e.g. building up a spreadsheet of cards so that you can easily track and sort by rarity, cost, type, and so on. This also helps with planning out your core mechanics and archetypes.

Card design is the bulk of the work involved in a character. Characters also have character-specific relics and potions, but those are often easier to come up with as you go. The sections for each content type under implementing content below have further details.

Common pitfalls to watch out for

Note

We're considering making a wiki version of this. Check back later for more.

The Slay the Spire Discord has a good overview of common pitfalls in character design. While written for the first game, almost all the advice there applies just as well to StS 2 (exceptions being the precise card count and that losing your starter relic isn't a thing anymore). Avoiding these pitfalls makes it easier to create a good character.

Initial setup

Before anything else, it's good to define your character's details and make your starter strike and defend.

Defining the details of your character

The template automatically creates a class for your character, named the same as your character. Open up that class. It has a bunch of defaults that define the basic information about your character.

You will probably want to change the following properties:

  • Color: the color used for your character's name in the Statistics screen
  • Gender: your character's gender
  • StartingHp: your character's starting HP (base game values: 80/70/75/66/75/77 for Ironclad/Silent/Regent/Necrobinder/Defect/Fool)
  • StartingRelics: your character's starting relics (usually only one); once you've made your starter relic, set it here
  • StartingDeck: your character's starting deck; once you've made your Strike, Defend, and unique starting cards, set them here

You do not need to change anything else right now.

  • The three pool properties define your cards/relics/potions; you shouldn't change these
  • The various icon-related properties will be covered below in the section about character visuals

Creating your starter strike

Creating your starter strike and defend will get you used to the process of creating cards with something simple. Even though all starter strikes and defends are basically the same, you need unique ones for your character to have unique art and to be recognized as your character's cards.

Start by going to the YourModCode/Cards folder. This is where you should put all the cards you create. Next, make a new class by right-clicking on the folder and selecting Add -> Class/Interface in the menu. Name it StrikeYourCharacter (adjusted to fit your character's name).

Now you should use the sample code below; make sure to change StrikeYourCharacter and YourModCard to the right class names for your project. After making those changes, replace the code in the file you just created (everything below the line that says namespace) with your edited sample. Rider will complain about missing references; follow Rider's suggestions to import them (pressing Alt+Enter should also do the trick). You can read over the comments to understand what the code is doing.

// Extending YourModCard (which will be named based on your mod's name) means the card will automatically
// be added to your character's card pool and will look for images in the right place. You can take a quick
// look at the YourModCard class to see what it does if you're curious.
public class StrikeYourCharacter() : YourModCard(1, CardType.Attack, CardRarity.Basic, TargetType.AnyEnemy)
{
	// This marks the card as a "strike" for effects like Perfected Strike. Most cards don't need any tags.
    protected override HashSet<CardTag> CanonicalTags => [CardTag.Strike];
	// These are the variables that the card uses; almost every card has some (most numbers on cards come from these)
    protected override IEnumerable<DynamicVar> CanonicalVars => [new DamageVar(6, ValueProp.Move)];
	// This is what changes when the card is upgraded
    protected override void OnUpgrade() => this.DynamicVars.Damage.UpgradeValueBy(3);

	// The OnPlay method is what happens when you play the card
    protected override async Task OnPlay(PlayerChoiceContext choiceContext, CardPlay cardPlay)
    {
		// For single-target cards like Strike, it's good to check that there actually is a target
        ArgumentNullException.ThrowIfNull(cardPlay.Target);
		// This gets the damage amount from the variables, sets up an attack with information from the card,
		// adds a slashing visual effect, and executes the attack
        await DamageCmd.Attack(this.DynamicVars.Damage.BaseValue)
			.FromCard(this, cardPlay)
			.Targeting(cardPlay.Target)
			.WithHitFx(VfxCmd.slashPath)
			.Execute(choiceContext);
    }
}

If you've done it correctly, everything will look good except for the class name StrikeYourCharacter having a squiggly red underline. With your cursor on Strike, press Alt+Enter to use the menu to generate localization, then move that text to your cards.json file (like what you did for your character during setup). Set the description to be "Deal {Damage:diff()} damage." and the title to "Strike". If you've done it right, when you switch back to the StrikeYourCharacter code, the red underline will disappear after a few moments.

To include this in your starting deck, go back to your character class and replace all the StrikeIronclad entries in StartingDeck with the card you created.

Testing your starter strike

Now you have a starter strike card of your own. Publish your mod, start a new run with your character, and the new strike and its text should show up. It will have a placeholder image; changing that is the next step.

If any of the following happen when you start up the game with your mod active, it means you've run into an error:

  • The mod details being colored red in the bottom right on the main menu (caused by your mod failing to load)
  • Cards staying in the middle of the screen and not moving after you play them (caused by your card's hitting an error)
  • All the cards being stuck in the top left of the compendium (caused by your cards localization or upgrade logic being broken)

The first you should do for any errors like this is check the logs to work out what's wrong.

Adding an image for your starter strike

Normal card art is expected to be 1000x760 or 500x380 (smaller art will be scaled) and to be in PNG format.

Once you have the art for your strike, go to the folder YourMod/images/card_portraits/big in your project. This is where you'll put all your card art (and you'll see that this folder already has a single placeholder image in it named card.png).

For your strike, you need to name the image file as follows: take the class name for the card, then convert it to all lowercase with a _ between each word. For example, if you kept the class name as literally StrikeYourCharacter, the image file for it would be strike_your_character.png.

Once you added the image in, publish again and your new image should show up. You now have a fully implemented starter strike!

Creating your starter defend

You can make your starter defend following the same steps. Apply what you've learned!

Here's the sample code for it:

public class DefendYourCharacter() : YourModCard(1, CardType.Skill, CardRarity.Basic, TargetType.Self)
{
    protected override HashSet<CardTag> CanonicalTags => [CardTag.Defend];
    protected override IEnumerable<DynamicVar> CanonicalVars => [new BlockVar(5, ValueProp.Move)];
    protected override void OnUpgrade() => this.DynamicVars.Block.UpgradeValueBy(3);

    protected override async Task OnPlay(PlayerChoiceContext choiceContext, CardPlay cardPlay)
    {
        await CreatureCmd.GainBlock(this.Owner.Creature, this.DynamicVars.Block, cardPlay);
    }
}

The description should be "Gain {Block:diff()} [gold]Block[/gold]." Don't forget to change your starting deck to use it too.

Implementing content

Creating more cards

Creating other cards will be similar to what you did for strikes and defends... except that you'll need to write the code yourself. With how many different things cards (and relics/potions/etc.) can do, people usually find that the most effective way is to learn is from examples; see learning how to make things for an overview of the process.

For general guidance on adding cards, you can read over Adding Cards. A lot of it was covered here already, but it has some good tips (there's a card template you may find helpful).

Other pages on this wiki may also be helpful, depending on what you're doing. See the front page for an overview.

As you're making cards, don't forget to check logs when you encounter errors so you can effectively debug your code.

General advice

Don't be afraid to ask for help. The Discord's #sts2-modding channel is active and people are happy to answer questions; everyone understands that it can be a steep learning curve to make your own cards if you don't have previous programming/modding experience.

Don't be afraid to learn either. Sometimes, the response you get to a question might be a link to documentation or a recommendation to strengthen your knowledge of C#. In the moment, these might seem like distractions from making a mod, but taking some time to learn will make the whole process faster; it pays back very quickly.

All the advice so far applies to the remaining types of content, so the sections below are focused on specific details around each piece of content.

Token/status cards

For any token/status cards you make, in addition to setting the rarity to Token/Status, you will need to put [Pool(typeof(TokenCardPool))]/[Pool(typeof(StatusCardPool))] right above the class name. Doing that marks as tokens/statuses instead of part of your character's normal card pool.

Ancient cards

Characters are expected to have two unique ancient cards, one for Archaic Tooth and one for Dusty Tome.

To link your starter card to the ancient card that Archaic Tooth turns it into, have the starter card implement ITranscendenceCard, e.g.:

public class StarterCard : MyModCard, ITranscendenceCard
{
    public CardModel GetTranscendenceTransformedCard() => ModelDb.Card<UpgradedStarterCard>();

If you have a standard setup with two ancient cards in your card pool, one of which is given by Archaic Tooth, the other will automatically be given by Dusty Tome.

Ancient card art is expected to be 606x852.

See Ancient Upgrades on BaseLib's wiki for further documentation.

Character-specific relics

Characters typically have a number of character-specific relics.

  • A starter relic
  • A starter relic upgrade (from Touch of Orobas)
  • 1 shop, 1 common, 2 uncommon, and 3 rare relics

These relics can be implemented like any other relic. As long as you extend your base relic class (YourModRelic), they will be put in your character's relic pool. Make sure to set the correct rarity for each relic (including Ancient rarity for the starter relic upgrade).

The one thing you need to set up is the link between your starter relic and its upgrade. To do this, add the following code to your starter relic: public override RelicModel GetUpgradeReplacement() => ModelDb.Relic<BetterStarter>(); (per Ancient Upgrades on BaseLib's wiki).

After you make your starter relic, make sure to go back and update the StartingRelics property in your character class (see the section on defining the details of your character above).

Relics are expected to have have three images:

  • A normal image and outline (both 94x94) that go in YourMod/images/relics
  • A big image (256x256) that goes in YourMod/images/relics/big

File naming works just like cards: take the class name for the card, then convert it to all lowercase with a _ between each word. The outline image adds _outline.

Yummy Cookie relic image

Yummy Cookie has a custom image for every character. To set up one for your character, go to your character class, and add the code:

    public override RelicIconData CustomYummyCookie =>
        new("yummy_cookie.png".BigRelicImagePath(), "yummy_cookie.png".RelicImagePath(), "yummy_cookie_outline.png".RelicImagePath());

This will look for your Yummy Cookie images in the same place as your other relic images.

Character-specific potions

Characters typically have three character-specific potions, one each of common/uncommon/rare.

These potions can be implemented like any other potion. As long as you extend your base potion class (YourModPotion), they will be put in your character's potion pool.

Potion images are 256x256 and go in YourMod/images/potions. Potions are expected to have an outline image, also 256x256, in YourMod/images/potions/outline. File naming works the same as other and both images use the same name (the game is able to tell them apart because they're in different directories).

Powers

Many things you naturally want to do with cards, relics, and other game mechanics will be implemented as powers. Everything that shows up as an icon under a player or monster health bar is a power. Examples include Strength, Weak, Poison, temporary strength reduction from Piercing Wail, and effects from power cards like Echo Form. Powers you create should extend your base power class (YourModPower).

Like the other types of content, the standard guidance applies here. You can learn from what the base game does, e.g. starting with an existing card or relic that applies a power similar to what you want. That will let you see the code for apply the power (usually simple) and the code for the power itself (which can be complex, depending on what the power does).

Powers are most often created as part of getting other content to work, rather than being something you set out to create like cards, relics, or potions.

Power images go in YourMod/images/powers. You're expected to have a 64x64 image there and a larger 256x256 image in YourMod/images/powers/big. File naming works the standard way and both images use the same name.

Visuals

Note

We're still working on good documentation for character visuals. Check back later for more.

Character visuals

Energy icon

Multiplayer hand

Enabling Godot scripts

If you want to use scripts defined in your mod for Godot scenes, you need to go to your MainFile class and uncomment the line there with Godot.Bridge.ScriptManagerBridge.LookupScriptsInAssembly(assembly);.

Character text

As one of the last steps of setting up your project, you should have generated a bunch of localization entries (text) for your character. You'll want to go through the entries in characters.json and ancients.json to fill in text that matches your character.

To see what the base game characters do for this, follow the instructions at Extracting Assets and Text and open the files of the same name from the base game.

For character text in characters.json, most of the entries are self-explanatory. For the ones that aren't:

  • aromaPrinciple: the text that will show up in the Aroma of Chaos event

As of beta 113 (released November 12, 2026), characters are expected to have a new entry for shortTitle in characters.json, used for the character's name on the Dread mode starting screen and packs of cards from that character in Blitz mode. The text for this entry should be the character's name without articles (e.g. "Defect" instead of "The Defect"). This will get added to the automatically created entries at some point, but for now you'll need to add it manually.

Ancient text

For ancient conversations (in ancients.json), most base game characters have several conversations with each ancient and the Architect, but the template only sets up a single basic Architect conversation. If you want your character to feel as "alive" as the base game characters, you will want to add conversations with the Architect, Neow, and the 7 ancients that appear across the acts.

Base game characters have three unique conversations with each ancient including Neow (with one that repeats) and three or four unique conversations with the Architect (with most or all of them repeating).

For documentation on what these entries should look like, see Ancient Dialogue on BaseLib's wiki.

For examples to learn from, look at the base game entries or check out how other mods do it (e.g. see the SHADOW_SILENT entries from Into the Spireverse's ancients.json.

Sea Glass

To define a custom name for Sea Glass for your character, add SEA_GLASS.YOURMOD-YOURCHARACTER.title: "Whatever Glass" to your relics.json, replacing YOURMOD-YOURCHARACTER appropriately (with the same string you can see in all the other JSON entries you're making).

Colorful Philosophers

Adding your character to the Colorful Philosophers event is not yet supported by BaseLib.

Clone this wiki locally