---
type: Architecture
title: Creeper Fear Plugin Architecture
description: Runtime boundaries, persistence model, and event flow for Creeper Aura progression.
---

# Creeper Fear Plugin Architecture

## Runtime

Creeper Fear targets Java 17 and Spigot API 26.2. The plugin entry point owns listeners, commands, player feedback, configuration, and a progression service.

## Progression model

Each known player is identified by UUID and has:

- a last-known player name for administrative lookup;
- a current rank (`LOCKED`, `I`, `II`, `III`, `IV`, `V`, or `VI`);
- a non-negative number of creeper kills earned within the current tier.

A qualifying kill increments current-tier progress. Unlocking the next rank resets that progress to zero. Rank VI accumulates no further progress. Lifetime kill totals are deliberately not retained.

## Persistence and threading

SQLite stores player progression in the plugin data directory. Gameplay listeners submit persistence work to a dedicated single-thread executor so database latency does not block the Minecraft server thread. Bukkit API state is captured before work leaves the server thread and is not accessed by persistence workers.

Player progress is loaded into an online cache before synchronous aura decisions. Offline administrative operations use the same serialized persistence boundary.

## Event flow

A creeper death is attributed to a player when the player directly dealt the final damage or is attributable through a projectile or owned tameable. The progression service deduplicates a creeper death and records one point.

A self-destructing creeper also awards one point to every player its explosion would have hit. Explosion awards are deduplicated independently for each creeper and player, count before armor or aura mitigation, and use the same feedback as credited kills.

For explosions, player damage events establish whether an unlocked player would have been hit before armor mitigation. Each protected player receives their own rank multiplier. If any aura activates, the corresponding creeper explosion's affected block list is cleared for everyone. Rank VI cancels the player's damage event entirely.

## Commands and configuration

`/creeperaura` exposes player progress and permission-protected offline administration. Rank requirements, multipliers, feedback duration, and messages are loaded from YAML. Valid command-based changes are written back to YAML and survive restart.

## Verification

Domain and persistence behavior is exercised through public interfaces with JUnit. Bukkit-facing adapters remain thin, while build verification ensures their compatibility with Spigot API 26.2.

## Related

- [Design index](index.md)
- [User stories](user-stories/index.md)