Encantamentos personalizados

O EliteMobs e o FreeMinecraftModels fornecem encantamentos personalizados através de um sistema MagmaCore partilhado. Cada plugin mantém as suas definições e efeitos Lua na sua própria pasta enchantments/. Os encantamentos nativos do Minecraft continuam no espaço de nomes minecraft:.

Atualizar definições incluídas

O catálogo restaura ficheiros YAML e Lua incluídos que estejam em falta e acrescenta campos predefinidos em falta às definições incluídas existentes. Preserva os valores já configurados e o código Lua existente. Isto também funciona quando o diretório enchantments/ já existe.

O plugin responsável pode primeiro arquivar ficheiros que correspondam a um formato retirado. Por exemplo, o EliteMobs preserva o YAML de encantamentos que contenha maxLevelV2 antes de gerar as predefinições atuais. O EliteMobs também arquiva cópias não editadas de versões anteriores dos scripts de encantamentos incluídos, como um grappling_hook.lua antigo, para que a predefinição atual seja escrita no seu lugar; um script que tenha editado permanece. Reveja as suas configurações no arquivo de configurações e volte a aplicá-las usando os campos atuais. Um efeito atualizado de DLC ou personalizado continua a precisar da sua própria definição e código Lua correspondentes.

Referências de itens

Os efeitos personalizados usam um ID com espaço de nomes em minúsculas e um nível inteiro positivo. Este é um exemplo de uma definição de item do FMM:

enchantments:
  - "minecraft:unbreaking,3"
  - "elitemobs:critical_strikes,2"

Por exemplo, critical_strikes.yml no catálogo de encantamentos do EliteMobs define elitemobs:critical_strikes. Uma definição FMM usa freeminecraftmodels:. As subpastas não fazem parte do ID; atribua nomes de ficheiro únicos aos conteúdos.

O YAML de itens personalizados do EliteMobs mantém nomes Bukkit como UNBREAKING,3 para encantamentos nativos, mas exige IDs com espaço de nomes para efeitos personalizados. Não copie a sintaxe de itens nativos do FMM para outro plugin sem confirmar o formato de itens desse plugin.

O provider instalado tem de reconhecer o ID. A compatibilidade, o tipo de item, o espaço, os conflitos e as capacidades necessárias vêm da definição correspondente. Remover um provider não transforma o seu efeito personalizado num encantamento nativo.

Formato das definições

Esta é a definição FMM de Ignition incluída no plugin, associada a ignition.lua no mesmo catálogo de encantamentos:

isEnabled: true
name: Ignition
description: Sets surviving targets on fire after a staff fireball hits.
maxLevel: 3
curse: false
validSlots: [MAINHAND]
itemTypes: [STAFF]
attackKinds: [STAFF_FIREBALL]
requires: []
conflicts: []
stacking: source_item
script: ignition.lua
parameters:
  base_ticks: 20
  ticks_per_level: 20

return {
    api_version = 1,
    on_ignition_ticks = function(context)
        return math.max(0, math.min(200, context.parameters.base_ticks
            + context.parameters.ticks_per_level * context.enchantment.level))
    end
}

Esta consulta devolve ao FMM a duração da ignição. Não é executada como script de elemento decorativo nem como script de item equipado.

Campo	Significado
`isEnabled`	Predefinido como `true`; definições desativadas não entram no catálogo
`name`	Nome de apresentação simples obrigatório
`description`	Descrição opcional, vazia por predefinição
`maxLevel`	Limite positivo do nível de encantamento; itens definidos explicitamente podem ultrapassá-lo
`curse`	Indica se o encantamento é uma maldição; predefinido como `false`
`validSlots`	Espaços de equipamento: `HEAD`, `CHEST`, `LEGS`, `FEET`, `MAINHAND`, `OFFHAND`
`itemTypes`	Categorias aceites: `SWORD`, `AXE`, `PICKAXE`, `SHOVEL`, `HOE`, `BOW`, `CROSSBOW`, `TRIDENT`, `MACE`, `SPEAR`, `HELMET`, `CHESTPLATE`, `LEGGINGS`, `BOOTS`, `SHIELD`, `FISHING_ROD`, `SHEARS`, `ELYTRA`, `WAND`, `STAFF`, `OTHER`
`attackKinds`	Filtro opcional para ataques mágicos: `WAND_MISSILE`, `STAFF_MELEE`, `STAFF_FIREBALL`
`requires`	Requisitos de capacidades do provider
`conflicts`	Outros IDs de encantamento com espaço de nomes em minúsculas
`stacking`	`source_item` por predefinição ou `sum_equipped_levels`
`script`	Nome de ficheiro `.lua` obrigatório em minúsculas e sem diretório
`parameters`	Valores escalares nomeados ou listas escalares por nível
`set`	Opcional. Faz deste encantamento um conjunto de itens

