Tutoriel : votre premier datapack
Dans ce tutoriel, vous créez un projet StewBeet, vous le compilez, vous le chargez dans Minecraft, puis vous ajoutez un custom item et tout un palier de rubis avec un custom block fonctionnel. Comptez une vingtaine de minutes. Vous avez déjà un datapack ? Migrez-le plutôt.
Il vous faut trois choses :
- uv, le gestionnaire de paquets Python d'Astral. Il installe Python pour vous, c'est donc la seule chose de cette liste à installer à la main.
- Un éditeur de texte. VS Code avec le pack d'extensions Python et l'extension StewBeet vous donne la complétion dans vos commandes.
- Minecraft Java Edition, pour tester le résultat.
Vous n'installez pas Python vous-même. StewBeet demande 3.14, chaque template l'indique dans son pyproject.toml, et uv télécharge une version compatible à la première compilation.
Installer uv
Lancez la ligne correspondant à votre système :
Les autres façons de l'installer (winget, Homebrew, pipx, un binaire autonome) sont listées sur la page d'installation de uv.
Fermez et rouvrez votre terminal, puis vérifiez que uv est dans votre PATH :
Vous avez déjà Python 3.14 et préférez pip ?
pip install stewbeetfonctionne aussi, et chaqueuv run stewbeet ...ci-dessous devient simplementstewbeet .... Le reste du tutoriel ne change pas.
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# macOS et Linux
curl -LsSf https://astral.sh/uv/install.sh | shuv --versionCréer le projet
StewBeet fournit trois templates. Ce tutoriel utilise Basic : chaque plugin est configuré et commenté, et il n'y a aucun contenu d'exemple à supprimer.
| Template | Pour | Ce que vous obtenez |
|---|---|---|
| Minimal | Apprendre beet seul | Un seul plugin StewBeet, rien d'autre |
| Basic | La plupart des projets | Tous les plugins, commentés, sans contenu d'exemple |
| Extensive | Lire de vrais exemples | Toutes les fonctionnalités, avec items, minerais et manuel fonctionnels |
-
Créez un dossier pour le projet, par exemple
C:/MyDatapacks/AwesomeOres/. -
Ouvrez-le dans VS Code (clic droit sur le dossier puis "Ouvrir avec Code", ou Fichier, Ouvrir le dossier).
-
Ouvrez un terminal avec Terminal, Nouveau terminal. Il démarre dans le dossier du projet.
-
Lancez :
Terminaluvx stewbeet init basic
uvx télécharge StewBeet, l'exécute une fois et jette la copie, rien n'est donc installé globalement. Le dossier ressemble maintenant à ceci :
Le rôle de pyproject.toml
Il rend le projet autonome :
requires-python indique à uv quel interpréteur récupérer.
La section [tool.uv.sources] est temporaire : la version de smithed publiée sur PyPI mélange des modèles Pydantic V1 et V2, ce qui fait échouer la fusion Smithed Weld sur les Python récents. Supprimez cette section et la dépendance smithed une fois le problème corrigé en amont.
Pour utiliser une autre bibliothèque dans vos définitions (requests, pillow), lancez uv add requests. Elle atterrit dans ce fichier, dans votre .venv, et dans le fichier de lock que vos collaborateurs réutilisent.
AwesomeOres/
├── .beet_cache/ # Cache de compilation (généré)
├── build/ # Dossier de sortie (généré)
├── .venv/ # Environnement du projet (créé par uv à la première compilation)
├── assets/ # Vos textures et sons
├── src/ # Votre code source
│ ├── data/ # Fonctions et données du datapack
│ │ └── basic_template/ # Votre namespace (à renommer)
│ ├── definitions/ # Modules de définitions
│ │ ├── additions.py # Custom items et custom blocks
│ │ └── ores.py # Paliers de minerais et d'équipements
│ ├── link.py # Code exécuté après les définitions
│ └── setup_definitions.py # Point d'entrée des définitions
├── .gitignore
├── pyproject.toml # Dépendances Python (StewBeet et ce que vous ajoutez)
├── beet.yml # Fichier de configuration principal
└── definitions_debug.json # Ce que vos définitions ont produit, pour le débogage[project]
name = "template"
version = "0.0.1"
requires-python = ">=3.14"
dependencies = [
"stewbeet>=3.16.0",
]
[tool.uv]
package = falseNommer votre pack
Ouvrez beet.yml. Ces champs identifient le pack et sont réutilisés dans pack.mcmeta, le lore des items, le nom des archives et le manuel :
| Champ | Règle | Exemple |
|---|---|---|
id | Minuscules et underscores, sans espaces. Doit correspondre au dossier de src/data/ | awesome_ores |
name | Texte libre | "Awesome Ores & Gems" |
version | Versioning sémantique, majeur.mineur.patch | 1.0.0 |
Renommez src/data/basic_template/ en src/data/awesome_ores/ pour qu'il corresponde à id.
# Identifiant du projet - DOIT correspondre à votre namespace dans src/data/
id: "awesome_ores"
# Nom du projet pour l'affichage
name: "Awesome Ores"
# Votre nom (apparaît dans pack.mcmeta et le lore des items)
author: "VotreNom"
# Version utilisant le versioning sémantique
version: "1.0.0"
# Brève description
description: "Mon premier datapack StewBeet avec des custom ores !"Compiler
Dans le terminal, lancez uv run stewbeet (ou uv run stewbeet build, qui revient au même).
La première exécution fait la mise en place : uv lit pyproject.toml, télécharge Python 3.14 s'il manque, crée .venv/ et installe StewBeet. Comptez une minute. Les exécutions suivantes compilent immédiatement.
La sortie ressemble à ceci. Les avertissements sont normaux sur un projet vide :
build/ contient maintenant :
| Chemin | Ce que c'est |
|---|---|
datapack/ | Le datapack généré, décompressé |
resource_pack/ | Le resource pack généré, décompressé |
AwesomeOres_datapack.zip | Le datapack, prêt à déposer dans un monde |
AwesomeOres_resource_pack.zip | Le resource pack, prêt à activer |
sha1_hashes.json | Les hashes des archives, pour les administrateurs de serveur |
Building project...
[WARNING 19:05:57] Error during generate_custom_records(): (FileNotFoundError) [WinError 3] The system cannot find the path specified: 'assets/records'
[DEBUG 19:05:58] Mem.definitions exported to 'definitions_debug.json'
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.resource_pack.sounds': 0.070ms (69900ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.resource_pack.item_models': 0.246ms (245700ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.resource_pack.check_power_of_2': 0.250ms (249700ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.custom_recipes': 0.021ms (20700ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.custom_paintings': 0.007ms (7400ns)
[WARNING 19:05:58] Database is empty, skipping manual generation.
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.ingame_manual': 0.075ms (74600ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.datapack.loading': 0.150ms (150300ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.datapack.custom_blocks': 0.108ms (108200ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.datapack.loot_tables': 0.187ms (187300ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.datapack.sorters': 0.031ms (31300ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.compatibilities.simpledrawer': 0.003ms (2700ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.compatibilities.neo_enchant': 0.003ms (2800ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.finalyze.custom_blocks_ticking': 0.045ms (45100ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.finalyze.basic_datapack_structure': 0.062ms (61600ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.finalyze.dependencies': 0.875ms (874900ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.finalyze.last_final': 0.154ms (154500ns)
Generating lang file: 100%|████████████████████████████████████████████████| 21/21 [4481.78it/s, 00:00<00:00]
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.auto.lang_file': 73.613ms (73613100ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.auto.headers': 0.561ms (561000ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.check_unused_textures': 0.125ms (124800ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.archive': 23.592ms (23592200ns)
[WARNING 19:05:58] No datapacks or libs to merge for build\AwesomeOres_datapack_with_libs.zip. Skipping weld.
[WARNING 19:05:58] No resource packs or libs to merge for build\AwesomeOres_resource_pack_with_libs.zip. Skipping weld.
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.merge_smithed_weld': 0.593ms (593100ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.copy_to_destination': 0.007ms (7300ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.compute_sha1': 25.546ms (25546400ns)
[DEBUG 19:05:58] Total execution time: 0.56934s
Done!Le charger dans Minecraft
Le plus rapide est de laisser chaque compilation copier les packs dans votre jeu. Ajoutez ceci à beet.yml, avec vos propres chemins :
Désormais, uv run stewbeet copie les deux packs après chaque compilation.
Pour les copier à la main :
- Copiez
build/AwesomeOres_datapack.zipdans le dossier datapacks du monde :- Windows :
%appdata%\.minecraft\saves\[NomDuMonde]\datapacks\ - macOS :
~/Library/Application Support/minecraft/saves/[NomDuMonde]/datapacks/
- Windows :
- Copiez
build/AwesomeOres_resource_pack.zipdans le dossier des resource packs :- Windows :
%appdata%\.minecraft\resourcepacks\ - macOS :
~/Library/Application Support/minecraft/resourcepacks/
- Windows :
Puis, en jeu :
- Lancez
/reload. - Activez le resource pack dans Options, Packs de ressources.
- Si vous avez gardé la fonction d'exemple dans
src/data/awesome_ores/function/, lancez-la avec/function awesome_ores:path/to/a/random/function/i/guess.
meta:
stewbeet:
build_copy_destinations:
datapack: ["C:/Users/VotreNom/AppData/Roaming/.minecraft/saves/NomDuMonde/datapacks"]
resource_pack: ["C:/Users/VotreNom/AppData/Roaming/.minecraft/resourcepacks"]Ajouter un custom item
- Créez
assets/textures/et placez-y un PNG 16x16, par exempleruby.png, pour obtenirassets/textures/ruby.png. - Ouvrez
src/definitions/additions.pyet déclarez l'item. L'idcorrespond au nom de la texture, c'est comme ça que StewBeet la trouve :
- Lancez
uv run stewbeet. La première compilation qui dessine les item models prend un peu plus de temps. - En jeu, lancez
/reload, puis/loot give @s loot awesome_ores:i/rubyou/function awesome_ores:_give_all.
À partir de cette seule déclaration, StewBeet a écrit l'item model et sa référence, ajouté la texture au resource pack, construit les components de l'item et ajouté une page au manuel.
# Imports
from stewbeet import *
# Point d'entrée principal
def main():
# Ajouter des items aux définitions
Mem.definitions["ruby"] = Item(
id="ruby",
components={
"lore": [{"text":"Une précieuse pierre précieuse rouge","color":"gray","italic":False}]
}
)
# Voir extensive_template/src/definitions/additions.py pour des exemples
passAjouter tout un palier de minerai
Placez ces textures dans assets/textures/ :
| Fichier | Utilisé pour |
|---|---|
ruby_ore.png | Le bloc de minerai |
ruby_sword.png | L'épée |
ruby_chestplate.png | L'item plastron |
ruby_layer_1.png | L'armure portée, couche supérieure (c'est ainsi que Minecraft dessine les custom armors) |
ruby_layer_2.png | L'armure portée, couche inférieure |
Ouvrez src/definitions/ores.py et décrivez le matériau. Tout ce que StewBeet trouve dans le dossier des textures avec le préfixe ruby est enregistré à partir de cette entrée :
Compilez, /reload, puis lancez /loot give @s loot awesome_ores:i/ruby_ore et posez le bloc. C'est un custom block complet : StewBeet a écrit son model, sa logique de pose et de cassage, ses drops et ses conditions de minage, son comportement avec Fortune et Silk Touch, et l'a branché sur la bibliothèque Smithed Custom Blocks.
# Imports
from stewbeet import *
# Point d'entrée principal
def main():
# Configuration pour tout générer à propos d'un matériau
ORES_CONFIGS: dict[str, EquipmentsConfig|None] = {
"ruby": EquipmentsConfig(
# Ce rubis est équivalent au diamant,
equivalent_to = DefaultOre.DIAMOND,
# Mais, a plus de durabilité (1.2 fois plus)
pickaxe_durability = 1.2 * VanillaEquipments.PICKAXE.value[DefaultOre.DIAMOND]["durability"],
# Et, fait 1 dégât de plus par coup (main), et a 0.5 armure de plus, et mine 20% plus vite (pioche)
attributes = {"attack_damage": 1, "armor": 0.5, "mining_efficiency": 0.2}
),
}
# Générer les minerais dans les définitions (ajoute tout ce qui est trouvé (dans le dossier textures) lié aux matériaux donnés, aux définitions)
generate_everything_about_these_materials(ORES_CONFIGS)
returnOuvrir le manuel en jeu
Le manuel utilise le système de dialogues de Minecraft, qui ne prend en compte les nouveaux dialogues qu'au redémarrage du serveur : quittez et rejoignez le monde d'abord. Appuyez ensuite sur G (le raccourci d'action rapide), ou lancez /loot give @s loot awesome_ores:i/manual si vous êtes parti du template Extensive.
Le manuel liste vos items avec leurs recipes, dessinées à partir des définitions que vous venez d'écrire.
Ce que contient beet.yml
Vous avez parcouru toute la boucle. Deux autres parties de beet.yml sont utiles à connaître avant d'aller plus loin.
Les dossiers que StewBeet lit, et où il copie le résultat :
meta:
stewbeet:
# Répertoire contenant toutes les textures du projet
textures_folder: "assets/textures"
# Répertoire contenant tous les custom sounds
sounds_folder: "assets/sounds"
# Répertoire contenant tous les jukebox records
records_folder: "assets/records"
# Répertoire contenant les bibliothèques qui seront copiées vers la destination de build, et fusionnées avec Smithed Weld si activé.
libs_folder: "libs"
# Optionnel : motifs glob (relatifs à libs_folder) des archives de bibliothèque à exclure du build
libs_exclude_patterns: []
# Liste optionnelle de chemins de destination où les fichiers générés seront copiés
build_copy_destinations:
datapack: ["C:/Users/VotreNom/AppData/Roaming/.minecraft/saves/NomDuMonde/datapacks"]
resource_pack: ["C:/Users/VotreNom/AppData/Roaming/.minecraft/resourcepacks"]Le pipeline, qui liste chaque étape de la compilation dans l'ordre. Retirez une ligne pour désactiver une fonctionnalité :
# Plugins à exécuter en premier
require:
- "stewbeet" # Équivalent à "stewbeet.plugins.initialize"
- "bolt" # Initialiser bolt
# Une liste de chaînes représentant des "plugins".
# - Ces plugins s'exécuteront après le chargement du pack (tous les contenus src/data et src/assets sont chargés en premier)
pipeline:
- "src.setup_definitions" # Votre code utilisateur pour définir items/blocs
- "stewbeet.plugins.resource_pack.sounds" # Générer les fichiers sons
- "stewbeet.plugins.resource_pack.item_models" # Générer les item models
- "stewbeet.plugins.resource_pack.check_power_of_2" # Vérifier les dimensions des textures
- "stewbeet.plugins.custom_recipes" # Générer les custom recipes
- "stewbeet.plugins.custom_paintings" # Générer les custom paintings
- "stewbeet.plugins.ingame_manual" # Générer le manuel en jeu
- "stewbeet.plugins.datapack.loading" # Configurer les fonctions load/tick
- "stewbeet.plugins.datapack.custom_blocks" # Configurer les mécaniques de blocs
- "stewbeet.plugins.datapack.loot_tables" # Générer les loot tables
- "stewbeet.plugins.datapack.sorters" # Configurer les item sorters
- "stewbeet.plugins.compatibilities.simpledrawer" # Compatibilité SimpleDrawer
- "stewbeet.plugins.compatibilities.neo_enchant" # Compatibilité NeoEnchant
- "src.link" # Code utilisateur pour lier les fonctionnalités
- "mecha" # Compilation Bolt/Mecha
- "stewbeet.plugins.finalyze.custom_blocks_ticking" # Finaliser le ticking des blocs
- "stewbeet.plugins.finalyze.basic_datapack_structure" # Finalisation de la structure
- "stewbeet.plugins.finalyze.dependencies" # Vérification des dépendances
- "stewbeet.plugins.finalyze.last_final" # Nettoyage final
- "stewbeet.plugins.auto.lang_file" # Générer les fichiers de langue
- "stewbeet.plugins.auto.headers" # Générer les en-têtes de fonctions
- "stewbeet.plugins.check_unused_textures" # Trouver les textures inutilisées
- "stewbeet.plugins.archive" # Créer les fichiers zip
- "stewbeet.plugins.merge_smithed_weld" # Fusionner avec Smithed Weld
- "stewbeet.plugins.copy_to_destination" # Copier vers les chemins configurés
- "stewbeet.plugins.compute_sha1" # Calculer les hashes de fichiersChaque option est décrite dans Configurer le build.
Étapes suivantes
- Définir des items et des blocs : chaque champ qu'acceptent un
Itemou unBlock, recipes comprises. - Écrire des fonctions et des fichiers : ajouter vos propres commandes au pack.
- Utiliser des bibliothèques de datapack : Smithed, Bookshelf et les vérifications de version que StewBeet écrit pour vous.
- Le template Extensive est un projet complet à lire.
Bloqué ? Demandez sur Discord ou ouvrez une issue GitHub.