# qb-streetraces

`qb-streetraces` creates short races with cash wagers and a browser UI. The pinned source
contains insufficiently authoritative wager handlers. Treat
this as a source reference requiring integration and security review before enabling real wagers.
It is not a verified drop-in installation for every current QBCore server.

## Installation and compatibility

The manifest loads `config.lua`, `client.lua`, `server.lua` and the files under `html/`.
The server retrieves QBCore commands and player objects from `qb-core`. No standalone SQL,
third-party racing database or custom resource exports are shipped in the reviewed repository.

```cfg
ensure qb-core
ensure qb-streetraces
```

Before enabling this on a public server, inspect every returned player object's money methods.
Several handlers use `exports['qb-core']:GetPlayer(...)` followed by `.Functions.AddMoney` or
`.Functions.RemoveMoney`. Core commit `9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf` exposes
both direct wrapper methods and a `.Functions` compatibility table. Those calls are supported
by that implementation; inspect other forks before assuming the same interface. See the
[server functions reference](/docs/api/server-functions) and match your exact core commit.
Do not fix this by inventing a new racing export.

## Verified configuration and commands

The default command names come from `Config.Commands`:

| Command | Purpose |
| --- | --- |
| `/createrace AMOUNT` | Requests race creation at a chosen destination |
| `/startrace` | Starts the creator's race |
| `/cancelrace` | Cancels the creator's pending race |
| `/quitrace` | Leaves a pending race |

To adjust limits, edit the existing configuration:

```lua
Config.MinimumRaceDistance = 150.0
Config.MinimumStake = 100
Config.MaximumStake = 5000
```

The create command checks its amount against the configured limits. A command check is not
validation of the separate network handler receiving the race table. `Config.Currency` is a
notification/display label, not a switch to a different money account.

## Event ownership

Server network handlers: `qb-streetraces:NewRace`, `qb-streetraces:JoinRace` and
`qb-streetraces:RaceWon`. The resource keeps race state in the process-local `Races` table.
Client handlers include `qb-streetraces:CreateRace`, `qb-streetraces:StartRace`,
`qb-streetraces:StopRace`, `qb-streetraces:SetRace`, `qb-streetraces:SetRaceId`,
`qb-streetraces:RaceDone` and `qb-streetraces:UpdateRaceInfo`.
These names describe implementation flow; they are not safe public award APIs.

## Authority limitations and diagnostics

`NewRace` accepts a client race table without reproducing the command's bounded stake validation.
`RaceWon` accesses the supplied race ID and awards its pot without proving that the sender is
an eligible winner or consuming a payout once. Client waypoint completion is insufficient
server authority. Repeated, invalid and concurrent requests require explicit server-side
validation in an installed fork. No exploit invocation example is provided here.

- **Money-method error:** check player presence and whether your core fork exposes `.Functions` on its wrapper.
- **No creation prompt:** check a destination waypoint beyond `MinimumRaceDistance`, command
  names and the amount supplied to the command.
- **Race data missing after restart:** the state is in memory, not persisted in SQL.
- **Offline participant errors:** review creator/player presence before using money methods.
- **NUI missing:** confirm the manifest's HTML paths and all shipped JS/CSS assets.

## Update checklist

On an isolated server, test creation, join, start, cancel, quit and restart with at least two
players. Verify stake removal/refund and exactly one payout. Include invalid race IDs, missing
players, negative/oversized stakes, replay and concurrent finish requests in server-authority
tests. These checks remain required; parsing Lua or documenting handlers cannot prove safety.

## Sources

- [Pinned resource source](https://github.com/qbcore-fivem/qb-streetraces/tree/41c1215ec56e37026259f5bc1cccac995b4b4b2c)
- [Manifest](https://github.com/qbcore-fivem/qb-streetraces/blob/41c1215ec56e37026259f5bc1cccac995b4b4b2c/fxmanifest.lua)
- [Configuration](https://github.com/qbcore-fivem/qb-streetraces/blob/41c1215ec56e37026259f5bc1cccac995b4b4b2c/config.lua)
- [Official documentation repository](https://github.com/qbcore-framework/qb-docs/tree/930c12ec4f60dfbba60253571f1a58980129516d/qbcore-resources)
- [Resource dependency checklist](/docs/migration/tools/compatibility-checker)
