Player Particle System

Player Particle System

Player particles are effects that trigger based on player actions, movement, and status. Unlike Pokémon particles, these are attached to the player character and respond to gameplay events.

Overview

Player particles provide:

• 73 unique triggers across 7 categories
• Action-based activation (walking, jumping, attacking, etc.)
• Flexible timing control via settings
• Category-based organization for permissions and GUI
• Multiple particle types for different use cases

Configuration Files

Player particle configurations are JSON files stored in:

config/glamour/player_particles/

Each file can contain one or multiple player particle configurations.

Full Schema

{
  "id": "cherry_trail",
  "displayName": "Cherry Trail",
  "description": "Leaves cherry blossoms as you walk",
  "type": "MOVEMENT",
  "particleResourceId": "cherry_leaves_particle",
  "category": "nature",
  "rarity": "UNCOMMON",
  "settings": {
    "followPlayer": false,
    "radius": 1.0,
    "intervalTicks": 8,
    "durationTicks": 60,
    "offsetX": 0.0,
    "offsetY": 0.2,
    "offsetZ": 0.0,
    "particleCount": 2
  },
  "guiItemId": "minecraft:cherry_leaves",
  "permission": "glamour.particles.player.cherry_trail",
  "triggers": ["WALKING", "RUNNING"]
}

Field Reference

Basic Fields

id

• Type: String
• Required: Yes
• Description: Unique identifier for the particle effect
• Rules: Lowercase, underscores, must be unique
• Example: "cherry_trail"

displayName

• Type: String
• Required: Yes
• Description: User-friendly name shown in GUI
• Example: "Cherry Blossom Trail"

description

• Type: String
• Required: Yes
• Description: Explanation shown to players
• Example: "Leaves a trail of cherry blossoms as you walk"

type

• Type: Enum
• Required: Yes
• Description: General category of the particle
• Options:
  • AMBIENT - Continuous timer-based effects
  • MOVEMENT - Movement-triggered effects
  • JUMP - Jump action effects
  • ATTACK - Attack/combat effects
  • SNEAK - Sneak/crouch effects
• Note: Type provides general categorization; specific behavior is controlled by triggers
• Example: "MOVEMENT"

particleResourceId

• Type: String
• Required: Yes
• Description: Cobblemon snowstorm particle identifier
• Format: Plain name or namespaced ID
• Example: "cherry_leaves_particle" or "cobblemon:sparkle"

category

• Type: String
• Required: Yes
• Description: Category for organization and permissions
• Default Categories:
  • fire - Fire-themed effects
  • magic - Magical/arcane effects
  • nature - Nature-themed effects
  • water - Water-themed effects
  • electric - Electric/lightning effects
  • air - Air/wind effects
  • combat - Combat-themed effects
  • stealth - Stealth/shadow effects
  • soul - Soul/spirit effects
  • miscellaneous - Other effects
• Example: "nature"

rarity

• Type: Enum
• Required: Yes
• Options: COMMON, UNCOMMON, RARE, EPIC, LEGENDARY, MYTHICAL
• Usage: Affects GUI sorting and can be used for permissions
• Example: "UNCOMMON"

guiItemId

• Type: String
• Required: No
• Default: "minecraft:firework_rocket"
• Description: Item shown as icon in GUI
• Example: "minecraft:cherry_leaves"

permission

• Type: String
• Required: No
• Default: glamour.particles.player.<id>
• Description: Permission node required to use this effect
• Example: "glamour.particles.player.cherry_trail"

triggers

• Type: Array of Strings
• Required: No
• Default: [] (empty = always active for AMBIENT type)
• Description: Specific gameplay events that trigger this effect
• See: Complete Trigger Reference below
• Example: ["WALKING", "RUNNING", "SPRINTING"]

Settings Object

The settings object controls particle behavior and appearance.

settings.followPlayer

• Type: Boolean
• Required: Yes
• Default: true
• Description: Whether particles follow the player or spawn at world position
• Options:
  • true - Particles move with player (attached)
  • false - Particles stay where spawned (trail effect)
• Example: false (for trails)

settings.radius

• Type: Float
• Required: Yes
• Default: 2.0
• Description: Random spawn radius around spawn point in blocks
• Range: 0.0-10.0
• Example: 1.0

settings.intervalTicks

