Écrire fonctions et fichiers
Quatre façons d'ajouter vos propres fonctions, advancements et tags au pack : des fichiers statiques chargés par beet.yml, l'API native de beet, les fonctions helper de StewBeet, et Bolt. La plupart des packs utilisent les helpers pour leur logique et les fichiers statiques pour le reste.
Votre code s'exécute dans un plugin utilisateur, après la mise en place des définitions et avant la finalisation.
Écrivez tout cela avec les commandes vérifiées à la frappe. Chaque approche ci-dessous finit par des commandes dans une chaîne Python, dans un module
.bolt, ou les deux. L'extension StewBeet pour VSCode les lit pour ce qu'elles sont : complétion, erreurs, ctrl+clic, et un lien de chaque bloc vers la fonction que votre build en a tirée. Voir Support éditeur.
Des fichiers complets à lire en parallèle de cette page :
- extensive/src/link.py, le template
- SimplEnergy/src/utils/machines.py, un pack publié
- StardustFragment/src/utils/remaining.py, un pack publié
Quelle approche choisir
| Approche | Idéale pour | Effort |
|---|---|---|
Fichiers statiques (beet.yml) | Fonctions et JSON écrits à la main qui ne changent pas | Le plus faible |
| API native beet | Types de fichiers inhabituels, contrôle total sur chaque objet | Le plus élevé |
| Helpers StewBeet (recommandé) | Logique générée depuis vos définitions, fonctions de load et d'horloge | Faible |
| Bolt | Logique riche en commandes, boucles et arithmétique autour des commandes | Moyen, un second langage |
Approche 1 : Chargement de fichiers statiques (beet.yml)
Beet charge des fichiers écrits à la main depuis un dossier avant l'exécution de tout plugin.
# Dans beet.yml
data_pack:
name: "datapack"
load: ["src"] # Charge tous les fichiers .mcfunction et .json depuis src/
resource_pack:
name: resource_pack
load: ["src"] # Charge tous les fichiers de textures, models et sons depuis src/Comment ça marche :
- Placez les fichiers
.mcfunctiondanssrc/data/<namespace>/function/ - Placez les fichiers
.jsondanssrc/data/<namespace>/advancement/,src/data/<namespace>/recipe/, etc. - Beet les charge automatiquement aux emplacements corrects du pack
- Les fichiers sont chargés avant que le code des plugins ne s'exécute
Exemple de structure :
src/
├── data/
│ └── my_namespace/
│ ├── function/
│ │ ├── load.mcfunction
│ │ └── tick.mcfunction
│ ├── advancement/
│ │ └── my_advancement.json
│ └── recipe/
│ └── my_recipe.json
└── assets/
└── my_namespace/
└── textures/
└── item/
└── my_item.png| Dossier | Contient |
|---|---|
data/ | Tout le contenu du datapack : fonctions, advancements, recipes, tags |
function/ | Les commandes Minecraft, en fichiers .mcfunction |
advancement/ | Succès et déclencheurs techniques, en .json |
recipe/ | Recipes de craft, de cuisson et autres, en .json |
assets/ | Tout le contenu du resource pack : textures, models, sounds |
textures/ | Images PNG des items, blocs et du reste |
À utiliser quand :
- Vous avez des fichiers statiques qui n'ont pas besoin de génération dynamique
- Vous organisez des commandes et données pré-écrites
- Vous voulez une structure de fichiers simple et directe
À éviter quand :
- Vous devez générer du contenu basé sur des définitions
- Vous devez combiner plusieurs sources de données
- Vous avez besoin de génération conditionnelle de fichiers
Approche 2 : API native Beet
L'API objet de beet, utilisée directement depuis un plugin.
from beet import Context, Function, Advancement, FunctionTag
from stouputils.typing import JsonDict
def beet_default(ctx: Context):
# Écrire une fonction
ctx.data["my_namespace"].functions["my_folder/my_function"] = Function("""
# Ceci est ma fonction
say Bonjour le monde !
scoreboard players add @a points 1
""")
# Écrire un advancement
advancement_data: JsonDict = {
"criteria": {
"requirement": {
"trigger": "minecraft:inventory_changed"
}
},
"rewards": {
"function": "my_namespace:rewards/give_item"
}
}
ctx.data["my_namespace"].advancements["my_advancement"] = Advancement(advancement_data)
# Écrire un tag de fonction
tag_data: JsonDict = {
"values": [
"my_namespace:my_folder/my_function",
"my_namespace:another_function"
]
}
ctx.data["my_namespace"].function_tags["minecraft:load"] = FunctionTag(tag_data)À utiliser quand :
- Vous avez besoin d'un contrôle total sur les objets fichiers
- Vous travaillez avec des structures imbriquées complexes
- Vous voulez la sécurité de type avec le modèle d'objets de beet
À éviter quand :
- Vous voulez des écritures de fichiers simples et rapides
- Vous gérez beaucoup de petites fonctions
- Vous avez besoin de gestion automatique des chemins
Approche 3 : Fonctions helper StewBeet (Recommandé)
Les helpers StewBeet prennent un chemin et une chaîne, créent le fichier ou le complètent, et savent où vivent les fonctions de load, de tick et d'horloge.
from stewbeet import write_function, write_load_file, write_tick_file, Mem
def beet_default(ctx: Context):
ns = ctx.project_id
# Écrire une fonction simple
write_function(f"{ns}:my_folder/my_function", """
# Ceci est ma fonction
say Bonjour le monde !
scoreboard players add @a points 1
""")
# Ajouter au fichier de chargement (s'exécute au chargement du datapack : "your_namespace:v{version}/load/confirm_load")
write_load_file("""
# Initialiser les scoreboards
scoreboard objectives add points dummy
scoreboard objectives add data dummy
""")
# Ajouter au fichier tick (s'exécute à chaque tick : "your_namespace:v{version}/tick")
write_tick_file("""
# Vérifier les joueurs avec scores élevés
execute as @a[scores={points=100..}] run function my_namespace:rewards/high_score
""")
# Écrire des fonctions versionnées (horloge automatique : "your_namespace:v{version}/second", etc.)
write_versioned_function("second", """
# S'exécute toutes les secondes (20 ticks)
execute as @a run title @s actionbar {"score":{"name":"@s","objective":"points"}}
""")
write_versioned_function("minute", """
# S'exécute toutes les minutes (1200 ticks)
say Une minute s'est écoulée !
""")À utiliser quand :
- Vous voulez un code simple et lisible
- Vous avez besoin de gestion automatique des chemins
- Vous utilisez les conventions de StewBeet (fonctions versionnées, fichiers load/tick)
- Vous voulez ajouter/préfixer du contenu facilement
À éviter quand :
- Vous avez besoin d'une organisation de fichiers non standard
- Vous n'utilisez pas le framework StewBeet
Approche 4 : Bolt
Bolt est la couche de script de mecha, et elle inverse les trois approches précédentes.
Au lieu que du Python écrive une chaîne qui contient des commandes, les commandes sont la syntaxe : dans un fichier .bolt, item = 3 est du Python et item modify entity @s weapon.mainhand set value ... est une commande, à la même indentation, dans la même portée.
Tout s'exécute au build. Rien du Python n'atteint le datapack.
# Dans beet.yml
require:
- "stewbeet"
- "bolt"
pipeline:
- "mecha" # bolt a besoin de mecha pour compiler ce qu'il a produit
meta:
bolt:
entrypoint: "*" # autorise bolt dans n'importe quel fichier de fonction, pas seulement les modulesDeux types de fichiers :
- Les modules,
.boltsousdata/<namespace>/module/. Importables, ils n'écrivent une fonction que là où ils le demandent. - Les fichiers de fonction,
.mcfunctioncouverts parentrypoint. Le fichier est une fonction, écrite en bolt.
Écrire une fonction
# src/data/voltaic/module/gui.bolt
MACHINES = ["pulverizer", "furnace", "smelter"]
for machine in MACHINES:
function f"voltaic:gui/{machine}/open":
playsound minecraft:block.barrel.open block @s ~ ~ ~ 0.6 1.4
data modify entity @s equipment.head set from storage voltaic:gui Icon
tag @s add voltaic.watchingTrois fonctions issues d'une boucle. La f-string est le chemin, le bloc indenté est le corps.
Un chemin est une valeur comme une autre : il se nomme, s'importe et se passe en argument. Deux raccourcis évitent d'écrire le namespace :
| Écrit | Résout en |
|---|---|
./load | <namespace>:<chemin du module>/load |
~/init | Un enfant de la fonction en cours d'écriture à cet endroit |
SERVER_LOAD = ./load
prepend function_tag minecraft:load {"values": [SERVER_LOAD]}
function SERVER_LOAD:
forceload add 0 0
scoreboard objectives add voltaic.energy dummyImbrication et execute implicite
Un execute qui se termine par deux-points écrit sa propre fonction et l'appel qui y mène :
execute as @a[tag=voltaic.using] at @s:
particle minecraft:electric_spark ~ ~1 ~
playsound minecraft:block.beacon.ambient block @s ~ ~ ~ 0.4 2.0Les conditions se lisent comme des conditions, avec if, else et les formes run return repliées dedans :
if score @s voltaic.energy matches 1..:
scoreboard players remove @s voltaic.energy 1
else:
function voltaic:machines/shutdownCompléter une fonction qui appartient à un autre module
from voltaic:core import SERVER_LOAD
append function SERVER_LOAD:
team add builder "Builder"
team modify builder color blackfunction, append function et prepend function sont les trois façons pour un module de contribuer à un chemin.
Plusieurs modules peuvent compléter la même fonction de load sans se connaître, et c'est ce qui rend viable un fichier par fonctionnalité.
C'est du Python, donc tout le langage est là
Les imports prennent une resource location là où Python prend un chemin pointé :
from lib:helpers import ticks # un module d'un autre namespace
from ./items import team_flag # un module voisin
from dataclasses import dataclass # du Python normal, depuis votre environnement
from functools import cacheClasses et décorateurs fonctionnent, et une méthode peut écrire des fonctions :
from functools import cached_property
class Gui:
""" L'interface d'une machine, ouverte par un clic droit dessus. """
def __init__(self, machine):
self.path = f"voltaic:gui/{machine}"
@cached_property
def open(self):
function f"{self.path}/open":
playsound minecraft:block.barrel.open block @s ~ ~ ~ 0.6 1.4
tag @s add voltaic.watching
return f"{self.path}/open"
gui = Gui("pulverizer")
function voltaic:gui/pulverizer/tick:
execute as @a[tag=voltaic.using] run function gui.opencached_property fait un vrai travail ici : la fonction est écrite la première fois que quelqu'un demande son chemin, et jamais deux fois.
Les fichiers JSON sont des littéraux, avec les valeurs Python déposées directement dedans :
ON_KILL = ./on_kill
advancement ON_KILL {
"criteria": {"kill": {"trigger": "minecraft:player_killed_entity"}},
"rewards": {"function": ON_KILL}
}
function ON_KILL:
advancement revoke @s only ON_KILLScoreboards et storage comme des variables
bolt_expressions (pip install bolt-expressions, puis à ajouter dans require) transforme l'arithmétique en les commandes qui l'exécutent :
from bolt_expressions import Scoreboard, Data
Energy = Scoreboard("voltaic.energy")
Temp = Data.storage("voltaic:temp")
Energy["@s"] -= 20
Energy["#total"] = Energy["@s"] * 3 + Energy["#buffer"]
Temp.display.text = Energy["#total"]Chaque ligne compile vers la séquence de scoreboard players operation nécessaire, temporaires compris.
C'est le même travail que les Équations côté StewBeet, exprimé dans le fichier qui s'en sert.
Bolt et StewBeet dans le même pack
Rien n'oblige à choisir. Un pack peut déclarer ses items avec Item(...), laisser les plugins générer les recipes et le manuel, écrire l'essentiel de sa logique avec write_function, et garder un module .bolt pour la partie où les commandes sont le point difficile.
Le pack de démonstration dont l'extension tire ses enregistrements est exactement cela : un petit pack écrit de trois façons.
À utiliser quand :
- Ce sont les commandes qui sont compliquées, pas les données derrière
- Vous voulez des boucles, des conditions et des classes autour des commandes sans f-string entre vous et elles
- Vous faites de l'arithmétique de scoreboard ou de storage et voulez la lire comme de l'arithmétique
- Vous voulez l'imbrication (
execute ...:) plutôt que de découper les fonctions à la main
À éviter quand :
- Le travail consiste à générer beaucoup de fonctions quasi identiques depuis vos définitions.
write_functiondans un plugin voitMem.definitionset c'est la route la plus courte - Un plugin StewBeet doit voir ce que vous avez écrit. Les plugins tournent sur le pack, et mecha compile après eux
- Vos collaborateurs ne veulent pas d'un second langage dans le projet
Dans l'éditeur
L'extension StewBeet donne au .bolt son propre langage, avec complétion et ctrl+clic sur les commandes et un lens par fonction que le module écrit.
Elle empêche aussi Spyglass de souligner un .mcfunction contenant du bolt, qu'il lit comme du mcfunction vanilla. Voir Support éditeur.
Bonnes pratiques
À faire
Organisation des fichiers :
- Utilisez des structures de dossiers significatives (ex.,
machines/,items/,utils/) - Groupez les fonctions liées ensemble
- Séparez la logique en petites fonctions réutilisables
Qualité du code :
- Utilisez des f-strings pour les chemins dynamiques :
f"{ns}:folder/{item}" - Utilisez des chaînes multi-lignes (guillemets triples) pour le contenu des commandes
- Ajoutez des commentaires descriptifs dans les fonctions générées
- Utilisez
prepend=Truepour le code d'initialisation dans les fichiers qui doivent s'exécuter en premier
Performance :
- Utilisez des fonctions versionnées (second, second_5, minute) au lieu de tick quand possible
- Regroupez les opérations dans des fonctions uniques
- Utilisez des predicates au lieu de conditions execute complexes
- Évitez les appels de fonction inutiles en tick
Conventions StewBeet :
- Utilisez toujours
Mem.ctx.project_idpour le namespace - Utilisez
write_load_file()pour l'initialisation - Utilisez
write_versioned_function()pour les fonctions d'horloge - Appelez les helpers StewBeet au lieu de l'API beet directe quand disponible
À ne pas faire
Gestion des fichiers :
- Ne codez pas en dur les chaînes de namespace (utilisez
ctx.project_idou variablens) - Ne mélangez pas fichiers statiques et génération dynamique pour le même chemin
- N'écrasez pas les fichiers sauf si intentionnel
- Ne créez pas d'appels circulaires de fonctions (boucles infinies)
Qualité du code :
- N'utilisez pas
ctx.data["namespace"].functions["path"]quand des helpers StewBeet existent - N'oubliez pas de gérer les cas limites (vérifications vides, limites de score)
- N'écrivez pas de fonctions monolithiques (divisez en morceaux plus petits)
- Ne dupliquez pas le code à travers plusieurs fonctions
Quelle approche choisir, en bref
- Fichiers statiques pour la configuration, les recipes fixes et les petites fonctions qui ne changent pas.
- Helpers StewBeet pour l'essentiel de la logique du datapack, et tout ce qui est généré depuis vos définitions.
- API native beet seulement quand aucun helper ne couvre le fichier dont vous avez besoin.
- Bolt là où ce sont les commandes, et non les données, qui sont difficiles.
Quelle que soit l'approche, regroupez les fonctions en dossiers par fonctionnalité, et placez le travail périodique dans des fonctions d'horloge versionnées plutôt que dans le tick.
Glossaire
| Terme | Signification |
|---|---|
| Chargement de fichiers statiques | Chargement pré-plugin des fichiers déclarés dans beet.yml (data_pack.load et resource_pack.load). |
| Écriture via API native Beet | Création de fichiers via les objets ctx.data/ctx.assets dans le code plugin. |
| Écriture via helpers StewBeet | Fonctions utilitaires comme write_function, write_tag et helpers associés pour générer plus vite. |
| Bolt | La couche de script de mecha. Python et commandes partagent une syntaxe, compilée au build. |
| Module | Un fichier .bolt sous data/<namespace>/module/, importé par d'autres et n'écrivant des fonctions que là où il le demande. |
| Imbrication | Un execute ou un if finissant par deux-points, que mecha transforme en sa propre fonction et l'appel qui y mène. |
Prochaines étapes
- Référence des fonctions utilitaires: chaque fonction et ses arguments.
- Support éditeur: l'extension qui vérifie chaque bloc de cette page.
- Cookbook: des exemples complets et fonctionnels.
- Équations: construire l'arithmétique de scoreboard.
- Configurer le build: contrôler quand votre code s'exécute.