Function: addMapper()

> addMapper(handler, opts): void

Defined in: src/handlers/hashtag-commands.ts:145

Registers a new mapper that converts a specific Hashtag-Command pattern into a PixiVNJsonOperation.

Mappers are evaluated in registration order by HashtagCommands.convertOperation before the built-in switch table. The first mapper whose HashtagHandlerOptions.validation matches the raw token list is called and its return value is used as the operation; subsequent mappers (and the built-in switch) are skipped.

Use addMapper instead of add when you want to extend or override the built-in command → operation translation without intercepting the full handler pipeline.

Parameters

handler

MapperHandler

A MapperHandler that receives the full token list and the current step, and returns either a PixiVNJsonOperation or undefined.

opts

HashtagHandlerOptions

Configuration including a name, optional description, and the validation rule used to select this mapper.

Returns

void

Example

import { HashtagCommands } from 'pixi-vn-ink'
import { z } from 'zod'

// Handle: # navigate scene_name
HashtagCommands.addMapper(
    (list, step) => {
        step.labelToOpen = { label: list[1], type: "jump" }
        step.goNextStep = undefined
        return undefined
    },
    {
        name: "navigate-command",
        validation: z.tuple([z.literal("navigate"), z.string()]),
    },
)