插件 API AutoDoc

AutoDoc: qexed_config_to_mdx

提交: c74f9372d61056392610ce80b3b5d9c8c7194fd0
ABI: wasm32-unknown-unknown
编码: postcard

运行时 ABI

插件需要导出线性内存和分配函数。除 qexed_plugin_init() 外，事件与查询函数都使用 (ptr: i32, len: i32) 读取 postcard payload；查询函数返回 i64，高 32 位是响应指针，低 32 位是响应长度。

qexed_plugin_sdk::qexed_plugin_memory!();

#[unsafe(no_mangle)]
pub extern "C" fn qexed_plugin_priority() -> i32 { 100 }

memory: WASM 线性内存导出。
qexed_plugin_alloc(len: i32) -> i32: 必需，宿主用它写入 payload。
qexed_plugin_dealloc(ptr: i32, len: i32): 可选，用于释放宿主写入或插件返回的缓冲区。
qexed_plugin_priority() -> i32: 可选，数值越大越先执行。

事件与查询

导出函数	类型	Payload	Response	说明
导出函数	类型	Payload	Response	说明
`qexed_plugin_init`	事件	-	-	插件加载并完成实例化后调用一次。适合初始化配置、注册宿主资源或写入启动日志。
`qexed_plugin_player_join`	事件	`PlayerPayload`	-	玩家进入服务器时触发。
`qexed_plugin_player_leave`	事件	`PlayerPayload`	-	玩家离开服务器时触发。
`qexed_plugin_chunk_load`	事件	`ChunkPayload`	-	区块进入服务端加载视野时触发。
`qexed_plugin_chunk_unload`	事件	`ChunkPayload`	-	区块从服务端加载视野卸载时触发。
`qexed_plugin_config_reload`	事件	`ConfigReloadPayload`	-	配置加载或重载后触发，payload 中包含配置路径。
`qexed_plugin_language_change`	事件	`LanguagePayload`	-	服务器运行语言变化后触发。
`qexed_plugin_mining_speed`	查询	`MiningSpeedQuery`	`MiningSpeedResponse`	允许插件按方块、工具和附魔修改挖掘速度。
`qexed_plugin_block_drops`	查询	`BlockDropQuery`	`BlockDropResponse`	允许插件替换或追加方块掉落物。
`qexed_plugin_commands`	查询	-	`PluginCommandDefinition`	收集插件提供的玩家命令定义。
`qexed_plugin_command_execute`	查询	`PluginCommandQuery`	`PluginCommandResponse`	玩家执行插件命令时调用，返回要执行的玩家动作。
`qexed_plugin_npc_mutations`	查询	`NpcMutationQuery`	`NpcMutationResponse`	允许插件动态新增、更新或移除 NPC。
`qexed_plugin_npc_interact`	事件/查询	`NpcInteractPayload`	`PluginCommandResponse`	玩家与 NPC 交互时触发，可按主手、副手和攻击事件返回动作。
`qexed_plugin_proxy_connect_result`	事件	`ProxyConnectResultPayload`	-	跨服代理连接完成或失败后回调。
`qexed_plugin_placeholders`	查询	`PlaceholderQuery`	`PlaceholderResponse`	解析服务器文本中的插件占位符。
`qexed_plugin_player_block_step`	查询	`BlockStepPayload`	`PluginCommandResponse`	玩家踩到方块时调用，适合跳板、区域触发器等逻辑。
`qexed_plugin_player_move`	查询	`PlayerMovePayload`	`PluginCommandResponse`	玩家位置发生变化时调用。
`qexed_plugin_player_input`	查询	`PlayerInputPayload`	`PluginCommandResponse`	玩家输入状态变化时调用，适合二段跳等玩法。
`qexed_plugin_click_detected`	事件	`ClickDetectedPayload`	-	连点检测命中后通知插件。
`qexed_plugin_pathfinding`	查询	`PathfindingQuery`	`PathfindingResponse`	预留的寻路查询事件；当前推荐使用宿主导入 qexed::pathfinding_find。
`qexed_plugin_custom_entities`	查询	-	`CustomEntityRegistryResponse`	注册插件自定义实体类型及其默认 Minecraft 实体类型和 AI 标识。
`qexed_plugin_entity_ai_tick`	查询	`EntityAiTickQuery`	`EntityAiTickResponse`	实体 AI tick 时调用，插件可返回移动、看向目标或移除实体等操作。

