Smart Filter Extras

一个面向 Minecraft 1.21.1 / NeoForge 的 FTB Filter System（下称 FFS）非官方附属模组。与 FTB Team 无关，也未经其认可。

• 模组 ID：smart_filter_extras
• 作者：传送门方块
• 语言：英语、简体中文、繁体中文、日语、韩语、俄语、德语、法语、西班牙语、巴西葡萄牙语（后 7 种未经母语者校对）

它给 FFS 的智能筛选器增加四个基础筛选：

筛选	写法	作用
物品列表（Item List）	smart_filter_extras:items(minecraft:stone,minecraft:dirt)	匹配列表中任意一个物品，最多 256 个
物品标签（多选）（Item Tags）	smart_filter_extras:item_tag(c:ingots,c:gems)	匹配属于任一所列物品标签的物品，最多 64 个标签
方块标签（Block Tag）	smart_filter_extras:block_tag(minecraft:mineable/pickaxe,minecraft:logs)	匹配“放置的方块属于任一所列方块标签”的物品
燃料值（Fuel Value）	smart_filter_extras:fuel(>=1600)	按熔炉燃烧时间（刻）比较；>0 是任何燃料，=0 是非燃料

FFS 自带的“物品”（item(...)）和“物品标签”（item_tag(...)）筛选保持原样。唯一的例外是 1.0.0 留下的逗号写法 item(a,b)：FFS 本身读不了它，本模组把它读作物品列表（见“旧版本写下的筛选”）。

这些筛选都可以用在 FTB 任务的物品任务里（需要 FTB XMod Compat，它负责把 FFS 接入 FTB 任务）：把智能筛选器设为任务物品，背包里任一匹配的物品都会被计入。

环境要求

组件	版本范围	开发与测试所用版本
Minecraft	1.21.1	1.21.1
NeoForge	21.1.217 起，21.2 之前	21.1.248
FTB Filter System	21.1.4 起，21.2 之前	21.1.4
Architectury API	13.0.8 起，14 之前	13.0.8
JEI（可选）	19.5.0.40 起，20 之前	19.57.0.450
EMI（可选）	1.1.23 起才有界面位置接口	1.1.24+1.21.1

NeoForge 21.1.248 上跑过全部测试（带 JEI、EMI 各一次）；最低版本 21.1.217 上也跑过全部测试，但没带 JEI，因为 JEI 19.57 本身要求 NeoForge 21.1.238 起。

FFS 21.1.0–21.1.3 的筛选 API 不同，本模组无法在这些版本上运行，加载器会直接拒绝。

EMI 的限制：EMI 1.1.24 在 NeoForge 上只在容器界面（箱子、背包这类）上显示侧栏，FFS 的配置界面不是容器界面，所以目前 EMI 不会出现在这些界面上，也就没法从 EMI 拖东西进来。本模组已经按 EMI 的接口注册了界面位置和拖放处理，EMI 以后支持这类界面时会直接生效。JEI 没有这个问题。

服务端和客户端都必须安装，而且版本要兼容。 只有一端安装，或两端的网络协议版本不同时，NeoForge 都会拒绝连接，避免出现“客户端打不开筛选”或“修改被服务端静默丢弃”的情况。网络协议版本目前是 4（每次新增了旧版本读不了的写法时都会升级）；3.0.0 起网络通道名也随模组 ID 改成了 smart_filter_extras:presence，所以和 2.x 测试版不能互连。

长度上限：FFS 把整个筛选当作一个字符串发送和保存，最多 32767 个字符，超过时在服务器上会断开连接。物品列表在加入条目前会检查整个筛选的长度，快到上限时停止加入并提示；单个变种条目最多 2048 个字符。

可选：安装 Just Enough Characters（JECH）后，物品搜索支持拼音（全拼、声母），例如输入 shitou 找到“石头”。

使用

物品列表

