example
example

资源 ESX Missions 为 FiveM ESX 设计的综合任务API系统

?丁宇?

活跃的用户
高级用户
认证用户
黄金
49.00 黄金
Markdown (GitHub flavored):
# ESX Missions: 一个为 FiveM ESX 设计的综合任务系统

## 1. 引言

ESX Missions 是一个为 FiveM ESX 框架设计的强大任务系统. 它允许服务器管理员为玩家创建和管理多种多样的任务, 包括具有每日、每周和每月重置周期的任务. 该系统提供了一个用户界面, 方便玩家追踪任务进度, 并支持灵活的奖励系统.

## 2. 功能特性

*   **多样化的任务类别**: 支持多种任务类型, 如新手教程、主线剧情、支线任务、日常任务、周常任务和月常任务.
*   **自动化重置系统**: 根据可配置的时间表自动重置每日、每周和每月任务.
*   **用户界面 (NUI)**: 提供直观的用户界面, 供玩家查看可用任务、追踪进度并了解奖励.
*   **灵活的奖励系统**: 允许配置奖励, 包括游戏内货币、物品和经验值 (XP).
*   **进度持久化**: 玩家的任务进度会保存到数据库中.
*   **开发者 API**: 提供简单的客户端 API, 供其他资源更新任务状态.

## 3. 先决条件

