Choice menus

In the visual novel, usually, there are choice menus that allow the player to make decisions that will affect the story.

In Pixi'VN, there is the option to prompt the player to make a choice. Each choice can either start a label or close the choice menu.

Require the player to make a choice

To require the player to make a choice, you can set narration.choiceMenuOptions with an array of StoredChoiceInterface. For create a StoredChoiceInterface object, you can use:

• newChoiceOption
• newCloseChoiceOption

import { newChoiceOption, newCloseChoiceOption, narration, newLabel } from "@drincs/pixi-vn"

export const startLabel = newLabel("start_label",
    [
        async () => {
            narration.dialogue = "Choose a fruit:"
            narration.choiceMenuOptions = [ 
                newChoiceOption("Orange", orangeLabel, {}), // by default, the label will be called by call
                newChoiceOption("Banana", bananaLabel, {}, { type: "jump" }), 
                newChoiceOption("Apple", appleLabel, { quantity: 5 }, { type: "call" }), 
                newCloseChoiceOption("Cancel"), 
            ] 
        },
        () => { narration.dialogue = "Restart" },
        async (props) => await narration.jumpLabel("start_label", props)
    ],
)

Create a choice menu option

In Pixi'VN you can create choice menu option using newChoiceOption function.

newChoiceOption is a function which has as parameters:

• text: The text that will be displayed in the choice menu.
• label: The label which will be called when the player chooses the option.
• props: The properties that will be passed to the label, if the label not need any parameter you can pass an empty object {}.
• options:
  • type: The way the label will be called. It can be call or jump. Default is call.
  • oneTime: If true, the choice can only be made once.
  • onlyHaveNoChoice: If true, the choice can see only if there are no other choices.
  • autoSelect: If true and if is the only choice, it will be selected automatically.

Create a close choice menu option

In addition to newChoiceOption there is also another function newCloseChoiceOption that allows you to create a closing option. Its operation consists in closing the menu of choices and continuing with the steps, without having to call any label.

newCloseChoiceOption is a function which has as parameters:

• text: The text that will be displayed in the choice menu.
• options:
  • closeCurrentLabel: If true, the current label will be closed. Default is false.
  • oneTime: If true, the choice can only be made once.
  • onlyHaveNoChoice: If true, the choice can see only if there are no other choices.
  • autoSelect: If true and if is the only choice, it will be selected automatically.

Get the user requested choice options

To get the choice menu, you can use narration.choiceMenuOptions. The result is an array of newChoiceOption and/or newCloseChoiceOption.

const menuOptions: StoredChoiceInterface[] = narration.choiceMenuOptions;

Select a choice

To select a choice, you can use narration.selectChoice.

const item = narration.choiceMenuOptions![0]; // get the first item of the menu

narration.selectChoice(item, {
    // add StepLabelProps here
    navigate: navigate, // example
    // and the props that will be passed to the label
    ...item.props
})
    .then(() => {
        // ...
    })
    .catch((e) => {
        // ...
    })

Clear the choice menu

To clear the choice options, you can use narration.choiceMenuOptions = undefined.

narration.choiceMenuOptions = undefined;

Custom the choice menu option

You can customize the choice menu option by adding additional properties to the ChoiceInterface interface. For example, you can add a icon property to add an icon to the choice menu option.

To do this, you need "override" the ChoiceInterface interface in the .d.ts file.

declare module '@drincs/pixi-vn' {
    interface ChoiceInterface {
        icon?: string
    }
}

How to create the choice menu UI screen

For example:

( It's in basic html, you will need to replace the basic html elements with UI components from your favorite library to improve the graphics. )