Update List Variable

Runs on: Backend -- applies the change inside the database transaction that reads and writes the variable.

The Update List Variable effect changes a Streamer Variable or User Variable that holds a list, by applying one operation inside the same database transaction that reads and writes it. This is what makes it safe: a plain Get Variable, modify, Set Variable chain reads the list, computes a new array, then writes the whole thing back, and if two viewers trigger that chain within milliseconds of each other, the second write silently erases the first viewer's change. Update List Variable locks the row for the duration of the change, so two !join commands, or two !addpoints hits, both land.

Use it for anything shared across viewers: queues, raffle entries, join lists, and leaderboards.

Configuration

• Store: Broadcaster or Viewer. Viewer lists need the target user wired into the User input.
• Variable: the list variable to change. Only list-typed (Array<...>) variables of the selected store are offered.
• Operation:
  • Add -- appends the Item input at the list's Position (End or Start).
  • Add If Missing -- appends Item only if nothing matches Match On (or the whole item, if Match On is left as "Whole Item"). Good for !join -- a viewer can't enter twice.
  • Update Or Add -- replaces the first entry matching Match On with Item, or appends it if nothing matched.
  • Change Number Field -- object lists only. Adds Amount to Number Field on the entry whose Match On field equals Value. If nothing matches, appends a new entry with that field set to Value and Number Field set to Amount, so a leaderboard increment never loses a chatter's first point. This is the operation behind !addpoints.
  • Remove Where -- removes every entry matching Match On and Value (or every occurrence of the whole item).
  • Take First / Take Last -- removes one entry from that end of the list and outputs it on item. This is a queue pop or dequeue; fires Empty instead when the list has nothing left.
  • Keep First / Keep Last -- trims the list down to Count entries.
  • Clear -- empties the list.
• Match On: for object lists, which field identifies an entry (e.g. username). Leave it as "Whole Item" to compare entire objects where that's offered.
• Number Field: for Change Number Field, which number field to increment. Only number-typed fields are offered.
• Case Sensitive: shown when the comparison is over text. Off by default.

Inputs

Name	Type	Description
Activate	pulse	Optional. Fires the effect even when every other input is inline/static.
User	User or string	The viewer whose list entry to change. Only shown for a Viewer store.
Item	matches the list's item type	The item to add, for Add, Add If Missing, and Update Or Add.
Value	matches the Match On field's type	The key to match, for Change Number Field and Remove Where.
Amount	number	How much to add to Number Field. Defaults to 1.
Count	number	How many entries to keep, for Keep First / Keep Last. Defaults to 10.

Outputs

Name	Type	Description
Item	matches the list's item type	The entry that was added, updated, or taken.
Result	matches the variable's type	The list after the write.
Empty	matches the variable's type	Fires (carrying the empty list) when Take First / Take Last runs on an empty list.
Then	pulse	Fires after the effect runs, whether it succeeded or not. Wire it into another effect's Activate to sequence them.

Outputs only reach a downstream node through forward wiring (Then into the next node's Activate, or the data outputs into a node that's already running from the same wave). A node that only pulls Item or Result backward, without the effect having already run, gets nothing.

Example

Build a leaderboard: Array<Entry> broadcaster variable, where Entry is a custom type with username and score fields. On !addpoints <name> <amount>, use Update List Variable with Operation Change Number Field, Match On username, Number Field score, Value the chatter's name, and Amount the points to add. Two chatters awarding points in the same instant both land, because the increment happens inside the database lock instead of racing a read-then-write from the flow. For !next in a giveaway queue, use Take First on a queue: Array<string> broadcaster variable and send the popped item to chat.

Not for flow or overlay variables: those write back their whole array at the end of each run, which would clobber an atomic change from the same run. Use a Broadcaster or Viewer variable for anything shared across viewers.