Plasmo Voice

https://plasmovoice.com/docs
Admin
Plasmo Voice is a voice communication plugin for Minecraft servers that enables addon development...
Tokens:31,379
Snippets:282
Trust Score:6.3
Update:3 days ago
Show doc for...
Tokens:
Raw
### Java implementation of CustomFrameProvider with AudioFrameProvider

Source: https://plasmovoice.com/docs/api/sources.html

Java example showing how to create a custom audio frame provider. It creates an AudioSender with the provider and distance, starts it, and removes the source on stop. The provider returns EndOfStream, Finished, or Provided frames from provide20ms.

```java
package com.plasmovoice.testaddon;

import su.plo.voice.api.server.PlasmoVoiceServer;
import su.plo.voice.api.server.audio.provider.AudioFrameProvider;
import su.plo.voice.api.server.audio.provider.AudioFrameResult;
import su.plo.voice.api.server.audio.source.AudioSender;
import su.plo.voice.api.server.audio.source.ServerPlayerSource;

public final class CustomFrameProvider {

    /**
     * Sends the audio samples to an audio source in specified distance.
     *
     * @param source The audio source to send audio.
     * @param distance The distance to send audio.
     */
    private void createCustomFrameProvider(
            ServerPlayerSource source,
            short distance
    ) {
        TestAudioFrameProvider frameProvider = new TestAudioFrameProvider();

        AudioSender audioSender = source.createAudioSender(frameProvider, distance);
        // or
        // AudioSender audioSender = source.createAudioSender(frameProvider);
        // if you are using direct or broadcast source

        audioSender.start();
        audioSender.onStop(() -> {
            // you also need to remove the source from the source line
            // if you don't need it after the audio was sent
            source.remove();
        });
    }

    public class TestAudioFrameProvider implements AudioFrameProvider {

        @Override
        public AudioFrameResult provide20ms() {
            if (/* end of the audio stream*/) {
                // [EndOfStream] means that [AudioFrameProvider] reaches the end of the current stream,
                // but not completely closed and frames could be sent later
                return AudioFrameResult.EndOfStream.INSTANCE;
            } else if (/* audio stream finished */) {
                // [Finished] means that [AudioFrameProvider] is completely closed and will not return any frames
                return AudioFrameResult.Finished.INSTANCE;
            }

            // null frame means that frame is not ready yet
            // return new AudioFrameResult.Provided(null);

            byte[] encryptedFrame = new byte[100];
            return new AudioFrameResult.Provided(encryptedFrame);
        }
    }
}
```

--------------------------------

### Kotlin implementation of CustomFrameProvider with AudioFrameProvider

Source: https://plasmovoice.com/docs/api/sources.html

Kotlin example showing how to create a custom audio frame provider. It creates an AudioSender with the provider and distance, starts it, and removes the source on stop. The provider returns EndOfStream, Finished, or Provided frames from provide20ms.

```kotlin
package com.plasmovoice.testaddon

import su.plo.voice.api.server.audio.provider.AudioFrameProvider
import su.plo.voice.api.server.audio.provider.AudioFrameResult
import su.plo.voice.api.server.audio.provider.AudioFrameResult.Provided
import su.plo.voice.api.server.audio.source.ServerPlayerSource

class CustomFrameProvider {

    /**
     * Sends the audio samples to an audio source in specified distance.
     *
     * @param source The audio source to send audio.
     * @param distance The distance to send audio.
     */
    private fun createCustomFrameProvider(
        source: ServerPlayerSource,
        distance: Short
    ) {
        val frameProvider = TestAudioFrameProvider()

        val audioSender = source.createAudioSender(frameProvider, distance)
        // or
        // AudioSender audioSender = source.createAudioSender(frameProvider);
        // if you are using direct or broadcast source

        audioSender.start()

        audioSender.onStop {
            // you also need to remove the source from the source line
            // if you don't need it after the audio was sent
            source.remove()
        }
    }

    inner class TestAudioFrameProvider : AudioFrameProvider {

        override fun provide20ms(): AudioFrameResult {
            if (/* end of the audio stream*/) {
                // [EndOfStream] means that [AudioFrameProvider] reaches the end of the current stream,
                // but not completely closed and frames could be sent later
                return AudioFrameResult.EndOfStream
            } else if (/* audio stream finished */) {
                // [Finished] means that [AudioFrameProvider] is completely closed and will not return any frames
                return AudioFrameResult.Finished
            }

            // null frame means that frame is not ready yet
            // return Provided(null);

            val encryptedFrame = ByteArray(100)
            return Provided(encryptedFrame)
        }
    }
}
```

--------------------------------

### onPlayerActivationStart

Source: https://plasmovoice.com/docs/api/activations.html

Registers a listener that is invoked when a player starts to speak to the activation.

```APIDOC
## onPlayerActivationStart

### Description
Registers a listener that is invoked when a player starts to speak to the activation.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
#### Listener Parameters
- **player** - The player who started speaking.

### Return Value
- None

### Example (Java)
```java
ServerActivation activation = /* */;

activation.onPlayerActivationStart(player -> {
    System.out.println(player + " start speaking to activation");
});
```

### Example (Kotlin)
```kotlin
val activation: ServerActivation = /* */;