1. 手持智能筛选器右键打开编辑界面，点击 Add...，选择“物品列表”。
2. 网格操作（已选物品有绿底和对勾；浅绿底和半透明对勾表示这个变种已被选中的物品本身匹配；底部蓝线表示只选了这个物品的部分变种）：
   • 单击加入或移除，右键移除；
   • 双击会确保选中该物品，然后保存并关闭；
   • 按住 Shift 单击，把当前显示的全部物品加入；按住 Shift 右键，把它们全部移除。例如搜索 @create 后 Shift+单击，就能一次选中该模组的全部物品。
3. 新建的物品列表一开始什么都没选；没选任何物品时“完成”按钮不可用。
4. 下方一行是已选物品，单击或右键可移除。超过 9 个时用翻页箭头翻页，或在这一行上滚动鼠标滚轮。快速双击已选行只会移除一个物品。
5. 标题栏右侧的两个页签切换物品来源：指南针 = 全部物品（创造模式物品栏），箱子 = 背包。
6. 搜索框右侧两个开关：
   • 只看已选（对勾）：网格只显示已选物品；
   • 区分变种（药水瓶）：每种药水、附魔书等分别列出。这时选中的是“治疗药水”这样的具体变种，只匹配带相同组件的物品（物品多带别的组件不影响，例如改过名字）。会随使用变化的数据（耐久、修复费用、弩的装填、正在写的书）和存放的内容（潜影盒等容器、收纳袋、方块实体数据、蜂巢里的蜜蜂、未开启的战利品）不计入变种。
7. 已选行上方的工具按钮：复制（把已选内容以逗号分隔复制到剪贴板）、粘贴（从剪贴板加入；可用逗号、空格或换行分隔 ID，也可以粘贴 items(...)、item(...) 这样的筛选字符串，不存在的 ID 会被跳过）、清空。列表中有不存在的条目时会多出一个黄色警告图标，悬停查看，单击移除。
8. 搜索框按物品名称和 ID 搜索，@模组ID 只显示该模组的物品；右侧 × 清空搜索。
9. 鼠标悬停在格子上时，提示框最后一行会说明单击会做什么。
10. 网格会随窗口高度在 4 到 8 行之间变化。
11. 安装 JEI 时，可以把 JEI 列表里的物品直接拖进网格或已选行（“区分变种”开启时会保留拖入物品的组件）。
12. 键盘：回车保存；在界面任意处直接打字会进入搜索框；搜索框没有在编辑时，Ctrl+C / Ctrl+V 复制、粘贴已选内容（与复制、粘贴按钮相同）。点进搜索框后，Ctrl+C / Ctrl+V 照常编辑搜索文字。

Windows 上如果有剪贴板管理器之类的程序正占用剪贴板，复制会读回校验并重试；仍然失败时会提示“剪贴板被其他程序占用”，不会假装复制成功。

如果列表中有当前游戏里不存在的物品 ID（例如移除了某个模组），这些 ID 会被保留，但不会匹配任何物品。界面上会提示“已保留 N 个缺失 ID”，点“移除”可以丢掉它们。其余物品照常工作，一个失效的 ID 不会让整个筛选失效。

方块标签和物品标签（多选）

两个界面的用法相同，区别只在于列的是方块标签还是物品标签。

1. Add... 中选择“方块标签”或“物品标签（多选）”。新建时什么都没勾选，“完成”不可用。单击行可以勾选或取消，可以勾选多个标签（匹配其中任意一个）；双击一行会勾选它并保存；回车保存。
2. 列表右侧是标签中的方块/物品数量。鼠标在一行上停留片刻，会显示这个标签的前 27 个物品图标和总数。下方显示已勾选的标签数和这些标签合起来的内容，悬停可查看全部已勾选标签。
3. 反查：搜索框下面的格子可以放一个方块（方块标签界面）或任何物品（物品标签界面），之后列表只显示包含它的标签。
   • 单击格子轮流选择背包里的方块/物品，滚轮切换上一个/下一个，右键或点 × 清除；
   • 也可以从 JEI 把方块/物品拖到格子或列表上。
