文档和工具

Extra-API服务端系统组件通用客户端系统AI组件UI通用系统System相关API事件组件实体特效事件Event服务端实体AddEntityServerEventAttackAnimBeginServerEventAttackAnimEndServerEventEntityLoadScriptEventEntityRemoveEventEntityStartRidingEventEntityStopRidingEventJumpAnimBeginServerEventMobDieEventOnKnockBackServerEventWalkAnimBeginServerEventWalkAnimEndServerEvent物品ActorAcquiredItemServerEventActorUseItemServerEventServerItemTryUseEventServerItemUseOnEventServerPlayerTryTouchEvent玩家AddExpEventAddLevelEventAddServerPlayerEventCommandEventDelServerPlayerEventDimensionChangeServerEventOnNewArmorExchangeServerEventPlayerAttackEntityEventPlayerDieEventPlayerHurtEventPlayerRespawnEventPlayerTeleportEventPlayerTouchNewModItemEventServerChatEventServerPlayerGetExperienceOrbEvent生物DamageEventExplosionHurtEventOnFireHurtEventServerSpawnMobEvent方块DestroyBlockEventServerBlockUseEventServerEntityTryPlaceBlockEventServerExplosionBlockEventServerPlayerTryDestroyBlockEventServerPostBlockPatternEventServerPreBlockPatternEvent世界LoadServerAddonScriptsAfterOnScriptTickServerPlaceNeteaseStructureFeatureEvent抛射物ProjectileCritHitEventProjectileDoHitEffectEvent客户端实体AddEntityEventAttackAnimBeginClientEventAttackAnimEndClientEventGetEntityByCoordEventRemoveEntityPacketEventWalkAnimBeginClientEventWalkAnimEndClientEvent物品ActorAcquiredItemClientEventActorUseItemClientEventClientItemTryUseEventClientItemUseOnEventOnCarriedNewItemChangedClientEventOnItemSlotButtonClickedEventStartUsingItemClientEventStopUsingItemClientEvent控制ClientJumpButtonPressDownEventClientJumpButtonReleaseEventOnClickInGameOnClientPlayerStartMoveOnClientPlayerStopMoveOnKeyPressInGame玩家AddPlayerEventApproachEntityClientEventClientShapedRecipeTriggeredEventDimensionChangeClientEventLeaveEntityClientEventOnGroundClientEvent方块ClientBlockUseEvent世界LoadClientAddonScriptsAfterOnScriptTickClientUnLoadClientAddonScriptsBefore界面ClientChestCloseEventClientChestOpenEventClientPlayerInventoryCloseEventClientPlayerInventoryOpenEventPopScreenEventPushScreenEventUiInitFinished组件Component服务端音效systemAudio文本msg实体actionattrauxValuecollisionBoxdimensionengineTypeexDatagravityhurtmodAttrposrot指令command方块blockblockInfoblockUseEventWhiteList玩家explvplayer生物armorSlotBreathcontrolAientityEventmobSpawnmoveTonameridetame生物群系biome物品chestBlockitembanneditemrecipe世界chunkSourceexplosiongamefeaturetimeweather模型modelscale客户端音效customAudiosystemAudio文字面板textBoard实体actorCollidableactorRenderauxValueengineTypehealthmodAttrposrot方块blockInfo控制actorMotionmouseHookoperationplayerView玩家camera序列帧frameAniControlframeAniEntityBindframeAniSkeletonBindframeAniTrans物品item粒子particleControlparticleEntityBindparticleSkeletonBindparticleTrans世界game界面fognameskyRender模型model客户端表现文字面板创建文字面板特效创建粒子特效创建模型特效创建特效编辑器编辑的序列帧特效创建序列帧特效服务端实体创建生成实体创建抛射物实体创建生物实体创建物品实体创建字符串定义的生物实体

Extra-API

服务端

这里是一些服务端的基础API接口,完成基础的系统和组件的初始化,同时也能从这个module中获取到一些通用的枚举类和levelId等信息。

系统

GetServerSystemCls

  • 描述

    用于获取服务器system基类。实现新的system时,需要继承该接口返回的类

  • 返回值

    数据类型 说明
    ServerSystem 服务端系统类
  • 示例

GetSystem

  • 描述

    用于获取其他系统实例

  • 参数

    参数名 数据类型 说明
    nameSpace str 系统注册的命名空间,一般为mod名字
    systemName str 要获取的系统名称
  • 返回值

    数据类型 说明
    system 返回具体系统的实例,如果获取不到则返回 None
  • 示例

RegisterSystem

  • 描述

    用于将系统注册到引擎中,引擎会保存系统的实例,并在退出时引擎会回收。系统可以执行我们引擎赋予的基本逻辑,例如监听事件、执行Tick函数、与客户端进行通讯等。

  • 参数

    参数名 数据类型 说明
    nameSpace str 命名空间,建议为mod名字
    systemName str 系统名称,自定义名称,可以使用英文、拼音和下划线,建议尽量个性化
    clsPath str 组件类路径,路径从脚本的第一层开始算起
  • 返回值

    数据类型 说明
    system 返回具体系统的实例
  • 示例

组件

GetComponentCls

  • 描述

    用于获取服务器component基类。实现新的component时,需要继承该接口返回的类

  • 返回值

    数据类型 说明
    BaseComponent 组件基类
  • 示例

RegisterComponent

  • 描述

    用于将组件注册到引擎中

  • 参数

    参数名 数据类型 说明
    nameSpace str 命名空间,建议为mod名字
    name str 组件名称
    clsPath str 组件类路径,路径从脚本的第一层开始算起
  • 返回值

    数据类型 说明
    bool 注册成功与否
  • 示例

通用

GenerateColor

  • 描述

    生成颜色字符,用于部分组件的参数设置。

  • 参数

    参数名 数据类型 说明
    color str 颜色字符,支持的颜色有'BLACK','DARK_BLUE','DARK_GREEN','DARK_AQUA','DARK_RED','DARK_PURPLE','GOLD','GRAY','DARK_GRAY','BLUE','GREEN','AQUA','RED','LIGHT_PURPLE','YELLOW','WHITE'
  • 返回值

    数据类型 说明
    str 用于引擎接口的颜色字符
  • 示例

GetEngineNamespace

  • 描述

    获取引擎事件的命名空间。监听引擎事件时,namespace传该接口返回的namespace

  • 返回值

    数据类型 说明
    str 引擎的命名空间
  • 示例

GetEngineSystemName

  • 描述

    获取引擎系统名。监听引擎事件时,systemName传该接口返回的systemName

  • 返回值

    数据类型 说明
    str 引擎的systemName
  • 示例

GetLevelId

  • 描述

    获取levelId。某些组件需要levelId创建,可以用此接口获取levelId。其中level即为当前地图的游戏。

  • 返回值

    数据类型 说明
    str 当前地图的levelId
  • 示例

GetMinecraftEnum

  • 描述

    用于获取游戏的枚举值,具体参见Minecraft枚举值文档

  • 返回值

    数据类型 说明
    minecraftEnum 枚举集合类
  • 示例

客户端

extraClientApi中界面的一些有用的API接口函数。

系统

GetClientSystemCls

  • 描述

    用于获取客户端system基类。实现新的system时,需要继承该接口返回的类

  • 返回值

    数据类型 说明
    ClientSystem 客户端系统类
  • 示例

GetSystem

  • 描述

    用于获取其他系统实例

  • 参数

    参数名 数据类型 说明
    nameSpace str 系统注册的命名空间,一般为mod名字
    systemName str 要获取的系统名称
  • 返回值

    数据类型 说明
    system 返回具体系统的实例,如果获取不到则返回 None
  • 示例

RegisterSystem

  • 描述

    用于将系统注册到引擎中,引擎会保存系统的实例,并在退出时引擎会回收。系统可以执行我们引擎赋予的基本逻辑,例如监听事件、执行Tick函数、与服务端进行通讯等。

  • 参数

    参数名 数据类型 说明
    nameSpace str 命名空间,建议为mod名字
    systemName str 系统名称,自定义名称,可以使用英文、拼音和下划线,建议尽量个性化
    clsPath str 组件类路径,路径从脚本的第一层开始算起
  • 返回值

    数据类型 说明
    system 返回具体系统的实例
  • 示例

AI

GetNavPath

  • 描述

    获取本地玩家到目标点的寻路路径,开发者可以通过该接口定制自定义的导航系统。

  • 参数

    参数名 数据类型 说明
    pos tuple (float, float, float)目标点的坐标
    maxTrimNode int 对搜索路径进行平滑时的最大尝试格数。设置的太大会影响寻路性能。默认值16
    maxIteration int A星寻路的最大迭代次数。默认值800
    isSwimmer bool 目标点是否在水中。默认为False
  • 返回值

    数据类型 说明
    int或list 返回1:参数错误
    返回2:玩家所在chunk未加载完毕
    返回3:终点为实心方块,无法寻路
    返回list(tuple(float,float,float),):寻到路径从起点到终点的坐标点列表。注意该list可能为空,表示本地玩家离地太远,或者被堵住无法行动。
  • 备注

    • 寻路算法迭代一定次数后(即maxIteration的数值),如果未寻到目标点,接口会返回局部最优解,即当前搜索到的点的集合中,离设置目标点最近的点的路径,但是这条路径可能是不准确或错误的(例如往终点的方向是死胡同的情况)。
      出现这种可能的情况包括:目标点无法抵达(被围住等),目标点所在chunk未加载,目标点较远(但是仍在区块加载范围内)或地形较复杂(例如与终点间有很长一面墙)。
    • 上述情况中,目标点较远或地形较复杂的情况可以通过增大maxIteration的数值避免,但是这样同时也会增加客户端的卡顿。
    • 如果终点在水里需要将isSwimmer参数设为True,但如果只是路途中会经过水域是不需要的。但需要注意在水中的寻路性能非常低下,其他参数不变时,单次寻路计算出的最大路径长度会小很多。

 

StartNavTo

  • 描述

    我们提供了一个基于上述接口的导航系统实现,做法是在路径上生成序列帧以引导玩家通向目标点,并且当玩家偏离路径会重新进行导航。

  • 参数

    参数名 数据类型 说明
    pos tuple (float, float, float)目标点的坐标
    sfxPath str 构成导航路径的序列帧素材路径。样式可以参考指向上的箭头
    callback function 玩家抵达终点时会调用的回调函数。该函数需要接受一个bool参数。
    sfxIntl float 相邻两个序列帧之间的间隔。默认值2
    sfxMaxNum int 同时存在的序列帧的最大个数。默认值16
    sfxScale tuple 序列帧的宽度及高度的缩放。默认为(0.5,0.5)
    maxIteration int A星寻路的最大迭代次数。默认值800
    isSwimmer bool 目标点是否在水中。默认为False
  • 返回值

    数据类型 说明
    int 返回0:导航正常开始
    返回-1:本地玩家离地太远,或者被堵住无法行动
    返回1:参数错误
    返回2:玩家所在chunk未加载完毕
    返回3:终点为实心方块,无法寻路
  • 备注

    • 寻路算法迭代一定次数后(即maxIteration的数值),如果未寻到目标点,接口会返回局部最优解,即当前搜索到的点的集合中,离设置目标点最近的点的路径,但是这条路径可能是不准确或错误的(例如往终点的方向是死胡同的情况)。
      出现这种可能的情况包括:目标点无法抵达(被围住等),目标点所在chunk未加载,目标点较远(但是仍在区块加载范围内)或地形较复杂(例如与终点间有很长一面墙)。

    • 上述情况中,目标点较远或地形较复杂的情况可以通过增大maxIteration的数值避免,但是这样同时也会增加客户端的卡顿。

    • 如果终点在水里需要将isSwimmer参数设为True,但如果只是路途中会经过水域是不需要的。但需要注意在水中的寻路性能非常低下,其他参数不变时,单次寻路计算出的最大路径长度会小很多。

    • callback函数接受一个bool参数。当参数为True时,表示玩家到达目标点附近,但不代表导航结束,如果玩家又离开目标点,导航系统会再次尝试导航,开发者需要在某个时机手动调用停止导航(参考以下StopNav接口)。当参数为False时,表示玩家偏离航线并到了某个无法到达目标点的状态(即返回值不为0的那些情况),这种情况导航会自动终止。

    • 如果上一次导航没结束时再次调用会覆盖之前的导航

    • 使用默认参数的导航效果示例:

      img

 

StopNav

  • 描述

    终止当前的导航

  • 返回值

组件

GetComponentCls

  • 描述

    用于获取客户端component基类。实现新的component时,需要继承该接口返回的类

  • 返回值

    数据类型 说明
    BaseComponent 组件基类
  • 示例

RegisterComponent

  • 描述

    用于将组件注册到引擎中

  • 参数

    参数名 数据类型 说明
    nameSpace str 命名空间,建议为mod名字
    name str 组件名称
    clsPath str 组件类路径,路径从脚本的第一层开始算起
  • 返回值

    数据类型 说明
    bool 注册成功与否
  • 示例

UI

CreateUI

  • 描述

    创建UI,详见UI文档

  • 参数

    参数名 数据类型 说明
    nameSpace str 命名空间,建议为mod名字
    uiKey str UI唯一标识
    createParams dict 创建UI的参数,会传到UI类的init函数中
  • 返回值

    数据类型 说明
    ScreenNode UI节点
  • 示例

GetTouchPos

  • 描述

    获取点击的屏幕坐标

  • 返回值

    数据类型 说明
    tuple (float,float)屏幕坐标
  • 示例

GetUI

  • 描述

    获取UI节点,详见UI文档

  • 参数

    参数名 数据类型 说明
    nameSpace str 命名空间,建议为mod名字
    uiKey str UI唯一标识
  • 返回值

    数据类型 说明
    ScreenNode UI节点
  • 示例

HideHudGUI

  • 描述

    隐藏HUD游戏界面的游戏原生UI

  • 参数

    参数名 数据类型 说明
    isHide boolean True为隐藏原生HUD,False为恢复显示
  • 返回值

  • 示例

HideJumpGui

  • 描述

    隐藏游戏中右下角的跳跃按钮

  • 参数

    参数名 数据类型 说明
    isHide boolean 是否隐藏,True为隐藏,False为显示
  • 返回值

  • 示例

HideNeteaseStoreGui

  • 描述

    隐藏游戏中的网易商店按钮

  • 参数

    参数名 数据类型 说明
    isHide boolean 是否隐藏,True为隐藏,False为显示
  • 返回值

  • 示例

HideSlotBarGui

  • 描述

    隐藏游戏中底部中间的物品栏界面

  • 参数

    参数名 数据类型 说明
    isHide boolean 是否隐藏,True为隐藏,False为显示
  • 返回值

  • 示例

HideSneakGui

  • 描述

    隐藏游戏中左下角方向键的中心处潜行按钮

  • 参数

    参数名 数据类型 说明
    isHide boolean 是否隐藏,True为隐藏,False为显示
  • 返回值

  • 示例

HideSwimGui

  • 描述

    隐藏游戏中的浮潜按钮

  • 参数

    参数名 数据类型 说明
    isHide boolean 是否隐藏,True为隐藏,False为显示
  • 返回值

  • 示例

HideWalkGui

  • 描述

    隐藏游戏中右上角的移动类型按钮

  • 参数

    参数名 数据类型 说明
    isHide boolean 是否隐藏,True为隐藏,False为显示
  • 返回值

  • 示例

RegisterUI

  • 描述

    注册UI,创建UI前,需要先注册UI。同一UI只需要注册一次既可。详见UI文档

  • 参数

    参数名 数据类型 说明
    nameSpace str 命名空间,建议为mod名字
    uiKey str UI唯一标识
    clsPath str UI类路径
    uiNameSpace str UIjson的命名空间
  • 返回值

  • 示例

SetResponse

  • 描述

    设置原生UI是否响应,详见UI文档

  • 参数

    参数名 数据类型 说明
    response boolean 点击UI时是否屏蔽下层敲击方块/攻击实体
  • 返回值

  • 示例

通用

GenerateColor

  • 描述

    生成颜色字符,用于部分组件的参数设置。

  • 参数

    参数名 数据类型 说明
    color str 颜色字符,支持的颜色有'BLACK','DARK_BLUE','DARK_GREEN','DARK_AQUA','DARK_RED','DARK_PURPLE','GOLD','GRAY','DARK_GRAY','BLUE','GREEN','AQUA','RED','LIGHT_PURPLE','YELLOW','WHITE'
  • 返回值

    数据类型 说明
    str 用于引擎接口的颜色字符

