Armas

Uma arma de cliente é uma arma que existe por conta própria. Ela nasce numa posição do mundo, mira sozinha, atira sozinha e tem munição própria — ninguém a segura e ninguém puxa o gatilho. É com isso que se monta torreta, armadilha, canhão de veículo e qualquer coisa que precise disparar sem um dono.

Isso é diferente da arma que está no inventário de um personagem. Aquela pertence ao ped, anda com ele, aparece no HUD e existe também no servidor. Uma arma de cliente é um elemento do tipo weapon, vive só na tela de quem a criou e nunca chega ao servidor.

Toda arma criada por script é um elemento: aparece em getElementType como "weapon", aceita setElementPosition e setElementRotation, some com destroyElement e é destruída automaticamente quando o resource que a criou para.

Quando um argumento inválido é passado — um elemento que não é arma, uma arma já destruída, um nome de estado ou de flag que não existe — a função devolve false e escreve o motivo no console de debug. A única que gera erro de Lua é setWeaponRenderEnabled, quando recebe algo que não seja booleano.

Estas 19 funções existem somente no cliente. Chamá-las de um script de servidor resulta em erro de valor nulo.

Veja também as funções de Armas compartilhadas, que trabalham com nomes, IDs e propriedades das armas nos dois lados.

createWeapon Cria uma arma no mundo.

Armas que realmente atiram

createWeapon aceita qualquer tipo que tenha modelo, mas só estas onze disparam de verdade. As outras viram um modelo parado no mundo, que você pode posicionar e destruir normalmente, e nada mais.

ID	Arma	Nome
22	Colt 45	pistol
23	Silenced	silenced
24	Deagle	deagle
28	Uzi	uzi
29	MP5	mp5
30	AK-47	ak-47
31	M4	m4
32	Tec-9	tec-9
33	Rifle	rifle
34	Sniper	sniper
38	Minigun	minigun

Exemplo — o ciclo completo de uma torreta: criar, configurar, mirar, atirar e destruir.

local torreta

addCommandHandler("torreta", function()
    if torreta then return end

    local x, y, z = getElementPosition(localPlayer)
    torreta = createWeapon("m4", x + 5, y, z + 1)

    if not torreta then
        outputDebugString("nao foi possivel criar a torreta")
        return
    end

    -- 1. configure antes de ligar
    setWeaponFiringRate(torreta, 150)                    -- um tiro a cada 150 ms
    setWeaponClipAmmo(torreta, 60)
    setWeaponFlags(torreta, "instant_reload", true)      -- sem pausa para recarregar
    setWeaponFlags(torreta, "shoot_if_out_of_range", true)

    -- 2. escolha o alvo
    setWeaponTarget(torreta, localPlayer)

    -- 3. um tiro avulso agora, e depois fogo contínuo
    fireWeapon(torreta)
    setWeaponState(torreta, "firing")

    -- 4. desliga e limpa depois de 10 segundos
    setTimer(function()
        if torreta then
            setWeaponState(torreta, "ready")
            destroyElement(torreta)
            torreta = nil
            outputDebugString("torreta removida")
        end
    end, 10000, 1)
end)

Estado

O estado é o que decide o que a arma faz a cada quadro.

Estado	O que significa
ready	Parada. Não atira sozinha.
firing	Atirando. A cada intervalo da cadência sai um tiro.
reloading	Recarregando. O motor coloca a arma neste estado sozinho quando o pente acaba, e devolve o estado anterior quando termina.
out_of_ammo	Aceito por setWeaponState, mas o motor nunca coloca a arma nele e não muda o comportamento por causa dele.
melee_madecontact	Mesma coisa: aceito, guardado e devolvido por getWeaponState, sem nenhum efeito.

Na prática só firing e reloading mudam o que a arma faz. Os outros dois são valores que você pode usar como marcação sua.

setWeaponState Muda o estado da arma.

getWeaponState Lê o estado atual.

