List

List nodes drive the runtime content, selection, and scroll position of the list widget whose private blueprint you are editing. Reach for them when the rows are decided while the game runs — save slots, a backlog, a settings menu — instead of being authored once in the inspector. Reshaping arrays and objects before you hand them over stays in Data.

Conventions

• The runtime item array is what the List renders. Set List Content writes an instance-level runtime array; Append, Insert, Remove, Clear and Refresh update that same store. Items are stored JSON-safe, so anything that does not survive a JSON round trip is dropped on the way in.
• itemsBinding is only a fallback. The element's items binding is read while no runtime items have been written, and the inspector's preview items stand in when there is no binding either. The first write to the runtime store ends that.
• Mutations promote the fallback. Every mutation except Set List Content and Clear List reads the current items first and writes the whole array back. On a List that has never been written to, that read comes from the fallback and the write turns the snapshot into runtime items — the binding stops applying from then on.
• Unmount clears the instance. When the List instance fully unmounts, runtime items, selection, and pending scroll commands are dropped. Nothing is persisted for you; write the content to a variable or to state and restore it explicitly when the List comes back.
• Reads are pure, mutations are latent. The Get nodes run in event, function, and macro graphs. Every mutation is latent and is limited to event and macro — a function returns synchronously to its caller and has nowhere to hand a pending write.
• Content and selection writes queue a flush; scroll nodes do not. A scroll node only records an intent for the renderer to consume, so it never re-runs flush-driven work.
• These are Self nodes. They act on the list-like widget that owns the graph — nl.list, nl.notification.list, nl.choice.list, nl.nvl.list — and take no target pin. To drive a different List, use the blueprint.element.list.* twins in Element, which carry a list input and only appear once the graph holds a binding node for an nl.list.
• Item context needs a template descendant. The three Get List Item … nodes, Get List Item Props, and Get Item Field appear only in blueprints owned by an element inside the List's item template, and read the item scope that element is currently rendering under.
• The field nodes name a declared field, not a JSON path. Get Item Field, Set Item Field At, Find Item By Field, and Sort List By Field pick from the fields the List declares for its items, and the card stores the field's stable id rather than the property name — so renaming the property, or reordering the fields, costs a graph nothing. Deep paths still belong to Get JSON Field. The two writers refuse to run with no field picked; the two reads simply answer with nothing.

Set List Content

blueprint.list.setItems · Latent

Replaces the runtime item array wholesale. A value that is not an array is written as an empty array rather than rejected, so a mistyped items edge silently empties the List.

Append List Item

blueprint.list.appendItem · Latent

Reads the current items, adds one at the end, and writes the whole array back.

Insert List Item

blueprint.list.insertItem · Latent

Inserts before the given index. The index is clamped to 0…length, and an index that is not a number falls back to the end, so this never throws for an out-of-range position.

Remove List Item

blueprint.list.removeItem · Latent

Removes the first item that is JSON-equal to item — comparison is by serialized value, not by reference, so an object rebuilt with the same fields still matches. When nothing matches, the array is left untouched and execution continues through next.

Remove List Item At

blueprint.list.removeItemAt · Latent

Removes the item at the given index. An index outside 0…length-1, or one that is not a number, leaves the array untouched and continues through next.

Clear List

blueprint.list.clear · Latent

Writes an empty runtime array. It has no pins beyond the execution pair.

Refresh List Items

blueprint.list.refreshItems · Latent

Writes the current items back unchanged, which re-renders every row and refreshes the item context its descendants read. Use it when an item's contents changed underneath the array — a mutated object, a value the rows read from state — and the array itself did not.

Set Selected Index

blueprint.list.setSelectedIndex · Latent

Stores the selected index as given. It is truncated but not clamped: an index outside the current items is kept, and Get Selected Item reports null for it. An index that is not a number resolves to -1.

Set Selected Item

blueprint.list.setSelectedItem · Latent

Finds the first item JSON-equal to item and selects its index. When nothing matches, the current selection is left alone — this is a silent no-op, not an error.

Scroll To Index

blueprint.list.scrollToIndex · Latent

