- 版权类型
- 原创
- 插件中文名称
- nso交互
- 插件英文名称
- nsoInteractions
- 原帖地址
- #
- 支持的核心（服务端）
- Spigot
- Paper
- Purpur
- PufferFish
- Leaves
- 语言支持
- 中文（简体）
- 适配版本（Java）
- 1.21
[MD]
# nsoInteractions 插件使用手册
nsoInteractions 是一款高度可定制的 Minecraft 对话系统插件，支持打字机效果、多分支剧情、条件判断、PAPI 变量以及自定义音效模板。
游戏版本我只测试了1.21.8，应该可以支持很多版本，但是我没有测试其他版本，如果有问题欢迎反馈。
## 1. 指令与权限
| 指令 | 描述 | 权限 |
| :--- | :--- | :--- |
| `/nsoi help` | 显示帮助菜单 | `nsoi.use` |
| `/nsoi reload` | 重载配置文件和对话数据 | `nsoi.admin` |
| `/nsoi start <对话ID> [玩家]` | 为自己或指定玩家开启对话 | `nsoi.admin` |
| `/nsoi list` | 列出所有已加载的对话 ID | `nsoi.admin` |
## 2. 核心配置文件
### config.yml
全局设置与音效模板。
- **sound-templates**: 定义打字机音效模板。
- `speed`: 字符显示速度（刻/字符）。
- `sound`: 播放的声音 (Bukkit Sound 枚举)。
- `volume`: 音量。
- `pitch`: 音调。
- `random-pitch`: 是否开启随机音调抖动。
- `mode`: 播放模式 (`PER_CHARACTER` 每个字都响, `ONCE` 每行只响一次)。
- **scoreboard**: 计分板选项前缀。
- **animations**: 动态文本设置（支持在对话中使用 `<anim:ID>`）。
### messages.yml
插件所有系统提示消息的软编码文件，支持颜色代码和 PAPI。
## 3. 对话文件配置 (data/*.yml)
对话文件放置在 `plugins/nsoInteractions/data/` 目录下。
### 根节点配置
- `id`: 对话的唯一标识符。
- `start_node`: 对话开始的节点 ID (支持固定 ID、条件判断或随机选择)。
- `allow_movement`: (true/false) 对话时是否允许移动。
- `timeout`: 对话超时自动关闭时间（秒）。
### 对话配置示例
```yaml
id: "example_dialog"
# 开始节点设置 (支持多样化选择)
# 方式 1: 简单字符串 (固定开始节点)
# start_node: "greeting"
# 方式 2: 条件判断 (按顺序匹配第一个满足条件的节点)
start_node:
options:
- node: "special_greeting"
condition: "%player_has_permission:vip% == true"
- node: "standard_greeting"
condition: "%player_level% >= 10"
default: "greeting" # 所有条件都不满足时的回退节点
# 方式 3: 随机开始
# start_node:
# random: true
# options:
# - node: "random_1"
# - node: "random_2"
# - node: "random_3"
allow_movement: false
timeout: 60
```
### 节点 (Nodes) 配置详解
每个节点代表对话的一个画面：
```yaml
nodes:
node_id:
# 标题设置（支持字符串或列表，列表会逐行显示）
title: "&6&l大标题"
# 小标题设置（承载主要对话内容，支持打字机效果）
subtitle:
- "&f这是第一行内容..."
- "&f这是第二行内容..."
# 调用的音效模板 ID (对应 config.yml 中的配置)
sound-template: "default"
# BossBar 设置
bossbar:
text: "&b进度展示"
color: "BLUE" # PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE
style: "SOLID" # SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20
progress: 50 # 0 到 100
# 执行动作（进入节点时触发）
actions:
- "console: give {player} diamond 1" # 控制台指令
- "command: me 感觉很好" # 玩家指令
- "sound: ENTITY_EXPERIENCE_ORB_PICKUP 1.0 1.0" # 播放声音
# 选项设置
options:
- text: "&a选择分支 A"
next: "next_node_a"
# 执行动作（点击此选项时触发）
actions: #此处也可以使用action，免得写一堆无用节点
- "console: eco take {player} 100"
- "sound: ENTITY_EXPERIENCE_ORB_PICKUP 1.0 1.0"
# 控制选项是否显示（可见性）
# 若不满足此条件，选项直接隐藏
display-condition: "%player_level% >= 5"
# 控制跳转逻辑（可用性/分支逻辑）
# 1. 若不满足此条件且未配置 else-next，选项会隐藏
# 2. 若不满足此条件且配置了 else-next，选项可见，但点击后跳转至 else-next
condition: "%player_level% >= 10"
else-next: "fail_node"
- text: "&c返回"
next: "greeting"
```
## 4. 进阶功能
### 条件判断 (Condition)
支持 PAPI 变量和逻辑运算符：`==`, `!=`, `>=`, `<=`, `>`, `<`。
| 配置项 | 作用阶段 | 逻辑效果 | 适用场景 |
| :--- | :--- | :--- | :--- |
| **display-condition** | 渲染前过滤 | 不满足时选项直接隐藏，玩家完全不可见。 | 职业/等级/任务进度的硬性前置要求。 |
| **condition** | 逻辑判定 | 1. 未设 `else-next`：不满足时隐藏。<br>2. 已设 `else-next`：不满足时**依然可见**，点击跳转至失败节点。 | 制作“由于钱不够点不开”或“尝试失败”的交互逻辑。 |
**示例：**
- `"%vault_eco_balance% >= 1000"`
- `"%player_has_item:DIAMOND:5% == true"`
### 多样化开始节点 (Start Node Variety)
`start_node` 支持多种配置方式，允许根据玩家状态或随机性开启对话。
| 模式 | 配置方式 | 逻辑说明 |
| :--- | :--- | :--- |
| **固定模式** | 直接写节点 ID 字符串 | 每次对话都从该节点开始（向下兼容）。 |
| **条件模式** | 使用 `options` 列表 | 按顺序匹配第一个满足 `condition` 的节点，若都不满足则进入 `default`。 |
| **随机模式** | 设置 `random: true` | 从 `options` 列表中随机抽取一个节点开始。 |
**固定模式示例：**
```yaml
start_node: "gatekeeper"
```
**条件模式示例：**
```yaml
start_node: #不要尝试在此处添加 random: true，虽然我也不知道会发生什么
options:
- node: "vip_greeting"
condition: "%player_has_permission:vip% == true"
- node: "newbie_greeting"
condition: "%player_level% < 5"
default: "standard_greeting"
```
**随机模式示例：**
```yaml
start_node:
random: true
options:
- node: "random_1"
- node: "random_2"
```
### 动作 (Actions) 格式
- `console: <指令>`: 以控制台身份运行。
- `command: <指令>`: 以玩家身份运行（指令不带 /）。
- `sound: <声音名称> [音量] [音调]`: 播放特定音效。
### 动态文本 (Animations)
在 `title` 或 `subtitle` 中使用 `<anim:flash_red>` 可以调用 `config.yml` 中定义的动态文本效果，适用于制作闪烁的提示或动态特效。
### 内部变量 (Variables)
在 `title`、`subtitle`、`actions` 或 `condition` 中可以使用以下内部变量：
- `{player}`: 当前玩家的名称。
---
## 5. PlaceholderAPI 变量
插件提供了以下变量，可用于对话文本、计分板或其他支持 PAPI 的插件中：
| 变量 | 描述 |
| :--- | :--- |
| `%nsointeractions_dialog_id%` | 当前正在进行的对话 ID |
| `%nsointeractions_remaining_time%` | 当前对话的剩余时间（秒），若无超时限制则显示 `∞` |
[/MD]
