Cours Modding Forge 1.20.1

Appearance

L'utilisation d'un item sur une entité ​

Après avoir appris à interagir avec le décor inanimé et les blocs du monde dans le Cours, nous allons aujourd'hui nous intéresser à la matière organique.

Dans ce cours, nous allons découvrir comment détecter et modifier des entités vivantes spécifiques à l'aide de la méthode interactLivingEntity. Ce mécanisme est le fondement de nombreuses fonctionnalités emblématiques du jeu de base, telles que la tonte des moutons avec des cisailles, la traite des vaches avec un seau ou l'application d'une étiquette (Name Tag).

1. Le concept de interactLivingEntity ​

Contrairement au clic droit dans le vide (use) ou sur un bloc (useOn), la méthode interactLivingEntity est interceptée par Minecraft uniquement lorsque le joueur effectue un clic droit sur une entité qui hérite de la classe LivingEntity (les animaux, les monstres, les villageois ou même d'autres joueurs).

Cette méthode reçoit directement trois arguments clés transmis par le moteur de Forge:

  • ItemStack stack : L'exemplaire exact de l'item que le joueur tient en main lors de l'interaction.

  • Player player : L'instance du joueur qui a cliqué sur la créature.

  • LivingEntity target : La créature ciblée. C'est l'entité vivante sur laquelle le clic a été enregistré.

Le Polymorphisme et le Downcasting (Mise à niveau) ​

L'argument target est fourni sous la forme générique d'une LivingEntity. Cela signifie que par défaut, le code sait seulement qu'il s'agit d'un être vivant, mais il ignore si c'est un zombie, un poulet ou une vache. Pour agir de manière chirurgicale, nous devrons utiliser l'opérateur Java instanceof pour vérifier son identité exacte avant de lui appliquer un traitement particulier.

2. Analyse des paramètres de la méthode ​

Voici la signature exacte de la méthode que nous devons surcharger dans notre classe personnalisée d'item:

java
@Override
public InteractionResult interactLivingEntity(ItemStack stack, Player player, LivingEntity target, InteractionHand hand) {
    // Votre logique ici
    return InteractionResult.PASS;
}

[Note : Le paramètre hand a été complété par cohérence avec la signature standard de Forge et le code fourni plus bas dans le document].

Comme pour les cours précédents, la valeur de retour (InteractionResult) indique à Minecraft si l'interaction a été consommée avec succès (SUCCESS) ou si le jeu doit poursuivre ses vérifications internes (PASS).

3. Structure du Code : Exemple pratique ​

Imaginons un item personnalisé appelé SeringueExtractriceItem. Lorsque le joueur fait un clic droit sur une Vache (Cow), l'item extrait son code génétique : la vache subit un léger dégât, un effet sonore est joué, et le joueur reçoit un effet de potion de force. Si la cible n'est pas une vache, rien ne se passe.

java
package com.monmod.items;

import net.minecraft.sounds.SoundEvents;
import net.minecraft.sounds.SoundSource;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResult;
import net.minecraft.world.effect.MobEffectInstance;
import net.minecraft.world.effect.MobEffects;
import net.minecraft.world.entity.LivingEntity;
import net.minecraft.world.entity.animal.Cow;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;

public class SeringueExtractriceItem extends Item {
    public SeringueExtractriceItem(Properties properties) {
        super(properties);
    }

    @Override
    public InteractionResult interactLivingEntity(ItemStack stack, Player player, LivingEntity target, InteractionHand hand) {
        // 1. Vérification de la cible grâce au Pattern Matching (Java 17 / Forge 1.20.1)
        if (target instanceof Cow vache) {
            // 2. Isolation du côté Serveur pour la logique métier (Cours 9)
            if (!player.level().isClientSide) {
                // Faire subir 1 point de dégât (0.5 cœur) à la vache
                vache.hurt(vache.damageSources().generic(), 1.0F);
                
                // Ajouter un effet de Force au joueur pendant 10 secondes (200 ticks)
                player.addEffect(new MobEffectInstance(MobEffects.DAMAGE_BOOST, 200, 0));
                
                // Jouer un son au niveau de l'entité ciblée
                player.level().playSound(null, vache.getX(), vache.getY(), vache.getZ(),
                        SoundEvents.BOTTLE_FILL, SoundSource.PLAYERS, 1.0F, 1.0F);
                
                // Endommager l'item dans la main du joueur
                stack.hurtAndBreak(1, player, (p) -> p.broadcastBreakEvent(hand));
            }
            // On indique que l'action s'est bien déroulée
            return InteractionResult.SUCCESS;
        }
        
        // Si ce n'est pas une vache, on laisse le comportement par défaut de Minecraft
        return InteractionResult.PASS;
    }
}

Piège Fréquent : L'accès au Level depuis l'entité Dans cette méthode, l'objet Level n'est pas passé directement en paramètre contrairement à d'autres méthodes de la classe Item. Pour récupérer le monde et faire vos vérifications de sécurité, vous devez passer par le joueur ou par l'entité en faisant player.level() (ou target.level()). Attention à ne pas utiliser l'ancienne syntaxe obsolète player.level (sans parenthèses) qui provoquera des erreurs de compilation.

4. Distinction cruciale : Frapper vs Interagir ​

Il est indispensable de ne pas confondre deux actions du joueur envers les créatures:

Action du joueurMéthode appeléeObjectif principal
Clic Gauche (Attaque)hurtEnemy(...)Infliger des dégâts de combat, appliquer du recul (Knockback), gérer les armes.
Clic Droit (Interaction)interactLivingEntity(...)Soigner, tondre, traire, modifier l'état interne de la créature de manière pacifique ou utilitaire.

Exercice Pratique Obligatoire ​

Mettez en pratique vos connaissances avec l'exercice suivant:

Objectif : Le Bâton d'Apaisement des Monstres

  1. Créez un nouvel item nommé BatonApaisementItem.

  2. Implémentez la méthode interactLivingEntity pour intercepter les clics sur les Creepers (Creeper).

  3. Si la cible est un Creeper:

  • Côté serveur, vous devez désamorcer sa charge ou l'empêcher d'exploser en modifiant son état interne (Indice : explorez les méthodes de la classe Creeper, en particulier celle liée au gonflement ou à l'allumage par briquet comme creper.setSwellDir(-1) ou l'annulation de son ciblage).

  • Alternative simplifiée pour l'exercice : remplacez-le instantanément par une entité Chicken (Poulet) à la même position géographique !

  • Jouez le son d'un bloc de laine qui se pose pour illustrer l'effet de douceur.

  1. Consommez 1 unité de durabilité de l'objet à chaque utilisation réussie.