Scripts Lua: primeiros passos

Esta página ensina a escrever o primeiro script Lua de um elemento decorativo do FreeMinecraftModels, desde um ficheiro vazio até uma interação funcional. No final, conhecerá os eventos, o contexto, a API de elementos decorativos e a estrutura geral de um script.

Depois de dominar o essencial, consulte:

API de elementos decorativos: context.prop, context.event, context.world e as restantes APIs do contexto.
Exemplos e padrões: scripts de elementos decorativos com notas de configuração para estudar e adaptar.
Resolução de problemas: erros comuns, diagnóstico e lista de verificação de qualidade.

Funcionalidade experimental

Os scripts Lua de elementos decorativos são experimentais. Os nomes de eventos, métodos auxiliares e comportamentos podem mudar à medida que o FreeMinecraftModels evolui. Teste-os cuidadosamente antes de os usar num servidor de produção.

Relação com Lua do EliteMobs

O FreeMinecraftModels usa o ambiente Lua do MagmaCore. Se já escreve poderes Lua para EliteMobs, reconhecerá os conceitos: ficheiros que devolvem uma tabela, api_version, eventos, context, estado, tempos de recarga, agendamento e isolamento. Os eventos e nomes exatos dos métodos dependem do plugin:

Os scripts EliteMobs executam-se em bosses e têm eventos como on_boss_damaged_by_player e on_enter_combat.
Os scripts de elementos decorativos FMM têm eventos como on_right_click, on_left_click e on_zone_enter.
Os encantamentos de itens usam o contexto separado de criação de encantamentos.

As APIs context.world, context.zones, context.scheduler, context.state e context.log aqui descritas são as versões FreeMinecraftModels/MagmaCore. Os scripts de NPC do EliteMobs usam as mesmas tabelas genéricas, mais context.npc. Os poderes de bosses usam variantes específicas de várias tabelas. Esta página trata das particularidades dos elementos decorativos FMM.

O que são scripts de elementos decorativos

São ficheiros .lua independentes em plugins/FreeMinecraftModels/scripts/. São referenciados por uma configuração YAML junto do ficheiro do modelo e executam-se quando o elemento decorativo é criado no mundo.

Para que servem

Use scripts quando precisar de:

Elementos interativos que respondem a cliques, como portas, alavancas e botões.
Decoração que ignora o dano predefinido do clique esquerdo.
Deteção de jogadores que entram ou saem de uma zona.
Animações ativadas por interação ou temporizador.
Sons quando alguém clica ou se aproxima.
Comportamentos que exigem lógica para além da decoração estática.

Um elemento puramente decorativo, sem interação, não precisa de script.

Itens personalizados e encantamentos

Os itens personalizados continuam a usar um YAML junto do modelo, com material, mas os seus efeitos usam agora encantamentos com espaço de nomes. O antigo ambiente de scripts de itens equipados foi removido. Um item personalizado com uma lista scripts: não vazia é ignorado com uma mensagem informativa na consola; a definição permanece intacta.

Os ficheiros Lua reconhecidos como scripts retirados de itens equipados em scripts/ são preservados em plugins/MagmaCore/outdated files/FreeMinecraftModels/<archive batch>/scripts/ antes da descoberta e após importações. A regra exige uma definição antiga válida com um evento de item retirado, como on_equip ou on_attack_entity. Não classifica como scripts retirados os scripts de elementos decorativos, os ficheiros que usam apenas eventos partilhados, os scripts malformados nem os efeitos atuais em enchantments/. Consulte as instruções de recuperação em ficheiros de configuração retirados.

Consulte Itens personalizados e armas mágicas para as definições atuais e Criação de encantamentos para os efeitos. As listas scripts: de elementos decorativos continuam a funcionar.

A quem se destina esta página

Esta página destina-se a quem:

Já conhece Lua do EliteMobs e quer aprender os eventos e APIs específicos do FMM.
Está a começar com Lua e precisa de uma referência completa com os nomes exatos.
Usa IA para preparar scripts e precisa de identificar APIs inventadas.

