LogoArcartX Doc

ArcartXPlayer:玩家管理对象

ArcartX玩家管理对象API

ArcartXPlayer

  • ArcartXPlayer 继承自 ArcartXEntity,是ArcartX对玩家的完整管理对象。
  • 通过 ArcartXAPI.getEntityManager().getPlayer(player) 获取。
  • 除了继承自 ArcartXEntity 的所有方法外,还提供了大量玩家专属功能。
  • 本类的方法分为两种发送模式:
    • 点对点 — 仅向该玩家自身的客户端发送数据包(如相机、着色器、特效等)
    • 广播 — 向所有能看到该玩家的客户端发送数据包(如模型、控制器、状态、额外模型、时装、变体、动画包等)

模型管理、动画控制(setState / setController)、额外模型、时装、模型变体、动画包等方法是广播模式,会同步给所有能看到该玩家的客户端。相机、着色器、天空盒、特效等方法是点对点模式,仅发送给该玩家自身。

公开属性

ArcartXPlayer 自身声明的公开属性如下(继承自父类的属性见 ArcartXEntity 页):

  • player: Player — 该对象对应的 Bukkit 玩家实例(构造时传入,只读)
  • encryptor: AESEncryptor? — 与客户端通信使用的 AES 加密器,可能为 null
  • key: String? — 通信密钥,可能为 null
  • alt: boolean — 是否为小号(alt)客户端标记
  • callbacks: Map<String, CallBack> — 回调映射表,用于客户端异步回调
  • crc64: Set<Long> — 已发送资源的 CRC64 校验集合
  • area: Area? — 玩家当前所处的区域,可能为 null
  • playerModel: String — 当前玩家模型ID(只读,通过 setModel 更新)
  • playerModelScale: double — 当前玩家模型缩放比例(只读)
  • 当前变体通过 getAppearance().getVariant() 读取,值为 DEFAULT_BBMODEL / CUSTOM_BBMODEL;variant 本身不是公开属性
  • animationPackId: String — 当前玩家动画包ID(只读,空字符串表示无)
  • sentResource: boolean — 是否已向该玩家发送资源
  • jumpTime: long — 上一次跳跃的时间戳

模型管理

setModel(modelID, scale)

  • 设置玩家模型,会触发 PlayerModelUpdateEvent 事件,并向所有能看到该玩家的其他玩家广播模型变更
  • 重写自 ArcartXEntity.setModel,额外记录 playerModel / playerModelScale 并派发玩家专属事件
  • 清除已选择的宿主配置 ID,保留模型变体、动态时装槽、旧时装和动画包。切换宿主与配套时装时,请使用下方 updateAppearance
  • 恢复旧模型接口的发送方式;未选择新宿主模式的外部 DEFAULT_BBMODEL 仍向旧客户端同步原时装和动画包
  • 提交前会触发可取消的 PlayerAppearanceChangeEvent;提交成功后才触发 PlayerModelUpdateEvent
  • 参数:
    • modelID: String — 模型ID
    • scale: double — 模型缩放比例
  • 返回值:无
  • 调用示例
axPlayer.setModel("knight", 1.0);

removeModel()

  • 移除玩家模型,恢复默认外观,并重置 playerModel 与 playerModelScale
  • 重写自 ArcartXEntity.removeModel
  • 同时清除宿主配置 ID 和动态时装槽;旧时装、动画包和模型变体保留。可通过 PlayerAppearanceChangeEvent 取消
  • 参数:无
  • 返回值:无
  • 调用示例
axPlayer.removeModel();

setDefaultModel(scale)

  • 将玩家模型设置为默认玩家模型(__default_player__),并将变体切换为 DEFAULT_BBMODEL
  • 会触发 PlayerVariantChangeEvent 事件(若被取消则不生效),并广播变体变更
  • DEFAULT_BBMODEL 变体会叠加原版附属物(盔甲/披风/鞘翅/时装)
  • 清除宿主配置 ID,保留动态时装、旧时装和动画包;旧变体事件通过后,还会触发可取消的 PlayerAppearanceChangeEvent
  • 参数:scale: double — 模型缩放比例(默认 1.0)
  • 返回值:无
  • 调用示例
axPlayer.setDefaultModel(1.0);

setCustomModel(modelID, scale)

  • 将玩家模型设置为自定义模型,并将变体切换为 CUSTOM_BBMODEL
  • 会触发 PlayerVariantChangeEvent 事件(若被取消则不生效),并广播变体变更
  • 参数:
    • modelID: String — 模型ID
    • scale: double — 模型缩放比例(默认 1.0)
  • 返回值:无
  • 调用示例
