IRpgCharactersApi

Interface

TheOmenDen.StreamPulse.Scripting.IRpgCharactersApiViewer RPG characters from a script (ctx.Rpg.Characters, spec 061/062). Read (existence + snapshot, inventory, fortune, pending modifier) plus the per-viewer play mutations (grant / consume), all dispatching the same Mediator handlers the chat/node/desktop paths run (parity). Every method is failure-safe: a not-joined viewer, an unavailable/gated RPG store, or any error yields null/ false/an empty list, never a throw.

Members

AddXpAsync

method

ValueTask<RpgAddXpInfo> AddXpAsync(string twitchUserId, long amount, CancellationToken cancellationToken = default)

Grants XP to a joined viewer and applies any level-ups, or null on failure (spec 064).

AllocatePointAsync
method
```
ValueTask<RpgProgressionInfo> AllocatePointAsync(string twitchUserId, string stat, int amount = default, CancellationToken cancellationToken = default)
```
Spends amount points into stat (blank / "fortune" targets Fortune) for a joined viewer, or null over the cap / over the pool / on an unknown stat / on failure (spec 064).
ConsumeItemAsync
method
```
ValueTask<bool> ConsumeItemAsync(string twitchUserId, string itemSlug, CancellationToken cancellationToken = default)
```
Uses a consumable the viewer holds (applies its effects). False when not held / not usable / on failure.

ExistsAsync

method

ValueTask<bool> ExistsAsync(string twitchUserId, CancellationToken cancellationToken = default)

True when the viewer has an RPG character (i.e. has joined).

GetAsync

method

ValueTask<RpgCharacterInfo> GetAsync(string twitchUserId, CancellationToken cancellationToken = default)

The viewer's character, or null when they haven't joined (or RPG is unavailable).

GetFortuneAsync
method
```
ValueTask<int> GetFortuneAsync(string twitchUserId, CancellationToken cancellationToken = default)
```
The viewer's luck (Fortune) value used to shape loot rolls. 0 when RPG is unavailable.

GetInventoryAsync

method

ValueTask<IReadOnlyList<RpgInventoryItem>> GetInventoryAsync(string twitchUserId, CancellationToken cancellationToken = default)

The viewer's inventory holdings (rarest first), or an empty list when not joined / unavailable.

GetLevelAsync

method

ValueTask<int> GetLevelAsync(string twitchUserId, CancellationToken cancellationToken = default)

The viewer's current level; 0 when not joined / unavailable (spec 064).

GetPendingModifierAsync

method

ValueTask<RpgPendingModifierInfo> GetPendingModifierAsync(string twitchUserId, CancellationToken cancellationToken = default)

The viewer's single pending one-shot next-fight modifier, or null when none is set.

GetProgressionAsync
method
```
ValueTask<RpgProgressionInfo> GetProgressionAsync(string twitchUserId, CancellationToken cancellationToken = default)
```
The viewer's progression (level, XP toward the next level, Fortune, unspent points), or null when not joined / unavailable (spec 064).

GrantItemAsync

method

ValueTask<bool> GrantItemAsync(string twitchUserId, string itemSlug, int quantity = default, CancellationToken cancellationToken = default)

Grants quantity of an item to a joined viewer (stacking). False on any failure.

GrantPointsAsync

method

ValueTask<RpgProgressionInfo> GrantPointsAsync(string twitchUserId, int amount, CancellationToken cancellationToken = default)

Grants unspent allocation points to a joined viewer, or null on failure (spec 064).

RespecAsync
method
```
ValueTask<RpgRespecInfo> RespecAsync(string twitchUserId, CancellationToken cancellationToken = default)
```
Respecs a joined viewer (debits the cost, refunds spent points, resets stats), or null when unaffordable / on cooldown / on failure (spec 064).