Engine e modelos

As funções de engine mexem no conteúdo do jogo que roda na máquina do jogador: modelos (.dff), texturas (.txd), colisões (.col), animações (.ifp) e arquivos .img. Com elas você troca o visual de qualquer objeto, veículo ou pedestre, cria IDs de modelo novos, mexe no comportamento físico das superfícies e controla quanto de memória o streaming pode usar.

Quase tudo aqui trabalha com IDs de modelo. As funções que aceitam “ID ou nome” resolvem o argumento assim:

Você passa	O que acontece
um número	usado como ID direto
uma string só com dígitos	convertida em número
"txdN"	o slot de TXD N, ou seja, 20000 + N
um nome de modelo	resolvido para o ID correspondente (sem diferenciar maiúsculas de minúsculas)

O que acontece com um argumento inválido depende da função. Os carregadores de TXD, DFF, COL e IFP e as funções de substituição, distância de LOD, nomes, nomes de textura, shaders e superfícies devolvem false (as de superfície, nil) e escrevem o motivo no console de debug. Já as funções de flags, ID de TXD, propriedades físicas, streaming, IMG, pools e roupas, além de engineGetModelTextures, conferem os argumentos de forma estrita: um tipo errado ou um ID inválido gera um erro Lua que interrompe o código que fez a chamada. Cada página diz qual é o caso.

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

Carregar e substituir arquivos

Os três carregadores aceitam um caminho dentro do resource ou os bytes do arquivo (o resultado de fileRead, por exemplo) — o formato é detectado a partir do conteúdo. O que volta é um elemento (txd, dff ou col) que as outras funções recebem. Ele é destruído quando o resource para, e os modelos que ele substituiu voltam ao original.

engineLoadTXD Carrega uma coleção de texturas.

engineLoadDFF Carrega um modelo.

engineLoadCOL Carrega um arquivo de colisão.

engineImportTXD Faz um TXD carregado valer para um modelo.

engineReplaceModel Troca a geometria de um modelo pelo DFF carregado.

engineReplaceCOL Troca a colisão de um modelo.

engineRestoreModel Devolve um modelo à geometria original.

engineRestoreCOL Devolve a colisão original de um modelo.

Formas de colisão

Uma colisão não precisa vir de um arquivo .col: setModelCollision constrói uma a partir de uma tabela de esferas, caixas, linhas e triângulos, e getModelCollision lê de volta, nessa mesma tabela, a colisão que um modelo usa no momento.

setModelCollision Dá a um modelo de objeto uma colisão construída a partir de uma tabela de formas.

getModelCollision Lê a colisão que um modelo usa no momento, como uma tabela de formas.

IDs de modelo personalizados

Em vez de sobrescrever um modelo que já existe, você pode pedir um ID livre e usá-lo só para o seu conteúdo.

engineRequestModel Reserva um ID de modelo novo.

engineFreeModel Devolve ao jogo um ID reservado.

Nomes e IDs

engineGetModelNameFromID Converte um ID em nome de modelo.

engineGetModelIDFromName O caminho inverso: nome para ID.

Flags de modelo

As flags controlam como o modelo é desenhado e como o jogo o trata. Elas podem ser lidas e escritas em bloco (como número) ou uma a uma (pelo nome).

Flag
is_road
draw_last
additive
ignore_lighting
no_zbuffer_write
dont_receive_shadows
is_glass_type_1
is_glass_type_2
is_garage_door
is_damagable
is_tree
is_palm
does_not_collide_with_flyer
is_tag
disable_backface_culling
is_breakable_statue
is_crane

engineGetModelFlags Lê todas as flags de um modelo como um número.

engineSetModelFlags Escreve todas as flags de uma vez.

engineGetModelFlag Lê uma flag pelo nome.

engineSetModelFlag Liga ou desliga uma flag pelo nome.

engineResetModelFlags Devolve as flags originais do modelo.

Distância de LOD, TXD e horário de exibição

engineGetModelLODDistance Lê a distância em que o modelo deixa de ser desenhado em detalhe.

engineSetModelLODDistance Define a distância de LOD.

