DataRegistry

Shared player and service-state storage for HauntedMC across Velocity and Paper.

DataRegistry keeps identity, presence, sessions, rename history, and service-registry data in one place so other plugins can read a consistent view of the network.

What It Does

• Stores player identity by UUID
• Tracks online status and current server
• Records session open and close events
• Optionally stores IP address and virtual host data
• Preserves former usernames in a dedicated history table
• Tracks services, running instances, and backend probe results

Runtime Model

• Velocity is the authoritative writer for joins, switches, disconnects, sessions, connection info, and backend probes.
• Bukkit/Paper runs as a bridge so backend plugins can read the same registry and publish service heartbeats.
• DataProvider is required for connection management and ORM bootstrap.

Running only Bukkit/Paper without Velocity is not a supported deployment mode.

Requirements

• Java 21
• Maven 3.8.6+
• DataProvider 2.0.0
• Velocity 3.5.0-SNAPSHOT and/or Paper 1.21.11-R0.1-SNAPSHOT

Install

Server setup:

1. Install DataProvider.
2. Build or download DataRegistry.jar.
3. Put both jars in the server plugins/ directory.
4. Start the server once to generate plugins/DataRegistry/config.yml.
5. Configure the player and service database profiles to match your DataProvider setup.

If you run backend servers, set platform.bukkit.service-name to the Velocity server name instead of leaving it on auto. That keeps service identity stable across restarts.

Configuration

The config is intentionally small. Most deployments only need to review:

• database.profiles.players.connection-id
• database.profiles.services.connection-id
• orm.schema-mode
• privacy.persist-ip-address
• privacy.persist-virtual-host
• features.*
• service-registry.*
• platform.bukkit.service-name
• platform.velocity.service-name

Defaults and inline comments live in src/main/resources/config.yml. Missing supported keys are restored on load and stale keys are removed.

Dependency Information

Coordinates:

• groupId: nl.hauntedmc.dataregistry
• artifactId: dataregistry
• version: VERSION_HERE

Repository:

• https://maven.pkg.github.com/HauntedMC/DataRegistry

Maven:

<repository>
  <id>github</id>
  <url>https://maven.pkg.github.com/HauntedMC/DataRegistry</url>
</repository>

<dependency>
  <groupId>nl.hauntedmc.dataregistry</groupId>
  <artifactId>dataregistry</artifactId>
  <version>VERSION_HERE</version>
  <scope>provided</scope>
</dependency>

Gradle (Groovy):

compileOnly "nl.hauntedmc.dataregistry:dataregistry:VERSION_HERE"

Use the API

From Bukkit/Paper:

Plugin plugin = Bukkit.getPluginManager().getPlugin("DataRegistry");
if (!(plugin instanceof PlatformPlugin platformPlugin)) {
    throw new IllegalStateException("DataRegistry is unavailable.");
}

DataRegistry registry = platformPlugin.getDataRegistry();
Optional<PlayerEntity> player = registry.getPlayerRepository().findByUUID(uuid);

Primary entry points:

• DataRegistry#getPlayerRepository()
• DataRegistry#getPlayerNameHistoryRepository()
• DataRegistry#getNetworkServiceRepository()
• DataRegistry#getServiceInstanceRepository()
• DataRegistry#getServiceProbeRepository()
• DataRegistry#newServiceRegistryService()

Build

mvn verify expects nl.hauntedmc.dataprovider:dataprovider:2.0.0 to be available locally or via authenticated GitHub Packages access.

For authenticated GitHub Packages access, add a Maven server entry for repository id github in ~/.m2/settings.xml:

<settings>
  <servers>
    <server>
      <id>github</id>
      <username>YOUR_GITHUB_USERNAME</username>
      <password>YOUR_TOKEN</password>
    </server>
  </servers>
</settings>

Use a token with read:packages (and repo if the package source repository is private), then run:

mvn test
mvn verify

Build output:

• target/DataRegistry.jar

Project Info

• Contributing
• Code of Conduct
• Security
• Support

License

This project is licensed under the GNU Affero General Public License v3.0.