GetEngineNamespace

  • 描述

    获取引擎事件的命名空间。监听引擎事件时,namespace传该接口返回的namespace

  • 返回值

    数据类型 说明
    str 引擎的命名空间
  • 示例

GetEngineSystemName

  • 描述

    获取引擎系统名。监听引擎事件时,systemName传该接口返回的systemName

  • 返回值

    数据类型 说明
    str 引擎的systemName
  • 示例

GetLevelId

  • 描述

    获取levelId。某些组件需要levelId创建,可以用此接口获取levelId。其中level即为当前地图的游戏。

  • 返回值

    数据类型 说明
    str 当前地图的levelId
  • 示例

GetLocalPlayerId

  • 描述

    获取本地玩家的id

  • 返回值

    数据类型 说明
    str 客户端玩家Id

GetMinecraftEnum

  • 描述

    用于获取游戏的枚举值,具体参见Minecraft枚举值文档

  • 返回值

    数据类型 说明
    minecraftEnum 枚举集合类
  • 示例

系统System相关API

系统System是我们的核心类,用于监听事件,使用组件,更新等。

获取自定义的System需要继承引擎的系统基类 ClientSystem/ServerSystem.

事件

BroadcastEvent

  • 描述

    本地广播事件,客户端system广播的事件仅客户端system能监听,服务器同理。

  • 参数

    参数名 数据类型 说明
    eventName str 事件名
    eventData dict 事件参数,一般用CreateEventData的返回值
  • 返回值

  • 示例

BroadcastToAllClient

  • 描述

    服务器广播事件到所有客户端,该接口仅服务器system有效。

  • 参数

    参数名 数据类型 说明
    eventName str 事件名
    eventData dict 事件参数,一般用CreateEventData的返回值
  • 返回值

  • 示例

CreateEventData

  • 描述

    创建自定义事件的数据,eventData用于发送事件。创建的eventData可以理解为一个dict,可以嵌套赋值dict,list和基本数据类型,但不支持tuple

  • 返回值

    数据类型 说明
    dict 事件数据
  • 示例

DefineEvent

  • 描述

    定义自定义事件

  • 参数

    参数名 数据类型 说明
    eventName str 事件名
  • 返回值

  • 示例

ListenForEvent

  • 描述

    注册监听某个系统抛出的事件。若监听引擎事件时,namespace和systemName分别为GetEngineNamespace()和GetEngineSystemName()

  • 参数

    参数名 数据类型 说明
    namespace str 所监听事件的来源系统的namespace
    systemName str 所监听事件的来源系统的systemName
    eventName str 事件名
    instance instance 回调函数所属的类的实例
    func function 回调函数
  • 返回值

  • 示例

NotifyToClient

  • 描述

    服务器发送事件到指定客户端,该接口仅服务器system有效。

  • 参数

    参数名 数据类型 说明
    targetId str 客户端对应的Id,一般就是玩家Id
    eventName str 事件名
    eventData dict 事件参数,一般用CreateEventData的返回值
  • 返回值

  • 示例

NotifyToServer

  • 描述

    客户端发送事件到服务器,该接口仅客户端system有效。

  • 参数

    参数名 数据类型 说明
    eventName str 事件名
    eventData dict 事件参数,一般用CreateEventData的返回值
  • 返回值

  • 示例

UnDefineEvent

  • 描述

    取消自定义事件

  • 参数

    参数名 数据类型 说明
    eventName str 事件名
  • 返回值

  • 示例

UnListenForEvent

  • 描述

    反注册监听某个系统抛出的事件,即不再监听。若是引擎事件,则namespace和systemName分别为GetEngineNamespace()和GetEngineSystemName()。与ListenForEvent对应。

  • 参数

    参数名 数据类型 说明
    namespace str 所监听事件的来源系统的namespace
    systemName str 所监听事件的来源系统的systemName
    eventName str 事件名
    instance instance 回调函数所属的类的实例
    func function 回调函数
  • 返回值

  • 示例

组件

CreateComponent

  • 描述

    给实体创建组件

  • 参数

    参数名 数据类型 说明
    entityId str 该组件属主的实体id
    nameSpace str 组件的命名空间,registerComponent的namespace
    name str 组件的名字
  • 返回值

    数据类型 说明
    instance 组件实例
  • 示例

DestroyComponent

  • 描述

    删除实体的组件

  • 参数

    参数名 数据类型 说明
    entityId str 该组件属主的实体id
    nameSpace str 组件的命名空间,registerComponent的namespace
    name str 组件的名字
  • 返回值

  • 示例

GetCompData

  • 描述

    获取组件数据,根据组件类型和参数不同,返回值不同

  • 参数

    参数名 数据类型 说明
    comp instance 组件实例
    moduleName str 模块名
    funcName str 方法名
    args tuple 具体函数的参数
  • 返回值

    数据类型 说明
    与组件相关 返回值与组件相关
  • 示例

GetComponent

  • 描述

    获取实体的组件

  • 参数

    参数名 数据类型 说明
    entityId str 该组件属主的实体id
    nameSpace str 组件的命名空间,registerComponent的namespace
    name str 组件的名字
  • 返回值

    数据类型 说明
    instance 组件实例或者None
  • 示例

实体

CreateEngineBullet

  • 描述

    服务端系统接口,用于创建抛射物类型的实体,具体参见创建实体部分内容

  • 参数

    参数名 数据类型 说明
    shooterId str 发射者entityId
    engineType MinecraftEnum.EntityType 弹射物类型
    pos tuple(float,float,float) 生成坐标
    direction tuple(float,float,float) 弹射物飞行方向
    power float 弹射物飞行速度
    gravity float 弹射物所受重力
    damage float 弹射物造成的伤害值
  • 返回值

    数据类型 说明
    str或None 实体Id或者None

CreateEngineEntity

  • 描述

    服务端系统接口,用于创建生物类型的实体,具体参见创建实体部分内容

  • 参数

    参数名 数据类型 说明
    engineType MinecraftEnum.EntityType 生物类型
    pos tuple(float,float,float) 生成坐标
    rot tuple(float,float) 生物面向
    dimensionId int 生成的维度,默认值为0(0为主世界,1为地狱,2为末地)
    isNpc bool 是否为npc,默认值为False。npc不会移动、转向、存盘。
  • 返回值

    数据类型 说明
    str或None 实体Id或者None

CreateEngineEntityByTypeStr

  • 描述

    服务端系统接口,利用字符串创建引擎实体,主要用于微软自定义物体,具体参见创建实体部分内容

  • 参数

    参数名 数据类型 说明
    engineTypeStr str 例如'minecraft:husk'
    pos tuple(float,float,float) 生成坐标
    rot tuple(float,float) 生物面向
    dimensionId int 生成的维度,默认值为0(0为主世界,1为地狱,2为末地)
    isNpc bool 是否为npc,默认值为False。npc不会移动、转向、存盘。
  • 返回值

    数据类型 说明
    str或None 实体Id或者None

CreateEngineItem

  • 描述

    服务端系统接口,用于创建物品实体,具体参见物品组件

  • 参数

    参数名 数据类型 说明
    pos tuple(float,float,float) 生成坐标
    itemId GetMinecraftEnum().ItemType 物品实体类型
    count int 物品的数量
    auxVal int 物品的扩展值(默认为0即可)
    modExtVal str 物品实例的标识符
    showInHand bool 物品是否显示是手上
  • 返回值

    数据类型 说明
    str或None 实体Id或者None

CreateTempEntity

  • 描述

    创建临时实体,返回的临时实体最终用于创建实体

  • 返回值

    数据类型 说明
    Entity 临时实体
  • 示例

DestroyEntity

  • 描述

    实体销毁接口

  • 参数

    参数名 数据类型 说明
    entityId str 销毁的实体ID
  • 返回值

特效

CreateEngineEffect

  • 描述

    客户端系统接口,用于创建模型挂接特效,具体参见创建特效部分内容。

  • 参数

    参数名 数据类型 说明
    path str 特效资源路径,需要加上后缀名(一般是json)
    bindEntity str 绑定实体的Id
    aniName str 选择使用哪个模型动作的特效
  • 返回值

    数据类型 说明
    int或None effectEntityId或者None

CreateEngineParticle

  • 描述

    客户端系统接口,用于创建粒子特效,具体参见创建特效部分内容

  • 参数

    参数名 数据类型 说明
    path str 特效资源路径,需要加上后缀名(一般是json)
    pos tuple (float,float,float)创建位置坐标
  • 返回值

    数据类型 说明
    int或None particleEntityId或者None

CreateEngineSfx

  • 描述

    客户端系统接口,用于创建序列帧特效,具体参见创建特效部分内容

  • 参数

    参数名 数据类型 说明
    path str 特效资源路径,不用后缀名
    pos tuple (float,float,float)创建位置,可选
    rot tuple (float,float)角度,可选
    scale float 缩放系数,可选
  • 返回值

    数据类型 说明
    int或None frameEntityId或者None

CreateEngineSfxFromEditor

  • 描述

    客户端系统接口,用于创建序列帧特效,具体参见创建特效部分内容

  • 参数

    参数名 数据类型 说明
    path str 特效资源路径,需要加上后缀名(一般是json)
    pos tuple (float,float,float)创建位置,可选
    rot tuple (float,float)角度,可选
    scale float 缩放系数,可选
  • 返回值

    数据类型 说明
    int或None frameEntityId或者None

 

事件Event

事件依赖于系统,事件需要系统才能监听触发,因此在使用事件之前需要先拥有自己的系统system。事件分为 定义事件、监听事件、反监听、发布事件和响应事件。

  • 定义事件

定义事件分为引擎定义的事件和自定义事件。引擎定义的事件不需要定义可以直接使用。自定义函数DefineEvent.

  • 监听事件

监听事件的含义是将回调函数注册到事件上,当事件发生时主动调用该回调函数。监听函数ListenForEvent.

  • 反监听事件

监听完毕后需要自行反监听该事件在System的Destroy函数中。反监听函数UnListenForEvent.

  • 发布事件

发布事件是指,在事件发生时发布这个事件通知所有监听了这个事件的回调函数。引擎定义的事件会在引擎事件发生时自动发布,自定义事件的发布需要先DefineEvent后才能发布,需要先CreateEventData创建事件数据,发布函数有BroadcastEvent / NotifyToClient / BroadcastToAllClient / NotifyToServer.

  • 响应事件

上述的发布事件很多都是广播,但是不是每条消息都需要每个system都处理,因此响应函数只会响应那些监听了这些事件且消息源有发布这些事件的时候才会响应。

响应函数会响应在监听事件时ListenForEvent的参数中的回调函数。回调函数会传入参数dict,不同事件的参数在下面具体事件中进行了说明,其中部分参数是可设置参数,可以通过修改值来改变事件的结果。

  • 示例

服务端

服务端引擎定义的事件如下

实体

AddEntityServerEvent

  • 描述

    actor实体增加,事件触发,对应客户端AddEntityEvent

  • 参数

    参数名 数据类型 说明
    id str 实体id
    posX float 位置x
    posY float 位置y
    posZ float 位置z
    dimensionId int 实体维度
    isBaby bool 是否为幼儿
    entityType int 实体类型
  • 返回值

AttackAnimBeginServerEvent

  • 描述

    当攻击动作开始时触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

  • 备注

    • 在modelComp替换骨骼动画后,该事件才生效

AttackAnimEndServerEvent

  • 描述

    当攻击动作结束时触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

  • 备注

    • 在modelComp替换骨骼动画后,该事件才生效

EntityLoadScriptEvent

  • 描述

    数据库加载实体自定义数据时触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

  • 备注

    • 只有使用过exDataComp的实体才有此事件

EntityRemoveEvent

  • 描述

    实体被删除时触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

EntityStartRidingEvent

  • 描述

    当实体骑乘上另一个实体时触发

  • 参数

    参数名 数据类型 说明
    id str 乘骑者实体id
    rideId str 被乘骑者实体id
  • 返回值

EntityStopRidingEvent

  • 描述

    当实体停止骑乘时触发

  • 参数

    参数名 数据类型 说明
    id str 乘骑者实体id
    rideId str 被乘骑者实体id
  • 返回值

JumpAnimBeginServerEvent

  • 描述

    当跳跃动作开始时触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

  • 备注

    • 在modelComp替换骨骼动画后,该事件才生效

MobDieEvent

  • 描述

    实体死亡时触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
    attacker str 伤害来源id
  • 返回值

OnKnockBackServerEvent

  • 描述

    实体被击退时触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

WalkAnimBeginServerEvent

  • 描述

    当走路动作开始时触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

  • 备注

    • 在modelComp替换骨骼动画后,该事件才生效

WalkAnimEndServerEvent

  • 描述

    当走路动作结束时触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

  • 备注

    • 在modelComp替换骨骼动画后,该事件才生效

物品

ActorAcquiredItemServerEvent

  • 描述

    触发时机:玩家获得物品时服务端抛出的事件(有些获取物品方式只会触发客户端事件,有些获取物品方式只会触发服务端事件,在使用时注意一点。)

  • 参数

    参数名 数据类型 说明
    actor str 获得物品玩家实体id
    secondaryActor str 物品给予者玩家实体id,如果不存在给予者的话,这里为空字符串
    itemName str 物品identifier
    amount int 物品数量
    acquireMethod int 获得物品的方法,详见MinecraftEnum.ItemAcquisitionMethod
  • 返回值

ActorUseItemServerEvent

  • 描述

    触发时机:玩家使用物品时服务端抛出的事件(比较特殊不走该事件的例子:1)喝牛奶;2)染料对有水的炼药锅使用;3)盔甲架装备盔甲)

  • 参数

    参数名 数据类型 说明
    playerId str 玩家实体id
    itemName str 物品identifier
    auxValue int 物品附加值
    stackSize int 数量
    useMethod int 使用物品的方法,详见MinecraftEnum.ItemUseMethodEnum
  • 返回值

ServerItemTryUseEvent

  • 描述

    玩家点击右键尝试使用物品时服务端抛出的事件

  • 参数

    参数名 数据类型 说明
    playerId str 玩家id
    itemName str 物品的identifier
    auxValue int 物品的附加值
  • 返回值

ServerItemUseOnEvent

  • 描述

    玩家在对方块使用物品时服务端抛出的事件。注:如果需要取消物品的使用需要同时在ClientItemUseOnEvent和ServerItemUseOnEvent中将ret设置为true才能正确取消。

  • 参数

    参数名 数据类型 说明
    entityId str 玩家实体id
    itemName str 物品的identifier
    auxValue int 物品的附加值
    x int 方块 x 坐标值
    y int 方块 y 坐标值
    z int 方块 z 坐标值
    face int 点击方块的面
    clickX float 点击点的x比例位置
    clickY float 点击点的y比例位置
    clickZ float 点击点的z比例位置
    ret bool 设为true可取消物品的使用
  • 返回值

ServerPlayerTryTouchEvent

  • 描述

    触发时机:玩家触碰/捡起物品时触发

  • 参数

    参数名 数据类型 说明
    playerId str 玩家Id
    entityId str 物品实体的Id
    itemName str 物品的identifier,例如"minecraft:dirt"
    auxValue int 物品的附加值
    cancel bool 设置为True时将取消本次拾取
    pickupDelay int 取消拾取后重新设置该物品的拾取cd,小于15帧将视作15帧,大于等于97813帧将视作无法拾取
  • 返回值

玩家

AddExpEvent

  • 描述

    触发时机:当玩家增加经验时触发该事件。

  • 参数

    参数名 数据类型 说明
    id str 玩家id
    addExp int 增加的经验值
  • 返回值

AddLevelEvent

  • 描述

    触发时机:当玩家升级时触发该事件。

  • 参数

    参数名 数据类型 说明
    id str 玩家id
    addLevel int 增加的等级值
    newLevel int 新的等级
  • 返回值

AddServerPlayerEvent

  • 描述

    触发时机:玩家加入时触发该事件。

  • 参数

    参数名 数据类型 说明
    id str 玩家id
    isTransfer bool 是否是切服时进入服务器,仅用于Apollo。如果是True,则表示切服时加入服务器,若是False,则表示登录进入网络游戏
    transferParam str 切服传入参数,仅用于Apollo。调用【TransferToOtherServer】或【TransferToOtherServerById】传入的切服参数
  • 返回值

CommandEvent

  • 描述

    玩家请求执行指令时触发

  • 参数

    参数名 数据类型 说明
    entityId str 玩家ID
    command str 指令字符串
    cancel bool 是否取消
  • 返回值

  • 备注

    • 该事件是玩家请求执行指令时触发的Hook,该事件不响应命令方块的指令和通过modSDK调用的指令,阻止玩家的该条指令只需要将cancel设置为True

