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

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

LocationStore

constructor()

Properties

size

val size: Int

Total number of stored locations.

Functions

add

fun add(loc: DespawnLocation): Boolean

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

all

fun all(): List<DespawnLocation>

Immutable snapshot of all locations.

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

Locations registered at key (one per owner).

clear

fun clear()

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

clearDirty

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

contains

fun contains(loc: DespawnLocation): Boolean

countOfOwner

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.

enabledCount

fun enabledCount(): Int

How many locations are switched on (the pipeline ignores the rest).

isEmpty

fun isEmpty(): Boolean

knownOwners

fun knownOwners(): Set<UUID>

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

markAllDirty

fun markAllDirty(): Boolean

ofOwner

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

All locations owned by owner.

ownersAt

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

Owners registered at key.

randomEnabledOrNull

fun randomEnabledOrNull(): DespawnLocation?

A random enabled location, weighted by TargetOptions.priority.

randomOrNull

fun randomOrNull(): DespawnLocation?

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

remove

fun remove(loc: DespawnLocation): Boolean

Removes loc. Returns false if it was not present.

removeAt

fun removeAt(key: BlockKey): Int

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

removeOwner

fun removeOwner(owner: UUID): Int

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

replaceAll

fun replaceAll(locations: Collection<DespawnLocation>)

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

update

fun update(loc: DespawnLocation): Boolean

Replaces the stored entry with the same block+owner as loc by loc itself (used to change a target's TargetOptions). Returns false when there is nothing to update or nothing would change.