4. 输入框可以输入完整的标签 ID（例如 mymod:custom_ores、#c:storage_blocks/iron）。当前世界没有这个标签时，列表顶部会出现一条标为“未加载”的条目供选择。在界面任意处直接打字会进入搜索框。
5. 滚轮一格滚一行。列表按窗口高度显示 4 到 8 行。
6. 搜索框右侧的对勾开关：只看已勾选的标签。
7. 反查格子那一行右侧的三个按钮：复制已勾选的标签（Ctrl+C）、从剪贴板勾选（Ctrl+V）、全部取消。粘贴可以是带 # 或命名空间的 ID 列表，也可以是 item_tag(...)、block_tag(...) 这样的筛选字符串。搜索框没有在编辑时快捷键才作用于勾选。
8. 方块标签只有方块物品能匹配。注意：种子会放置作物，所以小麦种子会匹配 minecraft:crops；红石粉会放置红石线，也同理。
9. 物品标签的每个标签都与 FFS 自带的“物品标签”筛选匹配方式相同；本筛选只是可以一次勾选多个，并且界面能输入长 ID、显示数量和预览。

未保存的修改

在任何一个配置界面里，有修改时点“取消”或按 Esc，会先问是否放弃修改；“继续编辑”（或再按 Esc）回到界面，修改都还在。点“完成”或回车保存时不会问。

燃料值

1. Add... 中选择“燃料值”。单击比较符按钮切换（>=、>、=、!=、<=、<），输入刻数；在数字框上滚动滚轮 ±100，按住 Shift ±1；回车保存。
2. 预设按钮：任意燃料（>0）、煤炭 / 烈焰棒 / 煤炭块 / 熔岩桶（不低于它们的燃烧时间）、非燃料（=0）。
3. 下方实时显示当前条件匹配的燃料（按燃烧时间从高到低），悬停可看具体刻数。
4. 烧一个物品需要 200 刻，煤炭可燃烧 1600 刻。燃烧时间来自 NeoForge 的 furnace_fuels 数据表，因此数据包修改的燃料值也会生效。

命令写法

