All resources

rsg-targetpractise – Technical Docs#

Developer notes for how the resource works internally. For installation and usage, see README.md.

File layout#

FileSidePurpose
shared/config.luasharedAll settings
shared/geometry.luasharedQuaternion maths, target pose, face-local conversion, ring scoring, hash normalisation
shared/locale.luasharedBuilds the ui_* locale table sent to the NUI (key list read from locales/en.json)
client/diagnostics.luaclient/targetdiag report, error capture, shared TargetPractiseNotify helper (loads first)
client/projectiles.luaclientShot release detection, knife capture, flight segments, projectile-skipping surface probe
client/client.luaclientTarget streaming, rsg-target options, placement preview, shot/impact detector, debug drawing
client/leaderboard.luaclientLeaderboard NUI open/close and focus
server/server.luaserverPlacement/pickup transactions, persistence, shot and hit validation, scoring, sync
server/leaderboard.luaserverBuilds leaderboard rows and range records (never exposes citizen IDs)
html/*NUIPlacement panel, bullseye banner, leaderboard

Placement flow#

  1. Player uses the target item (or admin runs /admintarget). The server checks the item/permission and creates a pending[src] request with an expiry.
  2. Server sends rsg-targetpractise:client:place. The client shows a ghost preview (no collision) and the placement panel.
  3. On Enter the client sends server:place(position, heading). The server re-checks the pending request, owner, routing bucket, distance from the player, spacing and limits.
  4. Inside a single-flight transaction, the target is saved as placing, the item is removed, then the target is saved as active and broadcast.

Pickup flow#

server:remove(id) checks distance, bucket and ownership (or admin). The target is saved as removing before the item is credited, so a crash can never duplicate the item. It is then deleted and saved.

Storage safety#

data/targets.json is written with a read-back check. If any save fails, or the file is invalid or has an unfinished placing/removing record at startup, all item mutations are disabled (storageHealthy = false) until an admin fixes the file and restarts. Nothing is ever refunded automatically.

Scoring flow#

  1. The client detector notices a shot (ammo drop / IsPedShooting / own moving knife) and sends server:shot(sequence, weaponHash). The server checks the weapon is configured, the player owns the weapon item (Config.RequireWeaponItem) and the cooldown, then records the shot with the server-side player position.
  2. On impact the client probes the surface, confirms it hit a streamed target face entity and sends server:hit(sequence, targetId, impact).
  3. The server consumes the shot (once only), checks the time window, citizen ID, routing bucket, range from the recorded shooter position and the ring/depth geometry, then calculates the points itself.
  4. Totals, records and hit marks are updated in memory and scoreRevision is bumped so open leaderboards refresh.

The impact point itself comes from the client. Points are only used for the session leaderboard by default; if you reward money or items via the hook below, add your own cap.

Events#

Client → server#

EventArgsNotes
rsg-targetpractise:server:placeposition, headingRequires a pending request
rsg-targetpractise:server:cancel–Clears the pending request
rsg-targetpractise:server:removeidOwner/admin, within RemoveDistance
rsg-targetpractise:server:sync–Throttled 2 s
rsg-targetpractise:server:shotsequence, weaponHashThrottled by shotCooldownMs
rsg-targetpractise:server:hitsequence, id, impactMust match the latest shot
rsg-targetpractise:server:leaderboardopen (bool)Opens/closes live updates
rsg-targetpractise:server:diagnostic–Admin-free, read-only

Server → client#

client:sync, client:place, client:scored, client:scoreRejected (debug only), client:leaderboard, client:debug, client:diagnosticServer.

Server-only hook#

AddEventHandler('rsg-targetpractise:server:acceptedHit', function(data)
    -- source, citizenid, name, targetId, weapon, weaponKind, points, radius,
    -- bullseye, distance, distanceBonus, timestamp, impact, scoringMode
end)

Sync#

Targets are sent per routing bucket with only id, position, heading and canRemove. The server resyncs on every change (broadcast), on RSGCore:Server:PlayerLoaded / OnPlayerUnload, and every 5 s for players whose bucket changed. Clients spawn local (non-networked) props within Config.StreamDistance.

Leaderboard#

While a player has the board open, the server checks every Config.LeaderboardRefreshMs and only re-sends when scoreRevision has changed (a new hit or a player leaving). Locales are sent once when the board opens.

Dependencies#

rsg-core, rsg-inventory, rsg-target, OneSync. No ox_lib: locales load via @rsg-core/shared/locale.lua (language from the rsg:locale convar).

<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

Technical reference#

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

Dependencies#

rsg-core, rsg-inventory, rsg-target, /onesync

Configuration#

OptionDefaultNotes
Config.Item'target'
Config.AdminPermission'admin'
Config.FrameModel'p_targetframe01x'
Config.FaceModel'p_targetarchery02x'
Config.SourcetableUnmodified values from ../props.txt. Geometry derives a LOCAL offset, not a world delta.
Config.Placementtable
Config.StreamDistance120.0
Config.RemoveDistance3.0
Config.LeaderboardRefreshMs2000
Config.ModelTimeoutMs10000
Config.PersistTargetstrue
Config.StorageFile'data/targets.json'
Config.Scoringtablex/z span the face; y is its depth. Values are in model-local metres.
Config.WeaponstableScored weapons. Values are locale keys (locales/*.json) used for the display name.
Config.WEAPON_BOW'weapon_bow'
Config.WEAPON_BOW_IMPROVED'weapon_bow_improved'
Config.WEAPON_THROWN_THROWING_KNIVES'weapon_throwing_knives'
Config.WeaponKindstableUsed by the leaderboard to separate arrow and knife hits. Unknown weapons fall back to 'other'.
Config.RequireWeaponItemtrueShots only count if the player has the weapon item in their inventory (blocks spoofed shot events).
Config.DebugfalseAdmins can toggle their own debug display with /targetdebug.
Config.DebugImpactMs8000
Config.Projectilestable
Config.Controlstable

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-targetpractise:client:syncclientlistclient/client.lua
rsg-targetpractise:client:scoreRejectedclientreasonclient/client.lua
RSGCore:Client:OnPlayerLoadedclient``client/client.lua
rsg-targetpractise:client:placeclient``client/client.lua
rsg-targetpractise:client:scoredclientpoints, radius, total, impact, mode, bullseye, weaponKind, weaponLabel, distance, bonusclient/client.lua
rsg-targetpractise:client:debugclientenabledclient/client.lua
rsg-targetpractise:client:diagnosticServerclientdataclient/diagnostics.lua
rsg-targetpractise:client:openLeaderboardclient``client/leaderboard.lua
rsg-targetpractise:client:leaderboardclientdataclient/leaderboard.lua
RSGCore:Client:OnPlayerUnloadclient``client/leaderboard.lua
rsg-targetpractise:server:leaderboardserveropenserver/server.lua
rsg-targetpractise:server:cancelserver``server/server.lua
rsg-targetpractise:server:placeserverposition, headingserver/server.lua
rsg-targetpractise:server:removeserveridserver/server.lua
rsg-targetpractise:server:syncserver``server/server.lua
rsg-targetpractise:server:diagnosticserver``server/server.lua
rsg-targetpractise:server:shotserversequence, weaponserver/server.lua
rsg-targetpractise:server:hitserversequence, id, impactserver/server.lua
-- from a client script
TriggerServerEvent('rsg-targetpractise:server:leaderboard', open)
-- from a server script
TriggerClientEvent('rsg-targetpractise:client:sync', source, list)

Commands#

CommandNotesFile
/targetremoveclient/client.lua
/targetdiagclient/diagnostics.lua
/targetboardclient/leaderboard.lua
/admintargetlocale('command_admin')server/server.lua
/targetdebuglocale('command_debug')server/server.lua
/targetscorelocale('command_score')server/server.lua

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 -->