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
// Forge Workflows: what each node actually does.
//
// Every executor calls a real three.ws endpoint (or the user's own Modly app on
// localhost) and returns { outputs, result }. `outputs` feeds the next node;
// `result` is what the node card shows (a viewer, a download, a saved link).
//
// Contracts used, all documented in docs/forge-workflows.md:
// POST /api/forge generate (text or image) GET ?job= poll
// POST /api/forge?action=rig auto-rig GET ?job= poll
// POST /api/forge-remesh | -segment | -stylize | -gameready GET ?job= poll
// POST /api/forge-upload presigned PUT for a photo
// POST /api/scene-glb-upload presigned PUT for a GLB
// POST /api/avatars/from-forge save to the signed-in library
// POST /api/creations {op:'publish'} publish to the public gallery
import { StepError } from './runner.js';
import { attachTierPass, getAccess, getTierPass } from '../three-access.js';
import { generateWithModly, MODLY_INSTALL_URL } from '../modly-local.js';
const POLL_MS = 2500;
const POLL_MAX_BACKOFF_MS = 15000;
const JOB_TIMEOUT_MS = 15 * 60 * 1000;
const IMAGE_MAX_BYTES = 8 * 1024 * 1024;
const GLB_MAX_BYTES = 200 * 1024 * 1024;
const IMAGE_TYPES = ['image/png', 'image/jpeg', 'image/webp'];
// ── Identity ─────────────────────────────────────────────────────────────────
// The same anonymous handle /forge uses, so a workflow's generations land in the
// same "My creations" list as the ones made on /forge.
const CLIENT_ID = (() => {
const KEY = 'forge:cid';
try {
let id = localStorage.getItem(KEY);
if (!id) {
id = crypto.randomUUID();
localStorage.setItem(KEY, id);
}
return id;
} catch {
return `c-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
}
})();
// `x-witness: handled`: this page renders a designed state for every error the
// forge endpoints answer with, so the session recorder should not treat them as
// unhandled failures.
export const CLIENT_HEADERS = Object.freeze({ 'x-forge-client': CLIENT_ID, 'x-witness': 'handled' });
function headers(extra = {}) {
return attachTierPass({ ...CLIENT_HEADERS, ...extra });
}
// ── Plumbing ─────────────────────────────────────────────────────────────────
function sleep(ms, signal) {
return new Promise((resolve, reject) => {
if (signal?.aborted) return reject(new DOMException('Cancelled', 'AbortError'));
const t = setTimeout(() => {
signal?.removeEventListener('abort', onAbort);
resolve();
}, ms);
const onAbort = () => {
clearTimeout(t);
reject(new DOMException('Cancelled', 'AbortError'));
};
signal?.addEventListener('abort', onAbort, { once: true });
});
}
async function request(url, { method = 'GET', body, signal, extraHeaders = {}, credentials } = {}) {
let res;
try {
res = await fetch(url, {
method,
signal,
credentials,
headers: headers(body !== undefined ? { 'content-type': 'application/json', ...extraHeaders } : extraHeaders),
body: body !== undefined ? JSON.stringify(body) : undefined,
});
} catch (err) {
if (signal?.aborted) throw err;
const e = new StepError('Could not reach three.ws. Check your connection, then retry this step.', { code: 'network' });
e.transport = true;
throw e;
}
const data = await res.json().catch(() => ({}));
return { res, data };
}
const SIGN_IN = () => ({ label: 'Sign in', href: `/login?next=${encodeURIComponent(location.pathname + location.search)}` });
/** Turn a non-2xx endpoint answer into an error the node card can act on. */
export function errorFromResponse(res, data, what) {
const msg = (fallback) => data?.message || data?.error_description || fallback;
if (res.status === 429 || data?.error === 'rate_limited') {
const secs = Math.max(1, Math.ceil(Number(data?.retry_after) || Number(res.headers?.get?.('ratelimit-reset')) || 30));
return new StepError(`${what} is rate limited right now. Retry in about ${secs}s.`, { code: 'rate_limited', retryAfter: secs });
}
if (res.status === 402 && data?.error === 'three_hold_required') {
const actions = [];
if (data.acquire?.swap_url) actions.push({ label: 'Get $THREE', href: data.acquire.swap_url });
actions.push({ label: 'Holder perks', href: '/three' });
return new StepError(msg(`${what} is a $THREE holder perk.`), { code: 'hold_required', actions });
}
if (res.status === 401) {
return new StepError(msg(`Sign in to use ${what}.`), { code: 'auth', action: SIGN_IN() });
}
if (data?.error === 'needs_key' || data?.error === 'invalid_key') {
return new StepError(msg('This engine needs your own API key.'), { code: data.error, action: { label: 'Open Forge', href: '/forge' } });
}
if (data?.error === 'image_not_usable') {
return new StepError(msg('That photo does not look usable for 3D. Try a clearer photo of a single object.'), { code: 'image_not_usable' });
}
if (res.status === 503 || data?.error === 'unconfigured' || data?.error === 'storage_unavailable' || data?.error === 'provider_busy') {
const secs = Number(data?.retry_after) > 0 ? Math.ceil(Number(data.retry_after)) : 0;
return new StepError(msg(`${what} is temporarily unavailable.`) + (secs ? ` Retry in about ${secs}s.` : ''), { code: data?.error || 'unavailable', retryAfter: secs });
}
return new StepError(msg(`${what} failed (HTTP ${res.status}).`), { code: data?.error || `http_${res.status}` });
}
// A time-based estimate only while the job is inside its ETA. Past it, the bar
// switches to an honest "taking longer" readout instead of parking at 95%.
function estimateProgress(elapsedSec, etaSec) {
if (!(etaSec > 0) || !(elapsedSec >= 0) || elapsedSec > etaSec) return null;
return Math.min(95, Math.round((elapsedSec / etaSec) * 100));
}
/**
* Poll a job until it finishes. `read(data)` maps a poll answer to
* { done: value } | { failed: message } | { pending: 'queued'|'running' }.
* Transport hiccups back off and keep going; the server owns the job.
*/
async function pollJob(url, { signal, progress, what, etaSeconds, read }) {
const started = Date.now();
let delay = POLL_MS;
for (;;) {
await sleep(delay, signal);
if (Date.now() - started > JOB_TIMEOUT_MS) {
throw new StepError(`${what} did not finish within ${Math.round(JOB_TIMEOUT_MS / 60000)} minutes. Retry this step.`, { code: 'timeout' });
}
let res, data;
try {
({ res, data } = await request(url, { signal }));
} catch (err) {
if (err?.transport) {
progress({ label: 'Connection unstable, still waiting', pct: null });
delay = Math.min(POLL_MAX_BACKOFF_MS, delay * 2);
continue;
}
throw err;
}
delay = POLL_MS;
if (res.status === 429) {
delay = Math.min(POLL_MAX_BACKOFF_MS, Math.max(POLL_MS, (Number(data?.retry_after) || 5) * 1000));
continue;
}
// A 502 without a status is the worker blinking; keep polling.
if (res.status >= 500 && !data?.status) continue;
if (!res.ok) throw errorFromResponse(res, data, what);
const step = read(data);
if (step.done) return step.done;
if (step.failed) throw new StepError(`${what} failed: ${step.failed}`, { code: 'job_failed' });
const elapsed = Number.isFinite(data.elapsed_seconds) ? data.elapsed_seconds : (Date.now() - started) / 1000;
const eta = Number(data.eta_seconds) || etaSeconds || 0;
const pct = estimateProgress(elapsed, eta);
progress({
label: step.pending === 'queued' ? 'Queued for a GPU' : 'Working',
pct,
estimate: pct != null,
elapsed: Math.round(elapsed),
eta: eta || null,
});
}
}
// ── Uploads ──────────────────────────────────────────────────────────────────
// Local bytes for URLs this page uploaded, so a Modly run can send the original
// photo without downloading it again.
const localBlobs = new Map();
async function presignAndPut(endpoint, file, contentType, { signal, what }) {
const { res, data } = await request(endpoint, { method: 'POST', body: { content_type: contentType, size_bytes: file.size }, signal });
if (!res.ok || !data.upload_url) throw errorFromResponse(res, data, what);
let put;
try {
put = await fetch(data.upload_url, { method: data.method || 'PUT', headers: data.headers || { 'content-type': contentType }, body: file, signal });
} catch (err) {
if (signal?.aborted) throw err;
throw new StepError(`${what} could not reach storage. Check your connection and try again.`, { code: 'network' });
}
if (!put.ok) throw new StepError(`${what} was rejected by storage (HTTP ${put.status}). Try again.`, { code: 'upload_failed' });
localBlobs.set(data.public_url, file);
return data.public_url;
}
/** Upload a photo the user picked. Resolves { url, name }. */
export async function uploadImage(file, { signal } = {}) {
const type = IMAGE_TYPES.includes(file.type) ? file.type : null;
if (!type) throw new StepError('Use a PNG, JPEG or WebP photo.', { code: 'bad_type' });
if (file.size > IMAGE_MAX_BYTES) throw new StepError('That photo is over 8 MB. Use a smaller one.', { code: 'too_large' });
const url = await presignAndPut('/api/forge-upload', file, type, { signal, what: 'The photo upload' });
return { url, name: file.name || 'photo' };
}
/** Upload a GLB (a local file, or a mesh made on the user's GPU). Resolves the public URL. */
export async function uploadGlb(blob, { signal } = {}) {
if (blob.size > GLB_MAX_BYTES) throw new StepError('That model is over 200 MB, the upload limit.', { code: 'too_large' });
const head = new Uint8Array(await blob.slice(0, 4).arrayBuffer());
if (String.fromCharCode(...head) !== 'glTF') throw new StepError('That file is not a binary glTF (.glb).', { code: 'bad_type' });
return presignAndPut('/api/scene-glb-upload', blob, 'model/gltf-binary', { signal, what: 'The model upload' });
}
// The processing workers fetch the model themselves, so the URL they get must be
// public http(s), short enough for the API (2048 chars) and not on this machine.
const WORKER_URL_MAX = 2048;
const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '0.0.0.0']);
function workerReachable(url) {
if (typeof url !== 'string' || url.length > WORKER_URL_MAX) return false;
try {
const u = new URL(url);
return (u.protocol === 'https:' || u.protocol === 'http:') && !LOCAL_HOSTS.has(u.hostname);
} catch {
return false;
}
}
async function fetchMeshBlob(url, signal) {
let res;
try {
res = await fetch(new URL(url, location.href), { signal });
} catch (err) {
if (signal?.aborted) throw err;
throw new StepError('Could not read the model from the previous step. Run that step again.', { code: 'network' });
}
if (!res.ok) throw new StepError(`The model from the previous step is no longer available (HTTP ${res.status}). Run that step again.`, { code: 'gone' });
return res.blob();
}
/**
* A mesh value as a URL a processing worker can fetch. Local bytes (a model made
* on the user's GPU), same-origin paths and over-long signed links are uploaded
* to three.ws storage first.
*/
async function publicMeshUrl(mesh, { signal, progress }) {
if (!mesh) throw new StepError('No model arrived from the previous step.', { code: 'no_input' });
if (mesh.publicUrl) return mesh.publicUrl;
if (workerReachable(mesh.url)) return mesh.url;
let blob = mesh.blob;
if (!blob && mesh.url) {
if (!/^(https?:|blob:|\/)/i.test(mesh.url)) {
throw new StepError('The engine returned the model in private storage. Run Generate again with Run fresh.', { code: 'unreachable_url' });
}
progress({ label: 'Fetching the model', pct: null });
blob = await fetchMeshBlob(mesh.url, signal);
}
if (!blob) throw new StepError('The previous step produced no model.', { code: 'no_input' });
progress({ label: 'Uploading the model', pct: null });
mesh.publicUrl = await uploadGlb(blob, { signal });
return mesh.publicUrl;
}
async function imageBlob(image, signal) {
if (image.blob) return image.blob;
const cached = localBlobs.get(image.url);
if (cached) return cached;
let res;
try {
res = await fetch(image.url, { signal });
} catch (err) {
if (signal?.aborted) throw err;
throw new StepError('Could not download the photo to send to Modly. Upload it again.', { code: 'network' });
}
if (!res.ok) throw new StepError(`The photo is no longer available (HTTP ${res.status}). Upload it again.`, { code: 'gone' });
return res.blob();
}
// $THREE gated calls carry the holder's tier pass. A wallet-only holder signs a
// free message once; a non-holder is never asked to sign.
async function primeTierProof(feature) {
try {
const access = await getAccess(feature, { fresh: true });
await getTierPass({ interactive: Boolean(access?.access?.eligible ?? access?.eligible) });
} catch {
// No proof just means the request goes out unproven and the server answers
// with its normal hold-or-pay message.
}
}
// ── Generation ───────────────────────────────────────────────────────────────
function mintProgressId() {
return crypto.randomUUID().replace(/[^A-Za-z0-9_-]/g, '').slice(0, 48);
}
const CRUMB_LABEL = {
directed: 'Prompt art-directed',
reference: 'Reference image ready',
views: 'Turnaround views painted',
submitting: 'Sending to the 3D engine',
};
// While the generate POST is still open (prompt direction, reference image),
// read the server's milestone crumbs so the node shows real stages instead of a
// silent spinner.
function watchCrumbs(traceId, progress, signal) {
let stopped = false;
const tick = async () => {
while (!stopped && !signal.aborted) {
await sleep(POLL_MS, signal).catch(() => {});
if (stopped || signal.aborted) return;
try {
const res = await fetch(`/api/forge?progress=${encodeURIComponent(traceId)}`, { headers: CLIENT_HEADERS, signal });
if (!res.ok) {
if (res.status !== 429) return;
continue;
}
const data = await res.json();
const last = Array.isArray(data?.progress) ? data.progress[data.progress.length - 1] : null;
const reference = data.progress.find((c) => c.stage === 'reference')?.preview_image_url || null;
if (!stopped && CRUMB_LABEL[last?.stage]) progress({ label: CRUMB_LABEL[last.stage], pct: null, preview: reference });
} catch {
return;
}
}
};
tick();
return () => {
stopped = true;
};
}
async function generateOnCloud({ params, inputs, signal, progress }) {
const text = typeof inputs.prompt === 'string' ? inputs.prompt.trim() : '';
const body = { tier: params.tier || 'draft', path: 'image' };
if (params.engine && params.engine !== 'auto') body.backend = params.engine;
if (params.mode === 'image') {
if (!inputs.image?.url) throw new StepError('No photo arrived from the previous step.', { code: 'no_input' });
body.image_urls = [inputs.image.url];
if (text) body.prompt = text.slice(0, 1000);
} else {
if (!text) throw new StepError('The prompt is empty.', { code: 'no_input' });
body.prompt = text.slice(0, 1000);
body.director = true;
}
if (body.tier === 'high') await primeTierProof('forge.high');
const traceId = mintProgressId();
body.progress_id = traceId;
progress({ label: params.mode === 'image' ? 'Submitting the photo' : 'Art-directing the prompt', pct: null });
const stopCrumbs = watchCrumbs(traceId, progress, signal);
let res, data;
try {
({ res, data } = await request('/api/forge', { method: 'POST', body, signal }));
} finally {
stopCrumbs();
}
if (!res.ok) throw errorFromResponse(res, data, 'Generation');
let done = data;
if (!(data.status === 'done' && data.glb_url)) {
if (!data.job_id) throw new StepError(data.message || 'The generator did not return a job.', { code: 'no_job' });
progress({ label: 'Queued for a GPU', pct: 0, estimate: true, eta: data.eta_seconds || null, preview: data.preview_image_url || null });
done = await pollJob(`/api/forge?job=${encodeURIComponent(data.job_id)}`, {
signal,
progress,
what: 'Generation',
etaSeconds: data.eta_seconds,
read: (d) => (d.status === 'done' && d.glb_url ? { done: d } : d.status === 'failed' ? { failed: d.error || d.message || 'the engine gave up' } : { pending: d.status }),
});
}
const mesh = {
url: done.glb_url,
filename: 'forge-model.glb',
creationId: done.creation_id || data.creation_id || null,
jobId: data.job_id || null,
backend: done.backend || data.backend || null,
previewImageUrl: done.preview_image_url || data.preview_image_url || null,
prompt: body.prompt || null,
};
return {
outputs: { mesh },
result: {
mesh,
note: mesh.creationId ? 'Saved to My creations automatically.' : '',
links: mesh.creationId ? [{ label: 'Open model page', href: `/m/${encodeURIComponent(mesh.creationId)}` }] : [],
cached: Boolean(data.cached),
},
};
}
async function generateOnModly({ params, inputs, signal, progress, modly }) {
if (!modly?.origin) throw new StepError('Connect Modly first: select this node and press Connect.', { code: 'modly_offline' });
if (!inputs.image) throw new StepError('No photo arrived from the previous step.', { code: 'no_input' });
const image = await imageBlob(inputs.image, signal);
try {
const out = await generateWithModly(modly.origin, {
image,
modelId: params.modlyModel,
signal,
onProgress: (pct, step) => progress({ label: step || 'Generating on your GPU', pct, estimate: false }),
});
const mesh = { url: null, blob: out.blob, filename: out.filename, jobId: out.jobId, backend: `modly:${out.modelId}` };
return { outputs: { mesh }, result: { mesh, note: 'Made on your GPU. It uploads to three.ws only if a later step needs it.' } };
} catch (err) {
if (signal.aborted || err?.code === 'CANCELLED') throw err;
throw new StepError(err?.message || 'Modly could not finish the generation.', { code: `modly_${String(err?.code || 'failed').toLowerCase()}`, action: { label: 'Get Modly', href: MODLY_INSTALL_URL } });
}
}
// ── Processing ───────────────────────────────────────────────────────────────
/** Submit a mesh job to one of the forge processing endpoints and wait for it. */
async function processMesh({ endpoint, what, body, signal, progress, feature, pick }) {
if (feature) await primeTierProof(feature);
progress({ label: `Submitting to ${what}`, pct: null });
const { res, data } = await request(endpoint, { method: 'POST', body, signal });
if (!res.ok || !data.job_id) throw errorFromResponse(res, data, what);
const done = await pollJob(`${endpoint}?job=${encodeURIComponent(data.job_id)}`, {
signal,
progress,
what,
etaSeconds: data.eta_seconds,
read: (d) => {
if (d.status === 'failed') return { failed: d.error || 'the worker gave up' };
const url = d.status === 'done' ? pick(d) : null;
return url ? { done: d } : { pending: d.status };
},
});
return { done, url: pick(done) };
}
function meshFrom(prev, url, extra = {}) {
return { url, filename: prev?.filename || 'forge-model.glb', prompt: prev?.prompt || null, creationId: null, ...extra };
}
// ── Export ───────────────────────────────────────────────────────────────────
let threePromise = null;
function loadThree() {
threePromise ||= Promise.all([
import('three/addons/loaders/GLTFLoader.js'),
import('three/addons/loaders/DRACOLoader.js'),
import('three/addons/libs/meshopt_decoder.module.js'),
import('three/addons/exporters/STLExporter.js'),
import('three/addons/exporters/OBJExporter.js'),
import('three/addons/exporters/PLYExporter.js'),
]).then(([gltf, draco, meshopt, stl, obj, ply]) => ({ gltf, draco, meshopt, stl, obj, ply }));
return threePromise;
}
async function meshArrayBuffer(mesh, signal) {
if (mesh.blob) return mesh.blob.arrayBuffer();
let res;
try {
res = await fetch(mesh.url, { signal });
} catch (err) {
if (signal?.aborted) throw err;
throw new StepError('Could not download the model to convert it. Check your connection and retry.', { code: 'network' });
}
if (!res.ok) throw new StepError(`The model is no longer available (HTTP ${res.status}).`, { code: 'gone' });
return res.arrayBuffer();
}
async function convertInBrowser(mesh, format, signal) {
const t = await loadThree();
const buf = await meshArrayBuffer(mesh, signal);
const loader = new t.gltf.GLTFLoader();
const draco = new t.draco.DRACOLoader();
draco.setDecoderPath('/three/draco/gltf/');
loader.setDRACOLoader(draco);
loader.setMeshoptDecoder(t.meshopt.MeshoptDecoder);
let gltf;
try {
gltf = await loader.parseAsync(buf, '');
} catch (err) {
throw new StepError(`Could not read the model to convert it: ${err?.message || 'invalid glTF'}.`, { code: 'parse_failed' });
} finally {
draco.dispose();
}
if (format === 'stl') return new Blob([new t.stl.STLExporter().parse(gltf.scene, { binary: true })], { type: 'model/stl' });
if (format === 'obj') return new Blob([new t.obj.OBJExporter().parse(gltf.scene)], { type: 'model/obj' });
const ply = await new Promise((resolve, reject) => {
try {
new t.ply.PLYExporter().parse(gltf.scene, resolve, { binary: true });
} catch (err) {
reject(err);
}
});
return new Blob([ply], { type: 'application/octet-stream' });
}
function triggerDownload(href, filename) {
const a = document.createElement('a');
a.href = href;
a.download = filename;
a.rel = 'noopener';
document.body.appendChild(a);
a.click();
a.remove();
}
// ── Executors ────────────────────────────────────────────────────────────────
export const EXECUTORS = {
async prompt({ params }) {
return { outputs: { text: String(params.text || '').trim() } };
},
async image({ params }) {
const image = (params.images || [])[0];
if (!image?.url) throw new StepError('Upload a photo first.', { code: 'no_input' });
return { outputs: { image: { url: image.url, name: image.name } }, result: { image } };
},
async loadMesh({ params }) {
const url = String(params.url || '').trim();
if (!/^https:\/\//i.test(url)) throw new StepError('Add an https link to a .glb, or upload one.', { code: 'no_input' });
const mesh = { url, filename: (params.name || url.split('/').pop() || 'model.glb').replace(/[?#].*$/, ''), creationId: null };
return { outputs: { mesh }, result: { mesh } };
},
async generate(ctx) {
return ctx.params.engine === 'modly' ? generateOnModly(ctx) : generateOnCloud(ctx);
},
async rig({ inputs, signal, progress }) {
const glbUrl = await publicMeshUrl(inputs.mesh, { signal, progress });
progress({ label: 'Submitting to the rigger', pct: null });
const { res, data } = await request('/api/forge?action=rig', { method: 'POST', body: { glb_url: glbUrl }, signal });
if (!res.ok || !data.job_id) {
if (res.status === 501 || data.error === 'rig_unconfigured') throw new StepError(data.message || 'Auto-rigging is not available right now.', { code: 'rig_unconfigured' });
throw errorFromResponse(res, data, 'Auto-rig');
}
const done = await pollJob(`/api/forge?job=${encodeURIComponent(data.job_id)}`, {
signal,
progress,
what: 'Auto-rig',
etaSeconds: data.eta_seconds || 90,
read: (d) => (d.status === 'done' && d.glb_url ? { done: d } : d.status === 'failed' ? { failed: d.error || 'the rigger gave up' } : { pending: d.status }),
});
const mesh = meshFrom(inputs.mesh, done.glb_url, { creationId: done.creation_id || null, rigged: true });
return {
outputs: { mesh },
result: { mesh, links: mesh.creationId ? [{ label: 'Open model page', href: `/m/${encodeURIComponent(mesh.creationId)}` }] : [] },
};
},
async remesh({ params, inputs, signal, progress }) {
const meshUrl = await publicMeshUrl(inputs.mesh, { signal, progress });
const body = { mesh_url: meshUrl, remesh_mode: params.mode, target_faces: Number(params.targetFaces), texture_size: Number(params.textureSize), output_format: 'glb' };
if (params.mode === 'triangle') body.operation = params.operation;
const { done, url } = await processMesh({ endpoint: '/api/forge-remesh', what: 'Remesh', body, signal, progress, pick: (d) => d.result_url });
const mesh = meshFrom(inputs.mesh, url, { faceCount: done.face_count ?? null });
return { outputs: { mesh }, result: { mesh, stats: done.face_count ? `${done.face_count.toLocaleString('en-US')} faces` : '' } };
},
async segment({ params, inputs, signal, progress }) {
const meshUrl = await publicMeshUrl(inputs.mesh, { signal, progress });
const body = { mesh_url: meshUrl, method: params.method, max_parts: Number(params.maxParts) };
const { done, url } = await processMesh({ endpoint: '/api/forge-segment', what: 'Segment', body, signal, progress, pick: (d) => d.result_url });
const mesh = meshFrom(inputs.mesh, url, { parts: done.parts || null });
const count = done.part_count ?? done.parts?.length;
return { outputs: { mesh }, result: { mesh, stats: count ? `${count} parts` : '' } };
},
async stylize({ params, inputs, signal, progress }) {
const meshUrl = await publicMeshUrl(inputs.mesh, { signal, progress });
const { done, url } = await processMesh({ endpoint: '/api/forge-stylize', what: 'Stylize', body: { mesh_url: meshUrl, style: params.style, output_format: 'glb' }, signal, progress, pick: (d) => d.result_url });
const mesh = meshFrom(inputs.mesh, url, { faceCount: done.face_count ?? null });
return { outputs: { mesh }, result: { mesh, stats: done.face_count ? `${done.face_count.toLocaleString('en-US')} faces` : '' } };
},
async gameready({ params, inputs, signal, progress }) {
const meshUrl = await publicMeshUrl(inputs.mesh, { signal, progress });
const body = { mesh_url: meshUrl, topology: params.topology, poly_budget: Number(params.polyBudget), texture_size: Number(params.textureSize), formats: ['glb', 'fbx'] };
const { done, url } = await processMesh({
endpoint: '/api/forge-gameready',
what: 'Game-ready',
body,
signal,
progress,
feature: 'forge.gameready',
pick: (d) => d.outputs?.glb?.url,
});
const mesh = meshFrom(inputs.mesh, url, { fbxUrl: done.outputs?.fbx?.url || null, faceCount: done.face_count ?? null });
const links = mesh.fbxUrl ? [{ label: 'Download FBX', href: mesh.fbxUrl, download: true }] : [];
return { outputs: { mesh }, result: { mesh, links, stats: done.face_count ? `${done.face_count.toLocaleString('en-US')} faces` : '' } };
},
async preview({ inputs }) {
if (!inputs.mesh) throw new StepError('No model arrived to preview.', { code: 'no_input' });
return { result: { mesh: inputs.mesh } };
},
async export({ params, inputs, iter, signal, progress }) {
const mesh = inputs.mesh;
if (!mesh) throw new StepError('No model arrived to export.', { code: 'no_input' });
const base = String(params.filename || 'forge-model').trim() + (iter != null ? `-${iter + 1}` : '');
const format = params.format || 'glb';
const filename = `${base}.${format}`;
let href;
let objectUrl = null;
if (format === 'glb') {
if (mesh.blob) href = objectUrl = URL.createObjectURL(mesh.blob);
else {
progress({ label: 'Downloading the GLB', pct: null });
href = objectUrl = URL.createObjectURL(new Blob([await meshArrayBuffer(mesh, signal)], { type: 'model/gltf-binary' }));
}
} else if (format === 'fbx') {
if (mesh.fbxUrl) href = mesh.fbxUrl;
else {
const meshUrl = await publicMeshUrl(mesh, { signal, progress });
const { url } = await processMesh({
endpoint: '/api/forge-remesh',
what: 'FBX conversion',
body: { mesh_url: meshUrl, operation: 'convert', remesh_mode: 'triangle', output_format: 'fbx' },
signal,
progress,
pick: (d) => d.result_url,
});
href = url;
}
} else {
progress({ label: `Converting to ${format.toUpperCase()}`, pct: null });
href = objectUrl = URL.createObjectURL(await convertInBrowser(mesh, format, signal));
}
if (params.autoDownload !== false) triggerDownload(href, filename);
return { result: { download: { href, filename, objectUrl } } };
},
async save({ params, inputs, signal, progress }) {
const mesh = inputs.mesh;
const glbUrl = await publicMeshUrl(mesh, { signal, progress });
const name = String(params.name || 'Forge workflow model').trim().slice(0, 80);
progress({ label: params.destination === 'gallery' ? 'Publishing to the gallery' : 'Saving to your library', pct: null });
if (params.destination === 'gallery') {
const { res, data } = await request('/api/creations', {
method: 'POST',
body: { op: 'publish', prompt: (mesh.prompt || name).slice(0, 1000), glbUrl, title: name, previewImageUrl: mesh.previewImageUrl || undefined, backend: mesh.backend || undefined },
signal,
});
if (res.status === 400 && data.error === 'invalid_glb_url') {
throw new StepError('The gallery only accepts models stored on three.ws. Add a Remesh or Save to library step instead.', { code: 'invalid_glb_url' });
}
if (!res.ok) throw errorFromResponse(res, data, 'Publishing');
return { result: { saved: true, links: [{ label: 'View in gallery', href: '/creations' }] } };
}
const { res, data } = await request('/api/avatars/from-forge', {
method: 'POST',
credentials: 'include',
body: { glb_url: glbUrl, name, visibility: params.visibility || 'unlisted', source_prompt: mesh.prompt || undefined, rigged: Boolean(mesh.rigged), tags: ['forge-workflow'] },
signal,
});
if (res.status === 401) throw new StepError('Sign in to save models to your library, then retry this step.', { code: 'auth', action: SIGN_IN() });
if (!res.ok) throw errorFromResponse(res, data, 'Saving');
const href = data.view_url || (data.avatar?.id ? `/avatars/${data.avatar.id}` : '/dashboard');
return { result: { saved: true, links: [{ label: 'Open in library', href }] } };
},
};