Não precisa de dominar toda a linguagem Lua para escrever scripts úteis. Na maioria dos casos, basta saber:

Colocar uma função de evento válida na tabela devolvida.
Ler valores de context.
Terminar antecipadamente com if ... then return end.
Chamar alguns métodos auxiliares com os nomes e argumentos corretos.

Breve introdução a Lua

A maioria dos scripts usa poucos conceitos: variáveis, como local x = 5; funções, como function foo() end; condições, como if x then ... end; tabelas, como {key = value}; e nil, o valor que representa ausência. A sintaxe é simples: não exige ponto e vírgula e os blocos terminam com end, sem chavetas.

Para uma explicação completa com exemplos, consulte Motor de scripts Lua do MagmaCore — breve introdução a Lua. É uma base comum aos plugins Nightbreak.

Localização dos ficheiros

Ficheiros de scripts

Coloque os ficheiros .lua na pasta central de scripts:

plugins/
  FreeMinecraftModels/
    scripts/
      invulnerable.lua
      interactive_door.lua
      proximity_sound.lua

O FMM descobre recursivamente os ficheiros .lua em plugins/FreeMinecraftModels/scripts/ ao inicializar o fornecedor de scripts e guarda o código em cache. Use nomes únicos entre subpastas, porque as associações usam o nome do ficheiro, não o caminho relativo. Depois de adicionar ou editar Lua, conclua um /fmm reload com sucesso antes de criar novas associações. Voltar a criar o elemento não relê o código Lua.

Na lista scripts: do modelo, inclua a extensão .lua para maior clareza. O FMM também aceita nomes sem extensão, acrescentando-a internamente. O ficheiro no disco tem de terminar em .lua e os nomes distinguem maiúsculas de minúsculas.

Modelos e configurações

Cada ficheiro de modelo pode ter um .yml correspondente no mesmo diretório:

plugins/
  FreeMinecraftModels/
    models/
      torch_01.fmmodel
      torch_01.yml          <-- script config for torch_01
    scripts/
      invulnerable.lua      <-- referenced by torch_01.yml

O .yml associa o modelo aos seus scripts.

Formato da configuração

O YAML junto do modelo tem estes campos:

isEnabled: true
voxelize: false
solidify: false
scripts:
  - invulnerable.lua

Os campos de elementos decorativos são:

Campo	Tipo	Predefinição	Notas
`isEnabled`	Booleano	`true`	Ativa a definição
`scripts`	Lista de cadeias	`[]`	Nomes dos ficheiros Lua de `scripts/`
`voxelize`	Booleano	`false`	Alinha a colocação à grelha de blocos e a rotações de 90 graus
`solidify`	Booleano	`false`	Adiciona barreiras por pacotes de rede a um elemento voxelizado

Cada script listado recebe uma instância própria. Para itens de mão, defina material, name, lore e enchantments com espaço de nomes. Consulte Itens personalizados.

Geração da configuração quando necessária

Se um elemento for criado sem .yml correspondente, o FMM gera uma configuração com isEnabled: true e uma lista scripts: vazia. A geração é assíncrona. Na primeira criação, o elemento ainda não terá scripts; é necessário editar a configuração para os associar.

O processo é:

Coloque o modelo em models/.
Crie o elemento uma vez, para gerar o .yml.
Edite esse ficheiro e adicione os nomes dos scripts.
Execute /fmm reload com sucesso após editar YAML ou Lua. Depois coloque um novo elemento e confirme o seu registo ou interação. As definições, as verificações de colocação e as listas de scripts do menu partilham o catálogo preparado. Recriar o elemento não volta a ler o YAML.

Referência de eventos

Cada script devolve uma tabela. Todas as chaves, exceto api_version e priority, devem ser um dos eventos suportados. O ambiente chama a função correspondente quando o evento ocorre no jogo.

