Connectors
Connectors handle the integration between Yukino and Discord client libraries. They manage voice state updates and server updates.
Base Connector
The Connector class is the base class for platform-specific implementations.
Constructor Requirements
- The constructor requires a
sessionId(typically the bot's user ID), which is used to set theclientIdproperty. - Either
urlorhost(and optionallyport) must be provided. authis required for Lavalink authentication.- Optionally,
restOptionscan be provided for custom REST configuration. - On instantiation, if no nodes exist, a default node is created using the provided connection options.
Properties
abstract class Connector extends EventEmitter {
public clientId: string; // Set from sessionId (usually bot's user ID)
public nodes: Map<string, Node>;
public voiceStates: Map<string, any>;
public voiceServers: Map<string, any>;
protected options: Required<ConnectorOptions>;
}
Methods
createNode(options: NodeOptions, restOptions?: RestOptions)
Creates a new Lavalink node instance. If a node with the same name exists, returns the existing instance. Optionally accepts custom REST options.
const node = connector.createNode({
name: 'main',
url: 'localhost:2333',
auth: 'password'
});
destroyNode(node: Node)
Destroys and removes a node instance. (Note: This method is not implemented in the base class; use the node's disconnect() method and remove it from the map.)
createPlayer(options: PlayerOptions)
Creates a new player instance.
const player = connector.createPlayer({
guildId: 'guild-id',
voiceChannelId: 'channel-id'
});
destroyPlayer(player: Player)
Destroys and cleans up a player instance. (Note: This method is not implemented in the base class; use the player's destroy() method.)
loadTrack(query: string, options?: SearchOptions)
Loads a track from a URL or search query.
const result = await connector.loadTrack('search query');
sendVoiceUpdate(guildId: string, channelId: string | null, mute?: boolean, deaf?: boolean)
Base implementation only emits an event (sendVoiceUpdate). Platform-specific connectors should override this to actually send the payload to Discord.
DiscordJSConnector
The DiscordJSConnector class implements the base Connector for Discord.js.
Constructor
import { Client } from 'discord.js';
import { DiscordJSConnector } from 'yukinojs';
const connector = new DiscordJSConnector({
client: client, // Must be a logged-in Discord.js Client
auth: 'password',
debug: true
});
- The
clientmust be logged in;sessionIdis set fromclient.user.idautomatically.
Voice State Management
The connector automatically handles voice state and server updates from Discord by listening to the raw event:
// Handled internally via the 'raw' event
client.on('raw', (packet) => {
// ...handled by DiscordJSConnector...
});
Voice Connection
sendVoiceUpdate(guildId: string, channelId: string | null, mute?: boolean, deaf?: boolean)
Sends voice state updates to Discord by sending a payload via the Discord.js WebSocket shard. This method is asynchronous.
// Join a voice channel
await connector.sendVoiceUpdate('guild-id', 'channel-id', false, false);
// Leave a voice channel
await connector.sendVoiceUpdate('guild-id', null);
Creating Custom Connectors
You can create custom connectors for other Discord library implementations by extending the base Connector class:
import { Connector } from 'yukinojs';
class CustomConnector extends Connector {
constructor(options: ConnectorOptions) {
super(options);
// Initialize your custom connector
}
public async sendVoiceUpdate(
guildId: string,
channelId: string | null,
mute?: boolean,
deaf?: boolean
): Promise<void> {
// Implement voice state update logic for your library
}
}
Required Implementations
Custom connectors must implement:
- Voice state update handling
- Voice server update handling
- Client ID management
- Voice channel connection/disconnection
Example: Minimal Custom Connector
class MinimalConnector extends Connector {
private client: any; // Your client type
constructor(options: ConnectorOptions) {
super(options);
this.client = options.client;
// Set up event listeners
this.client.on('voiceStateUpdate', this.onVoiceStateUpdate.bind(this));
this.client.on('voiceServerUpdate', this.onVoiceServerUpdate.bind(this));
}
private onVoiceStateUpdate(data: any): void {
this.voiceStates.set(data.guild_id, {
sessionId: data.session_id,
channelId: data.channel_id,
userId: data.user_id
});
this.updateVoiceState(data.guild_id);
}
private onVoiceServerUpdate(data: any): void {
this.voiceServers.set(data.guild_id, {
token: data.token,
endpoint: data.endpoint
});
this.updateVoiceState(data.guild_id);
}
private updateVoiceState(guildId: string): void {
const state = this.voiceStates.get(guildId);
const server = this.voiceServers.get(guildId);
if (state && server) {
// Update the node with new voice state
const node = this.nodes.values().next().value;
if (node) {
node.updateVoiceState(guildId, state, server);
}
}
}
public async sendVoiceUpdate(
guildId: string,
channelId: string | null,
mute = false,
deaf = false
): Promise<void> {
await this.client.updateVoiceState({
guild_id: guildId,
channel_id: channelId,
self_mute: mute,
self_deaf: deaf
});
}
}
Best Practices
- Handle voice state cleanup:
class BetterConnector extends Connector {
public destroy(): void {
this.voiceStates.clear();
this.voiceServers.clear();
this.nodes.clear();
}
}
- Implement error handling:
class RobustConnector extends Connector {
public async sendVoiceUpdate(...args): Promise<void> {
try {
await super.sendVoiceUpdate(...args);
} catch (error) {
this.emit('error', error);
throw error;
}
}
}
- Add debug logging:
class DebugConnector extends Connector {
private logger: Logger;
constructor(options: ConnectorOptions) {
super(options);
this.logger = Logger.create('Connector', options.debug || false);
}
protected onVoiceStateUpdate(data: any): void {
this.logger.debug('Voice state update:', data);
super.onVoiceStateUpdate(data);
}
}