fivem-basics

FiveM 基础

FiveM Lua 的资源结构、fxmanifest、客户端/服务端划分、事件、导出和调试。

激活约定

当用户创建或编辑任何 FiveM 资源、fxmanifest.lua、client*.lua 或 server*.lua，询问客户端/服务端、事件或导出的工作方式，或报告需要查看服务端日志与 F8 日志才能排查的错误时，加载此技能。

硬性规则

• 清单：使用 fx_version 'cerulean' 和 game 'gta5'（或 'rdr3' / 'common'）；所有提供给客户端的文件都要放入 files。
• 使用 RegisterNetEvent 注册网络事件；仅本地事件只使用 AddEventHandler，绝不使用 RegisterNetEvent。
• 服务端处理程序从 source 读取发送者；使用 TriggerClientEvent(event, -1, ...) 广播。
• 对于跨网络传输的所有网络事件，GetInvokingResource() 都是 nil；它不是身份验证检查。应改为验证类型、范围和服务端持有的状态。
• 绝不在客户端处理金钱或物品交易；应在服务端验证并执行。
• 除非有环境保护逻辑，否则不要在 shared_scripts 中使用游戏原生函数。
• 使用 PlayerPedId()，不要使用 GetPlayerPed(-1)；使用 #(a - b)，不要使用 GetDistanceBetweenCoords。
• 优先使用 local；优先使用变量化的 Wait()，而不是固定的 Wait(0)。
• 资源名称使用下划线，不要包含空格或特殊字符。

决策关口

需求	使用方式
客户端到服务端	TriggerServerEvent(event, ...)
服务端到一个/所有客户端	TriggerClientEvent(event, playerId | -1, ...)
仅限同一侧	TriggerEvent + AddEventHandler
跨网络返回数据	使用回调（ox_lib / 框架），不要使用成对事件
单个资源内的非网络调用	使用普通函数，不要使用事件
跨资源函数	在清单中使用 exports / server_export，调用 exports.res:fn()
服务端控制台无错误但仍有问题	请用户提供 F8 客户端日志

执行步骤

1. 搭建 client/、server/、shared/ 目录和清单；阅读 rules/structure.md 和 rules/fxmanifest.md。
2. 确定每段逻辑所在的一侧（原生函数放在客户端，数据和验证放在服务端）。
3. 根据“决策关口”连接通信；将事件命名为 resource:side:action。
4. 验证每个服务端处理程序的参数；添加距离和状态检查。
5. 提供 https://docs.fivem.net/natives/ 以供查询原生函数。

输出约定

返回清单以及按客户端/服务端划分、可运行的 Lua 代码，并明确标注事件名称、验证逻辑和 source 的处理方式。

参考资料

• rules/structure.md — 作用范围、客户端/服务端分离、命名。
• rules/fxmanifest.md — 清单条目、glob 模式、最小示例。
• rules/client-server.md — 各部分的运行位置及通信方式。
• rules/events.md — 注册、触发、命名、事件与函数的区别、安全性。
• rules/exports.md — 定义和使用导出。
• rules/debugging.md — 服务端控制台与 F8 日志。
• rules/optimization.md — 局部变量、表、原生函数、循环、安全性。
• rules/reference-links.md — 官方文档和原生函数参考。

上游文档：https://docs.fivem.net/docs/