Upgrade

Run upgrades: ids you unlock during a run, defined under configuration.upgrades. The first time you gain an upgrade, its invocations run (one-shot effects, unlocks, rule attachments, etc.). Stackable definitions can accumulate quantity; the service tracks totals for UI and rules.

State (Ephemeral)

Path	Purpose
`Ephemeral.upgrades`	Owned list, stack fields (`currentCount` / `quantity`), and denormalized counters (`listCount`, `totalStackQuantity`, …)

Each list item is an object with upgradeId, stack fields such as currentCount / quantity, plus fields merged from configuration.upgrades[upgradeId] for UI and rules. totalStackQuantity on Ephemeral.upgrades is the sum of stack sizes (see GnosisUpgradeService).

How it looks in `ephemeral.json`

ephemeral.json


{
  "Ephemeral": {
    "upgrades": {
      "list": [],
      "listCount": 0,
      "filledSlotsCount": 0,
      "emptySlotsCount": 999999,
      "totalStackQuantity": 0,
      "maxSize": 999999,
      "allowDuplicates": true,
      "stackable": true,
      "maxStackSize": 999999
    }
  }
}

Example one stackable upgrade: "list": [ { "upgradeId": "yourUpgradeId", "currentCount": 2 } ].

Events

String ids are in GnosisUpgradeEvents (Runtime/GnosisEngine/Source/Services/Ephemeral/Services/UpgradeService/).

Event id	Kind
`REQUEST_UPGRADE_ADD`	Request
`FACT_UPGRADE_ADD`	Fact
`FACT_UPGRADE_ADDED`	Fact
`REQUEST_UPGRADE_REMOVE`	Request
`FACT_UPGRADE_REMOVE`	Fact
`FACT_UPGRADE_REMOVED`	Fact
`FACT_UPGRADE_APPLIED`	Fact

Functions

Function	Parameters
`GetList`	—
`AddUpgrade`	`upgradeId`
`RemoveUpgrade`	`upgradeId`
`HasUpgrade`	`upgradeId` → `{ upgradeId, hasUpgrade, quantity }`
`GetEligibleUpgradeIds`	—
`GetRandomEligibleUpgrade`	optional `excludeUpgradeIds` list

Statistics

Upgrade increments Statistic.IncrementCounter on the ephemeral branch for upgrades.added.total and upgrades.removed.total. When a definition has tags, it also bumps upgrades.added.tag.<tag> and upgrades.removed.tag.<tag> for each tag.

You can read totals with a dot path, e.g. ephemeral.statistics.upgrades.added.total.