Kodara Studio

Kodara Studio / AutoEscola

Documentação da AutoEscola

Voltar para a página do script

Requisitos

  • OneSync ligado (padrão do txAdmin). Se estiver desligado, o console avisa na partida.
  • oxmysql, inclusive no standalone (as carteiras e os ajustes ficam no banco).
  • Um dos frameworks: Qbox, QBCore, ESX Legacy (testado na 1.16) — ou nenhum (standalone).
  • Servidor FiveM com artefato recente (o do txAdmin atual serve).

Instalação

  1. Coloque a pasta autoescola em resources.
  2. No server.cfg, depois do framework e do oxmysql, acrescente as linhas abaixo.
ensure autoescola
add_ace group.admin autoescola.admin allow
# opcional: registro no Discord (fica só no servidor, nunca vai pro jogador)
set autoescola_webhook "https://discord.com/api/webhooks/..."
  1. Reinicie o servidor. As tabelas são criadas sozinhas (autoescola.sql é só pra quem não tem permissão de CREATE no banco).
  2. No console deve aparecer [autoescola] framework detectado: ... e [autoescola] pronto.
  3. Se alguma carteira estiver sem percurso, sem veículo, sem perguntas ou com preço inválido, aparece uma linha vermelha carteira X INDISPONÍVEL dizendo o que falta. Essa carteira aparece como Indisponível no menu e ninguém paga por ela até você arrumar.
  4. Entre no jogo e abra /autoescola. A aba Início mostra o que falta configurar.

Quem é admin: quem tem a permissão ACE autoescola.admin (vale em qualquer framework). No ESX e no QBCore também vale o grupo admin, god ou superadmin (Config.AdminGroups). No Qbox e no standalone é só pela ACE (add_principal identifier.fivem:SEU_ID group.admin).

Ordem errada no server.cfg: se a autoescola estiver antes do framework, ela espera o framework ligar. Se ele não ligar em 15 s, aparece um aviso vermelho ESPERANDO O FRAMEWORK e ela fica desligada até você resolver. Servidor sem framework que tem uma pasta de framework parada em resources: ponha Config.Framework = 'standalone' no config.lua.

Atualizar para uma versão nova

  1. Guarde uma cópia da pasta autoescola que está no servidor (ali estão os arquivos que você mudou: config.lua, config_server.lua, locales.lua, a pasta locales/, server/questions.lua, bridge.lua e html/config.css).
  2. Apague a pasta antiga e coloque a nova inteira no lugar. Não misture arquivos de versões diferentes.
  3. Refaça nos arquivos novos as mudanças que você tinha feito (compare com a cópia do passo 1).
  4. Reinicie o servidor inteiro, ou digite no console refresh e depois restart autoescola. Só o restart autoescola não basta: se a versão nova trouxe um arquivo novo, aparece erro attempt to call a nil value. Confira no console a linha [autoescola] pronto.

Se você mudou a tela (pasta html/), troque a pasta html/ inteira pela nova e refaça suas mudanças nela.

O que foi salvo pelo painel (preços, percursos, veículos, cores, idioma, recepção) e as carteiras dos jogadores ficam no banco de dados: nada disso se perde na atualização.

Os dois arquivos de configuração

ArquivoQuem lêO que tem
config.luaservidor e o jogo de cada jogadorIdioma, framework, comandos, recepção (NPC e ícone), tecla ou ox_target/qb-target, unidade de velocidade, instrutor (e a voz dele), som do resultado
config_server.luasó o servidorDinheiro, permissão de admin, regras e limites das provas, proteção contra teleporte, trava de direção, exports e as 7 carteiras (preços, veículos e percursos)

Tudo o que está no config.lua é baixado pelos jogadores; por isso as regras ficam no config_server.lua. Não coloque nada sensível no config.lua. O webhook do Discord não fica em nenhum dos dois: é um convar do server.cfg.

Quase tudo também se ajusta pelo painel, sem editar arquivo e sem reiniciar.

O que você salva no painel vale mais que o arquivo. Depois que um ajuste é salvo pelo painel, o valor gravado no banco passa a valer no lugar do config.lua / config_server.lua. Na partida o console mostra uma linha ajustes salvos pelo painel valendo no lugar do config: ... com a lista. Pra mudar esses itens, use o painel.

Primeira configuração