axPlayer.setCustomModel("knight", 1.0);

setCustomModel 使用 CUSTOM_BBMODEL,不叠加时装和原版附属物,不是可装备动态时装的宿主模式。 它清除宿主配置 ID,但保留时装和动画包记录;时装在该模式下不显示,动画包仍按原有规则使用。旧变体事件通过后,还会触发可取消的 PlayerAppearanceChangeEvent。

tryModel(modelID, scale, time)

  • 临时只显示指定主体模型,持续 time 毫秒后恢复当前保存的完整外观
  • 临时外观使用 CUSTOM_BBMODEL,不带宿主配置、时装或动画包,避免把原宿主的附件绑定到另一套骨骼
  • 不修改 playerModel 或 getAppearance() 保存的记录。开始试穿时触发可取消的 PlayerAppearanceChangeEvent,不触发旧变体/模型事件;定时恢复不派发该事件
  • 试穿期间的真实外观提交会结束试穿,且不会被旧计时器覆盖。即使提交的外观与保存记录相同,也会恢复显示保存的外观;此恢复可被变更事件取消
  • 参数:
    • modelID: String — 临时模型ID
    • scale: double — 模型缩放比例
    • time: long — 临时持续时间(毫秒),到时后恢复原模型
  • 返回值:无
  • 调用示例
axPlayer.tryModel("hurt_pose", 1.0, 1000);

自定义玩家宿主与完整外观

以下 DTO 位于 priv.seventeen.artist.arcartx.core.playerhost 包。外观为运行时内存态,玩家离线后不自动保存。请在服务端玩家逻辑线程调用修改方法,不要在 PlayerAppearanceChangeEvent 内再次提交外观。

新客户端一次接收主体、宿主配置、动态槽、动画包和旧时装的完整快照。 旧客户端不支持自定义宿主绑定,只显示主体模型,不显示该宿主的时装或动画包。

setPlayerHost(modelID, profileId, scale)

设置可装备时装的非内置玩家宿主,变体切换为 DEFAULT_BBMODEL。已有动态槽、旧时装和动画包保留。

此方法明确选择新宿主模式,配置 ID 为空时也一样;旧客户端将仅显示主体,不使用该宿主的时装和动画包。 再次调用旧 setModel、setDefaultModel、setCustomModel 或 removeModel 会退出这个选择。

  • 参数:
    • modelID: String — 非空宿主模型 ID
    • profileId: String — 已注册的宿主配置 ID,须与模型绑定;空字符串使用模型 axmeta 的 player_host
    • scale: double — 大于零且不超过 1024 的缩放
  • Java 重载:setPlayerHost(modelID)、setPlayerHost(modelID, profileId)、setPlayerHost(modelID, profileId, scale);省略配置 ID 时为空,省略缩放时为 1.0
  • 返回值:boolean — 取消为 false,接受或状态未改变为 true
  • 调用示例
boolean changed = axPlayer.setPlayerHost("characters/hero", "hero", 1.0);

getAppearance() / getAppearanceRevision()

读取保存的完整外观和同步版本号。PlayerAppearance 及其集合均为只读快照;临时试穿不改变此快照。版本号供观察同步使用,不是身体动画或绑定缓存的重置开关。

PlayerAppearance appearance = axPlayer.getAppearance();
String profileId = appearance.getProfileId();
String variant = appearance.getVariant();
long revision = axPlayer.getAppearanceRevision();

setAppearance(appearance)

用一个 PlayerAppearance 完整替换保存的外观,不与旧值逐字段合并。 构造参数依次为 model、scale、variant、profileId、packId、slots、legacyCostume。其中 slots 为动态字符串槽,legacyCostume 为原五个枚举槽或套装。

这是明确选择完整外观的新接口:外部 DEFAULT_BBMODEL 或非空宿主配置 ID 会选择新宿主模式,并对旧客户端仅显示主体。 需要保留旧接口行为、只修改服装或动画包时,可使用 updateAppearance 且不设置 model / profileId。

PlayerAppearance next = new PlayerAppearance(
    "characters/hero", 1.0, "DEFAULT_BBMODEL", "hero", "hero_actions",
    java.util.Collections.singletonMap("hair", new PlayerHostCostume("costumes/hair")),
    axPlayer.getAppearance().getLegacyCostume()
);
boolean accepted = axPlayer.setAppearance(next);

updateAppearance(update)

接收 Consumer<PlayerAppearanceBuilder>,从当前保存的外观开始修改,回调结束后统一校验和提交。需要同时切换模型、宿主配置、时装和动画包时使用此方法;中途不会广播,也不会产生部分成功的状态。