engineResetModelLODDistance Volta à distância de LOD original.

engineGetModelTXDID Lê qual slot de TXD o modelo usa.

engineSetModelTXDID Aponta o modelo para outro slot de TXD.

engineResetModelTXDID Devolve o modelo ao seu slot de TXD original.

engineGetModelVisibleTime Lê a faixa de horas em que o modelo aparece no mundo.

engineSetModelVisibleTime Define a faixa de horas de um modelo.

Grupo de propriedades físicas do modelo

Cada modelo pode apontar para um grupo de propriedades físicas, numerado de 0 a 159. O valor -1 significa que o modelo não tem grupo e se comporta como estático.

engineGetModelPhysicalPropertiesGroup Lê o grupo de um modelo.

engineSetModelPhysicalPropertiesGroup Aponta o modelo para outro grupo.

engineRestoreModelPhysicalPropertiesGroup Devolve o grupo original do modelo.

Texturas

engineGetModelTextureNames Lista os nomes das texturas usadas por um modelo.

engineGetVisibleTextureNames Lista os nomes das texturas do mundo conhecidas pelo cliente.

engineGetModelTextures Devolve as texturas de um modelo como elementos utilizáveis em desenho.

Shaders em texturas do mundo

engineApplyShaderToWorldTexture Faz um shader passar a desenhar uma textura do mundo.

engineRemoveShaderFromWorldTexture Desfaz a aplicação.

Propriedades de superfície

Cada tipo de superfície do mundo tem um ID numérico e um conjunto de propriedades que definem som do passo, aderência dos pneus, efeitos de tiro e por aí vai.

Propriedade	Tipo do valor
audio	string: concrete, grass, sand, gravel, wood, water, metal
bulleteffect	string: disabled, metal, sand, wood, concrete
wheeleffect	string: disabled, grass, gravel, mud, sand, dust
skidmarktype	string: asphalt, dirt, dust, disabled
adhesiongroup	string: rubber, hard, road, loose, sand, wet
tyregrip	number
wetgrip	number
fractioneffect	number
roughness	number
stepwatersplash	bool
stepdust	bool
canclimb	bool
shootthrough	bool
seethrough	bool
stairs	bool
steepslope	bool
glass	bool
pavement	bool
softlanding	bool
footeffect	bool

Os IDs de superfície vão de 0 a 179. stepdust é aceita, mas sempre é lida e gravada como false.

engineGetSurfaceProperties Lê uma propriedade de uma superfície.

engineSetSurfaceProperties Escreve uma propriedade de uma superfície.

engineResetSurfaceProperties Devolve as propriedades originais.

Propriedades físicas de grupos de objetos

São os grupos referenciados por engineSetModelPhysicalPropertiesGroup, numerados de 0 a 159. Cada grupo define massa, elasticidade, comportamento ao quebrar e afins. Os nomes das propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor esperado
mass	number
turn_mass	number
air_resistance	number
elasticity	number
buoyancy	number
uproot_limit	number
col_damage_multiplier	number
smash_multiplier	number
break_velocity_randomness	number
col_damage_effect	string: none, change_model, smash, change_smash, breakable, breakable_remove
special_col_response	string: none, lamppost, small_box, big_box, fence_part, grenade, swingdoor, lockdoor, hanging, poolball
fx_type	string: none, play_on_hit, play_on_destroyed, play_on_hitdestroyed
break_mode	string: not_by_gun, by_gun, smashable
avoid_camera	bool
cause_explosion	bool
sparks_on_impact	bool
fx_offset	três números ou um Vector3 (lido de volta como Vector3)
break_velocity	três números ou um Vector3 (lido de volta como Vector3)
fx_system	string: nome de um sistema de FX, ou false para removê-lo (só escrita)

engineSetObjectGroupPhysicalProperty Escreve uma propriedade de um grupo.

engineGetObjectGroupPhysicalProperty Lê uma propriedade de um grupo.

engineRestoreObjectGroupPhysicalProperties Devolve as propriedades originais de um grupo.

Streaming: memória e buffer