Queues a scroll request for the given row. Negative and non-numeric indices resolve to 0.

Scroll To Top

blueprint.list.scrollToTop · Latent

Queues a scroll request for the start of the List.

Scroll To Bottom

blueprint.list.scrollToBottom · Latent

Queues a scroll request for the end of the List. Pair it with Append List Item to keep a log pinned to its newest row.

Set Visible

blueprint.list.setVisible · Latent

Sets the widget's runtime visibility. This is the authored visible property, not the Displayable render switch — see Set Display in Displayable when you want the element to stay mounted behind display: none.

Set Enabled

blueprint.list.setEnabled · Latent

Turns runtime interaction on or off for the List.

Set Item Field At

blueprint.list.setItemFieldAt · Latent

Writes one field of one row, leaving the rest of that row and the rest of the list alone. The row is rewritten rather than edited in place — the list hands its content out as a copy, so mutating what you read would change nothing anybody renders.

On-card fields

A row that is not there is a quiet no-op rather than an error: a graph writing into the row it was just handed is the ordinary case, and a list that shrank underneath it should not stop the chain.

Sort List By Field

blueprint.list.sortByField · Latent

Reorders the runtime items by one of their fields and writes the result back. Sorting is a write, so the fallback is promoted the way every other mutation promotes it.

On-card fields

Get List Content

blueprint.list.getItems · Pure

Outputs the runtime item array, or the itemsBinding / preview fallback while nothing has been written.

Get Selected Index

blueprint.list.getSelectedIndex · Pure

Outputs the runtime selected index, falling back to the element's authored selectedIndex.

Get Selected Item

blueprint.list.getSelectedItem · Pure

Outputs the item at the selected index, or null when that index falls outside the current items.

Get List Length

blueprint.list.getLength · Pure

How many rows the List currently holds.

Get Item At

blueprint.list.getItemAt · Pure

One row by index, without pulling the whole array through Get List Content.

Find Item By Field

blueprint.list.findItemByField · Pure

Looks a row up by one of its fields — the save slot whose id is "auto", the language row whose code matches the current locale.

On-card fields

Get Scroll Progress

blueprint.list.getScrollProgress · Pure

Where the List is scrolled to, as 0–1.

The Scroll head tells a graph that the List has moved; these four tell a graph where it ended up. The difference matters to anything triggered by something other than the List — a wheel handler on the page around it cannot be told, it has to ask — and mirroring the head's answer into a variable instead is the shape that silently goes stale.

Get Scroll Offset

blueprint.list.getScrollOffset · Pure

The same position in pixels, with the distance there is to travel.

Is Scrolled To Start

blueprint.list.isScrolledToStart · Pure

Is Scrolled To End

blueprint.list.isScrolledToEnd · Pure

Both edges are decided from one definition of "as far as this axis goes", so they and Get Scroll Progress cannot disagree — which is what lets a "jump to newest" button hide itself exactly when the backlog is already at the bottom.

Get Visible

blueprint.list.getVisible · Pure

Get Enabled

blueprint.list.getEnabled · Pure

Get List Item Props

blueprint.list.getItemProps · Pure

Outputs the item the current row is rendering: the item itself when it is an object, otherwise { value: item }, so a List of plain strings still gives you a field to read. Outside item context it outputs { value: null }.

Get List Item Index

blueprint.list.getItemIndex · Pure

Outputs the current row's index. Outside item context it outputs -1.

Get List Item Count

blueprint.list.getItemCount · Pure

Outputs the number of rows in the current render pass. Outside item context it outputs 0.

Get List Item Key

blueprint.list.getItemKey · Pure

Outputs the row's key: the value at the List's itemKeyPath when that value is a string or a number, and the row index as a string otherwise. Outside item context it outputs an empty string.

Get Item Field

blueprint.list.getItemField · Pure

One declared field of the row being rendered. The narrow form of Get List Item Props: pick the field on the card instead of reading the whole item and digging a key out of it, and the graph stops depending on what the property happens to be called.

On-card fields

Item context, like the three Get List Item … reads above — and like them it works inside a Blueprint Value, which is how one Text element in the template shows a different string per row.