回调内只修改传入的 builder,不要再次调用同一玩家的外观修改或试穿方法。此类调用会抛出 IllegalStateException,且不会派发变更事件;回调抛出异常时,尚未提交的修改全部放弃。

回调仅修改槽位或动画包时,保留当前是否选择新宿主的状态。 只要调用 builder 的 setModel 或 setProfileId,即使值与原值相同,也会按提交的模型与配置重新选择宿主模式。 动态槽 equipCostume / removeCostume 重载本身不改变此选择。

boolean accepted = axPlayer.updateAppearance(update -> {
    update.setModel("characters/hero");
    update.setScale(1.0);
    update.setVariant("DEFAULT_BBMODEL");
    update.setProfileId("hero");
    update.setPackId("hero_actions");
    update.getSlots().clear();
    update.getSlots().put("hair", new PlayerHostCostume("costumes/hair"));
});

setAppearance、updateAppearance 和动态槽修改方法的返回规则同 setPlayerHost。 输入不合法时抛出 IllegalArgumentException,不触发变更事件、不修改任何字段; 校验通过后仅派发一次可取消的 PlayerAppearanceChangeEvent。新方法不补发旧枚举时装、变体或动画包事件。

supportsCustomPlayerHost()

检查该玩家客户端在连接握手中是否上报 custom_player_host_v1。 握手尚未完成、旧客户端或已退出清理的连接返回 false。 该方法不代表模型资源已经加载成功。

此方法仅检查宿主功能,不代表已支持单文件时装筛选。renderRoots 另需 custom_costume_render_roots_v1; 服务端按接收外观的观察者能力自动降级,缺少该能力时暂不显示筛选槽,未筛选槽仍保留。

boolean supported = axPlayer.supportsCustomPlayerHost();

addExtraModel(locator, modelID)

  • 为玩家添加额外模型,挂载在指定定位器上
  • 参数:
    • locator: String — 定位器名称
    • modelID: String — 模型ID
  • 返回值:无
  • 调用示例
axPlayer.addExtraModel("back_extra", "wings_model");

removeExtraModel(locator)

  • 移除玩家指定定位器上的额外模型
  • 参数:locator: String — 定位器名称
  • 返回值:无
  • 调用示例
axPlayer.removeExtraModel("back_extra");

clearExtraModels()

  • 清除玩家所有额外模型
  • 参数:无
  • 返回值:无
  • 调用示例
axPlayer.clearExtraModels();

时装管理

时装为运行时内存态(不落库)。原 CostumeSlot 枚举仍为 HEAD / BODY / LEGS / FEET / DECORATION。 套装与这五个枚举槽互斥,动态字符串槽独立保存。原方法先触发 PlayerCostumeChangeEvent,再触发 PlayerAppearanceChangeEvent;任一事件取消都不会提交。

equipSuit(modelID, hide)

  • 为玩家装备整套时装,并清空原五个枚举时装槽;不清空动态字符串槽
  • 参数:
    • modelID: String — 时装套装模型ID
    • hide: boolean — 是否隐藏原版对应部位(默认 true)
  • 返回值:无
  • 调用示例
axPlayer.equipSuit("costume_suit_a", true);

equipCostume(slot, modelID, hide)

  • 为玩家在指定槽位装备单件时装,并清除已装备的套装
  • 参数:
    • slot: CostumeSlot — 时装槽位(HEAD / BODY / LEGS / FEET / DECORATION)
    • modelID: String — 时装模型ID
    • hide: boolean — 是否隐藏原版对应部位(默认 false)
  • 返回值:无
  • 调用示例
axPlayer.equipCostume(ArcartXPlayer.CostumeSlot.HEAD, "hat_a", false);

removeCostume(slot)

  • 移除玩家指定槽位的单件时装
  • 参数:slot: CostumeSlot — 时装槽位
  • 返回值:无
  • 调用示例
axPlayer.removeCostume(ArcartXPlayer.CostumeSlot.HEAD);

clearCostume()

  • 清除玩家所有时装,包括旧套装、五个枚举槽和动态字符串槽;不清除宿主配置或动画包
  • 参数:无
  • 返回值:无
  • 调用示例
axPlayer.clearCostume();

equipCostume(slotId, modelID, binding, hide)

