Plasmo Voice

Appearance

On this page

WARNING

The API documentation is a work in progress and is based on 2.1.0-SNAPSHOT.

Setting up dependency ​

There are four different API modules:

  • server — for server addons (Fabric/Forge/Spigot)
  • proxy — for proxy addons (BungeeCord/Velocity)
  • client — for client addons (Fabric/Forge)
  • server-common — for universal addons, shared module for server and proxy

Most of the examples below use the server module.

Build system ​

Version

kotlin
repositories {
    maven("https://repo.plasmoverse.com/releases")
    maven("https://repo.plasmoverse.com/snapshots")
}

dependencies {
    compileOnly("su.plo.voice.api:${api_module}:${version}")
}
groovy
repositories {
    maven {
        name = 'plasmoverse-releases'
        url = 'https://repo.plasmoverse.com/releases'
    }
    maven {
        name = 'plasmoverse-snapshots'
        url = 'https://repo.plasmoverse.com/snapshots'
    }
}

dependencies {
    compileOnly 'su.plo.voice.api:${api_module}:${version}'
}
xml
<project>
    <repositories>
        <repository>
            <id>plasmoverse-releases</id>
            <url>https://repo.plasmoverse.com/releases</url>
        </repository>
        <repository>
            <id>plasmoverse-snapshots</id>
            <url>https://repo.plasmoverse.com/snapshots</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>su.plo.voice.api</groupId>
            <artifactId>${api_module}</artifactId>
            <version>${version}</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

Kotlin ​

If you're using Kotlin, you may prefer using the Kotlin bundled with Plasmo Voice, eliminating the need for you to bundle it yourself.

To utilize the bundled Kotlin in Plasmo Voice, you simply need to relocate the Kotlin classes in your project:

kotlin
plugins {
    kotlin("jvm") version "1.8.20"
    id("com.github.johnrengelman.shadow") version("7.1.0")
}

tasks.shadowJar {
    relocate("kotlin", "su.plo.voice.libs.kotlin")
    relocate("kotlinx.coroutines", "su.plo.voice.libs.kotlinx.coroutines")
    relocate("kotlinx.serialization", "su.plo.voice.libs.kotlinx.serialization")
}
xml
<project>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.5.1</version>
                <executions>
                    <execution>
                        <id>shade</id>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <relocations>
                        <relocation>
                            <pattern>kotlin</pattern>
                            <shadedPattern>su.plo.voice.libs.kotlin</shadedPattern>
                        </relocation>
                        <relocation>
                            <pattern>kotlinx.coroutines</pattern>
                            <shadedPattern>su.plo.voice.libs.kotlinx.coroutines</shadedPattern>
                        </relocation>
                        <relocation>
                            <pattern>kotlinx.serialization</pattern>
                            <shadedPattern>su.plo.voice.libs.kotlinx.serialization</shadedPattern>
                        </relocation>
                    </relocations>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Alternatively, you can use a Plasmo Voice Gradle plugin for this:

Version

kotlin
pluginManagement {
    repositories {
        maven("https://repo.plasmoverse.com/snapshots")
    }
}
kotlin
plugins {
    id("su.plo.voice.plugin.relocate-kotlin") version "${version}"
}

Optional platform modules ​

You can also use platform modules to view sources of the Plasmo Voice in your IDE.

They also contain some Kotlin extensions. Extensions can be found at su.plo.voice.$PLATFORM.extension.

Available modules:

  • su.plo.voice.server:paper — Spigot/Paper/etc
  • su.plo.voice.proxy:bungee — BungeeCord
  • su.plo.voice.proxy:velocity — Velocity
  • su.plo.voice:protocol — Module with TCP/UDP packets used in Plasmo Voice

Creating an addon ​

To use the Plasmo Voice API, you need to create an addon.

To create an addon, you need to annotate class with @Addon and optionally implement AddonInitializer interface.

An addon id must start with a lowercase letter and may contain only lowercase letters, digits, hyphens, and underscores. It should be between 4 and 32 characters long. It's also preferred to the add prefix pv-addon- to your addon, but it is not mandatory.