fireWeapon Dispara um tiro agora mesmo.

getWeaponOwner Devolve o ped a que pertence uma arma criada pelo servidor.

Mira

Sem alvo, a arma atira em linha reta para a frente, a partir da boca do cano, até o alcance dela. Com alvo, ela gira sozinha a cada quadro para acompanhar.

setWeaponTarget Define para onde a arma aponta.

getWeaponTarget Lê o alvo atual.

Munição

A arma tem dois números de munição: o pente, que é o que ela gasta tiro a tiro, e a reserva, de onde o pente é reabastecido.

Como a recarga funciona

Quando o pente chega a zero, a arma tenta recarregar. Se a reserva tiver pelo menos um pente cheio, ela desconta um pente da reserva e enche o pente de volta. Sem a flag instant_reload isso leva o tempo de recarga da arma, e durante esse tempo o estado fica reloading. Se a reserva for menor que um pente cheio, a arma simplesmente para de atirar e fica assim.

setWeaponClipAmmo Define quantas balas estão no pente.

getWeaponClipAmmo Lê quantas balas restam no pente.

setWeaponAmmo Define a reserva de munição da arma.

getWeaponAmmo Lê a reserva de munição — a munição de onde o pente é recarregado, sem contar o que já está no pente.

Cadência de tiro

A cadência é o intervalo mínimo entre dois tiros automáticos, em milissegundos: quanto menor o número, mais rápido a arma atira. Ela só vale para o estado firing — fireWeapon ignora esse intervalo.

setWeaponFiringRate Define o intervalo entre tiros.

getWeaponFiringRate Lê o intervalo atual.

resetWeaponFiringRate Devolve a cadência ao valor original.

Propriedades

Um elemento arma carrega a própria cópia dos atributos que o tipo de arma usaria normalmente. Mudá-los aqui afeta aquela arma e mais nada — o tipo de arma em si fica intacto, e todas as outras armas do mesmo tipo também.

setWeaponProperty Altera um atributo de um elemento arma.

Flags

Flags são chaves liga/desliga do comportamento da arma. Todas começam desligadas.

Flag	Padrão	O que faz quando ligada
shoot_if_out_of_range	false	A arma atira mesmo com o alvo além do alcance dela. Desligada, ela segura o tiro.
shoot_if_target_blocked	false	O tiro vale mesmo quando a bala para em outra coisa no caminho. Desligada, o impacto é descartado quando a bala não chega no alvo. Só tem efeito quando o alvo é um elemento.
disable_model	false	Esconde o modelo da arma. Ela continua atirando normalmente, só fica invisível.
instant_reload	false	Enche o pente na hora, sem tempo de recarga e sem passar pelo estado reloading.
flags	—	Nome especial: em vez de um booleano só, trabalha com os oito testes de linha de visão do tiro de uma vez.

Testes de linha de visão

Quando a flag é flags, os oito booleanos vêm nesta ordem, tanto para escrever quanto para ler:

Posição	O que controla	Padrão
1	A bala testa prédios.	true
2	A bala testa pneus de veículo.	true
3	A bala testa bonecos.	true
4	A bala testa objetos.	true
5	A bala testa peds.	true
6	A bala testa veículos.	true
7	A bala enxerga através de materiais transparentes.	false
8	A bala atravessa materiais perfuráveis.	false

setWeaponFlags Liga ou desliga uma flag.

getWeaponFlags Lê uma flag.

Armas nas mãos dos personagens

Estas duas são globais e não têm nada a ver com as armas criadas por createWeapon: elas ligam e desligam o desenho das armas que os personagens seguram. Não recebem elemento nenhum.

Para esconder o modelo de uma arma criada por script, use a flag disable_model.

setWeaponRenderEnabled Liga ou desliga o desenho das armas seguradas pelos personagens.

isWeaponRenderEnabled Verifica se as armas dos personagens estão sendo desenhadas.