activation.onPlayerActivationStart { player ->
    println("$player start speaking to activation")
}
```
```

--------------------------------

### Example server.properties with server-port

Source: https://plasmovoice.com/docs/server/advanced

Shows a server.properties file with server-port set to 25565. This is used to illustrate how the default config resolves the voice server port when port is 0.

```properties
server-port=25565

```

--------------------------------

### Configure Public IP and Port on Backend Server

Source: https://plasmovoice.com/docs/server/proxy

Example configuration for the Plasmo Voice server-side plugin when the proxy and server are on different nodes, requiring a specific public IP and port.

```toml
[host]
ip = "0.0.0.0"
port = 0

[host.public]
ip = "222.2.222.222" # IP of the Server
port = 2000 # Port of the Server
```

--------------------------------

### Registering an event handler as a method in Java

Source: https://plasmovoice.com/docs/api/events.html

This example shows how to register a method as an event handler for UdpClientConnectEvent using the Plasmo Voice event bus in Java.

```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.event.EventPriority;
import su.plo.voice.api.server.PlasmoVoiceServer;
import su.plo.voice.api.server.event.connection.UdpClientConnectEvent;

@Addon(
        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.getEventBus().register(
                this,
                UdpClientConnectEvent.class,
                EventPriority.NORMAL,
                this::onClientConnected
        );
    }

    private void onClientConnected(UdpClientConnectEvent event) {
        System.out.println(
                event.getConnection().getPlayer() + " connected to UDP"
        );
    }
}
```

--------------------------------

### Load an addon (Kotlin)

Source: https://plasmovoice.com/docs/server/minestom

Load an addon after the voice server has been initialized.

```kotlin
import su.plo.voice.spectator.SpectatorAddon

// ... on server startup
voiceServer.onInitialize()
// ... after voice server initialization
PlasmoVoiceServer.getAddonsLoader().load(SpectatorAddon())
```

--------------------------------

### Load an addon (Java)

Source: https://plasmovoice.com/docs/server/minestom

Load an addon after the voice server has been initialized.

```java
import su.plo.voice.spectator.SpectatorAddon;

// ... on server startup
voiceServer.onInitialize();
// ... after voice server initialization
PlasmoVoiceServer.getAddonsLoader().load(new SpectatorAddon());
```

--------------------------------

### Configure Build System with Gradle

Source: https://plasmovoice.com/docs/api

Add the relocation plugin to your build.gradle file to manage dependencies.

```kotlin
plugins {
    id("su.plo.voice.plugin.relocate-kotlin") version "${version}"
}
```

--------------------------------

### Create check_voice.js script

Source: https://plasmovoice.com/docs/server/papi

Javascript code to create a custom placeholder that displays a green or red icon based on whether Plasmo Voice is installed.

```javascript
var placeholder = "%plasmovoice_installed%";
var voice = PlaceholderAPI.static.setPlaceholders(BukkitPlayer, placeholder);

var checkVoice = function (voice) {
  return voice === "true" ? " &a●&f | " : " &c●&f | ";
};

checkVoice(voice);
```

--------------------------------

### ServerActivation.Builder#build

Source: https://plasmovoice.com/docs/api/activations.html

Registers a new activation with the specified name, translation key, icon resource location, permission, and weight. The activation is dynamically synced with players and permissions.

```APIDOC
## ServerActivation.Builder#build

### Description
Registers a new activation with the specified name, translation key, icon resource location, permission, and weight. The activation is dynamically synced with players and permissions.

### Method
Builder method

### Parameters
#### Builder Parameters
- **addon** (Object) - Required - The addon instance created via Creating an addon.
- **name** (String) - Required - The activation name.
- **translationKey** (String) - Required - The translation key for the activation.
- **icon** (ResourceLocation or InputStream) - Required - The icon resource location or an InputStream for the icon.
- **permission** (String) - Required - The permission required for the activation.
- **weight** (int) - Required - The weight determining the activation's position in the list (lower weight means higher place).

### Request Example
```java
PlasmoVoiceServer voiceServer = /* */;
Object addon = /* */;

ServerActivation activation = voiceServer.getActivationManager().createBuilder(
    addon,
    "priority", // name
    "pv.activation.priority", // translation key
    "plasmovoice:textures/icons/microphone_priority.png", // icon resource location
    "pv.activation.priority", // permission
    10 // weight
).build();
```

### Response
#### Success Response
Returns a ServerActivation object representing the registered activation.

### Notes
- Activations are dynamically synced with players; registering or unregistering at any time is supported.
- When a player loses or gains the activation permission, the activation is removed or added to the client respectively.
- See ServerActivation.Builder for all available builder options.
```

--------------------------------

### Registering an event handler as a method in Kotlin

Source: https://plasmovoice.com/docs/api/events.html

This example shows how to register a method as an event handler for UdpClientConnectEvent using the Plasmo Voice event bus in Kotlin.