为动态字符串槽装备时装,须先设置非空宿主模型。槽 ID 使用 [a-z][a-z0-9_.-]{0,63},精确匹配,不自动转小写;中文名称填写在宿主配置的 label 中。动态槽最多 64 个,与旧 CostumeSlot 重载相互独立。

  • 参数:
    • slotId: String — 例如 hair、clothes、hair.front
    • modelID: String — 时装模型 ID
    • binding: PlayerHostBinding — 默认 mapped 严格同名绑定;attach 使用源根骨骼与宿主锚点
    • hide: PlayerHostHide? — 为 null 或省略时,先继承该槽的 default_hide;槽位也未配置时,mapped 按选中时装几何的绑定自动隐藏覆盖的宿主骨骼。显式空对象表示不隐藏
  • Java 重载:前两个参数必填,后两个参数可依次省略
  • 返回值:boolean
  • 调用示例
// 默认 mapped 绑定,并继承槽位隐藏设置
axPlayer.equipCostume("clothes", "costumes/coat");
 
// attach 到 Head 上的 hair_socket 定位器;省略定位器时只跟随骨骼
PlayerHostBinding binding = new PlayerHostBinding(
    "attach", "Hair", new PlayerHostAnchor("Head", "hair_socket"),
    java.util.Collections.emptyMap(), new PlayerHostOffset()
);
axPlayer.equipCostume("hair", "costumes/hair", binding);
 
// 显式不隐藏任何宿主部位或骨骼
axPlayer.equipCostume("hair", "costumes/hair", binding, new PlayerHostHide());

PlayerHostBinding 构造参数为 mode、sourceRoot、anchor、boneMap、offset。mode 只能是 attach 或 mapped; mapped 的映射为精确的源骨骼到目标骨骼,空映射使用严格同名匹配。PlayerHostOffset 的 position、rotation、scale 均为三个 double;数值必须有限、绝对值不超过 1000000,缩放绝对值至少为 0.000001。

PlayerHostHide 的 parts 仅接受 HEAD / BODY / LEGS / FEET / OTHER,隐藏对应部位的全部几何; 未单独分类的子骨继承最近的部位声明,单独声明的头部、鞋等不会被父骨所在部位一并隐藏。 bones 为精确骨骼名称,只隐藏所列骨骼自身的几何。 显式 hide 完全覆盖默认设置;非空或空的 default_hide 都按配置执行,不再追加自动范围。 只有两者都未配置时,才使用 mapped 自动覆盖,attach 不会自动隐藏锚点骨骼。

模型、动画包、骨骼和定位器名称最多 256 位;引用列表和骨骼映射最多 4096 项。 服务端校验字段格式,模型中骨骼和定位器是否存在由客户端加载后检查。

PlayerHostCostume(model, binding, hide, renderRoots)

用于在完整外观或 updateAppearance 中设置一个时装条目。 renderRoots 对应通讯字段 render_roots,允许同一个完整时装模型按骨骼范围装备到多个槽位,无需拆分文件。

  • model: String — 时装模型 ID。
  • binding: PlayerHostBinding — 默认 mapped 同名绑定。
  • hide: PlayerHostHide? — 默认 null,先继承槽位隐藏设置;槽位也未配置时按上述自动覆盖规则处理。显式空对象不隐藏。
  • renderRoots: List<String>? — 源时装骨骼及其后代的并集;默认 null,保持原显示范围。显式列表须非空,最多 4096 项。
// 示例宿主使用 skull;请替换成你的真实宿主骨骼名。
PlayerHostBinding binding = new PlayerHostBinding(
    "mapped", "", null, java.util.Map.of("Hair", "skull", "Head", "skull"),
    new PlayerHostOffset()
);
axPlayer.updateAppearance(update -> {
    update.getSlots().put("hair", new PlayerHostCostume(
        "costumes/hero", binding, new PlayerHostHide(),
        java.util.Arrays.asList("Hair")
    ));
    update.getSlots().put("head", new PlayerHostCostume(
        "costumes/hero", binding, null,
        java.util.Arrays.asList("Head")
    ));
});

骨骼名称必须存在于源时装,且大小写一致。 mapped 只校验选中几何的绑定;attach 的选择不能超出 sourceRoot 子树。 筛选只影响几何提交,完整骨树和动画仍保留,CPU/GPU 范围相同。错误槽位不会让宿主隐藏。

renderRoots 不是 hide:前者选择时装自身,后者隐藏宿主。 自动隐藏只计算选中的可绘几何,不会因为同一文件还包含其它部位就一起隐藏它们。 多个有效槽位的隐藏范围取并集,卸下后重新计算;隐藏只影响几何,不中断宿主动画或定位器。 旧的一至三个参数 Java 构造方法继续可用。各槽仍独立推进同一资源的动作,未按资源合并全局声音或命令事件。 详见自定义玩家宿主。

