PaperMC Despawned Items/io.fairyfox.papermc.despawneditems.location/LocationStore

LocationStore

class LocationStore

In-memory index over every despawn location. Replaces the old flat ArrayList that was copied and linearly scanned on every query and rewritten to disk in full on every change. Provides:

O(1) add, remove, contains and owner/block lookups;
a spatial index (byBlock) — block position → owners at that block;
an owner index (byOwner) — owner → their locations (for limits & bulk ops);
a flat bag with swap-remove for O(1) uniform randomOrNull draw;
dirty-owner tracking so persistence writes only the owners that changed.

Not thread-safe by design: it is mutated only from the server main thread (events and commands). Async persistence takes a snapshot on the main thread first.

Constructors

constructor()

Properties

Total number of stored locations.

Functions

fun add(loc: DespawnLocation): Boolean

Adds loc. Returns false (no-op) if that owner already has that block.

fun all(): List<DespawnLocation>

Immutable snapshot of all locations.

fun at(key: BlockKey): List<DespawnLocation>

Locations registered at key (one per owner).

fun clear()

Removes everything. Every previously-known owner is marked dirty so files are rewritten.

fun clearDirty(owners: Collection<UUID>): Boolean

fun contains(loc: DespawnLocation): Boolean

fun countOfOwner(owner: UUID): Int

How many locations owner has (used for per-user limits).

dirtyOwnersSnapshot

fun dirtyOwnersSnapshot(): Set<UUID>

Owners whose data changed since the last clearDirty.

fun isEmpty(): Boolean

fun knownOwners(): Set<UUID>

Owners that currently have at least one location (for full flush / file cleanup).

fun markAllDirty(): Boolean

fun ofOwner(owner: UUID): Set<DespawnLocation>

All locations owned by owner.

fun ownersAt(key: BlockKey): Set<UUID>

Owners registered at key.

fun randomOrNull(): DespawnLocation?

A uniformly random location (with replacement), or null if empty.

fun remove(loc: DespawnLocation): Boolean

Removes loc. Returns false if it was not present.

fun removeAt(key: BlockKey): Int

Removes every location at key regardless of owner; returns how many.

fun removeOwner(owner: UUID): Int

Removes every location owned by owner; returns how many were removed.

fun replaceAll(locations: Collection<DespawnLocation>)

Replaces all contents with locations without marking anything dirty (used on load).