API Reference

Stable Public API และ Connector API สำหรับเชื่อม resource ภายนอกกับ nX Police

Public API

สำหรับ Integration ภายนอกให้ใช้ Export ที่ระบุในหน้านี้ และแนะนำตรวจ GetApiVersion() ก่อนใช้ API ที่ขึ้นกับ Version

Client Stable API#

Export	Return	ใช้ทำอะไร
`GetApiVersion()`	number	Public API version
`CanUseKeyWhileCuffed(input)`	allowed/reason	ตรวจ Key Mapping หรือ FiveM Control ID ว่าอยู่ใน Cuff Whitelist หรือไม่
`CanOpenUi(uiName, input?)`	allowed/reason	ตรวจ policy เปิด UI รวมสถานะตายและ Cuff Whitelist; อาจคืน `dead_ui_blocked` หรือ `cuffed_ui_blocked`
`CanOpenUiWhileCuffed(uiName, input?)`	allowed/reason	API compatibility สำหรับตรวจ Cuff Whitelist โดยเฉพาะ
`AuthorizeCuffUiFromKey(uiName, input)`	allowed/reason	อนุญาต UI session จาก input ที่อยู่ใน Cuff Whitelist
`SetCuffUiActive(uiName, visible, input?)`	success/status	แจ้งสถานะ UI ภายนอก; ตอนเปิดสามารถส่ง input ที่ใช้เปิดเพื่อขอสิทธิ์ในครั้งเดียว
`Notify(message, kind?, duration?)`	success/reason	Toast ผ่าน Notification Provider กลาง
`OpenMenu(pageOrOptions, options?)`	true,status / false,reason	เปิด Police Command
`ToggleMenu(...)`	success/status	เปิดหรือปิด Police Command
`CloseMenu()`	boolean	ปิด Police Command
`RefreshMenu()`	success/status	Refresh เมนูที่เปิดอยู่
`OpenQuickMenu()`	success/status	เปิด Quick Menu พร้อมตรวจ Police/On-duty
`CloseQuickMenu()`	boolean	ปิด Quick Menu
`OpenReportInbox()` / `CloseReportInbox()`	status / boolean	ควบคุม Report Inbox
`CloseAllUi()`	boolean	ปิด UI ของ nX Police ที่กำลังเปิดอยู่ทั้งหมด

รองรับ overview, latest, cases, jail, manage, settings, report และ aliases home/dashboard/dispatch/case/management/reports

lua

local ok, status = exports['nX_police']:OpenMenu('cases')

exports['nX_police']:OpenMenu({
    page = 'overview',
    selectedTargetId = 12,
    openShop = false,
    shopSource = 'overview'
})

เหตุผลที่อาจคืน เช่น invalid_page, unavailable, not_police; Quick Menu อาจคืน off_duty

Client UI / Police State#

Export	ชนิด
`IsMenuOpen`, `IsMenuOpening`, `IsQuickMenuOpen`, `IsReportOpen`, `IsAgencyShopOpen`, `IsCurfewOpen`, `IsJailCardOpen`, `IsAnyUiOpen`, `IsNuiReady`	boolean
`GetActiveMenuPage()`, `GetNuiFocusOwner()`	string
`GetUiState()`	table สถานะ UI
`IsPolice()`, `IsOnDuty()`, `HasPoliceAccess()`, `IsCuffed()`, `IsJailed()`	boolean
`GetPoliceState()`	table สถานะตำรวจ/เวร/กุญแจมือ/คุก
`GetState()`	`{apiVersion, police, ui}`

Server Stable API#

Export	ใช้ทำอะไร
`GetApiVersion()`	Public API version
`NotifyPlayer(source, message, kind?, duration?)`	Notify ผู้เล่นผ่าน provider กลาง
`IsPolice(source)`, `IsOnDuty(source)`, `IsCuffed(source)`	อ่านสถานะผู้เล่น
`HasAbility(source, ability)`	ตรวจ RankPermissions โดยไม่ต้องเดาจาก grade
`GetPoliceState(source)` / `GetOfficerState(source)`	ข้อมูล Officer
`GetPoliceSources(onDutyOnly?)`	array ของ server ID
`GetPoliceCount(onDutyOnly?)`	จำนวนตำรวจ

lua

