Class TimbnPluginBalance

Namespace

Timbn.GraveyardKeeperTwo.Core.Framework

Assembly

Timbn.GraveyardKeeperTwo.Core.dll

Adds definitions to the game's balance tables on behalf of a plugin. The balance is where the game keeps every item, buff, quest, vendor, craft, and building, and GameBalance.Me.GetData looks them up by id. Use this for a kind of definition that has no easier Core API. Definitions are removed when the plugin unloads. Reach it through the plugin's Balance property.

public sealed class TimbnPluginBalance

Inheritance

object

TimbnPluginBalance

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Methods

Add(BalanceBaseObject)

Adds a definition to the balance. It goes in straight away if the balance has already loaded, and again every time the balance loads after that. Core keeps an added item, buff, craft or station out of every save the game writes, so the save still loads once the mod is gone. The game's lookups built from definitions follow along, so a build desk offers a new building and a station lists a new craft straight away, and a station already in the loaded save picks up a new or replaced world object definition.

public IDisposable Add(BalanceBaseObject definition)

Parameters

definition BalanceBaseObject

The definition to add. Its id must not belong to a definition the game ships.

Returns

IDisposable

A handle that removes the definition early when disposed. You don't need to keep it.

Add(BalanceBaseObject, Action<GameBalance>?)

Adds a definition like Add(BalanceBaseObject), and calls prepare with the loaded balance right before each insert. Use it when the definition needs something from the balance first, such as values copied from one of the game's items. If another plugin already holds the same id, this one replaces it in place, which is how a hot reloaded plugin takes over from its old copy.

public IDisposable Add(BalanceBaseObject definition, Action<GameBalance>? prepare)

Parameters

definition BalanceBaseObject

The definition to add. Its id must not belong to a definition the game ships.

prepare Action<GameBalance>

Called with the loaded balance just before the definition goes in, on every load. Can be null.

Returns

IDisposable

A handle that removes the definition early when disposed. You don't need to keep it.

AddCopy<T>(string, string, Action<T>?)

Adds a copy of one of the game's definitions under a new id. Every field is copied from the game's definition each time the balance loads, then edit runs on the copy, so it starts with everything the game expects and you change only what differs. For example Balance.AddCopy<ItemDef>("cook_baked_fish", "timbn_smoked_fish", fish => TimbnBalance.SetIcon(fish, "timbn_smoked_fish")).

public IDisposable AddCopy<T>(string templateId, string id, Action<T>? edit = null) where T : BalanceBaseObject, new()

Parameters

templateId string

The id of the game's definition to copy.

id string

The new definition's id. It must not belong to a definition the game ships.

edit Action<T>

Changes the copy after its fields are filled in. Can be null. The game reads an item's use effects again afterward, so a change to onUseExpressions shows.

Returns

IDisposable

A handle that removes the definition early when disposed. You don't need to keep it.

Type Parameters

T

The kind of definition, such as ItemDef, CraftDef, WGODef or BuildingDef.

AddItem(string, string, string, string, string, Action<ItemDef>?)

Adds an item copied from one of the game's, with its name and description in the loaded language and its own icon, in one call. Everything else, price, stack size and what using it does, stays the template's unless edit changes it. For example Balance.AddItem("cook_baked_fish", "timbn_smoked_fish", "Smoked Fish", "Golden and smoky.", "timbn_smoked_fish") is food that restores energy like baked fish. Core keeps the item out of every save the game writes.

public IDisposable AddItem(string templateItemId, string id, string name, string description, string iconId = "", Action<ItemDef>? edit = null)

Parameters

templateItemId string

The id of the game's item to copy.

id string

The new item's id. It must not belong to an item the game ships.

name string

The item's name. Empty leaves the text to the plugin's lang files.

description string

The item's tooltip description. Empty leaves it to the lang files.

iconId string

The item's icon, any sprite the game has or one added with Sprites.AddEmbeddedPng. Empty keeps the template's.

edit Action<ItemDef>

Changes anything else on the copy, such as its price or onUseExpressions, each time the balance loads. Can be null. It runs after the icon is set, and the game reads the item's use effects again afterward.

Returns

IDisposable

A handle that removes the item early when disposed. You don't need to keep it.

Examples

A pie worth more than the muffin it is copied from, with its text in the lang files.

Balance.AddItem("cook_muffin", "timbn_cheese_pie", "", "", "i_cheese_pie", pie => pie.basePrice = 40);

Edit<T>(string, Action<T>, Action<T>)

Changes one of the game's own definitions, such as a perk, an item, or a craft, and puts it back when the plugin unloads or the returned handle is disposed. Apply runs straight away if the balance has loaded, and again on the fresh copy each time the balance loads after that, so the change is never lost to a reload. Revert only runs on the copy apply changed, and only while that copy is still the loaded one. Keep what revert needs, such as the old value, from inside apply. Pair it with Settings.While to follow a toggle.

public IDisposable Edit<T>(string id, Action<T> apply, Action<T> revert) where T : BalanceBaseObject

Parameters

id string

The definition's id.

apply Action<T>

Makes the change. A throw is logged.

revert Action<T>

Puts the definition back the way apply found it. A throw is logged.

Returns

IDisposable

A handle that reverts the change early when disposed. You don't need to keep it.

Type Parameters

T

The definition's type, such as PerkDef, ItemDef, or CraftDef.

Examples

Raise the red tech point cap while the setting is on.

LazyExpression original = null!;
Settings.While(PluginConfig.TechPointCap, cap => cap > 999, () => Balance.Edit<GameResSystemDef>(
    "tech_red",
    resource => { original = resource.max; resource.max = new LazyExpression("5000"); },
    resource => resource.max = original));