Skip to content

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.

8.8 KB
Raw Blame
// Forge-in-world: turn a text prompt (or a reference photo) into a placeable
// GLB prop without leaving /play. This module is the network half only; it
// drives the same free draft lane the /forge page uses (POST /api/forge →
// poll GET /api/forge?job=) and resolves to a durable R2-hosted GLB URL that
// the multiplayer server's asset allow-list accepts, so the finished model can
// ride the existing obj:spawn channel and appear for everyone in the world.
// The UI/placement half lives in coincommunities.js (_forgeProp) and reuses
// the uploaded-prop pipeline (world-objects.js registerUploadedProp).

import { log } from '../shared/log.js';
import { coldStartLabel } from '../shared/forge-frames.js';

const SUBMIT_URL = '/api/forge';
const UPLOAD_URL = '/api/forge-upload';
const POLL_MS = 2500;
// Draft-tier generations land in ~30-60s; leave generous headroom for a cold
// GPU start (the submit response advertises 90s of cold-start alone).
const MAX_WAIT_MS = 6 * 60 * 1000;
const IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp']);
const MAX_IMAGE_BYTES = 8 * 1024 * 1024; // mirrors /api/forge-upload's cap

// Same anonymous handle the /forge page keys creations to, so items forged
// in-world show up in the same gallery/history as the rest of this browser's
// forges instead of forming a disconnected second identity.
function forgeClientId() {
	const KEY = 'forge:cid';
	try {
		let id = localStorage.getItem(KEY);
		if (!id) {
			id =
				crypto?.randomUUID?.() ||
				`c-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
			localStorage.setItem(KEY, id);
		}
		return id;
	} catch {
		return `c-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
	}
}

function headers(extra = {}) {
	return { 'x-forge-client': forgeClientId(), ...extra };
}

// A short palette-friendly display name for the forged prop.
export function forgePropName(prompt, file) {
	const base = String(prompt || '').trim() || String(file?.name || '').replace(/\.[a-z0-9]+$/i, '');
	// Trim after clamping so a cut mid-phrase does not leave a dangling space.
	return ((base || 'Forged item').slice(0, 24).trim()) || 'Forged item';
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

function throwIfAborted(signal) {
	if (signal?.aborted) throw new ForgeError('Forge cancelled.', { cancelled: true });
}

/** Error with user-facing message plus machine flags (rateLimited/cancelled). */
export class ForgeError extends Error {
	constructor(message, { rateLimited = false, cancelled = false } = {}) {
		super(message);
		this.name = 'ForgeError';
		this.rateLimited = rateLimited;
		this.cancelled = cancelled;
	}
}

async function readJson(res) {
	try { return await res.json(); } catch { return {}; }
}

function submitError(res, data) {
	if (res.status === 429) {
		return new ForgeError('The forge is busy right now. Give it a minute and try again.', { rateLimited: true });
	}
	const detail = typeof data?.error === 'string' && data.error.length < 200 ? data.error : '';
	return new ForgeError(detail ? `The forge refused that: ${detail}` : 'The forge could not take that request.');
}

// Push the reference image into forge storage via the presigned-PUT path the
// /forge page uses, returning a public URL /api/forge accepts in image_urls.
async function uploadReferenceImage(file, { onStatus, signal } = {}) {
	if (!IMAGE_TYPES.has(file.type)) {
		throw new ForgeError('Reference images must be a PNG, JPEG, or WebP.');
	}
	if (file.size > MAX_IMAGE_BYTES) {
		throw new ForgeError('That image is over 8 MB. Shrink it and try again.');
	}
	onStatus?.('Uploading your reference image…');
	const presign = await fetch(UPLOAD_URL, {
		method: 'POST',
		headers: headers({ 'content-type': 'application/json' }),
		body: JSON.stringify({ content_type: file.type, size_bytes: file.size }),
		signal,
	});
	const grant = await readJson(presign);
	if (!presign.ok || !grant.upload_url || !grant.public_url) {
		if (presign.status === 503) {
			throw new ForgeError('Image uploads are unavailable right now. Try a text prompt instead.');
		}
		throw submitError(presign, grant);
	}
	const put = await fetch(grant.upload_url, {
		method: grant.method || 'PUT',
		headers: grant.headers || { 'content-type': file.type },
		body: file,
		signal,
	});
	if (!put.ok) throw new ForgeError('The image upload failed. Check your connection and try again.');
	return grant.public_url;
}

// One progress line from a real /api/forge frame. Every number here is read off
// the payload; nothing is timed locally, so a slow job reports its own age
// rather than the tab's.
//
// Two states this used to flatten into "waiting for a slot":
//   • A scale-to-zero GPU worker booting. That is a nameable wait with a stated
//     budget, not an anonymous queue (coldStartLabel owns that wording, shared
//     with the homepage chamber and the Studio so the three cannot drift).
//   • The countdown. It printed `eta_seconds`, the lane's static TOTAL, on every
//     frame, so a two-minute wait read as a bar stuck at the same "~60s" the
//     whole time. `eta_remaining_seconds` is the live figure and leads now.
function statusLine(job = {}) {
	const cold = coldStartLabel(job);
	if (cold) return `${cold}, then forging…`;
	const num = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Math.round(Number(v)) : null);
	const remaining = num(job.eta_remaining_seconds) ?? num(job.eta_seconds);
	const elapsed = num(job.elapsed_seconds);
	// Elapsed is only worth showing once it means something; under 5s it just
	// flickers as the first polls land.
	const notes = [elapsed && elapsed >= 5 ? `${elapsed}s in` : null, remaining ? `~${remaining}s left` : null].filter(
		Boolean,
	);
	const suffix = notes.length ? ` (${notes.join(', ')})` : '';
	return job.status === 'queued'
		? `Forging: waiting for a slot${suffix}…`
		: `Forging your model${suffix}…`;
}

/**
 * Generate a placeable 3D prop from a prompt and/or reference image.
 * Resolves once the free draft lane finishes and the GLB has a stable URL.
 *
 * @param {object} req
 * @param {string} [req.prompt]  what to forge (3+ chars; required without a file)
 * @param {File}   [req.file]    optional reference image (png/jpeg/webp ≤ 8 MB)
 * @param {(msg: string) => void} [req.onStatus]  live progress line for the UI
 * @param {AbortSignal} [req.signal]
 * @returns {Promise<{url: string, name: string, durable: boolean, creationId: string|null}>}
 * @throws {ForgeError} with a user-facing message on every failure path
 */
export async function forgeWorldProp({ prompt = '', file = null, onStatus, signal } = {}) {
	const text = String(prompt || '').trim();
	if (!file && text.length < 3) {
		throw new ForgeError('Describe the item in a few words (or attach a photo).');
	}

	const body = { tier: 'draft', path: 'image' };
	if (file) {
		body.image_urls = [await uploadReferenceImage(file, { onStatus, signal })];
		if (text) body.prompt = text;
	} else {
		body.prompt = text;
	}

	throwIfAborted(signal);
	onStatus?.('Sending to the forge…');
	const res = await fetch(SUBMIT_URL, {
		method: 'POST',
		headers: headers({ 'content-type': 'application/json' }),
		body: JSON.stringify(body),
		signal,
	});
	const data = await readJson(res);
	if (!res.ok) throw submitError(res, data);

	const name = forgePropName(text, file);
	if (data.status === 'done' && data.glb_url) {
		return { url: data.glb_url, name, durable: data.durable !== false, creationId: data.creation_id || null };
	}
	if (!data.job_id) throw new ForgeError('The forge did not accept that request. Try rephrasing it.');

	onStatus?.(statusLine({ ...data, status: 'queued' }));
	const deadline = Date.now() + MAX_WAIT_MS;
	while (Date.now() < deadline) {
		throwIfAborted(signal);
		await sleep(POLL_MS);
		throwIfAborted(signal);
		let poll;
		try {
			poll = await fetch(`${SUBMIT_URL}?job=${encodeURIComponent(data.job_id)}`, { headers: headers(), signal });
		} catch (err) {
			if (signal?.aborted) throw new ForgeError('Forge cancelled.', { cancelled: true });
			// A dropped poll is not a dropped job: the generation keeps running
			// server-side, so ride out transient network blips and poll again.
			log.warn('[forge-prop] poll transport error, retrying:', err?.message || err);
			continue;
		}
		if (poll.status === 429) { onStatus?.('Forging: easing off the status checks…'); await sleep(POLL_MS * 2); continue; }
		const job = await readJson(poll);
		if (job.status === 'done' && job.glb_url) {
			return { url: job.glb_url, name, durable: job.durable !== false, creationId: job.creation_id || null };
		}
		if (job.status === 'failed') {
			const detail = typeof job.error === 'string' && job.error.length < 200 ? job.error : '';
			throw new ForgeError(detail ? `The forge could not build that: ${detail}` : 'The forge could not build that. Try different wording.');
		}
		onStatus?.(statusLine(job));
	}
	throw new ForgeError('The forge is taking too long. Your item may still finish in the /forge gallery.');
}