Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* The room graph, turned into a scene.
*
* Everything geometric about /home/:id is decided here, as a pure function of
* the graph `packages/home-bridge` already builds. No Three.js, no DOM, no
* clock: the same model drives the WebGL renderer and the 2D fallback, and a
* test can assert the whole layout of a real house without a GPU.
*
* Two rules shape it:
*
* 1. A real house has no geometry in Home Assistant. Areas and floors are
* registries with names and levels, and nothing else, so the default
* arrangement here has to be good enough to use before anyone authors a
* floorplan. Rooms are packed per floor in name order, which is stable
* across reconnects and matches how the list beside the scene reads.
* 2. A room with sixty entities is not sixty objects. People care about
* lights, locks, doors and temperature; a humidity sensor is a number,
* not a thing you walk up to. Objects are ranked, capped and the rest are
* summarized, so a busy room stays legible instead of becoming gravel.
*/
import { summarizeClimate, summarizeLighting, summarizeSecurity } from '../../packages/home-bridge/src/rooms.js';
/** Metres between floor slabs. Tall enough to read a room from the side. */
export const FLOOR_HEIGHT = 4.6;
/** One room occupies this cell; the room box sits inside it with a gap. */
export const CELL = 7.2;
const ROOM_GAP = 1.5;
const WALL_HEIGHT = 2.7;
/** Per room, before the rest is summarized into a readout. */
const MAX_CEILING = 6;
const MAX_WALL = 10;
const MAX_FLOOR = 6;
/**
* What a person cares about first, in order. Ranking is the whole reason a
* sixty-entity room is readable: the cap below cuts from the bottom of this
* list, never from the top, so the lights and the locks are always drawn.
*/
const RANK = {
light: 0,
lock: 1,
cover: 2,
climate: 3,
alarm_control_panel: 4,
media_player: 5,
fan: 6,
camera: 7,
vacuum: 8,
switch: 9,
binary_sensor: 10,
sensor: 11,
};
/** Binary sensors that are openings: they belong to the security story. */
const OPENING_CLASSES = new Set(['door', 'window', 'garage_door', 'opening']);
/**
* Where a domain lives in a room. Ceiling objects hang, wall objects mount on
* the perimeter, floor objects stand on the slab. This is the only place that
* decides it, so the renderer and the fallback legend cannot disagree.
*/
export function placementOf(entity) {
const domain = entity?.domain;
if (domain === 'light') return 'ceiling';
if (domain === 'fan') return entity.deviceClass === 'ceiling' || /ceiling/i.test(entity.name || '') ? 'ceiling' : 'floor';
if (domain === 'cover' || domain === 'lock' || domain === 'camera' || domain === 'switch') return 'wall';
if (domain === 'media_player' || domain === 'alarm_control_panel') return 'wall';
if (domain === 'binary_sensor') return OPENING_CLASSES.has(entity.deviceClass) ? 'wall' : null;
if (domain === 'climate' || domain === 'vacuum') return 'floor';
return null;
}
/**
* The visual kind the renderer draws. Deliberately coarser than the domain: a
* `switch` and a `media_player` are both panels on a wall, and giving each
* domain its own mesh would be a bestiary nobody can read at a glance.
*/
export function kindOf(entity) {
switch (entity.domain) {
case 'light':
return 'lamp';
case 'fan':
return 'fan';
case 'lock':
return 'lock';
case 'cover':
return entity.deviceClass === 'garage' || entity.deviceClass === 'door' ? 'door' : 'window';
case 'binary_sensor':
return entity.deviceClass === 'garage_door' || entity.deviceClass === 'door' ? 'door' : 'window';
case 'climate':
return 'thermostat';
case 'media_player':
return 'screen';
case 'camera':
return 'camera';
case 'alarm_control_panel':
return 'alarm';
case 'vacuum':
return 'puck';
case 'switch':
return 'plate';
default:
return 'plate';
}
}
/**
* Is this entity currently "active" in the way its kind means it?
*
* A light is on, a cover is open, a lock is UNLOCKED, a media player is
* playing. The lock inversion is deliberate and load-bearing: unlocked is the
* state a person needs to spot from across the room, so it is the one that
* lights up.
*/
export function activityOf(entity) {
const state = entity.state;
if (state === 'unavailable' || state === 'unknown') return 0;
switch (entity.domain) {
case 'light':
case 'switch':
case 'fan':
return state === 'on' ? 1 : 0;
case 'lock':
return state === 'unlocked' || state === 'open' || state === 'opening' ? 1 : 0;
case 'cover': {
const position = Number(entity.attributes?.current_position);
if (Number.isFinite(position)) return clamp01(position / 100);
return state === 'open' || state === 'opening' ? 1 : 0;
}
case 'binary_sensor':
return state === 'on' ? 1 : 0;
case 'media_player':
return state === 'playing' ? 1 : state === 'paused' || state === 'on' ? 0.5 : 0;
case 'climate':
return state && state !== 'off' ? 1 : 0;
case 'vacuum':
return state === 'cleaning' || state === 'returning' ? 1 : 0;
case 'alarm_control_panel':
return state && state !== 'disarmed' ? 1 : 0;
default:
return 0;
}
}
/** True when Home Assistant is telling us this device is not answering. */
export function isUnavailable(entity) {
return entity.state === 'unavailable' || entity.state === 'unknown' || entity.state == null;
}
/**
* The room's own light: what colour it is and how bright, from the lights that
* are actually on. `summarizeLighting` already averages brightness and colour;
* this turns that into something a renderer and a CSS gradient can both use.
*
* Off means genuinely dark. A room whose lights are all off must not read as
* "dimmed": that is the difference between a model of a house and a picture of
* one.
*/
export function lightOf(room) {
const lighting = room.lighting || { total: 0, on: 0, brightness: 0, rgb: null };
const on = lighting.on > 0;
const brightness = on ? clamp01(lighting.brightness || 0.8) : 0;
const rgb = on ? lighting.rgb || [255, 236, 202] : [120, 132, 168];
return {
on,
total: lighting.total,
count: lighting.on,
brightness,
rgb,
hex: rgbToHex(rgb),
// A dark room still needs enough ambient to be readable, so the floor of
// the range is the moonlight a screen has to have, not zero.
intensity: on ? 0.35 + brightness * 1.5 : 0.06,
};
}
/**
* Warm or cool, from the room's own measured temperature. Neutral below the
* comfort band's width so an ordinary room is not permanently tinted.
*/
export function climateOf(room, unit = null) {
const climate = room.climate;
if (!climate || !Number.isFinite(climate.temperature)) return null;
const t = climate.temperature;
// The comfort band is centred where the house measures it. Home Assistant
// reports whatever unit the instance is configured in, so a Fahrenheit house
// must not read as permanently freezing because 70 is nowhere near 21.
const fahrenheit = String(unit || '').includes('F');
const centre = fahrenheit ? 70 : 21;
const span = fahrenheit ? 11 : 6;
const offset = clamp(-1, 1, (t - centre) / span);
return {
temperature: t,
sources: climate.sources,
unit: unit || null,
// -1 fully cool, +1 fully warm. The renderer and the 2D card both read it.
tint: Number(offset.toFixed(3)),
label: `${t.toFixed(1)}${unit || '°'}`,
};
}
/** Sensors are numbers, not objects: they become one readout line per room. */
export function readoutsOf(entities) {
const out = [];
for (const entity of entities) {
if (entity.domain !== 'sensor') continue;
const value = Number(entity.state);
if (!Number.isFinite(value)) continue;
out.push({
entityId: entity.entityId,
name: entity.name,
deviceClass: entity.deviceClass || null,
value,
unit: entity.attributes?.unit_of_measurement || '',
});
}
return out.sort((a, b) => String(a.name).localeCompare(String(b.name))).slice(0, 6);
}
/**
* Build the scene.
*
* @param {object} graph the room graph from buildHomeGraph()
* @param {object} [options]
* @param {string} [options.focusRoomId] the room the camera and the agent are on
* @param {Record<string, {x:number,z:number,w?:number,d?:number}>} [options.layout]
* an authored floorplan (order 07). Absent, rooms pack by floor in name order.
* @returns {object} the scene model
*/
export function buildSceneModel(graph, options = {}) {
const source = graph && typeof graph === 'object' ? graph : {};
const rawRooms = Array.isArray(source.rooms) ? source.rooms : [];
const unassigned = Array.isArray(source.unassigned) ? source.unassigned : [];
const layout = options.layout || null;
// Every entity the house has that nobody put in an area is still somebody's
// device. A house with zero assigned areas is the common case, not an edge
// case, so it renders as one honest room rather than a blank floor.
const rooms = [...rawRooms];
if (unassigned.length) {
rooms.push({
id: '__unassigned__',
name: rawRooms.length ? 'Not in a room' : 'Everything',
floorId: null,
icon: null,
synthetic: true,
entities: unassigned,
// The rollups a real area gets, applied to the bucket nobody filed.
// Same functions the graph builder uses, so one shape flows through.
lighting: summarizeLighting(unassigned),
climate: summarizeClimate(unassigned, source.temperatureUnit || null),
secured: summarizeSecurity(unassigned),
});
}
const floors = planFloors(source.floors, rooms);
const placed = [];
for (const floor of floors) {
const cells = packCells(floor.rooms.length);
floor.rooms.forEach((room, index) => {
const authored = layout?.[room.id];
const cell = cells[index];
const x = Number.isFinite(authored?.x) ? authored.x : cell.x * CELL;
const z = Number.isFinite(authored?.z) ? authored.z : cell.z * CELL;
placed.push(buildRoom(room, { ...floor, temperatureUnit: source.temperatureUnit || null }, { x, z, w: authored?.w, d: authored?.d }));
});
}
const bounds = boundsOf(placed);
const focusRoomId = pickFocusRoom(placed, options.focusRoomId);
const drawn = placed.reduce((n, r) => n + r.objects.length, 0);
const total = placed.reduce((n, r) => n + r.entityCount, 0);
return {
floors: floors.map((f) => ({ id: f.id, name: f.name, level: f.level, y: f.y, roomIds: f.rooms.map((r) => r.id) })),
rooms: placed,
// The unit the HOUSE measures in, as the instance itself reports it, so
// every readout in every view can print it. Never derived from the
// visitor's locale: a Fahrenheit house read in French is still Fahrenheit,
// and a thermostat labelled with the wrong unit is a number that means
// nothing. Null when the instance did not say, and a bare degree sign is
// then the honest answer.
temperatureUnit: source.temperatureUnit || null,
bounds,
focusRoomId,
agent: agentStand(placed, focusRoomId),
// A house where nothing is assigned to an area is a designed state, not a
// failure, and the page has to be able to tell the two apart.
needsLayout: rawRooms.length === 0 && unassigned.length > 0,
empty: total === 0,
stats: { floors: floors.length, rooms: placed.length, entities: total, drawn, summarized: total - drawn },
};
}
/** Floors, with every room slotted onto one, ordered by level then by name. */
function planFloors(rawFloors, rooms) {
const declared = (Array.isArray(rawFloors) ? rawFloors : []).map((f) => ({
id: f.id,
name: f.name,
level: Number.isFinite(f.level) ? f.level : 0,
rooms: [],
}));
const byId = new Map(declared.map((f) => [f.id, f]));
let loose = null;
for (const room of [...rooms].sort(byName)) {
const floor = room.floorId && byId.get(room.floorId);
if (floor) {
floor.rooms.push(room);
continue;
}
// A house with no floor registry, or a room nobody placed on a floor.
// It joins the lowest declared floor rather than getting a phantom one
// beneath the house: a floor labelled "Unplaced" hanging under the ground
// floor reads as a basement the user does not have, and it dragged the
// default camera and the agent down into it.
if (!loose) {
loose = lowestFloor(declared) || { id: '__ground__', name: 'Home', level: 0, rooms: [] };
if (!byId.has(loose.id)) {
declared.push(loose);
byId.set(loose.id, loose);
}
}
loose.rooms.push(room);
}
const used = declared.filter((f) => f.rooms.length).sort((a, b) => a.level - b.level || String(a.name).localeCompare(String(b.name)));
used.forEach((floor, index) => {
floor.y = index * FLOOR_HEIGHT;
});
return used;
}
function lowestFloor(floors) {
return floors.reduce((low, f) => (!low || f.level < low.level ? f : low), null);
}
/**
* Pack n rooms into a grid centred on the origin. Wider than tall, because a
* screen is, and a house read from a 3/4 camera reads better in rows.
*/
export function packCells(n) {
// Never wider than there are rooms: the 1.35 bias makes a grid landscape,
// but applied to a single-room house it produced a two-column grid with one
// room sitting half a cell off centre.
const cols = Math.max(1, Math.min(n, Math.ceil(Math.sqrt(n * 1.35))));
const rows = Math.max(1, Math.ceil(n / cols));
const out = [];
for (let i = 0; i < n; i += 1) {
const col = i % cols;
const row = Math.floor(i / cols);
out.push({ x: col - (cols - 1) / 2, z: row - (rows - 1) / 2 });
}
return out;
}
function buildRoom(room, floor, cell) {
const entities = Array.isArray(room.entities) ? room.entities : [];
const w = Number.isFinite(cell.w) ? cell.w : CELL - ROOM_GAP;
const d = Number.isFinite(cell.d) ? cell.d : CELL - ROOM_GAP;
const ranked = [...entities].sort(
(a, b) => (RANK[a.domain] ?? 99) - (RANK[b.domain] ?? 99) || String(a.name).localeCompare(String(b.name)),
);
const slots = { ceiling: [], wall: [], floor: [] };
const caps = { ceiling: MAX_CEILING, wall: MAX_WALL, floor: MAX_FLOOR };
const overflow = [];
for (const entity of ranked) {
const where = placementOf(entity);
if (!where) continue;
if (slots[where].length >= caps[where]) {
overflow.push(entity);
continue;
}
slots[where].push(entity);
}
const objects = [];
slots.ceiling.forEach((entity, i) => objects.push(placeObject(entity, ceilingSlot(i, slots.ceiling.length, w, d))));
slots.wall.forEach((entity, i) => objects.push(placeObject(entity, wallSlot(i, slots.wall.length, w, d))));
slots.floor.forEach((entity, i) => objects.push(placeObject(entity, floorSlot(i, slots.floor.length, w, d))));
const secured = room.secured || null;
return {
id: room.id,
name: room.name,
floorId: floor.id,
level: floor.level,
synthetic: Boolean(room.synthetic),
x: cell.x,
y: floor.y,
z: cell.z,
w,
d,
h: WALL_HEIGHT,
light: lightOf(room),
climate: climateOf(room, floor.temperatureUnit),
security: secured
? { ...secured, unlocked: secured.unlocked || [], open: secured.open || [] }
: null,
objects,
readouts: readoutsOf(entities),
entityCount: entities.length,
hiddenCount: overflow.length,
unavailableCount: entities.filter(isUnavailable).length,
};
}
function placeObject(entity, slot) {
return {
entityId: entity.entityId,
name: entity.name,
domain: entity.domain,
deviceClass: entity.deviceClass || null,
kind: kindOf(entity),
placement: slot.placement,
x: round(slot.x),
y: round(slot.y),
z: round(slot.z),
rotation: round(slot.rotation),
state: entity.state,
activity: activityOf(entity),
available: !isUnavailable(entity),
attributes: entity.attributes || {},
};
}
/** Ceiling objects hang in a row across the room, just under the slab. */
function ceilingSlot(i, n, w, d) {
const span = w * 0.62;
const x = n === 1 ? 0 : -span / 2 + (span * i) / (n - 1);
return { placement: 'ceiling', x, y: WALL_HEIGHT - 0.42, z: n > 3 && i % 2 ? d * 0.16 : -d * 0.12, rotation: 0 };
}
/**
* Wall objects walk the perimeter clockwise from the front-left corner, so two
* doors never land on the same spot and a room reads the same way every time
* it rebuilds.
*/
function wallSlot(i, n, w, d) {
const perimeter = 2 * (w + d);
const t = ((i + 0.5) / Math.max(1, n)) * perimeter;
const halfW = w / 2 - 0.12;
const halfD = d / 2 - 0.12;
const y = 1.15;
if (t < w) return { placement: 'wall', x: -halfW + (t / w) * (w - 0.24), y, z: -halfD, rotation: 0 };
if (t < w + d) return { placement: 'wall', x: halfW, y, z: -halfD + ((t - w) / d) * (d - 0.24), rotation: -Math.PI / 2 };
if (t < 2 * w + d) return { placement: 'wall', x: halfW - ((t - w - d) / w) * (w - 0.24), y, z: halfD, rotation: Math.PI };
return { placement: 'wall', x: -halfW, y, z: halfD - ((t - 2 * w - d) / d) * (d - 0.24), rotation: Math.PI / 2 };
}
/** Floor objects stand in a shallow arc toward the front of the room. */
function floorSlot(i, n, w, d) {
const span = w * 0.5;
const x = n === 1 ? 0 : -span / 2 + (span * i) / (n - 1);
return { placement: 'floor', x, y: 0, z: d * 0.24, rotation: 0 };
}
function boundsOf(rooms) {
if (!rooms.length) return { minX: -CELL, maxX: CELL, minZ: -CELL, maxZ: CELL, minY: 0, maxY: FLOOR_HEIGHT, width: CELL * 2, depth: CELL * 2 };
let minX = Infinity;
let maxX = -Infinity;
let minZ = Infinity;
let maxZ = -Infinity;
let maxY = 0;
for (const room of rooms) {
minX = Math.min(minX, room.x - room.w / 2);
maxX = Math.max(maxX, room.x + room.w / 2);
minZ = Math.min(minZ, room.z - room.d / 2);
maxZ = Math.max(maxZ, room.z + room.d / 2);
maxY = Math.max(maxY, room.y + room.h);
}
return { minX, maxX, minZ, maxZ, minY: 0, maxY, width: maxX - minX, depth: maxZ - minZ };
}
function pickFocusRoom(rooms, requested) {
if (requested && rooms.some((r) => r.id === requested)) return requested;
if (!rooms.length) return null;
// Default to the busiest real room on the lowest floor: it is where a person
// walks in, and it is the room most likely to make the first frame legible.
// The unassigned bucket is never the default focus while a real room exists,
// however many entities it holds, because it is a filing cabinet and not a
// place in the house.
const real = rooms.filter((r) => !r.synthetic);
const pool0 = real.length ? real : rooms;
const lowest = Math.min(...pool0.map((r) => r.level));
const candidates = pool0.filter((r) => r.level === lowest);
const pool = candidates.length ? candidates : pool0;
return pool.reduce((best, room) => (room.objects.length > best.objects.length ? room : best), pool[0]).id;
}
/** Where the agent's body stands, and which way it faces. */
function agentStand(rooms, focusRoomId) {
const room = rooms.find((r) => r.id === focusRoomId) || rooms[0];
if (!room) return { roomId: null, x: 0, y: 0, z: 0, facing: 0 };
return {
roomId: room.id,
x: round(room.x - room.w * 0.22),
y: room.y,
z: round(room.z + room.d * 0.2),
// Facing out of the room toward the default camera, so it reads as
// standing in the house and looking at you rather than at a wall.
facing: 0,
};
}
/**
* Diff two scene models by entity id. The renderer uses it to touch only what
* changed: a burst of a hundred state updates must not rebuild a hundred
* meshes, and a ten-minute session must not grow the heap by one object.
*/
export function diffScene(previous, next) {
const before = objectIndex(previous);
const after = objectIndex(next);
const changed = [];
const added = [];
const removed = [];
for (const [id, object] of after) {
const old = before.get(id);
if (!old) {
added.push(object);
continue;
}
if (old.activity !== object.activity || old.state !== object.state || old.available !== object.available) changed.push(object);
}
for (const [id, object] of before) if (!after.has(id)) removed.push(object);
const roomsChanged = [];
const beforeRooms = new Map((previous?.rooms || []).map((r) => [r.id, r]));
for (const room of next?.rooms || []) {
const old = beforeRooms.get(room.id);
if (!old) {
roomsChanged.push(room.id);
continue;
}
if (
old.light.intensity !== room.light.intensity ||
old.light.hex !== room.light.hex ||
old.climate?.temperature !== room.climate?.temperature ||
old.security?.secure !== room.security?.secure
) {
roomsChanged.push(room.id);
}
}
return { added, changed, removed, roomsChanged };
}
function objectIndex(model) {
const map = new Map();
for (const room of model?.rooms || []) for (const object of room.objects) map.set(object.entityId, object);
return map;
}
// ── small helpers ────────────────────────────────────────────────────────────
function byName(a, b) {
return String(a.name).localeCompare(String(b.name));
}
function clamp01(n) {
return clamp(0, 1, n);
}
function clamp(min, max, n) {
return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : min;
}
function round(n) {
return Math.round(n * 1000) / 1000;
}
export function rgbToHex(rgb) {
const [r, g, b] = rgb;
return `#${[r, g, b].map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('')}`;
}