server.cfg

O server.cfg fica na raiz da pasta do servidor e é lido uma única vez, na inicialização. Alterações exigem reiniciar o servidor.

Sintaxe

Cada linha é um comando seguido de argumentos, separados por espaços ou tabs.

# comentário de linha inteira
sets sv_projectName "Meu Servidor"   // comentário no fim da linha

• # e // iniciam um comentário que vai até o fim da linha.
• Aspas duplas agrupam valores com espaços: "Meu Servidor".
• Dentro de aspas, \" produz uma aspa literal e \\ produz uma barra invertida.
• O nome do comando não diferencia maiúsculas de minúsculas; o nome das convars diferencia.
• Linhas vazias são ignoradas. Diretivas desconhecidas são ignoradas com um aviso no console.

Diretivas

Endpoints

endpoint_add_udp    "0.0.0.0:22003"
endpoint_add_tcp    "0.0.0.0:22005"
endpoint_add_voice  "0.0.0.0:22007"

Diretiva	Efeito	Padrão
endpoint_add_udp	Endereço e porta do tráfego de jogo. Define o bind address de todo o servidor.	0.0.0.0:22003
endpoint_add_tcp	Porta HTTP, usada para download de assets. Apenas a porta é aplicada; o IP acompanha o endpoint UDP.	0.0.0.0:22005
endpoint_add_voice	Porta do chat de voz. Declarar esta linha ativa o voice.	0.0.0.0:22007

O valor precisa estar no formato ip:porta, com a porta entre 1 e 65535. Um endpoint inválido é descartado e o padrão é mantido.

Nota

Para desligar o voice, remova (ou comente) a linha endpoint_add_voice. Se preferir manter a linha, use set voice_enabled false — a convar tem a palavra final.

Resources

ensure spawn-demo
ensure respawn

ensure <nome> inicia um resource junto com o servidor. Os resources sobem na ordem em que aparecem no arquivo, então declare primeiro aquilo de que os outros dependem.

start <nome> é aceito como sinônimo de ensure.

Os nametags vêm de um resource

O cliente não desenha os nametags dos jogadores sozinho. Quem os desenha é o resource nametags, que vem no grupo [mtax] e lê o que setPlayerNametagText, setPlayerNametagColor e setPlayerNametagShowing definem. Sem ele rodando, os jogadores não veem nametag nenhum — mantenha o ensure [mtax] ou distribua um resource seu que os desenhe.

Ícone do servidor

load_server_icon logo.png

Caminho, relativo à pasta do servidor, do ícone exibido na lista de servidores.

O arquivo precisa ser um PNG ou JPEG de no máximo 1 MiB e 500×500 pixels. Um arquivo que não abre, está em outro formato ou passa de qualquer um dos limites é descartado com um aviso no console na inicialização, e o servidor roda sem ícone.

Limite de jogadores

sv_maxclients 32

Atalho para set sv_maxclients 32. As duas formas são equivalentes. O valor vai de 1 a 4096: 0 vira 1 e qualquer coisa acima de 4096 vira 4096, com um aviso no console.

Incluir outro arquivo

exec configs/voice.cfg

Lê outro arquivo de configuração. O caminho é relativo à pasta do arquivo que fez o exec. O aninhamento é limitado a 8 níveis; além disso o arquivo é ignorado com um aviso.

ACL (reservada)

add_principal resource.admin group.admin
remove_principal resource.admin group.admin
add_ace group.admin command.restart allow
remove_ace group.admin command.restart allow

As diretivas add_principal, remove_principal, add_ace e remove_ace já são reconhecidas e carregadas. O modo de uma ACE deve ser allow ou deny.

Perigo

A ACL ainda não é aplicada por nenhuma operação nesta versão. O servidor exibe um aviso ao carregar essas diretivas; não as use como controle de acesso. Faça a validação de permissão dentro do handler Lua.

Convars

Convars são pares chave/valor. A diferença entre os três comandos é a visibilidade:

Comando	Visibilidade
set	Fica apenas no servidor.
sets	Replicada — publicada para os clientes e para a lista de servidores.
setr	Replicada — idêntica a sets.

Perigo

Nunca use sets ou setr para valores sensíveis (senhas, chaves de API, tokens): eles são publicados. Use sempre set.

Valores booleanos aceitam true/1/yes/on e false/0/no/off, sem diferenciar maiúsculas.

Identidade do servidor