To access the API, you need to inject PlasmoVoiceServer using @InjectPlasmoVoice. Alternatively, if you're using kotlin, you can use injectPlasmoVoice delegate.

The PlasmoVoiceServer will be injected right before invoking onAddonInitialize.

java
package com.plasmovoice.testaddon;

import su.plo.voice.api.addon.AddonInitializer;
import su.plo.voice.api.addon.InjectPlasmoVoice;
import su.plo.voice.api.addon.annotation.Addon;
import su.plo.voice.api.server.PlasmoVoiceServer;

@Addon(
        // An addon id must start with a lowercase letter and may contain only lowercase letters, digits, hyphens, and underscores.
        // It should be between 4 and 32 characters long.
        id = "pv-addon-test",
        name = "Test Addon",
        version = "1.0.0",
        authors = {"Plasmo"}
)
public final class TestAddon implements AddonInitializer {

    @InjectPlasmoVoice
    private PlasmoVoiceServer voiceServer;

    @Override
    public void onAddonInitialize() {
        // voiceServer is initialized now

        System.out.println("Addon initialized");
    }

    @Override
    public void onAddonShutdown() {
        System.out.println("Addon shut down");
    }
}
kotlin
package com.plasmovoice.testaddon

import su.plo.voice.api.addon.AddonInitializer
import su.plo.voice.api.addon.annotation.Addon
import su.plo.voice.api.addon.injectPlasmoVoice
import su.plo.voice.api.server.PlasmoVoiceServer

@Addon(
        // An addon id must start with a lowercase letter and may contain only lowercase letters, digits, hyphens, and underscores.
        // It should be between 4 and 32 characters long.
        id = "pv-addon-helloworld",
        name = "Hello World Add-on",
        version = "1.0.0",
        authors = ["Plasmo"]
)
class TestAddon : AddonInitializer {

    private val voiceServer: PlasmoVoiceServer by injectPlasmoVoice()
    // or
    // @InjectPlasmoVoice
    // private lateinit var voiceServer: PlasmoVoiceServer

    override fun onAddonInitialize() {
        // voiceServer is initialized now

        println("Addon initialized")
    }

    override fun onAddonShutdown() {
        println("Addon shut down")
    }
}

After creating an addon, you need to load it.

Loading an addon ​

On different platforms, you need to load it different ways. See below how to do it on the platform you're using.

Spigot ​

Add PlasmoVoice to your plugin.yml dependencies:

yaml
# ...
depend:
  - PlasmoVoice

To load a Plasmo Voice addon in Spigot/Paper, you need to load it via server addons loader in JavaPlugin's onLoad:

java
package com.plasmovoice.bukkitplugin;

import su.plo.voice.api.server.PlasmoVoiceServer;

import org.bukkit.plugin.java.JavaPlugin;

public final class BukkitPlugin extends JavaPlugin {

    // Addon class annotated with @Addon.
    private final TestAddon addon = new TestAddon();

    @Override
    public void onLoad() {
        PlasmoVoiceServer.getAddonsLoader().load(addon);
    }
}
kotlin
package com.plasmovoice.bukkitplugin

import su.plo.voice.api.server.PlasmoVoiceServer

import org.bukkit.plugin.java.JavaPlugin

class BukkitPlugin : JavaPlugin() {

    // Addon class annotated with @Addon.
    private val addon = TestAddon()

    override fun onLoad() {
        PlasmoVoiceServer.getAddonsLoader().load(addon)
    }
}

Fabric ​

Add plasmovoice to your fabric.mod.json dependencies:

json
{
    "depends": {
        "plasmovoice": ">=${version}"
    }
}

To load a Plasmo Voice addon in Fabric, you need to load it via server addons loader in ModInitializer's onInitialize:

java
package com.plasmovoice.fabricmod;

import su.plo.voice.api.server.PlasmoVoiceServer;

import net.fabricmc.api.ModInitializer;

public final class FabricMod implements ModInitializer {

    // Addon class annotated with @Addon.
    private final TestAddon addon = new TestAddon();

    @Override
    public void onInitialize() {
        PlasmoVoiceServer.getAddonsLoader().load(addon);
    }
}
kotlin
package com.plasmovoice.fabricmod

