Modding Notes

< Back to Modding

This page has notes that modders may find useful.

Apps

Decompile

To decompile Brotato for modding, use GDRETools, which can be downloaded here.

Godot

You'll need to download Godot to edit the decompiled project. Jonus has an excellent video here that covers the basics of modding, and will show you how to customise weapons and characters, and change item appearances. You can also read the documentation for Godot here.

Steam Errors

The standard version of Godot will have lots of errors related to the Steam API when you try to run it via Godot, due to it lacking inbuilt support for Steam's SDK. Instead, you can use an alternate version of Godot that has been compiled to include Steam support, called GodotSteam. Get the version you need for Brotato here (Godot v3.5).

Make sure you read GodotSteam's docs on exporting, because there are some limitations and caveats (eg. you can't use the "Export with Debug" option, and you need to set up your export templates manually).

Balancing

When balancing new items, referring to the vanilla Items can be very helpful.

We also have a special Items Grid page that shows all items in a grid, with buttons to filter by stat. This can help you identify gaps in vanilla's item pool that your mod might be able to fill, or see how much vanilla's stat increases differ by tier.

Characters with Positive Stats

Some characters start with very high base stats, which have the potential to instantly make your modded items OP:

Character	Stat	Value
Ranger	Range	50
Sick	Life Steal	25
Speedy	Speed	30
Ghost	Dodge	30
Hunter	Range	100
One Armed	Attack Speed	200

Characters with Negative Stats

If you're creating an effect that converts one negative stat to a different positive one, keep in mind that many Characters start with huge decreases to certain stats.

The vanilla items that use this effect are: Esty's Couch (-Speed), and Retromation's Hoodie (-Dodge).

Character	Stats	Value	Notes
Brawler	Range	-50
	Ranged Damage	-50
Crazy	Dodge	-30%
Mage	Ranged Damage	-100	No longer the case since v0.8.0.0
	Melee Damage	-100	No longer the case since v0.8.0.0
	Engineering	-50	No longer the case since v0.8.0.0
Chunky	Life Steal	-100
Lucky	Attack Speed	-60%
Mutant	Items Price	-50%
Loud	Harvesting	-95% (-3 per wave)
Pacifist	Damage	-100%
	Engineering	-100
Saver	Items Price	-50%
Sick	HP Regeneration	-100
Ghost	Armor	-100
Speedy	Armor while standing still	-100
Doctor	Attack Speed	-100%
Artificer	Damage	-100%
Masochist	Damage	-100%

Item Costs

Item costs for each tier in vanilla are as follows:

Tier	Min	Max
Tier 1	8	30
Tier 2	35	65
Tier 3	50	95
Tier 4	80	120

Weapon Costs

Weapon costs for each tier in vanilla. There are 3 different "Max" columns, because weapons that only start from tiers 2/3 have considerably higher max prices than weapons that start from tier 1.

Tier	Min	Max	Max T2	Max T3
Tier 1	10	20		-
Tier 2	22	39	56	-
Tier 3	45	74	103	144
Tier 4	91	149	207	289

Community Guide

Here's a guide written by a community member about balancing: Modding Balance Guide.

DebugService

You can use DebugService to edit your items, weapons, starting materials, and much more:

Option	Type	Default	Effect	Notes
debug_weapons	array	[]	Weapons to add at the start of each wave.	Unlike debug_items, these weapons are always added. Great for testing tier stacking. Not helpful if you only want 1 instance of the weapon though.
debug_items	array	[]	Items to add once, at the start of the next wave.	Can add multiple of the same item
starting_wave	int	1	Sets initial wave. Supports 1 - 20
starting_gold	int	30	Sets initial materials
invulnerable	bool	false	Disables your hurtbox	Prevents things like Bull's effect from triggering
instant_waves	bool	false	Waves only last 1 second	Great for testing shops
add_all_items	bool	false	Adds every item to your character	Can be combined with debug_items to stack them
add_all_weapons	bool	false	Adds every weapon	Can go over your character's weapon limit
unlock_all_chars	bool	false	Unlocks all characters	Temporary
unlock_all_challenges	bool	false	Unlocks all challenges	Permanent. Completes every challenge, unlocks their Steam achievements, and saves this data to your save file.
unlock_all_difficulties	bool	false	Unlocks all danger levels	Temporary
no_weapons	bool	false	Removes all weapons	Triggers at the start of each wave

