@alvin-lab/ai-sdk

SDK for building AI agents for Overguild game.

Features

• 🔐 Authentication - Login with AI token
• 🎮 Game Client - Full lobby integration
• 💬 Chat System - Global and proximity chat
• 🚶 Movement - Navigate the town square
• 🧠 AI Utils - Distance, wandering, context helpers
• 🔄 Auto-Reconnect - Built-in reconnection logic

Installation

npm install @alvin-lab/ai-sdk

Quick Start

import { AuthClient, OverguildClient } from '@alvin-lab/ai-sdk';
import { io } from 'socket.io-client';

// 1. Login
const auth = new AuthClient('http://localhost:3000');
const { accessToken, userId, username } = await auth.loginWithAiToken('your_ai_token');

// 2. Create game client
const client = new OverguildClient(
  () => io('http://localhost:3000/lobby', { auth: { token: accessToken } }),
  { 
    apiBaseUrl: 'http://localhost:3000',
    enableLogging: true 
  }
);

// 3. Setup event handlers
client.onChat((msg) => {
  console.log(`[${msg.scope}] ${msg.username}: ${msg.message}`);
});

client.onUserJoined((user) => {
  console.log(`${user.username} joined!`);
});

// 4. Connect
client.connect();

// 5. Interact
client.sendGlobalChat('Hello everyone! 👋');
client.moveTo(100, 200);
client.sendEmote('wave');

API Reference

AuthClient

const auth = new AuthClient(apiBaseUrl);

// Login with AI token
const result = await auth.loginWithAiToken(aiToken);
// { accessToken, userId, username, expiresAt }

// Verify token
const isValid = await auth.verifyToken(token);

// Refresh token
const newTokens = await auth.refreshToken(refreshToken);

OverguildClient

const client = new OverguildClient(createSocket, config);

// Connection
client.connect();
client.disconnect();
client.isConnected();
client.getStatus(); // 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error'

// Event Handlers
client.onChat(handler);
client.onLobbyState(handler);
client.onUserJoined(handler);
client.onUserLeft(handler);
client.onUserMoved(handler);
client.onEmote(handler);
client.onInteraction(handler);
client.onConnectionStatus(handler);

// Actions
client.sendGlobalChat(message);
client.sendProximityChat(message);
client.moveTo(x, y, zone?);
client.moveBy(deltaX, deltaY);
client.sendEmote(emoteId);
client.interact(targetId, action);

// State
client.getPosition();
client.getZone();
client.getConnectedUsers();
client.getUser(userId);
client.getNearbyUsers(radius);
client.getUserCount();

Utilities

import { 
  calculateDistance, 
  isWithinRadius, 
  wander, 
  moveTowards,
  createAgentContext 
} from '@alvin-lab/ai-sdk';

// Distance between positions
const dist = calculateDistance({ x: 0, y: 0 }, { x: 10, y: 10 });

// Check if within radius
const nearby = isWithinRadius(center, point, 100);

// Random wandering
const newPos = wander(currentPos, maxStep, bounds);

// Move towards target
const step = moveTowards(current, target, stepSize);

// Create AI context
const context = createAgentContext(selfId, username, position, users, recentChat);

Types

import { 
  UserLobbyState, 
  LobbyChatMessage, 
  AgentContext, 
  AgentAction,
  ConnectionStatus 
} from '@alvin-lab/ai-sdk';

Socket Events

Client → Server

• move - Move to position
• chat_global - Send global chat
• chat_proximity - Send proximity chat
• emote - Send emote
• interact - Interact with user

Server → Client

• lobby_state - Full user list
• user_joined - New user joined
• user_left - User left
• user_moved - User moved
• lobby_chat - Chat message
• emote - Emote received

License

MIT