Uma lista por nível tem de conter exatamente maxLevel entradas. Acima desse nível, é mantido o último valor da lista, enquanto o script continua a receber o nível real do encantamento. Os parâmetros pertencem ao efeito específico; colocar uma chave arbitrária aqui não cria uma mecânica nova.

Campos de topo desconhecidos, IDs duplicados, scripts em falta e eventos não suportados rejeitam o catálogo candidato. Corrija o ficheiro indicado no erro antes de recarregar. Um candidato falhado não substitui o catálogo ativo.

Responsabilidade pelos efeitos

Comece por um efeito fornecido pelo plugin que será dono da sua nova definição. Os eventos suportados e as operações do domínio desse efeito determinam o que ele pode fazer. Os eventos de consulta devolvem valores como o número de projéteis, a probabilidade de crítico ou o bónus de ameaça. Os eventos de ação tratam os itens aceites e podem manter efeitos temporizados.

A antiga API context.item do FMM e o seu ciclo de equipar/des-equipar não se aplicam aqui. Os scripts de encantamentos usam o seu próprio context.enchantment, context.parameters, a informação da origem capturada e as operações de ação. Não renomeie um script de item antigo esperando que o contexto seja compatível.

Livros e bigornas

Os livros encantados personalizados usam as mesmas definições de provider que os itens equipados. Uma bigorna valida o item de origem, o livro e o resultado completo, incluindo encantamentos nativos. Níveis personalizados iguais combinam-se no nível seguinte; níveis diferentes mantêm o mais alto. Cada encantamento personalizado alterado adiciona o seu nível resultante ao custo nativo de reparação. O nível resultante tem de respeitar o limite de nível da bigorna, o espaço, o tipo, as capacidades e os conflitos da definição.

Os livros mistos têm de transferir todas as entradas nativas aceites pelo servidor, além das entradas personalizadas. Se o servidor rejeitar uma entrada nativa, a operação personalizada também é rejeitada, em vez de a remover silenciosamente. Definições inválidas ou indisponíveis rejeitam igualmente a pré-visualização. As entradas e o estado do provider são verificados de novo ao recolher o resultado; uma pré-visualização visível não é uma reserva que sobreviva a uma alteração do catálogo.

Referência de consultas Lua

As consultas numéricas executam uma instância de script nova e fecham-na logo após devolver o resultado. Devolva um número finito ou nil quando não houver contribuição. O estado e o trabalho agendado não sobrevivem à consulta. Uma definição falhada fica isolada até um recarregamento bem-sucedido do catálogo; esgotar o orçamento restante do chamador, por si só, não isola a definição.

Contexto	Conteúdo
`context.enchantment`	`id` e `level` real
`context.parameters`	Valores desta definição resolvidos para esse nível
`context.input`	Factos escalares fornecidos pela mecânica proprietária; use o efeito incluído para conhecer as chaves exatas
`context.target`	Tabela de entidade ou entidade viva alvo, ou nil
`context.player`	Jogador que desencadeou a consulta, quando aplicável

O FMM fornece on_missile_count, on_missile_damage_factor, on_blast_radius_factor e on_ignition_ticks. Outros providers expõem os seus próprios eventos numéricos. Uma definição só pode declarar eventos aceites pelo respetivo provider.

Referência de ações Lua

Os scripts de ação usam as tabelas partilhadas de agendador, intervalos, mundo, zonas, jogador e eventos. Executam-se para uma entrada ou ataque aceite, usando uma origem capturada nos callbacks seguintes. O chat guarda a mensagem durante o evento de chat e captura o equipamento quando o despacho é executado no thread do servidor. O parâmetro opcional parameters.lifetime_ticks tem de ser um número inteiro positivo; sem ele, a ativação dura um tick. Os efeitos agendados precisam de uma duração definida suficientemente longa para terminar.

