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.

14.6 KB
Raw Blame
<!doctype html>
<html lang="en" class="cookbook-page">
	<head>
		<script>/* three.ws theme boot: no-flash; runtime in /theme-switcher.js */(function(){try{var m=localStorage.getItem('twx_theme');var l=m==='auto'?(window.matchMedia&&window.matchMedia('(prefers-color-scheme: light)').matches):m==='light';document.documentElement.setAttribute('data-theme',l?'light':'dark');}catch(e){document.documentElement.setAttribute('data-theme','dark');}})();</script>
		<meta charset="utf-8" />
		<meta http-equiv="X-UA-Compatible" content="IE=edge" />
		<title data-i18n="recipe.meta_title">three.ws Cookbook recipe</title>
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<meta name="author" content="nirholas" />
		<meta
			name="description"
			content="A runnable three.ws cookbook recipe: the file, why it is shaped that way, and what it produces."
		 data-i18n-attr="content:recipe.meta_description"/>
		<meta name="theme-color" content="#000000" />
		<meta property="og:type" content="article" />
		<meta property="og:site_name" content="three.ws" />
		<meta property="og:title" content="three.ws Cookbook recipe"  data-i18n-attr="content:recipe.meta_og_title"/>
		<meta
			property="og:description"
			content="A runnable three.ws cookbook recipe: the file, why it is shaped that way, and what it produces."
		 data-i18n-attr="content:recipe.meta_og_description"/>

		<link rel="icon" href="/favicon.ico" sizes="any" />
		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
		<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
		<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
		<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
		<link rel="manifest" href="/manifest.webmanifest" />
		<link rel="stylesheet" href="/style.css" />
		<link rel="stylesheet" href="/nav.css" />
		<link rel="stylesheet" href="/footer.css" />
		<link rel="stylesheet" href="/fonts/fonts.css" />
		<link
			rel="stylesheet"
			href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css"
		/>
		<link rel="stylesheet" href="/mobile.css" />
		<link rel="stylesheet" href="/cookbook.css" />
		<!-- Figures: the same capture pipeline and presentation the tutorial viewer
		     uses, so a `figure:` directive in a recipe renders identically there. -->
		<link rel="stylesheet" href="/tutorial-figures.css" />
		<script
			src="https://cdn.jsdelivr.net/npm/[email protected]/marked.min.js"
			integrity="sha384-odPBjvtXVM/5hOYIr3A1dB+flh0c3wAT3bSesIOqEGmyUA4JoKf/YTWy0XKOYAY7"
			crossorigin="anonymous"
		></script>
		<script
			src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"
			integrity="sha384-F/bZzf7p3Joyp5psL90p/p89AZJsndkSoGwRpXcZhleCWhd8SnRuoYo4d0yirjJp"
			crossorigin="anonymous"
		></script>
		<script defer src="/nav.js"></script>
		<script defer src="/footer-newsletter.js"></script>
		<script defer src="/cookbook-manifest.js"></script>
		<!-- model-viewer backs the live/model figures and the fallback a model
		     figure degrades to when its still has not been captured yet. -->
		<script src="/model-viewer-meshopt.js"></script>
		<script src="/tutorial-figures.js"></script>
	
	<!-- This file is the SHARED shell for every /cookbook/<slug> route, so its
	     head names the cookbook index, never one recipe. server/seo-head.mjs
	     rewrites the head per request from data/pages.json, and it treats a
	     canonical that already equals the request path as "this page authored
	     its own meta" and skips it. A canonical naming a real recipe therefore
	     silently exempted exactly that recipe from the rewrite: /cookbook/text-to-3d-cli
	     was the one route in the section still serving this shell's generic
	     title and description. Same shape as pages/tutorial.html and
	     pages/walkthrough.html, which point at /tutorials and /walkthroughs. -->
	<link rel="canonical" href="https://three.ws/cookbook">
	<meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1">
	<meta property="og:locale" content="en_US">
	<meta property="og:url" content="https://three.ws/cookbook">
	<meta property="og:image" content="https://three.ws/api/page-og?s=learn&amp;t=Cookbook&amp;d=Runnable+recipes+for+building+with+three.ws&amp;p=%2Fcookbook">
	<meta property="og:image:width" content="1200">
	<meta property="og:image:height" content="630">
	<meta property="og:image:type" content="image/png">
	<meta property="og:image:alt" content="The three.ws Cookbook">
	<meta name="twitter:card" content="summary_large_image">
	<meta name="twitter:site" content="@trythreews">
	<meta name="twitter:title" content="three.ws Cookbook recipe" data-i18n-attr="content:recipe.meta_twitter_title">
	<meta name="twitter:description" content="A runnable three.ws cookbook recipe: the file, why it is shaped that way, and what it produces." data-i18n-attr="content:recipe.meta_twitter_description">
	<meta name="twitter:image" content="https://three.ws/api/page-og?s=learn&amp;t=Cookbook&amp;d=Runnable+recipes+for+building+with+three.ws&amp;p=%2Fcookbook">