Note: DebugLoader lets you edit these settings via JSON, which can be useful for testing outside of the Godot editor.

Effects

See Modding Effects for a list of all the effects available in vanilla.

Text - BBCode

You can use some BBCode in your item descriptions. View the available options in the Godot docs.

Related Files

These files are related to text, and mostly apply colors:

• singletons/text.gd
• weapons/weapon_stats/weapon_stats.gd
  • In this file, col_pos_a means "color positive, part A", with part B being the closing [/color]
• singletons/utils.gd
  • This file also sets the icon size (see Image Icons below)
• ui/menus/shop/item_description.gd
  • Sets weapon and item descriptions. It's a good place to start if you're looking for the code that handles them.
• items/global/effect.gd
  • Has the function get_text, which modifies stats used by effects

Color Options

For programming (ie. not BBCode), see also: Color class; color constants cheatsheet.

Code	Color	Example	Notes	Via
[color=#00ff00]TEXT[/color]	Green	TEXT		Utils.POS_COLOR_STR
[color=red]TEXT[/color]	Red	TEXT		Utils.NEG_COLOR_STR
[color=white]TEXT[/color]	White	TEXT		Color.white
[color=#555555]TEXT[/color]	Grey	TEXT		Utils.GRAY_COLOR_STR
[color=#76FF76]TEXT[/color]	Materials	TEXT	Actually rgb(118,255,118)	Utils.GOLD_COLOR
[color=#EAE2B0]TEXT[/color]	Secondary	TEXT	Actually rgb(234,226,176)	Utils.SECONDARY_FONT_COLOR
[color=#C8C8C8]TEXT[/color]	Tier 1	TEXT		NA
[color=#4A9BD1]TEXT[/color]	Tier 2	TEXT	Actually rgb(74,155,209)	ItemService.TIER_UNCOMMON_COLOR
[color=#AD5AFF]TEXT[/color]	Tier 3	TEXT	Actually rgb(173,90,255)	ItemService.TIER_RARE_COLOR
[color=#FF3B3B]TEXT[/color]	Tier 4	TEXT	Actually rgb(255,59,59)	ItemService.TIER_LEGENDARY_COLOR

Image Icons

You can add an image with the code [img=20x20]res://path_to_image/file.png[/img].

• The size 20x20 applies to the default font size (100%).
  • At the minimum font size of 80%, the image size is 16x16.
  • At the maximum of 125%, the image size is 25x25.

• If you want to show scaled stat icons, you can use Utils.get_scaling_stat_text(stat_name) (see singletons/utils.gd).
  • The code in this func also shows how to get a scaled size for a custom image (var w = 20 * ProgressData.settings.font_size)

Here's the code for showing stat icons, when the Font Size option is set to its default 100%:

BBCode for stat icons

BBCode	Icon	Stat Name
[img=20x20]res://items/stats/max_hp.png[/img]		Max HP
[img=20x20]res://items/stats/hp_regeneration.png[/img]		HP Regeneration
[img=20x20]res://items/stats/lifesteal.png[/img]		Life Steal
[img=20x20]res://items/stats/percent_damage.png[/img]		Damage
[img=20x20]res://items/stats/melee_damage.png[/img]		Melee Damage
[img=20x20]res://items/stats/ranged_damage.png[/img]		Ranged Damage
[img=20x20]res://items/stats/elemental_damage.png[/img]		Elemental Damage
[img=20x20]res://items/stats/attack_speed.png[/img]		Attack Speed
[img=20x20]res://items/stats/crit_chance.png[/img]		Crit Chance
[img=20x20]res://items/stats/engineering.png[/img]		Engineering
[img=20x20]res://items/stats/range.png[/img]		Range
[img=20x20]res://items/stats/armor.png[/img]		Armor
[img=20x20]res://items/stats/dodge.png[/img]		Dodge
[img=20x20]res://items/stats/speed.png[/img]		Speed
[img=20x20]res://items/stats/luck.png[/img]		Luck
[img=20x20]res://items/stats/harvesting.png[/img]		Harvesting

Misc

For line breaks, use "\n".

To hide an item description, set the effect key to [EMPTY].

Limitations

Bold ([b]) and italics ([i]) don't work, because the vanilla game doesn't have support for them.

Text - Stats

Dynamic Stats

Item descriptions in the shop are retrieved the first time it appears, so any dynamic stats will need to account for this. It might mean that the stats your item shows are different once the item is bought.

They're also retrieved every time you hover over an item (via get_args), which gives you more freedom to use dynamic stats than the shop descriptions.

get_args

Use get_args to pass variables to your item descriptions. They replace {0}, {1}, etc, with each item in the array that get_args returns acting as a replacement for the matching {index} string in your translation.

The default effect (effect.gd) only passes 1 arg, value (0), which is converted from an int to string with str(value).

Most custom effects (eg. stat_effect.gd) pass 2 args: value (0) and key (1), with key being translated using tr(key.to_upper()).

You can use key_text to apply a custom effect description.

As mentioned above, you can also hide an item's description by setting the key_text to [EMPTY].

Translations

Guide

Here's a mini guide for using translations. It was published on Discord by Aequitas.

1. Create your CSV translation file
2. Drag it into your project's file system
3. Select the Import tab (screenshot here) and click reimport -- the .en.translation files should be created
4. Go to Project > Project Settings > Localization (tab)
5. Click add, and add your custom.en.translation file

Here's how your CSV should look:

Translation Notes

See Godot's tutorial Internationalizing games for more info on using translations. You may also find the docs on TranslationServer helpful.

You can use tr() to access translated strings. It's a native function.

To use commas, wrap your string in quotes, eg: "Potatoes are good, potatoes are cool"

Item Tags

The following item tags are used in vanilla:

Stats	Misc
stat_armor	economy
stat_attack_speed	exploration
stat_crit_chance	explosive
stat_dodge	less_enemies
stat_elemental_damage	less_enemy_speed
stat_engineering	more_enemies
stat_harvesting	pickup
stat_hp_regeneration	saving
stat_lifesteal	stand_still
stat_luck	xp_gain
stat_max_hp
stat_melee_damage
stat_percent_damage
stat_range
stat_ranged_damage
stat_speed

Multi Mod

If you're building a mod, creating it to work with dami's Multi Mod might be worth considering. It lets you add your mod pack to any compatible mod (eg. Invasion/dami's Arsenal). It lets you create custom characters, weapons, and items, and release your mod as a small standalone file (usually <3mb).

The only caveat is that you can't touch vanilla code, and can't currently add new weapon classes or challenges.

Weapon Cooldowns

Calculating the displayed cooldown text is tricky. The formula for Ranged weapons is easy to calculate, but the Melee formula is complex and takes many things into consideration. For this reason, Darkly77 made an cooldown text calculator, here:

Cooldown Calculator

Weapon Notes

Weapon stats have an option called increase_projectile_speed_with_range. In vanilla, this is only used by Flamethrower and Incendiary Turret, as their flame projectiles don't interact with Range in the usual way. So this option just makes their projectiles go further, because they're moving faster. Search for this var in weapon_service.gd to see the formula.

GitHub

There's a GitHub organisation for Brotato repos here. It is maintained by Darkly77, KANA, and dami, who are all active on the Space Potatoes Discord.

It's not recommended to host a full Brotato project on GitHub, because you'd be making all of Brotato's source code public. But you can host just your modded files (eg Darkly77's Invasion), or even just host the downloads for your mod (eg. KANA's mod releases)

Hosting your downloads on GitHub has a few advantages:

• You can create versioned README and CHANGELOG files to track your mod's changes.
• You can create separate releases, which track the release date.
• You can view download stats with this tool.