DelServerPlayerEvent

  • 描述

    触发时机:删除玩家时触发该事件。

  • 参数

    参数名 数据类型 说明
    id str 玩家id
    isTransfer bool 是否是切服时退出服务器,仅用于Apollo。如果是True,则表示切服时退出服务器;若是False,则表示退出网络游戏
  • 返回值

DimensionChangeServerEvent

  • 描述

    玩家维度改变时服务端抛出

  • 参数

    参数名 数据类型 说明
    playerId str 玩家实体id
    fromDimensionId int 维度改变前的维度
    toDimensionId int 维度改变后的维度
    fromX float 改变前的位置x
    fromY float 改变前的位置Y
    fromZ float 改变前的位置Z
    toX float 改变后的位置x
    toY float 改变后的位置Y(该值为32767,不是真实值)
    toZ float 改变后的位置Z
  • 返回值

OnNewArmorExchangeServerEvent

  • 描述

    触发时机:玩家切换盔甲时触发该事件

  • 参数

    参数名 数据类型 说明
    slot int 槽位id
    oldArmorName str 旧装备 装备名称
    oldArmorAuxValue int 旧装备 装备附加值
    oldArmorModExtralId str 旧装备 装备自定义标识符
    newArmorName str 新装备 装备名称
    newArmorAuxValue int 新装备 装备附加值
    newArmorModExtralId str 新装备 装备自定义标识符
    playerId str 玩家 entityId
  • 返回值

  • 备注

    • 当原有的装备槽内容为空时,oldArmorName值为'minecraft:air',且oldArmor其余字段不存在
      当脱下原有装备时,且新装备为空时,参数值同理

PlayerAttackEntityEvent

  • 描述

    触发时机:当玩家攻击时触发该事件。

  • 参数

    参数名 数据类型 说明
    playerId str 玩家id
    victimId str 受击者id
    damage int 伤害值:引擎传过来的值是0 允许脚本层修改为其他数
    isValid int 脚本是否设置伤害值:1表示是;0 表示否
    cancel bool 是否取消该次攻击,默认不取消
    isKnockBack bool 是否支持击退效果,默认支持,当不支持时将屏蔽武器击退附魔效果
  • 返回值

PlayerDieEvent

  • 描述

    触发时机:当玩家死亡时触发该事件。

  • 参数

    参数名 数据类型 说明
    id str 玩家id
    attacker str 伤害来源id
  • 返回值

PlayerHurtEvent

  • 描述

    触发时机:当玩家玩家受伤害前触发该事件。

  • 参数

    参数名 数据类型 说明
    id str 受击玩家id
    attacker str 伤害来源实体id,若没有实体攻击,例如高空坠落,id为-1
  • 返回值

PlayerRespawnEvent

  • 描述

    触发时机:玩家复活时触发该事件。

  • 参数

    参数名 数据类型 说明
    id str 玩家id
  • 返回值

PlayerTeleportEvent

  • 描述

    触发时机:当玩家传送时触发该事件,如:玩家使用末影珍珠或tp指令时。

  • 参数

    参数名 数据类型 说明
    id str 玩家id
  • 返回值

PlayerTouchNewModItemEvent

  • 描述

    玩家触碰/捡起新版自定义物品时触发该事件

  • 参数

    参数名 数据类型 说明
    playerId str 玩家实体id
    entityId str 物品实体id
    itemId str 物品id
    modId str modId
    modItemId str mod物品Id
    auxValue int 物品辅助id值
    customTips str 物品的自定义tips
    extraId str 物品自定义标识符。可以用于保存数据, 区分物品
  • 返回值

ServerChatEvent

  • 描述

    玩家发送聊天信息时触发

  • 参数

    参数名 数据类型 说明
    username str 玩家名称
    playerId str 玩家id
    message str 玩家发送的聊天消息内容
    cancel bool 是否取消这个聊天事件,若取消可以设置为True
  • 返回值

  • 示例

ServerPlayerGetExperienceOrbEvent

  • 描述

    触发时机:玩家获取经验球时触发的事件

  • 参数

    参数名 数据类型 说明
    playerId str 玩家id
    experienceValue int 经验球经验值
    cancel bool 是否取消(开发者传入)
  • 返回值

  • 备注

    • cancel值设为true时,捡起的经验球不会增加经验值,但是经验球一样会消失。

生物

DamageEvent

  • 描述

    实体被攻击时触发

  • 参数

    参数名 数据类型 说明
    srcId str 伤害源id
    entityId str 被伤害id
    damage int 伤害值,允许修改,设置为0则此次造成的伤害为0
    cause str 伤害来源,详见《3-3 Minecraft枚举值文档.md》ActorDamageCause
    knock bool 是否击退被攻击者,设置该值为False则不产生击退
  • 返回值

  • 备注

    • damage值会被护甲等被吸收,不一定是最终扣血量。通过设置这个伤害值可以取消伤害。

ExplosionHurtEvent

  • 描述

    当发生爆炸并且是有创建者时触发。玩家使用打火石点燃tnt也会触发该事件。

  • 参数

    参数名 数据类型 说明
    victim str 受伤实体id
    src str 爆炸创建者id
  • 返回值

OnFireHurtEvent

  • 描述

    生物受到火焰伤害时触发

  • 参数

    参数名 数据类型 说明
    victim str 受伤实体id
    src str 火焰创建者id
  • 返回值

  • 备注

    • 仅对使用blockInfo组件放置的火焰生效

ServerSpawnMobEvent

  • 描述

    游戏内自动生成怪物时触发

  • 参数

    参数名 数据类型 说明
    identifier str 生成实体的命名空间
    type int 生成实体的类型,参考MinecraftEnum.EntityType
    baby bool 生成怪物是否是幼年怪
    x float 生成实体坐标x
    y float 生成实体坐标y
    z float 生成实体坐标z
    dimensionId int 生成实体的维度,默认值为0(0为主世界,1为地狱,2为末地)
    cancel bool 是否生成该实体
  • 返回值

  • 备注

    • 该事件是游戏内自动生成怪物的Hook,阻止游戏内生成该生物只需要将cancel设置为True。如果通过MOD API生成,前缀为custom,内置逻辑生成的生物为minecraft前缀。

方块

DestroyBlockEvent

  • 描述

    触发时机:当方块已经被破坏时触发该事件。

  • 参数

    参数名 数据类型 说明
    x int 方块x坐标
    y int 方块y坐标
    z int 方块z坐标
    face int 方块被敲击的面向id
    fullName str 方块的identifier,包含命名空间及名称
    auxData int 方块子id
    playerId str 破坏方块的玩家ID
  • 返回值

  • 备注

    • 这是在生存模式或创造模式下都会触发,而且是对于任何方块

ServerBlockUseEvent

  • 描述

    触发时机:玩家右键点击新版自定义方块(或者通过接口AddBlockItemListenForUseEvent增加监听的MC原生游戏方块)时服务端抛出该事件(该事件tick执行,需要注意效率问题)。

  • 参数

    参数名 数据类型 说明
    playerId str 玩家Id
    blockName str 方块的identifier,包含命名空间及名称
    aux int 方块子Id
    cancel bool 设置为True可拦截与方块交互的逻辑。
    x int 方块x坐标
    y int 方块y坐标
    z int 方块z坐标
  • 返回值

  • 备注

    • 有的方块是在ServerBlockUseEvent中设置cancel生效,但是有部分方块是在ClientBlockUseEvent中设置cancel才生效,如有需求建议在两个事件中同时设置cancel以保证生效。

ServerEntityTryPlaceBlockEvent

  • 描述

    触发时机:当生物试图放置方块时触发该事件。

  • 参数

    参数名 数据类型 说明
    x int 方块x坐标
    y int 方块y坐标
    z int 方块z坐标
    fullName str 方块的identifier,包含命名空间及名称
    auxData int 方块子id
    entityId str 试图放置方块的生物ID
    cancel bool 默认为False,在脚本层设置为True就能取消该方块的放置
  • 返回值

  • 备注

    • 部分放置后会产生实体的方块、可操作的方块、带有特殊逻辑的方块,不会触发该事件,包括但不限于床、门、告示牌、花盆、船、红石中继器、船、炼药锅、钟、头部模型、蛋糕、酿造台、盔甲架等。

ServerExplosionBlockEvent

  • 描述

    游戏内爆炸发生时方块爆炸事件

  • 参数

    参数名 数据类型 说明
    data list[(x,y,z,cancel),...] 爆炸涉及到的方块坐标(x,y,z),cancel是一个bool值
  • 返回值

  • 备注

    • 通过设置这个cancel的bool值为True可以将该方块的爆炸取消,例如(x,y,z,True)

ServerPlayerTryDestroyBlockEvent

  • 描述

    触发时机:当玩家试图破坏方块时触发该事件。

  • 参数

    参数名 数据类型 说明
    x int 方块x坐标
    y int 方块y坐标
    z int 方块z坐标
    fullName str 方块的identifier,包含命名空间及名称
    auxData int 方块子id
    playerId str 试图破坏方块的玩家ID
    cancel bool 默认为False,在脚本层设置为True就能取消该方块的破坏
  • 返回值

ServerPostBlockPatternEvent

  • 描述

    触发时机:用方块组合生成生物,生成生物之后触发该事件。

  • 参数

    参数名 数据类型 说明
    engineId str 玩家ID
    auxId int 方块子ID
    ret bool 是否拦截后面逻辑。默认False,不影响手上物品使用,如果设为True,拦截了手上物品的使用逻辑
    x int 方块x坐标
    y int 方块y坐标
    z int 方块z坐标
  • 返回值

ServerPreBlockPatternEvent

  • 描述

    触发时机:用方块组合生成生物,在放置最后一个组成方块时触发该事件。

  • 参数

    参数名 数据类型 说明
    enable bool 是否允许继续生成。若设为False,可阻止生成生物
    x int 方块x坐标
    y int 方块y坐标
    z int 方块z坐标
    entityWillBeGenerated str 即将生成生物的名字,如"minecraft:pig"
  • 返回值

世界

LoadServerAddonScriptsAfter

  • 描述

    服务器加载完mod时触发

  • 返回值

OnScriptTickServer

  • 描述

    服务器tick时触发,1秒有30个tick

  • 返回值

PlaceNeteaseStructureFeatureEvent

  • 描述

    触发时机:首次生成地形时,尝试通过Netease Structure Feature放置结构(通过接口AddNeteaseFeatureWhiteList增加需要监听的结构名称)时服务端抛出该事件。

  • 参数

    参数名 数据类型 说明
    structureName str 结构名称
    x int 结构坐标最小方块所在的x坐标
    y int 结构坐标最小方块所在的y坐标
    z int 结构坐标最小方块所在的z坐标
    biomeType int 该feature所放置区块的生物群系类型
    biomeName str 该feature所放置区块的生物群系名称
    cancel bool 设置为True时可阻止该结构的放置
  • 返回值

  • 备注

    • 若在本监听事件中调用其他mod SDK接口将无法生效,强烈建议本事件仅用于设置结构放置与否

抛射物

ProjectileCritHitEvent

  • 描述

    触发时机:当抛射物与头部碰撞时触发该事件。注:需调用OpenPlayerCritBox开启玩家暴头后才能触发。

  • 参数

    参数名 数据类型 说明
    id str 子弹id
    targetId str 碰撞目标id
  • 返回值

ProjectileDoHitEffectEvent

  • 描述

    触发时机:当抛射物碰撞时触发该事件

  • 参数

    参数名 数据类型 说明
    id str 子弹id
    hitTargetType str 碰撞目标类型,'ENTITY'或是'BLOCK'
    targetId str 碰撞目标id
    hitFace int 撞击在方块上的面id
    x float 碰撞x坐标
    y float 碰撞y坐标
    z float 碰撞z坐标
    blockPosX int 碰撞是方块时,方块x坐标
    blockPosY int 碰撞是方块时,方块y坐标
    blockPosZ int 碰撞是方块时,方块z坐标
    srcId str 创建者id
  • 返回值

 

客户端

客户端引擎定义的事件如下

实体

AddEntityEvent

  • 描述

    actor实体增加,事件触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

AttackAnimBeginClientEvent

  • 描述

    modelComp替换骨骼动画后,攻击动作开始,事件触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

AttackAnimEndClientEvent

  • 描述

    modelComp替换骨骼动画后,攻击动作结束,事件触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

GetEntityByCoordEvent

  • 描述

    玩家点击屏幕时触发

  • 返回值

RemoveEntityPacketEvent

  • 描述

    当使用 RemoveActorPacket 移除实体时,事件触发

  • 参数

    参数名 数据类型 说明
    id str 移除的实体id
  • 返回值

WalkAnimBeginClientEvent

  • 描述

    modelComp替换骨骼动画后,走路动作开始,事件触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

WalkAnimEndClientEvent

  • 描述

    modelComp替换骨骼动画后,走路动作结束,事件触发

  • 参数

    参数名 数据类型 说明
    id str 实体id
  • 返回值

物品

ActorAcquiredItemClientEvent

  • 描述

    触发时机:玩家获得物品时客户端抛出的事件(有些获取物品方式只会触发客户端事件,有些获取物品方式只会触发服务端事件,在使用时注意一点。)

  • 参数

    参数名 数据类型 说明
    actor str 获得物品玩家实体id
    secondaryActor str 物品给予者玩家实体id,如果不存在给予者的话,这里为空字符串
    itemName str 物品identifier
    amount int 物品数量
    acquireMethod int 获得物品的方法,详见MinecraftEnum.ItemAcquisitionMethod
  • 返回值

ActorUseItemClientEvent

  • 描述

    触发时机:玩家使用物品时客户端抛出的事件(比较特殊不走该事件的例子:1)喝牛奶;2)染料对有水的炼药锅使用;3)盔甲架装备盔甲)

  • 参数

    参数名 数据类型 说明
    playerId str 玩家实体id
    itemName str 物品identifier
    auxValue int 物品附加值
    stackSize int 数量
    useMethod int 使用物品的方法,详见MinecraftEnum.ItemUseMethodEnum
  • 返回值

ClientItemTryUseEvent

  • 描述

    玩家点击右键尝试使用物品时服务端抛出的事件

  • 参数

    参数名 数据类型 说明
    playerId str 玩家id
    itemName str 物品的identifier
    auxValue int 物品的附加值
  • 返回值

ClientItemUseOnEvent

  • 描述

    玩家在对方块使用物品时客户端抛出的事件。注:如果需要取消物品的使用需要同时在ClientItemUseOnEvent和ServerItemUseOnEvent中将ret设置为true才能正确取消。

  • 参数

    参数名 数据类型 说明
    entityId str 玩家实体id
    itemName str 物品的identifier
    auxValue int 物品的附加值
    x int 方块 x 坐标值
    y int 方块 y 坐标值
    z int 方块 z 坐标值
    face int 点击方块的面
    clickX float 点击点的x比例位置
    clickY float 点击点的y比例位置
    clickZ float 点击点的z比例位置
    ret bool 设为true可取消物品的使用
  • 返回值

OnCarriedNewItemChangedClientEvent

  • 描述

    手持物品发生变化时,触发该事件;数量改变不会通知

  • 参数

    参数名 数据类型 说明
    itemName str 切换后物品的identifier。若没有物品时为"minecraft:air"
    auxValue int 切换后物品的附加值
  • 返回值

OnItemSlotButtonClickedEvent

  • 描述

    点击快捷栏和背包栏时返回玩家背包物品槽信号

  • 参数

    参数名 数据类型 说明
    slotIndex int 点击背包按钮对应的槽编号
  • 返回值

StartUsingItemClientEvent

  • 描述

    玩家使用物品(目前仅支持Bucket、Trident、RangedWeapon、Medicine、Food、Potion、Crossbow、ChemistryStick)时抛出

  • 参数

    参数名 数据类型 说明
    playerId str 玩家实体id
    itemId str 物品当前的唯一标识
    itemName str 物品identifier
    auxValue int 物品附加值
  • 返回值

StopUsingItemClientEvent

  • 描述

    玩家停止使用物品(目前仅支持Bucket、Trident、RangedWeapon、Medicine、Food、Potion、Crossbow、ChemistryStick)时抛出

  • 参数

    参数名 数据类型 说明
    playerId str 玩家实体id
    itemId str 物品当前的唯一标识
    itemName str 物品identifier
    auxValue int 物品附加值
  • 返回值

控制

ClientJumpButtonPressDownEvent

  • 描述

    跳跃按钮按下事件,返回值设置参数只对当次按下事件起作用

  • 参数

    参数名 数据类型 说明
    continueJump bool 设置是否执行跳跃逻辑
  • 返回值