O streaming decide o que fica carregado na memória de vídeo enquanto o jogador anda pelo mundo. Aumentar os limites reduz o “pop-in” de modelos ao custo de memória.

engineStreamingGetMemorySize Lê o limite de memória do streaming.

engineStreamingSetMemorySize Define o limite de memória do streaming.

engineStreamingRestoreMemorySize Volta ao limite calculado automaticamente a partir da memória da máquina.

engineStreamingGetUsedMemory Lê quanto o streaming está usando de fato.

engineStreamingFreeUpMemory Pede ao streaming que descarregue conteúdo até liberar uma quantidade de memória.

engineStreamingGetBufferSize Lê o tamanho do buffer de leitura do streaming.

engineStreamingSetBufferSize Define o tamanho do buffer de leitura.

engineStreamingRestoreBufferSize Volta ao tamanho de buffer padrão.

engineStreamingSetModelCacheLimits Define quantos modelos de veículo e de pedestre ficam em cache.

Streaming: modelos e mundo

engineStreamingRequestModel Pede ao streaming que carregue um modelo.

engineStreamingReleaseModel Libera um modelo pedido antes.

engineStreamingGetModelLoadState Diz em que ponto do carregamento um modelo está.

engineSetAsynchronousLoading Configura o carregamento assíncrono.

enginePreloadWorldArea Carrega antecipadamente o conteúdo de uma região do mundo.

engineRestreamWorld Descarrega e recarrega tudo que está no mundo.

engineRestreamModel Recarrega todos os elementos que usam um modelo.

engineRestream Recarrega os veículos, os peds, os objetos ou o mundo inteiro.

Slots de TXD

engineRequestTXD Reserva um slot de TXD novo.

engineFreeTXD Devolve um slot de TXD reservado.

Arquivos IMG

Um .img é um arquivo único que empacota vários modelos e texturas. engineLoadIMG devolve um elemento img; depois de plugado no streaming, seus arquivos podem ser ligados a IDs de modelo ou de TXD.

engineLoadIMG Carrega um arquivo .img do resource.

engineAddImage Pluga o arquivo no streaming.

engineRemoveImage Tira o arquivo do streaming.

engineImageGetFilesCount Conta os arquivos dentro do .img.

engineImageGetFiles Lista os nomes dos arquivos de dentro do .img.

engineImageGetFile Lê o conteúdo de um arquivo de dentro do .img.

engineImageLinkDFF Faz um ID de modelo passar a ler seu .dff de dentro do pacote.

engineImageLinkTXD O mesmo, para um slot de TXD.

engineRestoreDFFImage Desfaz a ligação de um modelo, voltando ao arquivo original do jogo.

engineRestoreTXDImage O mesmo, para um slot de TXD.

Pools

Pools são as listas internas de tamanho fixo em que o jogo guarda cada tipo de coisa. Consultá-las ajuda a entender por que algo parou de aparecer. Só building e pointer-single-link-pool podem ser redimensionadas em tempo de execução.

Pool
building
ped
object
dummy
vehicle
col-model
task
event
task-allocator
ped-intelligence
ped-attractor
entry-info-node
node-route
patrol-route
point-route
pointer-double-link-pool
pointer-single-link-pool
env-map-material
env-map-atomic
spec-map-material

engineGetPoolCapacity Lê a capacidade atual de uma pool.

engineGetPoolDefaultCapacity Lê a capacidade padrão de uma pool.

engineGetPoolUsedCapacity Lê quantos slots da pool estão ocupados.

engineSetPoolCapacity Redimensiona uma pool em tempo de execução.

Roupas

Estas duas funções registram arquivos de roupa novos no catálogo do cliente. Para vestir uma peça em alguém, veja as funções de Roupas.

engineAddClothingTXD Registra uma textura de roupa.

engineAddClothingModel Registra um modelo de roupa.

Animações

engineLoadIFP Carrega um pacote de animações e o registra sob um nome de bloco seu.

engineReplaceAnimation Troca uma animação do jogo por uma do seu pacote, para um ped específico.

engineRestoreAnimation Desfaz substituições de animação em um ped.