Rime Wanxiang Lua Scripts: Complete Guide to 20+ Modules and Their Functions

The Rime Wanxiang distribution provides 20+ specialized Lua scripts that extend the Rime input method engine with advanced features including Unicode input, real-time tips, configurable candidate replacement, and dynamic key processing.

The amzxyz/rime_wanxiang repository ships with a comprehensive Lua library designed to enhance Rime schema functionality beyond standard configuration. These Rime Wanxiang Lua scripts handle everything from mobile device detection and LevelDB persistence to arithmetic calculation and date expansion, all accessible through modular processor, translator, and filter hooks.

Core Infrastructure and Utilities

wanxiang.lua: The Foundation Module

The wanxiang/lua/wanxiang.lua file serves as the central utility library imported by nearly every other module. It provides device detection, version handling, and regex parsing helpers critical for cross-platform compatibility.

Key entry points include:

• wanxiang.is_mobile_device()【/wanxiang/lua/wanxiang.lua#L25-L73】 – Detects touch-screen environments to adapt UI behavior.
• wanxiang.get_input_method_type()【/wanxiang/lua/wanxiang.lua#L70-L22】 – Identifies the active input method category for schema-specific logic.
• wanxiang.load_regex_patterns()【/wanxiang/lua/wanxiang.lua#L180-L55】 – Loads and caches regex patterns used by filtering modules.

Database and API Wrappers

lib/userdb.lua provides a minimal LevelDB wrapper used by data-intensive modules like super_tips and super_sequence. The userdb.LevelDb() constructor【/wanxiang/lua/lib/userdb.lua#L15-L30】 handles database open/close operations, fetch, update, and metadata tracking.

librime.lua acts as a thin convenience wrapper around the Rime C-API (rime_api), exposing common functions such as get_user_data_dir and commit_text that other scripts require via the standard require pattern.

Input Processing and Key Handling

super_processor.lua: The Central Key Event Dispatcher

The super_processor.lua module bundles multiple independent key-handling features into a single processor. The M.init() function【/wanxiang/lua/super_processor.lua#L73-L90】 initializes per-environment state, while M.func()【/wanxiang/lua/super_processor.lua#L19-L71】 dispatches handlers for:

• Keypad number input
• Letter-based candidate selection
• Quick-symbol entry
• Backspace and repeat-input limits
• Tone-fallback logic
• Super-segmentation triggers
• Select-character commands (first/last character extraction)

key_binder.lua: Configuration Helper

key_binder.lua reads schema-specific key-binding configurations and provides lookup helpers via key_binder.get_binding()【/wanxiang/lua/key_binder.lua#L9-L24】, allowing processors to respect user-defined shortcuts without hard-coding key combinations.

Translation and Conversion Modules

Unicode and Character Input

unicode.lua enables direct Unicode codepoint entry. When the user types the configured trigger (default U) followed by a hexadecimal value, the unicode() function【/wanxiang/lua/unicode.lua#L6-L27】 converts it to the corresponding character, implementing range checks and surrogate-pair protection to prevent invalid output.

Calculators and Numeric Conversion

super_calculator.lua implements arithmetic evaluation triggered by the calculator tag (typically activated by V followed by digits). The calculator() function【/wanxiang/lua/super_calculator.lua#L5-L33】 parses and evaluates expressions like V1+2*3.

number_translator.lua converts numeric input into formal Chinese monetary units. The number_translator() function【/wanxiang/lua/number_translator.lua#L5-L40】 transforms sequences like R123 into 壹佰贰拾叁元.

Date, Time, and Version Shortcuts

shijian.lua handles temporal shortcuts such as /rq (date), /sr (time), and Ndate. The shijian() function【/wanxiang/lua/shijian.lua#L8-L44】 expands these triggers into formatted date/time strings based on the current system time.

version_display.lua provides the /wx translator. When triggered, the translator() function【/wanxiang/lua/version_display.lua#L4-L15】 displays the project URL and current version (standard vs. professional) as a candidate comment.

Candidate Filtering and Display

super_tips.lua: Dynamic Tip Database

super_tips.lua manages a LevelDB-backed tips system. It loads tip files, builds MD5 fingerprints for change detection, and renders contextual comments next to candidates when the super_tips option is enabled.

• tips.init()【/wanxiang/lua/super_tips.lua#L86-L108】 initializes the database connection and verifies file signatures.
• tips.get_tip()【/wanxiang/lua/super_tips.lua#L60-L70】 retrieves the appropriate tip text for a given candidate.

super_filter.lua: Regex-Based Hiding

The super_filter.lua module provides candidate suppression via regular expressions. The F.func() filter【/wanxiang/lua/super_filter.lua#L5-L27】 removes candidates matching configured patterns when a specific option (e.g., "hide_punctuation") is active.

super_comment_preedit.lua: Preedit Annotation

super_comment_preedit.lua injects comments—such as pinyin pronunciation—directly into the preedit area upon candidate selection. The F.func() implementation【/wanxiang/lua/super_comment_preedit.lua#L4-L26】 reads a configurable comment format string to determine what metadata appears inline.

super_english.lua: ASCII-Only Mode

For pure English input schemas, super_english.lua filters out non-ASCII candidates and forces a numeric page size. The P.init() function【/wanxiang/lua/super_english.lua#L8-L20】 sets up the environment, while F.func()【/wanxiang/lua/super_english.lua#L33-L55】 performs the actual candidate filtering.

