# Function: addMapper() (/jsdoc/pixi-vn-ink/index/namespaces/HashtagCommands/functions/addMapper)



\> **addMapper**(`handler`, `opts`): `void`

Defined in: [src/handlers/hashtag-commands.ts:146](https://github.com/DRincs-Productions/pixi-vn-ink/blob/c61af08e067878c4529bcc48dc32c8ef72ffc487/src/handlers/hashtag-commands.ts#L146)

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

Mappers are evaluated in registration order by
[HashtagCommands.convertOperation](/jsdoc/pixi-vn-ink/index/namespaces/HashtagCommands/functions/convertOperation) **before** the built-in `switch` table.  The
first mapper whose [HashtagHandlerOptions.validation](/jsdoc/pixi-vn-ink/index/interfaces/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](/jsdoc/pixi-vn-ink/index/namespaces/HashtagCommands/functions/add) when you want to extend or override the built-in
command → operation translation without intercepting the full handler pipeline.

## Parameters [#parameters]

### handler [#handler]

[`MapperHandler`](/jsdoc/pixi-vn-ink/index/type-aliases/MapperHandler)

A [MapperHandler](/jsdoc/pixi-vn-ink/index/type-aliases/MapperHandler) that receives the full token list and the current
step, and returns either a PixiVNJsonOperation or `undefined`.

### opts [#opts]

[`HashtagHandlerOptions`](/jsdoc/pixi-vn-ink/index/interfaces/HashtagHandlerOptions)

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

## Returns [#returns]

`void`

## Example [#example]

```ts title="content/ink/hashtag-commands.ts"
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()]),
    },
)
```