Tudo pelo painel (/autoescola).

  1. Recepção (NPC das provas): de fábrica fica na Legion Square. Para mudar: Ajustes → "Recepção da autoescola" → digite X, Y, Z e a direção, ou vá até o lugar e clique em Usar minha posição → Salvar recepção. Muda na hora para todos.
  2. Idioma: Ajustes → Idioma (Português, English, Español, Deutsch, Français, Italiano, Türkçe). Vale na hora para todos.
  3. Preços, espera e erros: Provas → escolha a carteira. "Reprova com (erros)" é o número de erros que reprova: com 5, o 5º erro já reprova. A espera pra refazer a prova vem em 120 s em todas as carteiras.
  4. Veículo da prova: na mesma tela, digite o nome de spawn e clique em Trocar. O jogo confere se o modelo existe (inclusive add-on) e se é do tipo certo.
  5. Percurso: Gravar percurso te leva ao ponto de partida já dentro do veículo. Dirija, use Parada obrigatória aqui nos cruzamentos e volte ao início: fecha sozinho. Se sair do jogo ou cancelar no meio, o percurso anterior não é perdido. Restaurar padrão devolve o percurso e o ponto de partida de fábrica.

Para aeronave, grave voando — a altura conta.

Toda vez que um percurso ou a recepção é salvo, o script grava uma cópia em rotas.json dentro da pasta do resource (serve de backup e pra levar a configuração pra outro servidor). É normal esse arquivo aparecer ali.

Como a prova funciona

  • Matrícula (paga uma vez) → teórica → prática. Reprovou? Refaz só a etapa que falhou, com taxa e tempo de espera configuráveis.
  • Teórica: o aluno responde com o mouse ou com as teclas A, B, C, D (ou 1, 2, 3, 4).
  • Pré-requisitos: caminhão e ônibus exigem carro; carreta exige caminhão.
  • Velocidade: o limite sobe do primeiro ponto até o meio do percurso e desce até o fim. Acima do limite + tolerância (5 km/h) conta erro na hora. No placar, a velocidade fica amarela acima do limite (dentro da tolerância, sem erro) e vermelha acima do limite + tolerância (quando o erro conta).
  • Paradas obrigatórias: o aluno tem que parar de verdade (abaixo de 3 km/h) dentro do ponto.
  • Erros que reprovam na hora: sair do veículo, destruir o veículo, morrer, estourar o tempo, sair do percurso e não voltar a tempo, soltar o reboque. Por categoria, pedHitFail = true reprova ao atropelar um pedestre e damageFail reprova quando o dano passa do valor.
  • Sair do percurso: o servidor compara o veículo com a trilha gravada (tolerância de 35 m, Config.PathTolerance). Quem sai e fica uns 4 s andando sem chegar mais perto do ponto recebe o aviso "Você saiu do percurso", e tem 8 s (Config.OffRouteSeconds) pra voltar à trilha. Voltou: a prova segue. Não voltou: reprova.
  • Teórica rápida demais: quem entrega a teórica mais rápido que Config.TheoryMinSecondsPerQuestion (2 s por pergunta de fábrica; 0 desliga) é reprovado e fica um registro de suspeita.
  • Teleporte: se o veículo "pula" mais do que conseguiria andar, a prova é reprovada com o motivo "movimento impossível", fica um registro practical_suspect e os admins online são avisados. Lag de verdade não reprova. Ajustes em Config.AntiTeleport. Se um admin teleportar um aluno durante a prova, ela também reprova.
  • Prova cancelada (falha do servidor): se o veículo da prova sumir ou for destruído antes de o aluno usar, a prova é cancelada: não conta tentativa, não tem espera e a taxa é devolvida. Os admins online são avisados.
  • Unidade: km/h ou mph conforme a configuração do GTA de cada jogador (Config.SpeedUnit = 'auto').
  • Dimensão privada: sempre ligada. Durante a prova o aluno fica invisível para os outros jogadores. O script usa as dimensões 7301 a 7556 de fábrica. Se outro script usa essa faixa, mude Config.PrivateExam.bucketBase.
  • Quem pode começar uma prova: de fábrica, qualquer um. Para bloquear (por exemplo, algemado ou caído), escreva a sua regra em Config.CanStartExam no config_server.lua; tem um exemplo pronto lá.
  • Ao aprovar a carteira é emitida sozinha e espelhada no framework: metadata.licences no Qbox/QBCore e esx_license no ESX.
  • Chave do veículo da prova: entregue automaticamente em qbx_vehiclekeys, qb-vehiclekeys, wasabi_carlock, Renewed-Vehiclekeys e cd_garage. Outro sistema: escreva uma função em Config.VehicleKeys.

Trava de direção

