Wildcard Syntax Reference

Works in the Prompt, Negative, and character fields. In the examples, # comments and text to the right of → are explanations only (do not type them). Draw results are just examples.

Quick reference

Pick one candidate at random

# Picks one of the candidates separated by |
{red|blue|green} hair          → blue hair

# Each group is drawn independently
{shirt|jacket}, {skirt|pants}  → jacket, skirt

# Candidates can be nested
{short|{long|very long}} hair → very long hair

Change how likely each candidate is

# Makes red three times as likely as blue
{3%%red|1%%blue} hair    → red hair

# Decimals also work
{0.5%%red|1.5%%blue}     → blue

# An omitted weight counts as 1
{3%%red|blue}           → red

# Weights of 0 or less count as 0. If every weight is 0, all candidates are equally likely
{0%%red|1%%blue}         → blue

Pick multiple candidates

# Picks 2. A candidate is never picked twice; results appear in draw order
{2$$red|blue|green}             → green, red

# Picks 1 to 3
{1-3$$red|blue|green}           → red, blue, green

# Omitting the lower bound starts from 1
{-2$$red|blue|green}            → blue, red

# Omitting the upper bound allows up to all candidates. The count stays between 1 and the number of candidates
{2-$$red|blue|green}            → red, green

# Combine a count with weights
{2$$3%%red|1%%blue|1%%green}    → red, blue

Change how picked candidates are joined

# Without a separator, results are joined with ", "
{2$$red|blue|green}          → red, blue

# Use {count$$separator$$candidate|candidate}
{2$$ + $$red|blue|green}     → red + blue
{2$$ / $$red|blue|green}     → red / blue

# An empty separator joins with nothing
{2$$$$red|blue|green}        → redblue

Pick from a TXT file

# Color candidates
red
blue
green

shirt
jacket
coat

skirt
pants
shorts

# Files go in the wildcard folder set in Settings (usually wildcards)
# Save as UTF-8, one candidate per line. Blank lines and lines starting with # are skipped
# Write the path relative to that folder, without the extension
# If the folder is .../wildcards, write __tag__ — do not add wildcards/
# __wildcards/tag__ would refer to .../wildcards/wildcards/tag.txt
__tag__ hair                         → blue hair

# Separate subfolders with /
__clothes/top__                      → jacket
__clothes/top__, __clothes/bottom__  → shirt, skirt

# Each occurrence is drawn independently, so results can repeat
__tag__, __tag__                     → red, red

Pick by searching file names

# Candidates from every matching file are pooled into one draw
# This does not search keys inside YAML files
__clothes/*__                        → shorts

# The extension can be specified too
__clothes/*.txt__                    → coat

# [tb] matches t or b
__clothes/[tb]*__                    → pants

# **/ includes subfolders
__clothes/**/*__                     → shirt

Pick multiple from files

# Picks 2 from the referenced candidate list
# If the list contains the same string more than once, results may repeat
{2$$__tag__}                       → red, green

# Count ranges and separators work here too
{1-3$$__tag__}                     → blue
{2$$ + $$__tag__}                  → blue + red