```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.event.EventPriority
import su.plo.voice.api.server.PlasmoVoiceServer
import su.plo.voice.api.server.event.connection.UdpClientConnectEvent

@Addon(
    id = "pv-addon-test",
    name = "Test Addon",
    version = "1.0.0",
    authors = ["Plasmo"]
)
class TestAddon : AddonInitializer {

    private val voiceServer: PlasmoVoiceServer by injectPlasmoVoice()

    override fun onAddonInitialize() {
        voiceServer.eventBus.register(
            this,
            UdpClientConnectEvent::class.java,
            EventPriority.NORMAL,
            ::onClientConnected
        )
    }

    private fun onClientConnected(event: UdpClientConnectEvent) {
        println("${event.connection.player} connected to UDP")
    }
}
```

--------------------------------

### Create language file structure

Source: https://plasmovoice.com/docs/api/languages.html

Shows the required folder structure for storing language files and the list file.

```text
- resources
  - test
    - en_us.toml
    - list

```

--------------------------------

### Create a Player Source in Java

Source: https://plasmovoice.com/docs/api/sources.html

Attaches a source to a specific player.

```java
PlasmoVoiceServer voiceServer = /* */;\n\nServerSourceLine sourceLine = voiceServer.getSourceLineManager()\n        .getLineByName("proximity")\n        .orElseThrow(() -> new IllegalStateException("Proximity source line not found"));\n\nVoiceServerPlayer voicePlayer = voiceServer.getPlayerManager()\n        .getPlayerByName("Apehum")\n        .orElseThrow(() -> new IllegalStateException("Player not found"));\n\nServerPlayerSource source = sourceLine.createPlayerSource(voicePlayer, false);
```

--------------------------------

### ServerSourceLine#createBroadcastSource

Source: https://plasmovoice.com/docs/api/sources.html

Creates a broadcast source attached to a group of players. By default, the group is not set, meaning all players with Plasmo Voice installed will hear the audio. Use ServerBroadcastSource#setPlayers to change the group.

```APIDOC
## ServerSourceLine#createBroadcastSource

### Description
Creates a broadcast source attached to a group of players. By default, the group is not set, meaning all players with Plasmo Voice installed will hear the audio. Use ServerBroadcastSource#setPlayers to change the group.

### Method
createBroadcastSource

### Parameters
- **permanent** (boolean) - Required - Whether the source is permanent.

### Returns
ServerBroadcastSource - The created broadcast source.

### Example (Java)
```java
PlasmoVoiceServer voiceServer = /* */;

ServerSourceLine sourceLine = voiceServer.getSourceLineManager()
        .getLineByName("proximity")
        .orElseThrow(() -> new IllegalStateException("Proximity source line not found"));

ServerBroadcastSource source = sourceLine.createBroadcastSource(false);

// Set "listeners" for broadcast source
VoicePlayer player = voiceServer.getPlayerManager()
    .getPlayerByName("Apehum")
    .orElseThrow(() -> new IllegalStateException("Player not found"));
Set<VoicePlayer> players = new HashSet<>();
players.add(player);
source.setPlayers(players);
```

### Example (Kotlin)
```kotlin
val voiceServer: PlasmoVoiceServer

val sourceLine = voiceServer.sourceLineManager
    .getLineByName("proximity")
    .orElseThrow { IllegalStateException("Proximity source line not found") }

val source = sourceLine.createBroadcastSource(false)

val player = voiceServer.playerManager
    .getPlayerByName("Apehum")
    .orElseThrow { IllegalStateException("Player not found") }

val players: MutableSet<VoicePlayer> = HashSet()
players.add(player)
source.players = players
```
```

--------------------------------

### Create an Addon in Java

Source: https://plasmovoice.com/docs/api

Implement the AddonInitializer interface and use @InjectPlasmoVoice to access the server API.

```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");
    }
}
```

--------------------------------

### Create a Player Source in Kotlin

Source: https://plasmovoice.com/docs/api/sources.html

Attaches a source to a specific player.

```kotlin
val voiceServer: PlasmoVoiceServer\n\nval sourceLine = voiceServer.sourceLineManager\n    .getLineByName("proximity")\n    .orElseThrow { IllegalStateException("proximity source line not found") }\n\nval voicePlayer = voiceServer.playerManager\n    .getPlayerByName("Apehum")\n    .orElseThrow { IllegalStateException("player not found") }\n\nval source = sourceLine.createPlayerSource(voicePlayer, false)
```

--------------------------------

### Equivalent Default Config with Resolved IP and Port

Source: https://plasmovoice.com/docs/server/advanced

Shows the effective config when the node IP is 111.1.111.111 and server-port is 25565. The bind IP is set to the node IP and the port to 25565.

```toml
[host]
ip = "111.1.111.111"
port = 25565

```

--------------------------------

### ServerSourceLine.Builder#withPlayers

Source: https://plasmovoice.com/docs/api/source-lines.html

Enables the players overlay feature for the source line. After building, the player set manager becomes accessible.

```APIDOC
## ServerSourceLine.Builder#withPlayers

### Description
Enables the players overlay feature for the source line. After building, the player set manager becomes accessible.

### Method
Builder method

### Parameters
- **enabled** (boolean) - Required - Set to true to enable the players feature.

### Request Example
```java
PlasmoVoiceServer voiceServer = /* */;

ServerSourceLine sourceLine = voiceServer.getSourceLineManager()
        .createBuilder(/*...*/)
        .withPlayers(true)
        .build();
```

### Response
Returns the builder instance for chaining.

```