</head>
	<body>
		<div class="cb-page">
			<header><div id="nav-container"></div></header>

			<main class="cb-main" id="main-content">
				<nav class="cb-crumbs" aria-label="Breadcrumb">
					<a href="/cookbook" data-i18n="recipe.cookbook">Cookbook</a> <span aria-hidden="true">/</span>
					<span id="cb-crumb-title" data-i18n="recipe.recipe">Recipe</span>
				</nav>

				<div class="cb-doc">
					<article class="cb-article" id="cb-article">
						<div class="cb-skeleton" aria-hidden="true">
							<span></span><span></span><span></span><span></span><span></span>
						</div>
						<p class="sr-only" role="status" data-i18n="recipe.loading_the_recipe">Loading the recipe.</p>
					</article>

					<aside class="cb-side" id="cb-side" hidden>
						<div class="cb-side-card" id="cb-facts-card">
							<h2 data-i18n="recipe.the_file">The file</h2>
							<dl class="cb-facts" id="cb-facts"></dl>
							<p style="margin: 0.9rem 0 0">
								<a class="cb-btn primary" id="cb-download" download>Download</a>
							</p>
						</div>
						<nav class="cb-side-card" id="cb-toc-card" aria-label="On this page">
							<h2 data-i18n="recipe.on_this_page">On this page</h2>
							<ul class="cb-toc" id="cb-toc"></ul>
						</nav>
					</aside>
				</div>
			</main>

			<footer id="site-footer"></footer>
		</div>

		<script>
			(function () {
				'use strict';

				const article = document.getElementById('cb-article');
				const side = document.getElementById('cb-side');
				const facts = document.getElementById('cb-facts');
				const toc = document.getElementById('cb-toc');
				const tocCard = document.getElementById('cb-toc-card');
				const crumb = document.getElementById('cb-crumb-title');
				const download = document.getElementById('cb-download');

				const ICON_COPY =
					'<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';

				function escapeHtml(value) {
					return String(value == null ? '' : value).replace(
						/[&<>"']/g,
						(c) =>
							({
								'&': '&amp;',
								'<': '&lt;',
								'>': '&gt;',
								'"': '&quot;',
								"'": '&#39;',
							})[c],
					);
				}

				function currentSlug() {
					const match = location.pathname.match(/^\/cookbook\/([a-z0-9-]+)\/?$/);
					return match ? match[1] : '';
				}

				function slugifyHeading(text) {
					return String(text)
						.toLowerCase()
						.replace(/[^a-z0-9]+/g, '-')
						.replace(/^-+|-+$/g, '');
				}

				function fillFacts(recipe) {
					const rows = [
						['Language', recipe.language],
						['Level', recipe.level],
						['Time', recipe.time],
						['Needs', recipe.needs],
						['Builds', recipe.builds],
					];
					facts.innerHTML = rows
						.filter(([, value]) => value)
						.map(
							([label, value]) =>
								'<dt>' +
								escapeHtml(label) +
								'</dt><dd>' +
								escapeHtml(value) +
								'</dd>',
						)
						.join('');
					if (recipe.download) {
						download.href = recipe.download.href;
						download.textContent = recipe.download.label;
					} else {
						download.hidden = true;
					}
					side.hidden = false;
				}

				/* Anchor every heading and mirror it into the sidebar, so a long recipe is
				   linkable section by section. */
				function buildToc() {
					const headings = article.querySelectorAll('h2, h3');
					const seen = new Set();
					const items = [];
					headings.forEach((heading) => {
						let id = slugifyHeading(heading.textContent);
						let unique = id;
						let n = 2;
						while (seen.has(unique)) unique = id + '-' + n++;
						seen.add(unique);
						heading.id = unique;
						items.push(
							'<li' +
								(heading.tagName === 'H3' ? ' class="sub"' : '') +
								'><a href="#' +
								unique +
								'">' +
								escapeHtml(heading.textContent) +
								'</a></li>',
						);
					});
					if (!items.length) {
						tocCard.hidden = true;
						return;
					}
					toc.innerHTML = items.join('');
					trackActiveHeading(headings);
				}

				function trackActiveHeading(headings) {
					if (!('IntersectionObserver' in window) || !headings.length) return;
					const links = new Map(
						Array.from(toc.querySelectorAll('a')).map((a) => [
							a.getAttribute('href').slice(1),
							a,
						]),
					);
					const observer = new IntersectionObserver(
						(entries) => {
							entries.forEach((entry) => {
								const link = links.get(entry.target.id);
								if (!link) return;
								if (entry.isIntersecting) {
									links.forEach((other) => other.removeAttribute('aria-current'));
									link.setAttribute('aria-current', 'true');
								}
							});
						},
						{ rootMargin: '-80px 0px -70% 0px' },
					);
					headings.forEach((heading) => observer.observe(heading));
				}

				/* Every code block gets a copy button. Wrapping wide blocks in a scroller
				   keeps the page itself from scrolling sideways on a phone. */
				function enhanceCode() {
					article.querySelectorAll('pre code').forEach((code) => {
						if (window.hljs) {
							try {
								window.hljs.highlightElement(code);
							} catch (err) {
								/* Highlighting is decoration; unstyled code still reads fine. */
							}
						}
						const pre = code.parentElement;
						const button = document.createElement('button');
						button.type = 'button';
						button.className = 'cb-copy';
						button.innerHTML = ICON_COPY + '<span>Copy</span>';
						button.addEventListener('click', async () => {
							const label = button.querySelector('span');
							try {
								await navigator.clipboard.writeText(code.textContent);
								label.textContent = 'Copied';
							} catch (err) {
								label.textContent = 'Press Ctrl+C';
							}
							setTimeout(() => {
								label.textContent = 'Copy';
							}, 1600);
						});
						pre.appendChild(button);
					});
					article.querySelectorAll('table').forEach((table) => {
						const scroller = document.createElement('div');
						scroller.className = 'cb-table-scroll';
						table.parentNode.insertBefore(scroller, table);
						scroller.appendChild(table);
					});
				}

				function appendPager(slug) {
					const recipes = window.RECIPES || [];
					const here = window.recipeIndex(slug);
					if (here < 0) return;
					const prev = recipes[here - 1];
					const next = recipes[here + 1];
					if (!prev && !next) return;
					const nav = document.createElement('nav');
					nav.className = 'cb-pager';
					nav.setAttribute('aria-label', 'More recipes');
					nav.innerHTML =
						(prev
							? '<a class="prev" href="' +
								escapeHtml(prev.href) +
								'"><span class="cb-pager-dir">Previous</span><span class="cb-pager-title">' +
								escapeHtml(prev.title) +
								'</span></a>'
							: '<span></span>') +
						(next
							? '<a class="next" href="' +
								escapeHtml(next.href) +
								'"><span class="cb-pager-dir">Next</span><span class="cb-pager-title">' +
								escapeHtml(next.title) +
								'</span></a>'
							: '<span></span>');
					article.appendChild(nav);
				}

				function showError(slug, detail) {
					article.innerHTML =
						'<div class="cb-error"><h1>This recipe did not load</h1><p>' +
						escapeHtml(detail) +
						'</p><p><a class="cb-btn primary" href="/cookbook">Back to the cookbook</a> ' +
						'<a class="cb-btn" href="/docs/3d-api">API docs</a></p></div>';
					document.title = 'three.ws Cookbook: recipe not found';
				}

				async function load() {
					const slug = currentSlug();
					if (!slug) {
						showError('', 'No recipe was named in the URL.');
						return;
					}
					const recipe = window.recipeBySlug(slug);
					if (recipe) {
						document.title = recipe.title + ' / three.ws Cookbook';
						crumb.textContent = recipe.title;
						fillFacts(recipe);
					}

					let markdown;
					try {
						const res = await fetch('/docs/cookbook/' + slug + '.md');
						if (!res.ok) throw new Error('HTTP ' + res.status);
						markdown = await res.text();
					} catch (err) {
						showError(
							slug,
							'We could not fetch /docs/cookbook/' +
								slug +
								'.md (' +
								err.message +
								'). It may have moved.',
						);
						return;
					}

					window.marked.setOptions({ gfm: true, breaks: false, mangle: false, headerIds: false });
					/* Figure directives become inert slots BEFORE the parse: as plain
					   markdown images marked emits <img src="figure:…">, and the browser
					   fires a doomed request for a scheme it cannot resolve. */
					const source = window.tutorialFigures
						? window.tutorialFigures.preprocess(markdown)
						: markdown;
					article.innerHTML = window.marked.parse(source);

					/* Internal .md links point at files in the repo; rewrite them to routes. */
					article.querySelectorAll('a[href$=".md"]').forEach((link) => {
						const href = link.getAttribute('href');
						if (/^https?:/.test(href)) return;
						link.setAttribute(
							'href',
							'/docs/' + href.replace(/^\.?\/?(docs\/)?/, '').replace(/\.md$/, ''),
						);
					});

					/* Swap the `figure:` directives for real captured media before the
					   TOC is built, so a figure never lands between a heading and its
					   observed position. Media is optional: every figure kind has a
					   live fallback, so a recipe with no captures still reads whole. */
					if (window.tutorialFigures) window.tutorialFigures.mount(article);

					buildToc();
					enhanceCode();
					appendPager(slug);
				}

				if (document.readyState === 'loading') {
					document.addEventListener('DOMContentLoaded', load);
				} else {
					load();
				}
			})();
		</script>
		<script type="module" src="/i18n.js"></script>
	</body>
</html>