Ta première particule

Les particules sont les petites images plates que tu vois partout dans Minecraft : la fumée d'un feu de camp, les cœurs au-dessus d'un animal content, les bulles sous l'eau. Dans ce guide, tu vas créer la tienne : une étincelle de rubis. C'est une gerbe de petits éclats rouges qui montent, scintillent et s'effacent.

Tu vas apprendre ce qu'on met dans un fichier de particule, comment dessiner sa texture, comment la faire évoluer dans le temps et comment l'afficher en jeu avec une commande, une animation ou un script.

Les fichiers

RP/
  particles/
    ruby_sparkle.json
    ruby_dust.json
  textures/
    particle/
      ruby_sparkle.png

Chaque fichier .json du dossier particles est chargé par le jeu. Le nom du fichier n'a pas d'importance, mais lui donner le même nom que la particule permet de s'y retrouver facilement.

Émetteurs et particules

Avant d'écrire quoi que ce soit, il est utile de connaître les deux parties de chaque effet :

• L'émetteur est un générateur invisible. Il décide combien de particules apparaissent, où elles démarrent et combien de temps il continue à en créer.
• Les particules sont les petites images. Chacune décide comment elle bouge, à quoi elle ressemble et quand elle disparaît.

C'est pour ça que les composants de particules se rangent en deux familles. Les noms qui commencent par minecraft:emitter_ règlent le générateur. Les noms qui commencent par minecraft:particle_ règlent chaque image. Tu peux les écrire dans n'importe quel ordre.

Étape 1 : la texture

Dessine un PNG de 8x8 et enregistre-le sous RP/textures/particle/ruby_sparkle.png. Une petite étoile à quatre branches fait très bien l'affaire.

Dessine-la en blanc et gris clair, pas en rouge. Plus tard, tu vas la teinter avec une couleur, et une teinte multiplie les pixels. Le blanc devient la couleur de ton choix, alors qu'une image rouge teintée en bleu deviendrait presque noire.

Laisse le fond complètement transparent. Les particules sont toujours des carrés plats, ce sont donc les pixels transparents qui leur donnent leur forme.

Étape 2 : la description

Crée le fichier de particule et commence par son nom et son apparence :

{
  "format_version": "1.10.0",
  "particle_effect": {
    "description": {
      "identifier": "wiki:ruby_sparkle",
      "basic_render_parameters": {
        "material": "particles_alpha",
        "texture": "textures/particle/ruby_sparkle"
      }
    },
    "components": {}
  }
}

• identifier est le nom que tu utilises pour jouer la particule. Donne-lui toujours ton propre espace de noms (ici wiki:), pour qu'elle n'entre jamais en conflit avec le jeu vanilla ou un autre add-on.
• texture est le chemin vers ton PNG depuis la racine du pack de ressources, sans .png.
• material décide comment les pixels transparents sont dessinés :

Notre étincelle doit briller, donc passe le matériau à particles_add une fois que tout marche. Commence avec particles_alpha pendant les tests, car c'est le plus facile à voir.

Étape 3 : l'émetteur

Remplis maintenant components. D'abord le générateur. On veut une seule gerbe rapide de 12 étincelles, réparties autour d'une petite boule :

"minecraft:emitter_lifetime_once": {
  "active_time": 0.5
},
"minecraft:emitter_rate_instant": {
  "num_particles": 12
},
"minecraft:emitter_shape_sphere": {
  "radius": 0.4,
  "direction": "outwards"
},

• emitter_lifetime_once fait tourner l'émetteur une seule fois, puis le supprime.
• emitter_rate_instant crée les 12 particules au même instant.
• emitter_shape_sphere les place dans une boule de 0,4 bloc de rayon, chacune orientée vers l'extérieur.

Chaque émetteur a besoin d'un composant de durée de vie et d'un composant de débit. Sans eux, rien n'apparaît. La forme est facultative : sans elle, chaque particule démarre pile au centre.

Étape 4 : les particules

Ensuite, indique à chaque étincelle comment bouger et à quoi ressembler. Ajoute ceci après les composants de l'émetteur :

