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. With no binding, the rows written in the inspector's List content stand in, and with no rows there either, as many rows of default field values as Placeholder rows sets. 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. Every mutation suspends the graph until it resolves.
• 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 row in reach. The three Get List Item … nodes and Get List Item Props appear only where a row can be in scope: in blueprints owned by an element inside the List's item template, where they read the item scope that element is currently rendering under; in the List's own blueprint, where Item Click, Item Hover, Item Render and Selection Changed each run for one row; and in a component definition's blueprints, since a placement of the component can sit in a row. A fn called from a row through Call Fn carries that row, so these nodes read it inside the fn body too.
• One field of the row is read with Get Field. It is in Data and offered in every blueprint. Left unwired in the places above, it reads the current row. It was named Get Item Field and filed under List.
• The field nodes name a declared field, not a JSON path. Get 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.
• Rows carry the List's struct. The struct is set under Edit content on the List (see Lists). Get List Content, Get Item At, Find Item By Field, Get Selected Item and the item of the item heads give rows of that struct, so a wire dragged off Item Click's item on an ending list offers an ending's fields. For the Element versions, which take a list pin, the struct is that of the List wired in.
• Rows that lack the List's fields are reported. Set List Content, Append List Item, Insert List Item, Remove List Item and Set Selected Item take rows of the List's struct. Rows that lack a field the List declares, or carry it as another type, are a warning on the canvas and the project check List fields do not match (blueprint/list-shape-mismatch): the List draws those fields empty. Rows with more fields than the List declares are accepted. Only nodes whose two structs are both known are checked.
• The visible and enabled nodes are two families. While the palette is browsed, Get Visible and Get Enabled are one row, Get Visible or Enabled, and Set Visible and Set Enabled are Set Visible or Enabled. A search finds each node by its own name, and the ▾ beside a placed card's title switches between the two. See Node families.

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 / List content / Placeholder rows 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.

To read one field of the row being rendered, use Get Field with Object left unwired. It works inside a Blueprint Value as these nodes do, which is how one Text element in the template shows a different string per row.