Common Story Queries

Common story queries read a piece of game data while story text, command parameters, or condition checks are being processed. A query can return either a number or text. When the game reaches that segment, it replaces the query directive with the query result, then continues processing the remaining text or command.

Common uses:

• Show player money, place names, or character names in dialogue.
• Check whether a value satisfies a requirement in IF, SELECT, and similar conditions.
• Pass a query result into a later command, such as reading a role ID first and then querying that role’s name.

Basic Format

Use the $ form for new content:

[$QUERY:arg1:arg2$]

The % form from earlier documents is still compatible:

[%QUERY:arg1:arg2%]

New documentation uses $ first. Both forms mean the same thing; only the surrounding symbols differ.

Colons : separate parameters inside a query directive. Use English half-width symbols for all syntax characters, such as $, :, [, ], &, and |, instead of Chinese full-width symbols.

Reading Placeholders

Usage examples in the index include uppercase placeholders. They are not fixed text to copy directly; they describe what you should fill in.

• QUERY: the query name, such as player_money or tagrole.
• INFO or a field name: the value to read, such as name, level, or campid.
• ID: the ID of a config or runtime object, such as a role ID, place ID, or quest ID.
• INDEX: a zero-based index.
• TAG_KEY: the field name of a custom TAG in a config table.
• VAR_ID: a custom variable ID.
• SUBARG: a temporary replacement result prepared by SET_SUBARG.

For example:

[$player_money$]
[$tagrole:name$]
[$tagrole:name:RoleID$]
[$tagrole:tag=TAG_KEY$]

The first line queries player money directly. The second line queries the target role name in the current story context. The third line queries a specified role instead. The fourth line reads a TAG value from the role config.

Nested Queries

Do not put one query directly inside another query. Save the inner query as SUBARG first, then use it in the next command.

For example, split a long nested query into two steps:

SET_SUBARG*[$str_val:enemy$]
SETSTRVAR*[$tagrole:name:SUBARG$]

Handle deeper nesting in the same way, starting from the innermost layer and working outward step by step. This makes scripts easier to check and avoids hard-to-read strings with too many brackets and separators.

Working with Conditions

Query results are often inserted into condition expressions:

IF*[$player_money$][>=]100

This means the commands inside the IF continue only when player money is at least 100. See Conditions and Numeric Expressions for the full condition syntax.

Query Index

Common Story Queries ...

Loading common story queries...