Ceremony Integration

Ceremony Integration

Glamour leverages the Ceremony library for robust Pokemon state management and persistence. This page explains the integration and what it means for server administrators.

What is Ceremony?

Ceremony is a comprehensive Pokemon state management infrastructure library that provides:

• Cross-Mod State Registry: Central registry for Pokemon effects shared across multiple mods
• Persistent State Storage: Player-scoped Pokemon data that persists across restarts
• Effect Interfaces: Standardized interfaces for sendout, ambient, and other effect types
• State Management Patterns: Generic data structures for extensible persistence
• Clean Extension APIs: Kotlin extensions for accessing state data

How Glamour Uses Ceremony

Effect Registration

Glamour registers all particle effects in Ceremony’s PokemonEffectRegistry:

Kotlin

// Sendout Effect Registration
PokemonEffectRegistry.register(
  id = "glamour:confetti_burst",
  effect = SendoutEffect { pokemon, world, pos ->
    // Particle spawning logic
  }
)

// Ambient Effect Registration
PokemonEffectRegistry.register(
  id = "glamour:sparkle_aura",
  effect = AmbientEffect { pokemon, world, pos, interval ->
    // Continuous particle logic
  }
)

Java

// Sendout Effect Registration
PokemonEffectRegistry.register(
  "glamour:confetti_burst",
  new SendoutEffect() {
    @Override
    public void execute(Pokemon pokemon, World world, BlockPos pos) {
      // Particle spawning logic
    }
  }
);

// Ambient Effect Registration
PokemonEffectRegistry.register(
  "glamour:sparkle_aura",
  new AmbientEffect() {
    @Override
    public void execute(Pokemon pokemon, World world, BlockPos pos, int interval) {
      // Continuous particle logic
    }
  }
);

Benefits:

• Effects are accessible to other Ceremony-compatible mods
• Centralized registry prevents ID conflicts
• Standardized interfaces ensure consistency

State Persistence

Applied particle effects are stored using Ceremony’s PokemonStateDataObject:

Kotlin

// Glamour's state adapter
class CeremonyParticleStateAdapter : ParticleStateInterface {
  override fun getAppliedEffects(playerUUID: UUID, pokemonUUID: UUID): AppliedEffects? {
    // Retrieves from Ceremony's state system
    return ceremonyState.get(playerUUID, pokemonUUID)
  }

  override fun setAppliedEffects(playerUUID: UUID, pokemonUUID: UUID, effects: AppliedEffects) {
    // Stores in Ceremony's state system
    ceremonyState.set(playerUUID, pokemonUUID, effects)
  }
}

Java

// Glamour's state adapter
public class CeremonyParticleStateAdapter implements ParticleStateInterface {
  @Override
  public AppliedEffects getAppliedEffects(UUID playerUUID, UUID pokemonUUID) {
    // Retrieves from Ceremony's state system
    return ceremonyState.get(playerUUID, pokemonUUID);
  }

  @Override
  public void setAppliedEffects(UUID playerUUID, UUID pokemonUUID, AppliedEffects effects) {
    // Stores in Ceremony's state system
    ceremonyState.set(playerUUID, pokemonUUID, effects);
  }
}

Benefits:

• Effects persist across server restarts
• Data survives when Pokemon are stored in PC
• Effects transfer with Pokemon during trades
• No separate database management needed

Data Structure

Glamour uses Ceremony’s AppliedEffects data structure:

Kotlin

data class AppliedEffects(
  val pokemonUuid: String,
  val sendoutEffect: String?,   // Particle ID or null
  val ambientEffect: String?    // Particle ID or null
)

Java

public class AppliedEffects {
  private final String pokemonUuid;
  private final String sendoutEffect;   // Particle ID or null
  private final String ambientEffect;    // Particle ID or null

  public AppliedEffects(String pokemonUuid, String sendoutEffect, String ambientEffect) {
    this.pokemonUuid = pokemonUuid;
    this.sendoutEffect = sendoutEffect;
    this.ambientEffect = ambientEffect;
  }

  public String getPokemonUuid() { return pokemonUuid; }
  public String getSendoutEffect() { return sendoutEffect; }
  public String getAmbientEffect() { return ambientEffect; }
}

This maps directly to Ceremony’s native state format for seamless integration.

State Management Flow

Applying a Particle

1. Player selects particle in GUI
2. Glamour creates AppliedEffects object
3. State saved through CeremonyParticleStateAdapter
4. Ceremony persists to its data store
5. Effect immediately available for rendering

Loading Effects on Server Start

1. Server starts and loads Ceremony
2. Ceremony loads all persistent state
3. Glamour queries state through adapter
4. Effects reapply automatically when Pokemon spawn

Pokemon State Lifecycle

Player applies particle
    ↓
Glamour → Ceremony State Storage
    ↓
[Server Restart]
    ↓
Ceremony loads state
    ↓
Pokemon spawns → Glamour queries Ceremony → Effect renders

Cross-Mod Compatibility

Because Glamour uses Ceremony’s registry, other mods can:

Query Glamour’s Effects

Kotlin

val effect = PokemonEffectRegistry.get("glamour:confetti_burst")