Advanced Data Management

super_sequence.lua: Custom Candidate Ordering

super_sequence.lua implements "free-order sorting" by storing per-input ordering adjustments in LevelDB. It synchronizes these preferences across devices and renders visual markers (+N, -N, ●) on candidates to indicate position changes.

• seq_data._ensure_export_file()【/wanxiang/lua/super_sequence.lua#L24-L42】 handles cross-device synchronization file management.
• F.func()【/wanxiang/lua/super_sequence.lua#L44-L70】 renders the visual position markers during candidate display.

super_replacer.lua: OpenCC-Style Conversion

super_replacer.lua offers a flexible replacement engine supporting four operation types: append, replace, comment, and abbrev. It automatically rebuilds its database when version numbers, delimiters, or source file signatures change.

• M.init()【/wanxiang/lua/super_replacer.lua#L30-L55】 parses the types configuration and builds the replacement database.
• M.func()【/wanxiang/lua/super_replacer.lua#L64-L85】 executes the core conversion logic on candidate text.

super_lookup.lua: Dictionary Integration

super_lookup.lua provides a lookup processor that queries definitions from a LevelDB dictionary when the user types a configured lookup key (default `) and presses Enter. The P.func() handler【/wanxiang/lua/super_lookup.lua#L34-L56】 manages the lookup session and result display.

Workflow and Utility Scripts

Schema and Session Management

set_schema.lua enables runtime schema switching via the /set_schema <name> command, implementing the set_schema() function【/wanxiang/lua/set_schema.lua#L4-L30】 to hot-swap configurations without restarting the input method.

partial_commit.lua allows committing only a segment of the current preedit (e.g., the first word) while preserving remaining input. The partial_commit() function【/wanxiang/lua/partial_commit.lua#L4-L27】 handles the segmentation logic and commit operation.

input_statistics.lua gathers session metrics including key counts and duration, writing them to a CSV file via the statistics() function【/wanxiang/lua/input_statistics.lua#L8-L38】 for later analysis.

Phrase Generation

auto_phrase.lua generates phrase candidates from user-defined tables, supporting both exact and fuzzy matching modes through the auto_phrase() function【/wanxiang/lua/auto_phrase.lua#L6-L45】.

How to Enable Wanxiang Lua Scripts in Your Schema

To activate these modules, reference them in your schema.yaml using the lua_processor, lua_translator, and lua_filter prefixes:

# schema.yaml (excerpt)

engine:
  processors:
    - lua_processor@*super_processor      # Key handling bundle

    - lua_processor@*super_lookup         # Dictionary lookup

    - lua_processor@*set_schema           # Runtime schema switching

  translators:
    - lua_translator@*version_display    # /wx version info

    - lua_translator@*unicode            # Uxxxx → Unicode

    - lua_translator@*super_calculator   # Arithmetic evaluation

    - lua_translator@*shijian            # Date/time shortcuts

  filters:
    - lua_filter@*super_tips             # Tip comments

    - lua_filter@*super_filter           # Regex filtering

    - lua_filter@*super_comment_preedit   # Preedit annotations

Toggle individual features using schema options:

# schema.yaml (options section)

options:
  super_tips: true            # Enable tip database lookup

  super_filter: true          # Enable regex candidate hiding

  calculator: true            # Enable arithmetic mode

Summary

• Wanxiang distributes 20+ modular Lua scripts organized into processors, translators, and filters for the Rime input method.
• wanxiang.lua provides core utilities like is_mobile_device() and regex loading used across the ecosystem.
• Data-intensive modules (super_tips, super_sequence, super_replacer) rely on lib/userdb.lua for LevelDB persistence and synchronization.
• super_processor.lua consolidates key handling for quick-symbols, limits, and segmentation into a single entry point.
• Conversion features include Unicode input (unicode.lua), Chinese monetary conversion (number_translator.lua), and temporal shortcuts (shijian.lua).
• Filtering and display scripts like super_filter.lua, super_comment_preedit.lua, and super_english.lua modify candidate presentation without altering the underlying dictionary.

Frequently Asked Questions

How do I check if the input method is running on a mobile device?

Call wanxiang.is_mobile_device() from the core utilities module. This function, defined at line 25 of wanxiang/lua/wanxiang.lua, detects touch-screen environments by inspecting system properties, allowing schemas to adapt key bindings or UI density for phones versus desktop computers.

What is the difference between super_replacer and standard OpenCC conversion?

super_replacer.lua offers four configurable operation types—append, replace, comment, and abbrev—and automatically rebuilds its LevelDB database when source files or version signatures change. Unlike static OpenCC tables, it supports dynamic candidate modification based on runtime schema options and maintains fingerprint-based change detection for synchronization across devices.

How does the super_sequence module store custom sort orders?

The module persists per-input ordering adjustments in a LevelDB database via the seq_data interface. The seq_data._ensure_export_file() function manages synchronization files for cross-device consistency, while visual markers (+N, -N, ●) are rendered by the filter function to indicate candidate position shifts relative to the default dictionary order.

Can I use Wanxiang scripts without the full Wanxiang schema distribution?

Yes. Individual modules can be extracted and loaded into any Rime schema by placing them in the lua/ directory and referencing them via lua_processor@*module_name or lua_translator@*module_name in your schema.yaml. Ensure you also copy wanxiang.lua and lib/userdb.lua if the module depends on core utilities or database functionality.

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