宿主导入 API

这些函数由服务端注册在 qexed import module 中；优先通过 qexed_plugin_sdk 包装函数调用。

名称	宿主签名	SDK 包装	说明
名称	宿主签名	SDK 包装	说明
`log`	`qexed::log(ptr: i32, len: i32)`	`qexed_plugin_sdk::log(message)`	写入服务端插件日志。
`config_exists`	`qexed::config_exists(ptr: i32, len: i32) -> i32`	`qexed_plugin_sdk::config_exists(path)`	检查插件配置文件是否存在。
`config_read`	`qexed::config_read(path_ptr: i32, path_len: i32, out_ptr: i32, out_len: i32) -> i64`	`qexed_plugin_sdk::config_read(path)`	读取插件配置文件。返回负数时表示输出缓冲区需要扩大。
`config_write`	`qexed::config_write(path_ptr: i32, path_len: i32, data_ptr: i32, data_len: i32) -> i32`	`qexed_plugin_sdk::config_write(path, contents)`	写入插件配置文件。
`economy_register_currency`	`qexed::economy_register_currency(id_ptr, id_len, name_ptr, name_len, symbol_ptr, symbol_len, fractional_digits) -> i32`	`qexed_plugin_sdk::economy_register_currency(id, name, symbol, fractional_digits)`	注册经济货币。
`economy_currency_info`	`qexed::economy_currency_info(currency_ptr, currency_len, out_ptr, out_len) -> i64`	`qexed_plugin_sdk::economy_currency_info(currency)`	读取经济货币信息。
`economy_balance`	`qexed::economy_balance(player_ptr, player_len, currency_ptr, currency_len) -> i64`	`qexed_plugin_sdk::economy_balance(player, currency)`	读取玩家余额。
`economy_set_balance`	`qexed::economy_set_balance(player_ptr, player_len, currency_ptr, currency_len, amount) -> i64`	`qexed_plugin_sdk::economy_set_balance(player, currency, amount)`	设置玩家余额。
`economy_deposit`	`qexed::economy_deposit(player_ptr, player_len, currency_ptr, currency_len, amount) -> i64`	`qexed_plugin_sdk::economy_deposit(player, currency, amount)`	给玩家增加余额。
`economy_withdraw`	`qexed::economy_withdraw(player_ptr, player_len, currency_ptr, currency_len, amount) -> i64`	`qexed_plugin_sdk::economy_withdraw(player, currency, amount)`	扣除玩家余额。
`lottery_roll`	`qexed::lottery_roll(entries_ptr: i32, entries_len: i32, out_ptr: i32, out_len: i32) -> i64`	`qexed_plugin_sdk::lottery_roll(entries)`	按权重随机抽取一个值。
`pathfinding_find`	`qexed::pathfinding_find(query_ptr: i32, query_len: i32, out_ptr: i32, out_len: i32) -> i64`	`qexed_plugin_sdk::pathfinding_find(dimension, start, goal, max_nodes)`	请求服务端寻路服务返回路径节点。

Payload 类型

`PlayerPayload`

玩家事件 payload。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`uuid`	`String`	-	玩家 UUID。
`username`	`String`	-	玩家名。
`entity_id`	`i32`	-	服务端实体 ID。
`language`	`String`	`""`	玩家语言。
`dimension`	`String`	`"minecraft:overworld"`	玩家所在维度。

`PlayerPayloadOwned`

拥有所有字段的玩家 payload，用于需要嵌套保存的查询结构。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`uuid`	`String`	-	玩家 UUID。
`username`	`String`	-	玩家名。
`entity_id`	`i32`	-	服务端实体 ID。
`language`	`String`	`""`	玩家语言。
`dimension`	`String`	`"minecraft:overworld"`	玩家所在维度。

`ChunkPayload`

区块加载/卸载事件 payload。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`dimension`	`String`	-	维度资源键。
`chunk_x`	`i32`	-	区块 X 坐标。
`chunk_z`	`i32`	-	区块 Z 坐标。

`ConfigReloadPayload`

