Pular para o conteúdo principal

Scripting Lua: Solução de problemas

Esta página aborda problemas comuns que você pode encontrar ao escrever ou depurar scripts de props do FreeMinecraftModels, além de dicas para trabalhar com o sistema de geração preguiçosa de configuração. Se você procura exemplos funcionais, consulte Exemplos e padrões. Se está apenas começando, consulte Primeiros passos.

Problemas comuns​

1. Arquivo de configuração não carrega / Script não atribuído​

Sintoma: O prop aparece mas não responde a cliques ou a nenhum hook.

Causas e soluções:

  • Ainda não existe um arquivo de configuração .yml. O FMM gera a configuração de forma preguiçosa no primeiro spawn do prop. Na primeira vez que um modelo é gerado, o FMM cria a configuração .yml de forma assíncrona com valores padrão (habilitado, sem scripts). Você precisa editar a configuração gerada para adicionar os nomes dos seus arquivos de script e então gerar o prop novamente.

  • A configuração tem isEnabled: false. Abra o arquivo .yml ao lado do arquivo do modelo e defina isEnabled: true.

  • A lista scripts: está vazia. Adicione os nomes dos seus arquivos de script:

    isEnabled: true
    scripts:
      - my_script.lua

  • O nome do arquivo .yml não corresponde ao nome do arquivo do modelo. A configuração deve ter o mesmo nome base que o arquivo do modelo. Por exemplo, torch_01.fmmodel precisa de torch_01.yml no mesmo diretório.

2. Arquivo de script não encontrado​

Sintoma: O console mostra: [FMM Scripts] Script 'my_script.lua' not found in scripts/ folder

Causas e soluções:

  • Diretório errado. Os arquivos de script devem estar em plugins/FreeMinecraftModels/scripts/, não ao lado do arquivo do modelo.

  • Nome de arquivo não corresponde. O nome na configuração .yml deve corresponder exatamente ao nome do arquivo na pasta scripts/, incluindo maiúsculas/minúsculas e a extensão .lua.

  • Arquivo não presente. Verifique se o arquivo .lua realmente existe na pasta scripts/.

3. Script não carrega de forma alguma​

Sintoma: Nenhum erro no console, mas nenhum hook é disparado.

Verifique o console do servidor para erros de sintaxe Lua durante a inicialização. As causas mais comuns são:

  • end faltando para fechar uma função ou bloco if
  • Parênteses não correspondentes
  • Vírgula faltando entre definições de hooks na tabela retornada
  • O arquivo não termina com .lua

Se houver um erro Lua, o console imprimirá um bloco de erro [Lua] com o nome do arquivo, número da linha e uma descrição.

4. Hook nunca dispara​

Sintoma: O script carrega (você vê a mensagem [FMM Scripts] Bound script), mas um hook específico nunca é ativado.

Verifique se o nome do hook está escrito exatamente como listado na referência de hooks. Erros comuns:

Nome erradoNome correto
on_clickon_right_click ou on_left_click
on_interacton_right_click
on_hiton_left_click
on_tickon_game_tick
on_removeon_destroy
on_arrow_hiton_projectile_hit

Verifique também se o prop possui realmente uma entidade armor stand associada. Algumas configurações de props podem não produzir uma entidade clicável.

5. Timeout / Orçamento de execução excedido​

Sintoma: O console mostra uma mensagem como:

[Lua] my_script.lua took 73ms in 'on_game_tick' (limit: 50ms) -- script disabled to prevent lag.

O script estava realizando trabalho demais em uma única chamada de hook. Causas comuns:

  • Iterar sobre entidades demais em on_game_tick
  • Criar partículas demais por tick
  • Executar loops custosos sem distribuir o trabalho entre ticks

Solução: Mova o trabalho pesado para trás de um cooldown baseado em estado ou use scheduler:run_repeating() com um intervalo razoável em vez de on_game_tick.

6. context.event é nil em um hook de clique​

Isso normalmente não deveria acontecer para on_left_click e on_right_click, mas sempre se proteja com:

if context.event then
  context.event.cancel()
end