Convar	Tipo	Padrão	Descrição
sv_projectName	texto	MTAX Server	Nome exibido na lista de servidores. Até 64 caracteres.
sv_projectDesc	texto	(vazio)	Descrição curta do servidor. Até 256 caracteres.
locale	texto	en-US	Região anunciada pelo servidor, no formato pt-BR. Não altera o idioma da interface.
tags	texto	(vazio)	Tags separadas por vírgula, usadas na busca. Até 128 caracteres.
banner_detail	URL	(vazio)	Banner exibido nos detalhes do servidor.
banner_connecting	URL	(vazio)	Banner exibido durante a conexão.
store_url	URL	(vazio)	Link para a loja do servidor.
discord_url	URL	(vazio)	Link do Discord da comunidade.

Esses valores são exibidos aos jogadores, então declare-os com sets:

sets locale          "pt-BR"
sets sv_projectName  "Meu Servidor"
sets sv_projectDesc  "Roleplay brasileiro"
sets tags            "roleplay, brasil"
sets discord_url     "https://discord.gg/exemplo"

Os limites contam caracteres, não bytes, então nomes acentuados não saem prejudicados. Um valor mais longo é cortado no limite, caracteres de controle são removidos, espaços no fim são aparados e o console imprime um aviso; o servidor sobe mesmo assim. Um nome que fique vazio depois disso volta para MTAX Server.

Acesso e capacidade

Convar	Tipo	Padrão	Descrição
sv_maxclients	inteiro	32	Número máximo de jogadores simultâneos, de 1 a 4096. Valores fora da faixa são ajustados, com um aviso.
sv_password	texto	(vazio)	Senha de entrada. Máximo de 32 caracteres, sem espaços. Vazio desativa.
sv_licenseKey	texto	(vazio)	Chave obrigatória de licença do servidor, com 64 caracteres hexadecimais.
sv_elementDataWhitelist	booleano	false	Recusa toda escrita de dado de elemento vinda de um cliente, a menos que um script tenha aberto aquela chave explicitamente.

sv_maxclients 64
set sv_password    "minhasenha"
set sv_licenseKey  "..."
set sv_elementDataWhitelist  1

O sv_elementDataWhitelist decide quem pode escrever dados de elemento

Clientes conseguem escrever dados de elemento, e este interruptor é o que o servidor confere quando nada mais específico foi definido para a chave.

Com a lista branca desligada — o padrão —, um cliente pode escrever em qualquer chave que não tenha sido explicitamente negada. Com ela ligada, um cliente não pode escrever em nada até um script abrir a chave com setElementData(elemento, chave, valor, sincronizacao, "allow").

Ligue em qualquer coisa competitiva: é a diferença entre um cliente modificado poder inventar os próprios valores e não poder. De um jeito ou de outro, uma escrita recusada nunca é aplicada, e ela dispara o onPlayerChangesProtectedData — veja o setElementData para a definição por chave.

Cuidado

sv_password e sv_licenseKey precisam usar set. Se forem declaradas com sets/setr, o servidor emite um aviso e não publica o valor.

Uma senha com espaços ou acima de 32 caracteres é rejeitada e o servidor sobe sem senha — confira o console na inicialização.

Sem uma sv_licenseKey válida, o servidor não conclui a inicialização.

Rede e desempenho

Convar	Tipo	Padrão	Descrição
sv_tickRate	inteiro	50	Ticks por segundo do loop principal. 0 volta para 50.
sv_httpDownloadUrl	URL	(vazio)	Servidor HTTP externo para baixar os assets. Vazio usa o HTTP interno.
sv_assetAckTimeout	ms	300000	Tempo máximo que o cliente tem para confirmar o download dos assets.
sv_handshakeTimeout	ms	10000	Tempo máximo para uma conexão concluir o handshake. 0 desativa o limite.
sv_maxConnectionsPerAddress	inteiro	8	Máximo de conexões simultâneas por endereço IP. 0 desativa o limite; aumente com cuidado para redes NAT compartilhadas.
sv_peerTimeout	ms	20000	Quanto tempo um jogador conectado pode ficar sem confirmar pacotes antes de o link ser derrubado.
sv_peerTimeoutMax	ms	45000	Teto para esse mesmo prazo, aplicado independentemente de como o tempo de ida e volta esteja se comportando. Valores abaixo de sv_peerTimeout são elevados até ele.
sv_maxEventPayload	bytes	10485760	Maior payload que um único triggerServerEvent pode carregar. O que passar disso é descartado e registrado como protocol-oversized. Um valor 0 ou menor é ignorado; o teto do transporte é 30 MB.

Nota

Os dois prazos substituem o padrão do próprio ENet, de 5 s, que qualquer engasgo de wifi ou de rede móvel alcança — e que o download de assets alcança sozinho, ocupando justamente o link por onde as confirmações passam. Diminua se você prefere recolher clientes travados mais rápido.