配置重载事件 payload。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`path`	`String`	-	配置路径。

`LanguagePayload`

语言变化事件 payload。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`language`	`String`	-	当前语言。

`ItemEnchantment`

原版附魔条目。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`id`	`String`	-	附魔资源键。
`level`	`i32`	-	附魔等级。

`PluginEnchantment`

插件自定义附魔条目。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`id`	`String`	-	自定义附魔 ID。
`level`	`i32`	-	附魔等级。

`MiningSpeedQuery`

挖掘速度查询。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`block_state`	`i32`	-	方块状态 ID。
`block_name`	`String`	-	方块资源键。
`item_id`	`Option<i32>`	`None`	工具物品 ID。
`enchantments`	`Vec<ItemEnchantment>`	`[]`	原版附魔。
`plugin_enchantments`	`Vec<PluginEnchantment>`	`[]`	插件附魔。
`speed`	`f32`	-	当前挖掘速度。

`MiningSpeedResponse`

挖掘速度响应。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`speed`	`Option<f32>`	`None`	直接覆盖速度。
`multiplier`	`Option<f32>`	`None`	乘法修正。
`add`	`Option<f32>`	`None`	加法修正。

`BlockDropPosition`

方块坐标。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`x`	`i32`	-	X 坐标。
`y`	`i32`	-	Y 坐标。
`z`	`i32`	-	Z 坐标。

`BlockDropQuery`

方块掉落查询。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`block_state`	`i32`	-	方块状态 ID。
`block_name`	`String`	-	方块资源键。
`position`	`BlockDropPosition`	-	方块位置。
`tool_item_id`	`Option<i32>`	`None`	工具物品 ID。
`enchantments`	`Vec<ItemEnchantment>`	`[]`	原版附魔。
`plugin_enchantments`	`Vec<PluginEnchantment>`	`[]`	插件附魔。
`default_item_id`	`Option<i32>`	`None`	默认掉落物品 ID。

`BlockDropResponse`

方块掉落响应。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`replace`	`bool`	`false`	是否替换默认掉落。
`items`	`Vec<BlockDropItem>`	`[]`	要追加或替换的物品。

`BlockDropItem`

掉落物条目。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`item_id`	`i32`	-	物品 ID。
`count`	`i32`	`1`	数量。

`BlockStepPosition`

玩家踩踏方块坐标。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`x`	`i32`	-	X 坐标。
`y`	`i32`	-	Y 坐标。
`z`	`i32`	-	Z 坐标。

`PlayerPositionPayload`

玩家或实体位置。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`x`	`f64`	-	X 坐标。
`y`	`f64`	-	Y 坐标。
`z`	`f64`	-	Z 坐标。
`yaw`	`f32`	-	水平朝向。
`pitch`	`f32`	-	俯仰角。
`on_ground`	`bool`	-	是否在地面上。

`BlockStepPayload`

玩家踩踏方块查询。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`player`	`PlayerPayloadOwned`	-	玩家。
`dimension`	`String`	-	维度资源键。
`block_state`	`i32`	-	方块状态 ID。
`block_name`	`String`	-	方块资源键。
`position`	`BlockStepPosition`	-	方块位置。
`player_position`	`PlayerPositionPayload`	-	玩家位置。

`PlayerMovePayload`

玩家移动查询。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`player`	`PlayerPayloadOwned`	-	玩家。
`dimension`	`String`	-	维度资源键。
`previous_position`	`PlayerPositionPayload`	-	移动前位置。
`position`	`PlayerPositionPayload`	-	当前位置。

`PlayerInputState`

玩家输入状态。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`forward`	`bool`	-	前进键。
`backward`	`bool`	-	后退键。
`left`	`bool`	-	左移键。
`right`	`bool`	-	右移键。
`jump`	`bool`	-	跳跃键。
`shift`	`bool`	-	潜行键。
`sprint`	`bool`	-	疾跑键。

`PlayerInputPayload`

玩家输入查询。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`player`	`PlayerPayloadOwned`	-	玩家。
`dimension`	`String`	-	维度资源键。
`position`	`PlayerPositionPayload`	-	玩家位置。
`previous_input`	`PlayerInputState`	-	上一输入状态。
`input`	`PlayerInputState`	-	当前输入状态。