Dentro de callbacks do scheduler, context.event é sempre nil -- este é o comportamento esperado. A modificação de eventos só pode acontecer dentro do hook de evento em si.

7. Animação não toca​

Sintoma: play_animation() retorna false, ou nada visível acontece.

Causas e soluções:

  • Nome de animação errado. O nome deve corresponder exatamente ao que está definido no arquivo do modelo. Verifique seu arquivo .bbmodel ou .fmmodel para o nome correto da animação.

  • O modelo não tem animações. Nem todos os modelos têm animações. Verifique se o arquivo do modelo realmente contém dados de animação.

  • Jogadores não estão no alcance do pacote de recursos. A animação é do lado do servidor, mas os jogadores precisam ter o pacote de recursos do FMM carregado para ver o modelo.

8. Partículas não aparecem​

  • Verifique se o nome da partícula é um valor válido do enum Particle do Bukkit em MAIÚSCULAS: "FLAME", não "flame".
  • Verifique se a localização está em um chunk carregado. Se não houver jogadores por perto, o chunk pode estar descarregado.
  • Verifique se count é pelo menos 1.
  • Algumas partículas (como DUST) precisam de dados extras específicos que o spawn_particle() básico pode não suportar. Use partículas padrão como FLAME, HEART, HAPPY_VILLAGER, NOTE, ENCHANT, etc.

9. Som não toca​

  • Verifique se o nome do som é uma constante válida do enum Sound do Bukkit em MAIÚSCULAS. Exemplo: "BLOCK_NOTE_BLOCK_HARP", não "block.note_block.harp".
  • Verifique se as coordenadas de localização estão corretas (não todas zero ou NaN).
  • Verifique se o volume é maior que 0.

10. Estado é redefinido inesperadamente​

context.state é por instância de prop e persiste durante a vida do prop. Se o estado parece ser redefinido:

  • O prop pode ter sido removido e gerado novamente (cada spawn cria uma nova instância).
  • Você pode estar lendo o estado em um callback do scheduler usando a variável de contexto errada. Sempre use o parâmetro de contexto próprio do callback.

Como funciona a geração preguiçosa de configuração​

Entender o sistema de configuração preguiçosa ajuda a evitar confusão ao configurar novos props:

  1. Primeiro spawn: Quando um prop aparece e nenhum arquivo .yml associado existe, o FMM cria a configuração de forma assíncrona. Isso significa que o arquivo é escrito em uma thread de fundo e não está imediatamente disponível.

  2. Valores padrão: A configuração gerada tem isEnabled: true e uma lista vazia scripts: [].

  3. Sem scripts no primeiro spawn: Como a configuração é criada depois que o prop já apareceu (e não tem scripts listados), o prop não terá scripts atribuídos no seu primeiro spawn.

  4. Editar e gerar novamente: Depois que o FMM cria a configuração, você a edita para adicionar os nomes dos seus arquivos de script. Na próxima vez que o prop aparecer, os scripts serão carregados.

  5. Localização da configuração: O arquivo .yml é criado no mesmo diretório que o arquivo do modelo, com o mesmo nome base. Por exemplo:

    • Modelo: plugins/FreeMinecraftModels/models/fountain.fmmodel
    • Configuração: plugins/FreeMinecraftModels/models/fountain.yml
Fluxo de trabalho de configuração rápida
  1. Coloque o modelo em models/
  2. Coloque o script em scripts/
  3. Gere o prop uma vez (gera o .yml)
  4. Edite o .yml para adicionar scripts: [my_script.lua]
  5. Gere o prop novamente -- o script agora está ativo

Leitura de mensagens de erro​

Quando algo dá errado em um script Lua de prop, o console imprime um bloco de erro [Lua]. Essas mensagens indicam exatamente qual arquivo, qual linha, qual hook e o que deu errado em linguagem clara.

Um erro típico se parece com isso:

[Lua] Error in 'my_door.lua' at line 12 during 'on_right_click':
[Lua]   -> You tried to call a method or function that doesn't exist.
[Lua]   -> Check the method name for typos, or make sure you're using ':' (colon) for method calls, not '.' (dot).
[Lua]   -> Script has been disabled for this entity to prevent further errors.

