Ctrlk
DiscordOfficial Store
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Configurations

All configuration is done in public/shared/config.lua (LudusConfig). Restart the resource after changing values.

General

Option
Type
Default
Description

Debug

boolean

false

Enable extra logs in F8 / server console. Set false on production.

Locale

string

"en"

Language code. Options: "en", "pt". Must match a file in public/shared/locales/.

Theme

string

"default"

NUI theme key from public/shared/themes.json (default | custom).

Bridge

Option
Type
Options
Description

Bridge.Framework

string

"auto" | "qb-core" | "qbx_core" | "es_extended"

Framework to use. "auto" detects automatically.

Bridge.Inventory

string

"auto" | "ox_inventory" | "qb-inventory" | "qs-inventory"

Inventory system.

Bridge.Interaction

string

"drawtext" | "target"

How players interact with placed boards.

Bridge.Target

string

"auto" | "ox_target" | "qb-target"

Target system when Interaction = "target".

Bridge.Notify

string

"auto" | "ox_lib" | "qbcore" | "esx" | "native"

Notification system.

Notify Options (ox_lib)

Option
Type
Default
Description

NotifyOptions.position

string

"top-right"

ox_lib toast position (top-right, top-left, top, bottom-right, …).

NotifyOptions.duration

number

4500

Toast duration (ms).

Toasts use a single path: Api.Notify → cdev_ludus:clientNotify → Notify bridge. Identical messages within ~900ms are ignored to prevent duplicates.

Interaction Options

DrawText (when Bridge.Interaction = "drawtext")

World text floats above the nearest board (checkers-style). Two actions:

On screen
Default key
Action

[E] Play Ludus

E

Interact (create / join lobby / open / spectate)

[G] Pick up board

G

Pick up idle board (owner or admin) — item returned

Option
Type
Default
Description

keyDisplay

string

"E"

Letter shown for play (must match the bound control).

controlId

number

38

FiveM control ID for play. 38 = E (controls list).

label

string | nil

nil

Custom play label. nil = locale ludus.interact_board.

pickupKeyDisplay

string

"G"

Letter shown for pickup.

pickupControlId

number

47

FiveM control ID for pickup. 47 = G.

pickupLabel

string | nil

nil

Custom pickup label. nil = locale ludus.pickup_board.

Performance: watcher sleeps at 500ms when far; a Wait(0) draw thread runs only while a board is in range, then exits (same pattern as cdev_checkers).

If you change controlId / pickupControlId, also update keyDisplay / pickupKeyDisplay so the on-screen letter matches the real key.Target (when Bridge.Interaction = "target")

Option

Type

Default

Description

label

string

"Ludus Table"

Text shown on target option.

icon

string

"fas fa-dice"

Icon (Font Awesome for ox_target).

distance

number

3.5

Aim distance to show the option.

ACE & Commands

Option

Type

Default

Description

ACE.Admin

string

"cdev_ludus.admin"

ACE permission for admin features.

Commands.Admin

string

"ludusadmin"

Admin panel command.

Commands.Place

string

"ludusplace"

Admin place command.

Commands.Delete

string

"ludusdelete"

Admin delete nearest board.

Commands.Gaming

string

"ludusgaming"

Gaming hub (profile / rank / history).

Commands.Balance

string

"ludusbalance"

Layout calibrator.

Item

Option

Type

Default

Description

Item.enabled

boolean

true

Enable item placement.

Item.name

string

"ludus_board"

Item name in inventory (must match).

Item.label

string

"Ludus Board"

Suggested display name.

Props

Board, dice, pawns, and stake chips. Must match stream files unless you replace models.

Option
Default / notes
Description

Props.board

"cdev_board"

Board model.

Props.die

"cdev_player_dice"

Dice model.

Props.DieAnim.spinMs

950

Spin duration (ms).

Props.DieAnim.bounceHeight

0.11

Bounce height (m).

Props.DieAnim.faces[1..6]

See config

Face-up attach rotations.

Props.pawns.*

cdev_player_red/blue/green/yellow

Pawn models per color.

Props.Chips.enabled

true

Spawn chip stacks at seats.

Props.Chips.showWithoutWager

false

Cosmetic chips even without wager.

Props.Chips.seatFactor

0.55

Chip distance toward seat (0–1).

Props.Chips.height

-0.008

Local Z above board (calibrate with /ludusbalance).

Props.Chips.spread

0.04

Lateral spacing between stacked chip props.

Props.Chips.fallback

"prop_cash_pile_02"

Used if casino chip DLC models are missing.

Props.Chips.tiers

stake → model + count

Visual tier by per-player stake.

Furniture (kit mode)

Option
Type
Default
Description

Furniture.tableModel

string

"prop_table_02"

Table under the board.

Furniture.chairModel

string

"prop_chair_02"

Chair per seat.

Furniture.spawnTable

boolean

true

Spawn table + chairs with the board.

Furniture.boardLift

number

0.02

Gap above table surface (m).

Furniture.boardOffset

table

{x=0,y=0}

Fine XY if board pivot is off-center.

Furniture.chairFaceOffset