Ajuste de sincronização

Com que frequência cada jogador é informado sobre os outros, e até que distância isso ainda acontece. Os padrões são onde quase todo servidor deveria ficar — mexa aqui só quando você tiver um problema de banda ou de resposta que já mediu.

Todas são opcionais, e 0 significa “manter o padrão embutido”. O servidor limita cada valor na entrada, então um erro de digitação não consegue desligar a sincronização; um valor fora da faixa é puxado para a ponta mais próxima, não recusado.

Convar	Tipo	Padrão	Faixa	Descrição
sync_relevance_radius	decimal	300	300–3000	A que distância um jogador ainda recebe atualizações. O piso é a distância em que o próprio cliente já descarta o clone.
sync_player_interval	ms	30	20–4000	Cadência de um jogador próximo.
sync_vehicle_interval	ms	30	20–4000	Cadência de um veículo próximo.
sync_ped_interval	ms	300	50–4000	Cadência de um ped controlado pelo servidor.
sync_far_interval	ms	1500	50–4000	Cadência da atualização em lote dos jogadores distantes.
sync_socket_buffer	bytes	8388608	—	Buffer de envio e recepção pedido ao socket do sistema.
sync_light_sync	booleano	true	—	A camada em lote dos distantes. Veja o aviso abaixo.

Entre “próximo” e “distante” existe um conjunto de zonas, escolhidas pela posição de quem envia em relação a para onde quem recebe está olhando. À frente, ou mais perto que sync_zone0_radius, é zona 0 e recebe a cadência cheia acima; quanto mais para trás, mais barata a zona:

Convar	Tipo	Padrão	Faixa	Descrição
sync_zone0_radius	decimal	50	0 – sync_relevance_radius	Dentro dessa distância quem envia é sempre zona 0, para onde quer que o outro esteja olhando.
sync_zone1_angle	decimal	135	0–360	Largura total, em graus, do cone à frente que ainda conta como zona 0.
sync_zone2_angle	decimal	225	sync_zone1_angle – 360	Largura total do cone mais aberto que conta como zona 1. Fora dele é zona 2.
sync_zone1_interval	ms	200	0–4000	Cadência da zona 1 — para os lados.
sync_zone2_interval	ms	400	0–4000	Cadência da zona 2 — atrás de quem recebe.
sync_max_zone_if_seen	inteiro	1	0–2	A pior zona para a qual quem envia pode ser rebaixado enquanto ele está olhando para, ou mirando em, quem recebe. Evita que dois jogadores em duelo rebaixem um ao outro. Diferente das demais, aqui 0 é um valor de verdade.

# um servidor de corrida: a distância importa mais do que a multidão atrás de você
set sync_relevance_radius  600
set sync_vehicle_interval  25
set sync_zone2_interval    600

Cuidado

sync_light_sync é uma chave só de propósito: ela liga o produtor em lote dos distantes e desliga a atualização cheia que ele substitui. Colocar false devolve todos os jogadores distantes para a atualização cheia — mais banda, não menos. Desligue apenas para isolar um bug de sincronização.

Envio dos clientes, comandos e FPS

Diferente das convars sync_* acima, que regulam o que o servidor repassa, os intervalos abaixo são enviados a cada cliente quando ele entra e regulam o que o cliente envia. Um valor fora da faixa é puxado para a ponta mais próxima. Os nomes, padrões e faixas são os mesmos do mtaserver.conf, então quem vem de um servidor MTA pode reaproveitar os valores que já usava.