Evento	Quando ocorre	Notas
`on_spawn`	O elemento é criado no mundo ou volta a carregar com o seu chunk	Uma vez, sempre que o script é associado
`on_game_tick`	Em cada tick do servidor, 50 ms a 20 TPS	Só ativo se o script definir esta função
`on_destroy`	O elemento é removido definitivamente	Limpeza de recursos. Não é chamado quando o chunk do elemento é descarregado nem quando o FMM recarrega
`on_left_click`	Um jogador atinge o elemento com clique esquerdo	`context.event` contém a opção de cancelamento do dano predefinido do FMM
`on_right_click`	Um jogador clica com o botão direito	`context.event` contém a opção de cancelamento da interação predefinida do FMM
`on_zone_enter`	Um jogador entra numa zona observada	Exige configurar a observação da zona
`on_zone_leave`	Um jogador sai de uma zona observada	Exige configurar a observação da zona
`on_projectile_hit`	Um projétil atinge o elemento	`context.projectile` é o projétil; `context.event.player` é o atirador. Consulte API de elementos decorativos

Efeitos de itens

Os antigos eventos de itens equipados deixaram de ser emitidos. Os efeitos usam encantamentos personalizados, com os seus próprios eventos e contexto. Não associe Lua de encantamentos à lista scripts: de um elemento decorativo nem copie um script antigo de item sem o adaptar.

Requisitos mínimos do ficheiro

Todos os scripts Lua de elementos decorativos devem usar return para devolver uma tabela.

Campos obrigatórios e opcionais de topo

Campo	Obrigatório	Tipo	Notas
`api_version`	Sim	Número	Atualmente deve ser `1`
`priority`	Não	Número	Validado se existir, mas o FMM não ordena os scripts por este valor. Executa-os pela ordem da lista `scripts:`
Chaves de eventos suportados	Não	Função	Use os nomes exatos da referência de eventos

Regras de validação

O ficheiro deve devolver uma tabela.
api_version é obrigatório e deve ser 1.
priority, se existir, deve ser numérico.
As restantes chaves de topo devem ser nomes de eventos suportados.
Cada chave de evento deve apontar para uma função.
As chaves de topo desconhecidas são rejeitadas.

nota

priority pode ajudar a manter scripts portáveis entre ambientes MagmaCore, mas o FMM usa atualmente a ordem da configuração. Coloque os scripts na ordem de execução desejada na lista scripts: do modelo.

As funções auxiliares e constantes locais devem ficar acima do return final, fora da tabela devolvida.

O primeiro script funcional, passo a passo

Preparação: criar a configuração

Coloque o modelo, por exemplo my_prop.fmmodel, em plugins/FreeMinecraftModels/models/.
Crie o elemento uma vez para gerar o .yml.
Crie plugins/FreeMinecraftModels/scripts/first_test.lua.
Edite plugins/FreeMinecraftModels/models/my_prop.yml:

isEnabled: true
scripts:
  - first_test.lua

Guarde o conteúdo Lua do passo 1 abaixo, execute /fmm reload e confirme que termina com sucesso. Volte a criar o elemento se necessário. Repita o recarregamento bem-sucedido após cada edição Lua dos passos seguintes.

Passo 1: carregar o ficheiro

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

A ausência de erros na consola é uma primeira verificação útil. Use a mensagem explícita do passo 2 para confirmar que:

O ficheiro contém Lua válido.
O FMM o encontrou em scripts/.
A configuração o referencia corretamente.
A tabela devolvida tem a estrutura correta.

Passo 2: produzir um resultado observável

return {
  api_version = 1,

  on_spawn = function(context)
    context.log:info("Prop script loaded for: " .. (context.prop.model_id or "unknown"))
  end
}

Consulte a consola. Se aparecer a mensagem, a função do evento foi executada.

Passo 3: reagir ao clique de um jogador

return {
  api_version = 1,

  on_right_click = function(context)
    context.log:info("Prop was right-clicked!")
  end
}

Clique no elemento com o botão direito. A mensagem na consola confirma o funcionamento do evento.

Passo 4: cancelar o dano do clique esquerdo

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event then
      context.event.cancel()
    end
  end
}