number

180.0

Extra yaw so chairs face the table.

Furniture.chairs

table

4 cardinal seats

Kit chair ring offsets.

Furniture.colorSeats

table

per color

Seat side mapping for sit / chips.

Search...

Option

Type

Default

Description

Placement.raycastDistance

number

20.0

Raycast distance (m).

Placement.maxDistanceFromPlayer

number

6.0

Max place distance (m).

Placement.minDistanceFromPlayer

number

1.4

Min place distance (m).

Placement.ghostAlpha

number

180

Ghost prop alpha (0–255).

Placement.smooth

number

0.35

Ghost smoothing (0–1).

Placement.heightStep

number

0.03

Height nudge per PageUp / PageDown.

Placement.Keybinds.place

number

38

Confirm place (E).

Placement.Keybinds.cancel

number

200

Cancel (ESC).

Placement.Keybinds.scrollUp/Down

number

15/14

Rotate board.

Placement.Keybinds.fineRotate

number

21

Shift for fine rotation.

Placement.Keybinds.rotateLeft/Right

number

174/175

Arrow rotate.

Placement.Keybinds.toggleKit

number

47

Toggle furniture kit (G).

Placement.Keybinds.ground

number

22

Snap to ground (SPACE).

Placement.Keybinds.heightUp/Down

number

10/11

PageUp / PageDown.

Sit Animation

Option

Type

Default

Description

Sit.Enable

boolean

true

Sit ped when joining lobby / match.

Sit.Chair.*

table

See config

Kit mode: chair anim + ped offset.

Sit.Floor.seatDistance

number

1.15

Board-only seat distance from board center (m).

Sit.Floor.Anims

table

jetski owner idle

Board-only floor sit anim.

Cinema Camera

Option

Type

Default

Description

Camera.defaultDistance

number

1.75

Default orbit distance.

Camera.minDistance

number

0.42

Min zoom.

Camera.maxDistance

number

4.5

Max zoom.

Camera.minHeight

number

0.12

Min height above board.

Camera.maxHeight

number

2.8

Max height above board.

Camera.defaultHeight

number

1.05

Default height.

Camera.lookAtZ

number

0.08

Look-at height on board.

Camera.rotateSpeed

number

90.0

A/D orbit speed (deg/sec).

Camera.elevateSpeed

number

1.6

W/S elevate speed (m/sec).

Camera.zoomStep

number

0.12

Zoom step per scroll.

Camera.fov

number

42.0

Cinema FOV.

Camera.Controls

table

W/S/A/D

Elevate / rotate control IDs.

Sync (spectators)

Option

Type

Default

Description

Sync.interestRadius

number

6.0

Players inside receive table FX / spectator sync.

Sync.leaveHysteresis

number

1.0

Extra meters before leave (anti-flicker).

Sync.idleWaitMs

number

750

Loop sleep when far from tables.

Sync.nearWaitMs

number

100

Loop sleep when near a table.

Sync.debugDraw

boolean

false

Draw sync radius rings when Debug is on.

Sync.debugNotify

boolean

false

Notify on sync enter/leave when Debug is on.

Distances

Option

Type

Default

Description

Distances.InteractionDistance

number

3.5

DrawText / interact prompt distance (m).

Distances.ActionMaxDistance

number

6.0

Server distance check for table actions.

Match

Option

Type

Default

Description

Match.MinPlayers

number

2

Minimum seats when creating a lobby (clamped 2–4).

Match.MaxPlayers

number

4

Maximum seats when creating a lobby (clamped 2–4).

Match.TurnTimeoutSec

number

60

Default turn timer when host enables it.

Match.TimerPresets

table

{30,45,60,90,120}

Lobby timer preset buttons (seconds).

Match.DisconnectPauseSec

number

90

Pause after disconnect before forfeit.

Match.Colors

table

red/blue/green/yellow

Playable colors.

Match.InitRollGapMs

number

1200

Delay between initiative dice reveals.

Match.InitRollLeadMs

number

500

Delay before first initiative roll.

Match.InitRollEndMs

number

900

Delay after last initiative roll.

Match.Controls.roll

number

38

Roll dice while cinema cam (E).

Turn timeout is clamped server-side to 10–300 seconds when enabled. Disabled timer uses 0.

Betting

Option

Type

Default

Description

Betting.MinStake

number

100

Minimum wager amount.

Betting.MaxStake

number

100000

Maximum wager amount.

Betting.Presets

table

{100,500,1000,5000}

Quick-select stake buttons.

Winner pot is paid as cash (Api.AddMoney cash account), even if players paid from bank.

Rating & Badges

Option

Type

Default

Description

Rating.DefaultPoints

number

1000

Starting points for new players.

Rating.MinPoints

number

1000

Floor points.

Rating.MaxPoints

number

6000

Ceiling points.

Rating.WinDelta

number

50

Points gained on win.

Rating.LossDelta

number

30

Points lost on loss.

Rating.ForfeitDelta

number

40

Points lost on forfeit.

Rating.PageSize

number

10

Ranking rows per page in hub.

Rating.Badges

table

See below