O sistema traduz erros comuns do Lua para linguagem clara:

Erro Lua brutoO que o console indica
attempt to call nilVocê tentou chamar um método ou função que não existe. Verifique erros de digitação e o uso de : vs. ..
index expected, got nilVocê tentou acessar um campo em algo que é nil. Verifique se o código anterior o inicializou.
attempt to indexVocê tentou acessar uma propriedade em um valor nil ou inválido.
bad argumentUma função recebeu o tipo errado de argumento. A mensagem mostra o tipo esperado vs. o real.
TimeoutSeu script levou Xms em 'hook_name' (limite: 50ms) -- script desabilitado para prevenir lag.
dica

Sempre leia a mensagem de erro [Lua] completa antes de mergulhar no código. Geralmente ela aponta diretamente para a solução.

Não assuma que métodos não documentados existem​

A API Lua do FMM expõe um conjunto específico de métodos. Não assuma que nomes abreviados ou alternativos existem. Erros comuns:

  • context.prop:get_location() -- não existe. Use context.prop.current_location (um campo, não um método).
  • context.prop:set_animation("open") -- não existe. Use context.prop:play_animation("open", true, true).
  • context.event:setCancelled(true) -- não existe. Use context.event.cancel().
  • context.cooldowns:check_local(...) -- não existe no FMM. Use context.state com scheduler:run_later() para cooldowns.
  • context.player -- não existe nos scripts de props do FMM. Use context.world:get_nearby_players() para encontrar jogadores perto do prop.
  • context.boss -- não existe. Isso é do EliteMobs. Use context.prop no FMM.

Em caso de dúvida, consulte a página da API de Props. Se não está documentado lá, não existe.

Dicas de depuração​

1. Use context.log:info() generosamente​

Adicione mensagens de log em cada passo ao depurar:

on_right_click = function(context)
  context.log:info("Right click received!")
  context.log:info("Event present: " .. tostring(context.event ~= nil))
  context.log:info("State is_open: " .. tostring(context.state.is_open))
end

2. Verifique o console na inicialização​

O FMM registra [FMM Scripts] Bound script 'X' to prop 'Y' para cada vinculação bem-sucedida. Se você não vê essa mensagem, a configuração ou o script não foi carregado.

3. Verifique o caminho do arquivo do modelo​

A configuração .yml deve ser um arquivo irmão do arquivo do modelo (mesmo diretório, mesmo nome base). Verifique isso conferindo:

  • Caminho do arquivo do modelo: plugins/FreeMinecraftModels/models/my_model.fmmodel
  • Caminho do arquivo de configuração: plugins/FreeMinecraftModels/models/my_model.yml

4. Teste hooks individualmente​

Ao construir um script complexo, comece testando cada hook isoladamente. Adicione um hook por vez e verifique se ele dispara antes de passar para o próximo.

5. Verifique erros de digitação nos nomes dos hooks​

A razão mais comum para um hook não disparar é um nome de hook escrito incorretamente. O script carregará sem erros, mas a função de hook com erro de digitação será rejeitada durante a validação.

Caminho de progressão para iniciantes​

Se você quer aprender este sistema do zero, esta progressão funciona bem:

  1. Escreva um arquivo com apenas api_version = 1 e on_spawn que registre uma mensagem.
  2. Adicione o script a uma configuração de prop e verifique se a mensagem de log aparece.
  3. Adicione on_right_click e registre quando o prop é clicado.
  4. Adicione on_left_click com context.event.cancel() para invulnerabilidade.
  5. Toque uma animação no clique direito.
  6. Adicione um som no clique direito.
  7. Adicione estado e comportamento de alternância.
  8. Adicione vigilância de zona para detecção de proximidade.
  9. Somente então passe para scripts complexos com múltiplos hooks e schedulers.

Cada passo se baseia no anterior, e você pode testar em cada etapa.

Próximos passos​

  • Primeiros passos -- estrutura de arquivos, hooks, tutorial do primeiro script, modelos para copiar e colar
  • API de Props -- referência completa da API
  • Exemplos e padrões -- scripts completos funcionais que você pode estudar e adaptar