# Using BreathWeapon<\/p>\n
This guide explains how to integrate the BreathWeapon particle system into your Minecraft mod to create custom particles without writing complex rendering code.<\/p>\n
## Setup<\/p>\n
### 1. Add Dependency<\/p>\n
In your `build.gradle`, add BreathWeapon to your dependencies:<\/p>\n
“`gradle
\nmavenCentral()
\n exclusiveContent {
\n forRepository {
\n maven {
\n name = “Modrinth”
\n url = “https:\/\/api.modrinth.com\/maven”
\n }
\n }
\n forRepositories(fg.repository)
\n filter {
\n includeGroup “maven.modrinth”
\n }
\n }<\/p>\n
dependencies {
\n implementation fg.deobf(“maven.modrinth:breath-weapon:0.0.1”)
\n}
\n“`<\/p>\n
### 2. Import the API<\/p>\n
In your code, import the spawning utilities:<\/p>\n
“`java
\nimport com.dracolich777.breathweapon.util.ParticleSpawner;
\nimport com.dracolich777.breathweapon.api.particle.ParticleRegistry;
\nimport net.minecraft.resources.ResourceLocation;
\n“`<\/p>\n
—<\/p>\n
## Quick Start<\/p>\n
### Minimal Setup<\/p>\n
**1. Create a particle definition JSON:**<\/p>\n
“`
\nsrc\/main\/resources\/data\/yourmodid\/particles\/my_effect.json
\n“`<\/p>\n
“`json
\n{
\n “type”: “sprite”,
\n “lifetime”: 50
\n}
\n“`<\/p>\n
**2. Spawn it in code:**<\/p>\n
“`java
\nParticleSpawner.spawn(level,
\n new ResourceLocation(“yourmodid”, “my_effect”),
\n x, y, z,
\n vx, vy, vz);
\n“`<\/p>\n
That’s it! The particle will render with default texture and physics.<\/p>\n
—<\/p>\n
## Creating Particle Definitions<\/p>\n
Particle definitions are JSON files placed in your mod’s datapacks. Create them at:<\/p>\n
“`
\nsrc\/main\/resources\/data\/yourmodid\/particles\/particle_name.json
\n“`<\/p>\n
### File Structure<\/p>\n
“`
\nsrc\/main\/resources\/
\n\u251c\u2500\u2500 assets\/yourmodid\/
\n\u2502 \u2514\u2500\u2500 textures\/
\n\u2502 \u2514\u2500\u2500 particle\/
\n\u2502 \u251c\u2500\u2500 beam.png
\n\u2502 \u251c\u2500\u2500 spark.png
\n\u2502 \u2514\u2500\u2500 smoke.png
\n\u2514\u2500\u2500 data\/yourmodid\/
\n \u2514\u2500\u2500 particles\/
\n \u251c\u2500\u2500 my_beam.json
\n \u251c\u2500\u2500 my_spark.json
\n \u2514\u2500\u2500 my_smoke.json
\n“`<\/p>\n
### Basic JSON Structure<\/p>\n
Every particle definition has this structure:<\/p>\n
“`json
\n{
\n “type”: “sprite | beam | geo”,
\n “texture”: “yourmodid:textures\/particle\/name”,
\n “lifetime”: 200,
\n “scale”: 1.0,
\n “gravity”: 0.0,
\n “drag”: 1.0,
\n “light”: { … },
\n “animation”: { … }
\n}
\n“`<\/p>\n
### Common Properties<\/p>\n
All particle types support:<\/p>\n
| Property | Type | Default | Description |
\n|———-|——|———|————-|
\n| `type` | string | “sprite” | Particle type: sprite, beam, or geo |
\n| `lifetime` | int | 200 | Duration in ticks (1 tick = 50ms) |
\n| `scale` | float | 1.0 | Size multiplier (0.1 – 10.0) |
\n| `gravity` | float | 0.0 | Downward acceleration (negative = upward) |
\n| `drag` | float | 1.0 | Velocity damping (0.9 = 10% slowdown\/tick) |
\n| `texture` | string | null | Texture path in format `modid:path` |<\/p>\n
### Light Configuration<\/p>\n
Add glow\/dynamic lighting to particles:<\/p>\n
“`json
\n{
\n “type”: “sprite”,
\n “light”: {
\n “mode”: “glow”,
\n “color”: [1.0, 0.5, 0.0],
\n “intensity”: 1.0
\n }
\n}
\n“`<\/p>\n
**Light Modes:**
\n– `”none”` – No special lighting
\n– `”glow”` – Constant glow effect
\n– `”pulse”` – Pulsing brightness<\/p>\n
**For Glow\/Pulse:**
\n“`json
\n“light”: {
\n “mode”: “glow”,
\n “color”: [r, g, b],
\n “intensity”: brightness_0_to_2
\n}
\n“`<\/p>\n
**For Pulse:**
\n“`json
\n“light”: {
\n “mode”: “pulse”,
\n “color”: [r, g, b],
\n “intensity”: 1.0,
\n “pulse_min”: 0.3,
\n “pulse_max”: 1.0,
\n “pulse_speed”: 0.1
\n}
\n“`<\/p>\n
—<\/p>\n
## Spawning Particles<\/p>\n
### Basic Spawning<\/p>\n
**Single particle:**<\/p>\n
“`java
\nParticleSpawner.spawn(level,
\n new ResourceLocation(“yourmodid”, “my_particle”),
\n x, y, z,
\n velocityX, velocityY, velocityZ);
\n“`<\/p>\n
### Pattern Spawning<\/p>\n
**Burst (random directions):**<\/p>\n
“`java
\nParticleSpawner.burst(level,
\n new ResourceLocation(“yourmodid”, “spark”),
\n center, \/\/ Vec3 position
\n count, \/\/ Number of particles (e.g., 10)
\n speed); \/\/ Speed in blocks\/tick (e.g., 0.5)
\n“`<\/p>\n
**Stream (directional):**<\/p>\n
“`java
\nParticleSpawner.stream(level,
\n new ResourceLocation(“yourmodid”, “smoke”),
\n entity, \/\/ Entity to spawn from
\n count, \/\/ Number of particles
\n speed, \/\/ Particle speed
\n spread); \/\/ Angular spread in radians
\n“`<\/p>\n
### Beam Spawning<\/p>\n
**Uniform beam:**<\/p>\n
“`java
\nParticleSpawner.spawnBeam(level,
\n new ResourceLocation(“yourmodid”, “laser”),
\n from, \/\/ Vec3 start position
\n to, \/\/ Vec3 end position
\n width); \/\/ Beam width (e.g., 0.3f)
\n“`<\/p>\n
**Tapered beam (width changes along length):**<\/p>\n
“`java
\nParticleSpawner.spawnBeam(level,
\n new ResourceLocation(“yourmodid”, “laser”),
\n from, \/\/ Vec3 start
\n to, \/\/ Vec3 end
\n startWidth, \/\/ Width at start (e.g., 0.5f)
\n endWidth); \/\/ Width at end (e.g., 0.1f)
\n“`<\/p>\n
—<\/p>\n
## Particle Types<\/p>\n
### Type 1: Sprite (Default)<\/p>\n
Simple 2D particles. Fast and lightweight.<\/p>\n
**Definition:**<\/p>\n
“`json
\n{
\n “type”: “sprite”,
\n “texture”: “yourmodid:particle\/spark”,
\n “lifetime”: 30,
\n “scale”: 0.5,
\n “gravity”: 0.05,
\n “drag”: 0.98,
\n “light”: {
\n “mode”: “glow”,
\n “color”: [1.0, 1.0, 0.0],
\n “intensity”: 0.8
\n }
\n}
\n“`<\/p>\n
**Best for:** Sparks, sparkles, dust, simple effects<\/p>\n
### Type 2: Beam<\/p>\n
Billboard between two points. Supports dynamic endpoints.<\/p>\n
**Definition:**<\/p>\n
“`json
\n{
\n “type”: “beam”,
\n “texture”: “yourmodid:particle\/laser”,
\n “lifetime”: 100,
\n “scale”: 1.0,
\n “light”: {
\n “mode”: “glow”,
\n “color”: [1.0, 0.0, 0.0],
\n “intensity”: 1.5
\n }
\n}
\n“`<\/p>\n
**Best for:** Lasers, energy blasts, directed attacks, tracers<\/p>\n
### Type 3: Geo (GeckoLib Model)<\/p>\n
Full 3D models with animation support.<\/p>\n
**Definition:**<\/p>\n
“`json
\n{
\n “type”: “geo”,
\n “model”: “yourmodid:geo\/explosion.geo.json”,
\n “texture”: “yourmodid:textures\/particle\/explosion.png”,
\n “animation”: “yourmodid:animations\/explosion.animation.json”,
\n “anim_name”: “animation.explosion.burst”,
\n “lifetime”: 50,
\n “scale”: 0.8,
\n “gravity”: -0.05,
\n “drag”: 0.95,
\n “spin”: {
\n “yaw”: 5.0,
\n “pitch”: 2.0,
\n “roll”: 3.0
\n }
\n}
\n“`<\/p>\n
**Properties:**
\n– `model` – Path to your GeckoLib `.geo.json` file
\n– `texture` – Texture for the model
\n– `animation` – Path to animation file (optional)
\n– `anim_name` – Which animation to play (optional)
\n– `spin` – Rotation speed in degrees\/tick (optional)<\/p>\n
**Best for:** Complex effects, explosions, magical effects, custom models<\/p>\n
—<\/p>\n
## Advanced Features<\/p>\n
### Dynamic Beam Endpoints<\/p>\n
Make beams that track targets or move over time:<\/p>\n
“`java
\nimport com.dracolich777.breathweapon.client.particle.SimpleBeamParticle;<\/p>\n
\/\/ When spawning, you need to access the particle directly
\n\/\/ This requires a custom spawning approach or event listener<\/p>\n
SimpleBeamParticle.EndpointProvider provider = (age, lifetime) -> {
\n \/\/ Calculate new position based on age
\n float progress = age \/ (float) lifetime;<\/p>\n
\/\/ Example: Spiral endpoint
\n double angle = progress * Math.PI * 4; \/\/ 2 rotations
\n double newX = centerX + Math.cos(angle) * radius;
\n double newY = centerY + Math.sin(angle) * radius;
\n double newZ = centerZ + Math.sin(progress * Math.PI) * 5;<\/p>\n
return new SimpleBeamParticle.BeamEndpoint(newX, newY, newZ);
\n};<\/p>\n
\/\/ Set on particle (requires direct particle access via event or hook)
\nparticle.setEndpointProvider(provider);
\n“`<\/p>\n
### Physics Customization<\/p>\n
Control how particles move:<\/p>\n
“`json
\n{
\n “gravity”: 0.1, \/\/ Fall speed (positive = down, negative = up)
\n “drag”: 0.95, \/\/ Slow down by 5% each tick
\n “scale”: 1.5 \/\/ Make it 1.5x bigger
\n}
\n“`<\/p>\n
**Examples:**<\/p>\n
– **Floating effect:** `”gravity”: -0.01, “drag”: 1.0`
\n– **Slow fall:** `”gravity”: 0.02, “drag”: 0.99`
\n– **Fading out:** Use short lifetime + high drag
\n– **Fast zoom:** Use high initial velocity + low gravity<\/p>\n
—<\/p>\n
## Complete Examples<\/p>\n
### Example 1: Energy Beam Attack<\/p>\n
**JSON Definition** (`data\/mymod\/particles\/energy_blast.json`):<\/p>\n
“`json
\n{
\n “type”: “beam”,
\n “texture”: “mymod:particle\/energy_beam”,
\n “lifetime”: 80,
\n “scale”: 0.9,
\n “light”: {
\n “mode”: “glow”,
\n “color”: [0.2, 0.7, 1.0],
\n “intensity”: 1.3
\n }
\n}
\n“`<\/p>\n
**Spawning Code** (in an ability handler):<\/p>\n
“`java
\n@SubscribeEvent
\npublic static void onPlayerAttack(LivingAttackEvent event) {
\n if (event.getEntity() instanceof Player player &&
\n player.level() instanceof ServerLevel level) {<\/p>\n
Vec3 from = player.getEyePosition();
\n Vec3 to = from.add(player.getLookAngle().scale(50));<\/p>\n
ParticleSpawner.spawnBeam(level,
\n new ResourceLocation(“mymod”, “energy_blast”),
\n from, to, 0.2f);
\n }
\n}
\n“`<\/p>\n
### Example 2: Explosion Effect<\/p>\n
**JSON Definition** (`data\/mymod\/particles\/explosion_burst.json`):<\/p>\n
“`json
\n{
\n “type”: “sprite”,
\n “texture”: “mymod:particle\/explosion”,
\n “lifetime”: 40,
\n “scale”: 1.2,
\n “gravity”: -0.02,
\n “drag”: 0.96,
\n “light”: {
\n “mode”: “pulse”,
\n “color”: [1.0, 0.6, 0.0],
\n “intensity”: 1.5,
\n “pulse_min”: 0.5,
\n “pulse_max”: 1.5,
\n “pulse_speed”: 0.15
\n }
\n}
\n“`<\/p>\n
**Spawning Code**:<\/p>\n
“`java
\npublic static void createExplosion(ServerLevel level, Vec3 center, int power) {
\n ParticleSpawner.burst(level,
\n new ResourceLocation(“mymod”, “explosion_burst”),
\n center,
\n power * 3, \/\/ More particles for bigger explosion
\n power * 0.1); \/\/ Faster spread for bigger explosion
\n}
\n“`<\/p>\n
### Example 3: Magical Aura<\/p>\n
**JSON Definition** (`data\/mymod\/particles\/mana_dust.json`):<\/p>\n
“`json
\n{
\n “type”: “sprite”,
\n “texture”: “mymod:particle\/mana”,
\n “lifetime”: 100,
\n “scale”: 0.6,
\n “gravity”: -0.005,
\n “drag”: 0.98,
\n “light”: {
\n “mode”: “glow”,
\n “color”: [0.7, 0.3, 1.0],
\n “intensity”: 0.9
\n }
\n}
\n“`<\/p>\n
**Spawning Code** (in entity tick):<\/p>\n
“`java
\npublic void createManaAura(Entity entity, ServerLevel level) {
\n Vec3 pos = entity.position().add(0, entity.getBbHeight() \/ 2, 0);<\/p>\n
\/\/ Small burst of particles around entity
\n ParticleSpawner.burst(level,
\n new ResourceLocation(“mymod”, “mana_dust”),
\n pos,
\n 5, \/\/ 5 particles
\n 0.3); \/\/ Slow spread
\n}
\n“`<\/p>\n
### Example 4: Status Effect Indicator<\/p>\n
**JSON Definition** (`data\/mymod\/particles\/poison_cloud.json`):<\/p>\n
“`json
\n{
\n “type”: “sprite”,
\n “texture”: “mymod:particle\/poison”,
\n “lifetime”: 60,
\n “scale”: 0.8,
\n “gravity”: 0.01,
\n “drag”: 0.99,
\n “light”: {
\n “mode”: “glow”,
\n “color”: [0.3, 0.8, 0.2],
\n “intensity”: 0.7
\n }
\n}
\n“`<\/p>\n
**Spawning Code** (while effect active):<\/p>\n
“`java
\n@SubscribeEvent
\npublic static void onLivingUpdate(LivingTickEvent event) {
\n LivingEntity entity = event.getEntity();<\/p>\n
if (entity.hasEffect(MobEffects.POISON) &&
\n entity.level() instanceof ServerLevel level &&
\n entity.tickCount % 5 == 0) { \/\/ Every 5 ticks<\/p>\n
Vec3 pos = entity.position().add(
\n (Math.random() – 0.5) * 0.5,
\n Math.random() * entity.getBbHeight(),
\n (Math.random() – 0.5) * 0.5
\n );<\/p>\n
ParticleSpawner.spawn(level,
\n new ResourceLocation(“mymod”, “poison_cloud”),
\n pos.x, pos.y, pos.z,
\n 0, -0.05, 0); \/\/ Slight upward drift
\n }
\n}
\n“`<\/p>\n
—<\/p>\n
## Checking Particle Availability<\/p>\n
Before spawning, verify the particle is registered:<\/p>\n
“`java
\nimport com.dracolich777.breathweapon.api.particle.ParticleRegistry;<\/p>\n
ResourceLocation particleId = new ResourceLocation(“yourmodid”, “my_particle”);<\/p>\n
if (ParticleRegistry.has(particleId)) {
\n \/\/ Safe to spawn
\n ParticleSpawner.spawn(level, particleId, x, y, z, 0, 0, 0);
\n} else {
\n LOGGER.warn(“Particle not found: {}”, particleId);
\n}
\n“`<\/p>\n
Get particle info:<\/p>\n
“`java
\nvar definition = ParticleRegistry.get(“yourmodid:my_particle”);
\nif (definition != null) {
\n int lifetime = definition.getLifetime();
\n float scale = definition.getScale();
\n String type = definition.getType(); \/\/ “beam”, “geo”, “sprite”
\n}
\n“`<\/p>\n
—<\/p>\n
## Best Practices<\/p>\n
### 1. Organize Your Particles<\/p>\n
“`
\ndata\/yourmodid\/particles\/
\n\u251c\u2500\u2500 abilities\/
\n\u2502 \u251c\u2500\u2500 fireball.json
\n\u2502 \u251c\u2500\u2500 lightning.json
\n\u2502 \u2514\u2500\u2500 healing_circle.json
\n\u251c\u2500\u2500 effects\/
\n\u2502 \u251c\u2500\u2500 hit_effect.json
\n\u2502 \u251c\u2500\u2500 death_burst.json
\n\u2502 \u2514\u2500\u2500 buff_indicator.json
\n\u2514\u2500\u2500 ambient\/
\n \u251c\u2500\u2500 magical_dust.json
\n \u251c\u2500\u2500 fire_embers.json
\n \u2514\u2500\u2500 water_splash.json
\n“`<\/p>\n
### 2. Keep Lifetimes Short<\/p>\n
Don’t make particles last longer than needed:
\n– Sparks: 20-60 ticks
\n– Beams: 50-150 ticks
\n– Explosions: 30-100 ticks
\n– Ambient: 60-200 ticks<\/p>\n
### 3. Test Physics<\/p>\n
“`json
\n{
\n “gravity”: 0.0, \/\/ Start with no gravity
\n “drag”: 1.0 \/\/ Start with no drag
\n}
\n“`<\/p>\n
Then adjust based on visual appearance.<\/p>\n
### 4. Use Appropriate Types<\/p>\n
– **Sprite** – Most effects (fast)
\n– **Beam** – Targeted effects, attacks
\n– **Geo** – Special occasions (slower)<\/p>\n
### 5. Reuse Definitions<\/p>\n
Create one definition and spawn it multiple times:<\/p>\n
“`java
\nfor (int i = 0; i < 10; i++) {\n ParticleSpawner.spawn(level,\n new ResourceLocation(\"mymod\", \"explosion\"),\n x, y, z,\n randomVelX, randomVelY, randomVelZ);\n}\n```\n\n### 6. Add Descriptions to JSONs\n\n```json\n{\n \"_comment\": \"Blue energy beam - used for mage spell attacks\",\n \"type\": \"beam\",\n ...\n}\n```\n\n---\n\n## Troubleshooting\n\n### Particles Not Showing\n\n**Problem:** I spawned a particle but it doesn't appear in-game.\n\n**Solutions:**\n1. Check particle definition is in correct folder: `data\/yourmodid\/particles\/name.json`\n2. Verify the particle ID matches the JSON filename\n3. Use `\/reload` to reload data\n4. Check texture path exists: `assets\/yourmodid\/textures\/particle\/name.png`\n5. Verify you're on the correct level (ServerLevel, not ClientLevel)\n\n**Debug code:**\n```java\nvar def = ParticleRegistry.get(\"yourmodid:my_particle\");\nif (def == null) {\n LOGGER.error(\"Particle not found in registry!\");\n} else {\n LOGGER.info(\"Particle found: {}\", def);\n}\n```\n\n### Texture Not Loading\n\n**Problem:** Particle appears but texture is wrong.\n\n**Solutions:**\n1. Verify texture path uses forward slashes: `\"mymod:particle\/name\"`\n2. Check texture file is PNG format\n3. Texture path should NOT include `.png` extension\n4. Texture should be in `assets\/yourmodid\/textures\/`\n\n### Beam Position Wrong\n\n**Problem:** Beam starts\/ends at wrong position.\n\n**Solutions:**\n1. Use world space coordinates (not relative)\n2. For entities: `entity.getEyePosition()` for eye level\n3. For blocks: `new Vec3(x + 0.5, y + 0.5, z + 0.5)` for center\n4. Verify `from` and `to` are not the same position\n\n### Particle Too Slow\/Fast\n\n**Problem:** Particle movement doesn't match expected velocity.\n\n**Solutions:**\n1. Increase `speed` parameter in `burst()` or `stream()`\n2. Adjust `drag` - lower values = keeps velocity longer\n3. Check particle spawn velocity is correct\n4. Use `gravity` to add momentum over time\n\n### GeckoLib Model Not Loading\n\n**Problem:** Type is \"geo\" but model doesn't render.\n\n**Solutions:**\n1. Verify model file path is correct\n2. Check `.geo.json` file exists\n3. Model path should NOT include `.geo.json` in JSON (just `path` without extension)\n4. Texture path must match model's texture reference\n5. Animation name must match exactly (case-sensitive)\n\n---\n\n## API Reference\n\n### ParticleSpawner Methods\n\n```java\n\/\/ Single particle\nParticleSpawner.spawn(level, id, x, y, z, vx, vy, vz);\nParticleSpawner.spawn(level, id, x, y, z, vx, vy, vz, extraData);\n\n\/\/ Patterns\nParticleSpawner.burst(level, id, center, count, speed);\nParticleSpawner.stream(level, id, entity, count, speed, spread);\n\n\/\/ Beams\nParticleSpawner.spawnBeam(level, id, from, to, width);\nParticleSpawner.spawnBeam(level, id, from, to, startWidth, endWidth);\n```\n\n### ParticleRegistry Methods\n\n```java\nParticleRegistry.register(id, definition);\nParticleRegistry.get(id);\nParticleRegistry.has(id);\nParticleRegistry.getAll();\nParticleRegistry.getAllFromMod(namespace);\n```\n\n---\n\n## Need Help?\n\n- DM me on discord or join my discord server:\n - Discord Server\n - `.themrsuit`\n\nGood luck creating amazing particles!\n<\/p>\n","protected":false},"excerpt":{"rendered":"
This is a library\/api mod to render geckolib models as particles<\/p>\n","protected":false},"featured_media":34677,"template":"","meta":{"_minecraft_slug":"breath-weapon","_minecraft_project_id":"DgX86wMm","_minecraft_author":"TheMrSuit","_minecraft_license":"MIT","_minecraft_downloads":45,"_minecraft_follows":1,"_minecraft_client_side":"required","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"breath-weapon.zip","_minecraft_size_bytes":5223667,"_minecraft_version_count":9,"_minecraft_updated_at":"2026-05-16T12:40:17.485702Z","_minecraft_date_created":"2026-05-11T16:50:58.688718Z","_minecraft_date_modified":"2026-05-13T18:31:17.934223Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/breath-weapon","_minecraft_icon_attachment_id":34677,"_minecraft_imported_at":"2026-06-01T16:36:15+00:00","_minecraft_import_hash":"78f035cdfa112ce05684ee85a77d6cca","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[104,873],"mod_loader":[106],"minecraft_version":[36],"class_list":["post-34676","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-forge","mod_category-library","mod_loader-forge","minecraft_version-1-20-1"],"yoast_head":"\n