Tudo em Config.Enforcement (no config_server.lua) e no painel (Veículos e Ajustes).

  • Bloqueio ligado (padrão): quem não tem a carteira não dirige (o motor desliga e o jogador sai do banco; block.mode = 'engine' só desliga o motor).
  • Burla do bloqueio: se a pessoa barrada continua no volante, com o motor ligado, e o veículo anda mais de 40 m (bypassDistance), os admins são avisados, fica no registro e dispara o evento autoescola:possibleBypass. Isso é sempre uma suspeita pra um admin conferir, não uma prova.
  • Opção block.onBypass = 'delete' (vem desligada): além de avisar, o servidor apaga o veículo de quem burlou. Cuidado: apaga mesmo que o veículo seja de outro jogador ou uma viatura.
  • Bloqueio desligado: a pessoa dirige, leva multa e a polícia recebe o alerta no mapa.
  • Categoria do veículo: pelo tipo (carro, moto, avião/helicóptero, barco) e pela lista de modelos (caminhão, ônibus, cavalo mecânico). Quem tem caminhão, ônibus ou carreta também dirige carro.
  • Veículos de emergência: viatura, ambulância e bombeiro só para quem é da corporação e está em serviço. No painel dá pra escolher os empregos. Cada veículo pode ter dono: Veículos → "Veículo de emprego" e marque quais empregos podem dirigir.
  • Veículo de mod: cadastre em Veículos como Precisa de carteira, Veículo de emprego ou Livre.
  • Sem framework não existe emprego: viaturas ficam livres (emergency.standaloneFree = true).
  • Bicicletas são livres. Exceções: exemptModels, exemptJobs, exemptAdmins.
  • Veículo de emprego dispensa a carteira da categoria.
  • No ar: quem assume o comando de uma aeronave sem carteira tem o motor cortado.

Standalone, ESX, QBCore e Qbox

  • Standalone: provas grátis (Config.StandaloneFree = true), carteira guardada pelo license: do jogador, sem multa e viaturas livres.
  • ESX: se uma carteira não existir na tabela licenses, o console avisa uma vez com o comando pra cadastrar, por exemplo INSERT INTO licenses (type, label) VALUES ('drive_bus', 'Ônibus');. A autoescola funciona mesmo sem isso; só não aparece em outros scripts do ESX.
  • QBCore e Qbox: todo personagem novo já nasce com licences.driver = true. A trava funciona do mesmo jeito, mas outros scripts que olham o metadata.licences vão mostrar "habilitado" pra quem nunca fez prova. Se isso incomodar, faça os outros scripts usarem o export HasLicense.

Comandos

ComandoQuemO que faz
/autoescolaadminAbre o painel. Também: /drivingschool, /autoescuela, /fahrschule, /autoecole, /autoscuola, /surucukursu
/ae escolaadminMarca a recepção onde você está
/ae spawn <cat>adminMarca o ponto de partida da carteira
/ae ir <cat> · /ae ir x y [z]adminVai até o ponto de partida ou até uma coordenada
/ae gravar <cat> · /ae gravar <cat> aquiadminGrava o percurso
/ae parada · /ae pararadminMarca parada obrigatória · encerra a gravação
/ae ver <cat>adminMostra o percurso por 60 s
/ae rota <cat> add [km/h] [parar] [fala] | desfazer | limpar | padraoadminEdição manual do percurso
/desistirjogadorDesiste da prova prática (conta como reprovação). Também: /giveup, /abandonar, /abbrechen, /abandonner, /abbandona, /vazgec
aefechar (F8)jogadorFecha qualquer tela da autoescola e devolve o mouse

Todos os nomes funcionam sempre, em qualquer idioma. Pra mudar ou usar um nome só, edite Config.Commands no config.lua. Categorias: carro/car, moto, caminhao/truck, onibus/bus, carreta/trailer, aeronave/air, barco/boat.

Exports e eventos

No servidor:

exports.autoescola:HasLicense(source_ou_identifier, 'car')   -- true/false
exports.autoescola:GetAllLicenses(source_ou_identifier)      -- { 'car', 'moto' }
exports.autoescola:IsInExam(source)
exports.autoescola:CanDrive(source, netId)                    -- a mesma resposta da trava de direção
exports.autoescola:GiveLicense(source_ou_identifier, 'boat', 'quem_emitiu')   -- escrita
exports.autoescola:RemoveLicense(source_ou_identifier, 'car', 'motivo')       -- escrita
exports.autoescola:ExemptVehicle(netId, true)                                  -- escrita

Ler é livre. Escrever vem desligado de fábrica: ligue Config.Exports.allowWrite = true e coloque o nome do resource em Config.Exports.whitelist (lista vazia nega todos). Toda escrita vai pro registro com o nome do resource.

HasLicense pode consultar o banco na primeira vez que pergunta por um jogador (depois fica na memória). Se você chama dentro de um laço rápido, guarde a resposta em vez de perguntar a cada quadro.

No cliente, exports.autoescola:HasLicense('car') serve só pra enfeite de interface. Pra decidir qualquer coisa, use o export do servidor.

Eventos de servidor (despacho, anticheat). Use AddEventHandler, nunca RegisterNetEvent:

AddEventHandler('autoescola:driverWithoutLicense', function(src, categoria, coords, multa)
    -- alguém dirigindo sem carteira (ligue no seu despacho: ps-dispatch, cd_dispatch...)
end)