--------------------------------

### ServerSourceLine.Builder#build

Source: https://plasmovoice.com/docs/api/source-lines.html

Creates a new source line with the specified name, translation key, icon, and weight. The builder is obtained from the source line manager.

```APIDOC
## ServerSourceLine.Builder#build

### Description
Creates a new source line with the specified name, translation key, icon, and weight.

### Method
Builder method

### Parameters
- **addon** (Object) - Required - The addon instance.
- **name** (String) - Required - The name of the source line.
- **translationKey** (String) - Required - The translation key for the source line.
- **iconResourceLocation** (String) - Required - The resource location of the icon.
- **weight** (int) - Required - The weight of the source line (lower weight means higher place).

### Request Example
```java
PlasmoVoiceServer voiceServer = /* */;
Object addon = /* */;

ServerSourceLine sourceLine = voiceServer.getSourceLineManager().createBuilder(
    addon,
    "priority", // name
    "pv.activation.priority", // translation key
    "plasmovoice:textures/icons/speaker_priority.png", // icon resource location
    10 // weight
).build();
```

### Response
Returns a ServerSourceLine object.

```

--------------------------------

### Initialize voice server (Kotlin)

Source: https://plasmovoice.com/docs/server/minestom

Initialize and shut down the MinestomVoiceServer during server lifecycle events.

```kotlin
// ... on server startup
val voiceConfigDirectory = File("plasmovoice")
val voiceServer = MinestomVoiceServer(voiceConfigDirectory)
voiceServer.onInitialize()

// ... on server shutdown
voiceServer.onShutdown()
```

--------------------------------

### Create a direct source in Java

Source: https://plasmovoice.com/docs/api/sources.html

Creates a ServerDirectSource for a specific player using the 'proximity' source line. The source is not spatial (false). Use BaseServerDirectSource#setSender to set the sender displayed in the player overlay.

```java
PlasmoVoiceServer voiceServer = /* */;

ServerSourceLine sourceLine = voiceServer.getSourceLineManager()
        .getLineByName("proximity")
        .orElseThrow(() -> new IllegalStateException("Proximity source line not found"));

VoicePlayer voicePlayer = voiceServer.getPlayerManager()
        .getPlayerByName("Apehum")
        .orElseThrow(() -> new IllegalStateException("Player not found"));

ServerDirectSource source = sourceLine.createDirectSource(voicePlayer, false);
```

--------------------------------

### Create an Addon in Kotlin

Source: https://plasmovoice.com/docs/api

Implement the AddonInitializer interface and use @InjectPlasmoVoice to access the server API.

```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 {

    @InjectPlasmoVoice
    private lateinit var voiceServer: PlasmoVoiceServer
    // or (only if you're using kotlin bundled with PV with relocation)
    // private val voiceServer: PlasmoVoiceServer by injectPlasmoVoice()

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

        println("Addon initialized")
    }

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

--------------------------------

### Add PlayerActivationInfo in Java

Source: https://plasmovoice.com/docs/api/sources.html

Use PlayerActivationInfo when handling activation to ensure addons can identify the source of the audio.

```java
ServerActivation activation = /* ... */;
ServerProximitySource<?> source = /* ... */;

activation.onPlayerActivation((player, packet) -> {
    source.sendAudioFrame(
        packet.getData(),
        packet.getSequenceNumber(),
        packet.getDistance(),
        new PlayerActivationInfo(player, packet)
    );

    return ServerActivation.Result.HANDLED;
});
```

--------------------------------

### Registering an activation in Java

Source: https://plasmovoice.com/docs/api/activations.html

Create a new activation using the ServerActivation.Builder.

```java
PlasmoVoiceServer voiceServer = /* */; 
Object addon = /* */; 

ServerActivation activation = voiceServer.getActivationManager().createBuilder( 
    addon, 
    "priority", // name 
    "pv.activation.priority", // translation key 
    "plasmovoice:textures/icons/microphone_priority.png", // icon resource location 
    "pv.activation.priority", // permission 
    10 // weight 
).build();
```

--------------------------------

### ArrayAudioFrameProvider usage for sending audio

Source: https://plasmovoice.com/docs/api/sources.html

Demonstrates how to use ArrayAudioFrameProvider to send a fixed set of audio samples to an audio source, including looping and cleanup.

```APIDOC
## ArrayAudioFrameProvider usage for sending audio

### Description
Use ArrayAudioFrameProvider to send fixed audio samples to an audio source. The provider can be looped and must be closed after use to avoid memory leaks.

### Method
createAudioSender

### Endpoint
ServerPlayerSource.createAudioSender(ArrayAudioFrameProvider frameProvider, short distance)

### Parameters
- **frameProvider** (ArrayAudioFrameProvider) - Required - Provider containing audio samples
- **distance** (short) - Optional - Distance to send audio; omit for direct or broadcast sources

### Request Example
```java
ArrayAudioFrameProvider frameProvider = new ArrayAudioFrameProvider(voiceServer, false);
AudioSender audioSender = source.createAudioSender(frameProvider, distance);
frameProvider.addSamples(samples);
audioSender.start();
```

