Troubleshooting Guide

Troubleshooting Guide

This guide covers common issues with Glamour and their solutions.

Installation Issues

Glamour Won’t Load

Symptoms:

• Mod doesn’t appear in mod list
• No Glamour commands available
• Server crashes on startup

Common Causes & Solutions:

Missing Dependencies

Check that all required mods are installed:

Required:
- Fabric Loader 0.16.14+
- Fabric API 0.116.4+1.21.1
- Fabric Kotlin 1.13.0+kotlin.2.1.0
- Cobblemon 1.7.0+1.21.1
- Ceremony 3.0.7+
- SGui 1.6.1+1.21.1
- Adventure Platform Fabric 5.14.2
- Impactor Libraries 5.3.0

Solution: Install any missing dependencies.

Wrong Minecraft Version

Error: Incompatible mod set!

Solution: Ensure you’re running Minecraft 1.21.1, not 1.21 or 1.21.2.

Conflicting Mods

Error: Class loading errors or mixins failing

Solution:

1. Remove other particle mods temporarily
2. Check logs for specific conflicts
3. Update all mods to latest versions

Corrupted JAR

Error: ZipException or file reading errors

Solution: Re-download Glamour JAR from a trusted source.

Configuration Not Generating

Symptom: config/glamour/ folder doesn’t exist after first launch

Causes:

1. Insufficient file permissions
2. Glamour didn’t fully initialize
3. Server crashed before config generation

Solutions:

1. Check server has write permissions to config directory
2. Look for initialization errors in logs
3. Manually create config/glamour/ and restart server

Command Issues

Commands Not Recognized

Symptom: /particles command not found

Checklist:

1. ✅ Glamour is loaded (/mods list or check logs)
2. ✅ You have permission (op level 2+ or LuckPerms permission)
3. ✅ Command syntax is correct

Solutions:

No Permission

# If using LuckPerms
lp user YourName permission set glamour.command.particles true

Command Syntax Error

Correct syntax:

/particles gui
/particles apply sendout particle_id
/persistentparticles reload

Not:

/particle gui          ❌ (missing 's')
/glamour particles gui ❌ (no /glamour prefix)

“You don’t have permission to use this particle”

Symptom: Can open GUI but can’t apply particles

Cause: Missing particle-specific permission

Solution:

# Grant specific particle
lp user YourName permission set glamour.particles.confetti_burst true

# Or grant category
lp user YourName permission set glamour.particles.category.celebration.* true

# Or grant rarity level
lp user YourName permission set glamour.particles.rarity.common.* true

# Or grant all
lp user YourName permission set glamour.particles.* true

“No Pokemon in that slot”

Symptom: Command fails when specifying slot number

Causes:

1. Slot is empty
2. Invalid slot number (must be 1-6)
3. Pokemon is in PC, not party

Solutions:

1. Check party has Pokemon in that slot
2. Use slot 1-6 only
3. Omit slot parameter to use selected Pokemon:

   /particles apply sendout confetti_burst

Particle Display Issues

Particles Not Showing

Symptom: Applied particles don’t render

Diagnostic Steps:

1. Verify Application

/particles manage

Check if particle is actually applied to Pokemon.

2. Check Distance

Are you within render distance?

• Default: 32 blocks
• Check particle config’s maxDistance setting
• Get closer to Pokemon

3. Verify Particle Resource ID

Error in logs: Unknown particle: ...

Solution: Check particleResourceId in config matches Cobblemon’s particle pack:

{
  "particleResourceId": "cobblemon:sparkle"  // Must be valid Cobblemon particle
}

Common valid particles:

• cobblemon:sparkle
• cobblemon:flame
• cobblemon:bubble
• cobblemon:electric_spark

4. Client-Side Check

Cause: Client missing Cobblemon or resource pack

Solution: Ensure client has:

• Cobblemon mod installed
• Cobblemon resource pack loaded
• Particles enabled in video settings

5. Visibility Settings

If using persistent particles with onlyWhenVisible: true:

• Pokemon must be in your field of view
• Turn to face Pokemon

If using requiresLOS: true:

• Must have direct line of sight
• Remove blocks between you and Pokemon

Particles Appearing Incorrectly

Too Many Particles

Symptom: Overwhelming particle spam

Solutions:

1. Increase intervalTicks (spawn less frequently)

   "intervalTicks": 100  // Was 20

2. Reduce particleCount

   "particleCount": 1    // Was 5

3. Decrease radius

   "radius": 0.5         // Was 2.0

Particles in Wrong Location

Symptom: Particles floating away from Pokemon

Cause: followEntity is false

Solution:

"followEntity": true  // Particles follow Pokemon

Symptom: Particles too high/low

Solution: Adjust offsetY

"offsetY": 1.5  // Raise particles
"offsetY": 0.0  // Lower particles

Persistent Particles Not Triggering

Symptom: Conditions should match but no particles

Debugging:

1. Check Configuration Loaded

/persistentparticles debug particle_id

Shows if config exists and its settings.

2. Verify Conditions Match

Common mistakes:

Species Name Format:

"species": ["pikachu"]        // ✅ Correct
"species": ["Pikachu"]        // ❌ Case matters
"species": ["pokemon:pikachu"] // ❌ Unless using namespace

