cw-racingapp — Manual

App de corridas em NUI: criar pistas com checkpoints, hospedar e entrar em corridas (sprint, voltas, eliminação, ranqueadas), com crypto próprio, crews, bounties de time trial e corridas automatizadas.

Sumário

1. Dependências
2. Instalação
3. Permissões (ACE)
4. Tipos de usuário do app
5. Configuração
6. Comandos
7. Criador de pistas
8. Racing Crypto e pagamentos
9. Corridas automatizadas
10. Bounties
11. ELO e ranqueadas
12. Banco de dados
13. Integrações
14. Entrypoints para outros recursos
15. Localização
16. Estrutura de arquivos

Dependências

O bridge (bridge/client/ e bridge/server/) escolhe o framework sozinho: se qbx_core estiver rodando, o arquivo qb.lua se desativa.

Instalação

1. Copie a pasta cw-racingapp para resources/.
2. Importe os SQLs:

   cw-racingapp.sql      -- tabelas race_tracks e racer_names
   cw-racingcrews.sql    -- tabela racing_crews
   default_tracks.sql    -- opcional: pistas de exemplo (ajuste os CITIZENID antes)

   O cw-racingapp.sql recria a race_tracks. Se você já tem essa tabela de uma versão anterior, faça backup antes.

3. Cadastre o item racing_gps no seu inventário (o nome vem de Config.ItemName.gps) e copie items/racing_gps.png para a pasta de imagens do inventário. O item é registrado como usável pelo bridge e abre o app.
4. Adicione ao server.cfg:

   ensure cw-performance
   ensure cw-racingapp
5. Ajuste o config.lua — em especial Config.Locale, Config.Inventory, Config.Payments e Config.Classes.

Permissões (ACE)

Os comandos administrativos são registrados como restritos, exigindo a ACE command.<nome>:

add_ace group.admin command.createracinguser allow
add_ace group.admin command.remracename allow
add_ace group.admin command.racingappcurated allow

Todos esses comandos só são registrados quando Config.Debug = true. Com o debug desligado (padrão), eles não existem — nem para a ACE.

A permissão do que cada jogador pode fazer dentro do app não usa ACE: ela vem do tipo de usuário salvo na tabela racer_names.

Tipos de usuário do app

Definidos em Config.Permissions. Cada racer name tem um tipo (auth) gravado no banco.

Se Config.AllowAnyoneToCreateUserInApp = true, qualquer um cria o próprio usuário com o tipo Config.BasePermission (padrão racer). Se o banco não tiver nenhum usuário, o primeiro criado vira god automaticamente.

Usuários também podem ser comprados no NPC trader ou no laptop (veja Config.Trader e Config.Laptop).

Configuração

Tudo em config.lua.

Geral

Corridas

Pistas e recordes

Nomes de corredor

GPS e checkpoints

Trader e laptop

Dois pontos onde se compra um usuário do app.

Config.AllowedJobs mapeia job → tipos de usuário que aquele job pode comprar. Só tem efeito com jobRequirement ativo.

Comandos

Cliente (sempre disponíveis)

Servidor (só com Config.Debug = true, restritos por ACE)

Criador de pistas

Requer a permissão create (tipo creator ou superior). As teclas vêm de Config.Buttons e, com Config.UseOxLibForKeybind = true, são remapeáveis pelo jogador nas configurações do FiveM.

Regras: mínimo de Config.MinimumCheckpoints (10) checkpoints; tamanho entre MinTireDistance e MaxTireDistance; nome entre MinTrackNameLength e MaxTrackNameLength. Passar de Config.MaxCheckpoints (60) gera aviso — e, na prática, pode travar os clientes.

Racing Crypto e pagamentos

O recurso tem um crypto próprio (Config.Payments.cryptoType, padrão RAC), guardado na coluna crypto da tabela racer_names.

Config.Payments define qual moeda é usada em cada fluxo:

Config.Options controla a conversão: conversionRate (dinheiro x taxa = crypto), sellCharge (% perdido na venda) e as flags allowBuyingCrypto, allowSellingCrypto e allowTransferCrypto. Se as três forem false, não há como abrir o menu de crypto.

Prêmios de participação

São dois sistemas distintos:

• Config.ParticipationTrophies — automático. Só paga se as condições forem atendidas: requireCurated, requireRanked, requireBuyIns com buyInMinimum, minimumOfRacers (padrão 6) e minumumRaceLength. O valor por posição vem de amount.
• Config.ParticipationAmounts — manual, para quem tem a permissão setupParticipation. positionBonuses dá um bônus percentual extra ao pódio.

Corridas automatizadas

Config.AutomatedRaces é a lista de corridas que o servidor hospeda sozinho, em rodízio.

{
    trackId = 'CW-7666',        -- id da pista (veja no app ou na tabela race_tracks)
    laps = 2,                   -- 0 = sprint, -1 = eliminação
    racerName = 'AutoMate',     -- nome do host
    maxClass = 'A',
    ghostingEnabled = false,
    ghostingTime = 0,
    buyIn = 1,
    ranked = true,
    reversed = false,
    participationMoney = 100,
    participationCurrency = Config.Payments.participationPayout,
    firstPerson = false
}

Config.AutomatedOptions controla o rodízio: timeBetweenRaces (ms entre corridas), minimumParticipants e os payouts extras (participation, winner e perRacer, que multiplica pelo número de corredores).

Bounties

Time trials: bata o tempo alvo numa pista e classe específicas para receber o prêmio.

