Switches Configuration Options in Rime Schema Files: The Complete Wanxiang Guide

Rime schema switches are UI-level toggles defined under the top-level switches: key that enable real-time input mode changes, using fields like name, options, states, and reset to configure binary or multi-state behaviors such as ASCII mode, emoji filtering, and character set conversion.

The amzxyz/rime_wanxiang repository provides production-ready examples of switches configuration options in Rime schema files, demonstrating how YAML declarations control input method behaviors ranging from language modes to tone display. These configurations determine how users interact with toggles via the status bar and key bindings, while also serving as runtime flags for Lua processors. Understanding the switch syntax is essential for customizing any Rime-based input method.

Core Switch Fields and Syntax

A switch is a map entry under the switches: list that may contain the following fields:

• name – String identifier used by the engine and key-binding rules (e.g., ascii_mode, emoji, charset_filter).
• options – Array of mutually-exclusive option identifiers for multi-state switches (e.g., [raw_input, tone_display, full_pinyin]).
• states – Array of human-readable UI labels displayed in the status bar; index order matches internal state values (e.g., [中文, 英文]).
• reset (optional) – Integer index specifying the default state when the schema loads or window focus changes (e.g., 0 for first state, 2 for third).
• abbrev (optional) – Single-character shortcut displayed when the schema appears in a selector menu.

Switches operate in two modes. A name field creates a binary toggle between two states (off/on). An options field creates an enumerated switch cycling through three or more mutually exclusive choices, where the first option serves as the default unless reset overrides it.

Switches Configuration Examples in Wanxiang

The Wanxiang project implements diverse switch patterns across its schema variants, from feature-rich pinyin configurations to minimal single-toggle setups.

Full Pinyin Schema Implementation

In wanxiang/wanxiang.schema.yaml (lines 21–40), the primary schema defines ten distinct switches controlling ASCII mode, punctuation, full-width characters, emoji filtering, translation modes, tone display, simplification conversion, comments, super tips, and character set priority:

switches:
  - name: ascii_mode                    # 中英输入状态

    states: [ 中文, 英文 ]
  - name: ascii_punct                   # 中英标点

    states: [ 中标, 英标 ]
  - name: full_shape                    # 全角/半角

    states: [ 半角, 全角 ]
  - name: emoji                         # Emoji 过滤

    states: [表情关, 表情开]
  - name: chinese_english               # 翻译模式

    states: [ 翻译关, 翻译开 ]
  - options: [ raw_input, tone_display, full_pinyin ]
    states: [ 原编码, 有声调, 无声调 ]
    reset: 2
  - options: [ s2s, s2t, s2hk, s2tw ]   # 简繁转换

    states: [ 简体, 通繁, 港繁, 臺繁 ]
  - options: [comment_off, tone_hint, toneless_hint]
    states: [ 注释关, 有声调, 无声调 ]
    reset: 2
  - name: super_tips
    states: [ 提示关, 提示开 ]
    reset: 1
  - name: charset_filter
    states: [ 大字集, 小字集 ]
    reset: 0
  - name: char_priority
    states: [词组先, 单字先]

Notice the multi-option blocks using options rather than name, particularly for tone display (reset: 2 forces "无声调" as the default) and simplification chains.

Nine-Key Variant Adjustments

The T9 schema in wanxiang/wanxiang_t9.schema.yaml (lines 20–46) replicates the core switches while adding abbreviation controls specific to nine-key input:

switches:
  - name: ascii_mode
    states: [ 中文, 英文 ]
  - name: ascii_punct
    states: [ 中标, 英标 ]
  - name: full_shape
    states: [ 半角, 全角 ]
  - name: emoji
    states: [表情关, 表情开]
  - name: chinese_english
    states: [ 翻译关, 翻译开 ]
  - name: charset_filter
    states: [ 大字集, 小字集 ]
    reset: 0
  - options: [ raw_input, tone_display, full_pinyin ]
    states: [ 原编码, 有声调, 无声调 ]
    reset: 2
  - options: [ s2s, s2t, s2hk, s2tw ]
    states: [ 简体, 通繁, 港繁, 臺繁 ]
  - options: [comment_off, tone_hint, toneless_hint]
    states: [ 注释关, 有声调, 无声调 ]
    reset: 2
  - name: super_tips
    states: [ 提示关, 提示开 ]
    reset: 1
  - options: [abbrev_off, abbrev_lazy, abbrev_always]
    states: [简码关, 空出简, 总出简]
    reset: 2

The abbrev_* options demonstrate how multi-state switches control whether short-code candidates are suppressed, shown lazily, or always displayed.

Minimal English Configuration

For contrast, wanxiang/wanxiang_english.schema.yaml (lines 11–15) shows a minimal single-switch setup:

switches:
  - name: ascii_mode
    reset: 0
    states: [整句, 字母]

Here reset: 0 ensures the schema initializes in "整句" (sentence) mode whenever the user activates it.

Runtime Integration with Key Bindings and Lua

Switches are manipulated at runtime through key bindings defined in key_binder presets or custom Lua processors. The engine exposes switch states via ctx:get_option("switch_name") and updates them via ctx:set_option("switch_name", boolean).

The following Lua filter illustrates how to read and toggle the emoji switch programmatically:

-- super_tips.lua (simplified illustration)
local function init(env)
  -- Initialize the emoji option if needed
  env.engine:set_option("emoji", false)
end

local function filter(input, env)
  local ctx = env.engine.context
  -- Example: Toggle emoji filter when 'e' is pressed in ASCII mode
  if ctx.keycode == 101 and ctx:get_option("ascii_mode") then
    local current = ctx:get_option("emoji")
    ctx:set_option("emoji", not current)
    return 2  -- Keep current input unchanged
  end
  return 1
end

The states arrays defined in the YAML determine the labels appearing in the candidate list or status bar when switches change. When reset values are specified, the engine automatically applies those defaults during schema reloads or window focus events.

Summary

• Binary toggles use the name field with two states, while multi-option switches use the options array with three or more choices.
• The reset field controls which state index (0-based) becomes active when a schema loads or regains focus.
• Switch identifiers are referenced by key_binder configurations for hotkeys and by Lua filters via ctx:get_option() and ctx:set_option().
• The wanxiang.schema.yaml, wanxiang_t9.schema.yaml, and wanxiang_english.schema.yaml files demonstrate progressive complexity from ten-switch configurations down to single-toggle minimal setups.
• states provide localized UI feedback, while abbrev offers quick selection shortcuts in schema menus.

Frequently Asked Questions

What is the difference between name and options in a Rime switch?

The name field creates a binary toggle between exactly two states (typically off/on), such as ascii_mode switching between Chinese and English input. The options field defines an array of three or more mutually exclusive identifiers, creating a cycle-through switch like the tone display modes (raw_input, tone_display, full_pinyin). When using options, the first entry is the default unless overridden by a reset value.

How does the reset field affect switch behavior?

The reset field accepts an integer index (starting at 0) that specifies which state becomes active when the schema is first loaded, reselected, or when the input window regains focus. For example, reset: 2 in the full_pinyin options block forces the switch to start at the third state ("无声调") rather than the default first state ("原编码").

Can switches control custom Lua filters?

Yes. Lua processors and filters access switch states through the engine context using ctx:get_option("switch_name") to read values and ctx:set_option("switch_name", value) to modify them. This allows custom scripts to conditionally alter candidate generation, pre-edit formatting, or translation behavior based on user toggles defined in the schema's switches section.

How do I add a new toggle to my Rime schema?

Add a new list item under the switches: key in your .schema.yaml file. For a binary toggle, provide a unique name and two states labels. For multiple choices, use options with an array of identifiers and matching states labels. Optionally include reset to set a non-default initial state or abbrev for a single-character menu shortcut. After editing, redeploy Rime to load the new switch configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}