Virtual Clients

A massive architectural advantage of PaindaProtocol is its native support for headless WebSocket connections via PPVirtualClient.

What is a Virtual Client?

A Virtual Client behaves exactly like a real user connecting over a WebSocket. It triggers your rate limiters, auth middleware, and presence mechanisms. However, it completely bypasses the physical network stack. The connection occurs synchronously in memory.

Why Use Virtual Clients?

• AI Game Bots: Connect NPCs to your game world without wasting open file descriptors or loopback network sockets.
• End-to-End Testing: Spin up hundreds of test clients synchronously within Jest or Vitest without starting a real HTTP server.
• SSR Data Hydration: Have a Next.js server component transparently connect, fetch the lobby state, and render it server-side.

Basic Integration

To connect a Virtual Client, initialize it and simply pass your active PPServer instance to the connect() method.

import { PPServer, PPVirtualClient } from "@painda/core";

const server = new PPServer({ port: 3000 });

// 1. Create a headless client
const bot = new PPVirtualClient("AI_BOT_01");

// 2. Setup listeners (just like a real client)
bot.on("game:state", (state) => {
   console.log("Bot sees the state:", state);
});

// 3. Inject it straight into the server pipeline
bot.connect(server);

// 4. Send messages seamlessly
bot.send({ type: "player:move", payload: { x: 10, y: 10 } });

Middleware Pipeline

Virtual Clients pass through identical middleware to real clients. This ensures your bots respect Authentication schemas, bans, and custom connection rules. We simulate the source IP of a virtual client as 127.0.0.1 to safely pass standard validations.