import su.plo.voice.api.server.PlasmoVoiceServer

import net.fabricmc.api.ModInitializer

class FabricMod : ModInitializer {

    // Addon class annotated with @Addon.
    private val addon = TestAddon()

    override fun onInitialize() {
        PlasmoVoiceServer.getAddonsLoader().load(addon)
    }
}

Forge ​

Add plasmovoice to your mods.toml dependencies:

toml
# ...
[[dependencies.forgemod]]
modId = "plasmovoice"
versionRange = "[${version},)"
ordering = "AFTER"
mandatory = true

To load a Plasmo Voice addon in Forge, you need to load it via the server addons loader in mod class constructor:

java
package com.plasmovoice.forgemod;

import su.plo.voice.api.server.PlasmoVoiceServer;

import net.minecraftforge.fml.common.Mod;

@Mod("forgemod")
public final class ForgeMod {

    // Addon class annotated with @Addon.
    private final TestAddon addon = new TestAddon();

    public ForgeMod() {
        PlasmoVoiceServer.getAddonsLoader().load(addon);
    }
}
kotlin
package com.plasmovoice.forgemod

import su.plo.voice.api.server.PlasmoVoiceServer

import net.minecraftforge.fml.common.Mod

@Mod("forgemod")
class ForgeMod {

    // Addon class annotated with @Addon.
    private val addon = TestAddon()

    init {
        PlasmoVoiceServer.getAddonsLoader().load(addon)
    }
}

BungeeCord ​

Add PlasmoVoice to your plugin.yml dependencies:

yaml
# ...
depends:
  - PlasmoVoice

To load a Plasmo Voice addon in BungeeCord, you need to load it via proxy addons loader in Plugin's onLoad:

java
package com.plasmovoice.bungeeplugin;

import su.plo.voice.api.proxy.PlasmoVoiceProxy;

import net.md_5.bungee.api.plugin.Plugin;

public final class BungeePlugin extends Plugin {

    // Addon class annotated with @Addon.
    private final TestAddon addon = new TestAddon();

    @Override
    public void onLoad() {
        PlasmoVoiceProxy.getAddonsLoader().load(addon);
    }
}
kotlin
package com.plasmovoice.bungeeplugin

import su.plo.voice.api.proxy.PlasmoVoiceProxy

import net.md_5.bungee.api.plugin.Plugin

class BungeePlugin : Plugin() {

    // Addon class annotated with @Addon.
    private val addon = TestAddon()

    override fun onLoad() {
        PlasmoVoiceProxy.getAddonsLoader().load(addon)
    }
}

Velocity ​

To load a Plasmo Voice addon in Velocity, you need to load it via proxy addons loader in ProxyInitializeEvent:

java
package com.plasmovoice.velocityplugin;

import su.plo.voice.api.proxy.PlasmoVoiceProxy;

import com.velocitypowered.api.event.Subscribe;
import com.velocitypowered.api.event.proxy.ProxyInitializeEvent;
import com.velocitypowered.api.plugin.Plugin;

@Plugin(
        id = "velocityplugin",
        name = "VelocityPlugin",
        version = "1.0.0",
        authors = {"Plasmo"},
        dependencies = {
                @Dependency(id = "plasmovoice")
        }
)
public final class VelocityPlugin {

    // Addon class annotated with @Addon.
    private final TestAddon addon = new TestAddon();

    @Subscribe
    public void onProxyInitialization(ProxyInitializeEvent event) {
        PlasmoVoiceProxy.getAddonsLoader().load(addon);
    }
}
kotlin
package com.plasmovoice.velocityplugin

import su.plo.voice.api.proxy.PlasmoVoiceProxy

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

@Plugin(
    id = "velocityplugin",
    name = "VelocityPlugin",
    version = "1.0.0",
    authors = ["Plasmo"],
    dependencies = [Dependency(id = "plasmovoice")]
)
class VelocityPlugin {

    // Addon class annotated with @Addon.
    private val addon = TestAddon()

    @Subscribe
    fun onProxyInitialization(event: ProxyInitializeEvent) {
        PlasmoVoiceProxy.getAddonsLoader().load(addon)
    }
}