astrbot_plugin_sf6

An AstrBot plugin for offline Street Fighter 6 move data and hitbox lookup.

Version 0.2 separates the lightweight plugin code from the large character resource pack. The running bot reads local JSON and image files only: it does not scrape SuperCombo Wiki and does not depend on Cloudflare availability.

Features

• Query every character currently listed on the SuperCombo SF6 data page.
• Use commands such as /sf6 Ryu 5LP and /sf6 Chun-Li 236K.
• Character names, aliases, and move inputs are case-insensitive.
• Customer shorthand such as 5L resolves to 5LP.
• Incomplete ambiguous inputs return a short candidate list.
• Replies include all locally available hitbox images and English frame data.
• The default interface and frame-data field labels are Simplified Chinese.
• Human-maintained character, move, and note translations fall back to English whenever a Chinese cell is still blank.
• /sf6 术语表 (also /sf6 输入) returns the bundled Chinese input/glossary image.
• Character JSON is loaded lazily, keeping normal memory use small.
• No runtime network requests and no third-party Python dependencies.

Install the plugin

Install from the AstrBot WebUI plugin manager using:

https://github.com/determinasc/astrbot_plugin_sf6

The declared compatibility range is AstrBot >=4.17.0,<5. It does not restrict AstrBot platforms; the primary tested target is QQ through the aiocqhttp adapter, including NapCat OneBot v11 connections.

Install the separate resource pack

Download astrbot_plugin_sf6_resources_2026.07.28.zip from GitHub Releases. Extract it first; do not place the ZIP itself in AstrBot. Copy manifest.json, characters, and images using any one of these methods. The plugin checks them in this order:

Priority	Resource location	Best for
1	resource_path in the AstrBot plugin settings	A shared disk, external disk, or any custom location
2	AstrBot/data/plugin_data/astrbot_plugin_sf6/	Recommended persistent installation
3	AstrBot/data/plugins/sf6_resource_pack/	Portable installation next to the plugin
4	AstrBot/data/plugins/astrbot_plugin_sf6/resources/	Bundled testing only; plugin updates may overwrite it

The recommended layout is:

AstrBot/data/plugin_data/astrbot_plugin_sf6/
├── manifest.json
├── characters/
│   ├── ryu.json
│   ├── kimberly.json
│   └── ...
└── images/
    └── hitboxes/
        ├── ryu/
        ├── kimberly/
        └── ...

The directory must directly contain manifest.json; do not add another ZIP-name directory level. A custom resource_path may use an absolute path, ~, or an environment variable. It may also point directly to manifest.json.

For Docker deployments, AstrBot above means the persistent AstrBot data volume inside the container. Restart the plugin or AstrBot after copying the pack or changing its settings. Running /sf6 will show the loaded character count; if installation is wrong, the reply lists every location that was searched.

Paths are discovered from the current AstrBot installation and are not tied to the computer on which the plugin was developed. The approximately 500 MiB resource pack is intentionally separate from the plugin, so it must still be copied once when moving AstrBot to another computer.

Usage

/sf6
/sf6 Kimberly 5LP
/sf6 ryu 5l
/sf6 Chun-Li 236K
/sf6 C. Viper 5HP
/sf6 术语表
/sf6 输入

Two-part names such as C. Viper, Dee Jay, E. Honda, and M. Bison are recognized directly. Compact aliases such as CViper, EHonda, and MBison also work.

Simplified Chinese translation table

The editable table is translations/zh_cn.csv. It contains 78 reusable terms, all 30 characters, and 2,306 moves in the current resource pack. The English source columns are populated; the chinese and notes_chinese columns are intentionally blank for human translation. Blank cells automatically use the corresponding English text.

Translators only edit chinese, notes_chinese, and the optional translator_note. See translations/README.md for the exact workflow. When a resource update adds characters or moves, run:

python scripts/generate_translation_template.py `
  "path/to/sf6_resource_pack" `
  "translations/zh_cn.csv"

The generator refreshes English source data and preserves existing human translations.

Bundled input and glossary image

The single Chinese input/glossary image from the customer requirements is bundled with the plugin code under assets/. It is deliberately not included in the approximately 500 MiB character resource ZIP, which remains unchanged. The plugin ships the original 917 × 14,648 JPEG instead of the low-resolution 133 × 2,131 DOCX preview, and sends that file without resizing it.

Development and validation

The repository tests use a tiny generated fixture, not the large resource pack:

python -m unittest discover -s tests -v
python -m compileall -q .
ruff check .
ruff format --check .

The complete Chinese maintenance procedure for adding new Wiki characters or refreshing existing data is documented in docs/SF6角色资源更新与新增角色指南.md.

Data source and attribution

English frame data and hitbox images are exported from the current character data pages on SuperCombo Wiki. Each character JSON records its exact page and MediaWiki revision. See NOTICE for attribution and licensing boundaries.

License

Plugin source code is licensed under the MIT License. The separately distributed Wiki-derived data and images are not relicensed under MIT; see NOTICE.