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

> Discover over 20 Rime Wanxiang Lua scripts extending Rime with Unicode input, real-time tips, and more. Unlock advanced input method features today.

- Repository: [amzxyz/rime_wanxiang](https://github.com/amzxyz/rime_wanxiang)
- Tags: deep-dive
- Published: 2026-02-24

---

**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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/schema.yaml) using the `lua_processor`, `lua_translator`, and `lua_filter` prefixes:

```yaml

# 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:

```yaml

# 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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/lib/userdb.lua)** for LevelDB persistence and synchronization.
- **[`super_processor.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/super_processor.lua)** consolidates key handling for quick-symbols, limits, and segmentation into a single entry point.
- **Conversion features** include Unicode input ([`unicode.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/unicode.lua)), Chinese monetary conversion ([`number_translator.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/number_translator.lua)), and temporal shortcuts ([`shijian.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/shijian.lua)).
- **Filtering and display** scripts like [`super_filter.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/super_filter.lua), [`super_comment_preedit.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/super_comment_preedit.lua), and [`super_english.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/schema.yaml). Ensure you also copy [`wanxiang.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.lua) and [`lib/userdb.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/lib/userdb.lua) if the module depends on core utilities or database functionality.