Rank badges by minimum points.

Default Badges

Min Points
Badge
Label

5500

GM

Grandmaster

4800

M

Master

4000

D

Diamond

3200

P

Platinum

2400

G

Gold

1800

S

Silver

1400

B

Bronze

1000

R

Rookie

Match History

Option
Type
Default
Description

MatchHistory.MaxEntriesPerPlayer

number

20

Max matches kept per player (FIFO trim).

MatchHistory.PageSize

number

10

History rows per page in hub.

Board Layout & Rules

Option
Type
Default
Description

BoardLayout.trackLength

number

56

Main track cells.

BoardLayout.homeLength

number

5

Colored home stretch cells.

BoardLayout.safeSquares

table

stars

Safe / star cell indices.

BoardLayout.startSquare

table

per color

Entry cell per color.

BoardLayout.MoveAnimation

table

420ms / lift 0.08

Pawn hop timing / height.

BoardLayout.Outline

table

See config

Legal / blocked / path outline colors.

Fine visual positions (cell size, yard radius, die Z, chip height, etc.) live in public/shared/layout.lua and can be overridden by public/shared/layout_override.json (written by /ludusbalance).

Custom Themes

Cdev Ludus Gaming ships one official look and a documented custom template for buyers.

Themes Config (public/shared/config.lua)

  • default — Official production theme (dark panels #161619 + blue accent #7289DA). Do not remove this block.

  • custom — Empty overrides with _key comments describing each token (same pattern as cdev_checkers). Fill only what you want to change; empty "" falls back to default.

Themes File (public/shared/themes.json)

Structure:

  • default — full color map applied when Theme = "default"

  • custom — pairs of _comment + empty value for each token

Example from custom:

✏️ How to create a custom theme

  1. Set Theme = "custom" in public/shared/config.lua.

  2. Open public/shared/themes.json.

  3. In the custom object, fill the color keys you want (leave others as "").

  4. Keys starting with _ are documentation only — never put a color there.

  5. Save and restart cdev_ludus.

📋 Theme keys (what each color changes)

Key
What it changes

bg

Main panel / page background

bgPanel

Panel background (lobby, hub, match sidebar)

bgPanelSolid

Solid panel background (no transparency)

bgInput

Input fields and chips background

bgHover

Hover state (rows, icon buttons)

bgActive

Active / selected fill (tabs, toggles)

border

Default panel / card border

borderActive

Active / focused border (accent outline)

borderInput

Input field border

accent

Primary accent (buttons, links, highlights)

accentHover

Primary accent hover

accentMuted

Soft accent fill / muted highlight

text

Primary text color

textSecondary

Secondary text color

textMuted

Muted labels / hints

textDim

Dimmed / placeholder text

success

Success / win color

error

Error / loss / danger color

warning

Warning / neutral status color

scrollbarThumb

Scrollbar thumb color

scrollbarThumbHover

Scrollbar thumb hover color

btnSecondary

Secondary button background

btnSecondaryHover

Secondary button hover background

overlay

Overlay / backdrop token (transparent or rgba)

headerBg

Panel header background

red / blue / green / yellow

Ludus seat color accents

⚠️ Important

  • Only colors can be changed; icons and layout are fixed.

  • Theme is server config only — players cannot switch themes in-game.

  • Use hex (#7289da) or CSS (rgba(114, 137, 218, 0.18)).

  • Empty custom values always fall back to default.

  • Do not delete the default theme block.

Custom Framework, Inventory, Notify & Target

Cdev Ludus Gaming uses a bridge system for framework, inventory, notifications, and target. By default it auto-detects supported systems. If you use a custom or unsupported system, edit the bridge files under public/bridge/.

Bridge config (public/shared/config.lua)

Custom Framework

Edit public/bridge/framework/server.lua and public/bridge/framework/client.lua.

Add a new entry to FrameworkSystems with: getFrameworkName, notify, getPlayer, getCitizenId, money helpers (getCashOnHand, getBankBalance, addMoney, removeMoney), and init.

Set Bridge.Framework = "your_framework" in config.

Custom Inventory

Edit public/bridge/inventory/server.lua.

Implement addItem, removeItem, getItemCount, hasItem for your system, then set Bridge.Inventory = "your_inventory".

Custom Notify

Edit public/bridge/notify/client.lua.

Add a branch in send() for your notify system, then set Bridge.Notify = "your_notify" (or use "native").

Custom Target

Edit public/bridge/target/client.lua.

Add your target attach/detach logic for board (and kit furniture) entities.

Alternatively, set Bridge.Interaction = "drawtext" to avoid target entirely.

Buyer-editable folders

Path

Role

public/shared/config.lua

All tunables

public/shared/layout.lua + layout_override.json

Visual layout

public/shared/locales/*.json

Strings

public/shared/themes.json

UI themes

public/bridge/**

Framework / inventory / target / notify

public/server/api.lua

Admin / money / notify hooks

public/client/api.lua

Client helpers for other resources

public/** is escrow-ignored. Core server logic still re-validates ACE, distance, money, and inventory.

PreviousInstallation Guide
NextCommands

Last updated