### Response
No response value is returned. The AudioSender can be stopped, paused, or resumed.
```

--------------------------------

### Create Player Source

Source: https://plasmovoice.com/docs/api/sources.html

Creates a source attached to a player. Audio will be played at a certain distance around the player.

```APIDOC
## Create Player Source

### Description
Creates a source attached to a player. Audio will be played at a certain distance around the player.

### Method
createPlayerSource

### Parameters
- **sourceLine** (ServerSourceLine) - Required - The source line to attach the source to.
- **voicePlayer** (VoiceServerPlayer) - Required - The player to attach the source to.
- **stereo** (boolean) - Required - Whether the source is stereo.

### Request Example
```java
PlasmoVoiceServer voiceServer = /* */;

ServerSourceLine sourceLine = voiceServer.getSourceLineManager()
        .getLineByName("proximity")
        .orElseThrow(() -> new IllegalStateException("Proximity source line not found"));

VoiceServerPlayer voicePlayer = voiceServer.getPlayerManager()
        .getPlayerByName("Apehum")
        .orElseThrow(() -> new IllegalStateException("Player not found"));

ServerPlayerSource source = sourceLine.createPlayerSource(voicePlayer, false);
```

### Response
Returns a ServerPlayerSource object.

### Additional Operations
- **removeFilter** (Filter) - Removes a filter from the source. By default, the player attached to the source can't hear the audio; remove the first filter to override this behavior.
```

--------------------------------

### Registering an activation in Kotlin

Source: https://plasmovoice.com/docs/api/activations.html

Create a new activation using the ServerActivation.Builder in Kotlin.

```kotlin
val voiceServer: PlasmoVoiceServer 
val addon: Any 

val activation = voiceServer.activationManager.createBuilder( 
    addon, 
    "priority", // name 
    "pv.activation.priority", // translation key 
    "plasmovoice:textures/icons/microphone_priority.png", // icon resource location 
    "pv.activation.priority", // permission 
    10 // weight 
).build()
```

--------------------------------

### Registering a source line in Java

Source: https://plasmovoice.com/docs/api/source-lines.html

Register a new source line by creating a builder via the source line manager.

```java
PlasmoVoiceServer voiceServer = /* */;\nObject addon = /* */;\n\nServerSourceLine sourceLine = voiceServer.getSourceLineManager().createBuilder(\n    addon,\n    "priority", // name\n    "pv.activation.priority", // translation key\n    "plasmovoice:textures/icons/speaker_priority.png", // icon resource location\n    10 // weight\n).build();
```

--------------------------------

### Initialize voice server (Java)

Source: https://plasmovoice.com/docs/server/minestom

Initialize and shut down the MinestomVoiceServer during server lifecycle events.

```java
// ... on server startup
File voiceConfigDirectory = new File("plasmovoice");
MinestomVoiceServer voiceServer = new MinestomVoiceServer(voiceConfigDirectory);
voiceServer.onInitialize();

// ... on server shutdown
voiceServer.onShutdown();
```

--------------------------------

### Create an Entity Source in Kotlin

Source: https://plasmovoice.com/docs/api/sources.html

Attaches a source to a specific entity instance.

```kotlin
val voiceServer: PlasmoVoiceServer\n\nval sourceLine = voiceServer.sourceLineManager\n    .getLineByName("proximity")\n    .orElseThrow { IllegalStateException("Proximity source line not found") }\n\nval platformEntity: Any = /* platform-specific entity instance, e.g org.bukkit.entity.Entity */\nval entity = voiceServer.minecraftServer.getEntityByInstance(platformEntity)\n\nval source = sourceLine.createEntitySource(entity, false)
```

--------------------------------

### Load Addon in Spigot (Java)

Source: https://plasmovoice.com/docs/api

Load the addon using the addons loader within the JavaPlugin's onLoad method.

```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);
    }
}
```

--------------------------------

### Enabling players in overlay in Java

Source: https://plasmovoice.com/docs/api/source-lines.html

Enable the players feature using withPlayers and manage player sets via ServerPlayerSetManager.

```java
PlasmoVoiceServer voiceServer = /* */;\n\nServerSourceLine sourceLine = voiceServer.getSourceLineManager()\n        .createBuilder(/*...*/)\n        .withPlayers(true)\n        .build();\n\nVoicePlayer player = /* voice player */;\n\nServerPlayerSetManager playerSetManager = sourceLine.getPlayerSetManager();\nServerPlayerSet broadcastSet = playerSetManager.createBroadcastSet();\nbroadcastSet.addPlayer(player);\n\n// sets the broadcast player set to the player\nplayerSetManager.setPlayerSet(player, broadcastSet);
```

--------------------------------

### Use custom placeholder

Source: https://plasmovoice.com/docs/server/papi

The syntax to use the newly created custom placeholder in other plugins or messages.

```text
%javascript_check_voice%
```

--------------------------------

### PlayerActivationInfo usage in ServerProximitySource

Source: https://plasmovoice.com/docs/api/sources.html

Shows how to include PlayerActivationInfo when sending audio frames from an activation handler so addons can identify the destination source.

```APIDOC
## PlayerActivationInfo usage in ServerProximitySource

### Description
When handling player activation, include PlayerActivationInfo in the sendAudioFrame call to inform addons about the destination source.

### Method
sendAudioFrame