removeCostume(slotId)

移除指定动态字符串槽,返回 boolean。不会移除同名含义的旧枚举槽,也不会清除宿主或动画包。

boolean accepted = axPlayer.removeCostume("hair");

动画控制

setAnimationPack(packId)

  • 为玩家设置动画包,会触发 PlayerAnimationPackChangeEvent 事件(若被取消则不生效),并广播给观察者
  • 参数:packId: String — 动画包ID
  • 返回值:无
  • 调用示例
axPlayer.setAnimationPack("knight_anim");

clearAnimationPack()

  • 清除玩家的动画包(将 animationPackId 置空),会触发 PlayerAnimationPackChangeEvent 事件(若被取消则不生效)
  • 参数:无
  • 返回值:无
  • 调用示例
axPlayer.clearAnimationPack();

playFirstPersonAnimationByTime(animation, speed, keepTime)

  • 为玩家播放第一人称动画,按持续时间控制
  • 参数:
    • animation: String — 动画名称
    • speed: double — 播放速度
    • keepTime: int — 持续时间(毫秒)
  • 返回值:无
  • 调用示例
axPlayer.playFirstPersonAnimationByTime("slash", 1.0, 500);

playFirstPersonAnimationByCountOf(animation, speed, count)

  • 为玩家播放第一人称动画,按播放次数控制
  • 参数:
    • animation: String — 动画名称
    • speed: double — 播放速度
    • count: int — 播放次数
  • 返回值:无
  • 调用示例
axPlayer.playFirstPersonAnimationByCountOf("swing", 1.5, 3);

setState(controller, state)

  • 设置玩家动作控制器的状态
  • 参数:
    • controller: String — 控制器名称
    • state: String — 状态名称
  • 返回值:无
  • 调用示例
axPlayer.setState("combat", "attack_1");

setState(controller, state, speed)

  • 设置玩家动作控制器的状态,指定播放速度
  • 参数:
    • controller: String — 控制器名称
    • state: String — 状态名称
    • speed: double — 播放速度
  • 返回值:无
  • 调用示例
axPlayer.setState("combat", "attack_1", 2.0);

setState(controller, state, speed, moveBreak)

  • 设置玩家动作控制器的状态,指定播放速度和移动打断时间
  • 参数:
    • controller: String — 控制器名称
    • state: String — 状态名称
    • speed: double — 播放速度
    • moveBreak: long — 移动打断时间(毫秒),-1为不打断
  • 返回值:无
  • 调用示例
axPlayer.setState("combat", "heavy_attack", 1.0, 2000);

setController(controller)

  • 为玩家设置动作控制器
  • 参数:controller: String — 控制器配置ID
  • 返回值:无
  • 调用示例
axPlayer.setController("combat_controller");

飞行状态

updateFlyingState()

  • 轮询检测玩家飞行态,若相比上次发生变化则按 seenBy 广播给观察者
  • 用于同步飞行态(原版不会向其他玩家同步 abilities.flying),一般由内部每 tick 调用
  • 参数:无
  • 返回值:无
  • 调用示例
axPlayer.updateFlyingState();

相机控制

setThirdPerson(enable)

  • 将玩家设置为第三人称视角
  • 参数:enable: boolean — true 设置为第三人称,false 设置为第一人称
  • 返回值:无
  • 调用示例
axPlayer.setThirdPerson(true);

setViewLock(enable)

  • 设置视角锁定开关(开启时锁定为第三人称,关闭时解除锁定)
  • 等价于 setViewLockMode,enable 为 true 时使用模式 2,false 时使用模式 0
  • 参数:enable: boolean — true 锁定视角,false 解除锁定
  • 返回值:无
  • 调用示例
axPlayer.setViewLock(true);

setViewLockMode(mode)

  • 设置视角锁定模式
  • 参数:mode: int — 锁定模式(0-关闭,1-强制锁定第一人称,2-强制锁定第三人称)
  • 返回值:无
  • 调用示例
axPlayer.setViewLockMode(2);

setCameraFromPreset(id)

  • 从预设配置设置玩家相机
  • 参数:id: String — 相机预设配置ID
  • 返回值:无
  • 调用示例
axPlayer.setCameraFromPreset("idle");

setCameraLocation(offsetX, offsetY, offsetZ, freeView)

  • 设置玩家相机的偏移位置
  • 参数:
    • offsetX: double — X轴偏移
    • offsetY: double — Y轴偏移
    • offsetZ: double — Z轴偏移
    • freeView: boolean — 是否允许自由视角
  • 返回值:无
  • 调用示例
axPlayer.setCameraLocation(0, 2.0, -5.0, true);