Convar	Tipo	Padrão	Faixa	Descrição
player_sync_interval	ms	100	50–4000	Com que frequência um cliente envia a própria atualização de posição. É também a taxa nominal contra a qual a checagem do anticheat movement-timing mede.
camera_sync_interval	ms	500	50–4000	Com que frequência um cliente envia a posição da câmera.
ped_sync_interval	ms	400	50–4000	Com que frequência um cliente envia os peds que está sincronizando.
unoccupied_vehicle_sync_interval	ms	400	50–4000	Com que frequência um cliente envia os veículos vazios que está sincronizando.
keysync_mouse_sync_interval	ms	100	50–4000	Atualização extra, só de teclas, quando a mira ou a câmera gira entre duas atualizações de posição. Só tem efeito abaixo de player_sync_interval.
keysync_analog_sync_interval	ms	100	50–4000	O mesmo, para o movimento do analógico. Só tem efeito abaixo de player_sync_interval.
lightweight_sync_interval	ms	1500	50–4000	Aceita e enviada aos clientes, mas ainda não tem efeito — a camada dos distantes segue sync_far_interval.
ped_syncer_distance	unidades	100	50–400	A que distância um jogador pode estar de um ped do servidor e ainda sincronizá-lo. Um novo sincronizador é escolhido 20 unidades mais perto que isso.
unoccupied_vehicle_syncer_distance	unidades	130	50–400	O mesmo, para veículos vazios.
physics_object_syncer_distance	unidades	130	50–400	O mesmo, para objetos com física dinâmica.
max_dynamic_physics_objects	inteiro	128	1–1024	Quantos objetos podem ter física dinâmica ligada ao mesmo tempo. Ligar em um além disso falha.
allow_multi_command_handlers	inteiro	1	0–2	O que o addCommandHandler faz com um nome de comando que já está registrado, no servidor e em todo cliente: 0 recusa com erro, 1 aceita com aviso, 2 aceita em silêncio.
fpslimit	inteiro	0	0, 25–65535	Limite de quadros aplicado a todo jogador; 0 significa sem limite. Valores de 1 a 24 viram 25; valores negativos ou acima de 65535 são ignorados. Vale o menor entre este, o limite de um script do cliente e a configuração do próprio jogador. Um script do servidor pode mudá-lo em tempo de execução.

set player_sync_interval          100
set allow_multi_command_handlers  2
set fpslimit                      100

Caminhos

Convar	Tipo	Padrão	Descrição
sv_resourcesPath	caminho	resources	Pasta escaneada em busca de resources.
sv_assetCachePath	caminho	cache/assets	Onde os pacotes de assets são gravados.
voice_cachePath	caminho	cache/voice	Cache do chat de voz.
sv_logFile	caminho	logs/server.log	O que o próprio servidor imprime: entradas, kicks, início de resources e todo outputServerLog. Vazio desativa o arquivo.
sv_scriptLogFile	caminho	logs/scripts.log	O que os scripts imprimem com outputDebugString. Vazio desativa o arquivo.

Os dois logs acumulam entre reinicializações e reiniciam o arquivo quando ele passa de 32 MB. Eles são separados de propósito: o log do servidor é o que você guarda para moderação, e o de scripts é o barulhento que você lê enquanto desenvolve.

Voz

Convar	Tipo	Padrão	Descrição
voice_enabled	booleano	ativado por endpoint_add_voice	Liga ou desliga o chat de voz.
voice_maxDistance	decimal	40.0	Distância máxima, em unidades do jogo, em que um jogador é ouvido.
voice_allowGuests	booleano	false	Permite voz para quem não está autenticado.
voice_noiseSuppression	decimal	0.9	O quanto cada cliente trata o próprio microfone, de 0 (desligado) a 1 (totalmente tratado).

O número de vagas de voz não é configurável: ele sempre acompanha sv_maxclients.

voice_maxDistance e voice_noiseSuppression são apenas os valores iniciais — um script pode mudar os dois em tempo de execução com setVoiceMaxDistance e setVoiceNoiseSuppression, que não gravam de volta aqui.

Anticheat

Convar	Tipo	Padrão	Descrição
ac_enabled	booleano	true	Chave geral. false faz nenhuma violação ser registrada.
ac_shadow	booleano	false	Modo sombra: as violações são registradas, mas nenhum kick é executado.
ac_trail	caminho	logs/anticheat.log	Arquivo onde as violações que atingiram o limite são gravadas. Vazio desativa a trilha.
ac_kick_on	texto	(vazio)	Nomes de violação, separados por vírgula, cuja ação é forçada para kick; o limite atual é preservado.
ac_enforce	booleano	false	Eleva movement-fly, combat-weapon-not-granted e vehicle-velocity para políticas de kick.
ac_validate_damage	booleano	false	Audita rajadas de dano reportado e gera combat-damage quando o teto é ultrapassado.
ac_damage_burst_cap	decimal	900.0	Soma máxima de dano reportado por um atacante em uma janela de aproximadamente 1 segundo.
ac_strict_event_source	booleano	false	Rejeita o source que o cliente informa no triggerServerEvent quando o elemento não é o próprio jogador nem um filho dele.
ac_macro	booleano	true	Age sobre os relatos de macro do cliente. false mantém os relatos chegando e os ignora.

set ac_enabled  1
set ac_shadow   0
set ac_trail    "logs/anticheat.log"
set ac_kick_on  "protocol-plaintext,vehicle-seat-occupied"
set ac_enforce  0

A lista completa de violações, a ação padrão de cada uma e o comando de console ac estão na página Anticheat.

Desafio de integridade