{
    trackId = 'CW-7666',
    maxClass = 'A',
    reversed = false,
    timeToBeat = 31787,   -- em ms
    extraTime = 5000,     -- folga aleatória somada ao alvo na geração
    price = 200,
    sprint = false,       -- exige que seja sprint
    rankRequired = 2,     -- opcional; senão usa defaultRankRequirement
}

Config.BountiesOptions define quantos bounties existem por vez (minAmount / maxAmount), se pode repetir pista (allowMultipleOnSameTrack) ou classe (allowMultipleInSameClass), o rank mínimo padrão (defaultRankRequirement) e o consecutiveMultiplier — quanto do prêmio original o jogador ganha ao bater o próprio tempo de novo (0.5 = 50%).

Config.FirstBountiesGenerateStartTime é o atraso (ms) até a primeira geração de bounties após o start do recurso.

ELO e ranqueadas

Corridas ranqueadas movem o ranking do racer name. Config.EloPunishments define o que é descontado por comportamento ruim:

Só quem tem a permissão startRanked (master ou god) pode iniciar uma corrida ranqueada.

Banco de dados

Três tabelas.

Integrações

cw-performance

Dependência declarada no manifest. É de onde vêm as classes de veículo (C, B, A, S…). Só use em Config.Classes classes que existam no cw-performance.

ox_target

Com Config.UseOxTarget = true, o NPC trader e o laptop viram alvos do ox_target.

ox_inventory / qb-inventory

Definido em Config.Inventory. O item racing_gps é registrado como usável pelo bridge do framework ativo e abre o app ao ser usado.

ox_lib

Keybinds do criador de pistas (Config.UseOxLibForKeybind), notificações (Config.OxLibNotify) e diálogos de input (Config.OxInput).

Entrypoints para outros recursos

Exports de cliente

exports['cw-racingapp']:openRacingApp()               -- abre a UI
exports['cw-racingapp']:IsInRace()                    -- bool
exports['cw-racingapp']:IsInEditor()                  -- bool
exports['cw-racingapp']:joinRace(raceId)              -- bool; exige estar dirigindo
exports['cw-racingapp']:getAvailableTracks()          -- pistas visíveis para o usuário atual
exports['cw-racingapp']:getAvailableRaces()           -- corridas abertas
exports['cw-racingapp']:attemptSetupRace(setupData)   -- hospeda uma corrida

attemptSetupRace espera uma tabela com track (trackId), laps, maxClass, ghostingOn, ghostingTime, buyIn, ranked, reversed, participationMoney, participationCurrency, firstPerson e silent. Retorna false se o jogador não estiver ao volante ou se a classe do carro não for permitida.

Exports de servidor

exports['cw-racingapp']:openRacingApp(source)                        -- abre a UI para um jogador
exports['cw-racingapp']:getRacerCrypto(racerName)                    -- saldo de crypto
exports['cw-racingapp']:hasEnoughCrypto(racerName, amount)           -- bool
exports['cw-racingapp']:addRacerCrypto(racerName, amount)            -- bool
exports['cw-racingapp']:removeCrypto(racerName, amount)              -- bool; false se não tiver saldo
exports['cw-racingapp']:getRacingUsersByCitizenId(citizenId)         -- lista de usuários
exports['cw-racingapp']:getRacingUsersBySrc(src)                     -- lista de usuários

Localização

Os arquivos ficam em locales/, carregados como shared_scripts. Cada um define uma variável global (TranslationsEN, TranslationsPT), e Config.Locale aponta para a variável desejada — não é a convar ox:locale nem uma string:

Config.Locale = TranslationsPT

Idiomas incluídos: en.lua (TranslationsEN) e pt-br.lua (TranslationsPT). O padrão deste fork é português.

Para adicionar um idioma, crie locales/<codigo>.lua com uma variável global nova, adicione o arquivo aos shared_scripts do fxmanifest.lua e aponte Config.Locale para ela. Chaves ausentes caem no próprio nome da chave.

Estrutura de arquivos

cw-racingapp/
├── bridge/
│   ├── client/           — qbox.lua, qb.lua, ox.lua, esx.lua: dados do jogador por framework
│   └── server/           — qbox.lua, qb.lua, ox.lua, esx.lua: dinheiro, citizenid, item usável
├── client/
│   ├── main.lua          — corrida, checkpoints, HUD, criador de pistas, NUI, keybinds, exports
│   ├── functions.lua     — helpers de cliente
│   └── classes.lua       — classes de veículo via cw-performance
├── server/
│   ├── main.lua          — corridas, setup, callbacks, comandos admin, export openRacingApp
│   ├── database.lua      — camada RADB: queries de pistas, usuários e crypto
│   ├── functions.lua     — callbacks de servidor e helper registerCommand
│   ├── crypto.lua        — saldo, compra, venda e transferência de RAC (exports)
│   ├── crews.lua         — crews e comandos de crew
│   ├── elo.lua           — ranking das corridas ranqueadas
│   └── bounties.lua      — geração e resgate de bounties
├── html/
│   ├── dist/             — build da UI (Vue) servida como ui_page
│   └── src/              — fonte da UI
├── locales/
│   ├── en.lua            — TranslationsEN
│   └── pt-br.lua         — TranslationsPT
├── items/
│   └── racing_gps.png    — imagem do item
├── config.lua            — toda a configuração
├── cw-racingapp.sql      — tabelas race_tracks e racer_names
├── cw-racingcrews.sql    — tabela racing_crews
├── default_tracks.sql    — pistas de exemplo (opcional)
├── README.md
├── LICENSE
└── fxmanifest.lua