/ftbfiltersystem parse smart_filter_extras:items(minecraft:stone,minecraft:dirt)
/ftbfiltersystem parse smart_filter_extras:item_tag(#c:ingots,c:gems)
/ftbfiltersystem parse smart_filter_extras:block_tag(#minecraft:logs)
/ftbfiltersystem parse and(smart_filter_extras:items(minecraft:oak_log,minecraft:stone)smart_filter_extras:block_tag(minecraft:logs))

• 物品 ID 用逗号分隔，空格会被忽略，省略命名空间时默认 minecraft，重复项只保留一次。
• 标签可以带或不带 #，保存时统一为不带 # 的形式。

卸载前的迁移

本模组的筛选写在物品数据里。卸载后，FFS 无法解析 smart_filter_extras:*，整个筛选会变成什么都不匹配，而且 GUI 打不开。卸载前请先迁移：

1. 把智能筛选器拿在主手（装在机器、管道里的筛选器要先取出来）。
2. 执行 /smart_filter_extras downgrade。
   • “物品列表”会被改写成 FFS 自带的写法：一个物品时是 item(a)，多个物品时是 or(item(a)item(b)...)，变种条目是 and(item(a)component(fuzzy:{...}))，匹配结果不变。组件文本里带括号或反斜杠（例如自定义名称含括号）的列表，FFS 自带的组件筛选无法可靠保存，这类列表会保持不变并提示。
   • 缺失的物品 ID 无法用自带筛选表示，会被丢弃，命令会提示数量。
   • “物品标签（多选）”会被改写成 item_tag(a) 或 or(item_tag(a)item_tag(b)...)，匹配结果不变。
   • “方块标签”和“燃料值”在 FFS 中没有等价筛选，会保持不变，命令会提示仍有几个需要本模组。

旧版本写下的筛选

FTB 任务的物品任务、管道和机器里的筛选器都按保存时的原文存放筛选，所以改过 ID 的旧筛选仍要能读。3.0.1 起下面这些旧写法都能直接使用，不需要迁移：

旧写法	来自	现在读作
smartfilterextras:items(...)、item_tag(...)、block_tag(...)、fuel(...)	2.x 测试版	对应的 smart_filter_extras:* 筛选
item(a,b,...)（逗号分隔多个物品）	1.0.0（ftbfiltersystemaddons）	物品列表
ftbfiltersystemaddons:block_tag(...)	1.0.0	方块标签

• 旧筛选在下次编辑并保存时会改成新写法。
• 只有一个物品的 item(a) 仍然是 FFS 自带的物品筛选，解析交给 FFS 自己注册的代码，界面、JEI 支持都不变。只有 FFS 本来就读不了的逗号写法才由本模组接管。
• 旧 ID 只用于读取，不会出现在 FFS 的“添加”菜单里，每种筛选只列一次。

与 1.0.0（ftbfiltersystemaddons）的区别

2.0.0 是一次重写：

• 模组 ID 从 ftbfiltersystemaddons 改为 smart_filter_extras（2.x 时是 smartfilterextras），包名也不再使用 FTB 的 dev.ftb 命名空间。
• 不再整体替换 FFS 的 item 筛选。新建的多物品筛选是独立的 smart_filter_extras:items；1.0.0 留下的 item(a,b) 见上一节。
• 配置界面完全重写，不包含 FFS 的代码。唯一用到的 FFS 内部（非 API）类是读取 item(a,b) 时用的筛选注册表；FFS 改了这个类时，只有 item(a,b) 这种写法会读不出来，日志里会有警告，其他功能不受影响。

构建与测试

需要 JDK 21。

./gradlew build                # 产物：build/libs/smart_filter_extras-<版本>.jar 及 .sha256
./gradlew runGameTestServer    # 服务端行为测试（27 项），任何一项失败都会让任务失败
./gradlew -Pquests=true runGameTestServer   # 同上，并装上 FTB 任务，检查任务能识别每种筛选
./gradlew runClientSmoke       # 自动化客户端检查：建超平坦世界，驱动两个配置界面，截图，写 runs/client-smoke/smoke-result.json

• 测试代码在 src/gametest/，只参与开发环境的运行，不会打进发布的 jar。
• 界面图标和模组图标由 tools/make-icons.ps1 生成（纯像素画，不含外部素材），修改后重新运行即可。
• 开发环境默认带 JEI 和 JECH 运行，runClientSmoke 会顺便检查 JEI 集成；游戏语言为中文时还会检查拼音搜索。
• -PrecipeViewer=emi 改为带 EMI 运行（检查 EMI 集成），-PrecipeViewer=none 不带配方查看器；-Pneoforge_version=21.1.217 可以在最低支持版本上测试。
• -Pquests=true 在开发环境里加入 FTB 任务、FTB 队伍、FTB 库和 FTB XMod Compat。两项任务测试在没有 FTB 任务时直接通过；有时会建出物品任务，检查新写法和旧写法的筛选在新建、存盘读回、网络同步之后都能匹配，以及“检测背包”能数对数量。
• 冒烟测试会记录搜索耗时（每个条目的微秒数，以及换算到 4 万条目时每次搜索的毫秒数）。
• .github/workflows/build.yml 在 GitHub Actions 上运行构建和 GameTest（客户端冒烟测试需要显示器，不在 CI 中运行）。
• 默认从官方 maven.neoforged.net 解析依赖。网络访问不了时，可以加 -PuseNeoForgedMirror=true 改用 ForgeCDN 镜像。
• Gradle wrapper 校验发行包的 SHA-256（distributionSha256Sum）。

许可

本仓库的代码使用 MIT 许可。FTB Filter System 归 FTB Team 所有，遵循其自己的许可；本仓库不包含其代码。