@elvenvtt/client

Standalone Node.js client for Elven VTT game tables. Connect to sessions, sync state, control actors -- no browser or DOM required.

Install

npm install @elvenvtt/client yjs

Quick Start

import { ElvenBot } from '@elvenvtt/client';

const bot = new ElvenBot({
  token: process.env.BOT_TOKEN,
});

bot.onSession((session) => {
  console.log(`Joined: ${session.name}`);
  session.sendChat('Bot is online!');
});

bot.onChat((msg, session) => {
  const text = msg.message?.text || msg.text || '';
  if (text === '!ping') {
    session.sendChat('Pong!');
  }
});

await bot.start();

Getting a Bot Token

1. Open the Elven desktop app
2. Go to God Mode (developer panel)
3. Create a new bot workspace -- a token is generated automatically

Or register via the API:

POST https://sync.elvenvtt.com/api/bots
Authorization: Bearer <firebase-id-token>
Body: { "name": "My Bot" }
Response: { "botId": "bot_xxx", "token": "eb_live_xxx" }

API

ElvenBot

const bot = new ElvenBot({
  token: string,          // Bot token (from .env)
  logLevel?: string,      // 'debug' | 'info' | 'warn' | 'error' (default: 'info')
  discoveryInterval?: number, // How often to check for new sessions (ms, default: 30000)
});

await bot.start();        // Connect to all invited sessions
await bot.stop();         // Disconnect from all sessions
bot.connectionCount;      // Number of active session connections

Events

bot.onSession((session) => { ... });          // Joined a session
bot.onSessionRemoved((sessionId) => { ... }); // Removed from a session
bot.onChat((msg, session) => { ... });        // Chat message received
bot.onAny((event, data, session) => { ... }); // Any ephemeral event

BotSession

session.sessionId;           // Session ID
session.name;                // Session name
session.sendChat(text);      // Send chat message
session.emit(event, data);   // Send ephemeral event
session.on(event, handler);  // Listen for ephemeral events
session.getCombat();         // Get combat state

ActorAPI (session.actors)

session.actors.getAll();                    // Get all actors
session.actors.get(id);                     // Get actor by ID
session.actors.create({ name, x, y, ... }); // Create actor
session.actors.update(id, changes);         // Update actor properties
session.actors.move(id, { x, y });          // Move actor
session.actors.delete(id);                  // Delete actor
session.actors.damage(id, amount);          // Deal damage
session.actors.heal(id, amount);            // Heal
session.actors.setHp(id, hp, maxHp?);      // Set HP directly
session.actors.addCondition(id, name);      // Add condition
session.actors.removeCondition(id, name);   // Remove condition
session.actors.clearConditions(id);         // Clear all conditions
session.actors.onChange(handler);            // Actor state changed

License

MIT