Consuming the API

This page explains the supported ways to consume Socialismus from your own code.

There are two main integration paths:

• addon plugins that run alongside Socialismus and depend on the published base API
• Socialismus modules that are loaded through Socialismus itself and depend on the module API

Coordinates

Socialismus currently publishes two main API artifacts:

• addon/plugin API
  • group: me.whereareiam.socialismus
  • artifact: api
• module API
  • group: me.whereareiam.socialismus.module
  • artifact: api

For both addon plugins and modules, compileOnly or the equivalent provided-scope dependency is usually the right choice. Socialismus provides these APIs at runtime, so you should not shade or relocate them into your own jar.

Repositories

Socialismus publishes API artifacts to these Maven repositories:

• release repository: https://maven.whereareiam.me/release
• development repository: https://maven.whereareiam.me/development

Adding the dependency

repositories {
    maven("https://maven.whereareiam.me/release")
}

dependencies {
    compileOnly("me.whereareiam.socialismus:api:<version>")
}

repositories {
    maven { url = uri("https://maven.whereareiam.me/release") }
}

dependencies {
    compileOnly "me.whereareiam.socialismus:api:<version>"
}

<repositories>
  <repository>
    <id>socialismus-release</id>
    <url>https://maven.whereareiam.me/release</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>me.whereareiam.socialismus</groupId>
    <artifactId>api</artifactId>
    <version>&lt;version&gt;</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

If you intentionally target development builds instead of releases, switch the repository URL to the development repository and use the matching development version.

Versioning semantics

Socialismus currently publishes two main version streams:

• release versions such as 1.0.0
• development versions such as dev-91e1b65

In practice:

• release versions are published to the release repository from GitHub release tags
• development versions are published to the development repository from branch builds
• development versions usually use <branch>-<short-commit-sha>, so the dev branch produces versions like dev-91e1b65

If you are writing a normal addon plugin or module for production, prefer release versions. Use development versions only when you intentionally depend on unreleased changes.

Javadocs

Use these links to browse the generated API documentation for the latest published release and latest published development build:

• Socialismus API latest release: unavailable
• Socialismus API latest development build: dev-bcd43a8
• Socialismus module API latest release: unavailable
• Socialismus module API latest development build: dev-bcd43a8

Declaring a dependency on Socialismus

Even when you only use the published API, your plugin should still declare that it depends on Socialismus if the integration is required at runtime.

import com.velocitypowered.api.plugin.Dependency;
import com.velocitypowered.api.plugin.Plugin;

@Plugin(
    id = "example-socialismus-addon",
    name = "ExampleSocialismusAddon",
    version = "1.0.0",
    dependencies = {
        @Dependency(id = "socialismus")
    }
)
public final class ExampleSocialismusAddon {
}

If your Socialismus integration is optional, use an optional dependency instead and guard your code accordingly.

Initialization and lifecycle

Do not assume the API is ready the moment your addon plugin class is loaded.

The main rules are:

• check SocialismusAPI.isInitialized() before accessing services directly
• or wait until Socialismus has finished bootstrapping and then resolve services

The API entry point is SocialismusAPI. That class exposes both generic getService(...) access and convenience methods for common services.

Platform startup and lifecycle integration depend on the platform your addon targets.

import com.google.inject.Inject;
import com.velocitypowered.api.event.Subscribe;
import com.velocitypowered.api.event.proxy.ProxyInitializeEvent;
import com.velocitypowered.api.plugin.Dependency;
import com.velocitypowered.api.plugin.Plugin;
import me.whereareiam.socialismus.SocialismusAPI;

@Plugin(
    id = "example-socialismus-addon",
    name = "ExampleSocialismusAddon",
    version = "1.0.0",
    dependencies = {
        @Dependency(id = "socialismus")
    }
)
public final class ExampleSocialismusAddon {
    @Inject
    public ExampleSocialismusAddon() {
    }

    @Subscribe
    public void onProxyInitialization(ProxyInitializeEvent event) {
        if (!SocialismusAPI.isInitialized()) {
            return;
        }

        // Safe place to resolve Socialismus services
        SocialismusAPI.getPlayerRegistry();
    }
}

Basic service usage example

import me.whereareiam.socialismus.SocialismusAPI;
import me.whereareiam.socialismus.service.container.ChatContainerService;

public final class ExampleAddon {
    public void printChats() {
        if (!SocialismusAPI.isInitialized()) {
            return;
        }

        ChatContainerService chatContainerService = SocialismusAPI.getChatContainerService();
        chatContainerService.getChats().forEach(chat ->
            System.out.println(chat.getId())
        );
    }
}

Resolving services generically

If there is no convenience method for the service you want, use getService(...).

import me.whereareiam.socialismus.SocialismusAPI;
import me.whereareiam.socialismus.registry.PlayerRegistry;

public final class ExampleAddon {
    public PlayerRegistry playerRegistry() {
        return SocialismusAPI.getService(PlayerRegistry.class);
    }
}

Common services worth using

These are some of the most useful API entry points for addon plugins and modules:

• SocialismusAPI.getPlayerRegistry() for reading and updating tracked SocialismusPlayer data
• SocialismusAPI.getChatContainerService() for listing and inspecting loaded chats
• SocialismusAPI.getChatCoordinationService() for entering the message coordination pipeline
• SocialismusAPI.getChatHistoryService() for removing tracked chat history entries
• SocialismusAPI.getChatRenderService() for rendering a formatted message for a recipient
• SocialismusAPI.getCommandService() for registering or inspecting Socialismus commands
• SocialismusAPI.getModuleService() if you intentionally integrate with the Socialismus module system
• SocialismusAPI.getEventManager() for registering or calling Socialismus events

Player lookup example

import me.whereareiam.socialismus.SocialismusAPI;
import me.whereareiam.socialismus.registry.PlayerRegistry;

import java.util.UUID;

public final class ExampleAddon {
    public void printPlayer(UUID uniqueId) {
        if (!SocialismusAPI.isInitialized()) {
            return;
        }

        PlayerRegistry playerRegistry = SocialismusAPI.getPlayerRegistry();
        playerRegistry.getPlayerData(uniqueId).ifPresent(player ->
            System.out.println(player.getUsername() + " -> " + player.getUniqueId())
        );
    }
}