# 实体管理

# CreateEngineEntityByNBT

服务端

method in mod.server.system.serverSystem.ServerSystem

  • 描述

    根据nbt数据创建实体

  • 参数

    参数名
    数据类型
    说明
    nbtDict dict 实体nbt数据,可以通过EntityDefinitionsCompServer.GetEntityNBTTags获取
    pos tuple(float,float,float)或None 生成坐标,如果为空,则读取nbt中的Pos
    rot tuple(float,float)或None 生成旋转,如果为空,则读取nbt中的Rotation
    dimensionId int 生成维度,默认为0
    isNpc bool 是否为npc,默认值为False。npc不会移动、转向、存盘。
    isGlobal None或bool 是否创建为全局实体,默认为None。None表示沿用nbt中是否为全局实体。设置为True或False表示覆盖nbt中的属性。全局实体不会因为玩家视野、加载范围限制而被卸载,行为与tick会一直跑,但不代表会一直存在,依然会受清除 (opens new window)等原生逻辑影响,比如如果对有minecraft:despawn组件的生物创建全局实体,则还需要设置SetPersistent,否则离远后实体仍然会消失。全局实体会影响游戏性能,建议整个存档内同时存在的数量不超过10个。
  • 返回值

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

    • 无法创建玩家实体,因为玩家是一个特殊的实体
    • 如果要直接通过nbtDict["Rotation"]修改旋转,需要注意nbt中y分量在第一位,x分量在第二位
  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateEntityDefinitions(entityId)
nbt = comp.GetEntityNBTTags()
newEntityId = self.CreateEngineEntityByNBT(nbt)

# CreateEngineEntityByTypeStr

服务端

method in mod.server.system.serverSystem.ServerSystem

  • 描述

    创建指定identifier的实体

  • 参数

    参数名
    数据类型
    说明
    engineTypeStr str 实体identifier,例如'minecraft:husk'
    pos tuple(float,float,float) 生成坐标
    rot tuple(float,float) 生物面向
    dimensionId int 生成的维度,默认值为0(0为主世界,1为地狱,2为末地)
    isNpc bool 是否为npc,默认值为False。npc不会移动、转向、存盘。
    isGlobal bool 是否创建为全局实体,默认为False。全局实体不会因为玩家视野、加载范围限制而被卸载,行为与tick会一直跑,但不代表会一直存在,依然会受清除 (opens new window)等原生逻辑影响,比如如果对有minecraft:despawn组件的生物创建全局实体,则还需要设置SetPersistent,否则离远后实体仍然会消失。全局实体会影响游戏性能,建议整个存档内同时存在的数量不超过10个。
  • 返回值

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

    • 在未加载的chunk无法创建 生成村民请使用"minecraft:villager_v2"
  • 示例

import mod.server.extraServerApi as serverApi
ServerSystem = serverApi.GetServerSystemCls()
class MyServerSystem(ServerSystem):
    def createMob(self):
        # 在主世界(0,5,0)的位置创建一个朝向为(0, 0)的尸壳
        entityId = self.CreateEngineEntityByTypeStr('minecraft:husk', (0, 5, 0), (0, 0), 0)

# CreateEngineItemEntity

服务端

method in mod.server.system.serverSystem.ServerSystem

  • 描述

    用于创建物品实体(即掉落物),返回物品实体的entityId

  • 参数

    参数名
    数据类型
    说明
    itemDict dict 物品信息字典
    dimensionId int 设置dimension,默认为主世界
    pos tuple(float,float,float) 生成坐标
  • 返回值

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

import mod.server.extraServerApi as serverApi
itemDict = {
    'itemName': 'minecraft:bow',
    'count': 1,
    'enchantData': [(serverApi.GetMinecraftEnum().EnchantType.BowDamage, 1),],
    'auxValue': 0,
    'customTips':'§c new item §r',
    'extraId': 'abc',
    'userData': { 'color': { '__type__':8, '__value__':'gray'} },
}
itemEntityId = self.CreateEngineItemEntity(itemDict, 0, (0, 5, 0))

# CreateEntityAOI

服务端

