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
- Coloque a pasta
autoescolaemresources. - 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/..."
- Reinicie o servidor. As tabelas são criadas sozinhas (
autoescola.sqlé só pra quem não tem permissão de CREATE no banco). - No console deve aparecer
[autoescola] framework detectado: ...e[autoescola] pronto. - Se alguma carteira estiver sem percurso, sem veículo, sem perguntas ou com preço inválido, aparece uma linha vermelha
carteira X INDISPONÍVELdizendo o que falta. Essa carteira aparece como Indisponível no menu e ninguém paga por ela até você arrumar. - 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
- Guarde uma cópia da pasta
autoescolaque está no servidor (ali estão os arquivos que você mudou:config.lua,config_server.lua,locales.lua, a pastalocales/,server/questions.lua,bridge.luaehtml/config.css). - Apague a pasta antiga e coloque a nova inteira no lugar. Não misture arquivos de versões diferentes.
- Refaça nos arquivos novos as mudanças que você tinha feito (compare com a cópia do passo 1).
- Reinicie o servidor inteiro, ou digite no console
refreshe depoisrestart autoescola. Só orestart autoescolanão basta: se a versão nova trouxe um arquivo novo, aparece erroattempt 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
| Arquivo | Quem lê | O que tem |
|---|---|---|
config.lua | servidor e o jogo de cada jogador | Idioma, 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.lua | só o servidor | Dinheiro, 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).
- 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.
- Idioma: Ajustes → Idioma (Português, English, Español, Deutsch, Français, Italiano, Türkçe). Vale na hora para todos.
- 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.
- 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.
- 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 = truereprova ao atropelar um pedestre edamageFailreprova 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_suspecte os admins online são avisados. Lag de verdade não reprova. Ajustes emConfig.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.CanStartExamnoconfig_server.lua; tem um exemplo pronto lá. - Ao aprovar a carteira é emitida sozinha e espelhada no framework:
metadata.licencesno Qbox/QBCore eesx_licenseno ESX. - Chave do veículo da prova: entregue automaticamente em
qbx_vehiclekeys,qb-vehiclekeys,wasabi_carlock,Renewed-Vehiclekeysecd_garage. Outro sistema: escreva uma função emConfig.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 eventoautoescola: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 pelolicense: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 exemploINSERT 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 ometadata.licencesvão mostrar "habilitado" pra quem nunca fez prova. Se isso incomodar, faça os outros scripts usarem o exportHasLicense.
Comandos
| Comando | Quem | O que faz |
|---|---|---|
/autoescola | admin | Abre o painel. Também: /drivingschool, /autoescuela, /fahrschule, /autoecole, /autoscuola, /surucukursu |
/ae escola | admin | Marca a recepção onde você está |
/ae spawn <cat> | admin | Marca o ponto de partida da carteira |
/ae ir <cat> · /ae ir x y [z] | admin | Vai até o ponto de partida ou até uma coordenada |
/ae gravar <cat> · /ae gravar <cat> aqui | admin | Grava o percurso |
/ae parada · /ae parar | admin | Marca parada obrigatória · encerra a gravação |
/ae ver <cat> | admin | Mostra o percurso por 60 s |
/ae rota <cat> add [km/h] [parar] [fala] | desfazer | limpar | padrao | admin | Edição manual do percurso |
/desistir | jogador | Desiste da prova prática (conta como reprovação). Também: /giveup, /abandonar, /abbrechen, /abandonner, /abbandona, /vazgec |
aefechar (F8) | jogador | Fecha 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: oensure autoescolatem que vir depois do framework. Sem framework, ponhaConfig.Framework = 'standalone'.ainda NÃO está pronta: a autoescola não conseguiu falar com o banco. Veja os erros do oxmysql acima e amysql_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 valuedepois de atualizar: o script foi religado só comrestart autoescola. Digiterefreshe depoisrestart autoescola(ou reinicie o servidor).- Painel não abre: confira a linha
add_ace group.admin autoescola.admin allowe se sua conta está nogroup.admin. carteira X INDISPONÍVEL: a linha diz o que falta (percurso, veículo, perguntas, preço). Arrume no painel ou noconfig_server.luae reinicie o script.- NPC da recepção não aparece: se o modelo de
Config.School.pednã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
aefecharno 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 omaxKmh. - Diagnóstico:
Config.Debug = truemostra mensagensDIAGno console e no F8. Deixefalseem produção.
