Lumo Docs

Lumo Carrom ​

Server-simulated carrom: singles, doubles, AI practice and shot replay.

Version 1.0.0 · Frameworks QBCore · Qbox · ESX · standalone

Config files · Exports & events · Changelog

Server-simulated 3D carrom with two-player singles, four-player doubles, AI practice, spectators, shot replay, striker fouls and queen-cover rules. In doubles, seats 1 + 3 play white against 2 + 4 black.

Setup ​

  1. Start oxmysql and your framework before this resource. QBCore, Qbox, ESX and standalone are auto-detected. object_gizmo enables precise table/chair placement; ox_target or qb-target enables table targeting. The nearby command also opens the lobby.
  2. Add ensure lumo-carrom to server.cfg after oxmysql and your framework. On a running server, run refresh, then ensure lumo-carrom in the console.
  3. Tables and the shared leaderboard schema are created automatically; no SQL import is needed. sql/install.sql is supplied for manual installs.
  4. As an admin, run /carromtables, choose New table here, place the furniture/chairs, choose the game where offered, and save. There are no fixed tables by default. Saved placements survive resource/server restarts.
  5. Stand near the board and use the target or /carrom. /carromboard displays the leaderboard.

Set options in config.lua. Admin access follows the framework permissions in Config.Admin, with the configured ACE fallback. No source build is required to test: the compiled NUI ships in html/dist.

Controls ​

Move the mouse along your baseline and click to place the striker. Aim, hold the left button to charge, then release to shoot. Right-click returns to placement. Enter starts a waiting game when you are the host. Wheel or V changes the camera; press Backspace twice to leave.

In-game test checklist ​

  • Place, edit and delete a table; restart the resource and confirm saved furniture returns.
  • Play singles and doubles, against AI and human players. Check aiming/power, pockets, repeat shots, striker fouls, queen cover, spectators and a player leaving during a shot.
  • Verify the board/pieces align at different headings, both camera views work, and leaving restores controls and the camera.

The automated suite checks Lua syntax, rules and server sessions without a FiveM client. Model rendering, CEF textures, seating, targeting and live multiplayer still require in-game testing.

Source and verification ​

  • client/, server/, shared/: game, table editor, rendering and rules.
  • framework/: per-resource framework adapter.
  • nui/src/: React lobby/admin UI; html/dui/: in-world board face.
  • shared/props.lua and docs/ASSETS.md: streamed model geometry contract.
  • blender/: original model/texture build scripts; stream/: exported props.

From the repository root: ./tests/lumo/run.sh. Rebuild UI changes with npm run typecheck && npm run build from this resource's nui/ folder.

Rebuild ​

Needs Blender 5.2 LTS, Sollumz 2.9 and texconv.exe (Microsoft DirectXTex) on PATH or in %USERPROFILE%\.local\bin (the lumo-ludo pipeline).

  1. Only if the art changed: python blender/make_textures.py (Python 3 + Pillow + numpy).
  2. Blender → Scripting → Text → Open blender/build_all.py → Run Script (or blender --background --python blender/build_all.py). It empties the open scene, rebuilds every prop, exports to stream/ and saves blender/lumo_carrom.blend.
  3. Never hand-edit the files in stream/; change the scripts and run again.

Blender MCP prompt: "Run blender/build_all.py in Blender with __file__ set to its path, show me the report and the files it wrote, then screenshot the props in Material Preview."

Credits ​

Models, textures and scripts are original work for lumo-carrom. Exported with Sollumz; DDS conversion with Microsoft DirectXTex texconv.