method in mod.server.component.dimensionCompServer.DimensionCompServer

  • 描述

    注册感应区域,有实体进入时和离开时会触发回调函数func

  • 参数

    参数名
    数据类型
    说明
    dimension int 维度id
    name str 注册的感应区域名
    aabb tuple(float,float,float,float,float,float) 感应区域的坐标范围,依次为minX, minY, minZ, maxX, maxY, maxZ
    func function 回调函数,参数dict请看备注
  • 返回值

    数据类型
    说明
    bool 是否注册成功
  • 备注

    • 每个实体都会触发一次func,第一次创建感应区时会检测一次区域内原有的生物并触发func
    • 不支持长或宽大于2000格的区域。对于大范围区域,建议在脚本中每隔一段时间获取实体坐标判断来实现。
    • 回调函数传入的参数dict
      参数名 类型 解释
      AOIName str 注册时传入的感应区域名
      entityType int 详见EntityType枚举
      pos tuple(float,float,float) 实体位置,只有进入的时候有
      dimension int 维度
      entityId str 实体Id
      identifier str 实体identifier
      isEnter bool 是否进入AOI,进入为True,退出为False
  • 示例

import mod.server.extraServerApi as serverApi
def fun(args):
    print "entitiy trigger AOI:{}".format(args)
comp = serverApi.GetEngineCompFactory().CreateDimension(levelId)
comp.CreateEntityAOI(0, "myTest", (0, 0, 0, 1, 1, 1), fun)

# CreateExperienceOrb

服务端

method in mod.server.component.expCompServer.ExpComponentServer

  • 描述

    创建专属经验球

  • 参数

    参数名
    数据类型
    说明
    exp int 经验球经验
    position tuple(float,float,float) 创建的位置
    isSpecial bool 是否专属经验球
  • 返回值

    数据类型
    说明
    bool 设置是否成功
  • 备注

    • 设置经验球经验,entityId是玩家的entityId。专属的经验球只有对应entityId的玩家才能拾取
  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateExp(entityId)
comp.CreateExperienceOrb(25,(10,10,10),False)

# CreateProjectileEntity

服务端

method in mod.server.component.projectileCompServer.ProjectileComponentServer

  • 描述

    创建抛射物(直接发射)

  • 参数

    参数名
    数据类型
    说明
    spawnerId str 创建者Id
    entityIdentifier str 创建抛射物的identifier,如minecraft:snowball
    param dict 默认为None,详细说明请见备注
  • 返回值

    数据类型
    说明
    str 创建抛射物的Id,失败时为“-1”
  • 备注

    • param参数解释如下:
      参数 类型 解释
      position tuple(float,float,float) 初始位置
      direction tuple(float,float,float) 初始朝向
      power float 投掷的力量值
      gravity float 抛射物重力因子,默认为json配置中的值
      damage float 抛射物伤害值,默认为json配置中的值
      targetId str 抛射物目标(指定了target之后,会和潜影贝生物发射的跟踪导弹的那个投掷物是一个效果),默认不指定
      isDamageOwner bool 对创建者是否造成伤害,默认不造成伤害
      auxValue int 抛射物auxValue(目前只对原生弓箭、喷溅药水有效)
  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateProjectile(levelId)
param = {
    'position': (1,1,1),
    'direction': (1,1,1)
}
comp.CreateProjectileEntity(playerId, "minecraft:snowball", param)

# DeleteEntityAOI

服务端

method in mod.server.component.dimensionCompServer.DimensionCompServer

  • 描述

    删除使用CreateEntityAOI注册的感应区

  • 参数

    参数名
    数据类型
    说明
    dimension int 维度id
    name str 需要删除的感应区域名
  • 返回值

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

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateDimension(levelId)
comp.DeleteEntityAOI(0, "myTest")

# DestroyEntity

服务端

method in mod.server.system.serverSystem.ServerSystem

  • 描述

    销毁实体

  • 参数

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

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

import mod.server.extraServerApi as serverApi
ServerSystem = serverApi.GetServerSystemCls()
class FpsServerSystem(ServerSystem):
    def testDestroyEntity(self, entityId):
        self.DestroyEntity(entityId)

# GetDroppedItem

服务端

method in mod.server.component.itemCompServer.ItemCompServer

  • 描述

    获取掉落物的物品信息

  • 参数

    参数名
    数据类型
    说明
    itemEntityId str 掉落物的entityId
    getUserData bool 是否获取userData,默认为False
  • 返回值

    数据类型
    说明
    dict 信息
  • 备注

    • 如果掉落物实体不存在,返回值为None
  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(levelId)
comp.GetDroppedItem(entityId)

# GetEngineActor

服务端客户端

# 服务端接口

method in mod.server.extraServerApi

  • 描述

    获取所有维度中已加载的所有实体(不包含玩家)。

  • 参数

  • 返回值

    数据类型
    说明
    dict 当前地图中的所有实体信息,key:实体id,value:实体信息字典
  • 备注

    • 实体信息字典 entityDict
      关键字 数据类型 说明
      dimensionId int 维度id
      identifier str 实体identifier
  • 示例

