Studios
Paintballhouse-3.jpg

Examples

SoonPaintballQbox
PAGE 04 OF 06  ·  CONFIGURATION → EXAMPLES → TROUBLESHOOTINGdocs.glitchstudios.dev
Browse docs

Held inventory#

When a match starts, each player's items are held:

  1. The inventory is read and the items are removed from ox_inventory in memory.
  2. One SQL transaction writes a row into glitch_paintball_holds and saves the now empty inventory into players.inventory.
  3. When the player leaves the match, the match ends or an admin cancels it, the items are given back in memory and one transaction deletes the row and writes the restored inventory.

The hold transaction is designed to preserve inventory across crashes; verify recovery on your deployment. If the server or the player's game crashes during a match, the hold is still in the database and is restored at the next login or resource start. Items that do not fit when they come back stay held, and the player can collect them from the desk after making room.

Slots listed in Config.KeepSlots are never held. Servers that store worn clothing as inventory items put those slots there. The default is an empty list, which holds everything.

The code writes to the players table (inventory, money and position columns). That is the Qbox schema. On another framework or schema, change server/holds.lua and the two functions Bridge.AddMoneyOffline and Bridge.SavePositionAfterDrop in server/bridge.lua. AddMoneyOffline writes the JSON money column of players directly, so it only works with Qbox.

What this writes outside its own tables#

The resource creates and uses its own tables glitch_paintball_holds and glitch_paintball_stats. It also writes three columns of the Qbox players table. Nothing else outside its own tables is touched. The code is in server/holds.lua and server/bridge.lua, both open in the escrow so you can audit them.

  • players.inventory: written together with the hold row when a match starts (the emptied inventory), and together with the row delete when items are given back (the restored inventory). A restore that leaves items behind because they did not fit writes the current inventory too.
  • players.money: read and written only by Bridge.AddMoneyOffline, when a wager must be refunded to a player who is offline. Online refunds and payouts go through qbx_core.
  • players.position: written 3 seconds after a player drops out of a running match, so they log back in at the return point instead of inside an arena.

Back up your database before installing, and test with a throwaway character.

Hit checks and weaponDamageEvent#

Hit detection uses the server event weaponDamageEvent (OneSync). The resource cancels damage into and out of arenas, between teammates and during spawn protection, and lets damage between opponents through. Another resource that also cancels or edits that event for the same players can conflict with it. The server credits a kill to the last opponent who hurt the victim within Config.KillCreditSeconds.

Clients report hits and deaths, so Config.Plausibility checks them against what the server knows:

  • A hit from further away than the weapon class reaches (maxDistance, plus distanceSlack) is dropped.
  • An attacker is limited to maxHitsPerSecond damage events. Shotgun pellets and the minigun count.
  • A "will kill" claim, which makes the victim's game show a death, only counts when the victim's server-side health and armour minus the server's own damage figure for the weapon are within killHealthSlack. The client's reported damage is ignored.
  • A headshot kill (the lobby rule) needs a gun and a victim whose server-side health and armour are within the weapon's damage times headshotMult (2), plus the slack. If the victim already took a hit in the last headshotRecentMs, the bound doubles. A headshot flag from the client alone never kills.
  • The weapon named in a hit must be the one the server sees in the attacker's hands, or one they held within weaponGraceMs (1 second). Otherwise the hit is dropped.
  • A client report that it died is accepted only after a recent hit, a forced death from the server, or when the server sees the ped at the health floor.
  • The death, shot, fired, respawn, streak and heal calls and the lobby callbacks are rate limited per player. A short burst is allowed, then one call per interval.

Set Config.Plausibility.enabled = false to turn the distance and rate checks off.

Exports and events#

Server exports:

  • IsInMatch(src) returns true while the player is in a live match.
  • GetLobbies() returns the lobby list.
  • AbortMatch(lobbyId) cancels a match and refunds wagers.
  • GetHolds() returns every inventory hold in the database.
  • ArcadeKick(src) removes a player waiting in a lobby (used by glitch-arcade when they leave its zone).

Client export: OpenFromArcade() opens the desk window.

Server events your own scripts can listen to:

  • glitch-paintball:onKill (killer or nil, victim, weapon)
  • glitch-paintball:onKillstreak (src, streak, label)
  • glitch-paintball:onMatchEnd (lobbyId, winner)