Java

PokemonEffect effect = PokemonEffectRegistry.get("glamour:confetti_burst");

Trigger Glamour Particles

Kotlin

val sendoutEffect = PokemonEffectRegistry.getSendoutEffect("glamour:sparkle_aura")
sendoutEffect.execute(pokemon, world, pos)

Java

SendoutEffect sendoutEffect = PokemonEffectRegistry.getSendoutEffect("glamour:sparkle_aura");
sendoutEffect.execute(pokemon, world, pos);

Check Applied Particles

Kotlin

val state = ceremonyState.get(playerUUID, pokemonUUID)
if (state.sendoutEffect == "glamour:confetti_burst") {
  // React to Glamour particle being active
}

Java

AppliedEffects state = ceremonyState.get(playerUUID, pokemonUUID);
if ("glamour:confetti_burst".equals(state.getSendoutEffect())) {
  // React to Glamour particle being active
}

Configuration Independence

While Glamour integrates deeply with Ceremony for state management, particle configurations remain independent:

• Particle JSON configs are loaded by Glamour
• No Ceremony configuration needed for basic usage
• Ceremony handles only the persistence layer

Database Backend

Ceremony supports multiple database backends:

SQLite (Default)

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

MySQL/MariaDB

{
  "database": {
    "type": "mysql",
    "host": "localhost",
    "port": 3306,
    "database": "ceremony",
    "username": "user",
    "password": "pass"
  }
}

MongoDB

{
  "database": {
    "type": "mongodb",
    "connectionString": "mongodb://localhost:27017/ceremony"
  }
}

Note: Configure in Ceremony’s config, not Glamour’s. Glamour automatically uses whatever backend Ceremony is configured with.

Performance Characteristics

State Reads

• Cached: Ceremony caches state in memory
• Fast Access: No database query on every particle render
• Lazy Loading: State loaded only when needed

State Writes

• Async: State writes happen asynchronously
• Batched: Multiple writes batched for efficiency
• Non-Blocking: Particle application doesn’t wait for database

Memory Usage

• State cached per-player, per-Pokemon
• Inactive Pokemon states unloaded from memory
• Configurable cache TTL in Ceremony

Troubleshooting

Effects Not Persisting

Symptom: Particles reset after server restart

Causes:

1. Ceremony not properly installed
2. Database connection issues
3. State write failures

Solutions:

• Check Ceremony is installed and loaded
• Verify database configuration
• Check server logs for Ceremony errors

State Conflicts

Symptom: Multiple mods fighting over same Pokemon state

Cause: Other mods also using Ceremony state

Solution: Ceremony’s state system is designed for this - each mod gets its own namespace. Check for mod conflicts in logs.

Performance Issues

Symptom: Lag when applying particles

Causes:

1. Database write contention
2. Ceremony cache misses
3. Slow database backend

Solutions:

• Use faster database (SQLite for small servers, MySQL for large)
• Increase Ceremony’s cache size
• Enable async writes in Ceremony config

Advanced: Custom State Extensions

Servers running custom mods can extend Glamour’s state through Ceremony:

Kotlin

// Custom state extension
data class CustomParticleData(
  val intensity: Float,
  val color: Color,
  val metadata: Map<String, Any>
)

// Register custom state object
ceremonyState.registerCustomState(
  namespace = "mymod:glamour_extended",
  dataClass = CustomParticleData::class
)

Java

// Custom state extension
public class CustomParticleData {
  private final float intensity;
  private final Color color;
  private final Map<String, Object> metadata;

  public CustomParticleData(float intensity, Color color, Map<String, Object> metadata) {
    this.intensity = intensity;
    this.color = color;
    this.metadata = metadata;
  }

  // Getters
  public float getIntensity() { return intensity; }
  public Color getColor() { return color; }
  public Map<String, Object> getMetadata() { return metadata; }
}

// Register custom state object
ceremonyState.registerCustomState(
  "mymod:glamour_extended",
  CustomParticleData.class
);

This allows custom mods to add additional particle metadata without modifying Glamour.

Developer Notes

Why Ceremony?

Glamour uses Ceremony instead of implementing its own state system because:

1. Battle-Tested: Ceremony is proven in production
2. Cross-Mod Compatible: Other mods can interact with Glamour
3. Robust Persistence: Handles edge cases (trades, PC storage, etc.)
4. Performance: Built-in caching and optimization
5. Maintainability: Don’t reinvent state management

Integration Points

Glamour touches Ceremony at three points:

1. Effect Registration: PokemonEffectRegistry.register()
2. State Read: ceremonyState.get()
3. State Write: ceremonyState.set()

All other Glamour logic is independent.

Ceremony Versioning

Glamour requires Ceremony 3.0.7 or higher.

Compatibility Matrix

Glamour Version	Ceremony Version	Compatible
1.0.x	3.0.7+	✅ Yes
1.0.x	3.0.0-3.0.6	⚠️ Partial
1.0.x	2.x.x	❌ No

Always use the recommended Ceremony version for best results.

Next Steps

• Installation Guide
• Particle Configuration
• Performance Tuning