Scripting Lua: API de Props e Itens

Esta página cobre todas as APIs disponíveis para scripts de props e itens do FreeMinecraftModels: context.prop, context.item, context.event, context.player, context.world, context.zones, context.scheduler, context.state e context.log. Se você é novo em scripting, comece com Primeiros Passos primeiro.

`context.prop`

A tabela prop fornece informações sobre a entidade prop e métodos para controlar suas animações. Ela é reconstruída nova para cada chamada de hook.

Campos

Campo	Tipo	Notas
`prop.model_id`	string	O nome do modelo blueprint (ex: `"torch_01"`)
`prop.current_location`	tabela de localização	A posição do prop no momento em que o context foi construído

A tabela de localização tem os campos padrão: x, y, z, world, yaw, pitch.

Exemplo: lendo informações do prop

return {
  api_version = 1,

  on_spawn = function(context)
    context.log:info("Prop spawned: " .. (context.prop.model_id or "unknown"))
    local loc = context.prop.current_location
    if loc then
      context.log:info("Location: " .. loc.x .. ", " .. loc.y .. ", " .. loc.z)
    end
  end
}

`prop:play_animation(name, blend, loop)`

Reproduz uma animação nomeada no modelo do prop.

Parâmetro	Tipo	Padrão	Notas
`name`	string	obrigatório	O nome da animação como definido no arquivo de modelo
`blend`	boolean	`true`	Se deve fazer blending com a animação atual
`loop`	boolean	`true`	Se a animação deve loopear

Retorna true se a animação foi encontrada e iniciada, false caso contrário.

Exemplo

return {
  api_version = 1,

  on_right_click = function(context)
    local success = context.prop:play_animation("open", true, false)
    if not success then
      context.log:warn("Animation 'open' not found on this model!")
    end
  end
}

`prop:stop_animation()`

Para todas as animações em reprodução no prop.

Não recebe parâmetros.

Exemplo

return {
  api_version = 1,

  on_right_click = function(context)
    context.prop:stop_animation()
  end
}

`prop:hurt_visual()`

Reproduz a animação visual de dano (flash de tonalidade vermelha) no prop sem causar dano real a ele.

Não recebe parâmetros.

Exemplo

return {
  api_version = 1,

  on_left_click = function(context)
    -- Flash red when punched, but don't actually take damage
    if context.event then
      context.event.cancel()
    end
    context.prop:hurt_visual()
  end
}

`prop:pickup()`

Remove o prop do mundo e dropa um item de papel de colocação em sua localização. O item dropado pode ser clicado com botão direito em um bloco para colocar o prop novamente.

Não recebe parâmetros.

Exemplo

return {
  api_version = 1,

  on_right_click = function(context)
    -- Let players pick up the prop by right-clicking it
    context.prop:pickup()
  end
}

`prop:mount(player)`

Monta um jogador no primeiro assento de ponto de montagem disponível no prop. O modelo deve ter bones de ponto de montagem definidos.

Parâmetro	Tipo	Notas
`player`	tabela de entidade	Uma tabela de entidade de jogador (ex: de `context.event.player`)

Exemplo

return {
  api_version = 1,

  on_right_click = function(context)
    local player = context.event and context.event.player
    if player then
      context.prop:mount(player)
    end
  end
}

`prop:dismount(player)`

Desmonta um jogador de sua posição de assento de ponto de montagem no prop.

Parâmetro	Tipo	Notas
`player`	tabela de entidade	Uma tabela de entidade de jogador

Exemplo

return {
  api_version = 1,

  on_right_click = function(context)
    local player = context.event and context.event.player
    if player then
      -- Toggle mount/dismount
      local passengers = context.prop:get_passengers()
      for i = 1, #passengers do
        if passengers[i].uuid == player.uuid then
          context.prop:dismount(player)
          return
        end
      end
      context.prop:mount(player)
    end
  end
}

`prop:get_passengers()`

Retorna um array Lua de tabelas de entidade para todos os passageiros atuais no prop.

Não recebe parâmetros.

Exemplo

