Gallery

The Gallery plugin is for a game's EXTRA screens: a CG gallery, scene recollection, music appreciation and voice extras. You list what those screens hold in Studio's Gallery editor, and these nodes return that list, combined with what the player has unlocked, as rows a List widget draws directly. The plugin ships disabled; see Built-in plugins.

The Extra screen of a project created from the Skeleton template is built from these nodes: one Get Gallery per column, Get Gallery Progress for its progress line, and Get Gallery Variants with Get Gallery Variant At for its CG viewer.

The catalog

• Entry. One item on an EXTRA screen: a CG, a recollection, an album or a voice set. Every entry has a kind, cg, scene, music or voice, shown in Studio as CG, Recollection, Music and Voice. The kind is the column the entry belongs to. Node cards and pins call an entry an artwork: the Artwork field, the artworkId pin.
• Variant. One member of an entry: a differential of a CG, a picture of a recollection, a track of an album, a line of a voice set. The player unlocks variants. An entry counts as unlocked as soon as any of its variants is.
• Cover. The variant that stands for the entry: the one you star, otherwise the first.
• Group. An optional category across all kinds, for a tab bar. An entry belongs to one group or to none.
• Locked look. While an entry is locked, its rows carry a placeholder picture instead of its art and the locked title instead of its name, and its description, audio, voice and scene fields are empty. The placeholder is the entry's own, or the catalog's default. The locked title is ??? until you change it; an empty title shows the real name.
• Hidden entry. An entry marked hidden is left out of Get Gallery rows and progress totals until the player unlocks it, so a secret entry does not show as an empty slot.

With the plugin on, the activity bar has a Gallery tool that lists the entries. Choosing an entry, or the expand button in the tool's header, opens the Gallery editor as a tab.

The editor has one column per kind. The add button changes with the column: Import CGs makes one entry per picked image, Import Tracks makes one album of the picked tracks, and Add Recollection and Add Voice Lines make an empty entry whose scene or lines you pick in the inspector. Groups are the chips under the columns; New group adds one. The inspector edits an entry's name, description, group and variants, whether it is Shown as a locked slot or Hidden until unlocked, and its own locked placeholder. The header button How locked entries look in game sets the catalog's Default placeholder and Locked title.

The catalog is saved with the project and packed with the game.

In a project with a second language, each entry's name and description, each variant's name, each group's name and the locked title have rows in the translation table, under Interface text and the plugin's name. The nodes return them in the player's language, and the words as written until a row is translated. The locked look applies to the translated names as it does to the names as written.

Unlocking

What unlocks a variant depends on its kind. The editor's inspector says the same for each column while nothing is selected.

The unlock record is kept in the player's persistent data, beside persistent variables, and in no save file. Starting a new game does not reset it, and loading a save does not change it. Lock Whole Gallery clears it. In Studio, Reset player data clears it for Dev Mode or for Preview, together with their saves.

The record holds variant ids, which the editor assigns, and the entry's own id for an entry that has no variants yet. Renaming or reordering a variant keeps its unlock. Deleting a variant and adding the same picture again makes a new variant, which starts locked.

An entry with no variants yet is unlocked and locked as a whole: reaching a recollection's scene, Unlock Gallery, Lock Gallery and Unlock Whole Gallery all reach it. A recollection starts with no pictures, so reaching its scene unlocks it before it has one, and the pictures added to it later count as unlocked for that player.

Conventions