import mod.server.extraServerApi as serverApi
entityDicts = serverApi.GetEngineActor()

# 客户端接口

method in mod.client.extraClientApi

  • 描述

    获取客户端当前维度中已加载的所有实体(不包含玩家)。

  • 参数

  • 返回值

    数据类型
    说明
    dict 当前地图中的所有实体信息,key:实体id,value:实体信息字典
  • 备注

    • 实体信息字典 entityDict
      关键字 数据类型 说明
      dimensionId int 维度id
      identifier str 实体identifier
  • 示例

import mod.client.extraClientApi as clientApi
entityDicts = clientApi.GetEngineActor()

# GetLocalPlayerId

客户端

method in mod.client.extraClientApi

  • 描述

    获取本地玩家的id

  • 参数

  • 返回值

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

import mod.client.extraClientApi as clientApi
localId = clientApi.GetLocalPlayerId()

# GetLootItems

服务端

method in mod.server.component.lootCompServer.LootComponentServer

  • 描述

    指定战利品表获取一次战利品,返回的物品与json定义的概率有关

  • 参数

    参数名
    数据类型
    说明
    lootPath str 战利品表的路径
    entityId str 模拟被击杀的实体ID,默认为"-1"
    killerId str 模拟击杀该实体的实体ID,默认为"-1"
    luck float 模拟击杀该实体的玩家的幸运值,默认为0.0
    getUserData bool 是否获取UserData,默认为False
  • 返回值

    数据类型
    说明
    list(dict) 根据战利品表随机生成的物品字典列表
  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateLoot(playerId)
result = comp.GetLootItems("loot_tables/entities/zombie.json")

# GetPlayerList

服务端客户端

# 服务端接口

method in mod.server.extraServerApi

  • 描述

    获取所有维度中的全部玩家的id列表

  • 参数

  • 返回值

    数据类型
    说明
    list(str) 返回玩家id列表
  • 备注

    • 由于引擎中的玩家id是无序存储的,所以该接口返回列表的先后顺序没有实际意义,仅为在多平台下表现一致。
  • 示例

import mod.server.extraServerApi as serverApi
print serverApi.GetPlayerList()

# 客户端接口

method in mod.client.extraClientApi

  • 描述

    获取所有维度中的全部玩家的id列表

  • 参数

  • 返回值

    数据类型
    说明
    list(str) 返回玩家id列表
  • 备注

    • 由于引擎中的玩家id是无序存储的,所以该接口返回列表的先后顺序没有实际意义,仅为在多平台下表现一致。
  • 示例

import mod.client.extraClientApi as clientApi
print clientApi.GetPlayerList()

# HasEntity

客户端

method in mod.client.component.gameCompClient.GameComponentClient

  • 描述

    判断 entity 是否存在

  • 参数

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

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

import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateGame(levelId)
exist = comp.HasEntity(entityId)

# IsEntityAlive

服务端客户端

# 服务端接口

method in mod.server.component.gameCompServer.GameComponentServer

  • 描述

    判断生物实体是否存活或非生物实体是否存在

  • 参数

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

    数据类型
    说明
    bool false表示生物实体已死亡或非生物实体已销毁,true表示生物实体存活或非生物实体存在
  • 备注

    • 注意,如果检测的实体所在的区块被卸载,则该接口返回False。因此,需要注意实体所在的区块是否被加载。
    • 区块卸载:游戏只会加载玩家周围的区块,玩家移动到别的区域时,原来所在区域的区块会被卸载,参考区块介绍 (opens new window)
  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateGame(levelId)
alive = comp.IsEntityAlive(entityId)

# 客户端接口

method in mod.client.component.gameCompClient.GameComponentClient

  • 描述

    判断生物实体是否存活或非生物实体是否存在

  • 参数

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

    数据类型
    说明
    bool false表示生物实体已死亡或非生物实体已销毁,true表示生物实体存活或非生物实体存在
  • 备注

    • 注意,如果检测的实体所在的区块被卸载,则该接口返回False。因此,需要注意实体所在的区块是否被加载。
    • 区块卸载:游戏只会加载玩家周围的区块,玩家移动到别的区域时,原来所在区域的区块会被卸载,参考区块介绍 (opens new window)
  • 示例

import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateGame(levelId)
alive = comp.IsEntityAlive(entityId)

# KillEntity

服务端

method in mod.server.component.gameCompServer.GameComponentServer

  • 描述

    杀死某个Entity

  • 参数

    参数名
    数据类型
    说明
    entityId str 要杀死的目标的entityId
  • 返回值

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

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateGame(levelId)
comp.KillEntity(entityId)

# SpawnItemToLevel

服务端

