All resources

rsg-gizmo — developer docs#

Contents#

  1. Architecture
  2. Options table
  3. Result format
  4. Client exports
  5. Server exports
  6. Events
  7. Integration examples
  8. Persistence
  9. Security model
  10. Database
  11. How-tos
  12. Troubleshooting

1. Architecture#

FilePurpose
fxmanifest.luaManifest; depends on rsg-core only
shared/config.luaDefaults, colours, control hashes, test command
client/client.luaGhost spawning, placement loop, raycast, drawing, exports
server/server.luaIsPlacementValid, SanitiseRotation, /gizmotest
html/*HUD (no NUI focus): mode, validity, coords, rotation, key list
locales/*.jsonAll player-facing text

rsg-gizmo never saves anything. It only returns where the player put the prop; the calling script owns items, money, database and spawning.

2. Options table (all optional; defaults from Config.Defaults)#

KeyTypeDescription
titlestringHUD title (default locale hud_title)
rayDistancenumberFree-mode ray length
maxDistancenumberMax player ↔ prop distance
rotation'z'/'all'Heading only or full rotation
snapToGroundboolLift model so its base sits on the hit surface
allowInterior / allowWaterboolBuilt-in rules. Interior blocks if the prop or the player is inside an interior
alphanumberGhost alpha
startMode'free'/'fine'Edit defaults to 'fine'
startCoordsvector3Initial position
startRotationvector3Initial pitch, roll, yaw
moveSpeed, rotateSpeed, scrollRotate, scrollHeight, precisionnumberFeel
validatefunction(coords, rotation) -> ok, reasonRuns every frame; return false, 'text' to block placement. Keep it cheap. Errors are caught and treated as invalid (enable Config.Debug to see them)

3. Result format#

{ coords = vector3, rotation = vector3(pitch, roll, yaw), heading = number }

nil means cancelled, invalid model, player died, another session active, or Cancel() was called. Spawn with SetEntityRotation(obj, rot.x, rot.y, rot.z, 2, true) (rotation order 2) or SetEntityHeading(obj, heading) for heading-only props.

4. Client exports#

ExportReturnsNotes
Place(model, options)result / nilBlocking — call inside CreateThread. Spawns a local, non-networked ghost and deletes it afterwards
Edit(entity, options)result / nilMoves an existing entity in place; restores position, rotation, alpha and collision on cancel. Requests network control if networked (waits up to 1s, returns nil if not granted). The caller still syncs the final position to the server/DB
IsActive()boolWhether a session is running
Cancel()—Ends the current session (result nil)

5. Server exports#

ExportReturnsNotes
IsPlacementValid(src, coords, maxDistance?)ok, reasonChecks numbers are finite and the player ped is within maxDistance + 2.0. Reasons: bad_coords, no_player, too_far
SanitiseRotation(rot)vector3Converts client input to a safe vector3 (each axis % 360, bad values → 0)

6. Events#

EventSideArgs
rsg-gizmo:client:placeclient (local TriggerEvent)model, options, cb(result) — non-blocking alternative to the export
rsg-gizmo:client:testclient (from server)model — used by /gizmotest

7. Integration examples#

Item-based placement:

-- server
RSGCore.Functions.CreateUseableItem('shopsign', function(source)
    TriggerClientEvent('rsg-stores:client:placeSign', source)
end)
RegisterNetEvent('rsg-stores:server:placeSign', function(coords, rot)
    local src = source
    if not exports['rsg-gizmo']:IsPlacementValid(src, coords, 6.0) then return end
    rot = exports['rsg-gizmo']:SanitiseRotation(rot)
    local Player = RSGCore.Functions.GetPlayer(src)
    if not Player or not exports['rsg-inventory']:RemoveItem(src, 'shopsign', 1) then return end
    -- insert into DB, then broadcast spawn
end)

-- client
RegisterNetEvent('rsg-stores:client:placeSign', function()
    local res = exports['rsg-gizmo']:Place(Config.SignModel, {
        title = locale('place_sign'), maxDistance = 6.0,
        validate = function(c) if IsPointNearRoad(c) then return false, locale('too_close_road') end return true end,
    })
    if res then TriggerServerEvent('rsg-stores:server:placeSign', res.coords, res.rotation) end
end)

(IsPointNearRoad above is a placeholder for your own rule.)

Admin moving an existing prop:

local res = exports['rsg-gizmo']:Edit(obj, { rotation = 'all' })
if res then TriggerServerEvent('my-script:server:moveProp', propId, res.coords, res.rotation) end

8. Persistence#

None. Callers store the result.

9. Security model#

  • The client result is untrusted. Always run IsPlacementValid (or your own distance check) on the server.
  • Calling scripts must check items, money, job/permission, zone rules and per-player limits themselves.
  • /gizmotest is gated by rsg-core command permission (Config.TestCommand.permission).

10. Database#

No tables.

11. How-tos#

  • Get coords for a config: /gizmotest p_chair05x, place it, copy the line from F8.
  • Change keys: edit Config.Controls with hashes from data/rdr3_discoveries/Controls/README.md.
  • Heading-only props (signs, tents): leave rotation = 'z'. Props on slopes: use rotation = 'all' and press G.

12. Troubleshooting#

ProblemFix
Export returns nil immediatelyAnother session is active, or the model name is invalid (notify shows "Invalid model")
Freezes calling codePlace blocks — call it inside CreateThread
Prop floats/sinksModel origin is unusual; use fine mode + wheel, or set snapToGround = false
Prop goes under the map in free modeAim at solid ground; ray only moves the prop on a hit
Edit returns nil on a networked propNetwork control wasn't granted within 1s; spawn it client-side or move it server-side from the result
rsg-gizmo restarted mid-placementThe ghost is deleted and an edited entity is put back where it was automatically

Support the Project : https://rexshack.tebex.store/

Blocking other resources while placing#

While a session runs the gizmo disables Config.BlockControls (now including the mouse-wheel aliases and rsg-voice's range key) and sets the local state bag LocalPlayer.state.gizmoActive = true. Resources that read input through key mappings / commands (which DisableControlAction cannot block) should check it, e.g. in rsg-voice:

if LocalPlayer.state.gizmoActive then return end
<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

Technical reference#

Generated from the source of rsg-gizmo 3.0.1. Names, arguments and defaults below are read straight from the code.

Dependencies#

rsg-core

Configuration#

OptionDefaultNotes
Config.Debugfalse
Config.DefaultstableDefaults (every one can be overridden per call through the options table)
Config.ColourstableDraw colours (r, g, b, a)
Config.ControlstableControl hashes: data/rdr3_discoveries/Controls/README.md
Config.BlockControlstableExtra controls blocked while placing
Config.TestCommand{ enabled = true, name = 'gizmotest', permission = 'admin', model = 'pAdmin test command: /gizmotest [model]

Exports#

Server

ExportArgumentsFile
IsPlacementValid``server/server.lua
SanitiseRotation``server/server.lua

Client

ExportArgumentsFile
Place``client/client.lua
Edit``client/client.lua
IsActive``client/client.lua
Cancel``client/client.lua
-- example
local result = exports['rsg-gizmo']:IsPlacementValid()

Events#

Server events can be fired by any client, so every handler re-validates the player, the arguments and any permission, distance or cooldown on the server. Never add a reward to a handler without those checks.

EventSideArgumentsFile
rsg-gizmo:client:testclientmodelclient/client.lua
-- from a server script
TriggerClientEvent('rsg-gizmo:client:test', source, model)

Locales#

Language files in locales/: de, el, en, es, fr, ja, nl, pl, pt-br, ro, ru. Set the language with setr rsg:locale "en".

<!-- END AUTO-REFERENCE -->