Elementos

Compartilhada

Praticamente tudo que existe no mundo do MTAX é um elemento: jogadores, veículos, peds, objetos, blips, colshapes e também os elementos “vazios” que você mesmo cria com createElement.

Os elementos vivem numa árvore. No topo fica o elemento raiz, disponível na global root. Cada resource também ganha o seu próprio nó, disponível na global resourceRoot; tudo que o resource cria nasce pendurado nele e é destruído junto quando ele para.

Quase toda função desta página recebe um elemento como primeiro argumento. Se você passar algo que não é um elemento vivo, a maioria delas devolve false e registra um aviso no console de debug — elas não interrompem o script. As exceções são hasElementData, setElementOnFire, isElementOnFire e setLowLODElement no cliente: nelas um argumento inválido lança um erro Lua que interrompe o código chamador, e que você pode capturar com pcall.

Onde a documentação pedir x, y, z, você também pode passar um Vector3 no lugar dos três números. Isso vale para setElementPosition, setElementRotation, setElementVelocity, setElementAngularVelocity, setElementAttachedOffsets, setElementInterior, attachElements, createVehicle e getElementsWithinRange.

Estas 69 funções existem no servidor e no cliente. Você pode usá-las em scripts declarados em server_files, client_files ou shared_files.

Veja também as funções de Elementos exclusivas do servidor.

Criação e destruição

createElement Cria um elemento genérico, sem representação visual, com o tipo que você quiser.

createVehicle Cria um veículo no mundo.

getVehicleController Devolve quem está ao volante de um veículo.

destroyElement Destrói um elemento e tudo que estiver abaixo dele na árvore.

Identidade e tipo

isElement Verifica se um valor é um elemento vivo.

getElementType Devolve o nome do tipo de um elemento.

getElementID Devolve o identificador de um elemento.

setElementID Define o identificador de um elemento.

getRootElement Devolve o elemento raiz do servidor.

Hierarquia

getElementParent Devolve o pai de um elemento.

setElementParent Move um elemento para debaixo de outro na árvore.

getElementChildren Lista os filhos diretos de um elemento.

getElementChild Devolve um filho pelo índice.

getElementChildrenCount Conta os filhos diretos de um elemento.

Busca

getElementsByType Busca todos os elementos de um tipo.

getElementByID Encontra um elemento pelo identificador.

getElementByIndex Devolve o n-ésimo elemento de um tipo.

Posição e rotação

getElementPosition Devolve a posição de um elemento no mundo.

setElementPosition Move um elemento para uma posição.

getElementRotation Devolve a rotação de um elemento, em graus.

setElementRotation Define a rotação de um elemento, em graus.

getElementMatrix Devolve a matriz de transformação de um elemento.

setElementMatrix Define a matriz de transformação e a posição de um elemento.

getElementVelocity Devolve a velocidade linear de um elemento.

setElementVelocity Define a velocidade linear de um elemento.

getElementAngularVelocity Devolve a velocidade de rotação de um elemento.

setElementAngularVelocity Define a velocidade de rotação de um elemento.

Interior e dimensão

getElementInterior Devolve o interior em que o elemento está.

setElementInterior Coloca um elemento em um interior, opcionalmente movendo-o ao mesmo tempo.

getElementDimension Devolve a dimensão em que o elemento está.

setElementDimension Move um elemento para outra dimensão.

Dados de elemento

Dados de elemento são pares chave/valor guardados junto do elemento. São a forma mais simples de anexar informação a qualquer coisa e, dependendo do modo de sincronização, essa informação chega aos clientes automaticamente.

Chaves com mais de 128 caracteres são cortadas nesse limite; o cliente também registra um aviso quando isso acontece. Uma string vazia é uma chave válida.

setElementData Guarda um valor no elemento.

Escrevendo a partir do cliente

Uma escrita feita no cliente chega ao servidor, por padrão, e dali aos outros jogadores. Ela é um pedido, não uma ordem: quem decide se atende é o servidor.

`sincronizar`	O que acontece
`true` (padrão)	A escrita é enviada ao servidor, que a aplica e repassa — se a chave permitir escrita de cliente.
`false`	O valor fica nesta máquina e nada é enviado.

Um elemento que o próprio cliente criou é local de qualquer forma: não há elemento do lado do servidor para escrever, então nada é enviado.

Decidindo o que um cliente pode escrever

A confiancaDoCliente é definida por elemento e por chave, e é contra ela que uma escrita de cliente é conferida:

Valor	Efeito
`"allow"`	Clientes podem escrever nesta chave deste elemento.
`"deny"`	Clientes nunca podem escrever nela.
`"default"`	Limpa a definição, devolvendo a chave ao critério do `sv_elementDataWhitelist`.

Uma chave sem nada definido segue o sv_elementDataWhitelist: recusada quando a lista branca está ligada, permitida quando está desligada. Remover uma chave limpa a confiança dela junto.

Uma escrita recusada nunca é aplicada. O servidor a registra, dispara o onPlayerChangesProtectedData no jogador e devolve o valor verdadeiro àquele cliente para que a cópia dele pare de divergir.