return {
  api_version = 1,

  on_game_tick = function(context)
    local passengers = context.prop:get_passengers()
    if #passengers > 0 then
      context.log:info("Prop has " .. #passengers .. " passenger(s)")
    end
  end
}

`prop:has_mount_points()`

Retorna se este prop tem bones de ponto de montagem definidos em seu modelo.

Não recebe parâmetros. Retorna true ou false.

Exemplo

return {
  api_version = 1,

  on_right_click = function(context)
    local player = context.event and context.event.player
    if player and context.prop:has_mount_points() then
      context.prop:mount(player)
    end
  end
}

`prop:spawn_elitemobs_boss(filename, x, y, z)`

Spawna um boss customizado do EliteMobs na localização dada. Requer que o EliteMobs esteja instalado no servidor.

Parâmetro	Tipo	Notas
`filename`	string	O nome do arquivo do boss customizado (ex: `"my_boss.yml"`)
`x`	number	Coordenada X
`y`	number	Coordenada Y
`z`	number	Coordenada Z

Retorna uma tabela de entidade viva para o boss spawnado, ou nil se o EliteMobs não estiver instalado ou o arquivo do boss não existir.

Exemplo

return {
  api_version = 1,

  on_right_click = function(context)
    local loc = context.prop.current_location
    if loc then
      local boss = context.prop:spawn_elitemobs_boss("dungeon_guardian.yml", loc.x, loc.y + 1, loc.z)
      if boss then
        context.log:info("Spawned boss: " .. (boss.name or "unknown"))
      else
        context.log:warn("Could not spawn boss -- is EliteMobs installed?")
      end
    end
  end
}

`prop:open_inventory(player, title, rows)`

Abre um inventário de baú GUI persistente para o jogador. O conteúdo é salvo no PersistentDataContainer do prop quando o inventário é fechado, e restaurado quando aberto novamente.

Parâmetro	Tipo	Padrão	Notas
`player`	tabela de entidade	obrigatório	O jogador para mostrar o inventário
`title`	string	obrigatório	O título do inventário (suporta códigos de cor com `&`)
`rows`	int	`3`	Número de linhas (1-6, onde 6 = 54 slots = baú duplo)

Retorna true se o inventário foi aberto, false caso contrário.

`prop:is_viewing_inventory(player)`

Retorna se o jogador dado atualmente tem o inventário deste prop aberto.

Parâmetro	Tipo	Notas
`player`	tabela de entidade	O jogador a verificar

Retorna true ou false.

Exemplo: Animação de fechar quando inventário é fechado

context.state["task_" .. player.uuid] = context.scheduler:run_repeating(5, 5, function(tick_context)
    if not tick_context.prop:is_viewing_inventory(player) then
        tick_context.prop:play_animation("close", true, false)
        tick_context.scheduler:cancel(tick_context.state["task_" .. player.uuid])
    end
end)

`prop:place_book(player)`

Pega o livro escrito ou escribível da mão principal do jogador e armazena no prop.

Parâmetro	Tipo	Notas
`player`	tabela de entidade	O jogador segurando o livro

Retorna true se bem-sucedido.

`prop:read_book(player)`

Abre o livro armazenado para leitura pelo jogador.

Parâmetro	Tipo	Notas
`player`	tabela de entidade	O jogador para mostrar o livro

Retorna true se um livro foi aberto.

`prop:take_book(player)`

Retorna o livro armazenado ao inventário do jogador e o remove do prop.

Parâmetro	Tipo	Notas
`player`	tabela de entidade	O jogador para dar o livro

Retorna true se bem-sucedido.

`prop:has_book()`

Retorna se um livro está armazenado neste prop. Não recebe parâmetros.

`prop:drop_inventory()`

Dropa todo o conteúdo do inventário armazenado na localização do prop como entidades de item, e então limpa os dados armazenados. Fecha automaticamente o inventário para qualquer jogador que esteja visualizando.

Não recebe parâmetros. Retorna true se bem-sucedido.

`prop:drop_book()`

Dropa o livro armazenado na localização do prop como uma entidade de item e limpa os dados do livro armazenado.

Não recebe parâmetros. Retorna true se bem-sucedido.

`prop:set_persistent_data(key, value)`

Armazena um valor string no PersistentDataContainer do armor stand do prop. Esses dados sobrevivem reinícios do servidor e descargas de chunks.

Parâmetro	Tipo	Notas
`key`	string	Um nome de chave único (armazenado como `fmm_lua_<key>` internamente)
`value`	string	O valor a armazenar. Use `tostring()` para números e booleanos.

Retorna true se bem-sucedido, false se o prop não tiver um armor stand de suporte.

`prop:get_persistent_data(key)`

Recupera um valor string previamente armazenado com set_persistent_data. Retorna nil se a chave não foi definida.

Parâmetro	Tipo	Notas
`key`	string	O nome da chave usado em `set_persistent_data`

Exemplo: Estado de alternância persistente

return {
  api_version = 1,

  on_spawn = function(context)
    local saved = context.prop:get_persistent_data("active")
    context.state.active = saved == "true"
  end,

  on_right_click = function(context)
    context.state.active = not context.state.active
    context.prop:set_persistent_data("active", tostring(context.state.active))
  end
}

`context.item`

A tabela item está disponível apenas em scripts de itens (não em scripts de props). Fornece informações sobre o item personalizado e métodos para manipulá-lo. Esta tabela é reconstruída nova para cada chamada de hook.

Campos

Campo	Tipo	Notas
`item.id`	string	O ID do tipo de item (o `fmm_item_id` da configuração YML)

`item:material()`

Retorna o nome do material do item como string (ex: "DIAMOND_SWORD", "STICK").

`item:get_amount()` / `item:set_amount(n)`

Obtém ou define o tamanho do stack do item.

Parâmetro	Tipo	Notas
`n`	int	A nova quantidade do stack

`item:consume(n)`

Decrementa a quantidade do stack do item em n (padrão 1). Se a quantidade resultante for 0 ou menos, o item é removido do inventário do jogador.

Parâmetro	Tipo	Padrão	Notas
`n`	int	`1`	Quantidade a consumir

`item:get_uses()` / `item:set_uses(n)`

Obtém ou define um contador de uso personalizado armazenado no PersistentDataContainer do item. Isso é independente da durabilidade vanilla e pode ser usado para implementar sistemas de durabilidade ou carga personalizados.

Parâmetro	Tipo	Notas
`n`	int	O novo contador de usos

`item:get_name()` / `item:set_name(s)`

Obtém ou define o nome de exibição do item. Suporta códigos de cor com &.

Parâmetro	Tipo	Notas
`s`	string	O novo nome de exibição (ex: `"&b&lFrost Sword"`)

`item:get_lore()` / `item:set_lore(table)`

Obtém ou define o lore do item. get_lore() retorna uma tabela de strings (uma por linha). set_lore() recebe uma tabela de strings.

Parâmetro	Tipo	Notas
`table`	table	Array de strings, uma por linha de lore

Exemplo: Script de item que rastreia usos

return {
  api_version = 1,

  on_right_click = function(context)
    local uses = context.item:get_uses()
    if uses <= 0 then
      context.player:send_message("&cThis item is out of charges!")
      return
    end
    context.item:set_uses(uses - 1)
    context.player:send_message("&aUsed! Charges remaining: " .. (uses - 1))
  end
}

`item:get_durability()`

Retorna uma tabela com campos current e max representando a durabilidade vanilla do item, ou nil se o item não tiver barra de durabilidade.

Exemplo

local dur = context.item:get_durability()
if dur then
  context.player:send_message("Durability: " .. dur.current .. "/" .. dur.max)
end

`item:get_durability_percentage()`

Retorna a durabilidade restante como uma fração de 0.0 a 1.0, ou nil se o item não tiver barra de durabilidade.

`item:use_durability(amount, can_break)`

Reduz a durabilidade vanilla do item por uma quantidade fixa.

Parâmetro	Tipo	Padrão	Notas
`amount`	int	obrigatório	Quantos pontos de durabilidade consumir
`can_break`	boolean	`false`	Se `true`, o item é destruído quando a durabilidade acaba. Se `false`, a durabilidade para em 1.

`item:use_durability_percentage(fraction, can_break)`

Reduz a durabilidade vanilla do item por uma porcentagem do seu máximo.

Parâmetro	Tipo	Padrão	Notas
`fraction`	number	obrigatório	Fração da durabilidade máxima a consumir (ex: `0.1` = 10%)
`can_break`	boolean	`false`	Se `true`, o item é destruído quando a durabilidade acaba. Se `false`, a durabilidade para em 1.

`context.event`

Dados do evento para o hook atual. Disponível em hooks de clique, combate e interação para scripts de props e itens. Retorna nil em hooks que não têm evento associado (on_spawn, on_game_tick, on_destroy, on_zone_enter, on_zone_leave, on_equip).

Campos e Métodos

Campo ou Método	Tipo	Notas
`event.player`	tabela de entidade de jogador	O jogador que acionou o evento. Disponível em `on_left_click`, `on_right_click` e `on_projectile_hit` (o atirador, se foi um jogador). Veja Métodos de Entidade de Jogador para todos os campos e métodos.
`event.is_cancelled`	boolean	Se o evento está atualmente cancelado
`event.cancel()`	function	Cancela o evento (ex: previne dano ou interação)
`event.uncancel()`	function	Descancela um evento previamente cancelado

info

Nem todos os eventos são canceláveis. Se o evento Bukkit subjacente não implementa Cancellable, event.cancel() e event.uncancel() não estarão presentes e event.is_cancelled será sempre false.

Exemplo: Tornando um prop invulnerável

Exemplo

return {
  api_version = 1,

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

Exemplo: Verificando estado de cancelamento

Exemplo

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event and not context.event.is_cancelled then
      context.event.cancel()
      context.log:info("Damage cancelled!")
    end
  end
}

cuidado

Dentro de callbacks agendados (scheduler:run_later, scheduler:run_repeating), context.event é sempre nil. Modificação de evento só pode acontecer durante o próprio hook de evento.

`context.world`

A API world é compartilhada entre todos os plugins Nightbreak. Veja context.world para a referência completa.

info

Props do FMM usam a mesma tabela world do MagmaCore que bosses do EliteMobs. Todos os métodos documentados na página global (get_block_at, set_block_at, spawn_particle, play_sound, strike_lightning, get_time, set_time, get_nearby_entities, get_nearby_players, spawn_entity, get_highest_block_y, raycast, spawn_firework) estão disponíveis no FMM. Veja a API world do MagmaCore para detalhes completos sobre world:raycast() (lançar um raio e detectar entidades/blocos atingidos) e world:spawn_firework() (spawnar foguetes de fogos de artifício com cores e formas personalizadas). EliteMobs estende a tabela world com métodos adicionais para spawnar bosses, reforços e mais -- veja Mundo e Ambiente do EliteMobs.

Métodos de Entidade de Jogador

Tabelas de entidade de jogador são retornadas de context.event.player, context.world:get_nearby_players() e callbacks de zona.

API Compartilhada

As tabelas de entidade, métodos de entidade viva, métodos específicos de jogador e métodos de UI de jogador são compartilhados entre todos os plugins Nightbreak. Veja o Motor de Scripting Lua do MagmaCore para a referência completa cobrindo campos base de entidade, campos e métodos de entidade viva, campos e métodos específicos de jogador e Métodos de UI de Jogador. Novos métodos de jogador incluem player:get_target_entity() (mira por raycast), player:get_eye_location(), player:get_look_direction(), player:send_block_change() (blocos falsos por jogador) e player:reset_block() -- veja Métodos Específicos de Jogador para detalhes.

`context.zones`

A API de zonas é compartilhada entre todos os plugins Nightbreak. Veja context.zones para a referência completa.

`context.scheduler`

A API do scheduler é compartilhada entre todos os plugins Nightbreak. Veja context.scheduler para a referência completa.

`context.state`

A API de estado é compartilhada entre todos os plugins Nightbreak. Veja context.state para a referência completa.

`context.log`

A API de logging é compartilhada entre todos os plugins Nightbreak. Veja context.log para a referência completa.

Modelo de Runtime

Um Runtime por Instância de Script

Cada entidade prop que tem scripts vinculados recebe sua própria instância de runtime Lua independente. Quando o prop spawna, o FMM carrega o código fonte Lua, o avalia em um ambiente sandboxado novo e armazena a tabela retornada. Quando o prop é removido, o runtime é encerrado.

Para scripts de itens, um runtime é criado por par (jogador, itemId). Quando um jogador equipa um item personalizado, FMM cria uma instância de script para esse jogador e tipo de item. Quando o item é desequipado, o runtime é encerrado.

Isso significa:

Variáveis locais declaradas no escopo do arquivo são privadas para aquela instância de script.
context.state é completamente isolado entre instâncias, mesmo que compartilhem o mesmo arquivo de script.

Propriedade de Tarefas Agendadas

Todas as tarefas criadas através do context.scheduler pertencem ao runtime que as criou. Quando um prop é removido:

O runtime é encerrado.
Cada tarefa pertencente -- tanto de execução única quanto repetitiva -- é automaticamente cancelada.
Todos os monitoramentos de zona são limpos.

Orçamento de Execução

Cada invocação de hook e cada invocação de callback é cronometrada. Se uma única chamada levar mais que 50 milissegundos, o script é desabilitado com um aviso no console:

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

Para ficar dentro do orçamento:

Evite loops sem limite dentro de hooks.
Mantenha handlers on_game_tick leves -- eles rodam a cada tick.
Use context.scheduler:run_repeating(...) para distribuir trabalho entre ticks.

Referência Completa de Hooks

Esta tabela lista todos os hooks disponíveis em scripts de props e itens.

Hooks de Props (8)

Hook	Dispara quando	`context.event`
`on_spawn`	Prop spawna no mundo	nil
`on_game_tick`	Cada tick do servidor (50ms)	nil
`on_destroy`	Prop é removido	nil
`on_left_click`	Jogador clica esquerdo no prop	evento de dano
`on_right_click`	Jogador clica direito no prop	evento de interação
`on_projectile_hit`	Projétil atinge o prop	evento de acerto de projétil
`on_zone_enter`	Jogador entra em uma zona monitorada	nil
`on_zone_leave`	Jogador sai de uma zona monitorada	nil

Hooks de Itens (22)

Hook	Categoria	Dispara quando	`context.event`
`on_attack_entity`	Combate	Jogador ataca uma entidade	evento de dano
`on_kill_entity`	Combate	Jogador mata uma entidade	evento de morte
`on_take_damage`	Combate	Jogador recebe dano	evento de dano
`on_shield_block`	Combate	Jogador bloqueia com escudo	evento de dano
`on_shoot_bow`	Combate	Jogador dispara arco	evento de tiro de arco
`on_projectile_hit`	Combate	Projétil do jogador acerta	evento de acerto de projétil
`on_projectile_launch`	Combate	Jogador lança projétil	evento de lançamento
`on_right_click`	Interação	Jogador clica direito	evento de interação
`on_left_click`	Interação	Jogador clica esquerdo	evento de interação
`on_shift_right_click`	Interação	Jogador shift+clique direito	evento de interação
`on_shift_left_click`	Interação	Jogador shift+clique esquerdo	evento de interação
`on_interact_entity`	Interação	Jogador clica direito em entidade	evento de interação com entidade
`on_equip`	Equipamento	Item entra em slot ativo	nil
`on_unequip`	Equipamento	Item sai de slot ativo	nil
`on_swap_hands`	Equipamento	Troca mão principal/secundária	evento de troca
`on_drop`	Equipamento	Jogador solta item	evento de soltar
`on_break_block`	Utilidade	Jogador quebra bloco	evento de quebra de bloco
`on_consume`	Utilidade	Jogador consome item	evento de consumo
`on_item_damage`	Utilidade	Item recebe dano de durabilidade	evento de dano de item
`on_fish`	Utilidade	Jogador usa vara de pescar	evento de pesca
`on_death`	Utilidade	Jogador morre enquanto equipado	evento de morte
`on_game_tick`	Ciclo de vida	Cada tick enquanto equipado	nil

Próximos Passos

Exemplos e Padrões -- scripts completos e funcionais de props e itens com explicações
Solução de Problemas -- problemas comuns, dicas de depuração e checklist de QC
Primeiros Passos -- estrutura de arquivos, hooks, passo a passo do primeiro script

context.prop
context.item
context.event
context.world
Métodos de Entidade de Jogador
context.zones
context.scheduler
context.state
context.log
Modelo de Runtime
Referência Completa de Hooks
- Hooks de Props (8)
- Hooks de Itens (22)
Próximos Passos

context.prop​

Campos​

prop:play_animation(name, blend, loop)​

prop:stop_animation()​

prop:hurt_visual()​

prop:pickup()​

prop:mount(player)​

prop:dismount(player)​

prop:get_passengers()​

prop:has_mount_points()​

prop:spawn_elitemobs_boss(filename, x, y, z)​

prop:open_inventory(player, title, rows)​

prop:is_viewing_inventory(player)​

prop:place_book(player)​

prop:read_book(player)​

prop:take_book(player)​

prop:has_book()​

prop:drop_inventory()​

prop:drop_book()​

prop:set_persistent_data(key, value)​

prop:get_persistent_data(key)​

context.item​

Campos​

item:material()​

item:get_amount() / item:set_amount(n)​

item:consume(n)​

item:get_uses() / item:set_uses(n)​

item:get_name() / item:set_name(s)​

item:get_lore() / item:set_lore(table)​

item:get_durability()​

item:get_durability_percentage()​

item:use_durability(amount, can_break)​

item:use_durability_percentage(fraction, can_break)​

context.event​

Campos e Métodos​

Exemplo: Tornando um prop invulnerável​

Exemplo: Verificando estado de cancelamento​

context.world​

Métodos de Entidade de Jogador​

context.zones​

context.scheduler​

context.state​

context.log​

Modelo de Runtime​

Um Runtime por Instância de Script​

Propriedade de Tarefas Agendadas​

Orçamento de Execução​

Referência Completa de Hooks​

Hooks de Props (8)​

Hooks de Itens (22)​

Próximos Passos​

`context.prop`

Campos

`prop:play_animation(name, blend, loop)`

`prop:stop_animation()`

`prop:hurt_visual()`

`prop:pickup()`

`prop:mount(player)`

`prop:dismount(player)`

`prop:get_passengers()`

`prop:has_mount_points()`

`prop:spawn_elitemobs_boss(filename, x, y, z)`

`prop:open_inventory(player, title, rows)`

`prop:is_viewing_inventory(player)`

`prop:place_book(player)`

`prop:read_book(player)`

`prop:take_book(player)`

`prop:has_book()`

`prop:drop_inventory()`

`prop:drop_book()`

`prop:set_persistent_data(key, value)`

`prop:get_persistent_data(key)`

`context.item`

Campos

`item:material()`

`item:get_amount()` / `item:set_amount(n)`

`item:consume(n)`

`item:get_uses()` / `item:set_uses(n)`

`item:get_name()` / `item:set_name(s)`

`item:get_lore()` / `item:set_lore(table)`

`item:get_durability()`

`item:get_durability_percentage()`

`item:use_durability(amount, can_break)`

`item:use_durability_percentage(fraction, can_break)`

`context.event`

Campos e Métodos

Exemplo: Tornando um prop invulnerável

Exemplo: Verificando estado de cancelamento

`context.world`

Métodos de Entidade de Jogador

`context.zones`

`context.scheduler`

`context.state`

`context.log`

Modelo de Runtime

Um Runtime por Instância de Script

Propriedade de Tarefas Agendadas

Orçamento de Execução

Referência Completa de Hooks

Hooks de Props (8)

Hooks de Itens (22)

Próximos Passos