ziplayer 0.2.7-dev.0 → 0.2.7-dev.2

package/src/structures/PlayerManager.ts

@@ -1,10 +1,22 @@
 import { EventEmitter } from "events";
 import { Player } from "./Player";
-import { PlayerManagerOptions, PlayerOptions, Track, SourcePlugin, SearchResult, ManagerEvents } from "../types";
+import {
+	PlayerManagerOptions,
+	PlayerOptions,
+	Track,
+	SourcePlugin,
+	SearchResult,
+	ManagerEvents,
+	PlayerStats,
+	PersistenceOptions,
+	DestroyedRecord,
+} from "../types";
 import type { BaseExtension } from "../extensions";
 import { withTimeout } from "../utils/timeout";
+import { PersistenceManager } from "../persistence/PersistenceManager";
 
 const GLOBAL_MANAGER_KEY: symbol = Symbol.for("ziplayer.PlayerManager.instance");
+
 export const getGlobalManager = (): PlayerManager | null => {
 	try {
 		const instance = (globalThis as any)[GLOBAL_MANAGER_KEY];
@@ -17,6 +29,7 @@ export const getGlobalManager = (): PlayerManager | null => {
 		return null;
 	}
 };
+
 const setGlobalManager = (instance: PlayerManager): void => {
 	try {
 		(globalThis as any)[GLOBAL_MANAGER_KEY] = instance;
@@ -30,6 +43,12 @@ export declare interface PlayerManager {
 	emit<K extends keyof ManagerEvents>(event: K, ...args: ManagerEvents[K]): boolean;
 }
 
+interface ManagerCacheEntry<T> {
+	data: T;
+	timestamp: number;
+	expiresAt: number;
+}
+
 /**
  * The main class for managing players across multiple Discord guilds.
  *
@@ -48,7 +67,9 @@ export declare interface PlayerManager {
  *       nodes: [{ host: "localhost", port: 2333, password: "youshallnotpass" }]
  *     })
  *   ],
- *   extractorTimeout: 10000
+ *   extractorTimeout: 10000,
+ *   autoCleanup: true,
+ *   cleanupInterval: 60000
  * });
  *
  * // Create a player for a guild
@@ -67,6 +88,13 @@ export declare interface PlayerManager {
 export class PlayerManager extends EventEmitter {
 	private static instance: PlayerManager | null = null;
 	private players: Map<string, Player> = new Map();
+	private searchCache: Map<string, ManagerCacheEntry<SearchResult>>;
+	private readonly SEARCH_CACHE_TTL = 60 * 1000; // 1 minute
+	private readonly MAX_CACHE_SIZE = 100;
+	private cleanupInterval: NodeJS.Timeout | null = null;
+	private statsInterval: NodeJS.Timeout | null = null;
+
+	private persistenceManager?: PersistenceManager;
 	static async default(opt?: PlayerOptions): Promise<Player> {
 		let globaldef = getGlobalManager();
 		if (!globaldef) {
@@ -74,14 +102,18 @@ export class PlayerManager extends EventEmitter {
 		}
 		return await globaldef.create("default", opt);
 	}
+
 	private plugins: SourcePlugin[];
 	private extensions: any[];
 	private B_debug: boolean = false;
 	private extractorTimeout: number = 10000;
+	private autoCleanup: boolean = true;
+	private cleanupTimeout: number = 60000; // 1 minute
+	private enableSearchCache: boolean = true;
 
 	private debug(message?: any, ...optionalParams: any[]): void {
 		if (this.listenerCount("debug") > 0) {
-			this.emit("debug", message, ...optionalParams);
+			this.emit("debug", `[PlayerManager] ${message}`, ...optionalParams);
 			if (!this.B_debug) {
 				this.B_debug = true;
 			}
@@ -91,6 +123,9 @@ export class PlayerManager extends EventEmitter {
 	constructor(options: PlayerManagerOptions = {}) {
 		super();
 		this.plugins = [];
+		this.searchCache = new Map();
+
+		// Initialize plugins
 		const provided = options.plugins || [];
 		for (const p of provided as any[]) {
 			try {
@@ -100,13 +135,33 @@ export class PlayerManager extends EventEmitter {
 					const instance = new (p as any)();
 					this.plugins.push(instance as SourcePlugin);
 				}
+				this.debug(`Registered plugin: ${p.name || "unnamed"}`);
 			} catch (e) {
-				this.debug(`[PlayerManager] Failed to init plugin:`, e);
+				this.debug(`Failed to init plugin:`, e);
 			}
 		}
+
 		this.extensions = options.extensions || [];
+		this.extractorTimeout = options.extractorTimeout ?? 10000;
+		this.autoCleanup = options.autoCleanup ?? true;
+		this.cleanupTimeout = options.cleanupInterval ?? 60000;
+		this.enableSearchCache = options.enableSearchCache ?? true;
+
+		if (options.persistence) {
+			this.initPersistence(options.persistence);
+		}
+		// Setup auto cleanup
+		if (this.autoCleanup) {
+			this.startAutoCleanup();
+		}
+
+		// Setup stats collection (optional)
+		if (options.enableStatsCollection) {
+			this.startStatsCollection();
+		}
 
 		setGlobalManager(this);
+		this.debug(`Initialized with ${this.plugins.length} plugins, ${this.extensions.length} extensions`);
 	}
 
 	private withTimeout<T>(promise: Promise<T>, message: string): Promise<T> {
@@ -120,53 +175,132 @@ export class PlayerManager extends EventEmitter {
 		throw new Error("Invalid guild or guildId provided.");
 	}
 
+	private getSearchCacheKey(query: string): string {
+		return query.toLowerCase().trim();
+	}
+
+	private getCachedSearch(query: string): SearchResult | null {
+		if (!this.enableSearchCache) return null;
+
+		const key = this.getSearchCacheKey(query);
+		const cached = this.searchCache.get(key);
+
+		if (cached && Date.now() < cached.expiresAt) {
+			this.debug(`[Cache] Search hit for: ${query}`);
+			return cached.data;
+		}
+
+		if (cached) {
+			this.searchCache.delete(key);
+		}
+
+		return null;
+	}
+
+	private setCachedSearch(query: string, result: SearchResult): void {
+		if (!this.enableSearchCache) return;
+
+		// Clean up old entries if cache is too large
+		if (this.searchCache.size >= this.MAX_CACHE_SIZE) {
+			const oldest = Array.from(this.searchCache.entries()).sort((a, b) => a[1].timestamp - b[1].timestamp)[0];
+			if (oldest) this.searchCache.delete(oldest[0]);
+		}
+
+		const key = this.getSearchCacheKey(query);
+		this.searchCache.set(key, {
+			data: result,
+			timestamp: Date.now(),
+			expiresAt: Date.now() + this.SEARCH_CACHE_TTL,
+		});
+		this.debug(`[Cache] Search stored for: ${query}`);
+	}
+
+	private clearExpiredCache(): void {
+		const now = Date.now();
+		let expiredCount = 0;
+
+		for (const [key, entry] of this.searchCache) {
+			if (now >= entry.expiresAt) {
+				this.searchCache.delete(key);
+				expiredCount++;
+			}
+		}
+
+		if (expiredCount > 0) {
+			this.debug(`[Cache] Cleared ${expiredCount} expired search entries`);
+		}
+	}
+
+	private startAutoCleanup(): void {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+		}
+
+		this.cleanupInterval = setInterval(() => {
+			this.cleanupInactivePlayers();
+			this.clearExpiredCache();
+		}, this.cleanupTimeout);
+
+		this.debug(`Auto-cleanup started with interval: ${this.cleanupTimeout}ms`);
+	}
+
+	private startStatsCollection(): void {
+		if (this.statsInterval) {
+			clearInterval(this.statsInterval);
+		}
+
+		this.statsInterval = setInterval(() => {
+			const stats = this.getStats();
+			this.emit("stats", stats);
+		}, 30000); // Every 30 seconds
+	}
+
+	private cleanupInactivePlayers(): void {
+		let cleanedCount = 0;
+
+		for (const [guildId, player] of this.players) {
+			// Clean up players that are not playing and not connected
+			if (!player.isPlaying && !player.connection && player.queue.isEmpty) {
+				const idleTime = Date.now() - (player as any)._lastActivity || Date.now();
+				if (idleTime > this.cleanupTimeout) {
+					this.debug(`Cleaning up inactive player for guild: ${guildId}`);
+					player.destroy();
+					this.players.delete(guildId);
+					cleanedCount++;
+				}
+			}
+		}
+
+		if (cleanedCount > 0) {
+			this.debug(`Cleaned up ${cleanedCount} inactive players`);
+		}
+	}
+
 	/**
 	 * Create a new player for a guild
 	 *
 	 * @param {string | {id: string}} guildOrId - Guild ID or guild object
 	 * @param {PlayerOptions} options - Player configuration options
 	 * @returns {Promise<Player>} The created player instance
-	 *
-	 * @example
-	 * // Create player with basic options
-	 * const player = await manager.create(guildId, {
-	 *   tts: { interrupt: true, volume: 1 },
-	 *   leaveOnEnd: true,
-	 *   leaveTimeout: 30000
-	 * });
-	 *
-	 * // Create player with advanced options
-	 * const advancedPlayer = await manager.create(guild, {
-	 *   volume: 0.8,
-	 *   quality: "high",
-	 *   selfDeaf: false,
-	 *   selfMute: false,
-	 *   tts: {
-	 *     createPlayer: true,
-	 *     interrupt: true,
-	 *     volume: 1.0,
-	 *     Max_Time_TTS: 30000
-	 *   },
-	 *   userdata: { customData: "example" }
-	 * });
-	 *
-	 * // Connect and play immediately
-	 * await player.connect(voiceChannel);
-	 * await player.play("Never Gonna Give You Up", userId);
 	 */
-
 	async create(guildOrId: string | { id: string }, options?: PlayerOptions): Promise<Player> {
 		const guildId = this.resolveGuildId(guildOrId);
+
 		if (this.players.has(guildId)) {
+			this.debug(`Player already exists for guildId: ${guildId}, returning existing`);
 			return this.players.get(guildId)!;
 		}
 
-		this.debug(`[PlayerManager] Creating player for guildId: ${guildId}`);
+		this.debug(`Creating player for guildId: ${guildId}`);
 		const player = new Player(guildId, options, this);
+
+		// Add all registered plugins
 		this.plugins.forEach((plugin) => player.addPlugin(plugin));
 
+		// Activate extensions
 		let extsToActivate: any[] = [];
 		const optExts = (options as any)?.extensions as any[] | string[] | undefined;
+
 		if (Array.isArray(optExts)) {
 			if (optExts.length === 0) {
 				extsToActivate = [];
@@ -179,6 +313,9 @@ export class PlayerManager extends EventEmitter {
 			} else {
 				extsToActivate = optExts;
 			}
+		} else {
+			// Use all extensions by default
+			extsToActivate = this.extensions;
 		}
 
 		for (const ext of extsToActivate) {
@@ -187,14 +324,16 @@ export class PlayerManager extends EventEmitter {
 				try {
 					instance = new ext(player);
 				} catch (e) {
-					this.debug(`[PlayerManager] Extension constructor error:`, e);
+					this.debug(`Extension constructor error for ${ext.name}:`, e);
 					continue;
 				}
 			}
+
 			if (instance && typeof instance === "object") {
 				const extInstance = instance as BaseExtension;
 				if ("player" in extInstance && !extInstance.player) extInstance.player = player;
 				player.attachExtension(extInstance);
+
 				if (typeof extInstance.active === "function") {
 					let activated: boolean | void = true;
 					try {
@@ -203,11 +342,12 @@ export class PlayerManager extends EventEmitter {
 							player.options.extractorTimeout ?? 15000,
 							`Extension ${extInstance?.name} activation timed out`,
 						);
-						this.debug(`[PlayerManager] Extension ${extInstance?.name} active`);
+						this.debug(`Extension ${extInstance?.name} active check returned: ${activated}`);
 					} catch (e) {
 						activated = false;
-						this.debug(`[PlayerManager] Extension activation error:`, e);
+						this.debug(`Extension activation error for ${extInstance?.name}:`, e);
 					}
+
 					if (activated === false) {
 						player.detachExtension(extInstance);
 						continue;
@@ -216,167 +356,267 @@ export class PlayerManager extends EventEmitter {
 			}
 		}
 
-		// Forward all player events
-		player.on("willPlay", (track, tracks) => this.emit("willPlay", player, track as Track, tracks as Track[]));
-		player.on("trackStart", (track) => this.emit("trackStart", player, track as Track));
-		player.on("trackEnd", (track) => this.emit("trackEnd", player, track as Track));
-		player.on("queueEnd", () => this.emit("queueEnd", player));
-		player.on("playerError", (error, track) => this.emit("playerError", player, error, track as Track));
-		player.on("connectionError", (error) => this.emit("connectionError", player, error));
-		player.on("volumeChange", (old, volume) => this.emit("volumeChange", player, old as number, volume as number));
-		player.on("queueAdd", (track) => this.emit("queueAdd", player, track as Track));
-		player.on("queueAddList", (tracks) => this.emit("queueAddList", player, tracks as Track[]));
-		player.on("queueRemove", (track, index) => this.emit("queueRemove", player, track as Track, index));
-		player.on("playerPause", (track) => this.emit("playerPause", player, track as Track));
-		player.on("playerResume", (track) => this.emit("playerResume", player, track as Track));
-		player.on("playerStop", () => this.emit("playerStop", player));
+		// Forward all player events to manager
+		this.setupEventForwarding(player, guildId);
+
+		// Mark last activity
+		(player as any)._lastActivity = Date.now();
+
+		this.players.set(guildId, player);
+		this.debug(`Player created for guildId: ${guildId}`);
+		return player;
+	}
+
+	private setupEventForwarding(player: Player, guildId: string): void {
+		const forwardEvents = {
+			willPlay: "willPlay",
+			trackStart: "trackStart",
+			trackEnd: "trackEnd",
+			queueEnd: "queueEnd",
+			playerError: "playerError",
+			connectionError: "connectionError",
+			volumeChange: "volumeChange",
+			queueAdd: "queueAdd",
+			queueAddList: "queueAddList",
+			queueRemove: "queueRemove",
+			playerPause: "playerPause",
+			playerResume: "playerResume",
+			playerStop: "playerStop",
+			ttsStart: "ttsStart",
+			ttsEnd: "ttsEnd",
+		} as const satisfies Record<string, keyof ManagerEvents>;
+
+		for (const [sourceEvent, targetEvent] of Object.entries(forwardEvents) as [
+			keyof typeof forwardEvents,
+			keyof ManagerEvents,
+		][]) {
+			player.on(sourceEvent, (...args: any[]) => {
+				if (sourceEvent === "trackStart") {
+					player._lastActivity = Date.now();
+				}
+
+				(this.emit as any)(targetEvent, player, ...args);
+			});
+		}
+
 		player.on("playerDestroy", () => {
 			this.emit("playerDestroy", player);
+
 			this.players.delete(guildId);
+
+			this.debug(`Player destroyed for guildId: ${guildId}`);
 		});
-		player.on("ttsStart", (payload) => this.emit("ttsStart", player, payload));
-		player.on("ttsEnd", () => this.emit("ttsEnd", player));
+
 		player.on("debug", (...args) => {
 			if (this.listenerCount("debug") > 0) {
 				this.emit("debug", ...args);
 			}
 		});
-
-		this.players.set(guildId, player);
-		return player;
 	}
-
 	/**
 	 * Get an existing player for a guild
 	 *
 	 * @param {string | {id: string}} guildOrId - Guild ID or guild object
 	 * @returns {Player | undefined} The player instance or undefined if not found
-	 * @example
-	 * // Get player by guild ID
-	 * const player = manager.get(guildId);
-	 * if (player) {
-	 *   await player.play("Never Gonna Give You Up", userId);
-	 * } else {
-	 *   console.log("No player found for this guild");
-	 * }
-	 *
-	 * // Get player by guild object
-	 * const playerFromGuild = manager.get(guild);
-	 * if (playerFromGuild) {
-	 *   playerFromGuild.setVolume(0.5);
-	 * }
-	 *
-	 * // Check if player exists before using
-	 * const existingPlayer = manager.get(guildId);
-	 * if (existingPlayer && existingPlayer.playing) {
-	 *   existingPlayer.pause();
-	 * }
 	 */
-
 	get(guildOrId: string | { id: string }): Player | undefined {
 		const guildId = this.resolveGuildId(guildOrId);
-		return this.players.get(guildId);
+		const player = this.players.get(guildId);
+		if (player) {
+			(player as any)._lastActivity = Date.now();
+		}
+		return player;
 	}
 
 	/**
-	 * Get an existing player for a guild
-	 *
-	 * @param {string | {id: string}} guildOrId - Guild ID or guild object
-	 * @returns {Player | undefined} The player instance or undefined
-	 * @example
-	 * const player = manager.get(guildId);
-	 * if (player) {
-	 *   await player.play("song name", userId);
-	 * }
+	 * Get an existing player for a guild (alias for get)
 	 */
 	getPlayer(guildOrId: string | { id: string }): Player | undefined {
-		const guildId = this.resolveGuildId(guildOrId);
-		return this.players.get(guildId);
+		return this.get(guildOrId);
 	}
 
 	/**
 	 * Get all players
 	 *
 	 * @returns {Player[]} All player instances
-	 * @example
-	 * const players = manager.getall();
-	 * console.log(`Players: ${players.length}`);
 	 */
-	getall(): Player[] | [] {
+	getAll(): Player[] {
 		return Array.from(this.players.values());
 	}
 
+	/**
+	 * Alias for getAll
+	 */
+	getall(): Player[] {
+		return this.getAll();
+	}
+
+	/**
+	 * Get players by filter
+	 *
+	 * @param {(player: Player) => boolean} filter - Filter function
+	 * @returns {Player[]} Filtered player instances
+	 */
+	getPlayersByFilter(filter: (player: Player) => boolean): Player[] {
+		return this.getAll().filter(filter);
+	}
+
+	/**
+	 * Get players in a voice channel
+	 *
+	 * @param {string} channelId - Voice channel ID
+	 * @returns {Player[]} Players in the channel
+	 */
+	getPlayersInChannel(channelId: string): Player[] {
+		return this.getAll().filter((p) => p.connection?.joinConfig.channelId === channelId);
+	}
+
 	/**
 	 * Destroy a player and clean up resources
 	 *
 	 * @param {string | {id: string}} guildOrId - Guild ID or guild object
 	 * @returns {boolean} True if player was destroyed, false if not found
-	 * @example
-	 * // Destroy player by guild ID
-	 * const destroyed = manager.delete(guildId);
-	 * if (destroyed) {
-	 *   console.log("Player destroyed successfully");
-	 * } else {
-	 *   console.log("No player found to destroy");
-	 * }
-	 *
-	 * // Destroy player by guild object
-	 * const destroyedFromGuild = manager.delete(guild);
-	 * console.log(`Player destroyed: ${destroyedFromGuild}`);
-	 *
-	 * // Clean up all players
-	 * for (const [guildId, player] of manager.players) {
-	 *   const destroyed = manager.delete(guildId);
-	 *   console.log(`Destroyed player for ${guildId}: ${destroyed}`);
-	 * }
 	 */
 	delete(guildOrId: string | { id: string }): boolean {
 		const guildId = this.resolveGuildId(guildOrId);
 		const player = this.players.get(guildId);
+
 		if (player) {
-			this.debug(`[PlayerManager] Deleting player for guildId: ${guildId}`);
+			this.debug(`Deleting player for guildId: ${guildId}`);
 			player.destroy();
-			return this.players.delete(guildId);
+			return true;
 		}
 		return false;
 	}
 
+	/**
+	 * Destroy multiple players by filter
+	 *
+	 * @param {(player: Player) => boolean} filter - Filter function
+	 * @returns {number} Number of players destroyed
+	 */
+	deleteWhere(filter: (player: Player) => boolean): number {
+		const toDelete = this.getPlayersByFilter(filter);
+		let count = 0;
+
+		for (const player of toDelete) {
+			const guildId = player.guildId;
+			player.destroy();
+			this.players.delete(guildId);
+			count++;
+		}
+
+		if (count > 0) {
+			this.debug(`Deleted ${count} players by filter`);
+		}
+		return count;
+	}
+
 	/**
 	 * Check if a player exists for a guild
 	 *
 	 * @param {string | {id: string}} guildOrId - Guild ID or guild object
-	 * @returns {boolean} True if player exists, false if not
-	 * @example
-	 * const exists = manager.has(guildId);
-	 * console.log(`Player exists: ${exists}`);
+	 * @returns {boolean} True if player exists
 	 */
 	has(guildOrId: string | { id: string }): boolean {
 		const guildId = this.resolveGuildId(guildOrId);
 		return this.players.has(guildId);
 	}
 
+	/**
+	 * Get number of players
+	 */
 	get size(): number {
 		return this.players.size;
 	}
 
+	/**
+	 * Check if debug is enabled
+	 */
 	get debugEnabled(): boolean {
 		return this.B_debug;
 	}
+
+	/**
+	 * Get manager statistics
+	 *
+	 * @returns {PlayerStats} Statistics about players
+	 */
+	getStats(): PlayerStats {
+		let activePlayers = 0;
+		let pausedPlayers = 0;
+		let connectedPlayers = 0;
+		let totalTracksInQueue = 0;
+
+		for (const player of this.players.values()) {
+			if (player.isPlaying) activePlayers++;
+			if (player.isPaused) pausedPlayers++;
+			if (player.connection) connectedPlayers++;
+			totalTracksInQueue += player.queueSize;
+		}
+
+		return {
+			totalPlayers: this.players.size,
+			activePlayers,
+			pausedPlayers,
+			connectedPlayers,
+			totalTracksInQueue,
+		};
+	}
+
 	/**
-	 * Destroy all players
+	 * Broadcast an action to all players
 	 *
-	 * @returns {void}
+	 * @param {string} action - Action to perform
+	 * @param {...any[]} args - Arguments for the action
 	 * @example
-	 * manager.destroy();
-	 * console.log(`All players destroyed`);
+	 * manager.broadcast("setVolume", 50);
+	 * manager.broadcast("pause");
+	 */
+	broadcast(action: string, ...args: any[]): void {
+		for (const player of this.players.values()) {
+			if (typeof (player as any)[action] === "function") {
+				try {
+					(player as any)[action](...args);
+				} catch (error) {
+					this.debug(`Error broadcasting ${action} to ${player.guildId}:`, error);
+				}
+			}
+		}
+	}
+
+	/**
+	 * Destroy all players and clean up
 	 */
 	destroy(): void {
-		this.debug(`[PlayerManager] Destroying all players`);
+		this.debug(`Destroying all players`);
+
+		if (this.persistenceManager) {
+			this.persistenceManager.saveAll().catch((err) => {
+				this.debug("Failed to save players before destroy:", err);
+			});
+			this.persistenceManager.shutdown().catch(console.error);
+		}
+		// Stop cleanup intervals
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = null;
+		}
+
+		if (this.statsInterval) {
+			clearInterval(this.statsInterval);
+			this.statsInterval = null;
+		}
+
+		// Destroy all players
 		for (const player of this.players.values()) {
 			player.destroy();
 		}
+
 		this.players.clear();
+		this.searchCache.clear();
 		this.removeAllListeners();
+		this.debug(`PlayerManager destroyed`);
 	}
 
 	/**
@@ -385,27 +625,193 @@ export class PlayerManager extends EventEmitter {
 	 * @param {string} query - The query to search for
 	 * @param {string} requestedBy - The user ID who requested the search
 	 * @returns {Promise<SearchResult>} The search result
-	 * @example
-	 * const result = await manager.search("Never Gonna Give You Up", userId);
-	 * console.log(`Search result: ${result.tracks.length} tracks`);
 	 */
 	async search(query: string, requestedBy: string): Promise<SearchResult> {
-		this.debug(`[PlayerManager] Search called with query: ${query}, requestedBy: ${requestedBy}`);
+		this.debug(`Search called with query: ${query}, requestedBy: ${requestedBy}`);
+
+		// Check cache first
+		const cached = this.getCachedSearch(query);
+		if (cached) {
+			return cached;
+		}
+
 		const plugin = this.plugins.find((p) => p.canHandle(query));
 		if (!plugin) {
-			this.debug(`[PlayerManager] No plugin found to handle: ${query}`);
+			this.debug(`No plugin found to handle: ${query}`);
 			throw new Error(`No plugin found to handle: ${query}`);
 		}
 
 		try {
-			return await this.withTimeout(plugin.search(query, requestedBy), "Search operation timed out");
+			const result = await this.withTimeout(plugin.search(query, requestedBy), "Search operation timed out");
+			this.setCachedSearch(query, result);
+			return result;
 		} catch (error) {
-			this.debug(`[PlayerManager] Search error:`, error);
+			this.debug(`Search error:`, error);
 			throw error as Error;
 		}
 	}
+
+	/**
+	 * Clear search cache
+	 */
+	clearSearchCache(): void {
+		const size = this.searchCache.size;
+		this.searchCache.clear();
+		this.debug(`Cleared ${size} search cache entries`);
+	}
+
+	/**
+	 * Register a plugin after initialization
+	 *
+	 * @param {SourcePlugin} plugin - Plugin to register
+	 */
+	registerPlugin(plugin: SourcePlugin): void {
+		this.plugins.push(plugin);
+		this.debug(`Registered plugin: ${plugin.name}`);
+
+		// Register plugin with all existing players
+		for (const player of this.players.values()) {
+			player.addPlugin(plugin);
+		}
+	}
+
+	/**
+	 * Unregister a plugin
+	 *
+	 * @param {string} name - Plugin name to unregister
+	 * @returns {boolean} True if plugin was unregistered
+	 */
+	unregisterPlugin(name: string): boolean {
+		const index = this.plugins.findIndex((p) => p.name === name);
+		if (index === -1) return false;
+
+		this.plugins.splice(index, 1);
+		this.debug(`Unregistered plugin: ${name}`);
+
+		// Note: Cannot easily remove plugins from existing players
+		return true;
+	}
+
+	/**
+	 * Get all registered plugins
+	 */
+	getPlugins(): SourcePlugin[] {
+		return [...this.plugins];
+	}
+
+	/**
+	 * Register an extension after initialization
+	 *
+	 * @param {BaseExtension} extension - Extension to register
+	 */
+	registerExtension(extension: BaseExtension): void {
+		this.extensions.push(extension);
+		this.debug(`Registered extension: ${extension.name}`);
+
+		// Register extension with all existing players
+		for (const player of this.players.values()) {
+			player.attachExtension(extension);
+		}
+	}
+
+	/**
+	 * Get manager configuration
+	 */
+	getConfig(): object {
+		return {
+			extractorTimeout: this.extractorTimeout,
+			autoCleanup: this.autoCleanup,
+			cleanupTimeout: this.cleanupTimeout,
+			enableSearchCache: this.enableSearchCache,
+			pluginsCount: this.plugins.length,
+			extensionsCount: this.extensions.length,
+			playersCount: this.players.size,
+		};
+	}
+	private initPersistence(persistenceOptions: PersistenceOptions): void {
+		this.persistenceManager = new PersistenceManager(this, persistenceOptions);
+
+		const forwardEvents = {
+			playerSaved: "playerSaved",
+			playerLoaded: "playerLoaded",
+
+			playerSkipped: "RTSkipped",
+			playerMarkedDestroyed: "RTMarkedDestroyed",
+			playerDestroyedCleared: "RTDestroyedCleared",
+
+			savedAll: "savedAll",
+			loadedAll: "loadedAll",
+
+			backupsCleaned: "backupsCleaned",
+			allBackupsCleaned: "allBackupsCleaned",
+
+			backupStats: "backupStats",
+			backupCleanupDone: "backupCleanupDone",
+		} as const satisfies Record<string, keyof ManagerEvents>;
+
+		for (const [sourceEvent, targetEvent] of Object.entries(forwardEvents) as [
+			keyof typeof forwardEvents,
+			keyof ManagerEvents,
+		][]) {
+			this.persistenceManager.on(sourceEvent, (...args: any[]) => {
+				this.emit(targetEvent, ...(args as ManagerEvents[typeof targetEvent]));
+			});
+		}
+
+		this.debug("Persistence manager initialized");
+	}
+
+	isAutoRestoreEnabled(): boolean {
+		return this.persistenceManager?.isAutoRestoreEnabled() ?? false;
+	}
+
+	getDestroyedPlayers(): DestroyedRecord[] {
+		return this.persistenceManager?.getDestroyedPlayers() ?? [];
+	}
+
+	/**
+	 * Get persistence manager
+	 */
+	getPersistence(): PersistenceManager | undefined {
+		return this.persistenceManager;
+	}
+
+	/**
+	 * Save all players
+	 */
+	async saveAllPlayers(): Promise<Map<string, boolean>> {
+		if (!this.persistenceManager) {
+			throw new Error("Persistence not enabled");
+		}
+		return await this.persistenceManager.saveAll();
+	}
+
+	/**
+	 * Load all players
+	 */
+	async loadAllPlayers(restorePosition: boolean = true): Promise<Map<string, boolean>> {
+		if (!this.persistenceManager) {
+			throw new Error("Persistence not enabled");
+		}
+		return await this.persistenceManager.loadAll(restorePosition);
+	}
+
+	/**
+	 * Save a specific player
+	 */
+	async savePlayer(guildId: string): Promise<boolean> {
+		if (!this.persistenceManager) return false;
+		const player = this.get(guildId);
+		if (!player) return false;
+		return await this.persistenceManager.savePlayer(player);
+	}
 }
 
+/**
+ * Get the global PlayerManager instance
+ *
+ * @returns {PlayerManager | null} Global instance or null
+ */
 export function getInstance(): PlayerManager | null {
 	const globalInst = getGlobalManager();
 	if (!globalInst) {