"minecraft:particle_lifetime_expression": {
  "max_lifetime": "math.random(0.6, 1.2)"
},
"minecraft:particle_initial_speed": 1.5,
"minecraft:particle_motion_dynamic": {
  "linear_acceleration": [0, 1.2, 0],
  "linear_drag_coefficient": 3
},
"minecraft:particle_appearance_billboard": {
  "size": [0.12, 0.12],
  "facing_camera_mode": "lookat_xyz",
  "uv": {
    "texture_width": 8,
    "texture_height": 8,
    "uv": [0, 0],
    "uv_size": [8, 8]
  }
},
"minecraft:particle_appearance_tinting": {
  "color": [1, 0.15, 0.3, 1]
}

Voici ce que fait chacun :

• Durée de vie. Chaque étincelle vit entre 0,6 et 1,2 seconde. math.random tire un nouveau nombre pour chaque particule, pour qu'elles ne disparaissent pas toutes en même temps. C'est du Molang, le petit langage de calcul utilisé par Bedrock.
• Vitesse. Elles partent à 1,5 bloc par seconde, dans la direction donnée par la sphère.
• Mouvement. linear_acceleration les pousse un peu vers le haut chaque seconde, pour qu'elles flottent comme des braises. linear_drag_coefficient est la résistance de l'air : elle ralentit vite la première poussée.
• Billboard. Chaque particule est un carré plat. size est la moitié de sa largeur et de sa hauteur en blocs, donc 0.12 donne un carré d'environ un quart de bloc de large. lookat_xyz le garde tourné vers le joueur.
• UV. Ça choisit quelle partie de la texture afficher. Notre texture est une seule image de 8x8, on l'utilise donc en entier : on part de 0, 0 et on prend 8, 8.
• Teinte. Rouge, vert, bleu et alpha, chacun de 0 à 1. [1, 0.15, 0.3, 1] est un rouge rubis. Tu peux aussi écrire "#FF2650".

Enregistre, charge le monde et tape :

/particle wiki:ruby_sparkle ~ ~1 ~

Tu devrais voir une petite bouffée rouge monter devant toi. Si tu ne vois rien, regarde le tableau à la fin de cette page.

Étape 5 : la faire scintiller avec une courbe

Pour l'instant, chaque étincelle garde la même taille jusqu'à disparaître d'un coup. Une courbe règle ça. C'est une valeur qui suit une forme que tu dessines avec quelques nombres.

Ajoute un bloc curves à côté de description et components :

"curves": {
  "variable.ruby_size": {
    "type": "linear",
    "input": "variable.particle_age / variable.particle_lifetime",
    "nodes": [0.2, 1, 0.6, 0]
  }
},

• Le nom doit commencer par variable.. Le jeu calcule la courbe pour chaque particule, à chaque image, et stocke le résultat dans cette variable.
• input indique où on en est sur la courbe. L'âge divisé par la durée de vie va de 0 (tout juste née) à 1 (sur le point de disparaître).
• nodes sont les valeurs le long du chemin, réparties régulièrement du début à la fin. Notre étincelle commence petite (0.2), grandit jusqu'à sa taille maximale (1), rétrécit (0.6) et finit à rien (0).
• type indique comment la courbe passe d'un nœud à l'autre. linear trace des lignes droites. catmull_rom et bezier font des courbes douces, et bezier_chain te laisse régler toi-même chaque point et chaque pente.

Maintenant, utilise la variable dans la taille du billboard :

"size": ["0.12 * variable.ruby_size", "0.12 * variable.ruby_size"],

Pour un fondu, la teinte peut aussi changer de couleur pendant la vie de la particule. Un gradient liste des couleurs, et interpolant choisit où on se trouve entre elles :

"minecraft:particle_appearance_tinting": {
  "color": {
    "gradient": ["#FFFF8FA8", "#FFFF2650", "#00A0002A"],
    "interpolant": "variable.particle_age / variable.particle_lifetime"
  }
}