AddEventHandler('autoescola:possibleBypass', function(src, veiculo, placa)
    -- SUSPEITA de bloqueio burlado. Avise a equipe; não use pra banir sozinho.
end)

possibleBypass é suspeita, não prova. Ligue num aviso pra equipe, não num banimento automático.

Recepção, som e voz do instrutor

De fábrica o jogador chega perto do NPC e aperta E. Para usar o "olhar e clicar" do seu servidor, mude no config.lua:

Config.Interact = { ..., target = 'auto' }   -- 'none' (tecla E) | 'auto' | 'ox_target' | 'qb-target'

'auto' usa o ox_target se ele estiver ligado, senão o qb-target, senão a tecla E.

Som do resultado: quando a prova termina, toca um som do próprio GTA (aprovado ou reprovado). Para trocar ou desligar, mude Config.Sounds no config.lua (enabled = false desliga).

Voz do instrutor: o NPC reage com vozes do próprio GTA (em inglês). Só o aluno ouve. Para trocar ou desligar, mude Config.Instructor.voice no config.lua (voice = false deixa ele calado).

Cores das telas

Pelo painel: /autoescola → aba Aparência. Escolha um tema pronto (amarelo, azul, verde, roxo, laranja) ou mexa nas cores e digite o código #rrggbb. Salvar para todos vale na hora para todos os jogadores. Voltar ao padrão apaga as cores do painel. Só admin consegue salvar.

Pelo arquivo: as cores de fábrica ficam em html/config.css. Cada cor é escrita em R, G, B (ex.: --ae-accent: 30, 110, 230;). Salve, dê restart autoescola e reabra a tela. A cor salva pelo painel passa por cima da do arquivo.

Idiomas e textos

locales.lua tem os textos em português, inglês e espanhol, e a pasta locales/ tem alemão, francês, italiano e turco. server/questions.lua tem as perguntas da teórica nos 7 idiomas. Tudo aberto para editar.

Para criar outro idioma, copie locales/de.lua, troque o nome (ex.: locales/pl.lua e Locales.pl), traduza e acrescente as perguntas em server/questions.lua (Questions.pl). O idioma novo aparece sozinho na lista de Ajustes → Idioma. Texto que faltar cai no português.

As perguntas de fábrica são iguais pra todo mundo que comprou o script. Vale trocar algumas e acrescentar as suas (quanto mais perguntas, mais difícil decorar).

Banco de dados

Tabelas criadas sozinhas (em utf8mb4): autoescola_licenses, autoescola_progress, autoescola_attempts, autoescola_logs, autoescola_names, autoescola_settings, autoescola_mirror.

Se aparecer Incorrect string value no console, converta uma vez: ALTER TABLE autoescola_logs CONVERT TO CHARACTER SET utf8mb4; (repita pras outras 6).

Limpeza automática: o registro de ações é apagado depois de 90 dias e o histórico de provas depois de 365 dias (Config.Retention; 0 = nunca apaga). Carteiras, matrículas e ajustes nunca são apagados.

Problemas comuns

  • ESPERANDO O FRAMEWORK: o ensure autoescola tem que vir depois do framework. Sem framework, ponha Config.Framework = 'standalone'.
  • ainda NÃO está pronta: a autoescola não conseguiu falar com o banco. Veja os erros do oxmysql acima e a mysql_connection_string.
  • "Prova cancelada" ou veículo da prova some ao nascer: algum script de lista de veículos proibidos (ou anticheat) está apagando o modelo. Troque o modelo no painel ou libere na lista.
  • Texto estranho (como step_of) depois de atualizar: ficaram arquivos de versões diferentes misturados. Refaça a atualização inteira.
  • attempt to call a nil value depois de atualizar: o script foi religado só com restart autoescola. Digite refresh e depois restart autoescola (ou reinicie o servidor).
  • Painel não abre: confira a linha add_ace group.admin autoescola.admin allow e se sua conta está no group.admin.
  • carteira X INDISPONÍVEL: a linha diz o que falta (percurso, veículo, perguntas, preço). Arrume no painel ou no config_server.lua e reinicie o script.
  • NPC da recepção não aparece: se o modelo de Config.School.ped não existir, o F8 avisa e a recepção passa a funcionar com o marcador amarelo.
  • Mouse preso depois de um erro de tela: digite aefechar no F8.
  • Percursos de fábrica foram gravados no mapa padrão do GTA. Com mapa que muda essas ruas, regrave pelo painel.
  • Aluno honesto reprovado por "movimento impossível": só acontece com travadas muito longas do jogo dele. Dá pra afrouxar em Config.AntiTeleport (lagSeconds, margin) ou desligar (enabled = false). Não baixe o maxKmh.
  • Diagnóstico: Config.Debug = true mostra mensagens DIAG no console e no F8. Deixe false em produção.