Podem ser guardados números, strings, booleanos, elementos, resources e tabelas (inclusive aninhadas, com elementos dentro). Uma tabela que referencia a si mesma, ou que contém a mesma tabela duas vezes, mantém essas referências. Guardar nil, uma função ou uma corrotina guarda nil: a chave continua existindo, getElementData devolve nil para ela e hasElementData devolve true. Dentro de uma tabela, os pares com esses valores são descartados. Uma tabela com mais de 16 níveis de profundidade ou mais de 4096 entradas em um mesmo nível é recusada e a função devolve false; no cliente esses limites só valem para escritas enviadas ao servidor.

Exemplo

-- servidor
setElementData(jogador, "dinheiro", 5000)
setElementData(jogador, "senhaHash", hash, false)      -- nunca sai do servidor
setElementData(veiculo, "chaves", { jogador1, jogador2 })

-- servidor: deixa o próprio cliente manter esta chave em dia
setElementData(jogador, "sensibilidadeMira", 1.0, true, "allow")

-- servidor: garante que ele nunca possa
setElementData(jogador, "dinheiro", 5000, true, "deny")

-- cliente: uma preferência local, que não vai para a rede
setElementData(localPlayer, "hudCompacto", true, false)

-- cliente: uma escrita que o servidor permitiu
setElementData(localPlayer, "sensibilidadeMira", 1.4)

getElementData Lê um valor guardado no elemento.

getAllElementData Devolve todos os dados guardados diretamente no elemento.

hasElementData Verifica se uma chave existe.

Anexos

attachElements Anexa um elemento a outro, para que ele passe a acompanhá-lo.

detachElements Desfaz o anexo de um elemento.

isElementAttached Verifica se um elemento está anexado a outro.

getElementAttachedTo Devolve a quem o elemento está anexado.

getAttachedElements Lista o que está anexado a um elemento.

setElementAttachedOffsets Ajusta os deslocamentos de um anexo já existente.

getElementAttachedOffsets Devolve os deslocamentos de anexo de um elemento.

Aparência e estado

getElementAlpha Devolve a opacidade de um elemento.

setElementAlpha Define a opacidade de um elemento.

getElementHealth Devolve a vida de um elemento.

setElementHealth Define a vida de um elemento.

getElementModel Devolve o ID de modelo de um elemento.

setElementModel Troca o modelo de um elemento.

setElementOnFire Coloca ou tira fogo de um elemento.

isElementOnFire Verifica se um elemento está pegando fogo.

isElementInWater Verifica se um elemento está dentro d'água.

isElementFrozen Verifica se um elemento está congelado no lugar.

setElementFrozen Congela ou descongela um elemento.

isElementDoubleSided Verifica se o elemento renderiza os dois lados de suas faces.

setElementDoubleSided Liga ou desliga a renderização das faces por dentro.

getElementCollisionsEnabled Verifica se um elemento tem colisão ativa.

setElementCollisionsEnabled Liga ou desliga a colisão de um elemento.

Consultas espaciais

isElementWithinColShape Verifica se um elemento está dentro de uma colshape.

getElementsWithinColShape Lista os elementos que estão dentro de uma colshape.

getElementsWithinRange Lista os elementos dentro de um raio a partir de um ponto.

isElementWithinMarker Verifica se um elemento está dentro de um marcador.

getElementColShape Devolve a colshape que um marcador ou pickup gera automaticamente.

Nível de detalhe

Objetos e edifícios podem ter uma versão simplificada, exibida de longe. Ligar os dois com setLowLODElement faz o cliente trocar automaticamente de um para o outro conforme a distância.

setLowLODElement Associa a um elemento a sua versão de baixo detalhe.

getLowLODElement Devolve a versão de baixo detalhe associada a um elemento.

isElementLowLOD Verifica se um elemento é uma versão de baixo detalhe.

Propagação para os filhos

Vários setters desta página não param no elemento que você passou: eles percorrem a árvore em profundidade e se aplicam também aos descendentes. É o que faz setElementHealth(root, 100) curar todo mundo de uma vez. A propagação pode ser desligada por elemento. Desligá-la no alvo impede a chamada de chegar aos filhos; desligá-la em um descendente ainda deixa esse nó receber a alteração, mas corta tudo que estiver abaixo dele.

Setter	Cliente	Servidor
`setElementPosition`, `setElementVelocity`, `setElementAngularVelocity`	Sim	Sim
`setElementRotation`	Sim	Não
`setElementMatrix`	Sim	Só a posição
`setElementHealth`, `setElementModel`	Sim	Sim
`setElementInterior`, `setElementDimension`	Sim	Sim
`setElementAttachedOffsets`, `setElementAlpha`, `setLowLODElement`	Sim	Sim
`attachElements`, `detachElements`	Sim	Não
`setElementOnFire`, `setElementFrozen`, `setElementDoubleSided`	Não	Sim

Tipos de descendente incompatíveis são ignorados. O retorno da função descreve a aplicação no elemento informado, não garante que cada descendente aceitou a propriedade.

isElementCallPropagationEnabled Verifica se um elemento repassa as chamadas aos seus filhos.

setElementCallPropagationEnabled Liga ou desliga a propagação de chamadas para os filhos.

Jogadores

getPlayerName Devolve o nick de um jogador.

getPlayerFromName Encontra um jogador pelo nick.