How overextended/ox_lib works
1. What this repo is
- ox_lib is a FiveM library/resource that packages reusable gameplay utilities, server/client helpers, and NUI UI components.
- It is split into three major delivery surfaces: Lua resource runtime, TypeScript npm package, and React/Vite web UI.
2. Top-level entry points
- fxmanifest.lua and init.lua define the FiveM resource bootstrap and expose the Lua library to consumers.
- The repo is organized so the same library can be consumed as:
- a FiveM resource (resource/)
- an npm package (package/)
- a browser/NUI frontend (web/)
3. Runtime boundary: client vs server vs shared
- The Lua code is explicitly divided into client.lua, server.lua, and shared.lua files under imports/.
- This separation is important architecturally: some utilities are purely client-side rendering/input, some are server-side coordination, and some are shared logic usable on both sides.
4. Core Lua utility library (imports/)
- imports/ is the primary Lua module collection.
- It contains small, composable subsystems such as:
- data structures and helpers: array, table, string, math, class, selector
- runtime coordination: callback, hook, registerHook, timer, cron, waitFor
- game-world queries: getClosest*, getNearby*, raycast, grid, zones, points
- streaming/request helpers: requestModel, requestAnimDict, requestScaleformMovie, etc.
- presentation helpers: marker, dui, scaleform, logger, print, locale
- These modules are the functional backbone of the library.
5. Resource implementation layer (resource/)
- resource/ contains the actual FiveM runtime glue that wires Lua modules to the game environment and NUI.
- Notable subareas:
- resource/interface/ for UI-related client/server bridges
- resource/locale/ for localization loading at runtime
- resource/version/ for version reporting/compatibility
- resource/vehicleProperties/ for vehicle state serialization/handling
- resource/cache/, resource/callbacks/, resource/acl/ for runtime support services
- This layer is where the abstract helpers become usable inside an active FiveM resource.
6. Client-side UI bridge
- resource/interface/client/*.lua and resource/client.lua connect gameplay code to the web UI.
- This includes flows for:
- notifications
- progress bars
- context and list menus
- radial menus
- input dialogs
- skill checks
- text UI / alerts / clipboard interactions
- The client runtime is responsible for emitting NUI messages and reacting to user interaction events.
7. Server-side services
- imports/*/server.lua and resource/interface/server/*.lua provide server-only behaviors.
- Core server responsibilities include:
- command registration (addCommand)
- server callbacks
- ACL / permissions
- locale/version services
- relaying server events to clients (triggerClientEvent)
- The server side acts as the authority for shared state and request/response logic.
8. NUI frontend (web/)
- web/ is a React + TypeScript + Vite single-page UI used as FiveM NUI.
- It contains feature-based components for:
- dialogs
- menus
- notifications
- progress indicators
- skill checks
- text UI
- debug/dev screens
- The frontend listens for NUI events, renders the requested component, and returns user actions back to Lua via fetch-based NUI calls.
9. Data flow between Lua and the web UI
- The common path is:
- gameplay code on client/server triggers an ox_lib interface helper
- the Lua bridge sends an NUI event or callback
- the web/ app renders the UI and captures user input
- the UI returns the result to Lua through a NUI callback/fetch bridge
- This bidirectional contract is central to the library’s architecture.
10. TypeScript package mirrors the runtime API
- package/ provides typed bindings and client/server/common modules for consumers who want editor support and static typing.
- It mirrors the Lua surface area conceptually:
- package/common/ for shared types/utilities such as cache, locale, hooks, zones, version
- package/client/ for client-facing features like points, streaming, vehicle properties, and interface wrappers
- package/server/ for command, callback, ACL, locale, and version utilities
- This is not just a separate app; it is the typed distribution layer for the same library.
11. Localization architecture
- locales/*.json contains many translated strings, showing that locale is a first-class cross-cutting concern.
- Locale loading exists in both Lua (imports/locale, resource/locale) and TypeScript (package/common/locale, package/server/locale), keeping text consistent across runtime layers.
12. Feature families that matter for the diagram
- The repo naturally clusters into a few major domains:
- interaction/UI: menus, dialogs, notifications, text UI, radial UI, progress, skill checks
- world querying: nearby/closest entity lookups, zones, raycasts, points
- streaming/assets: model/anim/audio/texture/weapon request helpers
- framework plumbing: callbacks, events, hooks, cache, versioning, ACL
- These are the main boxes you would want in an architecture diagram.
13. Release and packaging pipeline
- .github/workflows/release.yml and the version bump scripts indicate automated release packaging.
- The repository is built to produce distributable artifacts for both FiveM resource release and npm package release, keeping the Lua and TS surfaces in sync.
14. Practical architecture summary
- Think of ox_lib as a multi-target platform library:
- Lua provides the runtime/game integration
- React provides the interactive NUI layer
- TypeScript provides typed consumer APIs
- The main seams are client/server/shared boundaries, and the main integration channel is Lua ↔ NUI messaging.
Main entry points: init.lua Resource glue · server.lua Server runtime · index.ts Common API · client.lua Client runtime
Components 22
Lua runtime
FiveM resource bootstrap, runtime glue, and reusable Lua imports.
- fxmanifest · FiveM resource manifest and entry declaration.
fxmanifest.lua - init · Resource bootstrap that loads the Lua library.
init.lua - Resource glue · Main resource runtime wiring client, server, locale, version, cache, callbacks, and vehicle state.
resource/init.lua - Client runtime · Client-side resource entry that connects gameplay code to NUI and game APIs.
resource/client.lua - Server runtime · Server-side resource entry for authority, callbacks, ACL, and relays.
resource/server.lua - Shared imports · Common data structures, helpers, hooks, locale, timers, and query utilities.
imports/array/shared.lua - Client imports · Client-only helpers for UI, points, raycasts, streaming, markers, and controls.
imports/marker/client.lua - Server imports · Server-only helpers for commands, callbacks, cron, logging, and event relays.
imports/addCommand/server.lua - UI bridge · Lua interface layer that translates gameplay actions into NUI messages and results.
resource/interface/client/main.lua - Server services · Server-side interface services that support shared UI flows and authority checks.
resource/interface/server/progress.lua - Locales · Runtime localization loading and lookup for Lua resource execution.
resource/locale/client.lua - Versioning · Version reporting and compatibility helpers for the resource.
resource/version/shared.lua - Vehicle state · Vehicle properties serialization and restoration across client and server.
resource/vehicleProperties/client.lua
TypeScript package
Typed consumer distribution mirroring the runtime API.
- Common API · Shared TypeScript surface for cache, hooks, locale, zones, and version.
package/common/index.ts - Client API · Typed client-facing modules for interface wrappers, streaming, points, and vehicle properties.
package/client/index.ts - Server API · Typed server-facing modules for commands, callbacks, ACL, locale, and version.
package/server/index.ts
Web UI
React/Vite NUI frontend rendered inside FiveM.
- NUI app · React/Vite application that renders in-game UI surfaces and handles NUI events.
web/src/App.tsx - Dialogs · Alert and input dialog rendering with field components.
web/src/features/dialog/InputDialog.tsx - Menus · Context, list, and radial menu rendering and interaction.
web/src/features/menu/list/index.tsx - Feedback UI · Notifications, progress, skill checks, and text UI components.
web/src/features/notifications/NotificationWrapper.tsx - NUI hooks · Browser-side hooks and fetch bridge for inbound NUI events and outbound responses.
web/src/hooks/useNuiEvent.ts
Release pipeline
Automated versioning and publishing for resource and package surfaces.
- Release pipeline · Version bump and release workflow for distributable artifacts.
.github/workflows/release.yml
Connections 22
- fxmanifest → init: loads · Manifest loads the bootstrap entry.
- init → Resource glue: starts · Bootstrap hands off to the resource runtime.
- Resource glue → Client runtime: client side · Resource runtime exposes client entrypoints.
- Resource glue → Server runtime: server side · Resource runtime exposes server entrypoints.
- Resource glue → Shared imports: uses · Resource runtime consumes shared Lua helpers.
- Resource glue → Client imports: uses · Resource runtime consumes client-only helpers.
- Resource glue → Server imports: uses · Resource runtime consumes server-only helpers.
- Client runtime → UI bridge: bridges · Client runtime forwards gameplay actions into the UI bridge.
- Server runtime → Server services: services · Server runtime provides authority-side interface services.
- UI bridge → NUI app: NUI · Lua client bridge sends messages to the web UI.
- NUI app → NUI hooks: events · The web app listens for NUI events and sends responses back.
- NUI hooks → UI bridge: returns · UI actions are returned to Lua through the NUI bridge.
- Locales → Shared imports: shared concern · Locale loading is shared across Lua runtime layers.
- Versioning → Resource glue: reports · Version helpers feed resource compatibility reporting.
- Vehicle state → Server runtime: sync · Vehicle state is coordinated across server authority.
- Vehicle state → Client runtime: sync · Vehicle state is coordinated on the client runtime.
- Common API → Client API: shared API · Typed common modules are consumed by client bindings.
- Common API → Server API: shared API · Typed common modules are consumed by server bindings.
- Client API → NUI app: drives UI · Typed client wrappers mirror interface features used by the UI.
- Server API → Server runtime: mirrors · Server typings mirror the Lua server surface conceptually.
- Release pipeline → fxmanifest: bump · Release automation updates resource metadata.
- Release pipeline → Common API: publish · Release automation publishes the package surface in sync.