
MCAPIBridge
将Minecraft API桥接到外部程序,实现对游戏的远程控制和自动化。现支持Python、C#、Dart。将添加更多语言。
MCAPIBridge
MCAPIBridge 是一个功能强大的 Fabric Minecraft 模组,可在游戏与外部脚本(Python 等)之间建立实时 TCP Socket 连接。它提供了一套全面的 API,允许以编程方式控制世界、实体和玩家状态,作为 Minecraft 的可编程接口。
灵感来自经典的 Minecraft Pi Protocol (MCPI) 和 RaspberryJuice 插件。
⚡ 核心能力
🔌 Socket 服务器
- 端口 4711:开启一个本地 TCP 服务器,监听基于文本的命令。
- 协议:健壮的基于行的协议,兼容任何编程语言。
- 多客户端:通过多线程支持多个并发脚本连接。
🌍 世界与维度控制
- 方块操作:即时放置或查询任意方块(支持模组方块)。
- 维度支持:命令可自动定位到特定维度(主世界、下界、末地)。
- 告示牌编辑:动态修改告示牌方块上的文本。
- 服务器命令:以 OP 权限执行任意原版服务器命令(例如
/time、/weather)。
🧟 实体与物理引擎
- 高级生成:使用精确坐标和**旋转(偏航/俯仰)**召唤实体。
- 物理控制:
- 速度:对实体施加力向量以将其发射(创建抛射物)。
- 重力:为特定实体开启/关闭重力(例如,创建笔直的箭矢)。
- 实体雷达:扫描并获取指定半径内所有实体的列表。
- 粒子系统:生成具有自定义数量、速度和扩散体积的视觉效果。
- 强制注视:使用 lookAt 控制玩家或实体的注视方向,非常适合过场动画或恐怖机制。
👤 玩家管理
- 属性控制:读取和修改生命值(可突破原版限制)、饥饿值和游戏模式。
- 能力:切换飞行(即使在生存模式下)、上帝模式(无敌),并调整移动速度(行走/飞行)。
- 物品栏 API:
- 读取:获取完整物品栏内容(主物品栏、盔甲、副手)。
- 写入:给予物品或清除特定物品/槽位。
- 详细信息:访问实时数据,包括精确位置、旋转和手持物品。
- 传送:跨坐标和维度传送玩家或实体。
🖱️ 输入与事件系统
- 双端架构:包含客户端和服务端逻辑,以实现精确的输入检测。
- 射线检测交互:
- 右键:检测最远 500 格外的交互(服务端射线检测)。
- 左键:检测交互和攻击。
- 聊天监听:将游戏内聊天消息实时流式传输到外部脚本。
- 宏按键:在游戏的控制菜单中注册 5 个自定义宏按键。脚本可以监听这些特定按键的按下以触发自定义逻辑。
🔊 自定义音频系统
- 音调生成:生成具有自定义频率、时长和采样率的正弦波音调。
- WAV 文件播放:加载并播放自定义 WAV 音频文件(8/16 位 PCM,单声道/立体声)。
- 3D 空间音频:在特定世界坐标播放声音,具有真实的距离衰减。
- 动态控制:实时音量调整、循环播放、暂停/停止以及移动声源的位置更新。
- 多源混音:同时播放多个音频源(例如,和弦、环境层)。
- 音频克隆:高效克隆已加载的音频数据,用于低延迟多扬声器设置。
🖥️ 自定义屏幕系统
- 动态网络屏幕:新增自定义方块
mcapibridge:screen,可显示由脚本控制的实时图像或视频流。 - 无缝拼接:自动将相邻的屏幕方块合并为一个大显示屏,非常适合视频墙或广告牌。
- 高性能:使用客户端纹理渲染和 JPG/PNG 流式传输,以实现流畅的 30 FPS 播放。推荐使用 JPG 流式传输。
- 交互式配置:右键点击屏幕方块即可轻松配置 ID 和布局,无需命令。
- 合成配方:
G G G (玻璃板) R D R (红石、荧石粉、红石) I I I (铁锭)
⚡ 物理 IO 系统
- IO 端口方块:一种专用方块
mcapibridge:io,将 Minecraft 红石与外部硬件/脚本桥接。 - 输入模式:脚本发送信号 -> 方块发出红石能量(0-15)。
- 输出模式:方块检测红石能量 -> 向脚本发送事件。
- 实时交互:非常适合从 Minecraft 控制智能家居设备或在游戏内可视化传感器数据。
- 合成配方:
I R I (铁锭、红石、铁锭) S S S (石头)
📦 深度数据访问(NBT)
- NBT 修改:直接向实体和方块实体写入原始 NBT 数据。
- 高级自定义:创建巨人、冻结生物(
NoAI)、使实体发光,或使用类似 JSON 的 NBT 字符串填充箱子中的自定义战利品。
安装
Modrinth
⚠️ 安全警告
此模组会开启 端口 4711,并向任何连接到它的程序授予完整管理员(OP)权限。
- 请勿在未配置防火墙的公共服务器上安装此模组。
- 它仅设计用于单人游戏、局域网或私人服务器。
桥接库
Python 库
Python 示例
C# 库
C# 示例
Dart 库
Dart 示例
未来将支持更多语言。
📋 更新日志
2026/2/24
- 添加 Dart 支持
2026/2/13
- 添加 1.21.4、1.20.4、1.20.1 支持。
- 修复音频错误。现在你可以使用 audio.play 恢复已暂停的音频。
2026/2/11
- C#:添加 C# 支持。
- 1.21.1:添加 1.21.1 支持。
2026/2/10 Alpha-0.5.1
- IO 方块更新:添加
mc.io.config方法,用于通过脚本动态重新配置 IO 方块。
2026/2/9 Alpha-0.5.0
- 物理 IO 系统:添加
mcapibridge:io方块,用于将红石与外部 IO 桥接。- 输入模式:通过脚本控制游戏内红石能量。
- 输出模式:通过脚本监控游戏内红石能量变化。
- 交互式配置:右键点击打开 GUI,设置通道 ID 和模式。
- 视觉反馈:方块纹理根据模式(输入/输出)变化。
2026/2/8 Alpha-0.4.1
- 音频与视频维度支持:实现维度感知播放。屏幕和 3D 音频现在能在主世界、下界和末地之间正确隔离。
- 中途加入与恢复播放:添加状态持久化和偏移同步。新加入服务器的玩家将自动接收音频数据,并与视频完美同步地恢复播放。
- 同步调整:在音频设置中添加滑块,用于手动调整音频延迟补偿(+/- 5.00 秒)。
2026/2/6 Alpha-0.4.0
- 自定义屏幕系统:引入
mcapibridge:screen方块,用于显示实时图像和视频流。- 视频墙:支持无缝多方块屏幕拼接,并自动检测布局。
- 高分辨率流式传输:能够通过 JPG/PNG 压缩以 30 FPS 流式传输 1080p/720p 内容。
- 简易配置:右键点击打开 GUI,设置屏幕 ID。
- 音频优化:添加
audio.clone命令,可高效复制音频源,用于多扬声器设置(例如,环绕声影院),无需重新上传数据。 - 修复的错误:
- 修复 play3d 音频无法自动将音量设为 0 的问题。
- 修复有时 Socket 与桥接库仍保持连接的问题。
2026/2/4 Alpha-0.3.1
- 音频设置集成:在 Minecraft 的声音选项菜单中添加原生“MCAPIBridge Audio”音量滑块。
2026/2/4 Alpha-0.3.0
- 自定义音频系统:通过 OpenAL 添加完整的音频播放能力。
- 音调生成:创建具有可配置频率和时长的正弦波音调。
- WAV 支持:加载并播放自定义
.wav文件(自动将立体声转换为单声道)。 - 3D 空间音频:在世界坐标播放音频,具有真实的距离衰减和衰减控制。
- 动态位置:实时更新声源位置,实现环绕效果。
- 播放控制:音量调整、循环切换、暂停、停止和卸载功能。
- 多源:同时播放多个音频源,用于和弦和分层音频。
2026/2/1 Alpha-0.2.2
- 深度数据控制:为实体和方块添加 NBT 修改支持,允许高级自定义,如巨型生物或自定义战利品。
- 摄像机控制:实现
lookAtAPI,强制玩家或实体注视特定坐标。
2026/1/31 Alpha-0.2.1
- 修复错误:单次攻击或聊天事件现在可由多个已连接的脚本处理。
2026/1/31 Alpha-0.2.0
- 客户端输入:现在即使瞄准空气也能检测左/右键点击(使用客户端数据包)。
- 宏按键:在游戏设置中添加 5 个可自定义按键,脚本可监听这些按键以触发自定义动作。
🗺️ 路线图
- 更多语言桥接库:用于 ESP32 的 Arduino、用于 ESP32 的 Micropython 库。
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。