Python 🎉Mapart-地图画插件！适用于LumenBridge的群内自助地图画插件！ 1.0.1

[MD]# MapArt使用文档 *** ## 一、三步上手（新手必看） 1. **绑定**：先在服务器完成 QQ 与 XboxID 的白名单绑定（没绑定的发指令会提示） 2. **上传**：在 QQ 群里发一张图片，并附一句话：`地图画上传 我的画` 3. **领取**：进入游戏，输入 `/getmap 我的画` —— 地图画物品就进背包了！ 拿在手里可以看，或者放进**物品展示框**挂在墙上，就是一幅画。 *** ## 二、怎么上传图片（三种方式，选一种就行） | 方式 | 怎么操作 | 适合场景 | | ------ | ----------------------------- | --------- | | ① 一起发 | 图片和指令发在**同一条消息**里 | 最常用，推荐 | | ② 先图后令 | 先单独发图片，5 分钟内再发指令 | 图片已经发过的时候 | | ③ 引用上传 | **引用**一条含图片的消息，再发指令（可引用别人发的图） | 想用群里已有的图 | > 引用上传仅支持 OneBot 个人号机器人；QQ 官方机器人请用方式①或②。 上传指令的完整格式： ``` 地图画上传 [名称] [规格] [模式] ``` * **名称**：可以不写（自动生成）；1-24 位中文/字母/数字/下划线/连字符 * **规格**：`3x2` 表示宽 3 张 × 高 2 张（见下节） * **模式**：`抖动` 或 `平滑`（渲染效果，见第五节） 所有部分**顺序随意**，例如下面这些写法都对： ``` 地图画上传 我的画 地图画上传 我的画 3x2 地图画上传 抖动 地图画上传 我的画 3x2 抖动 高清 留边 ``` *** ## 三、智能分割：图片大小不同，切的张数也不同！ **插件会自动看图片的实际清晰度来决定切几张**——这就是"智能分割"： | 图片大小 | 自动切成 | 为什么 | | ------------------------ | ---------- | ------------------- | | 小图（短边小于 256 像素，如表情包、小头像） | **1x1 单张** | 像素本来就少，切了也不更清晰，纯属浪费 | | 中等图片（如 512×512） | 2×2 | 每张地图分到的像素刚好 | | 大图（如 1024×512） | 4×2 | 像素多，多切才能不浪费清晰度 | | 超大图（如 1920×1080） | 4×4（顶格） | 越大切得越多 | **想更清晰？加「高清」**——切得更细（每 128 像素一张，接近无损）： ``` 地图画上传 我的画 高清 ``` **想自己定张数？直接写规格**（如 `3x2` = 宽 3 张 × 高 2 张）： ``` 地图画上传 我的画 3x2 ``` **图片被裁掉了？加「留边」**——完整显示、四周留白，不裁剪： ``` 地图画上传 我的画 留边 ``` > 记法说明：`4x2` 读作"4 列 2 行"。第一个数是左右方向几张，第二个数是上下方向几张。`1x1` 就是一张图。 *** ## 四、批量上传：一次发一整个压缩包！ 有多张图片要做成地图画？不用一张张发： 1. 把图片打包成一个 **zip 压缩包** 2. 在群里发送这个压缩包 + 指令：`地图画上传` **就这么简单！** 插件会自动： * 解压并识别包里所有图片（png/jpg/webp/gif/bmp） * **名称自动取自图片的文件名**（如 `风景.png` → 地图画名"风景"） * 每张图**各自智能分割**——小图 1 张、大图多切，互不影响 * 处理完回一条汇总：每张图的名称、切成几×几、成功/失败 你也可以带参数，**参数会应用到每一张图**： ``` 地图画上传 抖动 → 全部用抖动渲染 地图画上传 高清 → 全部切得更细 地图画上传 3x2 → 全部强制切成 3x2 ``` > 注意：批量上传不支持自定义名称（名称来自文件名）；压缩包里最多 20 张图片（管理员可调）。 *** ## 五、抖动还是平滑？（渲染模式） | 模式 | 效果 | 适合 | | ------ | ---------------- | -------------- | | 平滑（默认） | 色块干净整齐 | logo、动漫、图标、色块图 | | 抖动 | 用小噪点模拟更多颜色，过渡更细腻 | 照片、渐变图、真人图 | ``` 地图画上传 我的画 抖动 ``` > 记不住就先试默认的平滑；觉得照片糊/糙就加「抖动」重传一次。 *** ## 六、QQ 群指令（完整用法） ### 1. `地图画帮助` 查看全部指令的帮助。 ``` 地图画帮助 ``` ### 2. `图片列表` 查看自己已经上传的全部地图画，包括每幅是几×几张。 ``` 图片列表 ``` ### 3. `地图画上传`（详见第二、三、四、五节） ``` 地图画上传 [名称] [规格] [模式] ``` * **名称**：可省略（自动生成）；1-24 位中文/字母/数字/下划线/连字符 * **规格**：`3x2`（宽 3 张 × 高 2 张）或 `高清` 或 `留边`，可省略 * **模式**：`抖动` / `平滑`，可省略（默认平滑） * 所有参数**顺序随意、都可以不写**，发压缩包则批量上传（名称取文件名） ``` 地图画上传 我的画 → 最简：名称 + 自动分割 地图画上传 我的画 3x2 → 指定切成 3×2 地图画上传 我的画 高清 → 切得更细 地图画上传 我的画 留边 → 完整显示不裁剪 地图画上传 我的画 抖动 → 抖动渲染 地图画上传 我的画 3x2 抖动 高清 留边 → 全部参数随意组合 地图画上传 → 不写名称，自动生成名称 （发一张图片 + 上面任意一条指令即可；发 zip 压缩包 + 指令 = 批量上传） ``` ### 4. `获取地图画`（领取，**默认整套发放**，需在线） 完整格式（方括号里的都是可选项）： ``` 获取地图画 名称 [第N批] [每批M张] 获取地图画 名称 [第N行] ``` * **`获取地图画 名称`** —— 默认整套发放，几张就占几格背包空位 * **`第N批`** —— 领第 N 批；不写"每批M张"时批量用服务器默认值（一般是 8 张） * **`每批M张`** —— 每批发 M 张，M 至少为 1 * **`第N行`** —— 一次领一整行（和"批"互斥，不能同时用） * 参数顺序随意、可省略"第"和"张"字（`1批`、`每批4` 也能识别） ``` 获取地图画 我的画 → 整套全部发放（默认） 获取地图画 我的画 第1批 → 分批：第 1 批（每批张数 = 服务器默认值） 获取地图画 我的画 第2批 → 领第 2 批（接着上一次） 获取地图画 我的画 第1批 每批4张 → 每批 4 张，领第 1 批 获取地图画 我的画 每批4张 → 不写批号 = 第 1 批，每批 4 张 获取地图画 我的画 第2批 每批4张 → 每批 4 张，领第 2 批 获取地图画 我的画 第1行 → 按行领：第 1 行（整行一次到手） 获取地图画 我的画 第2行 → 领第 2 行 ``` 领完一批机器人会提示"下一批怎么发"，照着复制即可。 ### 5. `获取全部地图画`（一键领取，需在线） 把你名下**所有**地图画一口气全部发放，逐幅独立结算、互不影响。 ``` 获取全部地图画 ``` 背包装不下会发到装不下为止并提示，清理背包后再发一次即可。 ### 6. `删除地图画` ``` 删除地图画 名称 → 删除自己的一幅 删除地图画 玩家名/名称 → 管理员：删除指定玩家的（中间用 / 分隔） ``` ``` 删除地图画 我的画 删除地图画 Steve/我的画 → 管理员删除 Steve 的「我的画」 ``` > **QQ 领取都需要先绑定**（QQ ↔ XboxID 白名单），没绑定会提示； > 领取时人必须**在线**，不在线请进游戏用 `/getmap`。 > **什么时候用分批？** 地图物品不能叠加——16 张的画整套领取需要 16 格背包空位。 > 背包装不下时就加参数分批：`获取地图画 我的画 第1批 每批4张`，每次只占 4 格， > 放好一批再领下一批。`第N行` 则一次正好一整行，拼墙最顺手。 *** ## 七、游戏内命令（完整用法） 在游戏聊天框输入，参数规则和 QQ 群指令完全一样（顺序随意、`第`/`张` 字可省略）。 ### 1. `/getmap` —— 查看列表 ``` /getmap /getmap help ``` 列出你所有的地图画（名称、几×几张）。 ### 2. `/getmap 名称` —— 领取整套（默认） ``` /getmap 我的画 ``` 几张地图就占几格背包空位，背包不够请用下面的分批参数。 ### 3. `/getmap 名称 [第N批] [每批M张]` / `[第N行]` —— 分批领取 ``` /getmap 我的画 第1批 → 第 1 批（每批张数 = 服务器默认值） /getmap 我的画 第2批 → 领第 2 批 /getmap 我的画 第1批 每批4张 → 每批 4 张，领第 1 批 /getmap 我的画 每批4张 → 不写批号 = 第 1 批 /getmap 我的画 第2批 每批4张 → 每批 4 张，领第 2 批 /getmap 我的画 第1行 → 按行领：第 1 行 /getmap 我的画 第2行 → 领第 2 行 ``` 领完一批聊天框会提示"下一批： /getmap 名称 第N批"，照着输入即可。 ### 4. `/getmap all` —— 一键领取全部 ``` /getmap all ``` 名下所有地图画一次全发；装不下会发到装不下为止并提示， 清理背包后再执行一次即可（已领过的可以重复领）。 ### 5. `/getmap del 名称` —— 删除 ``` /getmap del 我的画 ``` ### 6. `/getmap 玩家名/名称` —— 管理员发放他人的 需要 OP 权限，中间用 `/` 分隔；控制台也能用（无需在线校验）。 ``` /getmap Steve/我的画 ``` > QQ 群里对应的指令：`获取全部地图画`、`删除地图画 Steve/我的画`，两边功能完全同步。 *** ## 八、怎么拼成一面画墙 多张地图拼墙其实很简单，像拼拼图一样： 1. 领取后**拿着地图物品看提示文字（物品说明）**，每张都标了位置， 例如：`整幅 3×2 拼图 · 第2行 第3列` * 「第2行 第3列」= 第 2 行从左数第 3 张 2. 找一面墙，按从左到右、从上到下的顺序放**物品展示框**， 把对应行列号的地图放进对应位置的展示框 3. 整套领取背包装不下？改用按行领取（`获取地图画 名称 第1行`）， 一次正好一整行，拿到就摆上墙，再领下一行 ``` 摆放示意（3×2 的例子）： [第1行 第1列] [第1行 第2列] [第1行 第3列] [第2行 第1列] [第2行 第2列] [第2行 第3列] ``` *** ## 九、关于扣费（如果服务器开启了） * 费用按**张数**计算：`每张单价 × 本批张数` 例如单价 100 金币、分批领取（每批 8 张），一次扣 800 金币；领几批扣几批 * 扣费后如果发放失败（背包满等）会**自动全额退款** * 一键领取全部时逐幅结算，哪幅失败哪幅退，不影响其他 * 想知道单价多少，询问服主即可 *** ## 十、常见问题（FAQ） **Q：提示「背包空位不足」？** 整套领取共几张地图就需要几格空位（地图不叠加）。清理背包再领，或改用分批：`获取地图画 我的画 第1批 每批4张`，每次只占 4 格。 **Q：上传后游戏里地图是空白的？** 1. 确认领取时人在游戏里（QQ 领取要求在线，游戏内 /getmap 不用） 2. 重登一下服务器，机器人会自动补发画面 **Q：为什么我的小图只给了 1 张，别人的大图给了 8 张？** 这就是智能分割：小图切成多张不会更清晰（反而会糊），所以 1 张刚好；大图像素多，切得多才能保留清晰度。想强制多切可以指定规格（如 `2x2`）。 **Q：图片边缘被裁掉了？** 这是默认的「裁边防变形」。想完整显示就在上传时加 `留边`。 **Q：压缩包上传没反应？** 1. 必须是标准 **.zip** 格式（不支持 rar/7z） 2. 包里要有图片文件（png/jpg/webp/gif/bmp） 3. QQ 机器人需要能收到文件消息（部分协议端不支持群文件下载，此时请单张上传） **Q：名字写错了 / 不想要了？** `删除地图画 名称` 删掉重传即可（删除不退款已扣的获取费用，请先想好名字）。 **Q：上传次数被限制了？** 服务器可设置「每 N 小时最多 M 次」，提示里会写还要等多久。 **Q：能上传多大的图？** 默认单张 10MB 以内，png/jpg/webp/gif/bmp 都支持。 **Q：重启服务器后我的地图画还在吗？** 在。已放进展示框/背包里的物品一直都在，服务器重启后机器人也会自动恢复画面。 *** ## 十一、给管理员：配置项说明 配置位置：LumenBridge WebUI 的 mapart 面板（或子插件目录 `config.json`）。 **所有上限、阈值都可以自由调整，没有写死的限制。** | 配置项 | 默认值 | 说明 | | ----------- | --- | ------------------------- | | 额外允许的群 | 空 | 额外允许使用功能的群号（主群默认允许） | | 图片大小上限(MB) | 10 | 单张上传图片体积上限 | | 每人上限(幅) | 8 | 每位玩家最多保存的作品数（一幅可含多张地图） | | 全服地图上限(张) | 200 | 全服地图总张数（按张累计），防存档膨胀 | | 自动分割张数 | 2 | 关闭智能分割时的长边张数（见下） | | 单幅最大边(张) | 4 | 单幅宽/高各最多几张（4 即最大 4×4） | | 智能分割 | 开 | 按图片像素密度自动定张数（小图 1 张、大图多切） | | 小图阈值(像素) | 256 | 短边低于该像素的图片保持单张 | | 批量上限(张) | 20 | 单个压缩包内最多处理图片数，0 不限制 | | 每批领取张数 | 8 | 分批获取（`第N批`）未指定「每批M张」时使用的默认批量（默认获取仍是整套发放） | | 默认抖动渲染 | 关 | 新上传默认使用的渲染模式 | | 上一条图片有效期(秒) | 300 | 「先发图再发指令」的可引用时长 | | 获取扣费开关 | 关 | 需安装 economy 子插件 | | 获取费用(金币/张) | 100 | 按张计费 | | 上传限制窗口(小时) | 1 | 频率限制时间窗口 | | 窗口内上传上限(次) | 0 | 0 = 不限制 | **智能分割调参示例**： * 想让小图也切？把「小图阈值」调成 0，或直接关闭「智能分割」开关（回到按宽高比切割的旧模式） * 想允许更大的拼图？把「单幅最大边」调成 6（最大 6×6=36 张） * 想更省地图额度？把「小图阈值」调大（如 384，更多图保持单张） **升级说明**：从旧版本升级无需任何操作，旧数据自动迁移。新版本新增的配置项会自动补全默认值。 [/MD]