ClientJumpButtonReleaseEvent

  • 描述

    跳跃按钮按下释放事件

  • 返回值

OnClickInGame

  • 描述

    鼠标按下时触发,使用了鼠标钩子才会生效

  • 参数

    参数名 数据类型 说明
    key str "left"左键,"right"右键
  • 返回值

OnClientPlayerStartMove

  • 描述

    移动按钮按下触发事件

  • 返回值

OnClientPlayerStopMove

  • 描述

    移动按钮按下释放时触发事件

  • 返回值

OnKeyPressInGame

  • 描述

    按键按下时触发

  • 参数

    参数名 数据类型 说明
    screenName str 当前screenName
    key str 键码,详见《3-3 Minecraft枚举值文档.md》KeyBoardType
    isDown int 是否按下,按下为1,弹起为0
  • 返回值

玩家

AddPlayerEvent

  • 描述

    玩家加入游戏时触发

  • 参数

    参数名 数据类型 说明
    id str 玩家id
  • 返回值

  • 示例

ApproachEntityClientEvent

  • 描述

    玩家靠近生物时触发

  • 参数

    参数名 数据类型 说明
    playerId str 玩家实体id
    entityId str 靠近的生物实体id
  • 返回值

ClientShapedRecipeTriggeredEvent

  • 描述

    玩家获取配方物品时触发

  • 参数

    参数名 数据类型 说明
    recipeId str 配方id
  • 返回值

DimensionChangeClientEvent

  • 描述

    玩家维度改变时客户端抛出

  • 参数

    参数名 数据类型 说明
    playerId str 玩家实体id
    fromDimensionId int 维度改变前的维度
    toDimensionId int 维度改变后的维度
    fromX float 改变前的位置x
    fromY float 改变前的位置Y
    fromZ float 改变前的位置Z
    toX float 改变后的位置x
    toY float 改变后的位置Y(该值为32767,不是真实值)
    toZ float 改变后的位置Z
  • 返回值

LeaveEntityClientEvent

  • 描述

    玩家远离生物时触发

  • 参数

    参数名 数据类型 说明
    playerId str 玩家实体id
    entityId str 远离的生物实体id
  • 返回值

OnGroundClientEvent

  • 描述

    玩家着地时触发

  • 参数

    参数名 数据类型 说明
    id str 玩家id
  • 返回值

方块

ClientBlockUseEvent

  • 描述

    触发时机:玩家右键点击新版自定义方块(或者通过接口AddBlockItemListenForUseEvent增加监听的MC原生游戏方块)时客户端抛出该事件(该事件tick执行,需要注意效率问题)。

  • 参数

    参数名 数据类型 说明
    playerId str 玩家Id
    blockName str 方块的identifier,包含命名空间及名称
    aux int 方块子Id
    cancel bool 设置为True可拦截与方块交互的逻辑。
    x int 方块x坐标
    y int 方块y坐标
    z int 方块z坐标
  • 返回值

  • 备注

    • 有的方块是在ServerBlockUseEvent中设置cancel生效,但是有部分方块是在ClientBlockUseEvent中设置cancel才生效,如有需求建议在两个事件中同时设置cancel以保证生效。

世界

LoadClientAddonScriptsAfter

  • 描述

    客户端加载mod完成事件

  • 返回值

OnScriptTickClient

  • 描述

    客户端tick事件,1秒30次

  • 返回值

UnLoadClientAddonScriptsBefore

  • 描述

    客户端卸载mod之前触发

  • 返回值

界面

ClientChestCloseEvent

  • 描述

    关闭箱子界面时触发,包括小箱子,合并后大箱子和末影龙箱子

  • 返回值

ClientChestOpenEvent

  • 描述

    打开箱子界面时触发,包括小箱子,合并后大箱子和末影龙箱子

  • 参数

    参数名 数据类型 说明
    playerId str 玩家实体id
    x int 箱子位置x值
    y int 箱子位置y值
    z int 箱子位置z值
  • 返回值

ClientPlayerInventoryCloseEvent

  • 描述

    打开物品背包界面时触发

  • 返回值

ClientPlayerInventoryOpenEvent

  • 描述

    打开物品背包界面时触发

  • 返回值

PopScreenEvent

  • 描述

    screen移除触发

  • 参数

    参数名 数据类型 说明
    screenName str UI名字
  • 返回值

PushScreenEvent

  • 描述

    screen创建触发

  • 参数

    参数名 数据类型 说明
    screenName str UI名字
  • 返回值

UiInitFinished

  • 描述

    UI初始化框架完成,此时可以创建UI

  • 返回值

 

组件Component

组件是为了完成某个或某些特定逻辑功能的数据集合,组件只会保存数据并不会执行相应的逻辑,只有组件在System中更新的时候,System从判断组件是否需要更新,从组件中拿到需要更新的数据来执行相应的逻辑功能。 组件分为引擎组件和自定义组件。引擎组件的参数类型和功能都是确定好的,玩家可以创建Create或获取Get组件来完成逻辑功能。自定义组件需要自定义组件的数据结构,自定义组件的更新逻辑。

服务端

音效

systemAudio

PlaySystemSound(playerId, soundId, pos, blockId, entityType, isBaby, isGlobal)

  • 描述

    播放游戏内原有内容

  • 参数

    参数名 数据类型 说明
    playerId str 玩家id
    soundId SysSoundType GetMinecraftEnum().SysSoundType.*
    pos (float,float,float) 音源位置
    blockId BlockType GetMinecraftEnum().BlockType.*
    entityType EntityType GetMinecraftEnum().EntityType.*
    isBaby bool 是否为幼儿音效
    isGlobal bool 是否为全局
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 由于游戏中音效是通过事件触发的。例如:鸡的死亡音效:因为死亡跟block无关,因此 soundId -- Death, entityType -- Chicken, blockId -- -1
    • 着地音效:因为着地到不同的block,音效是不一样的, 因此 soundId -- Fall, entityType -- -1, blockId -- grass

文本

msg

SendMsg(name, msg)

  • 描述

    创建消息实体

  • 参数

    参数名 数据类型 说明
    name str 发送者玩家的名字
    msg str 消息内容
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • name参数需要设置玩家的名字(可通过name组件获取),如果设置的玩家名字不存在,则随机找一个玩家发出该消息

实体

action

GetAttackTarget()

  • 描述

    获取攻击目标

  • 返回值

    数据类型 说明
    str 攻击目标实体id
  • 示例

GetHurtBy()

  • 描述

    获取攻击自己的对象实体id

  • 返回值

    数据类型 说明
    str 攻击自己的对象实体id
  • 示例

SetAttackTarget(targetId)

  • 描述

    设置攻击目标

  • 参数

    参数名 数据类型 说明
    targetId str 攻击目标实体id
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SetHurtBy(attackerId)

  • 描述

    设置攻击自己的对象实体id

  • 参数

    参数名 数据类型 说明
    attackerId str 攻击自己的对象实体id
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SetMobKnockback(xd, zd, power, height, heightCap)

  • 描述

    设置击退的初始速度,需要考虑阻力的影响

  • 参数

    参数名 数据类型 说明
    xd float x轴方向,用來控制角度
    zd float z轴方向,用來控制角度
    power float 用来控制水平方向的初速度
    height float 竖直方向的初速度
    heightCap float 向上速度阈值,当实体本身已经有向上的速度时需要考虑这个值,用来确保最终向上的速度不会超过heightCap
  • 返回值

    数据类型 说明
    None 无返回值
  • 示例

attr

GetAttrMaxValue(type)

  • 描述

    获取属性最大值

  • 参数

    参数名 数据类型 说明
    type AttrType GetMinecraftEnum().AttrType.*
  • 返回值

    数据类型 说明
    value 属性值结果
  • 示例

GetAttrValue(type)

  • 描述

    获取属性值

  • 参数

    参数名 数据类型 说明
    type AttrType GetMinecraftEnum().AttrType.*
  • 返回值

    数据类型 说明
    value 属性结果
  • 示例

SetAttrMaxValue(type, value)

  • 描述

    设置属性最大值

  • 参数

    参数名 数据类型 说明
    type AttrType GetMinecraftEnum().AttrType.*
    type value 属性值
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SetAttrValue(type, value)

  • 描述

    设置属性值

  • 参数

    参数名 数据类型 说明
    type AttrType GetMinecraftEnum().AttrType.*
    type value 属性值
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

auxValue

GetAuxValue()

  • 描述

    获取射出的弓箭或投掷出的药水的数据值

  • 返回值

    数据类型 说明
    int auxValue
  • 示例

collisionBox

GetSize()

  • 描述

    获取实体的包围盒

  • 返回值

    数据类型 说明
    tuple(int,int) 包围盒大小
  • 示例

SetSize(size)

  • 描述

    设置实体的包围盒

  • 参数

    参数名 数据类型 说明
    size tuple(int,int) 第一位表示宽度和长度,第二位表示高度
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 对新生产的实体需要经过5帧之后再设置包围盒的大小才会生效

dimension

ChangePlayerDimension(dimensionId, pos)

  • 描述

    传送玩家

  • 参数

    参数名 数据类型 说明
    dimensionId int 维度,0-overWorld; 1-nether; 2-theEnd
    pos tuple(int,int,int) 传送的坐标
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

GetPlayerDimensionId()

  • 描述

    获取玩家dimension

  • 返回值

    数据类型 说明
    int 玩家维度
  • 示例

MirrorDimension(fromId, toId)

  • 描述

    复制不同dimension的地形

  • 参数

    参数名 数据类型 说明
    fromId int 原dimensionId
    toId int 目标dimensionId
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

engineType

