pixel-ops

Theme Hospital-style isometric agent simulation for React. Visualize your AI agents, workers, or services as pixel art characters in an interactive campus.

Install

npm install pixel-ops pixi.js react react-dom

Quick Start

import { PixelOps, PixelOpsAdapter } from 'pixel-ops';
import 'pixel-ops/style.css';

class MyAdapter extends PixelOpsAdapter {
  connect() {
    this.emit('agent:status', { id: 'bot-1', status: 'working', task: 'Processing' });
  }
  disconnect() {}
}

function App() {
  const adapter = useMemo(() => new MyAdapter(), []);
  return (
    <PixelOps
      adapter={adapter}
      config={{
        agents: [
          { id: 'bot-1', name: 'Worker Bot', sprite: 'worker', defaultRoom: 'dev-office' },
        ],
        rooms: ['reception', 'dev-office', 'break-room'],
      }}
    />
  );
}

See the Getting Started Guide for a full walkthrough.

Features

• Isometric pixel art campus with 6 built-in rooms and customizable furniture
• Event adapter pattern — push state from any backend (REST, WebSocket, polling)
• 13 optional game systems — economy, weather, research, reputation, and more
• Drag-and-drop furniture editor with 64+ assets and layout persistence
• Speech bubbles that track above each agent's head in real time
• HUD overlays — budget bar, reputation meter, time controls, minimap, comms terminal
• Tree-shakeable — only import what you need

Adapter Events

Push state from your system into pixel-ops via the adapter:

Event	Payload	Description
agent:status	{ id, status, room?, task? }	Agent state change
agent:move	{ id, room }	Move agent to room
notification	{ level, message, agentId? }	Display notification
metric	{ key, value }	Update metric display
economy:transaction	{ amount, type, reason }	Economy event (opt-in)
research:progress	{ topicId, progress }	Research update (opt-in)
reputation:change	{ delta, reason }	Reputation change (opt-in)

See the Adapter Guide for details on building custom adapters.

Optional Systems

Enable game systems for richer simulation:

import { EconomySystem, WeatherSystem } from 'pixel-ops/systems';

<PixelOps
  config={{
    // ...agents and rooms...
    systems: [new EconomySystem(), new WeatherSystem()],
  }}
/>

Available systems: Economy, Weather, Research, Needs, Mood, Reputation, Time, IdleBehavior, Prestige, Events, Relationships, Awards, Sound.

See the Systems Guide for each system's events and configuration.

Custom Rooms

config={{
  customRooms: [{
    id: 'war-room',
    name: 'War Room',
    width: 6,
    height: 4,
    floor: 'metal',
    furniture: [
      { type: 'monitor-wall', gridX: 1, gridY: 1 },
      { type: 'conference-table', gridX: 3, gridY: 2 },
    ],
  }],
}}

See Configuration for all config options.

Built-in Sprites

worker, orchestrator, benchmark, self_improve, research, review, memory, indexer, mcp

Custom sprites: pass a URL via customSpriteUrl in agent config.

Documentation

Guide	Description
Getting Started	Installation, first adapter, mounting the component
Adapter Guide	Building adapters for WebSocket, REST, polling
Configuration	All config options, custom rooms, themes
Systems	Optional game systems and their events
UI Components	Overlay components for custom composition
Integration Examples	Real-world examples (CI/CD, Kubernetes, chat bots)
Assets	Sprite sheets, tilesets, furniture, custom assets

License

MIT

Assets include Kenney game assets (CC0).