交互系统（开发者指南）

交互系统允许开发者完全自定义玩家与商店的交互方式。

在 6.2.0.11 版本，这个系统已重新设计为：

模块化
可扩展
线程安全
完全可以通过第三方附加组件自定义

本教程将通过以下方式带你了解：

什么是“交互系统”
获取 InteractionManager
理解 InteractionType
理解 InteractionBehavior
注册自定义交互
最佳实践

概览

互动系统由三个主要部分组成：

组件	目的
`InteractionType`	描述发生什么类型的点击 (站立、潜行、左键点击、告示牌、商店方块等)
`InteractionBehavior`	描述触发该类型时应发生什么操作
`InteractionManager`	管理交互与行为的中心注册条目

这种程度的划分使得开发者可以：

添加新的点击类型
添加新行为
覆盖现有行为
在不修改核心代码的情况下对 QuickShop 进行功能扩展

获取 InteractionManager

首先，你需要获取 InteractionManager 实例。

InteractionManager manager = api.getInteractionManager();

直接使用插件实例，则：

InteractionManager manager = QuickShop.getInstance().getInteractionManager();

获取后，你可以：

注册新的互动类型
注册新行为
覆盖现有行为

理解 InteractionType

InteractionType 表示一个玩家如何与商店互动。

例如：

STANDING_LEFT_CLICK_SIGN
STANDING_RIGHT_CLICK_SHOPBLOCK
SNEAKING_LEFT_CLICK_CONTAINER
等等。

每个 InteractionType 都定义：

玩家状态（正常站立/潜行状态）
点击类型（左键/右键）
点击目标（告示牌/商店方块/容器本身）

InteractionTypes 不会定义行为本身——它们定义的只是触发器。

理解 InteractionBehavior

InteractionBehavior 定义了触发交互时发生的内容。

内置行为示例：

TRADE_INTERACTION
TRADE_UI
CONTROL_PANEL
CONTROL_PANEL_UI
NONE

一个行为：

能执行逻辑
可能打开界面
可能在聊天栏显示菜单
可能直接交易物品
可以取消或修改流程

这种分离使得多种交互类型可以复用不同行为。

注册自定义交互

你可以注册两种：

其一，自定义的 InteractionType
其二，自定义的 InteractionBehavior

创建自定义 InteractionBehavior

创建一个实现 InteractionBehavior 的类。

示例：

public class MyTradeBehavior implements InteractionBehavior {

    @Override
    public String getKey() {
        return "MY_CUSTOM_TRADE";
    }

    @Override
    public void execute(InteractionClick click) {
        Player player = click.getPlayer();
        Shop shop = click.getShop();

        player.sendMessage("你触发了自定义交互！");

        // 在这里插入你的自定义逻辑。
    }
}

然后注册：

InteractionManager manager = api.getInteractionManager();
manager.behavior(new MyTradeBehavior());

你就成功注册了一个可以使用的行为。

创建自定义 InteractionType

如果你想要引入新的触发定义，你也可以注册自定义交互类型。

示例：

public class MyCustomInteraction implements InteractionType {

    @Override
    public String getKey() {
        return "STANDING_DOUBLE_CLICK_SIGN";
    }

    @Override
    public boolean matches(InteractionClick click) {
        // 检测这个交互的自定义逻辑
        return click.isStanding()
                && click.isSign()
                && click.isDoubleClick();
    }
}

manager.interaction(new MyCustomInteraction());

绑定类型到行为

内部的 InteractionManager 会根据配置和注册顺序将互动类型映射为行为。

注册行为后：

它可以在 interaction.yml 中引用
或者，添加进其他代码

示例 interaction.yml 用法：

STANDING_LEFT_CLICK_SIGN: MY_CUSTOM_TRADE

InteractionClick 对象

执行行为时，你会收到一个 InteractionClick 对象。

它会提供：

getPlayer()
getShop()
getLocation()
isSneaking()
isSign()
isShopBlock()
等等。

这可以为安全执行提供充分的信息。

进阶：覆盖内置行为

如果你注册的行为键名与现存的相同，那么可以覆盖它。

⚠️谨慎行事——你正在改变核心功能。

最佳做法

坚持使用不重复键名

防止名称重合：

MYPLUGIN_CUSTOM_BEHAVIOR

保持行为轻量

不要用这些东西阻塞主线程：

大量数据库调用
文件读写
网络调用

必要时请采用异步任务。

灵活运用权限

总是有效：

if (!player.hasPermission("myplugin.use")) {
    return;
}

非必要不硬覆写

与其覆写原有行为，不如试着将其拓展。

示例：完全最小实现

public class ExampleAddon {

    public void register(QuickShopAPI api) {

        InteractionManager manager = api.getInteractionManager();

        manager.behavior(new MyTradeBehavior());
        manager.interaction(new MyCustomInteraction());
    }
}

总结

交互系统旨在：

完全扩展性
将触发器与行为分离
便于第三方开发者简单集成

返回 InteractionManager：

InteractionManager manager = api.getInteractionManager();

您可以完全控制商店如何响应玩家动作。

概览