Créer un item simple

robin4002

L’item est de loin l’objet le plus présent dans Minecraft, on en compte 312 en 1.13 (et sans compter les ItemBlock, un item spécifique lié au bloc qu’il représente dont on a déjà parlé dans le tutoriel sur les blocs). Au niveau du code, les items sont des singletons (il n’y a qu’une seule instance par item) tout comme les blocs et sont identifiés à l’aide d’un nom de registre unique (à nouveau comme les blocs).

Sommaire du tutoriel

Pré-requis
La classe de déclaration des items
- Déclaration des items
- Enregistrement des items
La classe de l’item
Les ressources
Résultat
Licence et attribution

Pré-requis

La classe de déclaration des items

La première étape de ce tutoriel va être de créer une classe servant pour la déclaration et l’enregistrement de tous les items dans un package dédié aux items. On nommera celle-ci comme on le souhaite (ici ModTutorialItems, le nom du mod suivi de Items afin de repérer facilement que cette classe contient tous les items) et y on mettra l’annotation @Mod.EventBusSubscriber avec comme bus Mod.EventBusSubscriber.Bus.MOD.

package dev.mff.modtutorial.common.item;

import dev.mff.modtutorial.ModTutorial;
import net.minecraftforge.fml.common.Mod;

@Mod.EventBusSubscriber(modid = ModTutorial.MOD_ID, bus = Mod.EventBusSubscriber.Bus.MOD)
public class ModTutorialItems {

}

Déclaration des items

Tout comme dans le tutoriel sur les blocs, nous allons utiliser l’annotation @ObjectHolder qui va dynamiquement assigner une valeur à la constante. La syntaxe peut être déroutante comme on peut avoir l’impression que la variable est toujours null mais elle est plus avantageuse car elle permet à d’autres mods de mieux pouvoir interagir avec l’item.

On déclare donc notre item en créant une constante (une variable static et final) de type Item et en plaçant au-dessus l’annotation @ObjectHolder avec l’identifiant du mod, suivi d’un deux points puis par l’identifiant de l’item. Cet identifiant doit être unique pour chaque item et doit être entièrement en minuscule (on pourra mettre des tirets du bas pour séparer les différents mots, par exemple si on veut faire un item soupe de légume, on choisira comme nom vegetable_soup plutôt que vegetablesoup qui n’est pas très lisible …),

@ObjectHolder(ModTutorial.MOD_ID + ":item_tutorial")
public static final Item ITEM_TUTORIAL = null;

Enregistrement des items

L’événement RegistryEvent.Register<Item> permet d’enregistrer les items. Pour l’utiliser, il faut créer une méthode static (registerItems, par exemple) précédée par l’annotation @SubscribeEvent et avec cet événement en argument.

Dans cette méthode, on va appeler la fonction getRegistry().register de l’événement, en y créant une nouvelle instance de la classe Item tout en appelant la fonction setRegistryName afin de donner le nom de registre à notre item. Ce dernier doit être le même que celui donné lors de la déclaration de l’item.
Une fois tout ceci fait, on obtient ceci :

	@SubscribeEvent
     	public static void registerItems(RegistryEvent.Register<Item> event) {
     		event.getRegistry().register(new Item(new Item.Properties().group(ItemGroup.MISC)).setRegistryName("item_tutorial"));
     	}

Note