As ativações param quando termina a duração, quando o ator morre, se desconecta ou muda de mundo, quando o mundo proprietário descarrega, quando descarrega um chunk que contenha uma das entidades próprias ou quando o provider recarrega ou é desativado. Podem terminar mais cedo quando a última entrada deixa de ter trabalho próprio. parameters.stop_on_unequip: true também para uma ativação quando o item capturado deixa de estar equipado. Os intervalos locais pertencem ao jogador e ao ID do encantamento; os globais pertencem ao jogador dentro do provider. Ambos sobrevivem a trocas de equipamento, ativações concluídas, mudanças de mundo e recarregamentos válidos, e são limpos ao desligar ou encerrar o provider.

Evento	Entrada aceite
`on_attack_entity`	Dano corpo a corpo nativo positivo aceite com o item na mão principal, ou ataque explícito do plugin
`on_projectile_hit`	Dano aceite a uma entidade viva por um projétil de arco capturado, uma vez por projétil e alvo, ou impacto explícito do plugin
`on_take_damage`	Dano positivo no jogador; os espaços equipados elegíveis são inspecionados
`on_right_click`, `on_left_click`	Interação com a mão sem agachar
`on_shift_right_click`, `on_shift_left_click`	Interação com a mão enquanto agacha; substituem o evento de clique normal correspondente
`on_break_block`	Destruição aceite de um bloco pelo jogador usando o item da mão principal
`on_chat`	Chat aceite, despachado no thread do servidor com a mensagem capturada
`on_sneak`	Entrada no estado de agachamento; as contribuições de equipamento são recolhidas por definição
`on_projectile_launch`	Munição encantada consumida ao lançar uma flecha através de um evento de arco
`on_game_tick`	Tick enquanto esta ativação permanecer ativa
`on_zone_enter`, `on_zone_leave`	Jogadores que atravessam uma zona observada por esta ativação

Estes eventos não criam um runtime separado para equipar/des-equipar. Uma definição que só use on_game_tick ainda precisa de um evento de entrada para iniciar a ativação. Os eventos nativos de ataque, dano, chat e mineração observam entradas já aceites; não podem cancelar o evento original. Os quatro eventos de interação expõem um sinalizador de cancelamento síncrono: context.event:cancel() recusa a interação correspondente com item ou bloco. Callbacks agendados não podem cancelar retroativamente uma entrada.

Contexto	Conteúdo
`context.enchantment`	`id`, `level`
`context.parameters`	Parâmetros da definição resolvidos para o nível
`context.player`	Tabela do jogador que atua
`context.target`	Tabela da entidade viva afetada, ou nil
`context.source`	Factos capturados: `item`, `slot`, `inventory_slot`, `equipment`, `attack_kind`, `providers`; algumas entradas também fornecem `ammunition`, `projectile`, `message`, `block`, `drop_items`, `sneaking` ou `equipped_levels`
`context.item`	Métodos de durabilidade e consumo do espaço capturado, quando o item continua endereçável; consulte métodos de item
`context.action`	`id` (UUID do ataque), `instance` (token da ativação), `actor` (UUID), `world` (UUID do mundo) e os métodos abaixo
`context.set`	Para um conjunto de itens: `id`, `name`, `level` e `pieces`; nil nos restantes casos

Os snapshots de itens contêm material, amount e enchantments. São dados, não objetos de inventário ativos. Os UUIDs nos factos de origem são cadeias de texto. source.block da mineração contém x, y, z e material em minúsculas.