• Every node has exec pins. None is Pure, and a Blueprint Value offers none of them. Run them from an event graph and hand what they return to a List or a variable. All but Get Gallery Groups are Latent.
• A wired pin wins over the card. artworkId, variantId and groupId override the card's Artwork, Variant and Group when they carry a non-empty string. The card picks by name while you author; the pins take the ids rows carry, which is how a row the player clicks drives a viewer.
• Rows are masked already. Lock state is applied inside each row, so an item template draws whatever it is given and cannot show a locked entry's art by mistake.
• Rows feed a List. Wire entries into Set List Content, and set the List's Struct under Edit content to Gallery entry, Gallery variant or Gallery group (see Lists). The widgets in the item template then pick the fields by name, and Get Field reads one in a blueprint. These structs are known while the Gallery plugin is enabled.
• An entry the node cannot find fails it. With no entry picked on the card and nothing on artworkId, a node fails with Pick a gallery artwork. An id the catalog does not hold fails with Gallery artwork not found: <id>.
• Where they run. In the editor canvas the nodes read the catalog as you are editing it, with nothing unlocked, and an unlock or lock changes nothing. In Dev Mode, Preview and the built game they read the catalog packed with the game.
• A game with no catalog. When the game carries no gallery catalog (the project never saved one), the plugin logs No gallery catalog was published with this game. once. Get Gallery and Get Gallery Groups return empty arrays, Get Gallery Progress returns zeros, and every node that names an entry fails.

Get Gallery

narraleaf.gallery.getEntries · Latent

The catalog's entries as rows, in the editor's order, narrowed by kind and group. A hidden entry the player has not unlocked is left out.

On-card fields

Entry fields

Get Gallery Variants

narraleaf.gallery.getVariants · Latent

One entry's variants as rows, in the editor's order: the differential strip of a CG viewer, an album's track list, a voice set's lines. Whether the entry is hidden does not matter here.

On-card fields

Variant fields

Get Gallery Groups

narraleaf.gallery.getGroups

The catalog's groups in the editor's order, for a tab bar. A row's id goes into the groupId pin of Get Gallery or Get Gallery Progress.

Get Gallery Progress

narraleaf.gallery.getStats · Latent

Completion figures for a screen's header, narrowed by kind and group the way Get Gallery is. A hidden entry counts only once it is unlocked, so a secret entry does not show in the total.

On-card fields

Unlock Gallery

narraleaf.gallery.add · Latent

Unlocks one variant of an entry, or every variant of it when no variant is named.

On-card fields

A variant id that is not one of the entry's variants changes nothing.

Lock Gallery

narraleaf.gallery.remove · Latent

Locks one variant of an entry again, or every variant of it when no variant is named. The pins and fields are those of Unlock Gallery.

On-card fields

Unlock Whole Gallery

narraleaf.gallery.unlockAll · Latent

Unlocks every variant of every entry, hidden entries included: the reward for finishing the game, and a quick way to see a gallery screen filled while you build it.

Lock Whole Gallery

narraleaf.gallery.clear · Latent

Clears the unlock record, which locks every entry again. The record is in no save file, so loading a save does not bring the unlocks back.

Is Gallery Unlocked

narraleaf.gallery.isUnlocked · Latent

With a variant named, whether that variant is unlocked. With none, whether any variant of the entry is (for an entry with no variants yet, whether the entry is), which is the question a grid cell asks.

On-card fields

Get Gallery Variant At

narraleaf.gallery.getVariant · Latent

One variant by position, for a viewer that steps to the previous or next differential. The position counts every variant in the editor's order, locked ones included.

On-card fields

A position outside the entry gives null, false and empty strings.

Hidden nodes

Four older nodes read the catalog one item at a time. They are hidden from the palette, superseded by the array nodes above, and still run in graphs that hold them.

Get Gallery Variant Count

narraleaf.gallery.getVariantCount

Superseded by the count of Get Gallery Variants. Counts every variant of the entry, locked ones included.

Get Gallery Cover

narraleaf.gallery.getCover · Latent

Superseded by the image and name fields of a Get Gallery row. Reads the entry's cover only: image is null and unlocked is false until the cover variant itself is unlocked, and name is the locked title until then.

Get Gallery Artwork Count

narraleaf.gallery.getArtworkCount

Superseded by the count of Get Gallery. Counts every entry in the catalog, of every kind, hidden entries included.

Get Gallery Artwork At

narraleaf.gallery.getArtworkAt · Latent

Superseded by Get Gallery. One entry by position over the whole catalog, hidden entries included, with the locked title for its name while it is locked. A position outside the catalog gives empty strings, false and 0.