### Endpoint
ServerProximitySource.sendAudioFrame(byte[] data, int sequenceNumber, short distance, PlayerActivationInfo info)

### Parameters
- **data** (byte[]) - Required - Audio frame data
- **sequenceNumber** (int) - Required - Sequence number of the audio frame
- **distance** (short) - Required - Distance for the audio
- **info** (PlayerActivationInfo) - Required - Contains player and packet information

### Request Example
```java
ServerActivation activation = /* ... */;
ServerProximitySource<?> source = /* ... */;

activation.onPlayerActivation((player, packet) -> {
    source.sendAudioFrame(
        packet.getData(),
        packet.getSequenceNumber(),
        packet.getDistance(),
        new PlayerActivationInfo(player, packet)
    );

    return ServerActivation.Result.HANDLED;
});
```

### Response
No response value is returned.
```

--------------------------------

### Download and reload Javascript extension

Source: https://plasmovoice.com/docs/server/papi

Commands to download the Javascript extension for PlaceholderAPI and reload the plugin to apply changes.

```text
/papi ecloud download Javascript
/papi reload
```

--------------------------------

### Define server and client translations in en_us.toml

Source: https://plasmovoice.com/docs/api/languages.html

TOML file with [server] and [client] blocks containing translation keys.

```toml
[server]
addon.test.pepega = "Pepega"

[client]
addon.test.pepega = "Pepega"

```

--------------------------------

### Create a Static Source in Java

Source: https://plasmovoice.com/docs/api/sources.html

Creates a static source at a specific world coordinate. The position can be updated after creation using setPosition.

```java
PlasmoVoiceServer voiceServer = /* */;\n\nServerSourceLine sourceLine = voiceServer.getSourceLineManager()\n        .getLineByName("proximity")\n        .orElseThrow(() -> new IllegalStateException("Proximity source line not found"));\n\nMcServerWorld world = voiceServer.getMinecraftServer()\n        .getWorlds()\n        .stream()\n        .filter(w -> w.getName().equals("world"))\n        .findAny()\n        .orElseThrow(() -> new IllegalStateException("World not found"));\n\nServerPos3d position = new ServerPos3d(world, 0.0D, 64.0D, 0.0D);\nServerStaticSource source = sourceLine.createStaticSource(position, false);\n\n// You can also change the source position after it has been created:\nServerPos3d newPosition = new ServerPos3d(world, 10.0D, 64.0D, 0.0D);\nsource.setPosition(newPosition);
```

--------------------------------

### Create a direct source in Kotlin

Source: https://plasmovoice.com/docs/api/sources.html

Kotlin equivalent of creating a ServerDirectSource for a specific player using the 'proximity' source line. The source is not spatial (false). Use BaseServerDirectSource#setSender to set the sender displayed in the player overlay.

```kotlin
val voiceServer: PlasmoVoiceServer

val sourceLine = voiceServer.sourceLineManager
    .getLineByName("proximity")
    .orElseThrow { IllegalStateException("Proximity source line not found") }

val voicePlayer: VoicePlayer = voiceServer.playerManager
    .getPlayerByName("Apehum")
    .orElseThrow { IllegalStateException("Player not found") }

val source = sourceLine.createDirectSource(voicePlayer, false)
```

--------------------------------

### Configure Plasmo Voice Proxy Plugin

Source: https://plasmovoice.com/docs/server/proxy

Initial configuration file for the Plasmo Voice proxy plugin, where server addresses can be explicitly defined if they differ from the proxy's game server configuration.

```toml
[host]
ip = "0.0.0.0"
port = 0

# [servers]
# farmworld = "127.0.0.1:25565"
# overworld = "127.0.0.1:25566"
```

--------------------------------

### Create Proximity Activation Helper in Java

Source: https://plasmovoice.com/docs/api/activations.html

Implementation of ProximityServerActivationHelper within a Java addon, including listener registration and unregistration.

```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;
import su.plo.voice.api.server.audio.capture.ProximityServerActivationHelper;
import su.plo.voice.api.server.audio.capture.ServerActivation;
import su.plo.voice.api.server.audio.line.ServerSourceLine;

@Addon(
        id = "pv-addon-test",
        name = "Test Addon",
        version = "1.0.0",
        authors = {"Plasmo"}
)
public final class TestAddon implements AddonInitializer {

    @InjectPlasmoVoice
    private PlasmoVoiceServer voiceServer;

    private ProximityServerActivationHelper proximityHelper;

    @Override
    public void onAddonInitialize() {
        ServerActivation activation = /* register or get activation */;
        ServerSourceLine sourceLine = /* register or get source line */;

        this.proximityHelper = new ProximityServerActivationHelper(voiceServer, activation, sourceLine);
        proximityHelper.registerListeners(this);
    }

    @Override
    public void onAddonShutdown() {
        if (proximityHelper != null) {
            proximityHelper.unregisterListeners(this);
        }
    }
}
```

--------------------------------

### Registering an activation with InputStream icon in Java

Source: https://plasmovoice.com/docs/api/activations.html

Use an InputStream to provide a custom icon for the activation.

```java
PlasmoVoiceServer voiceServer = /* */; 
Object addon = /* */; 