Convar	Tipo	Padrão	Descrição
ac_integrity	booleano	false	Ativa o desafio periódico: o servidor envia um nonce, o cliente calcula o hash da tabela de armas / estado do mundo que está em uso, e o servidor compara com o digest que ele mesmo calcula.
ac_integrity_enforce	booleano	false	Com ac_integrity ativo, muda divergências para kick (3 em 5 min) e ausência de resposta para kick (2 em 5 min).
ac_integrity_interval	segundos	60	Intervalo entre os desafios. Valores <= 0 são ignorados.

Cuidado

O ac_integrity vem desligado de propósito. A primeira execução é calibração, não detecção: se integrity-* disparar para todo mundo, é o estado do próprio servidor divergindo, não um cheat. Dois desafios se alternam (tabela de armas e estado do mundo), então com 60 cada tabela é verificada a cada 2 minutos.

Envelope de sincronização

Estes quatro limitam o que o servidor aceita como movimento plausível. Omitir a linha mantém o valor embutido.

Convar	Tipo	Padrão	Descrição
ac_world_bound	decimal	4000.0	Metade do lado do quadrado válido do mundo, em X e Y.
ac_player_max_speed	decimal	40.0	Teto da velocidade de solo a pé, em unidades de mapa por segundo. O servidor deriva das posições que o cliente reporta — nunca da velocidade que ele alega, na qual um hack só mente — e apenas no plano horizontal, então queda livre nunca dispara. Acima do teto a amostra de posição é recusada e o jogador é devolvido para trás. É pulada em veículo, com jetpack concedido, congelado e durante um warp de script. Uma corrida fica em torno de 7, então o server.cfg gerado vem com 15.
ac_vehicle_max_speed	decimal	160.0	Velocidade máxima de veículo, em unidades do jogo por segundo. Ainda não ligada a nenhuma checagem.
ac_max_velocity	decimal	20.0	Tamanho máximo do vetor de velocidade que um pacote de sync pode alegar, em unidades do jogo. Um maior é zerado e marcado como movement-velocity — o vetor alegado é spoofável, então isso só pega hack preguiçoso.

Cuidado

Só aperte esses valores depois de medir no seu próprio servidor. Interiores ficam bem longe do mapa e um carro rápido é realmente rápido assim — um valor apertado demais vira movement-speed e movement-out-of-bounds em jogador legítimo.

Exemplo completo

# ─────────────────────────────────────────────
#  MTAX — server.cfg
# ─────────────────────────────────────────────

endpoint_add_udp    "0.0.0.0:22003"
endpoint_add_tcp    "0.0.0.0:22005"
endpoint_add_voice  "0.0.0.0:22007"

sets locale          "pt-BR"
sets sv_projectName  "MTAX dev"
sets sv_projectDesc  "Servidor demonstrativo MTAX"
sets tags            "demo, mtaxsa"

load_server_icon logo.png
sets banner_detail      "http://url.to/image.png"
sets banner_connecting  "http://url.to/image.png"
sets store_url          "http://teste.wrpstore.app"
sets discord_url        "https://discord.gg/mtaxsa"

sv_maxclients 32
# Obrigatória: substitua pelo valor emitido no Portal MTAX.
set sv_licenseKey "..."

set sv_password ""

set sv_tickRate         50
set sv_httpDownloadUrl  ""
set sv_assetAckTimeout  300000
set sv_handshakeTimeout 10000
set sv_maxConnectionsPerAddress 8

set sv_peerTimeout     20000
set sv_peerTimeoutMax  45000

set voice_maxDistance       40.0
set voice_noiseSuppression  0.9

# Ausente = mantém o valor embutido.
# set sync_relevance_radius  300
# set sync_player_interval   30
# set sync_vehicle_interval  30
# set sync_far_interval      1500
set sync_light_sync 1

# Envio dos clientes, comandos e FPS. Ausente = mantém o padrão.
# set player_sync_interval          100
# set allow_multi_command_handlers  1
# set fpslimit                      0

set ac_enabled              1
set ac_shadow               0
set ac_trail                "logs/anticheat.log"
set ac_kick_on              ""
set ac_enforce              0
set ac_validate_damage      0
set ac_damage_burst_cap     900.0
set ac_strict_event_source  0
set ac_macro                1

set ac_integrity            0
set ac_integrity_enforce    0
set ac_integrity_interval   60

# Ausente = mantém o valor embutido.
# set ac_world_bound        4000.0
set ac_player_max_speed     15.0
# set ac_vehicle_max_speed  160.0
# set ac_max_velocity       20.0

ensure spawn-demo
ensure respawn
ensure accounts