Biome Names:

"biomes": ["minecraft:plains"]  // ✅ Correct (namespaced)
"biomes": ["plains"]            // ❌ Missing namespace

Time of Day:

"timeOfDay": ["night"]  // ✅ Correct
"timeOfDay": ["Night"]  // ❌ Case matters

3. Check Priority

Another config might have higher priority:

/persistentparticles debug higher_priority_config

If both match, higher priority wins.

4. View Statistics

/persistentparticles stats

Shows how many Pokemon are being tracked and renders per tick.

Performance Issues

Server Lag

Symptom: TPS drops when many Pokemon are out

Diagnostics:

/persistentparticles stats

Check:

• Renders This Tick: Should be < 100
• LOS Tests: Should be < 50

Solutions:

Reduce Render Frequency

"intervalTicks": 100  // Increase from 20

Lower Particle Counts

"particleCount": 2    // Decrease from 5

Reduce Render Distance

"maxDistance": 24     // Decrease from 64

Enable Visibility Checks

"onlyWhenVisible": true  // Cheap optimization

Avoid Expensive LOS

"requiresLOS": false  // Don't use unless necessary

Client FPS Drops

Symptom: Client lag when near many Pokemon

Cause: Too many particles rendering on client

Solutions:

1. Reduce particleCount in configs
2. Lower maxDistance to cull distant particles
3. Increase intervalTicks for less frequent spawns
4. Client: Lower particle setting in video options

Memory Issues

Symptom: High memory usage or out-of-memory errors

Causes:

1. Too many cached states
2. Memory leak in configuration loading

Solutions:

1. Restart server periodically
2. Reduce number of persistent particle configs
3. Increase JVM heap size:

   java -Xmx4G -Xms4G -jar server.jar

Configuration Issues

JSON Parse Errors

Error: Expected ',' at line X

Cause: Invalid JSON syntax

Common Mistakes:

Missing Comma

{
  "id": "test"
  "type": "SENDOUT"  // ❌ Missing comma after "test"
}

Fix:

{
  "id": "test",
  "type": "SENDOUT"  // ✅ Comma added
}

Trailing Comma

{
  "id": "test",
  "type": "SENDOUT",  // ❌ Trailing comma before }
}

Fix:

{
  "id": "test",
  "type": "SENDOUT"  // ✅ No trailing comma
}

Wrong Quotes

{
  "id": 'test'  // ❌ Single quotes
}

Fix:

{
  "id": "test"  // ✅ Double quotes
}

Config Not Loading

Symptom: Particles don’t appear after creating config file

Checklist:

1. ✅ File is in correct directory
2. ✅ File has .json extension
3. ✅ JSON is valid (use a validator)
4. ✅ Ran reload command

Solutions:

Wrong Directory

✅ config/glamour/particles/my_particle.json
❌ config/glamour/my_particle.json
❌ config/particles/my_particle.json

Run Reload Command

/particles reload
/persistentparticles reload

Check Logs

Look for errors in logs/latest.log:

[Glamour] Failed to load particle config: my_particle.json

Effects Not Persisting

Symptom: Particles reset after server restart

Cause: Ceremony state not saving

Solutions:

Check Ceremony Installation

Ensure Ceremony mod is installed and loaded.

Verify Database

Check Ceremony’s database configuration:

{
  "database": {
    "type": "sqlite",
    "path": "ceremony_data.db"
  }
}

Check File Permissions

Ensure server can write to database file.

Review Logs

Look for Ceremony database errors in logs.

LuckPerms Issues

Permissions Not Working

Symptom: Permission granted but still denied

Solutions:

Clear Permission Cache

/lp reloadconfig
/particles reload

Check Permission Inheritance

/lp user YourName permission info

Verify the permission is actually granted (not negated by higher priority).

Rejoin Server

Player may need to rejoin for permissions to update.

Wildcard Permissions Not Working

Symptom: glamour.particles.* doesn’t grant all particles

Cause: LuckPerms wildcard not properly configured

Solution:

# Use proper wildcard syntax
lp user YourName permission set glamour.particles.* true

# Verify
lp user YourName permission check glamour.particles.confetti_burst

Database Issues

SQLite Lock Errors

Error: database is locked

Causes:

1. Multiple servers accessing same database
2. Improper shutdown left lock

Solutions:

1. Ensure only one server instance running
2. Delete .db-shm and .db-wal files
3. Restart server

MySQL Connection Failures

Error: Communications link failure

Solutions:

1. Verify MySQL server is running
2. Check connection credentials
3. Ensure firewall allows connection
4. Test connection with MySQL client

MongoDB Connection Issues

Error: Connection refused

Solutions:

1. Verify MongoDB server is running
2. Check connection string format
3. Ensure database exists
4. Check authentication credentials

Getting Help

If none of these solutions work:

1. Check Logs: Look in logs/latest.log for errors
2. Test Minimal Setup: Remove other mods to isolate issue
3. Verify Versions: Ensure all mods are correct versions
4. Create Issue: Report bug with:
   • Exact error message
   • Glamour version
   • Full mod list
   • Relevant log excerpts
   • Steps to reproduce

Next Steps

• Best Practices
• Performance Tuning
• Particle Examples