• Type: Integer
• Required: Yes
• Default: 20
• Description: Ticks between particle spawns (20 ticks = 1 second)
• Range: 1-1000+
• Example: 8 (0.4 seconds)

settings.durationTicks

• Type: Integer
• Required: Yes
• Default: 40
• Description: How long each particle instance lasts
• Range: 1-1000+
• Example: 60 (3 seconds)

settings.offsetX / offsetY / offsetZ

• Type: Float
• Required: Yes
• Default: 0.0
• Description: Position offset from player center on each axis
• Usage: Adjust particle spawn location
• Example: "offsetY": 0.2 (slightly above ground)

settings.particleCount

• Type: Integer
• Required: Yes
• Default: 1
• Description: Number of particles spawned per interval
• Range: 1-20
• Performance: Higher values increase client load
• Example: 2

Trigger Reference

Triggers are organized into 7 categories with 73 total triggers.

Movement Triggers (13)

• WALKING - Walking at normal speed
• RUNNING - Running (no sprint)
• SPRINTING - Sprinting
• SNEAKING - Sneaking/crouching
• SWIMMING - Swimming in water
• FLYING - Flying (creative/spectator)
• JUMPING - Jumping action
• FALLING - Falling through air
• LANDING - Landing from fall
• MOVING - Any movement
• STANDING_STILL - Not moving
• CROUCHING - Sneaking position
• GLIDING - Elytra gliding

Combat Triggers (11)

• ATTACKING - Attacking entities
• BLOCKING - Blocking with shield
• TAKING_DAMAGE - Receiving damage
• CRITICAL_HIT - Landing critical hit
• COMBAT - In combat state
• ENTERING_COMBAT - Combat state start
• LEAVING_COMBAT - Combat state end
• DODGING - Dodging attacks
• KILLING_ENTITY - Killing entities
• DEATH - Player death
• RESPAWN - Player respawn

Interaction Triggers (12)

• EATING - Eating food
• DRINKING - Drinking potions
• MINING - Breaking blocks
• PLACING_BLOCK - Placing blocks
• INTERACTING - Right-click interactions
• CRAFTING - Crafting items
• ENCHANTING - Using enchanting table
• BREWING - Brewing potions
• FISHING - Fishing
• TRADING - Trading with villagers
• OPENING_CHEST - Opening containers
• USING_ITEM - Using items

Status Triggers (11)

• LOW_HEALTH - Below 25% health
• FULL_HEALTH - At maximum health
• HEALING - Gaining health
• REGENERATING - Health regeneration
• POISONED - Poison effect active
• ON_FIRE - On fire
• INVISIBLE - Invisibility effect active
• HUNGRY - Low food level
• WELL_FED - Full food level
• TIRED - (Custom implementation)
• ENERGIZED - (Custom implementation)

Experience Triggers (5)

• LEVEL_UP - Gaining a level
• GAINING_EXP - Gaining experience points
• ACHIEVEMENT - Earning advancement
• FIRST_TIME_CRAFT - Crafting item for first time
• MILESTONE_REACHED - Custom milestones

Environment Triggers (14)

• IN_RAIN - While raining
• IN_STORM - During thunderstorm
• IN_SUNLIGHT - In direct sunlight
• IN_SHADE - In shade
• UNDERWATER - Underwater
• HIGH_ALTITUDE - High Y coordinate
• UNDERGROUND - Below certain Y level
• IN_NETHER - In Nether dimension
• IN_END - In End dimension
• DAY_TIME - During day
• NIGHT_TIME - During night
• DAWN - At dawn
• DUSK - At dusk
• (Generic) ENVIRONMENT - Any environmental condition

Special Triggers (7)

• ALWAYS - Constantly active
• IDLE - When standing still
• MEDITATION - (Custom implementation)
• CELEBRATION - Special events
• STEALTH - Stealth mode
• FOCUS - Focus mode
• LUCKY - Lucky events

Example Configurations

Simple: Footstep Trail

{
  "id": "footsteps",
  "displayName": "Magical Footsteps",
  "description": "Sparkles appear with each step",
  "type": "MOVEMENT",
  "particleResourceId": "cobblemon:sparkle",
  "category": "magic",
  "rarity": "COMMON",
  "settings": {
    "followPlayer": false,
    "radius": 0.3,
    "intervalTicks": 10,
    "durationTicks": 40,
    "offsetX": 0.0,
    "offsetY": 0.1,
    "offsetZ": 0.0,
    "particleCount": 1
  },
  "guiItemId": "minecraft:glowstone_dust",
  "triggers": ["WALKING", "RUNNING"]
}

