Gallery

Gallery is a built-in service specifically designed for visual novel game galleries (image collections). It allows you to add, remove, and check for items, with support for serialization/deserialization.

Gallery is suitable for managing image collection systems in games, such as character portraits, CG images, background images, etc.

import {Gallery} from "narraleaf-react";

Basic Usage

Creating a Gallery

const gallery = new Gallery<{timestamp: number}>();
 
scene.action([
  gallery.add("item", () => ({
    timestamp: Date.now(),
  }))
]);

Registering the Service

To use Gallery, you need to register it in the story:

story.registerService("gallery", gallery);

After registering, you can access the Gallery using the game context:

const liveGame = useLiveGame();
 
const gallery = liveGame.story?.getService<Gallery<{timestamp: number}>>("gallery");
 
if (gallery) {
  console.log("All items in the gallery:", gallery.$getAll());
}

Complete Example

const gallery = new Gallery<{timestamp: number, description: string}>();
 
scene.action([
  gallery.add("item1", {
    timestamp: Date.now(),
    description: "First item"
  }),
  
  gallery.add("item2", (ctx) => ({
    timestamp: Date.now(),
    description: "Dynamically created item"
  })),
  
  Condition.If(gallery.has("item1"), [
    "Item 1 is unlocked!",
  ]),
  
  gallery.remove("item1"),
  
  gallery.clear()
]);

Chainable Methods

These methods need to be used within scene.action and return operation objects that can be chained together.

add

Add an item to the gallery

scene.action([
  gallery.add("item", {
    timestamp: Date.now(),
    description: "Item description"
  })
]);
 
// or using a function
scene.action([
  gallery.add("item", (ctx) => {
    return {
      timestamp: Date.now(),
      description: "Dynamic item"
    };
  })
]);

name: string - The name of the item to add
metadata: Metadata | ((ctx: ScriptCtx) => Metadata) - The metadata of the item, can be an object or a function that returns metadata

remove

Remove an item from the gallery

scene.action([
  gallery
    .remove("item")
    .remove("item2"),
]);

name: string - The name of the item to remove

clear

Clear the gallery

scene.action([
  gallery.clear()
]);

Public Methods

These methods prefixed with $ execute immediately and don't need to be used within scene.action. They are specifically designed for directly manipulating gallery data during game runtime.

has

Check if an item exists in the gallery

Condition.If(gallery.has("item"), [
    "Item is unlocked!",
    // ...
])

name: string - The name of the item to check
Returns Lambda<boolean> - Returns true if the item exists, false otherwise

$add

Add an item to the gallery immediately

gallery.$add("item", {
  timestamp: Date.now(),
  description: "Immediately added item"
});

name: string - The name of the item to add
metadata: Metadata - The metadata of the item

$remove

Remove an item from the gallery immediately

gallery.$remove("item");

name: string - The name of the item to remove

$clear

Clear the gallery immediately

gallery.$clear();

After calling this method, the gallery will be empty immediately.

$get

Get the metadata of an item

const metadata = gallery.$get("item");
console.log(metadata?.timestamp);

name: string - The name of the item to get the metadata of
Returns Metadata | undefined - The metadata of the item

$set

Set the metadata of an item

gallery.$set("item", {
  timestamp: Date.now(),
  description: "Updated description"
});

name: string - The name of the item to set the metadata of
metadata: Metadata - The metadata to set

$getAll

Get all items in the gallery

const allItems = gallery.$getAll();
console.log("All items:", allItems);

Returns Record<string, Metadata> - All items in the gallery

$has

Check if an item exists in the gallery

if (gallery.$has("item")) {
  console.log("Item exists");
}

name: string - The name of the item to check
Returns boolean - Returns true if the item exists, false otherwise

Type Parameters

Metadata

Gallery accepts a generic parameter Metadata to define the type of item metadata:

// Define metadata type
type ItemMetadata = {
  timestamp: number;
  description: string;
  unlocked: boolean;
};
 
// Create Gallery with type constraints
const gallery = new Gallery<ItemMetadata>();
 
// Now all methods will have type checking
gallery.add("item", {
  timestamp: Date.now(),
  description: "Description",
  unlocked: true
});

Video Animation