`ClickDetectedPayload`

连点检测事件 payload。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`player`	`PlayerPayloadOwned`	-	玩家。
`dimension`	`String`	-	维度资源键。
`position`	`PlayerPositionPayload`	-	玩家位置。
`action`	`String`	-	点击动作。
`clicks`	`u32`	-	窗口内点击次数。
`window_ms`	`u64`	-	统计窗口毫秒数。

`PathfindingQuery`

寻路查询。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`dimension`	`String`	-	维度资源键。
`start`	`BlockDropPosition`	-	起点。
`goal`	`BlockDropPosition`	-	终点。
`max_nodes`	`usize`	`0`	最大搜索节点数。

`PathfindingResponse`

寻路响应。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`found`	`bool`	`false`	是否找到路径。
`path`	`Vec<BlockDropPosition>`	`[]`	路径节点。

`PluginCommandDefinition`

插件命令定义。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`name`	`String`	-	命令名，不包含斜杠。
`description_key`	`String`	`""`	命令说明翻译键。

`PluginCommandQuery`

插件命令执行查询。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`command`	`String`	-	命令名。
`argument`	`String`	-	原始参数文本。
`player`	`PlayerPayloadOwned`	-	执行命令的玩家。

`PluginCommandResponse`

插件动作响应。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`handled`	`bool`	`false`	插件是否处理了该调用。
`actions`	`Vec<PlayerAction>`	`[]`	服务端要执行的玩家动作。

`ProxyConnectResultPayload`

跨服连接结果事件 payload。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`player`	`PlayerPayloadOwned`	-	玩家。
`target_server`	`String`	-	目标子服。
`current_server`	`String`	`""`	当前子服。
`proxy_protocol`	`String`	`""`	代理协议。
`status_code`	`i32`	-	状态码。
`status`	`String`	-	状态文本。
`success`	`bool`	-	是否成功。
`message`	`String`	`""`	附加消息。

`PlaceholderQuery`

占位符解析查询。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`player`	`Option<PlayerPayloadOwned>`	`None`	可选玩家上下文。
`text`	`String`	-	待解析文本。
`context`	`Vec<PlaceholderContext>`	`[]`	额外上下文。

`PlaceholderContext`

占位符上下文键值对。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`key`	`String`	-	上下文键。
`value`	`String`	-	上下文值。

`PlaceholderResponse`

占位符响应。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`replacements`	`Vec<PlaceholderReplacement>`	`[]`	替换项。

`PlaceholderReplacement`

占位符替换项。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`key`	`String`	-	占位符键。
`value`	`String`	-	替换值。

`NpcInteractPayload`

NPC 交互 payload。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`player`	`PlayerPayloadOwned`	-	玩家。
`entity`	`NpcEntityPayload`	-	NPC 实体。
`action`	`String`	-	动作类型。
`hand`	`String`	`""`	交互手。
`configured_event`	`String`	`""`	配置中绑定的事件名。

`NpcEntityPayload`

NPC 实体 payload。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`key`	`String`	-	NPC 配置键。
`entity_id`	`i32`	-	服务端实体 ID。
`dimension`	`String`	-	维度资源键。
`x`	`f64`	-	X 坐标。
`y`	`f64`	-	Y 坐标。
`z`	`f64`	-	Z 坐标。
`yaw`	`f32`	-	水平朝向。
`pitch`	`f32`	-	俯仰角。

`NpcMutationQuery`

NPC 变更查询。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`reason`	`String`	-	触发原因。

`NpcMutationResponse`

NPC 变更响应。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`operations`	`Vec<NpcMutationOp>`	`[]`	变更操作列表。

`NpcMutationOp`

NPC 变更操作枚举：Upsert 或 Remove。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`Upsert { npc }`	`NpcUpsert`	-	新增或更新 NPC。
`Remove { key }`	`String`	-	移除指定 NPC。

`NpcUpsert`