method in mod.server.component.itemCompServer.ItemCompServer

  • 描述

    生成物品掉落物,如果需要获取物品的entityId,可以调用服务端系统接口CreateEngineItemEntity

  • 参数

    参数名
    数据类型
    说明
    itemDict dict 物品信息字典
    dimensionId int 设置dimension
    pos tuple(float,float,float) 生成位置
  • 返回值

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

import mod.server.extraServerApi as serverApi
itemDict = {
    'itemName': 'minecraft:bow',
    'count': 1,
    'enchantData': [(serverApi.GetMinecraftEnum().EnchantType.BowDamage, 1),],
    'auxValue': 0,
    'customTips':'§c new item §r',
    'extraId': 'abc',
    'userData': {},
}
comp = serverApi.GetEngineCompFactory().CreateItem(levelId)
comp.SpawnItemToLevel(itemDict, 0, (0,80,20))
# 当最大生成数量为 1 时,可以继续调用生成 2 个物品
comp.SpawnItemToLevel(itemDict, 0, (0,80,20))

# SpawnLootTable

服务端

method in mod.server.component.actorLootCompServer.ActorLootComponentServer

  • 描述

    使用生物类型模拟一次随机掉落,生成的物品与json定义的概率有关

  • 参数

    参数名
    数据类型
    说明
    pos tuple(int,int,int) 掉落位置
    identifier str 实体identifier,如minecraft:guardian
    playerKillerId str 玩家杀手(只能是玩家),默认None
    damageCauseEntityId str 伤害来源实体Id(掉落与该实体手持物品的抢夺附魔等级有关),默认None
  • 返回值

    数据类型
    说明
    bool 是否成功生成掉落
  • 备注

    • 需要在对应的player实体附近生成,否则会生成失败。对于某些特殊的生物,如minecraft:sheep,需要使用SpawnLootTableWithActor接口来模拟随机掉落。
  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateActorLoot(playerId)
result = comp.SpawnLootTable((1, 4, 5), 'minecraft:guardian')

# SpawnLootTableWithActor

服务端

method in mod.server.component.actorLootCompServer.ActorLootComponentServer

  • 描述

    使用生物实例模拟一次随机掉落,生成的物品与json定义的概率有关

  • 参数

    参数名
    数据类型
    说明
    pos tuple(int,int,int) 掉落位置
    entityId str 模拟生物的生物Id
    playerKillerId str 玩家杀手(只能是玩家),默认None
    damageCauseEntityId str 伤害来源实体Id(掉落与该实体手持物品的抢夺附魔等级有关),默认None
  • 返回值

    数据类型
    说明
    bool 是否成功生成掉落
  • 备注

    • 需要在对应的player实体附近生成,否则会生成失败
  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateActorLoot(playerId)
result = comp.SpawnLootTableWithActor((1, 4, 5), '-335007449086')

# SpawnResources

服务端

method in mod.server.component.blockInfoCompServer.BlockInfoComponentServer

  • 描述

    产生方块随机掉落(该方法不适用于实体方块)

  • 参数

    参数名
    数据类型
    说明
    identifier str 方块的identifier,如minecraft:wool
    pos tuple(int,int,int) 掉落位置
    aux int 方块的附加值
    probability float 掉落概率,范围为[0, 1],0为不掉落,1为100%掉落
    bonusLootLevel int 时运等级 (opens new window),默认为0
    dimensionId int 掉落方块的维度,默认值为-1,传入非负值时用于获取产生方块掉落的维度;否则将随机挑选一个存在玩家的维度产生掉落
    allowRandomness bool 是否允许随机采集,默认为True,如果为False,掉落概率probability无效
  • 返回值

    数据类型
    说明
    bool 是否成功
  • 备注

    • 时运等级[bonusLootLevel]只对部分方块生效 掉落概率[probability]对部分农作物树叶不生效
    • 可在对应维度的常加载区块产生掉落
  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockInfo(levelId)
# 金矿石掉落
result = comp.SpawnResources('minecraft:gold_ore', (1,1,1), 7, 1.0, 10)
# 指定维度产生掉落
comp = serverApi.GetEngineCompFactory().CreateBlockInfo(levelId)
result = comp.SpawnResources('minecraft:gold_ore', (1,1,1), 7, 1.0, 10, 0)

# SpawnResourcesSilkTouched

服务端

