> For the complete documentation index, see [llms.txt](https://ak-scripts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ak-scripts.gitbook.io/docs/yi-lai/markdown/ui-mo-kuai-dao-chu/ji-neng-tiao-skillbar.md).

# 技能条（Skillbar）

## 🎯 Skillbar（技能条）模块导出文档

### 📋 概述

Skillbar 模块是 ak-lib 的技能条小游戏系统，支持难度控制、成功判定、多轮挑战、自定义按键等功能。

### 🚀 导出方式

#### 客户端

```lua
exports['ak-lib']:Skillbar(data, callback)
exports['ak-lib']:OpenSkillbar(data, callback)
exports['ak-lib']:CloseSkillbar()
exports['ak-lib']:IsSkillbarActive()
exports['ak-lib']:GetCurrentSkillbar()
```

#### 服务端

```lua
exports['ak-lib']:Skillbar(target, data, callback)
exports['ak-lib']:OpenSkillbar(target, data, callback)
```

### 📖 可用导出

#### 客户端

| 导出                             | 说明        | 参数                                    | 返回值                   |
| ------------------------------ | --------- | ------------------------------------- | --------------------- |
| `Skillbar(data, callback)`     | 显示技能条     | `data` (table), `callback` (function) | boolean               |
| `OpenSkillbar(data, callback)` | 显示技能条（别名） | `data` (table), `callback` (function) | boolean               |
| `CloseSkillbar()`              | 关闭技能条     | -                                     | boolean               |
| `IsSkillbarActive()`           | 检查技能条是否活动 | -                                     | boolean, table (当前数据) |
| `GetCurrentSkillbar()`         | 获取当前技能条数据 | -                                     | table / nil           |

#### 服务端

| 导出                                     | 说明             | 参数                                                       | 返回值 |
| -------------------------------------- | -------------- | -------------------------------------------------------- | --- |
| `Skillbar(target, data, callback)`     | 向指定玩家显示技能条     | `target` (number), `data` (table), `callback` (function) | nil |
| `OpenSkillbar(target, data, callback)` | 向指定玩家显示技能条（别名） | `target` (number), `data` (table), `callback` (function) | nil |

### 💡 使用示例

#### 客户端：基础使用

```lua
-- 基础技能条
exports['ak-lib']:Skillbar({
    difficulty = "medium",  -- 难度：easy/medium/hard/veryhard
    rounds = 3,              -- 总回合数
    successNeed = 2           -- 需要成功几回合
}, function(result)
    if result == true then
        print("技能条挑战成功！")
    elseif result == false then
        print("技能条挑战失败！")
    else
        print("技能条已取消")
    end
end)

-- 自定义难度（精确控制）
exports['ak-lib']:Skillbar({
    size = 15,   -- 目标区域大小（百分比）
    speed = 50,  -- 移动速度
    rounds = 3,
    successNeed = 2
}, function(result)
    -- ...
end)

-- 自定义输入键（多个键随机选择）
exports['ak-lib']:Skillbar({
    difficulty = "hard",
    rounds = 3,
    successNeed = 2,
    keys = { 'KeyE', 'KeyF', 'KeyG' }  -- 每回合随机选择一个键
}, function(result)
    -- ...
end)

-- 固定使用单个键
exports['ak-lib']:Skillbar({
    difficulty = "medium",
    rounds = 2,
    successNeed = 1,
    key = 'KeyE'  -- 固定使用 E 键
}, function(result)
    -- ...
end)

-- 容错模式（允许一次失败）
exports['ak-lib']:Skillbar({
    difficulty = "hard",
    rounds = 3,
    successNeed = 2,
    allowRetry = true  -- 允许失败一次后重试
}, function(result)
    -- ...
end)

-- 渐进式难度（每回合变难）
exports['ak-lib']:Skillbar({
    difficulty = "medium",
    rounds = 5,
    successNeed = 3,
    progressive = true  -- 每回合难度递增
}, function(result)
    -- ...
end)

-- 成功/失败特效
exports['ak-lib']:Skillbar({
    difficulty = "medium",
    rounds = 3,
    successNeed = 2,
    fxSuccess = true,  -- 成功时播放特效
    fxFail = true      -- 失败时播放特效
}, function(result)
    -- ...
end)

-- 自定义成功判定阈值
exports['ak-lib']:Skillbar({
    difficulty = "medium",
    rounds = 3,
    successNeed = 2,
    successThreshold = 0.8  -- 80% 重叠才算成功（默认 0.8）
}, function(result)
    -- ...
end)

-- 检查技能条是否活动
if exports['ak-lib']:IsSkillbarActive() then
    print("技能条正在运行")
end

-- 关闭技能条
exports['ak-lib']:CloseSkillbar()
```

#### 服务端：向玩家发送技能条

```lua
-- 向指定玩家显示技能条
exports['ak-lib']:Skillbar(source, {
    difficulty = "hard",
    rounds = 5,
    successNeed = 3
}, function(result)
    if result == true then
        print("玩家成功完成技能条")
    elseif result == false then
        print("玩家失败技能条")
    else
        print("玩家取消了技能条")
    end
end)
```

### 📝 参数说明

#### data 参数（table）

| 字段                 | 类型      | 说明                                                   | 必需 | 默认值                                  |
| ------------------ | ------- | ---------------------------------------------------- | -- | ------------------------------------ |
| `difficulty`       | string  | 难度预设：`'easy'` / `'medium'` / `'hard'` / `'veryhard'` | 否  | `Config.Skillbar.DefaultDifficulty`  |
| `size`             | number  | 目标区域大小（百分比，越小越难）                                     | 否  | 根据 difficulty                        |
| `speed`            | number  | 移动速度（越大越快）                                           | 否  | 根据 difficulty                        |
| `rounds`           | number  | 总回合数                                                 | 否  | `Config.Skillbar.DefaultRounds`      |
| `successNeed`      | number  | 需要成功几回合                                              | 否  | `Config.Skillbar.DefaultSuccessNeed` |
| `successThreshold` | number  | 成功判定阈值（0.0 \~ 1.0）                                   | 否  | `Config.Skillbar.SuccessThreshold`   |
| `key`              | string  | 固定输入键                                                | 否  | `'Space'` 或 `'Enter'`                |
| `keys`             | table   | 输入键列表（随机选择）                                          | 否  | `['Space', 'Enter']`                 |
| `allowRetry`       | boolean | 是否允许重试（容错模式）                                         | 否  | `false`                              |
| `progressive`      | boolean | 是否渐进式难度                                              | 否  | `false`                              |
| `fxSuccess`        | boolean | 成功时播放特效                                              | 否  | `false`                              |
| `fxFail`           | boolean | 失败时播放特效                                              | 否  | `false`                              |
| `position`         | string  | 位置（九宫格）                                              | 否  | `Config.Skillbar.Position`           |

#### 难度预设（difficulty）

* `'easy'` - 简单：区域大，速度慢
* `'medium'` - 中等：平衡挑战（默认）
* `'hard'` - 困难：区域小，速度快
* `'veryhard'` - 极难：极小区域，极快速度

#### 输入键（key / keys）

支持的按键：

* `'Space'` - 空格键
* `'Enter'` - 回车键
* `'KeyE'` - E 键
* `'KeyF'` - F 键
* 其他键盘按键...

**注意：** 使用 `key` 固定使用一个键，使用 `keys` 数组每回合随机选择一个键。

#### callback 回调函数

```lua
function(result)
    -- result: true / false / nil
    -- true: 挑战成功
    -- false: 挑战失败
    -- nil: 玩家取消（按 ESC）
end
```

#### 位置选项（position）

支持九宫格位置（默认：`'bottom-center'`）：

* `'top-left'` - 左上角
* `'top-center'` - 顶部中间
* `'top-right'` - 右上角
* `'middle-left'` - 左边中间
* `'middle-center'` - 屏幕中央
* `'middle-right'` - 右边中间
* `'bottom-left'` - 左下角
* `'bottom-center'` - 底部中间（默认）
* `'bottom-right'` - 右下角

### ⚠️ 注意事项

1. **同时只能显示一个**：Skillbar 同时只能显示一个，新的会替换旧的。
2. **成功判定**：玩家需要在移动滑块到达目标区域时按下指定键，重叠度达到 `successThreshold` 才算成功。
3. **多回合挑战**：`rounds` 指定总回合数，`successNeed` 指定需要成功几回合才能通过挑战。
4. **容错模式**：`allowRetry = true` 时，玩家失败一次后可以重试该回合。
5. **渐进式难度**：`progressive = true` 时，每回合难度会递增（区域变小，速度变快）。
6. **自定义难度**：可以使用 `size` 和 `speed` 精确控制难度，会覆盖 `difficulty` 预设值。
7. **服务端调用**：服务端调用时需要提供 `target` 参数（玩家服务器 ID）。
8. **取消技能条**：玩家可以按 ESC 键取消技能条，回调函数会收到 `nil`。

### 🔗 相关文档

* 技能条说明


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ak-scripts.gitbook.io/docs/yi-lai/markdown/ui-mo-kuai-dao-chu/ji-neng-tiao-skillbar.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.