Funções (Edição Java)

Funções permitem que os jogadores executem listas de comandos usando arquivos de texto com a extensão .mcfunction. Recomenda-se usar a codificação ANSI (sem BOM) em arquivos de função para evitar problemas. Esta página cobre o uso de funções na Edição Java.

Uso

Para utilizar as funções, um arquivo de texto [FUNCTION_NAME].mcfunction pode ser colocado na pasta [WORLD_NAME]/datapacks/[DATA_PACK_NAME]/data/[NAMESPACE]/functions. Para executar a função, use o nome da função totalmente qualificado, que é [NAMESPACE]: [FUNCTION_NAME]. Se não houver ambiguidade com outros datapacks ou com um comando existente no minecraft, você pode apenas usar [FUNCTION_NAME]. Se o namespace for deixado de fora ao tentar chamar uma função, o padrão será o namespace minecraft: . O uso de um namespace personalizado é recomendado para evitar comportamento indesejado no caso de adições futuras ao namespace padrão.

As funções também podem ser colocadas em subpastas dentro da pasta functions. Também é necessário ter um arquivo pack.mcmeta na pasta [DATA_PACK_NAME]. Por exemplo, a execução da função custom: example /test fará referência ao arquivo localizado em data/custom/functions/example/test.mcfunction.

Funções, sendo arquivos de texto, são facilmente modificáveis e menos prováveis do que blocos de comando de induzirem lag quando usadas em grandes quantidades. Se uma função for modificada ou adicionada, o uso do comando /reload recarregará os arquivos de função do disco. Isso permite que o Minecraft reconheça quaisquer alterações nos arquivos de função, sem a necessidade de sair e entrar novamente no mundo.

Após a execução bem-sucedida da /function, uma mensagem será exibida no bate-papo: Comandos [quantidade] executados da função '[diretório do arquivo de função]'. As funções incorporadas não exibirão esta mensagem de bate-papo. A saída bem-sucedida dos comandos dentro de uma função não pode ser medida com um comparador (embora o mesmo efeito possa ser obtido com o uso dos comandos /execute store).

Em um único jogador ou em um mundo de LAN, com um bloco de comando, uma função pode executar qualquer comando que não seja mais restritivo do que o nível de permissão 2.

No software multijogador padrão, uma função pode executar qualquer comando que não seja mais restritivo do que o nível de permissão prescrito na configuração function-permission-level em server.properties.

Sintaxe da função

Testando o sistema de funções. Três mensagens /tellraw e um comando /give foram usados nesta função simples.

No arquivo .mcfunction, um comando válido é colocado por linha, sem a barra normal (/). Os jogadores podem adicionar comentários dentro do arquivo de texto da função começando uma linha com #.

Comandos individuais em funções podem ser maiores que o limite de 32.500 caracteres em blocos de comando, mas o número total de comandos executados dentro de uma função ainda obedecerá a /gamerule maxCommandChainLength, que é de 65.536 comandos por padrão; quaisquer comandos além deste limite serão ignorados.

Rodando uma função

As funções executarão todos os seus comandos em um único tick e as funções chamadas por outras funções também executarão seus comandos no mesmo tick de seu pai. As funções usarão o ambiente de comando de qualquer coisa chamada a função. Isso inclui o remetente do comando, posição, rotação, etc. Este contexto de comando é preservado para todos os comandos na função, então um comando /setblock usará o contexto de posição salvo mesmo quando um comando anterior na mesma função teletransportar o executor original para uma posição diferente. Por exemplo:

execute as @a at @s run function foo:bar

foo:bar

teleport @s ~ ~5 ~
setblock ~ ~-1 ~ emerald_block
execute at @s run setblock ~ ~-1 ~ diamond_block

Quando chamada através de um jogador, esta função irá teletransportar aquele jogador 5 blocos para cima, coloque um bloco de esmeralda um bloco abaixo de sua posição original antes do teletransporte, e coloque um bloco de diamante um bloco abaixo de sua nova posição após o teletransporte.

Como visto no exemplo acima, o contexto do comando pode ser atualizado normalmente por seus respectivos subcomandos /execute.

É sugerido usar @s seletor de destino para a entidade usada com mais frequência em uma função e usar /execute teste ao chamar essa função para modificar a entidade executora para a entidade usada com mais frequência. Isso pode simplificar o conteúdo se a entidade foi selecionada com argumentos do seletor de destino e melhorar o desempenho em geral para a iteração reduzida por meio da lista de entidades mundiais.

Existem vários métodos de execução de um arquivo de função no jogo:

Comandos

/function

• Permite que os jogadores executem uma função ou todas as funções em uma tag de função uma vez.
• Usa o ambiente de comando de qualquer coisa chamada de comando /function.
• O ambiente de comando inicial pode ser modificado pelo comando /execute.
• Uso: /function <name>

Progressos

Progressos podem rodar uma função ao serem completados. Os comandos da função são executados pelo jogador que completou o avanço.

As funções de recompensa são chamadas em arquivos de avanço JSON usando o seguinte formatot:

{
    "rewards": {
        "function": "namespace:path/to/function/file"
    }
}

Tags

As funções podem ser agrupadas usando tags em datapacks. Essas tags podem então ser chamadas para executar todas as funções dentro dessa tag com /function# (namespace) : (tag) .

As funções marcadas em tick serão executadas automaticamente a cada tick no início do tick. As funções marcadas em load serão executadas após (re) carregar o datapack.

• Nota: tick será executado antes de load após recarregar o datapack. Isso significa que você não pode depender inerentemente de um estado estável do datapack para o primeiro tick. *

História

Edição Java
1.12		pre1			Funções adicionadas.
		pre3			Os comandos não podem mais começar com / (barra)
					Os comentários agora só podem ser precedidos com #; usar // não é mais permitido
		pre4			Adicionados novos argumentos ao comando /function: [if | A menos que] [seletor]
		pre6			Funções ignoradas (quando uma condição falha) agora são consideradas falhas quando usadas em comandos.
1.13		17w43a			Funções personalizadas foram movidas para pacotes de dados.
		17w45a			As funções agora são completamente analisadas e armazenadas em cache no carregamento.
		17w49b			Removido /gamerule gameLoopFunction.
					A função agora pode ser marcada.
					As funções marcadas em tick agora são executadas a cada tick no início do tick.
		18w01a			As funções marcadas em load agora são executadas após recarregar o datapack.
1.14.4		pre4			Adicionado nível de permissão de função ao server.properties

Problemas

Problemas relacionados com "Function" são mantidos no rastreador de erros. Reporte problemas lá, em inglês.

Referências

Predefinição:Data packs