NPC 新增/更新数据。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`key`	`String`	-	NPC 稳定键。
`dimension`	`String`	`"minecraft:overworld"`	维度资源键。
`x`	`f64`	-	X 坐标。
`y`	`f64`	-	Y 坐标。
`z`	`f64`	-	Z 坐标。
`yaw`	`f32`	`0`	水平朝向。
`pitch`	`f32`	`0`	俯仰角。
`name`	`String`	`""`	NPC 玩家名。
`display_name`	`String`	`""`	显示名称。
`skin_textures`	`String`	`""`	Mojang texture 属性。
`skin_signature`	`String`	`""`	Mojang texture 签名。
`look_at_players`	`bool`	`false`	是否看向附近玩家。
`main_hand_event`	`String`	`"interact"`	主手交互事件名。
`off_hand_event`	`String`	`"interact_off_hand"`	副手交互事件名。
`attack_event`	`String`	`"attack"`	攻击交互事件名。

`CustomEntityDefinition`

插件自定义实体定义。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`id`	`String`	-	自定义实体 ID，例如 demo:patrol_guard。
`entity_type`	`String`	`"minecraft:armor_stand"`	底层 Minecraft 实体类型。
`display_name`	`String`	`""`	默认显示名称。
`ai`	`String`	`""`	默认 AI 标识，例如 plugin:demo_patrol。

`CustomEntityRegistryResponse`

自定义实体注册响应。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`entities`	`Vec<CustomEntityDefinition>`	`[]`	自定义实体定义列表。

`EntityAiTickQuery`

实体 AI tick 查询。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`entity`	`EntityAiEntityPayload`	-	当前实体。
`nearby_players`	`Vec<EntityAiPlayerPayload>`	`[]`	附近玩家。
`tick_ms`	`u64`	-	AI tick 间隔毫秒数。

`EntityAiEntityPayload`

AI tick 中的实体信息。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`key`	`String`	-	实体稳定键。
`entity_id`	`i32`	-	服务端实体 ID。
`entity_type`	`String`	-	底层 Minecraft 实体类型。
`custom_type`	`String`	`""`	插件自定义实体类型。
`ai`	`String`	`""`	AI 标识。
`spawn_rule`	`String`	`""`	产生该实体的刷怪规则。
`dimension`	`String`	-	维度资源键。
`position`	`PlayerPositionPayload`	-	实体位置。

`EntityAiPlayerPayload`

AI tick 附近玩家信息。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`player`	`PlayerPayloadOwned`	-	玩家。
`position`	`PlayerPositionPayload`	-	玩家位置。

`EntityAiTickResponse`

实体 AI tick 响应。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`operations`	`Vec<EntityAiOperation>`	`[]`	AI 操作列表。

`EntityAiOperation`

实体 AI 操作枚举：MoveDelta、LookAt 或 Remove。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`MoveDelta { x, y, z, yaw, pitch }`	`f64 / Option<f32>`	-	按增量移动实体，可选更新朝向。
`LookAt { x, y, z }`	`f64`	-	让实体看向指定坐标。
`Remove`	`unit`	-	移除实体。

`PlayerAction`

服务端对玩家执行的动作枚举。

字段/变体	类型	默认值	说明
字段/变体	类型	默认值	说明
`SystemMessage`	`{ text, translate, with, overlay }`	-	发送系统消息。
`Teleport`	`{ dimension, x, y, z, yaw, pitch }`	-	传送玩家。
`Transfer`	`{ host, port, message }`	-	使用客户端转移连接。
`ProxyConnect`	`{ server, message }`	-	通过代理连接到子服。
`OpenMenu`	`{ menu }`	-	打开配置菜单。
`SetPlayersVisible`	`{ visible }`	-	切换其他玩家可见性。
`Velocity`	`{ x, y, z, additive }`	-	设置或叠加玩家速度。

最小示例

use qexed_plugin_sdk::{PlayerPayload, decode_payload};

qexed_plugin_sdk::qexed_plugin_memory!();

#[unsafe(no_mangle)]
pub extern "C" fn qexed_plugin_player_join(ptr: i32, len: i32) {
    let Some(player) = (unsafe { decode_payload::<PlayerPayload>(ptr, len) }) else {
        qexed_plugin_sdk::log("player_join decode failed");
        return;
    };
    qexed_plugin_sdk::log(&format!("{} joined", player.username));
}

更多完整示例见 plugins/examples，其中 command_npc_demo 覆盖命令、NPC、占位符、自定义实体和插件 AI。