DocumentationdevelopmentPerformance Tuning

Performance Tuning

Optimising scripts early prevents lag spikes, timeouts, and frustrated players. Use this guide to build a repeatable process fo r measuring, diagnosing, and improving QBCore performance in development and staging environments.

Establish a Baseline

  • Profile an idle server. Record CPU, memory, and tick usage with only core resources enabled. This becomes your reference w hen new features land.
  • Capture targeted workloads. Simulate peak activity (e.g., multiple robberies, busy EMS shifts) and log frame time, network t usage, and database latency.
  • Track metrics over time. Store measurements in a shared doc or dashboard so regressions are obvious during code review.

Instrument Your Code

  • Use lightweight timers. Measure hot code paths with GetGameTimer() or os.clock to identify slow sections.
  • Emit structured telemetry. Push counters (e.g., processed jobs, queue length) to your logging solution for quick insight.
  • Trace with the Event Debugger. The Event Debugger shows event frequency, payload sizes, and hand ler durations—perfect for spotting spammy triggers or heavy loops.

Optimise Server Scripts

  • Exit loops aggressively. Break out once work is complete and avoid polling when events can notify you instead.
  • Cache expensive lookups. Store computed routes, shop inventories, or permission checks rather than rebuilding them per req uest.
  • Defer heavy tasks. Move long-running jobs (e.g., batch payouts or import scripts) to scheduled threads with generous Wait intervals.
  • Validate configs for performance traps. The Config Validator flags common mistakes such as zero- interval loops or missing cooldowns.

Optimise Client Scripts and UI

  • Throttle rendering. Use SetTimeout/Wait wisely in NUI scripts and re-render only when reactive data changes.
  • Limit entity loops. Replace for loops that scan every ped/vehicle each frame with targeted queries or server-supplied lis ts.
  • Optimise network usage. Send compact payloads and debounce remote events so you are not firing multiple updates per tick.

Database and External Services

  • Bundle queries. Batch writes when possible and reuse prepared statements. Avoid synchronous calls in event handlers.
  • Index frequently queried columns. Coordinate with your DBA (or review your SQL dumps) to ensure lookups stay fast.
  • Monitor third-party dependencies. If you rely on external APIs, implement retries and circuit breakers to avoid blocking t he main gameplay loop.

Ongoing Monitoring

  1. Run the Event Debugger in staging after every major release to verify event throughput stays healthy.
  2. Schedule recurring Config Validator checks to ensure new configs do not reintroduce expensive loops or broken cooldowns.
  3. Compare metrics against your baseline and investigate any upward trends immediately.
  4. Log optimisation wins in your changelog so future developers know the history behind key design choices.

See Also

Best PracticesIndex