Value maps¶

A value map rewrites a captured value into something else before it is used in an action, so one action string can serve many values.

A capture stores what you said, such as lancemate two. That text is rarely the key name you want to press. A [command.map.<capture>] table remaps each value to its replacement, and the mapped value is what gets substituted into the action.

How it works¶

Each entry under [command.map.<capture>] is spoken_value = replacement. A value with no entry passes through unchanged. Each capture is mapped independently, so a command with two captures can carry two maps.

The order of resolution is fixed:

Amri works out the captures from what you said.
Synonyms fold spoken variants onto canonical values.
A value branch is selected, keyed on the canonical value.
The map replaces each value with its mapped value.
{name} placeholders in the action string are filled with the mapped values, and the action runs.

Because the map runs after synonyms and before substitution, map keys are the canonical values, and the action string always sees the replacement.

Value map versus synonym¶

They both change a value, at different points and for different reasons:

A synonym changes which value gets stored, so several spoken words become one canonical value the whole command shares.
A value map leaves the stored value alone and changes only the value substituted into an action, so a value like lancemate two becomes the key f3.

Example¶

Two captures, each mapped independently to a key. One shared action string presses the target key, waits, then presses the action key:

[[command]]
name = "Lancemate Command"
description = "Order a lancemate to carry out an action."
category = "combat"

[command.trigger]
pattern = "[command;] {target:lance;lancemate one;lancemate two;lancemate three} [to;] {action:attack my target;form on me;hold fire;weapons free}"

[command.map.target]
"lance"          = "f1"
"lancemate one"  = "f2"
"lancemate two"  = "f3"
"lancemate three" = "f4"

[command.map.action]
"attack my target" = "f1"
"form on me"        = "f2"
"hold fire"         = "f5"
"weapons free"      = "f5"

[command.response]
default = ["amri.input.tap('{target}')", "sleep_ms(50)", "amri.input.tap('{action}')"]

Say "command lancemate two to hold fire", and Amri presses f3, waits, then presses f5.

Unmapped values pass through

A value with no map entry is used as-is. You only need entries for the values that must change, not for every value the capture can hold.