Método de ação	Devolve	Comportamento
`stop()`	nil	Para esta ativação e limpa o trabalho que lhe pertence
`has_previous()`	bool	Verifica se existe outra instância ativa deste encantamento para o mesmo jogador
`replace_previous()`	nil	Para as instâncias anteriores e preserva esta
`damage_target(target_uuid, amount)`	bool	Pede ao provider dano finito positivo com a atribuição de origem capturada; false quando rejeitado
`own_entity(uuid)`	bool	Regista uma entidade válida do mesmo mundo que não seja jogador para remoção na limpeza; use depois de a criar
`launch_projectile(location, direction, speed, range, ticks, impact, visual?, protected_path?=false)`	bool	Lança um projétil controlado pelo script; velocidade e alcance têm de ser finitos e positivos e ticks tem de ser pelo menos 1
`attribute_projectile(uuid, callback, protect?=false)`	bool	Associa o dano de um projétil nativo próprio a um callback definido
`place_block(x, y, z, expected_material, block_data)`	bool	Coloca através da validação de ação de bloco do jogador apenas quando o material atual corresponde
`break_block(x, y, z, expected_material, drop_material?, amount?=1)`	bool	Destrói através da validação de ação de bloco do jogador com uma queda de item opcional
`break_naturally(x, y, z, expected_material)`	bool	Destrói usando a ferramenta capturada e a política de drops do evento de destruição de origem
`temporary_block(x, y, z, block_data, ticks?=0)`	bool	Reserva um bloco carregado e restaura-o na limpeza ou após ticks positivos; zero dura até à limpeza
`can_own_block(x, y, z)`	bool	Verifica coordenadas carregadas e se a posse temporária está disponível
`temporary_gravity(uuid, enabled)`	bool	Reserva o estado da gravidade e restaura-o na limpeza
`restore_gravity(uuid)`	bool	Restaura antecipadamente a reserva de gravidade desta ativação
`temporary_scale(uuid, scale)`	bool	Reserva a escala de uma entidade viva até à limpeza
`temporary_potion(uuid, type, ticks, amplifier)`	bool	Reserva um efeito de poção durante ticks positivos e com amplificador não negativo
`restore_potion(uuid, type)`	bool	Restaura antecipadamente a reserva de poção desta ativação
`ride_rails(speed)`	bool	Senta o jogador numa vagoneta que só os clientes veem e conduz-a pelos carris ligados no bloco do jogador, em direção à ponta para onde está virado, a `speed` blocos por tick (acima de 0, no máximo 2); false quando não há carril aí, o jogador já está montado ou o adaptador NMS do servidor não está disponível

Uma viagem sobre carris é trabalho que pertence à sua ativação. Agachar-se, o fim da linha, um teletransporte, a morte, desligar-se ou qualquer outra coisa que afaste o jogador mais de um bloco da vagoneta termina a viagem e, depois, a ativação; o jogador é colocado onde a vagoneta parou, exceto após um teletransporte, a morte ou desligar-se. Parar a ativação, incluindo através de replace_previous(), também tira o jogador da vagoneta. O lifetime_ticks da ativação continua a aplicar-se, por isso dê-lhe tempo suficiente para a linha mais longa.

Os callbacks de impacto de projéteis recebem (fresh_context, target_or_nil, location); os callbacks visuais recebem (fresh_context, location). Os callbacks de dano de projéteis nativos recebem (fresh_context, target, native_damage) no tick seguinte. Substituem a aplicação nativa e têm de aplicar explicitamente o dano pretendido, normalmente através de fresh_context.action:damage_target(target.uuid, amount). Com protect=true nativo, blocos protegidos de explosões e ignição são filtrados. protected_path=true em projéteis controlados pelo script absorve voos que atravessem posições protegidas ou não carregadas.

A limpeza própria limita-se às operações que registam posse. world:spawn_entity, entity:set_gravity e world:set_block_at normais não passam automaticamente a ter limpeza da ação. Os métodos de estado temporário gerem a restauração; não substituem a verificação de que um efeito hostil ou uma edição de bloco é permitida.

Conjuntos de itens

Uma secção set transforma um encantamento num conjunto de itens. Coloque o mesmo encantamento em todas as peças. O conjunto está completo enquanto cada espaço listado em pieces tiver um item que o transporte. Um conjunto completo executa os seus hooks uma vez por evento. Com qualquer peça em falta, não se executa nada.

name: Crooked's Full Set
maxLevel: 1
validSlots: [HEAD, CHEST, LEGS, FEET]
itemTypes: [HELMET, CHESTPLATE, LEGGINGS, BOOTS]
script: crooked_set.lua
parameters:
  lifetime_ticks: 620
  stop_on_unequip: true
set:
  pieces:
    HEAD: Crooked's Hex-Brim
    CHEST: Crooked's Warded Wrap
    LEGS: Crooked's Bent Hosen
    FEET: Crooked's Wayward Soles
  lore:
    - "&5Crooked's Full Set &7($equippedPieces/$totalPieces)"
    - "$setPieces"
    - "&7When damaged, has a 5% chance to grant Regeneration I."