Pour enregistrer un autre item, il suffira de répéter la ligne event.getRegistry().register(new Item... en dessous de la ligne existante. Inutile de faire une seconde méthode avec l’événement RegistryEvent.Register<Item>

La classe item prend en argument dans son constructeur un Item.Properties. On crée donc également une nouvelle instance de cette classe et on peut appeler ses différentes méthodes. Ici, j’ai appelé la fonction group avec comme argumentItemGroup.MISC, ce qui ajoute l’item à la liste créative “divers”.
On peut appeler d’autres méthodes de la classe Item.Properties si nécessaire. Elles retournent toutes this, ce qui permet de les chaîner :

new Item.Properties().group(ItemGroup.MISC).maxStackSize(16).rarity(EnumRarity.UNCOMMON)

maxStackSize permet de changer le nombre maximum d’items en une pile et rarity permet de définir la rareté d’un item (changer la couleur de son nom quand on passe la souris dessus).

La classe de l’item

Cette partie est optionnelle

Plutôt que d’utiliser la classe Item de Minecraft, on peut aussi créer sa propre classe qui hérite de la classe Item. Pour un item simple, cela n’est pas du tout nécessaire. Par contre, cela sera nécessaire dans certains cas pour ajouter des actions à un item.

Si vous pensez en avoir besoin, créez une classe héritant de la classe net.minecraft.item.Item (nommez-la comme vous le voulez, du moment que son nom fait du sens. Ici, cela sera ItemTutorial) puis laissez-vous guider par votre IDE qui devrait vous proposer d’y ajouter un constructeur. Cela donne ceci :

package dev.mff.modtutorial.common.item;

import net.minecraft.item.Item;

public class ItemTutorial extends Item {

    public ItemTutorial(Properties properties) {
        super(properties);
    }
}

Afin que l’item créé précédemment utilise cette classe, il suffira de remplacer new Item(... par new ItemTutorial(... dans la fonction d’enregistrement des items.

À partir de là, on pourra facilement surcharger les méthodes de la classe Item et donc modifier le comportement de ces dernières pour notre item. Par exemple, en surchargeant la méthode addInformation, on peut ajouter du texte en dessous du nom de l’item :

    @Override
    public void addInformation(ItemStack stack, World worldIn, List<ITextComponent> tooltip, ITooltipFlag flag) {
        tooltip.add(new TextComponentString("Hello MFF!"));
    }

Mais ce n’est pas le sujet du tutoriel qui est là pour expliquer les bases des items, nous reviendrons donc plus en détails sur leur personnalisation dans un futur tutoriel.

Les ressources

Dans le dossier src/main/resources de votre projet, commencez par créer les packages suivants s’il n’existent pas déjà :

assets.modid.models.item
assets.modid.textures.item
assets.modid.lang
En remplaçant à chaque fois modid par l’identifiant de votre mod.
Vous pouvez aussi créer chaque dossier depuis l’explorateur de fichier (chaque point indique que la suite est un sous-dossier, par exemple modid est un dossier qui doit être créé dans le dossier assets).

Les modèles d’items

Dans le dossier models/item créez un fichier avec l’extension .json ayant le même nom de registre que votre item (donc item_tutorial.json dans le cas de ce tutoriel). Dans ce fichier, ajoutez le contenu suivant :

{
    "parent": "item/generated",
    "textures": {
        "layer0": "modid:item/nom_de_la_texture"
    }
}

En remplaçant modid par l’identifiant de votre mod et nom_de_la_texture par le nom voulu (on peut simplement y remettre le nom de registre de l’item).
La ligne parent indique que notre modèle hérite de item/generated qui est le modèle de base pour la plupart des items de Minecraft.

Note

Dans les dépendances externes de votre IDE, vous trouverez client-extra.jar dans lequel se trouvent toutes les ressources de Minecraft. Le package assets.minecraft.models.item contient les modèles des items de Minecraft, mais aussi les json parents, comme generated.json ou handheld.json (qui sera par exemple utilisé pour les outils, le rendu en main est plus grand qu’un item normal), etc. Il est possible de reprendre les propriétés de ces jsons (par exemple la propriété display, la copier dans notre modèle et changer les valeurs.

Les textures

On va ensuite ajouter le fichier de texture à l’item. Celle-ci doit avoir une taille étant un multiple de 2 (la taille habituelle pour Minecraft est de 16x16, mais on peut très bien utiliser une texture en 32x32 qui aura donc 4 fois plus de pixels). Le format doit être un PNG et la transparence est supportée.
Le fichier doit avoir le nom indiqué précédemment et être dans le dossier textures/item du dossier assets/modid.

La texture utilisée pour ce tutoriel est la suivante : (inutile de chercher un sens à cette texture)

Les fichiers de langues

Enfin, il ne reste plus qu’à donner un nom à l’item. Le dossier lang contient un fichier .json pour chacun des langages à supporter sous le format langage_variante.json. Donc fr_fr.json pour le français de la France, ou bien fr_ca.json pour le français canadien. Si un fichier de langage pour une variante n’existe pas, il prendra celui de la variante de base. S’il n’existe toujours pas, il passe sur l’anglais. Il faudra donc penser à aussi mettre un fichier en_us.json (pour l’anglais des états-unis, la langue de base de Minecraft).

Dans ce fichier, il faudra mettre une clé nommée item.modid.nom_de_registre_de_l_item et ayant pour valeur le nom traduit. Ce qui donne ceci :

{
  "item.modid.nom_de_registre_de_l_item": "Nom traduit dans la langue du fichier",
  "item.modtutorial.item_tutorial": "Tutorial item"
}

La première ligne est un exemple avec la syntaxe générale, la seconde ligne est la traduction anglaise pour l’item réalisé dans ce tutoriel.

Note

Dans le format json, des virgules séparent les différents éléments. Le dernier élément est le seul à ne pas en avoir comme il n’y a rien qui suit.

Résultat

Notre item est désormais fonctionnel !

Image de l'item tutoriel

Les différentes modifications du code sont retrouvables sur le commit Github suivant : https://github.com/MinecraftForgeFrance/mod-tutorial-1.13.2/commit/7efe69b32fd13b45511db0d5a77610ebbad44162

Licence et attribution

Ce tutoriel rédigé par robin4002 corrigé par @Superloup10 et @DiabolicaTrix et publié sur Minecraft Forge France est mis à disposition selon les termes de la licence Creative Commons Attribution - Pas d’Utilisation Commerciale - Partage dans les Mêmes Conditions 4.0 International

Sommaire des tutoriels