try (InputStream is = Files.newInputStream(new File("icon.png").toPath())) { 
    ServerActivation activation = voiceServer.getActivationManager().createBuilder( 
        addon, 
        "priority", // name 
        "pv.activation.priority", // translation key 
        is, // icon 
        "pv.activation.priority", // permission 
        10 // weight 
    ).build(); 
} catch (IOException e) { 
    e.printStackTrace(); 
}
```

--------------------------------

### Enabling players in overlay in Kotlin

Source: https://plasmovoice.com/docs/api/source-lines.html

Enable the players feature and manage player sets using Kotlin syntax.

```kotlin
val voiceServer: PlasmoVoiceServer\n\nval sourceLine: ServerSourceLine = voiceServer.sourceLineManager\n    .createBuilder(/* */)\n    .withPlayers(true)\n    .build()\n\nval player: VoicePlayer /* voice player */\n\nval playerSetManager = sourceLine.playerSetManager\nval broadcastSet = playerSetManager.createBroadcastSet()\nbroadcastSet.addPlayer(player)\n\n// sets the broadcast player set to the player\nplayerSetManager.setPlayerSet(player, broadcastSet)
```

--------------------------------

### List available languages

Source: https://plasmovoice.com/docs/api/languages.html

Text file listing the language code.

```text
en_us

```

--------------------------------

### Create Static Source

Source: https://plasmovoice.com/docs/api/sources.html

Creates a static source attached to a specific position in the world. The source can be repositioned after creation.

```APIDOC
## Create Static Source

### Description
Creates a static source attached to a specific position in the world. The source can be repositioned after creation.

### Method
createStaticSource

### Parameters
- **sourceLine** (ServerSourceLine) - Required - The source line to attach the source to.
- **position** (ServerPos3d) - Required - The initial position of the source.
- **stereo** (boolean) - Required - Whether the source is stereo.

### Request Example
```java
PlasmoVoiceServer voiceServer = /* */;

ServerSourceLine sourceLine = voiceServer.getSourceLineManager()
        .getLineByName("proximity")
        .orElseThrow(() -> new IllegalStateException("Proximity source line not found"));

McServerWorld world = voiceServer.getMinecraftServer()
        .getWorlds()
        .stream()
        .filter(w -> w.getName().equals("world"))
        .findAny()
        .orElseThrow(() -> new IllegalStateException("World not found"));

ServerPos3d position = new ServerPos3d(world, 0.0D, 64.0D, 0.0D);
ServerStaticSource source = sourceLine.createStaticSource(position, false);
```

### Response
Returns a ServerStaticSource object.

### Additional Operations
- **setPosition** (ServerPos3d) - Updates the source position.
```

--------------------------------

### Load Addon in Spigot (Kotlin)

Source: https://plasmovoice.com/docs/api

Load the addon using the addons loader within the JavaPlugin's onLoad method.

```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)
    }
}
```

--------------------------------

### Configure Plasmo Voice Gradle plugin repository

Source: https://plasmovoice.com/docs/api

Add the snapshot repository to your settings.gradle.kts file.

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

--------------------------------

### Create an Entity Source in Java

Source: https://plasmovoice.com/docs/api/sources.html

Attaches a source to a specific entity instance.

```java
PlasmoVoiceServer voiceServer = /* */;\n\nServerSourceLine sourceLine = voiceServer.getSourceLineManager()\n        .getLineByName("proximity")\n        .orElseThrow(() -> new IllegalStateException("Proximity source line not found"));\n\nObject platformEntity = /* platform-specific entity instance, e.g org.bukkit.entity.Entity */;\nMcServerEntity entity = voiceServer.getMinecraftServer().getEntityByInstance(platformEntity);\n\nServerEntitySource source = sourceLine.createEntitySource(entity, false);
```

--------------------------------

### Create a broadcast source in Java

Source: https://plasmovoice.com/docs/api/sources.html

Creates a ServerBroadcastSource for the 'proximity' source line. By default, the player group is not set, so all players with Plasmo Voice hear the audio. Use ServerBroadcastSource#setPlayers to set the group of players that can hear it.

```java
PlasmoVoiceServer voiceServer = /* */;

ServerSourceLine sourceLine = voiceServer.getSourceLineManager()
        .getLineByName("proximity")
        .orElseThrow(() -> new IllegalStateException("Proximity source line not found"));

ServerBroadcastSource source = sourceLine.createBroadcastSource(false);

// Set "listeners" for broadcast source
VoicePlayer player = voiceServer.getPlayerManager()
    .getPlayerByName("Apehum")
    .orElseThrow(() -> new IllegalStateException("Player not found"));
Set<VoicePlayer> players = new HashSet<>();
players.add(player);
source.setPlayers(players);
```

--------------------------------

### Add PlayerActivationInfo in Kotlin

Source: https://plasmovoice.com/docs/api/sources.html

Use PlayerActivationInfo when handling activation to ensure addons can identify the source of the audio.

```kotlin
val activation: ServerActivation = /* */
val source: ServerProximitySource<*> = /* */