GetEngineType()

  • 描述

    获取实体在游戏中的类型id,详见`GetMinecraftEnum().EntityType

  • 返回值

    数据类型 说明
    EntityType GetMinecraftEnum().EntityType.*
  • 示例

GetEngineTypeStr()

  • 描述

    获取实体在游戏中的类型id的str

  • 返回值

    数据类型 说明
    str 实体类型的string描述
  • 示例

exData

GetExtraData(key)

  • 描述

    用于保存实体数据和全局数据,数据存放到leveldb

  • 参数

    参数名 数据类型 说明
    key str 自定义key
  • 返回值

    数据类型 说明
    value 设定的value值
  • 示例

SetExtraData(key, value)

  • 描述

    用于保存实体数据和全局数据,数据存放到leveldb

  • 参数

    参数名 数据类型 说明
    key str 自定义key
    value value 支持python基本数据类型,tuple不支持
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 用levelId创建组件时,数据存放在全局;用entityId创建时,存放在实体中。创建entity和level的extraData需要用不同变量创建该组件。

gravity

GetGravity()

  • 描述

    获取实体的重力因子,当生物重力因子为0时则应用世界的重力因子

  • 返回值

    数据类型 说明
    float 重力因子
  • 示例

SetGravity(gravity)

  • 描述

    设置实体的重力因子,当生物重力因子为0时则应用世界的重力因子

  • 参数

    参数名 数据类型 说明
    gravity float 负数,表示每帧向下的速度
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

hurt

SetHurtByEntity(attackerId, damage, byPassArmor)

  • 描述

    对实体造成伤害

  • 参数

    参数名 数据类型 说明
    attackerId str 伤害来源的实体id
    damage int 伤害值
    bypassArmor bool 是否忽略护甲
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

modAttr

用于支持脚本层的属性管理

GetAttr(paramName, defaultValue)

  • 描述

    获取属性值

  • 参数

    参数名 数据类型 说明
    paramName str 属性名称,str的名称建议以mod命名为前缀,避免多个mod之间冲突
    defaultValue PyObject 属性默认值,属性不存在时返回该默认值,此时属性值依然未设置
  • 返回值

    数据类型 说明
    PyObject 返回属性值
  • 示例

  • 备注

    • defaultValue不传的时候默认为None

SetAttr(paramName, paramValue)

  • 描述

    设置属性值

  • 参数

    参数名 数据类型 说明
    paramName str 属性名称,str的名称建议以mod命名为前缀,避免多个mod之间冲突
    paramValue PyObject 属性值,支持python基础数据
  • 返回值

  • 示例

  • 备注

    • 注意:tuple、set在同步时会转成list。建议优先使用数字和字符串等非集合类型。

pos

GetPos()

  • 描述

    获取实体位置

  • 返回值

    数据类型 说明
    tuple(float,float,float) 位置信息
  • 示例

SetPos(pos)

  • 描述

    设置实体位置

  • 参数

    参数名 数据类型 说明
    pos tuple(int,int,int) xyz值
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

rot

GetRot()

  • 描述

    获取实体角度

  • 返回值

    数据类型 说明
    tuple(float,float) (上下角度,左右角度)单位是角度而不是弧度
  • 示例

SetRot(rot)

  • 描述

    设置体角度

  • 参数

    参数名 数据类型 说明
    rot tuple(float,float) (上下角度,左右角度)单位是角度而不是弧度
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

指令

command

SetCommand(cmdStr, playerId)

  • 描述

    使用游戏内指令

  • 参数

    参数名 数据类型 说明
    cmdStr str 指令
    playerId str 玩家id:可选,如果playerId不设置,则随机选择玩家
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

方块

block

RegisterBlockPatterns(pattern, defines, result_actor_name)

  • 描述

    注册特殊方块组合

  • 参数

    参数名 数据类型 说明
    pattern list 方块组合位置
    defines dict 方块组合类型
    result_actor_name str 合成结果
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 与物品配方不同,如果在pattern和defines中不指明空气方块,在pattern中出现defines中没有出现的字符(包括“ ”空字符),那么该位置可以匹配任何方块

blockInfo

GetBlockLightLevel(pos)

  • 描述

    获取方块位置的光照等级

  • 参数

    参数名 数据类型 说明
    pos (int,int,int) 方块位置
  • 返回值

    数据类型 说明
    int 光照等级
  • 示例

GetBlockNew(pos)

  • 描述

    获取某一位置的block

  • 参数

    参数名 数据类型 说明
    pos (int,int,int) 方块位置
  • 返回值

    数据类型 说明
    dict 方块信息字典,详见SetBlockNew的备注
  • 示例

  • 备注

    • 已经加载的地形才能获取方块信息

SetBlockNew(pos, blockDict)

  • 描述

    设置某一位置的方块

  • 参数

    参数名 数据类型 说明
    pos (int,int,int) 方块位置
    blockDict dict 方块信息字典
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 已经加载的地形才能设置方块

      方块信息字典 blockDict

      关键字 数据类型 说明
      name str 必须设置,方块identifier,包含命名空间及名称,如minecraft:air
      aux int 方块附加值,可缺省,默认为0

原版方块的identifier可以在这里查找:https://minecraft-zh.gamepedia.com/基岩版数据值

blockUseEventWhiteList

管理方块对BlockUseEvent/ClientBlockUseEvent事件在脚本层的监听

AddBlockItemListenForUseEvent(blockName)

  • 描述

    增加blockName方块对BlockUseEvent/ClientBlockUseEvent事件的脚本层监听

  • 参数

    参数名 数据类型 说明
    blockName str 方块名称
  • 返回值

    数据类型 说明
    bool 是否增加成功
  • 示例

ClearAllListenForBlockUseEventItems()

  • 描述

    清空所有已添加方块对BlockUseEvent/ClientBlockUseEvent事件的脚本层监听

  • 返回值

    数据类型 说明
    bool 是否清空成功
  • 示例

RemoveBlockItemListenForUseEvent(blockName)

  • 描述

    移除blockName方块对BlockUseEvent/ClientBlockUseEvent事件的脚本层监听

  • 参数

    参数名 数据类型 说明
    blockName str 方块名称
  • 返回值

    数据类型 说明
    bool 是否移除成功
  • 示例

玩家

exp

GetPlayerExp()

  • 描述

    获取玩家经验值

  • 返回值

    数据类型 说明
    float 玩家经验值
  • 示例

lv

GetPlayerLevel()

  • 描述

    获取玩家等级

  • 返回值

    数据类型 说明
    int 玩家等级
  • 示例

player

ClosePlayerCritBox()

  • 描述

    关闭玩家爆头,关闭后将无法触发ProjectileCritHitEvent事件。

  • 返回值

  • 示例

GetPlayerHunger()

  • 描述

    获取玩家饥饿度,展示在UI饥饿度进度条上,初始值为20,即每一个鸡腿代表2个饥饿度。饱和度(saturation):玩家当前饱和度,初始值为5,最大值始终为玩家当前饥饿度(hunger),该值直接影响玩家饥饿度(hunger)。1)增加方法:吃食物。 2)减少方法:每触发一次消耗事件,该值减少1,如果该值不大于0,直接把玩家饥饿度(hunger)减少1。

  • 返回值

    数据类型 说明
    float 玩家饥饿度
  • 示例

GetPlayerMaxExhaustionValue()

  • 描述

    获取玩家foodExhaustionLevel的归零值,常量值,默认为4。消耗度(exhaustion)是指玩家当前消耗度水平,初始值为0,该值会随着玩家一系列动作(如跳跃)的影响而增加,当该值大于最大消耗度(maxExhaustion)后归零,并且把饱和度(saturation)减少1(为了说明饥饿度机制,我们将此定义为消耗事件

  • 返回值

    数据类型 说明
    float 玩家foodExhaustionLevel的归零值
  • 示例

OpenPlayerCritBox()

  • 描述

    开启玩家爆头,开启后才能触发ProjectileCritHitEvent事件。

  • 返回值

  • 示例

SetPlayerHunger(value)

  • 描述

    设置玩家饥饿度。

  • 参数

    参数名 数据类型 说明
    value float 饥饿度
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

SetPlayerMaxExhaustionValue(value)

  • 描述

    设置玩家foodExhaustionLevel的归零值,通过调整最大消耗度(maxExhaustion)的大小,就可以加快或者减慢饥饿度(hunger)的消耗,当最大消耗度(maxExhaustion)很大时,饥饿度可以看似一直不下降

  • 参数

    参数名 数据类型 说明
    value float foodExhaustionLevel的归零值
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

生物

armorSlot

GetArmorNew(slotPos)

  • 描述

    获取装备

  • 参数

    参数名 数据类型 说明
    slotPos ArmorSlotType GetMinecraftEnum().ArmorSlotType.*
  • 返回值

    数据类型 说明
    tuple 装备tuple(itemName,auxValue,extraId),不存在时为minecraft:air
  • 示例

SetArmorNew(slotPos, armorName, extraId, enchantData)

  • 描述

    设置装备

  • 参数

    参数名 数据类型 说明
    slotPos int ArmorSlotType GetMinecraftEnum().ArmorSlotType.*
    armorName str 装备名称
    extraId str 装备自定义标识符
    enchantData list[(int,int)] list[(enchant.type,enchant.level)]附魔值
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • armorName设置为"minecraft:air"或者"",可以置空该槽位的装备

Breath

GetCurrentAirSupply()

  • 描述

    生物当前氧气储备值

  • 返回值

    数据类型 说明
    int 生物当前氧气储备值
  • 示例

GetMaxAirSupply()

  • 描述

    获取生物最大氧气储备值

  • 返回值

    数据类型 说明
    int 最大氧气储备值
  • 示例

GetUnitBubbleAirSupply()

  • 描述

    单位气泡数对应的氧气储备值

  • 返回值

    数据类型 说明
    int 单位气泡数对应的氧气储备值
  • 示例

IsConsumingAirSupply()

  • 描述

    获取生物当前是否在消耗氧气

  • 返回值

    数据类型 说明
    bool 是否消耗氧气
  • 示例

SetCurrentAirSupply(data)

  • 描述

    获取生物氧气储备值

  • 参数

    参数名 数据类型 说明
    data int 设置生物当前氧气值
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SetMaxAirSupply(data)

  • 描述

    获取生物最大氧气储备值

  • 参数

    参数名 数据类型 说明
    data int 设置生物最大氧气值
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

controlAi

SetBlockControlAi(isBlock)

  • 描述

    设置屏蔽生物原生AI

  • 参数

    参数名 数据类型 说明
    isBlock bool 是否保留AI,false为屏蔽
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 屏蔽AI后的生物无法行动,不受重力且不会被推动。但是可以受到伤害,也可以被玩家交互(例如马被骑或村民被交易)

entityEvent

TriggerCustomEvent(entityId, eventName)

  • 描述

    触发生物自定义事件

  • 参数

    参数名 数据类型 说明
    entityId str 生物Id
    eventName str 事件名称
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 触发苦力怕爆炸

      在苦力怕的entity json文件中events字段下增加如下事件,然后在mod中运行示例代码:

mobSpawn

SpawnCustomModule(biomeType, change, entityType, probability, minCount, maxCount, environment, minBrightness, maxBrightness, minHeight, maxHeight)

  • 描述

    设置自定义刷怪

  • 参数

    参数名 数据类型 说明
    biomeType BiomeType GetMinecraftEnum().BiomeType.*
    change Change GetMinecraftEnum().Change.*
    entityType EntityType GetMinecraftEnum().EntityType.*
    probability int 生成的权重[1, 10]
    minCount int 最小生成数量[0, 10]
    maxCount int 最大生成数量[0, 10]
    environment int 1:生成在表面;2:生成在水里
    minBrightness int 生成该生物时的最小光照[1, 15],不设置时使用默认值
    maxBrightness int 生成该生物时的最大光照[1, 15],不设置时使用默认值
    minHeight int 生成该生物时最小的海拔高度[0, 256],不设置时使用默认值
    maxHeight int 生成该生物时最大的海拔高度[0, 256],不设置时使用默认值
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

moveTo

SetMoveSetting(pos, speed, maxIteration, callback)

  • 描述

    寻路组件

  • 参数

    参数名 数据类型 说明
    pos (float,float,float) 寻路目标位置
    speed float 移动速度
    maxIteration int 寻路算法最大迭代次数 默认200
    callback function 寻路结束回调函数
  • 返回值

  • 示例

  • 备注

    • 目前仅支持陆地行走的生物,对于飞行、游泳、爬墙的生物暂不支持。

    • 不同的生物拥有不同的默认最大跟随距离,若要寻路的目标点距离大于此值引擎会拒绝寻路,要修改该距离可以通过在entity的json中配置.

    • 关于maxIteration参数

      该参数会影响实际寻到路径的长度。若寻路算法迭代一定次数后,未寻到目标点,会返回局部最优解,即生物只会走到半路。在无大型障碍物的情况下,参数对应的参考寻路距离如下:该参数默认值200,最大值2000,请开发者根据实际情况选择。

      maxIteration 与目标点直线距离
      200 13
      500 20
      1000 30
      2000 43
    • 关于callback函数

      该函数需要接受两个参数,第一个参数为寻路的entityId,类型str,第二个参数为寻路结果,类型int (玩家获取到的位置比地面会高1.62格,若以玩家位置为目标点需要先把y轴减去1.62,否则callback会一直返回1)

      结果 说明
      -3 寻路失败,大于跟随距离,或者对正在寻路的飞行系生物使用
      -2 寻路失败,生物没有寻路组件(指minecraft:navigation)
      -1 寻路失败,参数错误,或生物不存在
      0 寻路完成。到达设定的目标点
      1 寻路完成,但未到达目标点(可能由于maxIteration参数偏小)
      2 寻路中断。中途遇到障碍物被阻碍
      3 寻路中断。被生物原版寻路行为覆盖,或寻路未结束时重复调用moveTo组件

name

GetName()

  • 描述

    获取生物name

  • 返回值

    数据类型 说明
    str 生物名称
  • 示例

SetName(name)

  • 描述

    用于生成nameTag,玩家和新版流浪商人暂不支持

  • 参数

    参数名 数据类型 说明
    name str 名称
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

ride

SetCanOtherPlayerRide(tamedEntityId, canRide)

  • 描述

    设置其他玩家受否有权限骑乘,True表示每个玩家都能骑乘,False只有驯服者才能骑乘

  • 参数

    参数名 数据类型 说明
    tamedEntityId str 驯服骑乘的生物id
    canRide bool 是否控制
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SetControl(tamedEntityId, isControl)

  • 描述

    设置是否拥有该生物控制权,控制行走跳跃

  • 参数

    参数名 数据类型 说明
    tamedEntityId str 驯服骑乘的生物id
    isControl bool 是否控制
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SetEntityRide(playerId, tamedEntityId)

  • 描述

    设置生物骑乘

  • 参数

    参数名 数据类型 说明
    playerId str 玩家id
    tamedEntityId str 驯服骑乘的生物id
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 骑乘信息会被存盘

SetRidePos(tamedEntityId, pos)

  • 描述

    设置生物骑乘位置

  • 参数

    参数名 数据类型 说明
    tamedEntityId str 驯服骑乘的生物id
    pos (float,float,float) 骑乘时挂接点
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SetShowRideUI(tamedEntityId, isShowUI)

  • 描述

    设置是否显示马匹的HI界面,建议不显示

  • 参数

    参数名 数据类型 说明
    tamedEntityId str 驯服骑乘的生物id
    isShowUI bool 是否显示UI
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

tame

GetOwnerId()

  • 描述

    获取驯服生物的主人id

  • 返回值

    数据类型 说明
    str 主人id,不存在时返回None
  • 示例

SetEntityTamed(playerId, tamedId)

  • 描述

    设置生物驯服,需要配合 entityEvent组件使用。该类驯服不包含骑乘功能。

  • 参数

    参数名 数据类型 说明
    playerId str 驯服玩家Id
    tamedId str 被驯服的生物Id
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

     

  • 备注

    • 设置生物json文件能够被驯服

      1. 修改生物entity json文件:- 增加 minecraft:tameable 组件- 增加 tame 组件集合描述,其中minecraft:behavior.follow_owner优先级要高于已有搜寻状态的优先级- event事件增加对应的on_tame事件,事件执行移除不想管的组件集合,添加刚刚设置的新tame组件集合2. 设置驯服主体和被驯服主体entityId,通过设置tameSetting属性3. 设置触发对应的驯服事件 - 驯服苦力怕 json做如下修改

生物群系

biome

GetBiomeName(pos)

  • 描述

    获取某一位置所属的生物群系信息

  • 参数

    参数名 数据类型 说明
    pos (int,int,int) 指定位置
  • 返回值

    数据类型 说明
    str 该位置所属生物群系name
  • 示例

  • 备注

    • 已经加载的地形才能获取生物群系信息

物品

chestBlock

GetChestBoxItem(playerId, pos, slotPos)

  • 描述

    获取箱子物品

  • 参数

    参数名 数据类型 说明
    playerId str 玩家id
    pos (int,int,int) 箱子位置
    slotPos int 箱子槽位
  • 返回值

    数据类型 说明
    itemDict 物品信息字典,没有物品则返回None
  • 示例

  • 备注

    • 物品信息字典 itemDict

      关键字 数据类型 说明
      itemName str 物品的identifier
      showInHand bool 是否显示在手上,默认为true
      count int 数量
      auxValue int 物品附加值
      enchantData list 附魔数据
      customTips str 物品的自定义tips
      extraId str 物品自定义标识符。可以用于保存数据, 区分物品

GetChestBoxSize(playerId, pos)

  • 描述

    获取箱子容量大小

  • 参数

    参数名 数据类型 说明
    playerId str 玩家id
    pos (int,int,int) 箱子位置
  • 返回值

    数据类型 说明
    int 箱子大小,错误值-1
  • 示例

SetChestBoxItemNum(playerId, pos, slotPos, num)

  • 描述

    设置箱子槽位物品数目

  • 参数

    参数名 数据类型 说明
    playerId str 玩家id
    pos (int,int,int) 箱子位置
    slotPos int 箱子槽位
    num int 箱子数目
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SpawnItemToChestBlock(itemDict, playerId, slotPos, blockPos)

  • 描述

    添加物品到箱子

  • 参数

    参数名 数据类型 说明
    itemDict dict 物品字典
    playerId str 玩家id
    slotPos int 箱子槽位
    blockPos (int,int,int) 箱子位置
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 物品信息字典 itemDict

      关键字 数据类型 说明
      itemName str 物品的identifier,若设置为空为"minecraft:air"
      count int 必须设置 数量
      auxValue int 必须设置 物品附加值
      showInHand bool 可选设置 是否显示在手上,默认为true
      enchantData list 可选设置 附魔数据
      customTips str 可选设置 物品的自定义tips
      extraId str 可选设置 物品自定义标识符。可以用于保存数据, 区分物品

itembanned

AddBannedItem(itemName)

  • 描述

    增加禁用物品

  • 参数

    参数名 数据类型 说明
    itemName str 物品标识符,格式[namespace:name:auxvalue],auxvalue默认为0,auxvalue为*时候匹配任意auxvalue值。例如:minecraft:egg(也可以通过填写配置文件config/banned_items.json进行启动禁用)
  • 返回值

    数据类型 说明
    bool 是否增加成功
  • 示例

ClearBannedItems()

  • 描述

    清空禁用物品

  • 返回值

    数据类型 说明
    bool 是否清空成功
  • 示例

RemoveBannedItem(itemName)

  • 描述

    移除禁用物品

  • 参数

    参数名 数据类型 说明
    itemName str 物品标识符,格式[namespace:name:auxvalue],auxvalue默认为0,auxvalue为*时候匹配任意auxvalue值。
  • 返回值

    数据类型 说明
    bool 是否移除成功
  • 示例

item

AddEnchantToInvItem(slotPos, enchantType, level)

  • 描述

    给物品栏的物品添加附魔信息

  • 参数

    参数名 数据类型 说明
    slotPos int 物品栏槽位
    enchantType int 附魔类型,可以查看枚举值文档
    level int 附魔等级
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

GetInvItemEnchantData(slotPos)

  • 描述

    获取物品栏的物品附魔信息

  • 参数

    参数名 数据类型 说明
    slotPos int 物品栏槽位
  • 返回值

    数据类型 说明
    list[tuple(EnchantType,int)] EnchantType:附魔类型,见枚举值文档;int:附魔等级。没有附魔则为空list
  • 示例

GetPlayerItem(posType, slotPos)

  • 描述

    获取玩家物品

  • 参数

    参数名 数据类型 说明
    posType ItemPosType GetMinecraftEnum().ItemPosType.*,玩家物品位置
    slotPos int 箱子槽位
  • 返回值

    数据类型 说明
    itemDict 物品信息字典,没有物品则返回None
  • 示例

  • 备注

    • 物品信息字典 itemDict

      关键字 数据类型 说明
      itemName str 物品的identifier,即"命名空间:物品名"
      showInHand bool 是否显示在手上,默认为true
      count int 数量
      auxValue int 物品附加值
      enchantData list 附魔数据
      customTips str 物品的自定义tips
      extraId str 物品自定义标识符。可以用于保存数据, 区分物品

SetInvItemExchange(pos1, pos2)

  • 描述

    交换玩家背包物品

  • 参数

    参数名 数据类型 说明
    pos1 int 物品位置
    pos2 int 物品位置
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SetInvItemNum(slotPos, num)

  • 描述

    设置玩家背包物品数目

  • 参数

    参数名 数据类型 说明
    slotPos int 物品栏槽位
    num int 物品数目
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SpawnItemToChestBlock(itemDict, playerId, slotPos, blockPos)

  • 描述

    添加物品到箱子

  • 参数

    参数名 数据类型 说明
    itemDict dict 物品字典
    playerId str 玩家id
    slotPos int 箱子槽位
    blockPos (int,int,int) 箱子位置
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 物品信息字典itemDict同SpawnItemToLevel中注释部分

SpawnItemToLevel(itemDict, dimensionId, pos)

  • 描述

    添加物品到level

  • 参数

    参数名 数据类型 说明
    itemDict dict 物品字典
    dimensionId int 设置dimension
    pos tuple(x,y,z) 出生位置
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 物品信息字典 itemDict

      关键字 数据类型 说明
      itemName str 物品的identifier。若需要设置为空则填"minecraft:air"
      count int 必须设置 数量
      auxValue int 必须设置 物品附加值
      showInHand bool 可选设置 是否显示在手上,默认为true
      enchantData list 可选设置 附魔数据
      customTips str 可选设置 物品的自定义tips
      extraId str 可选设置 物品自定义标识符。可以用于保存数据, 区分物品

SpawnItemToPlayerCarried(itemDict, playerId)

  • 描述

    添加物品到玩家右手

  • 参数

    参数名 数据类型 说明
    itemDict dict 物品字典
    playerId str 玩家id
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 物品信息字典itemDict同SpawnItemToLevel中注释部分

SpawnItemToPlayerInv(itemDict, playerId, slotPos)

  • 描述

    添加物品到玩家背包

  • 参数

    参数名 数据类型 说明
    itemDict dict 物品字典
    playerId str 玩家id
    slotPos int 背包槽位
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 物品信息字典itemDict同SpawnItemToLevel中注释部分

SpawnItemToPlayerOffHand(itemDict, playerId)

  • 描述

    添加物品到玩家左手

  • 参数

    参数名 数据类型 说明
    itemDict dict 物品字典
    playerId str 玩家id
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

  • 备注

    • 物品信息字典itemDict同SpawnItemToLevel中注释部分

recipe

GetRecipeResult(recipeId)

  • 描述

    根据配方id获取配方结果。仅支持合成配方

  • 返回值

    数据类型 说明
    list[{resultDict}] 设置结果
  • 示例

  • 备注

    • resultDict字典内容如下

      关键字 数据类型 说明
      itemName str 物品名称id
      auxValue int 物品附加值
      num int 物品数目

世界

chunkSource

DeleteAllArea()

  • 描述

    删除所有长加载区域

  • 参数

    参数名 数据类型 说明
    key str 长加载区域的名称
  • 返回值

    数据类型 说明
    int 删除的区域数目,错误时为None
  • 示例

DeleteArea(key)

  • 描述

    删除一个长加载区域

  • 参数

    参数名 数据类型 说明
    key str 长加载区域的名称
  • 返回值

    数据类型 说明
    bool 删除是否成功
  • 示例

GetAllAreaKeys()

  • 描述

    获取所有长加载区域名称列表

  • 返回值

    数据类型 说明
    List[str] 名称列表list
  • 示例

SetAddArea(key, dimensionId, minPos, maxPos)

  • 描述

    设置区块的长加载

  • 参数

    参数名 数据类型 说明
    key str 长加载区域的名称
    dimensionId int 区块所在的维度
    minPos tuple(int,int,int) 加载区域的最小坐标
    maxPos tuple(int,int,int) 加载区域的最da坐标
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

  • 备注

    • key必须唯一,若添加区域时key已存在将添加失败

      该方式创建的长加载区域不会tick,也不会加载存档的生物。并且可以使用api创建实体,但暂不支持block的设置及获取。但如果区域已被加载过,玩家远离时区域内的实体会一直保持加载。若需要区域被tick,请使用原版tickingarea指令,详见官方wiki

explosion

CreateExplosion(pos, radius, fire, breaks, sourceId, playerId)

  • 描述

    用于生成爆炸

  • 参数

    参数名 数据类型 说明
    pos tuple(float,float,float) 爆炸位置
    radius int 爆炸半径
    fire bool 是否带火
    breaks bool 是否破坏方块
    sourceId str 爆炸伤害源的实体id
    playerId str 爆炸创造的实体id
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

game

CanSee(fromId, targetId, viewRange, onlySolid, angleX, angleY)

  • 描述

    判断起始对象是否可看见目标对象,基于对象的Head位置判断

  • 参数

    参数名 数据类型 说明
    fromId str 起始对象ID
    targetId str 目标对象ID
    viewRange float 视野距离,默认值8.0
    onlySolid bool 只判断固体方块遮挡,默认True; False则液体方块也会遮挡
    angleX float 视野X轴角度,默认值180.0度
    angleY float 视野Y轴角度,默认值180.0度
  • 返回值

    数据类型 说明
    bool 是否可见
  • 示例

DisableVineBlockSpread(disable)

  • 描述

    设置是否禁用藤曼蔓延生长

  • 参数

    参数名 数据类型 说明
    disable bool true:禁用 false:非禁用
  • 返回值

  • 示例

GetEntitiesAround(entityId, radius, filters)

  • 描述

    获取区域内的entity列表

  • 参数

    参数名 数据类型 说明
    entityId str 某个entityId
    radius int 正方体区域半径
    filters dict 过滤设置字典
  • 返回值

    数据类型 说明
    List[str] 返回entityId的list
  • 示例

GetEntitiesInSquareArea(entityId, startPos, endPos)

  • 描述

    获取区域内的entity列表

  • 参数

    参数名 数据类型 说明
    entityId str 某个entityId
    startPos tuple(int,int,int) 初始位置
    endPos tuple(int,int,int) 结束位置
  • 返回值

    数据类型 说明
    List[str] 返回entityId的list
  • 示例

GetGameDiffculty()

  • 描述

    获取游戏难度

  • 返回值

    数据类型 说明
    int GetMinecraftEnum().GameDiffculty.*:Peaceful,Easy,Normal,Hard分别为0~3
  • 示例

GetGameRule()

  • 描述

    获取游戏规则

  • 返回值

    数据类型 说明
    gameRule 字典
  • 示例

     

    该接口在Apollo和联机大厅下不生效

  • 备注

    • 游戏规则字典 gameRule见代码注释

GetGameType()

  • 描述

    获取游戏类型

  • 返回值

    数据类型 说明
    int GetMinecraftEnum().GameType.*:Survival,Creative,Adventure,SurvivalViewer,CreativeViewer分别为0~4
  • 示例

GetLevelGravity()

  • 描述

    获取重力因子

  • 返回值

    数据类型 说明
    float 重力因子
  • 示例

GetPlayerGameType(playerId)

  • 描述

    获取指定玩家的游戏模式

  • 参数

    参数名 数据类型 说明
    playerId str 玩家id
  • 返回值

    数据类型 说明
    int GameType类型
  • 示例

IsLockDifficulty()

  • 描述

    获取当前世界的游戏难度是否被锁定

  • 返回值

    数据类型 说明
    bool isLock True为已锁定,False为未锁定
  • 示例

LockDifficulty(lock)

  • 描述

    锁定当前世界游戏难度(仅本次游戏有效),锁定后任何玩家在游戏内都无法通过指令或暂停菜单修改游戏难度

  • 参数

    参数名 数据类型 说明
    lock bool True:锁定 False:解锁
  • 返回值

    数据类型 说明
    bool result是否操作成功
  • 示例

SetDisableContainers(isDisable)

  • 描述

    设置是否屏蔽容器交互(不包括背包),不包括纯客户端逻辑控制的容器:纱布机,切石机,制图台等

  • 参数

    参数名 数据类型 说明
    isDisable bool 是否屏蔽容器交互
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetDisableDropItem(isDisable)

  • 描述

    设置禁止丢弃物品

  • 参数

    参数名 数据类型 说明
    isDisable bool 是否禁止丢弃物品
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetDisableHunger(isDisable)

  • 描述

    设置是否屏蔽饥饿度

  • 参数

    参数名 数据类型 说明
    isDisable bool 是否屏蔽饥饿度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetGameRulesInfo(gameRuleDict)

  • 描述

    设置游戏规则。所有参数均可选。

  • 参数

    参数名 数据类型 说明
    gameRuleDict dict 游戏规则字典
  • 返回值

  • 示例

    该接口在Apollo和联机大厅下不生效

  • 备注

SetHurtCD(cdTime)

  • 描述

    设置伤害CD

  • 参数

    参数名 数据类型 说明
    cdTime int 单位帧数
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetLevelGravity(data)

  • 描述

    设置重力因子

  • 参数

    参数名 数据类型 说明
    data float 重力因子
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetNotifyMsg(msg, color)

  • 描述

    设置消息通知

  • 参数

    参数名 数据类型 说明
    msg str 消息内容
    color serverApi.GenerateColor 颜色默认白色
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

feature

管理PlaceNeteaseStructureFeatureEvent事件在脚本层的监听

AddNeteaseFeatureWhiteList(structureName)

  • 描述

    添加structureName对PlaceNeteaseStructureFeatureEvent事件的脚本层监听

  • 参数

    参数名 数据类型 说明
    structureName str 结构名称
  • 返回值

    数据类型 说明
    bool 是否增加成功
  • 示例

ClearAllNeteaseFeatureWhiteList()

  • 描述

    清空所有已添加Netease Structure Feature对PlaceNeteaseStructureFeatureEvent事件的脚本层监听

  • 返回值

    数据类型 说明
    bool 是否清空成功
  • 示例

RemoveNeteaseFeatureWhiteList(structureName)

  • 描述

    移除structureName对PlaceNeteaseStructureFeatureEvent事件的脚本层监听

  • 参数

    参数名 数据类型 说明
    structureName str 结构名称
  • 返回值

    数据类型 说明
    bool 是否移除成功
  • 示例

time

GetTime()

  • 描述

    获取当前世界时间

  • 返回值

    数据类型 说明
    int 当前时间,帧数
  • 示例

SetTime(time)

  • 描述

    设置当前世界时间

  • 参数

    参数名 数据类型 说明
    time int 时间,单位帧数,游戏一天24000帧,可以通过设置时间来改变天亮和天黑以及其他
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

weather

IsRaining()

  • 描述

    获取是否下雨

  • 返回值

    数据类型 说明
    bool 是否下雨
  • 示例

IsThunder()

  • 描述

    获取是否打雷

  • 返回值

    数据类型 说明
    bool 是否打雷
  • 示例

SetRaining(level, time)

  • 描述

    设置是否下雨

  • 参数

    参数名 数据类型 说明
    level float 下雨强度
    time int 下雨时间单位为帧
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetThunder(level, time)

  • 描述

    设置是否打雷

  • 参数

    参数名 数据类型 说明
    level float 打雷强度
    time int 打雷时间单位为帧
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

模型

model

SetModel(modelName)

  • 描述

    设置骨骼模型

  • 参数

    参数名 数据类型 说明
    modelName str 模型名称,值为""时重置模型
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SetModelTexture(texture)

  • 描述

    设置骨骼模型贴图

  • 参数

    参数名 数据类型 说明
    texture str 模型纹理
  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

SetUsingModelSkin()

  • 描述

    设置骨骼模型使用平台皮肤

  • 返回值

    数据类型 说明
    bool 设置结果
  • 示例

scale

SetEntityScale(entityId, scale)

  • 描述

    设置实体的放缩比例大小,设置比例过大会导致游戏卡顿,建议控制在20倍以内

  • 参数

    参数名 数据类型 说明
    entityId str 要设置的实体
    scale float 比例因子
  • 返回值

    数据类型 说明
    int 成功返回1,失败返回-1
  • 示例

  • 备注

    • 目前此功能只支持设置生物的骨骼模型,游戏原生实体(包括手持物品)的暂不做支持与维护

 

客户端

音效

customAudio

用于播放自定义音效

Play(name, pos, volume, pitch)

  • 描述

    播放自定义音效

  • 参数

    参数名 数据类型 说明
    name str 音效名称
    pos (float,float,float) 播放位置
    volume float 音量大小,范围0-1
    pitch float 播放速度,范围0-256,1表示原速
  • 返回值

    数据类型 说明
    bool 播放是否成功
  • 示例

  • 备注

    • 与示例对应的sound_definitions.json配置:

    • 目前自定义音效支持fsb、wav、ogg格式

    • 详细的配置及使用请参考样例mod

    • sound_definitions.json位于resources\sounds目录下,对音效进行配置,name字段表示resources目录下音效资源的路径

systemAudio

用于播放原版音效

Play(soundId, pos, entityType, blockId, isBaby, isGlobal)

  • 描述

    播放原版音效

  • 参数

    参数名 数据类型 说明
    soundId SysSoundType GetMinecraftEnum().SysSoundType.*
    pos (float,float,float) 播放位置
    entityType EntityType GetMinecraftEnum().EntityType.*
    blockId BlockType GetMinecraftEnum().BlockType.*
    isBaby bool 是否幼儿
    isGlobal bool 是否全局
  • 返回值

    数据类型 说明
    bool 播放是否成功
  • 示例

  • 备注

    • 对于死亡音效,因为死亡跟block无关,因此blockId为-1,其他参数根据实际情况选择
    • 对于着地音效,与实体类型及幼儿属性无关,而着地到不同的block,音效是不一样的,根据实际情况设置blockId

文字面板

textBoard

用于更新文字面板。文字面板的创建见“创建文字面板”

SetSize(size)

  • 描述

    修改跳字大小

  • 参数

    参数名 数据类型 说明
    size float 字体大小, 如果为负数则字体会倒过来
  • 返回值

    数据类型 说明
    None 无返回值
  • 示例

SetTextColor(textColor)

  • 描述

    修改字体颜色

  • 参数

    参数名 数据类型 说明
    textColor (float,float,float,float) 颜色的RGBA值,范围0-1
  • 返回值

    数据类型 说明
    None 无返回值
  • 示例

UpdatePos(pos)

  • 描述

    更新文字面板的位置。创建文字面板后需要移动位置时使用

  • 参数

    参数名 数据类型 说明
    pos (float,float,float) 世界坐标
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

实体

actorCollidable

客户端用来控制玩家是否可碰撞

SetActorCollidable(isCollidable)

  • 描述

    设置实体是否可碰撞

  • 参数

    参数名 数据类型 说明
    isCollidable int 0:不可碰撞 1:可碰撞
  • 返回值

    数据类型 说明
    bool True表示设置成功
  • 示例

actorRender

客户端用来控制实体是否渲染的组件

GetNotRenderAtAll()

  • 描述

    获取实体是否不渲染

  • 返回值

    数据类型 说明
    bool True表示不渲染
  • 示例

SetNotRenderAtAll(notRender)

  • 描述

    设置实体是否不渲染

  • 参数

    参数名 数据类型 说明
    notRender bool True表示不渲染
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

auxValue

用于获取弓箭和药水实体的数据值

GetAuxValue()

  • 描述

    获取射出的弓箭或投掷出的药水的数据值

  • 返回值

    数据类型 说明
    int 具体数值见wiki的“箭”及“药水”页面
  • 示例

engineType

获取实体在游戏中的类型id,详见GetMinecraftEnum().EntityType

GetEngineType()

  • 描述

    获取实体类型

  • 返回值

    数据类型 说明
    EntityType GetMinecraftEnum().EntityType.*
  • 示例

GetEngineTypeStr()

  • 描述

    获取实体类型名称

  • 返回值

    数据类型 说明
    str 实体类型名称,如minecraft:husk
  • 示例

  • 备注

    • 微软自定义实体只能通过engineTypeStr获取类型

health

客户端用来设置血条颜色,血条背景相关的组件

SetColor(front, back)

  • 描述

    设置血条的颜色及背景色

  • 参数

    参数名 数据类型 说明
    front (float,float,float,float) 血条颜色的RGBA值,范围0-1
    back (float,float,float,float) 背景颜色的RGBA值,范围0-1
  • 返回值

  • 示例

  • 备注

    • 必须用game组件设置ShowHealthBar时才能显示血条!!

ShowHealth(show)

  • 描述

    设置某个entity是否显示血条,默认为显示

  • 参数

    参数名 数据类型 说明
    show bool 设置是否显示
  • 返回值

  • 示例

  • 备注

    • 必须用game组件设置ShowHealthBar时才能显示血条!!

modAttr

用于支持脚本层的属性管理

GetAttr(paramName, defaultValue)

  • 描述

    获取属性值

  • 参数

    参数名 数据类型 说明
    paramName str 属性名称,str的名称建议以mod命名为前缀,避免多个mod之间冲突
    defaultValue PyObject 属性默认值,属性不存在时返回该默认值,此时属性值依然未设置
  • 返回值

    数据类型 说明
    PyObject 返回属性值
  • 示例

  • 备注

    • defaultValue不传的时候默认为None

RegisterUpdateFunc(paramName, func)

  • 描述

    注册属性值变换时的回调函数,当属性变化时会调用该函数

  • 参数

    参数名 数据类型 说明
    paramName str 监听的属性名称
    func callable 监听的回调函数
  • 返回值

  • 示例

  • 备注

    • 回调函数需要接受一个参数,参数是dict,具体数据示例:{'oldValue': 0, 'newValue': 1, 'entityId': ’-433231231231‘}

SetAttr(paramName, paramValue)

  • 描述

    设置客户端属性值

  • 参数

    参数名 数据类型 说明
    paramName str 属性名称,str的名称建议以mod命名为前缀,避免多个mod之间冲突
    paramValue PyObject 属性值,支持python基础数据
  • 返回值

  • 示例

  • 备注

    • 注意:这里设置了只在本地有效,并不会同步到服务端和其他客户端

UnRegisterUpdateFunc(paramName, func)

  • 描述

    反注册属性值变换时的回调函数

  • 参数

    参数名 数据类型 说明
    paramName str 监听的属性名称
    func callable 监听的回调函数
  • 返回值

  • 示例

  • 备注

    • 需要传注册时的同一个函数作为参数

pos

客户端用来获取实体位置的组件

GetPos()

  • 描述

    获取实体位置

  • 返回值

    数据类型 说明
    (float,float,float) 实体的坐标
  • 示例

  • 备注

    • 对于非玩家,获取到的是脚底部位的位置;对于玩家,获取到的是比脚底高1.62的位置(除了睡觉时)

rot

客户端用来获取实体角度的组件,也可以用来设置本地玩家自己的旋转角度

GetRot()

  • 描述

    获取实体角度

  • 返回值

    数据类型 说明
    (float,float) 俯仰角度及绕竖直方向的角度,单位是角度
  • 示例

SetRot(rot)

  • 描述

    设置实体的角度

  • 参数

    参数名 数据类型 说明
    rot (float,float) 俯仰角度及绕竖直方向的角度,单位是角度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

  • 备注

    • 只能设置localplayer,即本地玩家自己

方块

blockInfo

GetBlock(pos)

  • 描述

    获取某一位置的block

  • 参数

    参数名 数据类型 说明
    pos (float,float,float) 方块位置
  • 返回值

    数据类型 说明
    tuple(str,int) 参数1:方块的名称,参数2:方块的aux值
  • 示例

  • 备注

    • 已经加载的地形才设置、获取方块信息

控制

actorMotion

玩家的移动方向和大小

GetInputVector()

  • 描述

    获取方向键(移动轮盘)的输入

  • 返回值

    数据类型 说明
    (float,float) 返回一个单位向量,向量第一项为向左的大小,第二项为向前的大小
  • 示例

SetMotion(motion)

  • 描述

    设置瞬时的移动方向向量,主要用于本地玩家

  • 参数

    参数名 数据类型 说明
    motion (float,float,float) 世界坐标系下的向量,该方向为世界坐标系下的向量,以x,z,y三个轴的正方向为正值,可以通过当前玩家的rot组件判断目前玩家面向的方向,可在开发模式下打开F3观察数值变化。
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

mouseHook

鼠标钩子,主要用来获取玩家点击鼠标的事件,进而修改点击鼠标之后的逻辑。

GetHook()

  • 描述

    获取当前是否开启了鼠标钩子

  • 返回值

    数据类型 说明
    bool 是否开启
  • 示例

SetHook(hook)

  • 描述

    设置鼠标钩子。开启之后玩家点击鼠标会触发“OnClickInGame”事件

  • 参数

    参数名 数据类型 说明
    hook bool True为开启
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

operation

设置是否响应本地玩家的操作

SetCanAll(all)

  • 描述

    一次性设置除SetMoveLock之外的所有属性

  • 参数

    参数名 数据类型 说明
    all bool True为全部响应
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

  • 备注

    • 要在其他属性设置之前设置,不然在all之前设置的会被覆盖掉

SetCanAttack(attack)

  • 描述

    设置是否响应攻击

  • 参数

    参数名 数据类型 说明
    attack bool True为可攻击
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetCanChat(chat)

  • 描述

    设置是否响应聊天按钮

  • 参数

    参数名 数据类型 说明
    chat bool True为可打开聊天页面
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetCanDrag(drag)

  • 描述

    设置是否响应屏幕拖动

  • 参数

    参数名 数据类型 说明
    drag bool True为可拖动屏幕
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetCanInair(inair)

  • 描述

    设置是否响应上升下降按钮(飞在空中时右下角的三个按钮)

  • 参数

    参数名 数据类型 说明
    inair bool True为可点击
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetCanJump(jump)

  • 描述

    设置是否响应跳跃(以及在水中浮起)

  • 参数

    参数名 数据类型 说明
    jump bool True为可跳跃
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetCanMove(move)

  • 描述

    设置是否响应移动

  • 参数

    参数名 数据类型 说明
    move bool True为可移动
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetCanOpenInv(open)

  • 描述

    设置是否响应打开背包按钮

  • 参数

    参数名 数据类型 说明
    open bool True为可打开背包
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetCanPause(pause)

  • 描述

    设置是否响应暂停按钮

  • 参数

    参数名 数据类型 说明
    pause bool True为可打开暂停页面
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetCanPerspective(persp)

  • 描述

    设置是否响应切换视角

  • 参数

    参数名 数据类型 说明
    persp bool True为可切换
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetCanScreenShot(shot)

  • 描述

    设置是否响应截图按钮

  • 参数

    参数名 数据类型 说明
    shot bool True为可截图
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetCanWalkMode(walkmode)

  • 描述

    设置是否响应切换行走模式

  • 参数

    参数名 数据类型 说明
    walkmode bool True为可切换
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetMoveLock(movelock)

  • 描述

    设置是否锁住移动,与SetCanMove的区别:设置了SetCanMove(False)之后actorMotion组件的SetMotion会失效,而用moveLock为True则不会

  • 参数

    参数名 数据类型 说明
    movelock bool True为锁住
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

playerView

视角模式相关

GetPerspective()

  • 描述

    获取当前的视角模式

  • 返回值

    数据类型 说明
    int 0:第一人称视角;1:第三人称视角;2:前视第三人称视角
  • 示例

SetPerspective(persp)

  • 描述

    设置视角模式

  • 参数

    参数名 数据类型 说明
    persp int 0:第一人称视角;1:第三人称视角;2:前视第三人称视角
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

玩家

camera

摄相机控制

DepartCamera()

  • 描述

    分离玩家与摄像机

  • 返回值

  • 示例

  • 备注

    • 分离之后,可以看到玩家四周

GetCameraOffset()

  • 描述

    获取摄像机偏移量

  • 返回值

    数据类型 说明
    tuple(float,float,float) 偏移量
  • 示例

GetCameraPitchLimit()

  • 描述

    获取摄像机上下角度限制值

  • 返回值

    数据类型 说明
    tuple(float,float) 上下角度限制值
  • 示例

GetCameraRot()

  • 描述

    获取相机转向

  • 返回值

    数据类型 说明
    tuple(float,float) 转向
  • 示例

GetChosen()

  • 描述

    获取屏幕点击位置的实体或方块信息,通常与GetEntityByCoordEvent配合使用

  • 返回值

    数据类型 说明
    dict 选中目标的数据,详见PickFacing接口的备注
  • 示例

  • 备注

    • 目前只有在第一人称视角才能准确获取

GetChosenEntity()

  • 描述

    获取屏幕点击位置的实体id,通常与GetEntityByCoordEvent配合使用

  • 返回值

    数据类型 说明
    str 实体id
  • 示例

  • 备注

    • 目前只有在第一人称视角才能准确获取

GetForward()

  • 描述

    返回相机向前的方向

  • 返回值

    数据类型 说明
    tuple(float,float,float) 向前的方向
  • 示例

GetFov()

  • 描述

    获取视野大小

  • 返回值

    数据类型 说明
    float 即视频设置中的视野,单位为角度
  • 示例

GetFpHeight()

  • 描述

    获取本地玩家当前状态下,第一人称视角时的摄像机高度偏移量。游泳时,滑翔时以及普通状态下会有所不同

  • 返回值

    数据类型 说明
    float 高度偏移量
  • 示例

GetPosition()

  • 描述

    返回相机中心

  • 返回值

    数据类型 说明
    tuple(float,float,float) 相机中心位置
  • 示例

IsModCameraLockPitch()

  • 描述

    是否锁定摄像机上下角度

  • 返回值

    数据类型 说明
    bool 是否锁定
  • 示例

IsModCameraLockYaw()

  • 描述

    是否锁定摄像机左右角度

  • 返回值

    数据类型 说明
    bool 是否锁定
  • 示例

LockCamera(lockPos, lockRot)

  • 描述

    锁定摄像机

  • 参数

    参数名 数据类型 说明
    lockPos (float,float,float) 世界坐标
    lockRot (float,float) 摄像机的角度(俯仰角及偏航角)
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

  • 备注

    • 锁定摄像机时只是锁定画面视角,玩家仍然可以移动

LockModCameraPitch(enable)

  • 描述

    锁定摄像机上下角度(第三人称下生效,锁定后不能上下调整视角)

  • 参数

    参数名 数据类型 说明
    enable int 1:锁定 0:解锁
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

LockModCameraYaw(enable)

  • 描述

    锁定摄像机左右角度(第三人称下生效,锁定后不能通过鼠标左右调整视角)

  • 参数

    参数名 数据类型 说明
    enable int 1:锁定 0:解锁
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

PickFacing()

  • 描述

    获取准星选中的实体或者方块

  • 返回值

    数据类型 说明
    dict 选中目标的数据,详见备注
  • 示例

  • 备注

    • 选中目标为实体时,返回值为:

    • 选中目标为方块时,返回值为:

    • 没有选中目标时,返回值为:

ResetCameraBindActorId()

  • 描述

    重置将摄像机绑定到目标玩家身上

  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

SetCameraBindActorId(targetId)

  • 描述

    将摄像机绑定到目标玩家身上(需要先DepartCamera,调用者与targetId必须在同一个dimension,同时需要在加载范围之内)

  • 参数

    参数名 数据类型 说明
    targetId str 目标玩家id
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

SetCameraOffset(offset)

  • 描述

    设置摄像机偏移量

  • 参数

    参数名 数据类型 说明
    offset tuple(float,float,float) 偏移量
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

SetCameraPitchLimit(limit)

  • 描述

    设置摄像机上下角度限制值,默认是(-90,90)

  • 参数

    参数名 数据类型 说明
    limit tuple(float,float) 上下角度限制值
  • 返回值

    数据类型 说明
    bool 是否成功
  • 示例

SetCameraPos(pos)

  • 描述

    设置相机中心的位置

  • 参数

    参数名 数据类型 说明
    pos tuple(float,float,float) 位置
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

SetCameraRot(rot)

  • 描述

    设定相机转向

  • 参数

    参数名 数据类型 说明
    rot tuple(float,float) 转向
  • 返回值

    数据类型 说明
    bool 是否设置成功
  • 示例

SetFov(fov)

  • 描述

    设置视野大小

  • 参数

    参数名 数据类型 说明
    fov float 单位为角度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

UnDepartCamera()

  • 描述

    绑定玩家与摄像机

  • 返回值

  • 示例

  • 备注

    • 绑定之后,只能看到玩家背部

UnLockCamera()

  • 描述

    解除摄像机锁定

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

序列帧

frameAniControl

用于设置序列帧的播放控制相关属性

Play()

  • 描述

    播放序列帧

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetDeepTest(deepTest)

  • 描述

    设置序列帧是否透视,默认为否

  • 参数

    参数名 数据类型 说明
    deepTest bool False表示透视,则被物体/方块阻挡时仍然能看到序列帧
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetFaceCamera(face)

  • 描述

    设置序列帧是否始终朝向摄像机,默认为是

  • 参数

    参数名 数据类型 说明
    face bool True表示朝摄像机
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetLoop(loop)

  • 描述

    设置序列帧是否循环播放,默认为否

  • 参数

    参数名 数据类型 说明
    loop bool True表示循环播放
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

Stop()

  • 描述

    停止序列帧(不是暂停)

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

frameAniEntityBind

用于将序列帧绑定到实体

Bind(bindEntityId, offset, rot)

  • 描述

    绑定entity

  • 参数

    参数名 数据类型 说明
    bindEntityId str 绑定的entity的ID
    offset (float,float,float) 绑定的偏移量
    rot (float,float,float) 绑定的旋转角度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

frameAniSkeletonBind

用于将序列帧绑定到骨骼模型

Bind(modelId, boneName, offset, rot)

  • 描述

    绑定骨骼模型

  • 参数

    参数名 数据类型 说明
    modelId int 绑定的骨骼模型的ID(见model组件的GetModelId)
    boneName str 绑定具体骨骼的名称
    offset (float,float,float) 绑定的偏移量
    rot (float,float,float) 绑定的旋转角度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

frameAniTrans

用于设置序列帧的transform属性

SetPos(pos)

  • 描述

    设置序列帧的位置

  • 参数

    参数名 数据类型 说明
    pos (float,float,float) 世界坐标
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetRot(rot)

  • 描述

    设置序列帧的旋转

  • 参数

    参数名 数据类型 说明
    rot (float,float,float) 按顺序绕局部坐标系的+x,-y,+z轴旋转的角度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

  • 备注

SetScale(scale)

  • 描述

    设置序列帧的缩放

  • 参数

    参数名 数据类型 说明
    scale (float,float,float) 第一个参数为贴图横向上的缩放,第二个参数为纵向上的缩放
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

  • 备注

物品

item

获取玩家左右手和背包的物品信息

GetCarriedItem()

  • 描述

    获取右手物品的信息

  • 返回值

    数据类型 说明
    item字典 item字典的具体结构见“使用说明”,没有物品则返回None
  • 示例

GetOffhandItem()

  • 描述

    获取左手物品的信息

  • 返回值

    数据类型 说明
    item字典 item字典的具体结构见“使用说明”,没有物品则返回None
  • 示例

GetSlotId()

  • 描述

    获取当前手持的快捷栏的槽id

  • 返回值

    数据类型 说明
    int 0到8
  • 示例

粒子

particleControl

用于控制粒子播放相关

Play()

  • 描述

    播放粒子特效

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetRelative(relative)

  • 描述

    当粒子绑定了entity或骨骼模型时,发射出的粒子使用entity坐标系还是世界坐标系。与mcstudio特效编辑器中粒子的“相对挂点运动”选项功能相同。

  • 参数

    参数名 数据类型 说明
    relative bool True表示相对坐标系,False表示世界坐标系
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

Stop()

  • 描述

    停止粒子播放

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

particleEntityBind

用于将粒子绑定到实体

Bind(bindEntityId, offset, rot)

  • 描述

    绑定entity

  • 参数

    参数名 数据类型 说明
    bindEntityId str 绑定的entity的ID
    offset (float,float,float) 绑定的偏移量,相对绑定entity脚下中心
    rot (float,float,float) 绑定的旋转角度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

particleSkeletonBind

用于将粒子绑定到骨骼模型

Bind(modelId, boneName, offset, rot)

  • 描述

    绑定骨骼模型

  • 参数

    参数名 数据类型 说明
    modelId int 绑定的骨骼模型的ID(见model组件的GetModelId)
    boneName str 绑定具体骨骼的名称
    offset (float,float,float) 绑定的偏移量
    rot (float,float,float) 绑定的旋转角度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

particleTrans

用于设置粒子的transform属性

SetPos(pos)

  • 描述

    设置粒子的位置

  • 参数

    参数名 数据类型 说明
    pos (float,float,float) 世界坐标
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetRot(rot)

  • 描述

    设置粒子的旋转

  • 参数

    参数名 数据类型 说明
    pos (float,float,float) 按顺序绕局部坐标系的+x,+y,+z轴旋转的角度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

世界

game

游戏逻辑相关的组件

AddPickBlacklist(entityId)

  • 描述

    添加使用camera组件选取实体时的黑名单,即该实体不会被选取到

  • 参数

    参数名 数据类型 说明
    entityId str 实体id
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

CheckNameValid(name)

  • 描述

    检查昵称是否合法,即不包含敏感词

  • 参数

    参数名 数据类型 说明
    name str 昵称
  • 返回值

    数据类型 说明
    bool true:昵称合法 false:昵称非法
  • 示例

CheckWordsValid(words)

  • 描述

    检查语句是否合法,即不包含敏感词

  • 参数

    参数名 数据类型 说明
    words str 语句
  • 返回值

    数据类型 说明
    bool true:语句合法 false:语句非法
  • 示例

ClearPickBlacklist()

  • 描述

    清除使用camera组件选取实体的黑名单

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

GetEntityInArea(entityId, pos_a, pos_b, exceptEntity)

  • 描述

    返回区域内的实体

  • 参数

    参数名 数据类型 说明
    entityId str 实体Id
    pos_a (int,int,int) 起点
    pos_b (int,int,int) 终点,终点应大于起点
    exceptEntity bool 返回结果中是否除去entityId, 默认为False
  • 返回值

    数据类型 说明
    list/None 成功返回列表,失败返回None
  • 示例

GetScreenSize()

  • 描述

    获取游戏分辨率

  • 返回值

    数据类型 说明
    (float,float) 宽高(像素)
  • 示例

HasEntity(entityId)

  • 描述

    判断 entity 是否存在

  • 参数

    参数名 数据类型 说明
    entityId str 实体id
  • 返回值

    数据类型 说明
    int 0表示不存在,1表示存在
  • 示例

SetNameDeeptest(deeptest)

  • 描述

    设置名字是否透视

  • 参数

    参数名 数据类型 说明
    deeptest bool True为不透视。默认情况下为透视
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetRenderLocalPlayer(render)

  • 描述

    设置本地玩家是否渲染

  • 参数

    参数名 数据类型 说明
    render bool True为渲染
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

ShowHealthBar(show)

  • 描述

    设置是否显示血条

  • 参数

    参数名 数据类型 说明
    show bool True为显示。开启后可用health组件单独设置某个实体的血条颜色及是否显示
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

界面

fog

雾效渲染相关的组件,支持设置雾效颜色与范围

ResetFogColor()

  • 描述

    重置雾效颜色

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

ResetFogLength()

  • 描述

    重置雾效范围

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetFogColor(color)

  • 描述

    设置雾效颜色

  • 参数

    参数名 数据类型 说明
    color (float,float,float,float) 颜色RGBA,范围0到1之间,a值主要用于水下效果
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetFogLength(start, end)

  • 描述

    设置雾效范围

  • 参数

    参数名 数据类型 说明
    start float 雾效起始距离
    end float 雾效终点范围
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

name

玩家名字相关

SetShowName(show)

  • 描述

    设置名字是否显示

  • 参数

    参数名 数据类型 说明
    show bool True为显示
  • 返回值

  • 示例

skyRender

天空渲染相关的组件。注意:末地、下界不支持此功能

ResetAmbientBrightness()

  • 描述

    重置环境光亮度

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

ResetMoonRot()

  • 描述

    重置月亮角度

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

ResetSkyColor()

  • 描述

    重置天空颜色

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

ResetStarBrightness()

  • 描述

    重置星星亮度

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

ResetSunRot()

  • 描述

    重置太阳角度

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetAmbientBrightness(brightness)

  • 描述

    设置环境光亮度,影响天空亮度,不影响实体与方块光照

  • 参数

    参数名 数据类型 说明
    brightness float 范围0到1之间
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetMoonRot(rot)

  • 描述

    设置月亮所在角度

  • 参数

    参数名 数据类型 说明
    rot (float,float,float) 第一个float表示日升日落,第三个float表示南北偏移。单位为角度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetSkyColor(color)

  • 描述

    设置天空颜色

  • 参数

    参数名 数据类型 说明
    color (float,float,float,float) 颜色RGBA,0到1之间,目前a值暂时没用
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetStarBrightness(brightness)

  • 描述

    设置星星亮度,白天也可以显示星星

  • 参数

    参数名 数据类型 说明
    brightness float 范围0到1之间
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetSunRot(rot)

  • 描述

    设置太阳所在角度

  • 参数

    参数名 数据类型 说明
    rot (float,float,float) 第一个float表示日升日落,第三个float表示南北偏移。单位为角度
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SkyTextures()

  • 描述

    修改太阳、月亮、云层分布、天空盒的贴图。使用addon配置,非python接口。

  • 返回值

  • 备注

    • 游戏提供了重载贴图的方式来修改太阳、月亮、云层分布、天空盒的贴图。末地和下界没有太阳月亮和云层,另外末地的天空是用一张贴图end_sky.png而不是天空盒贴图,end_sky.png要结合雾效颜色使用。下界暂不支持此功能。具体路径为:

      贴图 路径
      太阳贴图 modResource目录/textures/environment/{dimName}_sun.png
      月亮贴图 modResource目录/textures/environment/{dimName}_moon_phases.png
      云层分布贴图 modResource目录/textures/environment/{dimName}_clouds.png
      天空盒贴图 modResource目录/textures/environment/{dimName}_cubemap/cubemap_0.png

其中:天空盒贴图需要放6张图,即最后需要包含cubemap_0.pngcubemap_5.png,而{dimName}表示dimension的名称,各个dimension名称如下:

示例:

模型

model

用于设置实体的骨骼模型及动画

Bind(boneName, weapon)

  • 描述

    实体替换骨骼模型后,再往上其他挂接骨骼模型

  • 参数

    参数名 数据类型 说明
    boneName str 挂接的骨骼名称
    weapon str 要挂接的骨骼模型名称
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

CreateFreeModel(modelName)

  • 描述

    创建自由的模型(无需绑定Entity)

  • 参数

    参数名 数据类型 说明
    modelName str 模型名称
  • 返回值

    数据类型 说明
    modelId 创建成功返回 modelId,创建失败返回 0
  • 示例

GetBoneWorldPos(boneName)

  • 描述

    获取骨骼的坐标

  • 参数

    参数名 数据类型 说明
    boneName str 骨骼名称
  • 返回值

    数据类型 说明
    (int,int,int) 位置坐标
  • 示例

GetEntityBoneWorldPos(entityId, boneName)

  • 描述

    获取换了骨骼模型的实体的骨骼坐标

  • 参数

    参数名 数据类型 说明
    entityId str 实体id
    boneName str 骨骼名称
  • 返回值

    数据类型 说明
    (int,int,int) 位置坐标
  • 示例

GetModelId()

  • 描述

    获取骨骼模型的Id,主要用于特效绑定骨骼模型

  • 返回值

    数据类型 说明
    int 当前骨骼模型实例的id
  • 示例

GetPlayingAnim()

  • 描述

    获取当前播放的骨骼动画名称

  • 返回值

    数据类型 说明
    str 骨骼动画名称
  • 示例

HideModel(modelId)

  • 描述

    隐藏纯模型

  • 参数

    参数名 数据类型 说明
    modelId int 要隐藏的modelId
  • 返回值

    数据类型 说明
    None 无返回值
  • 示例

ModelPlayAni(modelId, aniName, isLoop)

  • 描述

    纯骨骼播放动作

  • 参数

    参数名 数据类型 说明
    modelId int 要设置的modelId
    aniName str 要设置的动画名称
    isLoop bool 是否循环播放,默认为 False
  • 返回值

  • 示例

PlayAnim(aniName, isLoop)

  • 描述

    播放骨骼动画

  • 参数

    参数名 数据类型 说明
    aniName str 动画名称
    isLoop bool 是否循环播放
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

PlayBodyAnim(bodyAniName, bodyIsLoop)

  • 描述

    上下半身分离时,对上半身播放动画

  • 参数

    参数名 数据类型 说明
    bodyAniName str 骨骼动画名称
    bodyIsLoop bool 是否循环播放
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

  • 备注

    • 骨骼模型需要有一根名为“up”的骨骼,并且上半身的其他骨骼都以up为父骨骼

PlayLegAnim(legAniName, legIsLoop)

  • 描述

    上下半身分离时,对下半身播放动画

  • 参数

    参数名 数据类型 说明
    legAniName str 骨骼动画名称
    legIsLoop bool 是否循环播放
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

  • 备注

    • 骨骼模型需要有一根名为“down”的骨骼,并且下半身的其他骨骼都以down为父骨骼

RemoveFreeModel(modelId)

  • 描述

    移除自由模型

  • 参数

    参数名 数据类型 说明
    modelId int 要移除的modelId
  • 返回值

    数据类型 说明
    bool 是否成功移除
  • 示例

ResetModel()

  • 描述

    恢复实体为原版模型

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetAnimSpeed(aniName, speed)

  • 描述

    设置某个骨骼动画的播放速度

  • 参数

    参数名 数据类型 说明
    aniName str 骨骼动画名称
    speed float 速度倍率
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

SetFreeModelBoundingBox(modelId, min, max)

  • 描述

    设置模型包围盒

  • 参数

    参数名 数据类型 说明
    modelId int 要设置的modelId
    min (float,float,float) 包围盒最小点
    max (float,float,float) 包围盒最大点
  • 返回值

    数据类型 说明
    bool 成功返回True,失败返回False
  • 示例

  • 备注

    • min的元素一定要比对应的max的元素小。
    • 模型包围盒用于判断渲染剔除:判断一个模型要不要渲染,要看它在不在视野范围内,也就是看游戏摄像机的视锥体(摄像机拍到的范围)和这个包围盒有没有交集。有则说明在视野范围内,反之则不在视野范围内。进而可以剔除掉该模型,不进行渲染。

SetFreeModelPos(modelId, x, y, z)

  • 描述

    设置自由模型的位置

  • 参数

    参数名 数据类型 说明
    modelId int 要设置的modelId
    x float 要设置的位置X轴参数
    y float 要设置的位置Y轴参数
    z float 要设置的位置Z轴参数
  • 返回值

    数据类型 说明
    bool 是否成功设置
  • 示例

SetFreeModelRot(modelId, x, y, z)

  • 描述

    设置自由模型的方向

  • 参数

    参数名 数据类型 说明
    modelId int 要设置的modelId
    x float 沿X方向的旋转参数
    y float 沿Y方向的旋转参数
    z float 沿Z方向的旋转参数
  • 返回值

    数据类型 说明
    bool 是否成功设置
  • 示例

SetFreeModelScale(modelId, x, y, z)

  • 描述

    设置自由模型的大小

  • 参数

    参数名 数据类型 说明
    modelId int 要设置的modelId
    x float 沿X方向的比例因子
    y float 沿Y方向的比例因子
    z float 沿Z方向的比例因子
  • 返回值

    数据类型 说明
    bool 是否成功设置
  • 示例

SetLegacyBindRot(enable)

  • 描述

    用于修复特效挂接到骨骼时的方向

  • 参数

    参数名 数据类型 说明
    enable bool 设置为False时,可以使特效与骨骼方向一致
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

  • 备注

    • 在挂接特效前调用即可

SetModel(modelName)

  • 描述

    替换实体的骨骼模型

  • 参数

    参数名 数据类型 说明
    modelName str 骨骼模型的名称
  • 返回值

    数据类型 说明
    int 替换的骨骼模型实例的id。失败返回-1
  • 示例

  • 备注

    • 要恢复原版模型请使用ResetModel接口
    • 使用客户端组件更换模型不会同步及存盘,仅是纯客户端表现,如需要同步及存盘,请使用服务器的model组件

SetSkin(skin)

  • 描述

    更换原版自定义皮肤

  • 参数

    参数名 数据类型 说明
    skin str 贴图路径,以textures\models为当前路径的相对路径
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

  • 备注

    • 会覆盖原有皮肤(包括4d皮肤)。但会被骨骼模型覆盖

SetTexture(texture)

  • 描述

    替换骨骼模型的贴图

  • 参数

    参数名 数据类型 说明
    texture str 贴图路径,以textures\models为当前路径的相对路径
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

ShowModel(modelId)

  • 描述

    显示纯模型

  • 参数

    参数名 数据类型 说明
    modelId int 要显示的modelId
  • 返回值

    数据类型 说明
    None 无返回值
  • 示例

StopBodyAnim()

  • 描述

    停止上半身动画

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

StopLegAnim()

  • 描述

    停止下半身动画

  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

UnBind(boneName)

  • 描述

    取消某个骨骼上挂接的所有骨骼模型

  • 参数

    参数名 数据类型 说明
    boneName str 骨骼名称
  • 返回值

    数据类型 说明
    bool 设置是否成功
  • 示例

 

客户端表现

注意,以下特效的创建仅在客户端有效,如果想要多人同时看到某个特效,需要服务端通过事件系统发送消息到对应的客户端。

文字面板

创建文字面板

  • 描述

    用于创建文字面板

  • 参数

    参数名 数据类型 说明
    text str 要显示的文本内容
    ownerId str 绑定的实体id(只是生命周期绑定,暂不支持位置绑定)
    pos tuple (float,float,float) 文字面板的位置,世界坐标
    textColor (float,float,float,float) 文字的颜色RGBA值,范围0-1
    tagColor (float,float,float,float) 面板的背景颜色颜色RGBA值,范围0-1
    size float 可选,文字大小。默认值1.0
    depthTest bool 可选,设置文字面板是否会被实体或方块等遮挡,True表示会被遮挡,False表示不会被遮挡。默认值True
  • 返回值

    数据类型 说明
    int或者None 成功创建返回大于0的fontEntityId,失败返回None
  • 示例

  • 备注

    • 创建文字面板后,可以用textBoard组件更新位置

特效

创建粒子特效

  • 描述

    用于创建粒子特效

  • 参数

    参数名 数据类型 说明
    path str 特效资源路径,需要加上后缀名(一般是json)
    pos tuple (float,float,float)创建位置坐标
  • 返回值

    数据类型 说明
    int或None particleEntityId或者None
  • 示例

  • 备注

    • 创建粒子后,可以用返回的particleEntityId创建客户端粒子分类中的相关组件,设置所需属性,以实现各种表现效果。
    • 粒子创建之后需要调用particleControl组件的Play函数才会播放

创建模型特效

  • 描述

    指用编辑器保存资源包中models/effect/xxx_effect.json生成编辑好的所有挂点的所有特效。生成的特效会自动进行挂接及播放,编辑器中设为不可见的特效也会进行播放。并且使用这种方式创建的特效,开发者不用维护entity进出视野导致的挂接特效被移除,引擎会在entity每次进入视野时自动创建所有特效。

  • 参数

    参数名 数据类型 说明
    path str 特效配置路径,需要包含json后缀名
    bindEntity str 绑定实体的Id
    aniName str 选择使用哪个模型动作的特效
  • 返回值

    数据类型 说明
    int或None effectEntityId或者None
  • 示例

  • 备注

    • 创建特效前需要将entity的骨骼模型替换为编辑器中的一致(或者其他骨骼相同的模型),否则将挂接失败,替换模型见服务端和客户端的model组件。
    • 暂不支持挂接原版史蒂夫的特效。

创建特效编辑器编辑的序列帧特效

  • 描述

    指使用资源包中effect/xxx.json,按照编辑器中编辑好的参数创建序列帧。支持环状序列帧

  • 参数

    参数名 数据类型 说明
    path str 特效配置路径,一般为"effect/xxx.json","xxx"为编辑器创建序列帧时填写的名称
    pos tuple (float,float,float)创建位置,可选,没传则可以创建完用frameAniTrans组件设置,一般需要设置播放的位置
    rot tuple (float,float,float)角度,可选,没传则可以创建完用frameAniTrans组件设置
    scale float 缩放系数,可选,没传则可以创建完用frameAniTrans组件设置
  • 返回值

    数据类型 说明
    int或None frameEntityId或者None
  • 示例

  • 备注

    • 创建序列帧后,可以用返回的frameEntityId创建序列帧分类中的相关组件,设置所需属性,以实现各种表现效果
    • 需要注意,序列帧创建之后需要调用frameAniControl组件的play函数才会播放
    • 根据editor配置生成序列帧后还需要设置位置或绑定,以及进行播放。

创建序列帧特效

  • 描述

    用于创建序列帧特效

  • 参数

    参数名 数据类型 说明
    path str 特效资源路径,不用后缀名
    pos tuple (float,float,float)创建位置,可选,没传则可以创建完用frameAniTrans组件设置
    rot tuple (float,float,float)角度,可选,没传则可以创建完用frameAniTrans组件设置
    scale float 缩放系数,可选,没传则可以创建完用frameAniTrans组件设置
  • 返回值

    数据类型 说明
    int或None frameEntityId或者None
  • 示例

  • 备注

    • 创建序列帧后,可以用返回的frameEntityId创建序列帧分类中的相关组件,设置所需属性,以实现各种表现效果
    • 需要注意,序列帧创建之后需要调用frameAniControl组件的play函数才会播放

 

服务端实体创建

引擎实体的创建在服务端处理,并且会自动同步给所有客户端。

生成实体

创建抛射物实体

  • 描述

    用于创建抛射物类型的实体

  • 参数

    参数名 数据类型 说明
    shooterId str 发射者entityId
    engineType MinecraftEnum.EntityType 弹射物类型
    pos tuple(float,float,float) 生成坐标
    direction tuple(float,float,float) 弹射物飞行方向
    power float 弹射物飞行速度
    gravity float 弹射物所受重力
  • 返回值

    数据类型 说明
    str或None 实体Id或者None
  • 示例

  • 备注

    • engineType建议都用arrow。
    • 同样,在未加载的chunk中将创建失败。

创建生物实体

  • 描述

    用于创建生物类型的实体

  • 参数

    参数名 数据类型 说明
    engineType MinecraftEnum.EntityType 生物类型
    pos tuple(float,float,float) 生成坐标
    rot tuple(float,float) 生物面向
    dimensionId int 生成的维度,默认值为0(0为主世界,1为地狱,2为末地)
    isNpc bool 是否为npc,默认值为False。npc不会移动、转向、存盘。
  • 返回值

    数据类型 说明
    str或None 实体Id或者None
  • 示例

  • 备注

    • 设置未加载的chunk的坐标会创建失败。

创建物品实体

  • 描述

    用于创建物品实体,具体参见物品组件

  • 参数

    参数名 数据类型 说明
    pos tuple(float,float,float) 生成坐标
    itemId GetMinecraftEnum().ItemType 物品实体类型
    count int 物品的数量
  • 返回值

    数据类型 说明
    str或None 实体Id或者None
  • 示例

创建字符串定义的生物实体

  • 描述

    利用字符串创建引擎实体,主要用于微软自定义物体

  • 参数

    参数名 数据类型 说明
    engineTypeStr str 例如'minecraft:husk'
    pos tuple(float,float,float) 生成坐标
    rot tuple(float,float) 生物面向
    dimensionId int 生成的维度,默认值为0(0为主世界,1为地狱,2为末地)
    isNpc bool 是否为npc,默认值为False。npc不会移动、转向、存盘。
  • 返回值

    数据类型 说明
    str或None 实体Id或者None
  • 示例

  • 备注

    • 设置未加载的chunk的坐标会创建失败。