Intermediate: Combat Aura

{
  "id": "battle_aura",
  "displayName": "Battle Aura",
  "description": "Fierce aura during combat",
  "type": "AMBIENT",
  "particleResourceId": "cobblemon:flame",
  "category": "combat",
  "rarity": "RARE",
  "settings": {
    "followPlayer": true,
    "radius": 1.5,
    "intervalTicks": 15,
    "durationTicks": 30,
    "offsetX": 0.0,
    "offsetY": 1.0,
    "offsetZ": 0.0,
    "particleCount": 3
  },
  "guiItemId": "minecraft:blaze_powder",
  "triggers": ["COMBAT", "ATTACKING"]
}

Advanced: Conditional Sprint Effect

{
  "id": "speed_lines",
  "displayName": "Speed Lines",
  "description": "Motion lines when sprinting",
  "type": "MOVEMENT",
  "particleResourceId": "speed_line_particle",
  "category": "air",
  "rarity": "EPIC",
  "settings": {
    "followPlayer": false,
    "radius": 0.8,
    "intervalTicks": 3,
    "durationTicks": 15,
    "offsetX": 0.0,
    "offsetY": 1.0,
    "offsetZ": 0.0,
    "particleCount": 2
  },
  "guiItemId": "minecraft:feather",
  "triggers": ["SPRINTING"]
}

Expert: Multi-Trigger Ambient

{
  "id": "nature_spirit",
  "displayName": "Spirit of Nature",
  "description": "Nature particles in various situations",
  "type": "AMBIENT",
  "particleResourceId": "leaf_particle",
  "category": "nature",
  "rarity": "LEGENDARY",
  "settings": {
    "followPlayer": true,
    "radius": 2.0,
    "intervalTicks": 20,
    "durationTicks": 80,
    "offsetX": 0.0,
    "offsetY": 1.5,
    "offsetZ": 0.0,
    "particleCount": 1
  },
  "guiItemId": "minecraft:oak_leaves",
  "triggers": ["IN_SUNLIGHT", "IN_RAIN", "WALKING"]
}

Best Practices

Performance

1. Lower particle counts: Keep particleCount at 1-3 for most effects
2. Increase intervals: 10-20 ticks is reasonable for most effects
3. Short durations: 20-60 ticks prevents particle buildup
4. Use followPlayer wisely: false for trails, true for auras

Design

1. Match triggers to effect: Sprint effects should use SPRINTING
2. Combine related triggers: [“WALKING”, “RUNNING”, “SPRINTING”]
3. Consider player experience: Avoid overwhelming particle density
4. Test performance: Check with multiple players active

Organization

1. Consistent naming: Use descriptive, unique IDs
2. Categorize properly: Use appropriate category for permissions
3. Set appropriate rarity: Affects GUI sorting and desirability
4. Document clearly: Good descriptions help players choose

Integration with Wardrobe

Player particles can be used in the Wardrobe system as effect IDs in presets. The id field of a player particle becomes the effectId in a wardrobe preset.

Example:

// Player Particle (player_particles/flame.json)
{
  "id": "flame_particle",
  "displayName": "Flame",
  ...
}

// Wardrobe Preset (wardrobe/presets.json)
{
  "id": "flame_trail",
  "effectId": "flame_particle",  // References player particle ID
  ...
}

Commands

Reload player particle configurations:

/particles reload

Permissions

Per-Particle Permission

glamour.particles.player.<particle_id>

Wildcard Permissions

glamour.particles.player.*              # All player particles
glamour.particles.category.nature.*     # All in nature category
glamour.particles.rarity.legendary.*    # All legendary rarity

Troubleshooting

Particles don’t appear

• Check permission configuration
• Verify particleResourceId exists
• Ensure triggers match player action
• Check particle count isn’t 0

Performance issues

• Reduce particleCount
• Increase intervalTicks
• Lower durationTicks
• Limit number of active effects

Particles in wrong location

• Adjust offsetX/Y/Z values
• Check followPlayer setting
• Verify radius is appropriate

Next Steps

• Wardrobe Presets
• Persistent Particles
• Performance Tuning