activation.onPlayerActivation { player, packet ->
    source.sendAudioFrame(
        packet.data,
        packet.sequenceNumber,
        packet.distance,
        PlayerActivationInfo(player, packet)
    )

    ServerActivation.Result.HANDLED
}
```

--------------------------------

### ServerPlayerSet#addPlayer

Source: https://plasmovoice.com/docs/api/source-lines.html

Adds a voice player to the player set.

```APIDOC
## ServerPlayerSet#addPlayer

### Description
Adds a voice player to the player set.

### Method
Set method

### Parameters
- **player** (VoicePlayer) - Required - The voice player to add.

### Request Example
```java
VoicePlayer player = /* voice player */;
ServerPlayerSet broadcastSet = /* */;
broadcastSet.addPlayer(player);
```

### Response
No return value.

```

--------------------------------

### ServerSourceLine#createDirectSource

Source: https://plasmovoice.com/docs/api/sources.html

Creates a direct source attached to a specific player. The source can only be heard by that player. Optionally, the sender can be set using BaseServerDirectSource#setSender.

```APIDOC
## ServerSourceLine#createDirectSource

### Description
Creates a direct source attached to a specific player. The source can only be heard by that player. Optionally, the sender can be set using BaseServerDirectSource#setSender.

### Method
createDirectSource

### Parameters
- **voicePlayer** (VoicePlayer) - Required - The player who will hear the source.
- **permanent** (boolean) - Required - Whether the source is permanent.

### Returns
ServerDirectSource - The created direct source.

### Example (Java)
```java
PlasmoVoiceServer voiceServer = /* */;

ServerSourceLine sourceLine = voiceServer.getSourceLineManager()
        .getLineByName("proximity")
        .orElseThrow(() -> new IllegalStateException("Proximity source line not found"));

VoicePlayer voicePlayer = voiceServer.getPlayerManager()
        .getPlayerByName("Apehum")
        .orElseThrow(() -> new IllegalStateException("Player not found"));

ServerDirectSource source = sourceLine.createDirectSource(voicePlayer, false);
```

### Example (Kotlin)
```kotlin
val voiceServer: PlasmoVoiceServer

val sourceLine = voiceServer.sourceLineManager
    .getLineByName("proximity")
    .orElseThrow { IllegalStateException("Proximity source line not found") }

val voicePlayer: VoicePlayer = voiceServer.playerManager
    .getPlayerByName("Apehum")
    .orElseThrow { IllegalStateException("Player not found") }

val source = sourceLine.createDirectSource(voicePlayer, false)
```
```

--------------------------------

### Add addon dependency (Gradle Kotlin DSL)

Source: https://plasmovoice.com/docs/server/minestom

Add the Modrinth repository and addon dependency to your build.gradle.kts file.

```kotlin
repositories {
    // note that there is a better way to specify modrinth maven repository
    // see "Advanced repository declaration" https://support.modrinth.com/en/articles/8801191-modrinth-maven
    maven("https://api.modrinth.com/maven")
}

dependencies {
    compileOnly("maven.modrinth:pv-addon-spectator:${version}")
}
```

--------------------------------

### Register activation listeners in Java

Source: https://plasmovoice.com/docs/api/activations.html

Registers listeners for player activation events. Returning ServerActivation.Result.HANDLED cancels the corresponding PlayerSpeakEvent or PlayerSpeakEndEvent.

```java
ServerActivation activation = /* */; 

activation.onPlayerActivationStart(player -> {
    System.out.println(player + " start speaking to activation");
});

activation.onPlayerActivation((player, packet) -> {
    System.out.println(player + " is speaking to activation");

    // you need to return "HANDLED" if activation was handled successfully.
    // this will cancel PlayerSpeakEvent
    return ServerActivation.Result.HANDLED;
});

activation.onPlayerActivationEnd((player, packet) -> {
    System.out.println(player + " has finished speaking to activation");

    // you need to return "HANDLED" if activation was handled successfully.
    // this will cancel PlayerSpeakEndEvent
    return ServerActivation.Result.HANDLED;
});
```

--------------------------------

### Registering an EventListener class with @EventSubscribe

Source: https://plasmovoice.com/docs/api/events.html

Demonstrates registering a separate event listener class using the event bus.

```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.event.EventSubscribe;
import su.plo.voice.api.server.PlasmoVoiceServer;
import su.plo.voice.api.server.event.connection.UdpClientConnectEvent;

@Addon(
        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.getEventBus().register(this, new EventListener());
    }

    public static final class EventListener {

        @EventSubscribe
        public void onClientConnected(UdpClientConnectEvent event) {
            System.out.println(
                    event.getConnection().getPlayer() + " connected to UDP"
            );
        }
    }
}
```

```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.event.EventSubscribe
import su.plo.voice.api.server.PlasmoVoiceServer
import su.plo.voice.api.server.event.connection.UdpClientConnectEvent

@Addon(
    id = "pv-addon-test",
    name = "Test Addon",
    version = "1.0.0",
    authors = ["Plasmo"]
)
class TestAddon : AddonInitializer {

    private val voiceServer: PlasmoVoiceServer by injectPlasmoVoice()

    override fun onAddonInitialize() {
        voiceServer.eventBus.register(this, EventListener())
    }

    class EventListener {

        @EventSubscribe
        fun onClientConnected(event: UdpClientConnectEvent) {
            println("${event.connection.player} connected to UDP")
        }
    }
}
```
Tokens:
Raw