Chaque couleur est écrite ici sous la forme #AARRGGBB, donc les deux premiers caractères sont l'alpha. L'étincelle commence rose pâle, devient rouge rubis et finit sombre et invisible. Avec particles_add, les couleurs sombres se fondent dans le néant, ce qui rend super bien pour les effets lumineux.

Étape 6 : ajouter un pop avec un événement

Les événements déclenchent des choses à un moment précis. Laissons une minuscule bouffée de poussière là où chaque étincelle disparaît.

D'abord, crée la poussière. C'est un deuxième effet, plus petit :

{
  "format_version": "1.10.0",
  "particle_effect": {
    "description": {
      "identifier": "wiki:ruby_dust",
      "basic_render_parameters": {
        "material": "particles_add",
        "texture": "textures/particle/ruby_sparkle"
      }
    },
    "components": {
      "minecraft:emitter_lifetime_once": { "active_time": 0.2 },
      "minecraft:emitter_rate_instant": { "num_particles": 3 },
      "minecraft:emitter_shape_point": {},
      "minecraft:particle_initial_speed": 0.4,
      "minecraft:particle_lifetime_expression": { "max_lifetime": 0.3 },
      "minecraft:particle_appearance_billboard": {
        "size": [0.04, 0.04],
        "facing_camera_mode": "lookat_xyz",
        "uv": {
          "texture_width": 8,
          "texture_height": 8,
          "uv": [0, 0],
          "uv_size": [8, 8]
        }
      },
      "minecraft:particle_appearance_tinting": { "color": "#FF7A0F2E" }
    }
  }
}

Puis, de retour dans ruby_sparkle.json, nomme un événement et indique ce qu'il fait :

"events": {
  "pop": {
    "particle_effect": {
      "effect": "wiki:ruby_dust",
      "type": "emitter"
    }
  }
},

Enfin, déclenche l'événement quand chaque étincelle arrive au bout de sa vie :

"minecraft:particle_lifetime_events": {
  "expiration_event": "pop"
}

Un événement peut faire plus que créer des particules :

Le fichier terminé

Voici l'étincelle complète, avec le matériau lumineux activé :

{
  "format_version": "1.10.0",
  "particle_effect": {
    "description": {
      "identifier": "wiki:ruby_sparkle",
      "basic_render_parameters": {
        "material": "particles_add",
        "texture": "textures/particle/ruby_sparkle"
      }
    },
    "curves": {
      "variable.ruby_size": {
        "type": "linear",
        "input": "variable.particle_age / variable.particle_lifetime",
        "nodes": [0.2, 1, 0.6, 0]
      }
    },
    "events": {
      "pop": {
        "particle_effect": {
          "effect": "wiki:ruby_dust",
          "type": "emitter"
        }
      }
    },
    "components": {
      "minecraft:emitter_lifetime_once": {
        "active_time": 0.5
      },
      "minecraft:emitter_rate_instant": {
        "num_particles": 12
      },
      "minecraft:emitter_shape_sphere": {
        "radius": 0.4,
        "direction": "outwards"
      },
      "minecraft:particle_lifetime_expression": {
        "max_lifetime": "math.random(0.6, 1.2)"
      },
      "minecraft:particle_lifetime_events": {
        "expiration_event": "pop"
      },
      "minecraft:particle_initial_speed": 1.5,
      "minecraft:particle_initial_spin": {
        "rotation": "math.random(0, 360)",
        "rotation_rate": 90
      },
      "minecraft:particle_motion_dynamic": {
        "linear_acceleration": [0, 1.2, 0],
        "linear_drag_coefficient": 3
      },
      "minecraft:particle_appearance_billboard": {
        "size": ["0.12 * variable.ruby_size", "0.12 * variable.ruby_size"],
        "facing_camera_mode": "lookat_xyz",
        "uv": {
          "texture_width": 8,
          "texture_height": 8,
          "uv": [0, 0],
          "uv_size": [8, 8]
        }
      },
      "minecraft:particle_appearance_tinting": {
        "color": {
          "gradient": ["#FFFF8FA8", "#FFFF2650", "#00A0002A"],
          "interpolant": "variable.particle_age / variable.particle_lifetime"
        }
      }
    }
  }
}

