ParticleEffectResourceDefinition
ParticleEffectResourceDefinition manages particle effect files in resource packs (RP/particles/*.json).
Class Signature
class ParticleEffectResourceDefinition {
// Properties
readonly id?: string;
readonly isLoaded: boolean;
readonly file?: IFile;
readonly data?: IParticleEffectWrapper;
readonly description?: IParticleEffectDescription;
readonly formatVersion?: string;
// Texture methods
getCanonicalizedTexturesList(): string[] | undefined;
// Loading and persistence
static async ensureOnFile(file: IFile, handler?): Promise<ParticleEffectResourceDefinition>;
async load(): Promise<void>;
persist(): boolean;
// Utilities
getFormatVersion(): number[] | undefined;
async getFormatVersionIsCurrent(): Promise<boolean>;
async addChildItems(project: Project, item: ProjectItem): Promise<void>;
async deleteLinkToChild(rel: IProjectItemRelationship): Promise<void>;
getPackRootFolder(): IFolder | undefined;
}
Loading Particle Definitions
import { ParticleEffectResourceDefinition } from 'minecraft-creator-tools';
// Load from file
const particleDef = await ParticleEffectResourceDefinition.ensureOnFile(file);
console.log('Particle ID:', particleDef.id);
console.log('Format version:', particleDef.formatVersion);
// Access particle description
if (particleDef.description) {
console.log('Identifier:', particleDef.description.identifier);
if (particleDef.description.basic_render_parameters) {
console.log('Material:', particleDef.description.basic_render_parameters.material);
console.log('Texture:', particleDef.description.basic_render_parameters.texture);
}
}
Working with Textures
// Get texture paths
const textures = particleDef.getCanonicalizedTexturesList();
if (textures) {
for (const texPath of textures) {
console.log('Texture:', texPath);
}
}
// Set texture
if (particleDef.description?.basic_render_parameters) {
particleDef.description.basic_render_parameters.texture =
'textures/particles/my_particle';
particleDef.persist();
}
Particle JSON Structure
{
"format_version": "1.10.0",
"particle_effect": {
"description": {
"identifier": "custom:magic_sparkle",
"basic_render_parameters": {
"material": "particles_alpha",
"texture": "textures/particles/sparkle"
}
},
"components": {
"minecraft:emitter_rate_instant": {
"num_particles": 10
},
"minecraft:emitter_lifetime_once": {
"active_time": 1
},
"minecraft:emitter_shape_sphere": {
"radius": 0.5,
"surface_only": false,
"direction": "outwards"
},
"minecraft:particle_lifetime_expression": {
"max_lifetime": "Math.random(0.5, 1.5)"
},
"minecraft:particle_initial_speed": 2.0,
"minecraft:particle_motion_dynamic": {
"linear_acceleration": [0, -9.8, 0]
},
"minecraft:particle_appearance_billboard": {
"size": [0.1, 0.1],
"facing_camera_mode": "lookat_xyz",
"uv": {
"texture_width": 128,
"texture_height": 128,
"uv": [0, 0],
"uv_size": [8, 8]
}
},
"minecraft:particle_appearance_tinting": {
"color": [1, 1, 1, 1]
}
}
}
}
Common Particle Components
Emitter Components
{
"components": {
// Emit particles instantly
"minecraft:emitter_rate_instant": {
"num_particles": 20
},
// Emit particles over time
"minecraft:emitter_rate_steady": {
"spawn_rate": 10,
"max_particles": 100
},
// Emit once and stop
"minecraft:emitter_lifetime_once": {
"active_time": 2.0
},
// Emit continuously
"minecraft:emitter_lifetime_looping": {
"active_time": 5.0,
"sleep_time": 1.0
},
// Emit from sphere
"minecraft:emitter_shape_sphere": {
"radius": 1.0,
"surface_only": true,
"direction": "outwards"
},
// Emit from point
"minecraft:emitter_shape_point": {
"offset": [0, 1, 0],
"direction": [0, 1, 0]
},
// Emit from disc
"minecraft:emitter_shape_disc": {
"radius": 2.0,
"plane_normal": [0, 1, 0],
"surface_only": false
},
// Emit from box
"minecraft:emitter_shape_box": {
"half_dimensions": [1, 1, 1],
"surface_only": false,
"direction": "outwards"
}
}
}
Particle Lifetime and Motion
{
"components": {
// Particle lifetime
"minecraft:particle_lifetime_expression": {
"max_lifetime": "Math.random(1.0, 3.0)",
"expiration_expression": "variable.particle_age >= variable.particle_lifetime"
},
// Initial speed
"minecraft:particle_initial_speed": "Math.random(1.0, 3.0)",
// Or speed range
"minecraft:particle_initial_speed": [1.0, 3.0],
// Dynamic motion (gravity, drag)
"minecraft:particle_motion_dynamic": {
"linear_acceleration": [0, -9.8, 0],
"linear_drag_coefficient": 0.5
},
// Parametric motion (follows curve)
"minecraft:particle_motion_parametric": {
"relative_position": [
"Math.cos(variable.particle_age * 360)",
"variable.particle_age",
"Math.sin(variable.particle_age * 360)"
]
},
// Collision with world
"minecraft:particle_motion_collision": {
"enabled": true,
"collision_drag": 0.8,
"coefficient_of_restitution": 0.5,
"collision_radius": 0.1,
"expire_on_contact": false
}
}
}
Appearance Components
{
"components": {
// Billboard (faces camera)
"minecraft:particle_appearance_billboard": {
"size": ["0.1 + variable.particle_age * 0.1", 0.1],
"facing_camera_mode": "lookat_xyz",
"uv": {
"texture_width": 128,
"texture_height": 128,
"uv": [0, 0],
"uv_size": [16, 16]
}
},
// Animated texture
"minecraft:particle_appearance_billboard": {
"size": [0.2, 0.2],
"facing_camera_mode": "lookat_xyz",
"uv": {
"texture_width": 128,
"texture_height": 128,
"uv": [0, 0],
"uv_size": [16, 16],
"flipbook": {
"base_UV": [0, 0],
"size_UV": [16, 16],
"step_UV": [16, 0],
"frames_per_second": 10,
"max_frame": 8,
"stretch_to_lifetime": false,
"loop": true
}
}
},
// Color tinting
"minecraft:particle_appearance_tinting": {
"color": {
"interpolant": "variable.particle_age / variable.particle_lifetime",
"gradient": {
"0.0": [1, 1, 0, 1],
"0.5": [1, 0.5, 0, 1],
"1.0": [1, 0, 0, 0]
}
}
},
// Lighting
"minecraft:particle_appearance_lighting": {}
}
}
Complete Particle Examples
Magic Spell Effect
{
"format_version": "1.10.0",
"particle_effect": {
"description": {
"identifier": "custom:magic_spell",
"basic_render_parameters": {
"material": "particles_alpha",
"texture": "textures/particles/magic"
}
},
"components": {
"minecraft:emitter_rate_instant": {
"num_particles": 30
},
"minecraft:emitter_lifetime_once": {
"active_time": 0.5
},
"minecraft:emitter_shape_sphere": {
"radius": 0.3,
"surface_only": true,
"direction": "outwards"
},
"minecraft:particle_lifetime_expression": {
"max_lifetime": 2.0
},
"minecraft:particle_initial_speed": 3.0,
"minecraft:particle_motion_dynamic": {
"linear_acceleration": [0, 2, 0],
"linear_drag_coefficient": 2.0
},
"minecraft:particle_appearance_billboard": {
"size": [
"0.2 - (variable.particle_age / variable.particle_lifetime) * 0.15",
"0.2 - (variable.particle_age / variable.particle_lifetime) * 0.15"
],
"facing_camera_mode": "lookat_xyz",
"uv": {
"texture_width": 128,
"texture_height": 128,
"uv": [0, 0],
"uv_size": [8, 8]
}
},
"minecraft:particle_appearance_tinting": {
"color": {
"interpolant": "variable.particle_age / variable.particle_lifetime",
"gradient": {
"0.0": [0.5, 0, 1, 1],
"0.5": [0.7, 0.3, 1, 0.8],
"1.0": [1, 1, 1, 0]
}
}
}
}
}
}
Fire Effect
{
"format_version": "1.10.0",
"particle_effect": {
"description": {
"identifier": "custom:fire",
"basic_render_parameters": {
"material": "particles_alpha",
"texture": "textures/particles/fire"
}
},
"components": {
"minecraft:emitter_rate_steady": {
"spawn_rate": 20,
"max_particles": 50
},
"minecraft:emitter_lifetime_looping": {
"active_time": 10
},
"minecraft:emitter_shape_disc": {
"radius": 0.5,
"plane_normal": [0, 1, 0]
},
"minecraft:particle_lifetime_expression": {
"max_lifetime": "Math.random(0.5, 1.5)"
},
"minecraft:particle_initial_speed": [0.5, 2.0],
"minecraft:particle_motion_dynamic": {
"linear_acceleration": [
"Math.random(-1, 1)",
"3 + Math.random(0, 2)",
"Math.random(-1, 1)"
]
},
"minecraft:particle_appearance_billboard": {
"size": [
"0.3 - (variable.particle_age / variable.particle_lifetime) * 0.2",
"0.3 - (variable.particle_age / variable.particle_lifetime) * 0.2"
],
"facing_camera_mode": "lookat_xyz",
"uv": {
"texture_width": 128,
"texture_height": 128,
"uv": [0, 0],
"uv_size": [16, 16],
"flipbook": {
"base_UV": [0, 0],
"size_UV": [16, 16],
"step_UV": [16, 0],
"frames_per_second": 15,
"max_frame": 8,
"stretch_to_lifetime": true
}
}
},
"minecraft:particle_appearance_tinting": {
"color": {
"interpolant": "variable.particle_age / variable.particle_lifetime",
"gradient": {
"0.0": [1, 1, 0.5, 1],
"0.3": [1, 0.6, 0, 1],
"0.6": [0.8, 0.2, 0, 0.7],
"1.0": [0.3, 0.1, 0.1, 0]
}
}
}
}
}
}
Explosion Effect
import { ParticleEffectResourceDefinition } from 'minecraft-creator-tools';
const particleDef = await ParticleEffectResourceDefinition.ensureOnFile(file);
// Configure explosion particle
if (particleDef.data) {
particleDef.data.particle_effect = {
description: {
identifier: 'custom:explosion',
basic_render_parameters: {
material: 'particles_alpha',
texture: 'textures/particles/explosion'
}
},
components: {
'minecraft:emitter_rate_instant': {
num_particles: 50
},
'minecraft:emitter_lifetime_once': {
active_time: 0.1
},
'minecraft:emitter_shape_sphere': {
radius: 0.1,
surface_only: false,
direction: 'outwards'
},
'minecraft:particle_lifetime_expression': {
max_lifetime: 'Math.random(0.3, 0.8)'
},
'minecraft:particle_initial_speed': [5, 10],
'minecraft:particle_motion_dynamic': {
linear_acceleration: [0, -20, 0],
linear_drag_coefficient: 3.0
},
'minecraft:particle_appearance_billboard': {
size: [
'0.3 + (variable.particle_age / variable.particle_lifetime) * 0.5',
'0.3 + (variable.particle_age / variable.particle_lifetime) * 0.5'
],
facing_camera_mode: 'lookat_xyz',
uv: {
texture_width: 128,
texture_height: 128,
uv: [0, 0],
uv_size: [16, 16]
}
},
'minecraft:particle_appearance_tinting': {
color: {
interpolant: 'variable.particle_age / variable.particle_lifetime',
gradient: {
'0.0': [1, 1, 1, 1],
'0.3': [1, 0.8, 0.5, 0.8],
'0.6': [0.5, 0.5, 0.5, 0.4],
'1.0': [0.2, 0.2, 0.2, 0]
}
}
}
}
};
}
particleDef.persist();
console.log('Explosion particle created!');
Particle Materials
Common particle materials:particles_alpha- Standard alpha blendingparticles_blend- Additive blending (bright effects)particles_opaque- No transparency
Molang in Particles
Particles support Molang expressions for dynamic behavior:{
"minecraft:particle_lifetime_expression": {
"max_lifetime": "Math.random(1.0, 3.0)"
},
"minecraft:particle_initial_speed": "2 + Math.random(0, 3)",
"minecraft:particle_appearance_billboard": {
"size": [
"0.1 * (1 + Math.sin(variable.particle_age * 360))",
"0.1 * (1 + Math.cos(variable.particle_age * 360))"
]
},
"minecraft:particle_motion_parametric": {
"relative_position": [
"Math.cos(variable.particle_age * 720) * 2",
"variable.particle_age * 5",
"Math.sin(variable.particle_age * 720) * 2"
]
}
}