Este é o padrão de invulnerable.lua. Cancela o dano predefinido do FMM para aquele clique, mas não torna a entidade de suporte invulnerável a todas as fontes de dano.

Passo 5: reproduzir uma animação ao clicar

return {
  api_version = 1,

  on_right_click = function(context)
    context.prop:play_animation("open", true, false)
  end
}

Pede a animação open, sem repetição, após o tick do estado atual. O modelo tem de a conter. blend não faz uma transição gradual; a fila só tem uma posição e um pedido posterior pode substituir o anterior. A morte terminal pode recusar o pedido. Verifique o resultado visível no jogo; a aceitação não prova reprodução.

O que é `context`?

Cada função de evento recebe o argumento context. Contém as operações e dados necessários para interagir com o elemento decorativo, o mundo, as zonas e outros recursos.

O FMM cria-o e passa-o à função; não precisa de o criar. Para as APIs partilhadas context.state, context.log, context.cooldowns, context.scheduler, context.world e context.zones, consulte Motor de scripts Lua do MagmaCore.

Principais APIs de `context`

Segue-se um resumo. A referência completa está em API de elementos decorativos.

context.prop: a entidade do elemento decorativo, apenas nestes scripts. Disponibiliza model_id, current_location, play_animation() e stop_animation().
context.player: jogador que provocou um clique ou evento genérico de zona, e o atirador em on_projectile_hit quando foi um jogador a disparar o projétil. É nil nos eventos do ciclo de vida, nas funções agendadas e nos eventos sem jogador.
context.event: opção de cancelamento e jogador dos eventos de clique do FMM, o evento de impacto de projétil e o seu atirador em on_projectile_hit, ou uma tabela apenas com o jogador nos eventos genéricos de zona. Disponibiliza event.player, is_cancelled e, para cliques e impactos de projéteis, cancel() / uncancel(). Não expõe campos específicos do Bukkit como target, block, projectile ou item. É nil quando não há evento nem jogador, como em on_spawn e on_game_tick.
context.projectile: a entidade do projétil em on_projectile_hit, e nil em todos os outros eventos. Consulte on_projectile_hit.
context.state: tabela Lua que se mantém durante a vida da instância do script. Consulte context.state.
context.cooldowns: auxiliares de tempos de recarga locais e globais. Use context.cooldowns:check_local("key", ticks) para tempos de recarga por script. Consulte context.cooldowns.
context.log: mensagens na consola. Consulte context.log.
context.scheduler: tarefas adiadas e repetidas. Consulte context.scheduler.
context.world: partículas, sons, consulta de blocos, relâmpagos e entidades próximas. Consulte context.world.
context.zones: criação e observação de zonas espaciais, incluindo esferas, cilindros e paralelepípedos. Consulte context.zones.

Sintaxe de métodos: `:` e `.`

Consulte Motor de scripts Lua do MagmaCore para a diferença entre : e . em Lua. A API do FMM aceita ambas as formas.

Modelos iniciais para copiar

Script válido mínimo

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Cancelamento de dano por clique esquerdo

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event then
      context.event.cancel()
    end
  end
}

Elemento interativo

return {
  api_version = 1,

  on_spawn = function(context)
    context.state.is_active = false
  end,

  on_right_click = function(context)
    context.state.is_active = not context.state.is_active

    if context.state.is_active then
      context.prop:play_animation("activate", true, true)
    else
      context.prop:stop_animation()
    end
  end
}

Organização de um ficheiro maior

local ANIMATION_NAME = "idle"

local function do_something(context)
  context.log:info("Doing something!")
end

return {
  api_version = 1,
  priority = 0,

  on_spawn = function(context)
    context.state.task_id = nil
  end,

  on_right_click = function(context)
    do_something(context)
  end,

  on_destroy = function(context)
    if context.state.task_id ~= nil then
      context.scheduler:cancel(context.state.task_id)
    end
  end
}

Primeiro processo de trabalho

Ao criar um script, siga esta ordem:

