Server Plugin API Reference

interface PluginDefinition {
  name: string;
  version: string;
  author?: string;
  description?: string;
  register(ctx: PluginContext): void | Promise<void>;
  unregister?(): void | Promise<void>;
}

interface PluginContext {
  // Event System
  eventBus: EventBus;
  // Subscribe: eventBus.on(event, handler)

  // Entities & Zones (read-only)
  entities: EntityRegistry;
  zones: ZoneManager;

  // Chat Commands
  registerCommand(
    name: string,
    handler: CommandHandler,
    options?: CommandOptions
  ): void;

  // Custom Intents
  registerIntent(
    intentType: string,
    handler: IntentHandler
  ): void;

  // Messaging
  sendSystemMessage(entityId: string, msg: string): void;
  broadcastSystemMessage(msg: string): void;

  // Client Communication
  sendToClient(entityId: string, channel: string, data: any): void;
  broadcastToClients(channel: string, data: any): void;
  onClientMessage(
    channel: string,
    handler: (entityId: string, data: any) => void | Promise<void>
  ): () => void;

  // Timers
  setInterval(cb: () => void, ms: number): () => void;
  setTimeout(cb: () => void, ms: number): () => void;

  // Data Store
  getData<T>(key: string): T | undefined;
  setData<T>(key: string, value: T): void;

  // Logging
  log: PluginLogger;
}

type CommandHandler = (
  entityId: string,
  args: string[],
  rawMessage: string
) => void | Promise<void>;

interface CommandOptions {
  description?: string;
  usage?: string;
  minArgs?: number;
  adminOnly?: boolean;
}

type IntentHandler = (
  entityId: string,
  data: any
) => void | Promise<void>;

interface PluginLogger {
  info(msg: string, ...args: any[]): void;
  warn(msg: string, ...args: any[]): void;
  error(msg: string, ...args: any[]): void;
  debug(msg: string, ...args: any[]): void;
}