MSMP World
一个服务端 Fabric 模组,通过提供获取和设置世界数据的额外功能,扩展了 Minecraft Server Management Protocol (MSMP)。
此模组旨在为工具、仪表板、自动化系统、地图生成器、外部监控工具和集成方案提供支持,使其能够在不依赖命令解析或 RCON 技巧的情况下,以结构化方式访问世界数据。
安装
- 下载模组
.jar 文件并将其放入服务器的 mods/ 文件夹中。
- 在
server.properties 中启用管理服务器:
management-server-enabled=true
- 启动服务器。管理服务器默认将在
localhost:25576 上监听。
RPC 方法
该模组目前提供以下 MSMP RPC 方法。所有这些方法也可以通过标准的 rpc.discover MSMP 端点自动发现。
| 方法 |
描述 |
world:block |
返回指定维度中给定位置的方块 |
world:block/set |
设置指定维度中给定位置的方块 |
world:chunk/surface |
使用紧凑调色板格式返回区块(256 列)的表面方块 |
world:chunk/surface/set |
使用紧凑调色板格式批量放置区块所有 256 列的方块 |
world:path_find |
计算两个位置或实体之间的路径,模拟通用的类似玩家的陆地行走者 |
如果您需要更多用于其他目的的方法或通知,请提交 Issue
方法参考
world:block
返回指定位置的方块(ID、状态和方块实体数据)。
// 请求
{ "dimension": "minecraft:overworld", "position": [100, 64, 200] }
// 响应
{
"dimension": "minecraft:overworld",
"position": [100, 64, 200],
"block": {
"id": "minecraft:chest",
"states": { "facing": "north" },
"components": { "Items": [ { "Slot": 0, "id": "minecraft:diamond", "count": 5 } ] }
}
}
对于没有状态属性的方块,将省略 states。如果方块没有方块实体(箱子、告示牌、熔炉等),则省略 components。
world:block/set
设置指定位置的方块。返回放置后的确认状态。
// 请求
{
"dimension": "minecraft:overworld",
"position": [100, 64, 200],
"block": {
"id": "minecraft:chest",
"states": { "facing": "north" },
"components": { "Items": [ { "Slot": 0, "id": "minecraft:diamond", "count": 5 } ] }
}
}
// 响应 - 结构与 world:block 相同
states 和 components 都是可选的。缺失的状态将回退到方块的默认值(与原版 /setblock 行为匹配)。
world:chunk/surface
返回区块每个 256 列(16×16)的表面方块,使用紧凑调色板格式以避免重复相同的方块描述。
// 请求
{ "dimension": "minecraft:overworld", "chunk": [6, -2], "heightMap": "MOTION_BLOCKING_NO_LEAVES" }
// 响应(摘录 - 高度/方块始终恰好有 256 个条目)
{
"dimension": "minecraft:overworld",
"chunk": [6, -2],
"heightMap": "MOTION_BLOCKING_NO_LEAVES",
"palette": [
{ "id": "minecraft:grass_block" },
{ "id": "minecraft:water" },
{ "id": "minecraft:chest", "states": { "facing": "north" } }
],
"heights": [71, 68, 77, /* ... */],
"blocks": [0, 1, 2, /* ... */],
"blockEntities": [
{ "index": 2, "components": { "Items": [ /* ... */ ] } }
]
}
解读响应: blocks[i] 是 palette 中的索引;heights[i] 是该列表面方块的 Y 坐标。扁平索引映射到世界坐标的方式如下:
worldX = chunkX * 16 + (index / 16)
worldZ = chunkZ * 16 + (index % 16)
哨兵值: heights[i] == -2147483648 (Integer.MIN_VALUE) 和 blocks[i] == -1 表示“在此列中未找到方块”(例如世界边缘的空列)。数组长度始终恰好为 256。
blockEntities 是一个稀疏列表 - 只有在其表面具有方块实体的列才会出现在此处,引用相同的扁平 index。将其与 palette 分开保留,以便例如两个具有不同库存但方向相同的箱子仍然可以共享一个调色板条目。
heightMap 值(可选,默认为 MOTION_BLOCKING_NO_LEAVES):
| 值 |
含义 |
WORLD_SURFACE |
最顶部的非空气方块(包括雪、树叶、花朵) |
MOTION_BLOCKING |
最顶部的阻挡方块,计入水面 |
MOTION_BLOCKING_NO_LEAVES |
如上所述,但忽略树叶(显示树木下的地面) |
OCEAN_FLOOR |
海底,忽略水 |
world:chunk/surface/set
替换区块中每列的表面方块。服务器根据当前地形自动确定放置 Y 坐标 - 无需提供高度。若要在特定 Y 坐标放置方块,请使用 world:block/set。
heightMap(可选,默认为 MOTION_BLOCKING_NO_LEAVES)定义了在计算放置高度时什么算作“表面” - 与 world:chunk/surface 相同的值。例如,OCEAN_FLOOR 允许您替换海底而不触碰其上方的水面。
blocks[i] == -1: 保留此列不变。
// 请求 - 将所有表面方块涂成沙子
{
"dimension": "minecraft:overworld",
"chunk": [6, -2],
"palette": [{ "id": "minecraft:sand" }],
"blocks": [0, 0, 0, /* ... 共 256 项 */]
}
// 请求 - 使用不同的高度图替换海底
{
"dimension": "minecraft:overworld",
"chunk": [6, -2],
"heightMap": "OCEAN_FLOOR",
"palette": [{ "id": "minecraft:gravel" }],
"blocks": [0, 0, 0, /* ... */]
}
// 响应 - 结构与 world:chunk/surface 相同(包含已解析的高度作为确认)
验证会在任何世界修改之前完整运行——无效的调色板条目或无效的 blockEntities 引用会导致整个请求失败,而不是留下部分应用的区块。
world:path_find
计算两个目标之间的导航路径,模拟通用的玩家类地面行走者(不支持飞行或游泳)。当不存在路径或目标不可达时返回 found: false——这是正常结果,而非错误。
start 和 end 均接受固定位置或实体引用(通过 UUID 或玩家名称):
// 固定位置
{ "position": [100, 64, 200] }
// 任意实体(通过 UUID)
{ "entity": { "id": "069a79f4-44e9-4726-a5be-fca90e38aaf5" } }
// 在线玩家(通过名称)
{ "entity": { "name": "Steve" } }
硬性距离限制: 如果 start 和 end 之间的直线距离大于 256 格,请求将被立即拒绝。这可以通过配置文件进行配置。
// 请求 - 位置到位置
{
"dimension": "minecraft:overworld",
"start": { "position": [100, 64, 200] },
"end": { "position": [150, 70, 230] }
}
// 请求 - 实体到位置
{
"dimension": "minecraft:overworld",
"start": { "entity": { "name": "Steve" } },
"end": { "position": [150, 70, 230] }
}
// 请求 - 实体到实体
{
"dimension": "minecraft:overworld",
"start": { "entity": { "name": "Steve" } },
"end": { "entity": { "id": "069a79f4-44e9-4726-a5be-fca90e38aaf5" } }
}
// 响应 - 找到路径
{
"dimension": "minecraft:overworld",
"found": true,
"path": [
[100, 64, 200],
[101, 64, 201],
/* ... */
[150, 70, 230]
]
}
// 响应 - 未找到路径
{ "dimension": "minecraft:overworld", "found": false, "path": [] }
许可证
LGPL-3.0
MSMP World
A server-side Fabric mod that extends the Minecraft Server Management Protocol (MSMP) by providing additional functions for getting and setting world data.
This mod is designed for tooling, dashboards, automation systems, map generators, external monitoring tools, and integrations that need structured access to world data without relying on command parsing or RCON hacks.
Installation
- Download the mod
.jar and place it in your server's mods/ folder.
- Enable the Management Server in
server.properties:
management-server-enabled=true
- Start the server. The Management Server will listen on
localhost:25576 by default.
RPC Methods
The mod currently provides the following MSMP RPC methods. All of these methods are also automatically discoverable through the standard rpc.discover MSMP endpoint.
| Method |
Description |
world:block |
Returns the block at a given position in a given dimension |
world:block/set |
Sets the block at a given position in a given dimension |
world:chunk/surface |
Returns the surface blocks of a chunk (256 columns) using a compact palette format |
world:chunk/surface/set |
Bulk-places blocks across all 256 columns of a chunk using a compact palette format |
world:path_find |
Computes a path between two positions or entities, simulating a generic player-like ground walker |
If you want more methods or notifications for other purposes, please open an issue
Method Reference
world:block
Returns the block (id, states, and block-entity data) at a given position.
// Request
{ "dimension": "minecraft:overworld", "position": [100, 64, 200] }
// Response
{
"dimension": "minecraft:overworld",
"position": [100, 64, 200],
"block": {
"id": "minecraft:chest",
"states": { "facing": "north" },
"components": { "Items": [ { "Slot": 0, "id": "minecraft:diamond", "count": 5 } ] }
}
}
states is omitted for blocks with no state properties. components is omitted if the block has no block entity (Chest, Sign, Furnace, ...).
world:block/set
Sets the block at a given position. Returns the confirmed state after placement.
// Request
{
"dimension": "minecraft:overworld",
"position": [100, 64, 200],
"block": {
"id": "minecraft:chest",
"states": { "facing": "north" },
"components": { "Items": [ { "Slot": 0, "id": "minecraft:diamond", "count": 5 } ] }
}
}
// Response - same shape as world:block
states and components are both optional. Missing states fall back to the block's default values (matching Vanilla /setblock behavior).
world:chunk/surface
Returns the surface block of each of the 256 columns (16×16) of a chunk, using a compact palette format to avoid repeating identical block descriptions.
// Request
{ "dimension": "minecraft:overworld", "chunk": [6, -2], "heightMap": "MOTION_BLOCKING_NO_LEAVES" }
// Response (excerpt - heights/blocks always have exactly 256 entries)
{
"dimension": "minecraft:overworld",
"chunk": [6, -2],
"heightMap": "MOTION_BLOCKING_NO_LEAVES",
"palette": [
{ "id": "minecraft:grass_block" },
{ "id": "minecraft:water" },
{ "id": "minecraft:chest", "states": { "facing": "north" } }
],
"heights": [71, 68, 77, /* ... */],
"blocks": [0, 1, 2, /* ... */],
"blockEntities": [
{ "index": 2, "components": { "Items": [ /* ... */ ] } }
]
}
Reading the response: blocks[i] is an index into palette; heights[i] is the Y-coordinate of the surface block in that column. The flat index maps to world coordinates as:
worldX = chunkX * 16 + (index / 16)
worldZ = chunkZ * 16 + (index % 16)
Sentinel values: heights[i] == -2147483648 (Integer.MIN_VALUE) and blocks[i] == -1 mean "no block found in this column" (e.g. an empty column at the world edge). The array length is always exactly 256.
blockEntities is a sparse list - only columns that have a block entity at their surface appear here, referenced by the same flat index. Kept separate from palette so that e.g. two chests with different inventories but the same orientation can still share one palette entry.
heightMap values (optional, defaults to MOTION_BLOCKING_NO_LEAVES):
| Value |
Meaning |
WORLD_SURFACE |
Topmost non-air block (includes snow, leaves, flowers) |
MOTION_BLOCKING |
Topmost blocking block, water surface counts |
MOTION_BLOCKING_NO_LEAVES |
Like above, but leaves are ignored (shows ground under trees) |
OCEAN_FLOOR |
Ocean floor, ignores water |
world:chunk/surface/set
Replaces the surface block of each column in a chunk. The server determines the placement Y automatically from the current terrain - no need to supply heights. To place blocks at a specific Y-coordinate, use world:block/set instead.
heightMap (optional, defaults to MOTION_BLOCKING_NO_LEAVES) defines what counts as "the surface" when computing placement heights - same values as world:chunk/surface. For example, OCEAN_FLOOR lets you replace the ocean floor without touching the water surface above it.
blocks[i] == -1: leave this column untouched.
// Request - paint all surface blocks with sand
{
"dimension": "minecraft:overworld",
"chunk": [6, -2],
"palette": [{ "id": "minecraft:sand" }],
"blocks": [0, 0, 0, /* ... 256 entries total */]
}
// Request - replace ocean floor using a different heightmap
{
"dimension": "minecraft:overworld",
"chunk": [6, -2],
"heightMap": "OCEAN_FLOOR",
"palette": [{ "id": "minecraft:gravel" }],
"blocks": [0, 0, 0, /* ... */]
}
// Response - same shape as world:chunk/surface (includes resolved heights as confirmation)
Validation runs in full before any world mutation - a bad palette entry or invalid blockEntities reference fails the entire request rather than leaving a partially-applied chunk.
world:path_find
Computes a navigation path between two targets, simulating a generic player-like ground walker (no flying, no swimming). Returns found: false when no path exists or the target is unreachable - this is a normal outcome, not an error.
Both start and end accept either a fixed position or an entity reference (by UUID or player name):
// Fixed position
{ "position": [100, 64, 200] }
// Any entity by UUID
{ "entity": { "id": "069a79f4-44e9-4726-a5be-fca90e38aaf5" } }
// Online player by name
{ "entity": { "name": "Steve" } }
Hard distance limit: requests with a straight-line distance greater than 256 blocks between start and end are rejected immediately. This can be configured through the config file.
// Request - position to position
{
"dimension": "minecraft:overworld",
"start": { "position": [100, 64, 200] },
"end": { "position": [150, 70, 230] }
}
// Request - entity to position
{
"dimension": "minecraft:overworld",
"start": { "entity": { "name": "Steve" } },
"end": { "position": [150, 70, 230] }
}
// Request - entity to entity
{
"dimension": "minecraft:overworld",
"start": { "entity": { "name": "Steve" } },
"end": { "entity": { "id": "069a79f4-44e9-4726-a5be-fca90e38aaf5" } }
}
// Response - path found
{
"dimension": "minecraft:overworld",
"found": true,
"path": [
[100, 64, 200],
[101, 64, 201],
/* ... */
[150, 70, 230]
]
}
// Response - no path found
{ "dimension": "minecraft:overworld", "found": false, "path": [] }
License
LGPL-3.0
评论 0
登录后参与评分
还没有评论,来抢沙发吧