# Pick from several files at once
{2$$__clothes/*__}                 → shirt, pants

# Mix file references and inline candidates
{__tag__|black} hair               → green hair

Pick from a YAML key

outfit:
  color:
    - white
    - black
  top:
    - "__color__ shirt"
  set:
    - "__top__, __clothes/bottom__"
color:
  - red
  - blue

# Refer to it as __file/key/child-key__ (.yaml and .yml are supported)
__pack/outfit/color__      → white

# __color__ uses the nearer white / black
# They take priority over red / blue at the root
__pack/outfit/top__        → black shirt
__pack/outfit/set__        → white shirt, skirt

# Pick multiple from a key's candidates
{2$$__pack/outfit/color__} → white, black

# A file name alone picks from everything under all keys
__pack__                  → black shirt

# The older key-only form still works. To specify the file, start with the file name
__outfit/top__             → white shirt

Add multiple character prompts from YAML

# |- keeps line breaks, storing several lines as one candidate
# The position can be omitted, as in CHAR: __clothes/top__
# Write the shared prompt first and put all CHAR: lines at the end
# Everything after CHAR: up to the next CHAR: or the end belongs to that character
scene:
  - |-
    landscape
    CHAR:A1: __clothes/top__
    CHAR:E5: {red|blue} hair

# Write this wildcard in the prompt field
# Place wildcards that contain CHAR: at the very end of the prompt
# To add shared tags, put them before it, as in cinematic lighting, __characters/scene__
# Any regular prompt typed after this wildcard is absorbed into the last character prompt
# The same happens on a new line. Put anything meant to be shared before the wildcard
__characters/scene__

# It expands as below, and each CHAR: part is sent to its character prompt
# CHAR: is this app's own notation. It is split into shared and character prompts before sending to the API
# The main prompt becomes landscape; the characters get jacket / blue hair, etc.
# With position enabled, A1 is top left and E5 is bottom right (columns A–E, rows 1–5)
landscape
CHAR:A1: jacket
CHAR:E5: blue hair

# Models without structured character support merge it into the main text

# Appended after it, cinematic lighting belongs to the last character, not the shared prompt
__characters/scene__, cinematic lighting

# Appended on a new line, cinematic lighting still belongs to the last character
__characters/scene__
cinematic lighting

# To use it as a shared prompt, put it before the wildcard
cinematic lighting, __characters/scene__

Pick from a JSON key

{"sky": ["sunny", "cloudy", "rainy"]}

# Refer to it the same way as YAML
__weather/sky__ → cloudy

Refer explicitly to an external file

purple

# Example added inside outfit in pack.yaml
external_top:
  - "__external/color__ shirt"

# A path to an existing external file takes priority
# Short internal references are searched in this order: same level → parent level → unique suffix match in the same YAML → external
# If several internal candidates make it ambiguous, the reference is left as is with a warning
__pack/outfit/external_top__ → purple shirt

Refer when the file name and top key match

wardrobe:
  top:
    - shirt
    - jacket

# Write both the file name and the top key
__wardrobe/wardrobe/top__ → shirt

# The repeated name can also be written once
__wardrobe/top__          → jacket

Pick in order with SEQ

# Write SEQ: explicitly for sequential picks
# Uses red / blue / green from tag.txt once each
# After the last one, it starts over from the first
[SEQ:__tag__]         → red → blue → green → red …

# :2 uses each candidate twice. Omitted means once; 0 is also treated as once
[SEQ:__tag__:2]       → red → red → blue → blue → green → green …

# Use YAML candidates in order
[SEQ:__pack/outfit/color__] → white → black → white …

# References inside a single-candidate template are also expanded in order
[SEQ:__pack/outfit/top__]   → white shirt → black shirt → white shirt …

# GUI: when typed directly in an input field, it resets to the start and queues one full cycle when generation begins
# Multiple SEQs generate up to the least common multiple of their cycles. You are asked to confirm before starting if it exceeds 2,000
# CLI: set the number of images with --count
# The old [__tag__:2] form is not treated as SEQ. Change it to [SEQ:__tag__:2]

Move to Negative

# The examples below assume Negative is lowres
# <!…!> moves the content to the end
portrait <!watermark!>
→ Prompt: portrait
→ Negative: lowres, watermark

# stn moves it to the start
portrait <ppp:stn>watermark<ppp:/stn>
→ Prompt: portrait
→ Negative: watermark, lowres

# s explicitly means the start
portrait <ppp:stn s>watermark<ppp:/stn>
→ Prompt: portrait
→ Negative: watermark, lowres

# e means the end
portrait <ppp:stn e>watermark<ppp:/stn>
→ Prompt: portrait
→ Negative: lowres, watermark

# Only the content of the picked candidate is moved. It can be written inside wildcard candidates too
{red hair <!blue hair!>|blue hair <!red hair!>}
→ Prompt: red hair
→ Negative: lowres, blue hair

# Inside a character field, it moves to that character's Negative
# Move blocks written in the Negative field leave their content in place
# V5 Full Medium: the target is removed from Prompt, and wildcards / SEQ inside it are not expanded
# The model's fixed default Negative and the original text in the editor / YAML are kept
# pN / iN, unclosed blocks, and nested move blocks cause an error before sending

Tell drawing apart from emphasis

# [] stays after wildcard expansion and is sent as NovelAI de-emphasis
# Candidates are still drawn at random as usual, and SEQ does not advance
[__tag__]       → [blue]
[[__tag__]]     → [[red]]

# Braces without | or $$, and NAI numeric emphasis, are left as is
{red}           → {red}
1.2::red::      → 1.2::red::

# %% sets a weight. Written alone at the start of a TXT line, it is not a draw weight
# Write it inside candidates, as in {3%%red|blue}
3%%red          → 3%%red

# Empty candidates are skipped. An empty string is never picked
{red|}          → red

# Reference names containing ? are not supported. For file name search, use *, ** and [ab]
# Missing and circular references are left unresolved and logged as warnings
# Random draw results may change even with a fixed Seed
# SEQ keeps a fixed Seed. Only when it is -1 is the image generation Seed randomized