method in mod.server.component.blockInfoCompServer.BlockInfoComponentServer

  • 描述

    模拟方块精准采集掉落

  • 参数

    参数名
    数据类型
    说明
    identifier str 方块的identifier,如minecraft:wool
    pos tuple(int,int,int) 掉落位置
    aux int 方块的附加值
    dimensionId int 掉落方块的维度,默认值为-1,传入非负值时用于获取产生方块掉落的维度;否则将随机挑选一个存在玩家的维度产生掉落
  • 返回值

    数据类型
    说明
    bool 是否成功
  • 备注

    • 如果指定方块不属于精准采集方块,返回False
  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockInfo(levelId)
result = comp.SpawnResourcesSilkTouched('minecraft:gold_ore', (1,1,1), 7)

# getEntitiesOrBlockFromRay

服务端客户端

# 服务端接口

method in mod.server.extraServerApi

  • 描述

    从指定位置发射一条射线,获取与射线相交的实体和方块

  • 参数

    参数名
    数据类型
    说明
    dimensionId int 生成的维度(必填)(0为主世界,1为下界,2为末地)
    pos tuple(float,float,float) 指定位置坐标(必填)
    rot tuple(float,float,float) 射线方向单位向量(必填)
    distance int 射线长度(一个方块长度为1)(选填,默认16)
    isThrough bool 是否穿透,如穿透,则返回所有射线穿过的实体或方块,如不穿透,则返回第一个碰撞到的实体或方块(选填,默认为False)
    filterType minecraftEnum RayFilterType枚举(选填,默认为serverApi.GetMinecraftEnum().RayFilterType.OnlyEntities)
  • 返回值

    数据类型
    说明
    list(dict) 返回实体信息列表(根据距指定位置由近到远排序, id越靠前距离指定位置越近),详细见备注
  • 备注

    • 选中目标为实体时,返回值为:
      [{
          "type": "Entity",
          "entityId": entityId,
          "identifier": identifier,
          "hitPos" : (x, y, z)  #精准碰撞坐标,类型为tuple(float,float,float)
      },
      {
          ...
      }]
      
    • 选中目标为方块时,返回值为:
      [{
          "type": "Block",
          "pos" : (0, 1, 0),
          "identifier": identifier,
          "hitPos" : (x, y, z) #精准碰撞坐标,类型为tuple(float,float,float)
      },
      {
          ...
      }]
      
    • 没有选中目标时,返回值为:None
    • 假设方块的clip(计算射线检测时用的碰撞盒)没有体积时,射线检测将会无视这个方块,例如原版的火焰,灵魂火等;自定义方块的clip可以在netease:aabb中进行设置
  • 示例

import mod.server.extraServerApi as serverApi
entityDicts = serverApi.getEntitiesOrBlockFromRay(0, (0, 0, 0), (1, 0, 0), 16, False, serverApi.GetMinecraftEnum().RayFilterType.OnlyEntities)

# 客户端接口

method in mod.client.extraClientApi

  • 描述

    从指定位置发射一条射线,获取与射线相交的实体和方块

  • 参数

    参数名
    数据类型
    说明
    pos tuple(float,float,float) 指定位置坐标(必填)
    rot tuple(float,float,float) 射线方向单位向量(必填)
    distance int 射线长度(一个方块长度为1)(选填,默认16)
    isThrough bool 是否穿透,如穿透,则返回所有射线穿过的实体或方块,如不穿透,则返回第一个碰撞到的实体或方块(选填,默认为False)
    filterType minecraftEnum RayFilterType枚举(选填,默认为serverApi.GetMinecraftEnum().RayFilterType.OnlyEntities)
  • 返回值

    数据类型
    说明
    list(dict) 返回实体信息列表(根据距指定位置由近到远排序, id越靠前距离指定位置越近),详细见备注
  • 备注

    • 选中目标为实体时,返回值为:
      [{
          "type": "Entity",
          "entityId": entityId,
          "identifier": identifier,
          "hitPos" : (x, y, z)  #精准碰撞坐标,类型为tuple(float,float,float)
      },
      {
          ...
      }]
      
    • 选中目标为方块时,返回值为:
      [{
          "type": "Block",
          "pos" : (0, 1, 0),
          "identifier": identifier,
          "hitPos" : (x, y, z) #精准碰撞坐标,类型为tuple(float,float,float)
      },
      {
          ...
      }]
      
    • 没有选中目标时,返回值为:None
    • 假设方块的clip(计算射线检测时用的碰撞盒)没有体积时,射线检测将会无视这个方块,例如原版的火焰,灵魂火等;自定义方块的clip可以在netease:aabb中进行设置
  • 示例

import mod.client.extraClientApi as clientApi
entityDicts = clientApi.getEntitiesOrBlockFromRay((0, 0, 0), (1, 0, 0), 16, False, clientApi.GetMinecraftEnum().RayFilterType.OnlyEntities)