地图画 (MapDrawing)

将图片、视频、网页绘制到 Minecraft 地图上的 ToolDelta 插件

简介

地图画是一款基于 ToolDelta 框架的 Minecraft 插件，能够将图片、视频或网页内容绘制到游戏内的地图画上。支持三种渲染模式：静态图片、动态视频、以及可交互的网页画面。

主要功能

🖼️ 图片模式

• 支持多种图片格式（PNG、JPG、JPEG）
• 多种地图尺寸自定义设置
• 图片缩放或中心裁剪处理
• 实时预览功能
• 多种 mapid 获取方式（掉落物、潜影盒、展示框、ClientBoundMapItemData）

🎬 视频模式

• 支持 MP4、AVI 等常见视频格式
• 帧率优化处理
• 视频画面中心裁剪适配
• 与底图机制配合，节省传输带宽

🌐 网页模式

• 基于 Playwright 的无头浏览器渲染
• Minecraft 视角数学3D射线追踪
• 玩家视角与画面交点精确计算
• 自定义光标实时追踪
• 羊毛掉落物交互触发（单击、长按、拖动）
• 支持键盘输入、网页导航（前进/后退）
• 历史栈管理

技术特性

高性能计算

• Numba JIT 加速的图像处理核心函数
• 增量更新算法，仅传输变化像素
• 预渲染底图机制，Alpha=254 标识未覆盖区域
• 颜色量化压缩（可配置色彩级别）

坐标系统

• 严格遵循 Minecraft 坐标系（X+东、Z+南、Y+上）
• 玩家眼睛高度 1.62 格
• 展示框厚度 13/128 格
• 最大交互距离 20 格

数据格式

ClientPixels = List[{
    "Colour": {"R": int, "G": int, "B": int, "A": int},
    "Index": int
}]

项目结构

地图画/
├── __init__.py      # 插件主入口，MapBuilder 类
├── maptool.py       # 图像处理核心，MapTool 类
├── screen.py        # 网页交互模块，ScreenTool 与 WebMapRaycast 类
├── index.html       # 网页地图画前端页面
├── datas.json       # 配置数据
└── prompt.md        # 开发提示文档

环境要求

• Python 3.11+
• Minecraft Bedrock Edition
• ToolDelta 插件框架

依赖库

库名	用途
playwright	网页渲染与自动化控制
numpy	数值计算与图像处理
numba	JIT 编译加速（可选，无则回退）
orjson	高性能 JSON 序列化（可选）
opencv-python	图像与视频处理

安装

1. 确保已安装 ToolDelta 框架
2. 将本插件目录放入 插件文件/ToolDelta类式插件/ 目录
3. 安装依赖：pip install playwright numpy numba orjson opencv-python
4. 运行 playwright install chromium 安装浏览器

使用方法

命令触发

命令	功能
img_map / 地图	打开图片模式菜单
video_map / 视频地图	打开视频模式菜单
web_map / 网页地图	打开网页模式菜单

网页模式指令（聊天发送）

指令	功能
.web get	获取玩家 runtime_id
.web type <文字>	向网页输入文字
.web back	返回上一页
.web forward	前进下一页
.web url <网址>	打开指定网址
.web q / .web quit	退出网页交互模式

羊毛交互（网页模式）

羊毛颜色	动作
白色羊毛	单击
黑色羊毛	长按开始/结束
橙色羊毛	拖动开始/结束
淡灰色羊毛	滚动（预留）

工作原理

图像渲染流程

1. 图片经 cv2 读取并转换为 RGB
2. MapTool 进行尺寸适配与颜色量化
3. optimized_split_map 将图像分割为 128×128 块
4. 通过 send_packet 发送增量数据到客户端

网页射线追踪

1. 玩家位置与视角通过 PlayerAuthInput / MovePlayer 包获取
2. WebMapRaycast.cast() 计算射线与画面平面交点
3. 交点转换为网页像素坐标 (0width, 0height)
4. 坐标通过 ScreenTool 同步到浏览器光标

作者与致谢

• 作者: Mono
• 开发工具: Codex (GPT-5.4)、Trae CN、Kimi 2.5

协议

私有仓库 | 禁止泄露源码 | 禁止商用

更多信息请访问 ToolDelta 文档

---

让每一张地图都成为艺术的画布