if exports['nX_police']:HasAbility(source, 'search') then
    -- authorized integration
end

local sources = exports['nX_police']:GetPoliceSources(true)
local count = exports['nX_police']:GetPoliceCount(true)

Customer Function Hooks (ไม่ใช่ Export)#

จุดเชื่อม lifecycle ที่ลูกค้าตั้งเองอยู่ใน config/functions/ และไม่ใช่ Public Export:

Functions.Client.DepartmentAnnouncement(data) — เปลี่ยน UI ประกาศหน่วยงาน/ประกาศภายใน; return true เพื่อใช้ UI ภายนอก หรือ false/error เพื่อ fallback กลับ UI เดิม
Functions.Client.OnDutyChanged(onDuty, data)
Functions.Server.OnDutyChanged(source, xPlayer, onDuty, data)

DepartmentAnnouncement เปลี่ยนเฉพาะ Presentation ฝั่ง Client และไม่เปลี่ยน Server recipient/permission authority. ส่วน Duty hooks ทั้งสองทำงานเฉพาะหลังการกดเข้า/ออกเวรผ่าน nX Police สำเร็จและ Server ยืนยัน transition แล้ว ไม่ถูกเรียกจาก login/reconnect/restart/passive sync หรือการอ่าน IsOnDuty().

อย่าใช้ hook แทน Server permission

Hook มีไว้เชื่อม resource ภายนอก ไม่ได้เปลี่ยน authority ของ nX Police. งานที่เกี่ยวกับเงิน ของ หรือสิทธิ์ต้องตรวจ Server-side ตาม Public API/ระบบเดิม

Dispatch#

ReportCrime มีทั้ง Client/Server และ DispatchCrime เป็น alias ใช้ประเภทเหตุและข้อมูลตาม Config ที่เปิดใช้งาน

lua

-- Client
exports['nX_police']:ReportCrime('cement', { details = 'พบการขโมยวัสดุก่อสร้าง' })

-- Server
exports['nX_police']:ReportCrime('cement', { source = playerId, details = 'รายละเอียดเหตุ' })

Search / Evidence / Vehicle Storage Connector API#

Export	Side	ใช้เมื่อ
`CanSearchType`	Server	ตรวจ Search Type
`CanSearchTarget`	Server	ตรวจ officer/target ก่อน search
`DepositSeizedItem`	Server	ฝากของกลางทั่วไปหลังระบบต้นทาง remove สำเร็จ
`ShouldRouteSearchSeizure`	Server	ตรวจว่ารายการยึดจาก Search ควรเข้าหน่วยงานหรือไม่
`DepositSearchSeizure`	Server	ฝากของกลางจาก Search เข้า Safe/Bank
`RecordSeizedEvidence`	Server	บันทึกหลักฐานหลังยึดสำเร็จ
`CanVehicleSeizure`	Server	ตรวจ officer/plate/owner/item ก่อนยึดจากท้ายรถ
`DepositVehicleSeizure`	Server	ฝากของจาก Vehicle Storage เข้าหน่วยงาน

ลำดับการเชื่อมสำคัญ

Inventory/Vehicle Storage ต้องนำของออกสำเร็จก่อนเรียก API ฝากของกลางหรือบันทึกหลักฐาน เพื่อให้ข้อมูลตรงกับของจริง

Jail / Discord / UI Coordination#

UseCuffUnlockItem(sourceId) — ใช้ Item ปลดกุญแจมือตาม Config.Cuff
CutJailGps(sourceId) — ใช้ GPS Cutter ตาม Config.Jail.Escape.GpsCutter
DiscordLog(payload) — Client/Server logging boundary; ข้อมูลสำคัญควรส่งจาก Server
DiscordLogStats() — ดูสถานะ Discord Log
SetExternalHotbarVisible, SetToastReservedZone, PulseToastReservedZone — Client UI coordination

Inventory Connector-level API#

สำหรับผู้เขียน compat เท่านั้น ถ้าใช้ nc_inventory ตาม default ไม่ต้องเรียกเอง:

Client: GetInventoryDriver, RoutePoliceSearchSeizure, IsPoliceSafeSecondary, PoliceSafeTransfer, HandleInventorySecondaryAction, HandleInventoryOpened, HandleInventoryClosed

Server: GetInventoryDriver, InventorySafeAvailable