*   [ESX Legacy](https://github.com/esx-framework/esx-legacy) (或兼容版本的 es_extended).

## 4. 安装步骤

1.  下载 `esx_missions` 资源.
2.  将 `esx_missions` 文件夹放置到您服务器的 `resources` 目录中.
3.  将 `esx_missions.sql` 文件导入到您的 MySQL 数据库中. 这将创建必需的 `user_missions` 表.
4.  在您的 `server.cfg` 文件中添加 `ensure esx_missions`.
5.  重启您的 FiveM 服务器.

## 5. 配置说明

所有主要配置均位于 `shared/config.lua` 文件中.

### 5.1. `Config.Missions`

此表定义了所有任务类别及其各自的任务.

**结构示例:**

```lua
Config.Missions = {
    ['CategoryKey'] = { -- 类别的唯一字符串键 (例如, 'daily_tasks')
        _index = 1,                             -- (整数) UI 中类别的排序顺序 (数字越小越靠前).
        icon = 'fas fa-tasks',                  -- (字符串) 类别的 Font Awesome 图标 (例如, 'fas fa-user-ninja').
        title = '每日任务',                     -- (字符串) 类别的显示标题.
        description = '完成这些任务以获得每日奖励. ', -- (字符串) 类别的描述.
        mission = {                             -- (表, 数组) 此类别中的任务列表.
            {
                icon = 'fas fa-walking',            -- (字符串) 任务的 Font Awesome 图标.
                name = 'daily_walk_distance',       -- (字符串) 任务的唯一内部名称/ID.
                title = '步行5公里',                -- (字符串) 任务的显示标题.
                description = '徒步总共行走5公里. ', -- (字符串) 任务的详细描述.
                count = 5000,                       -- (整数) 完成任务所需的目标计数或进度值 (例如, 距离的米数).
                levelRequire = 0,                   -- (整数) 开始/查看此任务所需的最低玩家等级 (0 表示无要求).
                resetType = 'daily',                -- (字符串) 重置频率: 'never' (永不), 'daily' (每日), 'weekly' (每周), 'monthly' (每月).
                -- isCompleted: (布尔值) 此状态由脚本根据玩家进度动态处理.
                reward = {                          -- (表) 任务奖励.
                    xp = 100,                       -- (整数, 可选) 经验值.
                    money = 500,                    -- (整数, 可选) 游戏内现金.
                    items = {                       -- (表, 数组, 可选) 物品奖励.
                        { name = 'water_bottle', amount = 2, label = '水瓶' } -- 'name' 是物品 ID, 'amount' 是数量, 'label' 是显示名称.
                    },
                    cars = {                        -- (表, 数组, 可选) 车辆奖励 (UI 主要显示名称).
                        { name = 'sultan', label = '苏丹跑车' } -- 'name' 是车辆模型, 'label' 是显示名称.
                    }
                },
                help = 'optional_help_event_trigger' -- (字符串, 可选) 如果存在, 可用于触发客户端事件以获取特定任务的帮助信息.
            },
            -- ... 此类别中的更多任务
        }
    },
    -- ... 更多类别
}
```

### 5.2. `Config.ResetTimes`

此表配置自动任务重置的确切时间.

**结构示例:**

```lua
Config.ResetTimes = {
  daily = { hour = 0, minute = 0 },    -- 每日在 00:00 (服务器时间) 重置.
  weekly = { weekday = 1, hour = 0, minute = 0 }, -- 每周的周一 (1=周一, 7=周日) 00:00 重置.
  monthly = { day = 1, hour = 0, minute = 0 }  -- 每月的第一天 00:00 重置.
}
```

## 6. 使用方法

### 6.1. 玩家命令

*   `/missions`: 打开任务界面.

### 6.2. 管理员/测试命令

*   `/testMission [任务类别Key] [任务名称Key] [进度数量]`: 更新特定任务的进度以进行测试.
    *   示例: `/testMission daily_tasks daily_walk_distance 500`
*   `/checkResetTimes`: 在服务器控制台显示已配置的重置时间.

## 7. API 参考

从其他资源与 `esx_missions` 交互的主要方式是通过客户端导出函数.

### 7.1. `updateMissionStatus` (客户端)

更新当前玩家任务的进度或完成状态.

**语法:**

```lua
exports['esx_missions']:updateMissionStatus(missionCategory, missionName, progress)
```

**参数:**

*   `missionCategory` (字符串): `Config.Missions` 中定义的任务类别键 (例如, `'daily_tasks'`).
*   `missionName` (字符串): 在 `Config.Missions` 中指定类别内定义的任务唯一 `name` (例如, `'daily_walk_distance'`).
*   `progress` (数字 | 布尔值):
    *   如果为 `数字`: 增加到任务当前进度的值. 系统会将此值与现有进度相加.
    *   如果为 `布尔值 (true)`: 将任务标记为完全完成, 无论其当前进度或目标 `count`如何.

**使用示例:**

```lua
-- 示例:玩家执行了推进任务进度的操作
AddEventHandler('myResource:playerWalkedSegment', function(distanceIncrement)
    -- 假设 'daily_tasks' 是一个类别, 'daily_walk_distance' 是一个任务名称
    exports['esx_missions']:updateMissionStatus('daily_tasks', 'daily_walk_distance', distanceIncrement)
end)

-- 示例:直接完成一个任务
RegisterNetEvent('myResource:playerAchievedGoal')
AddEventHandler('myResource:playerAchievedGoal', function(missionCategoryToComplete, missionNameToComplete)
    exports['esx_missions']:updateMissionStatus(missionCategoryToComplete, missionNameToComplete, true)
end)
```

## 8. 数据库结构

系统使用一个主表来存储玩家任务数据.

**表名: `user_missions`**

| 列名           | 类型          | 可为空 | 默认值                       | 描述                                        |
|----------------|---------------|------|------------------------------|-------------------------------------------------|
| `id`           | INT(11)       | 否   | AUTO_INCREMENT               | 主键.                                       |
| `identifier`   | VARCHAR(60)   | 否   |                              | 玩家的唯一标识符 (例如, license, steam).      |
| `mission_data` | LONGTEXT      | 否   |                              | 存储玩家任务进度和状态的 JSON 字符串.           |
| `last_updated` | TIMESTAMP     | 否   | `current_timestamp()` ON UPDATE `current_timestamp()` | 最后更新的时间戳.                              |

**索引:**
*   PRIMARY KEY (`id`)
*   INDEX `identifier` (`identifier`)
*   INDEX `mission_data` (`mission_data`(768)) (针对某些数据库版本对 JSON 数据的部分索引)

**约束:**
*   `mission_data` CHECK (json_valid(`mission_data`)) (确保 `mission_data` 是有效的 JSON)

## 9. 任务重置机制

任务重置系统设计稳健, 并在多个层面运行:

1.  **服务器启动时**: 资源启动时检查并执行必要的重置.
2.  **玩家登录时**: 当玩家登录时, 会根据其任务的 `resetType` 和该类型的上次重置时间检查其任务, 并在必要时进行更新.
3.  **定期检查**: 系统可能包括定期的服务器端检查, 以确保重置正确应用.

任务通过将其进度设置为 0 并将其完成状态设置为 `false` 来重置. 相关重置类型 (`daily`, `weekly`, `monthly`) 的 `lastReset` 时间戳会被更新.

## 10. 故障排除

*   **错误: "attempt to index a nil value" (通常与 `ESX` 或任务数据相关)**:
    *   确保 `es_extended` 在 `esx_missions` 之前启动.
    *   验证数据库中是否存在 `user_missions` 表及其结构是否与文档中的模式匹配.
    *   确认在 API 调用或配置中使用的 `missionCategory` 和 `missionName` 与 `Config.Missions` 中的键完全匹配.
    *   确保在进行任务交互之前, 玩家数据 (`ESX.PlayerData`) 已完全加载.
*   **任务未按预期重置**:
    *   仔细检查 `Config.ResetTimes` 的语法和逻辑时间是否正确.
    *   验证服务器时间是否准确.
    *   在服务器启动时或计划的重置时间, 检查服务器控制台是否有与重置机制相关的任何错误.

## 11. 项目结构

```
esx_missions/
├── client/                 # 客户端代码
│   ├── html/               # NUI (HTML, CSS, JS) 文件, 用于任务界面
│   │   ├── index.html
│   │   ├── style.css
│   │   └── script.js
│   └── main.lua            # 客户端 Lua 逻辑, NUI 事件处理, API 导出
├── server/                 # 服务器端代码
│   └── main.lua            # 服务器端 Lua 逻辑, 数据库交互, 任务重置处理
├── shared/                 # 共享配置
│   └── config.lua          # 共享配置 (Config.Missions, Config.ResetTimes)
├── esx_missions.sql        # 数据库表的 SQL 结构文件
├── fxmanifest.lua          # FiveM 资源清单文件
└── README.md               # 本文档
```

## 12. 贡献代码

欢迎贡献!请随时提交拉取请求 (Pull Requests) 或开启问题 (Issues) 来报告错误、请求功能或提出建议.

贡献代码时请注意:
*   遵循现有的编码风格.
*   为您的更改提供清晰的描述.
*   充分测试您的更改.

## 13. 未来增强计划 (路线图)

*   服务器端对任务开始请求的验证 (例如, 等级要求、前置任务).
*   国际化 (i18n) 支持.
*   在 NUI 中提供更精细的错误反馈.
*   支持为每个任务单独设置自定义重置时间/逻辑.

下载地址:GitHub
视频示例:需梯子
图片预览:

1747553568315.png1747553583885.png
 
后退
顶部