return {
    api_version = 1,
    on_take_damage = function(context)
        -- Runs only while all four pieces are worn, once per hit.
        context.action:temporary_potion(context.player.uuid, "REGENERATION", 100, 0)
    end
}

Campo do conjunto	Significado
`pieces`	Obrigatório. Associa espaços de equipamento a nomes de peças. Quando `validSlots` está definido, tem de incluir o espaço de cada peça
`name`	Nome usado por `$setName`. Por predefinição, é o `name` do encantamento e aceita códigos de cor `&`
`lore`	As linhas de lore do conjunto. Por predefinição, o nome do conjunto com o número de peças, seguido de uma linha por peça
`equippedPiece`	Linha de uma peça vestida. Por predefinição, `&a✔ $pieceName`
`missingPiece`	Linha de uma peça em falta. Por predefinição, `&c✘ $pieceName`

A lore do conjunto aceita estes placeholders:

Placeholder	Mostra
`$setName`	O nome do conjunto
`$equippedPieces`	Quantas peças o jogador veste
`$totalPieces`	Quantas peças tem o conjunto
`$setPieces`	Uma linha por peça, por ordem de espaço, a partir de `equippedPiece` ou `missingPiece`. O texto à volta do placeholder repete-se em cada linha
`$pieceName`, `$pieceSlot`	Dentro de `equippedPiece` e `missingPiece`, o nome da peça e o seu espaço, como `Head` ou `Main Hand`
`$ifSetComplete`	Mostra a linha apenas enquanto todas as peças estão vestidas
`$ifSetIncomplete`	Mostra a linha apenas enquanto falta uma peça

Os itens de conjunto mostram esta secção em vez de uma linha na lista de encantamentos personalizados. No EliteMobs, coloque $itemSet em itemLoreStructureV2 em ItemSettings.yml, ou na própria lore de um item personalizado. Sem nenhuma das duas, o conjunto segue a lore personalizada do item. $ifItemSet mostra uma linha da estrutura apenas em itens de conjunto. Os itens personalizados do FMM mostram o conjunto na linha de lore que contém $itemSet, ou depois da sua lore.

A secção mostra o que o jogador que transporta o item veste e é redesenhada quando equipa ou remove uma peça. Um item guardado fora do inventário de um jogador mantém o estado que mostrava quando saiu.

Os hooks de conjunto diferem dos hooks de encantamentos normais em alguns aspetos:

Todos os hooks de ação da tabela acima chegam a um conjunto completo, sejam quais forem os espaços das suas peças. Um conjunto de armadura pode responder a on_attack_entity ou a on_break_block.
A conclusão é verificada quando o evento acontece. Um projétil verifica os conjuntos vestidos quando atinge o destino, e qualquer projétil conta, não apenas as flechas de arco.
on_take_damage define context.target como o atacante, quando existe.
context.source.item e context.item são a primeira peça por ordem de espaço: HEAD, CHEST, LEGS, FEET, MAINHAND, OFFHAND. Leia context.source.equipment.MAINHAND para obter a arma ou ferramenta segurada.
context.set.level é o nível mais baixo entre as peças. context.set.pieces tem como chave o espaço, com o name e o inventory_slot de cada peça.
stop_on_unequip: true interrompe uma ativação de conjunto quando qualquer peça é retirada.
As consultas numéricas, como a ameaça e a probabilidade de crítico do EliteMobs ou os modificadores de lançamento do FMM, contam um conjunto uma única vez e só enquanto está completo.

Atualizar conteúdo existente

O FMM ignora itens personalizados com scripts: não vazio ou entradas de encantamentos sem espaço de nomes que tenham sido retiradas. Substitua essas definições de itens por encantamentos com espaço de nomes; os scripts de elementos decorativos continuam suportados.

Os efeitos personalizados do EliteMobs usam agora maxLevel e parameters específicos do efeito no YAML do provider. A configuração de encantamentos nativos e de nível Elite é um formato separado. Consulte a referência de encantamentos do EliteMobs em vez de copiar um ficheiro maxLevelV2 antigo para uma definição de provider.

Atualizar definições incluídas​

Referências de itens​

Formato das definições​

Responsabilidade pelos efeitos​

Livros e bigornas​

Referência de consultas Lua​

Referência de ações Lua​

Conjuntos de itens​

Atualizar conteúdo existente​