startSceneCamera(sceneId)

  • 开始播放场景相机
  • 参数:sceneId: String — 场景相机配置ID
  • 返回值:无
  • 调用示例
axPlayer.startSceneCamera("intro_scene");

stopSceneCamera()

  • 停止场景相机播放
  • 参数:无
  • 返回值:无
  • 调用示例
axPlayer.stopSceneCamera();

着色器与天空盒

enableShader(shader)

  • 为玩家启用后处理着色器
  • 参数:shader: String — 着色器名称
  • 返回值:无
  • 调用示例
axPlayer.enableShader("blur");

disableShader()

  • 关闭玩家的着色器效果
  • 参数:无
  • 返回值:无
  • 调用示例
axPlayer.disableShader();

setSkyTexture(texturePath, forceNoCloud)

  • 为玩家设置自定义天空盒贴图
  • 参数:
    • texturePath: String — 天空盒贴图资源路径
    • forceNoCloud: boolean — 是否强制隐藏云层
  • 返回值:无
  • 调用示例
axPlayer.setSkyTexture("sky/night.png", true);

clearSkyTexture()

  • 清除玩家的自定义天空盒,恢复默认天空
  • 参数:无
  • 返回值:无
  • 调用示例
axPlayer.clearSkyTexture();

setClientTitle(text)

  • 设置玩家客户端的标题文本
  • 参数:text: String — 标题文本
  • 返回值:无
  • 调用示例
axPlayer.setClientTitle("欢迎来到冒险世界");

特效

以下特效方法均为点对点发送,仅发送给该玩家自身的客户端。如果你需要让周围所有玩家都看到特效,请使用 ArcartXEffectManager 的范围广播方法。

spawnBedrockParticle(identifier, particleID, effectPosition)

  • 在玩家客户端生成基岩粒子效果
  • 参数:
    • identifier: String — 粒子标识符
    • particleID: String — 粒子ID
    • effectPosition: EffectPosition — 特效位置
  • 返回值:无
  • 调用示例
axPlayer.spawnBedrockParticle("my_particle", "flame",
    EffectPosition.followEntity(player));

存在一个已弃用的旧重载 spawnBedrockParticle(id, x, y, z, yaw, pitch)(@Deprecated),请改用上面的 spawnBedrockParticle(identifier, particleID, effectPosition)。

与 ArcartXEffectManager.spawnBedrockParticle 的区别:

  • ArcartXPlayer.spawnBedrockParticle — 点对点,仅该玩家自身可见
  • ArcartXEffectManager.Entity.spawnBedrockParticle — 范围广播,所有能看到该实体的玩家可见
  • ArcartXEffectManager.World.spawnBedrockParticle — 范围广播,指定位置128格内所有玩家可见

选择哪个取决于你的需求:如果粒子只需要一个玩家看到,用Player版本;如果需要所有人看到(如技能特效),用EffectManager版本。

addWorldTexture(id, builder, effectPosition)

  • 在玩家客户端添加世界贴图
  • 参数:
    • id: String — 贴图唯一标识
    • builder: WorldTextureBuilder — 贴图构建器
    • effectPosition: EffectPosition — 特效位置
  • 返回值:无
  • 调用示例
WorldTextureBuilder builder = new WorldTextureBuilder()
    .setTexture("effects/magic_circle.png", true, true)
    .setSize(256.0, 256.0)
    .setLifeTime(-1);
axPlayer.addWorldTexture("magic_circle", builder,
    EffectPosition.followEntity(player, 0, 0, 0, 0, 0, 0, true, true));

与 ArcartXEffectManager.spawnWorldTextureEffect 的区别:

  • ArcartXPlayer.addWorldTexture — 点对点,仅该玩家自身可见
  • ArcartXEffectManager.spawnWorldTextureEffect — 范围广播,周围所有玩家可见

removeWorldTexture(id)

  • 移除玩家客户端的世界贴图
  • 参数:id: String — 贴图唯一标识
  • 返回值:无
  • 调用示例
axPlayer.removeWorldTexture("magic_circle");

playBlockAnimation(x, y, z, animation, speed, transitionTime, keepTime)

  • 在玩家客户端播放方块动画
  • 参数:
    • x y z: int — 方块坐标
    • animation: String — 动画名称
    • speed: double — 播放速度
    • transitionTime: int — 过渡时间(毫秒)
    • keepTime: long — 持续时间(毫秒)
  • 返回值:无
  • 调用示例
axPlayer.playBlockAnimation(100, 64, 200, "open", 1.0, 5, 3000);

