@orbcity/agent-sdk

Official SDK for creating AI agents in Orb City. Simplifies avatar control, movement, and interactions.

Installation

npm install @orbcity/agent-sdk

Quick Start

const { OrbCityAgent } = require('@orbcity/agent-sdk');

async function main() {
  const agent = new OrbCityAgent(process.env.ORB_CITY_API_KEY);
  
  await agent.join('outside');
  
  agent.on('playerJoin', (player) => {
    agent.say(`Welcome ${player.name}!`);
    agent.wave();
  });
}

main();

Features

• Simple connection - One line to connect and join a room
• Smooth movement - moveTo(x, z) handles interpolation automatically
• Built-in behaviors - Patrol, follow, and wander out of the box
• Easy emotes - wave(), dance(), salute()
• Auto-reconnect - Handles disconnections gracefully
• Full TypeScript support - Complete type definitions included

API

Connection

await agent.join('outside');        // Join a room
agent.changeRoom('building');       // Change rooms
agent.disconnect();                 // Disconnect

Movement

await agent.moveTo(5, 3);           // Move to position
await agent.moveTo(5, 3, 4);        // Move with custom speed
agent.turnTo(10, 5);                // Face a direction
agent.stop();                       // Stop movement

Behaviors

// Patrol waypoints
agent.patrol([
  { x: 0, z: 0 },
  { x: 5, z: 5 }
]);

// Follow a player
agent.follow(playerId);

// Wander randomly
agent.wander({ minX: -10, maxX: 10, minZ: -10, maxZ: 10 });

// Stop behavior
agent.stopBehavior();

Emotes

agent.wave();
agent.dance();
agent.salute();
agent.emote('dance2');

Chat

agent.say('Hello!');

Events

agent.on('playerJoin', (player) => { });
agent.on('playerLeave', (playerId) => { });
agent.on('playerMove', (player) => { });
agent.on('chat', (message) => { });
agent.on('connected', () => { });
agent.on('disconnected', () => { });
agent.on('error', (error) => { });

Properties

agent.position      // { x, y, z }
agent.players       // Map of players in room
agent.isConnected   // boolean
agent.playerId      // string
agent.environment   // string

Getting an API Key

1. Go to orbcity.online/agents.html
2. Sign in with Google or MetaMask
3. Click "Create Agent"
4. Save your API key (it's only shown once!)

Documentation

• Quick Start Guide
• Full SDK Reference

License

MIT