Crie o .lua e faça funcionar on_spawn.
Adicione o nome do script à configuração .yml do elemento.
Passe para o evento que pretende usar, como on_right_click.
Adicione primeiro uma mensagem na consola.
Adicione um efeito: animação, som ou partícula.
Depois, acrescente funções auxiliares, estado, agendamento ou zonas.

Após cada edição Lua, guarde o ficheiro e conclua um /fmm reload com sucesso antes de verificar o novo comportamento. Altere uma coisa por passo para o registo ou efeito visível identificar o que funcionou.

Scripts incluídos

O FMM escreve quatro scripts Lua quando faltam. Também substitui versões antigas reconhecidas dos scripts predefinidos, mas preserva outras edições existentes. Inspecione o ficheiro instalado se o comportamento diferir das predefinições atuais:

invulnerable.lua: cancela o dano predefinido do clique esquerdo do FMM. Não bloqueia todas as fontes de dano.
pickupable.lua: cancela o dano predefinido do clique esquerdo e conta três golpes permitidos antes de pedir a recolha. O contador pertence à associação e é partilhado entre jogadores; uma tarefa de 100 ticks do servidor repõe-no após um golpe anterior. Os golpes permitidos pedem um flash de dano. Bloqueia locais protegidos ou de masmorras, exceto para jogadores com a permissão de exceção de proteção do FMM ou estatuto de operador.
storage_double.lua: pede um inventário com 54 posições, animações e sons de abertura e fecho. Aplica a mesma verificação de proteção e exceção de operador; consulta o acompanhamento dos jogadores a cada 5 ticks do servidor. O inventário do elemento é partilhado por todos os jogadores que o veem e é guardado quando o último o fecha ou quando o chunk é descarregado. A destruição pede drop_inventory(), que guarda primeiro o inventário aberto, pelo que os itens colocados num inventário ainda aberto são incluídos no que cai. Consulte prop:open_inventory para os detalhes.
storage_single.lua: igual ao anterior, mas com 3 linhas e 27 posições, em vez de 6 linhas.

Consulte mais exemplos em Exemplos e padrões.

Ambiente Lua isolado

Os scripts de elementos decorativos usam o mesmo ambiente LuaJ isolado do EliteMobs, com as mesmas restrições. Para a lista completa de globais removidos e funções da biblioteca padrão disponíveis, consulte Motor de scripts Lua do MagmaCore.

Próximos passos

API de elementos decorativos: referência completa de context.prop, context.event, context.world, context.zones e context.scheduler.
Exemplos e padrões: scripts de elementos decorativos, com explicações e notas de configuração.
Resolução de problemas: problemas comuns, diagnóstico e verificação de qualidade.

Nos poderes Lua de bosses EliteMobs, o isolamento, api_version, tabela de estado, tempos de recarga e estrutura por eventos são semelhantes. Contudo, o contexto do boss usa métodos específicos do EliteMobs. Consulte a documentação Lua do EliteMobs para os nomes exatos.

O que são scripts de elementos decorativos​

Para que servem​

Itens personalizados e encantamentos​

A quem se destina esta página​

Breve introdução a Lua​

Localização dos ficheiros​

Ficheiros de scripts​

Modelos e configurações​

Formato da configuração​

Geração da configuração quando necessária​

Referência de eventos​

Efeitos de itens​

Requisitos mínimos do ficheiro​

Campos obrigatórios e opcionais de topo​

Regras de validação​

O primeiro script funcional, passo a passo​

Preparação: criar a configuração​

Passo 1: carregar o ficheiro​

Passo 2: produzir um resultado observável​

Passo 3: reagir ao clique de um jogador​

Passo 4: cancelar o dano do clique esquerdo​

Passo 5: reproduzir uma animação ao clicar​

O que é context?​

Principais APIs de context​

Sintaxe de métodos: : e .​

Modelos iniciais para copiar​

Script válido mínimo​

Cancelamento de dano por clique esquerdo​

Elemento interativo​

Organização de um ficheiro maior​

Primeiro processo de trabalho​

Scripts incluídos​

Ambiente Lua isolado​

Próximos passos​