LogoArcartX Doc

玩家事件

服务端玩家状态变化事件

玩家事件

  • 由服务端玩家状态变化触发的事件,与客户端事件不同,这些事件在服务端逻辑中产生。

PlayerAreaEnterEvent

  • 玩家进入 ArcartX 区域时触发
  • 属性:
    • player: Player — 玩家
    • area: Area — 进入的区域对象
  • 可取消:否
  • 调用示例
@EventHandler
public void onAreaEnter(PlayerAreaEnterEvent event) {
    String areaName = event.getArea().getName();
    // 玩家进入了区域
}

PlayerAreaLeaveEvent

  • 玩家离开 ArcartX 区域时触发
  • 属性:
    • player: Player — 玩家
    • area: Area — 离开的区域对象
    • newArea: Area? — 新进入的区域(如果直接从一个区域进入另一个区域),可能为 null
  • 可取消:否
  • 调用示例
@EventHandler
public void onAreaLeave(PlayerAreaLeaveEvent event) {
    Area newArea = event.getNewArea();
    if (newArea != null) {
        // 玩家从一个区域直接进入了另一个区域
    } else {
        // 玩家离开区域进入了无区域地带
    }
}

PlayerExtraSlotUpdateEvent

  • 玩家额外槽位物品更新时触发(通过 ArcartXPlayer.setSlotItemStack 设置时)
  • 属性:
    • player: Player — 玩家
    • slotID: String — 槽位 ID
    • itemStack: ItemStack — 更新后的物品
  • 可取消:否
  • 调用示例
@EventHandler
public void onSlotUpdate(PlayerExtraSlotUpdateEvent event) {
    String slotID = event.getSlotID();
    ItemStack item = event.getItemStack();
    // 槽位物品已更新
}

PlayerModelUpdateEvent

  • setModel、setDefaultModel 或 setCustomModel 成功提交后触发;这是更新通知,不可取消
  • setPlayerHost、setAppearance、updateAppearance 使用下方完整外观事件,不额外派发此通知
  • 属性:
    • player: Player — 玩家
    • modelID: String — 新模型 ID
  • 可取消:否
  • 调用示例
@EventHandler
public void onModelUpdate(PlayerModelUpdateEvent event) {
    String modelID = event.getModelID();
    // 玩家模型已更新
}

PlayerAnimationPackChangeEvent

  • 玩家动画包变更前触发,可通过取消阻止变更
  • 属性:
    • player: Player — 玩家
    • packId: String — 即将设定的动画包 ID,空串表示取消动画包
  • 可取消:是
  • 调用示例
@EventHandler
public void onAnimationPackChange(PlayerAnimationPackChangeEvent event) {
    String packId = event.getPackId();
    if (packId.isEmpty()) {
        // 即将取消玩家的动画包
    }
    // event.setCancelled(true); // 阻止本次变更
}

PlayerCostumeChangeEvent

  • 玩家时装变更前触发,可通过取消阻止变更
  • 保留原套装、枚举槽和 clearCostume 方法的事件行为;动态字符串槽重载不派发此事件
  • 属性:
    • player: Player — 玩家
    • type: PlayerCostumeChangeEvent.Type — 变更类型,取值 EQUIP_SUIT(穿全套装)、EQUIP_SLOT(穿某槽)、REMOVE_SLOT(脱某槽)、CLEAR(脱下全部)
    • slot: ArcartXPlayer.CostumeSlot? — 涉及的时装槽位;EQUIP_SUIT 与 CLEAR 时为 null
    • modelID: String? — 涉及的模型ID;REMOVE_SLOT 与 CLEAR 时为 null
    • hide: boolean — 是否隐藏对应部位
  • 可取消:是
  • 调用示例
@EventHandler
public void onCostumeChange(PlayerCostumeChangeEvent event) {
    if (event.getType() == PlayerCostumeChangeEvent.Type.EQUIP_SUIT) {
        String modelID = event.getModelID();
        // 玩家即将穿上整套时装
    }
    // event.setCancelled(true); // 阻止本次变更
}

PlayerVariantChangeEvent

  • 玩家模型变体变更前触发,可通过取消阻止变更
  • 属性:
    • player: Player — 玩家
    • variant: ArcartXPlayer.PlayerModelVariant — 即将设定的模型变体
  • 可取消:是
  • 调用示例
@EventHandler
public void onVariantChange(PlayerVariantChangeEvent event) {
    ArcartXPlayer.PlayerModelVariant variant = event.getVariant();
    // 玩家即将切换模型变体
    // event.setCancelled(true); // 阻止本次变更
}

PlayerAnimationPackChangeEvent、PlayerCostumeChangeEvent、PlayerVariantChangeEvent 均在状态变更前触发,且可取消。原方法的这些事件通过后,还会派发 PlayerAppearanceChangeEvent;取消任一事件都不会提交外观。

PlayerAppearanceChangeEvent

完整外观校验通过、实际提交前触发,包名为 priv.seventeen.artist.arcartx.event.player。用于统一检查主体模型、宿主配置、动态时装槽、动画包和旧时装。

  • 属性:
    • player: Player — 玩家
    • previous: PlayerAppearance — 修改前的只读完整外观
    • appearance: PlayerAppearance — 即将提交的只读完整外观
  • 可取消:是;取消后模型、槽位、宿主配置和动画包均不改变
  • 调用示例
@EventHandler
public void onAppearanceChange(PlayerAppearanceChangeEvent event) {
    if (event.getAppearance().getProfileId().equals("restricted")) {
        event.setCancelled(true);
    }
}

setPlayerHost、setAppearance、updateAppearance 和动态字符串槽修改仅派发此事件。updateAppearance 回调结束后只派发一次,不逐字段触发旧领域事件。输入不合法时先抛出 IllegalArgumentException,不派发事件;完整外观及是否明确选择新宿主均未改变、且没有临时试穿时,新方法直接成功,不派发事件。临时试穿期间提交相同的保存外观仍会派发本事件;接受后结束试穿,取消则继续试穿。

旧时装、变体、动画包方法先派发各自的可取消事件,再派发本事件,最后统一提交。setModel 提交前派发本事件、成功后派发 PlayerModelUpdateEvent;setDefaultModel / setCustomModel 的顺序为旧变体事件、本事件、提交、模型更新通知。

tryModel 开始时会以临时 body-only 外观派发本事件,取消可阻止试穿;其 previous 为当前显示外观,包含尚未结束的试穿。定时恢复保存外观不派发本事件。getAppearance 始终读取保存的外观,不读取试穿投影。

事件中的外观及集合不可修改。请取消当前请求或在事件结束后另行安排更新,不要在本事件处理函数中再次提交外观;递归提交会被拒绝。

On this page