N | Utility: ProjectileUtils

N | Utility: ProjectileUtils

---

Table of Contents

• 1. Overview
• 2. What is ProjectileUtils?
• 3. Basic Usage
• 4. API Reference
• 5. Advanced Patterns
• 6. Troubleshooting & Notes
• 7. See Also

---

1. Overview

ProjectileUtils is a utility class in FXItems for creating custom projectiles with enhanced behaviors, effects, and integration with other plugins such as ModelEngine.
It centralizes projectile spawning logic, allowing you to easily define particles, damage, speed, and more for custom item abilities.

---

2. What is ProjectileUtils?

• Spawns projectiles (arrows or custom entities) with custom properties.
• Supports custom damage, particle trails, gravity, glowing, knockback, and more.
• Integrates with ModelEngine for visual custom projectiles if the plugin is installed.
• Handles projectile despawn timing and custom behaviors on impact.

---

3. Basic Usage

Example: Spawn a custom projectile

ProjectileUtils.createCustomProjectile(
    plugin,
    player,                      // Shooter
    Particle.FLAME,              // Trail particle
    2,                           // Particle count
    true,                        // Gravity
    false,                       // Glowing
    1,                           // Knockback strength
    false,                       // Silent
    2.0,                         // Speed
    8.0,                         // Damage
    false,                       // Speed-based damage
    EntityType.ARROW,            // Projectile type
    false,                       // Use ModelEngine
    "",                          // ModelEngine modelId
    60,                          // Despawn time (ticks)
    0                            // Piercing level
);

---

4. API Reference

/**
 * Creates a custom projectile with specified properties.
 *
 * @param plugin           The plugin instance.
 * @param shooter          The player launching the projectile.
 * @param trailParticle    Particle trail type.
 * @param particleCount    Number of particles per tick.
 * @param gravity          Whether gravity affects the projectile.
 * @param glowing          Whether the projectile glows.
 * @param knockbackStrength Knockback level for arrows.
 * @param silent           If true, projectile is silent.
 * @param speed            Launch speed.
 * @param damage           Base damage (used if not speedBasedDamage).
 * @param speedBasedDamage If true, damage scales with speed.
 * @param projectileType   Bukkit EntityType (e.g., ARROW, SNOWBALL).
 * @param useModelEngine   If true, uses ModelEngine for visuals.
 * @param modelId          ModelEngine model id (if used).
 * @param despawnTime      Time in ticks before the projectile despawns.
 * @param piercingLevel    Pierce level (arrows only).
 * @throws ProjectileException if ModelEngine is required but not present, or modelId is invalid.
 */
public static void createCustomProjectile(
    Plugin plugin,
    Player shooter,
    Particle trailParticle,
    int particleCount,
    boolean gravity,
    boolean glowing,
    int knockbackStrength,
    boolean silent,
    double speed,
    double damage,
    boolean speedBasedDamage,
    EntityType projectileType,
    boolean useModelEngine,
    String modelId,
    int despawnTime,
    int piercingLevel
)

---

5. Advanced Patterns

• ModelEngine Projectiles:
  Set useModelEngine to true and provide a valid modelId to use a ModelEngine entity as the projectile.
  If ModelEngine is not installed, an exception is thrown.
• Custom Damage:
  For arrows, custom damage is handled via metadata and applied on impact.
• Particle Trails:
  Particle effects are spawned along the projectile's path every tick.
• Despawning:
  Projectiles are automatically despawned after the configured time.

---

6. Troubleshooting & Notes

• If ModelEngine is not installed and useModelEngine is true, an exception is thrown with a clear message.
• If using ModelEngine, modelId must be a valid string; otherwise, the projectile will not spawn.
• Custom damage for arrows is only applied if speedBasedDamage is false.
• All behavior (particle, glowing, damage) is handled within the utility; no need to manually manage these with listeners.

---

7. See Also

• L | Utility: CooldownUtils
• M | Utility: TeleportUtils
• API: Utils

---