On a aussi glissé particle_initial_spin : chaque étincelle démarre avec un angle au hasard et tourne lentement, pour qu'aucune ne ressemble à une autre.

Jouer la particule

Avec une commande

/particle joue un effet à une position. Il faut que les commandes de triche soient activées.

/particle wiki:ruby_sparkle ~ ~1 ~

Tu peux aussi la mettre dans une fonction ou un bloc de commande. Utilise execute pour la jouer sur quelqu'un : /execute as @a at @s run particle wiki:ruby_sparkle ~ ~2 ~ affiche une étincelle au-dessus de la tête de chaque joueur.

Depuis l'animation d'une créature

Une créature peut jouer des particules depuis ses animations. Ça se passe dans le fichier d'entité client du pack de ressources, alors consulte d'abord Ta première créature personnalisée si tu n'en as pas encore créé.

1. Donne un nom court à l'effet dans la description de l'entité client :

"particle_effects": {
  "sparkle": "wiki:ruby_sparkle"
}

2. Joue-le depuis une animation à un moment donné. locator est facultatif : c'est un point nommé sur le modèle, et l'effet le suit quand la créature bouge. Sans locator, l'effet se joue aux pieds de la créature.

"particle_effects": {
  "0.5": {
    "effect": "sparkle",
    "locator": "head"
  }
}

3. Ou joue-le depuis un état de contrôleur d'animation. Il démarre quand la créature entre dans l'état :

"particle_effects": [
  { "effect": "sparkle" }
]

Chacun d'eux peut aussi avoir un pre_effect_script : un peu de Molang qui s'exécute juste avant le départ de l'effet. Sers-t'en pour envoyer des valeurs au fichier de particule, comme une couleur qui dépend de la créature.

Depuis un script

Les scripts peuvent jouer des particules n'importe où, n'importe quand. Ton pack de comportements a besoin d'un module de script dans son manifeste : Préparer le projet montre comment faire.

import { world } from "@minecraft/server";

world.afterEvents.itemUse.subscribe(({ source, itemStack }) => {
  if (itemStack.typeId !== "wiki:ruby_wand") return;

  const { x, y, z } = source.location;
  source.dimension.spawnParticle("wiki:ruby_sparkle", { x, y: y + 1.5, z });
});

Chaque fois qu'un joueur utilise un objet wiki:ruby_wand, une étincelle éclate au-dessus de lui. dimension.spawnParticle montre l'effet à tous les joueurs proches. player.spawnParticle marche de la même façon, mais seul ce joueur le voit.

Les scripts peuvent aussi envoyer des valeurs à la particule avec un MolangVariableMap. Ça permet à un seul fichier de particule de créer des étincelles de n'importe quelle couleur :

import { MolangVariableMap } from "@minecraft/server";

// Inside the same itemUse handler as above:
const vars = new MolangVariableMap();
vars.setColorRGB("variable.tint", { red: 0.2, green: 0.6, blue: 1 });
source.dimension.spawnParticle("wiki:ruby_sparkle", { x, y: y + 1.5, z }, vars);

Dans le fichier de particule, lis les trois parties de la couleur avec variable.tint.r, variable.tint.g et variable.tint.b :

"minecraft:particle_appearance_tinting": {
  "color": ["variable.tint.r", "variable.tint.g", "variable.tint.b", 1]
}

Variables Molang pratiques

Le jeu remplit ces valeurs pour toi. Utilise-les dans n'importe quel champ Molang.

variable.particle_random_1 est parfait pour varier les choses. Par exemple, "0.1 + variable.particle_random_1 * 0.05" donne à chaque étincelle une taille légèrement différente.

Quand quelque chose ne marche pas

Tu trouveras plus d'aide dans Dépannage. Envie d'aller plus loin ? Tous les réglages des émetteurs sont sur Composants d'émetteur, et tous les réglages des particules sur Composants de particule.