spawnHammerCrackEffect(x, y, z, radius, depth, in, keep, out, mode)

  • 在玩家客户端生成锤击裂纹特效
  • 参数:
    • x y z: int — 中心坐标
    • radius: float — 裂纹半径
    • depth: float — 裂纹深度
    • in: int — 淡入时间(毫秒)
    • keep: int — 保持时间(毫秒)
    • out: int — 淡出时间(毫秒)
    • mode: int — 裂纹模式
  • 返回值:无
  • 调用示例
axPlayer.spawnHammerCrackEffect(100, 64, 200, 3.0f, 1.0f, 200, 1000, 500, 0);

伤害显示

addDamageDisplay(damageDisplayConfigId, x, y, z, damage)

  • 在指定坐标为玩家显示伤害数字
  • 参数:
    • damageDisplayConfigId: String — 伤害显示配置ID
    • x y z: double — 显示坐标
    • damage: double — 伤害数值
  • 返回值:无
  • 调用示例
axPlayer.addDamageDisplay("critical", 100.0, 65.0, 200.0, 999.0);

addDamageDisplay(damageDisplayConfigId, target, damage)

  • 在目标实体位置为玩家显示伤害数字
  • 参数:
    • damageDisplayConfigId: String — 伤害显示配置ID
    • target: Entity — 目标实体
    • damage: double — 伤害数值
  • 返回值:无
  • 调用示例
axPlayer.addDamageDisplay("default", targetEntity, 50.0);

与 ArcartXEntity.broadcastDamageDisplay 的区别:

  • ArcartXPlayer.addDamageDisplay — 点对点,仅该玩家自身可见
  • ArcartXEntity.broadcastDamageDisplay — 范围广播,所有能看到该实体的玩家可见
  • ArcartXEntity.sendDamageDisplayToPlayers — 指定列表,仅列表中的玩家可见

路标管理

addWayPoint(id, title, waypointConfigId, x, y, z)

  • 为玩家添加一个路标
  • 参数:
    • id: String — 路标唯一标识
    • title: String — 路标显示标题
    • waypointConfigId: String — 路标配置ID
    • x y z: double — 路标坐标
  • 返回值:无
  • 调用示例
axPlayer.addWayPoint("quest_1", "任务目标", "default", 100.0, 64.0, 200.0);

deleteWayPoint(id, regex)

  • 删除玩家的路标
  • 参数:
    • id: String — 路标标识
    • regex: boolean — 是否使用正则匹配(默认false)
  • 返回值:无
  • 调用示例
axPlayer.deleteWayPoint("quest_1");

clearWayPoint()

  • 清除玩家的所有路标
  • 参数:无
  • 返回值:无
  • 调用示例
axPlayer.clearWayPoint();

额外槽位管理

setSlotItemStack(slotID, itemStack)

  • 设置额外槽位的物品,同时更新数据库和客户端显示,并触发 PlayerExtraSlotUpdateEvent 事件、执行槽位配置的更新脚本
  • 参数:
    • slotID: String — 槽位ID
    • itemStack: ItemStack — 物品
  • 返回值:无
  • 调用示例
axPlayer.setSlotItemStack("ring_1", itemStack);

setSlotItemStackOnlyClient(slotID, itemStack)

  • 仅更新客户端显示的槽位物品,不写入数据库
  • 参数:
    • slotID: String — 槽位ID
    • itemStack: ItemStack — 物品
  • 返回值:无
  • 调用示例
axPlayer.setSlotItemStackOnlyClient("preview_slot", previewItem);

removeSlotItemStackOnlyClient(slotID, startWith)

  • 仅从客户端移除槽位物品显示
  • 参数:
    • slotID: String — 槽位ID
    • startWith: boolean — 是否匹配以该ID开头的所有槽位
  • 返回值:无
  • 调用示例
axPlayer.removeSlotItemStackOnlyClient("temp_", true); // 移除所有temp_开头的槽位

getSlotItemStack(slotID)

  • 获取额外槽位中的物品
  • 参数:slotID: String — 槽位ID
  • 返回值:ItemStack? — 物品对象,可能为null
  • 调用示例
ItemStack item = axPlayer.getSlotItemStack("ring_1");

syncSlotCacheToClient()

  • 将所有槽位缓存同步到客户端,通常在玩家重新连接时使用
  • 参数:无
  • 返回值:无
  • 调用示例
axPlayer.syncSlotCacheToClient();

物品冷却

setTagCooldown(tag, time)

  • 设置物品冷却标签的冷却时间
  • 参数:
    • tag: String — 冷却标签
    • time: long — 冷却时间(毫秒)
  • 返回值:无
  • 调用示例
axPlayer.setTagCooldown("skill_1", 3000); // 3秒冷却

getTagCooldown(tag)

  • 获取物品冷却标签的剩余冷却时间
  • 参数:tag: String — 冷却标签
  • 返回值:long — 剩余冷却时间(毫秒),0表示已冷却完毕
  • 调用示例
long remaining = axPlayer.getTagCooldown("skill_1");

音效

playSoundForSelf(resourcePath, soundCategory, pitch, keepTime)

  • 为玩家自身播放音效
  • 参数:
    • resourcePath: String — 音效资源路径
    • soundCategory: String — 音效类别
    • pitch: float — 音调
    • keepTime: int — 持续时间(毫秒)
  • 返回值:无
  • 调用示例
axPlayer.playSoundForSelf("sounds/ui_click.ogg", "master", 1.0f, 1000);

其他功能

sendCustomPacket(id, data...)

  • 向玩家客户端发送自定义数据包
  • 参数:
    • id: String — 数据包ID
    • data: String... — 数据内容(可变参数)
  • 返回值:无
  • 调用示例
axPlayer.sendCustomPacket("my_plugin:update", "key1", "value1");

parseAria(code)

  • 在玩家客户端执行Aria脚本代码
  • 参数:code: String — Aria脚本代码
  • 返回值:无
  • 调用示例
axPlayer.parseAria("Chat.open(\"Hello!\")");

sendChatCard(cardID, cardData)

  • 向玩家发送聊天卡片消息
  • 参数:
    • cardID: String — 卡片配置ID
    • cardData: Map<String, String> — 卡片数据
  • 返回值:无
  • 调用示例
Map<String, String> data = new HashMap<>();
data.put("title", "任务完成");
data.put("reward", "100金币");
axPlayer.sendChatCard("quest_complete", data);

On this page

ArcartXPlayer
公开属性
模型管理
setModel(modelID, scale)
removeModel()
setDefaultModel(scale)
setCustomModel(modelID, scale)
tryModel(modelID, scale, time)
自定义玩家宿主与完整外观
setPlayerHost(modelID, profileId, scale)
getAppearance() / getAppearanceRevision()
setAppearance(appearance)
updateAppearance(update)
supportsCustomPlayerHost()
addExtraModel(locator, modelID)
removeExtraModel(locator)
clearExtraModels()
时装管理
equipSuit(modelID, hide)
equipCostume(slot, modelID, hide)
removeCostume(slot)
clearCostume()
equipCostume(slotId, modelID, binding, hide)
PlayerHostCostume(model, binding, hide, renderRoots)
removeCostume(slotId)
动画控制
setAnimationPack(packId)
clearAnimationPack()
playFirstPersonAnimationByTime(animation, speed, keepTime)
playFirstPersonAnimationByCountOf(animation, speed, count)
setState(controller, state)
setState(controller, state, speed)
setState(controller, state, speed, moveBreak)
setController(controller)
飞行状态
updateFlyingState()
相机控制
setThirdPerson(enable)
setViewLock(enable)
setViewLockMode(mode)
setCameraFromPreset(id)
setCameraLocation(offsetX, offsetY, offsetZ, freeView)
startSceneCamera(sceneId)
stopSceneCamera()
着色器与天空盒
enableShader(shader)
disableShader()
setSkyTexture(texturePath, forceNoCloud)
clearSkyTexture()
setClientTitle(text)
特效
spawnBedrockParticle(identifier, particleID, effectPosition)
addWorldTexture(id, builder, effectPosition)
removeWorldTexture(id)
playBlockAnimation(x, y, z, animation, speed, transitionTime, keepTime)
spawnHammerCrackEffect(x, y, z, radius, depth, in, keep, out, mode)
伤害显示
addDamageDisplay(damageDisplayConfigId, x, y, z, damage)
addDamageDisplay(damageDisplayConfigId, target, damage)
路标管理
addWayPoint(id, title, waypointConfigId, x, y, z)
deleteWayPoint(id, regex)
clearWayPoint()
额外槽位管理
setSlotItemStack(slotID, itemStack)
setSlotItemStackOnlyClient(slotID, itemStack)
removeSlotItemStackOnlyClient(slotID, startWith)
getSlotItemStack(slotID)
syncSlotCacheToClient()
物品冷却
setTagCooldown(tag, time)
getTagCooldown(tag)
音效
playSoundForSelf(resourcePath, soundCategory, pitch, keepTime)
其他功能
sendCustomPacket(id, data...)
parseAria(code)
sendChatCard(cardID, cardData)