3D World (three-d)

Category: frontend | Form: | Symbol: 3d

Build and deploy interactive 3D worlds with Bevy

Three-D creates GPU-accelerated 3D experiences using Bevy, compiled to wasm32-unknown-unknown. The build operation uses BuildForce with FrameworkHint::Bevy, enables wasm-opt for size reduction, and stores artifacts to S3 (namespace exp-{element_id}). WASM metadata (wasm_size_bytes) is reported in build output. Serve loads cached index.html; without a build, an interactive WebGL demo (rotating icosphere) is returned as placeholder. Three-D has its own asset management system with a separate S3 namespace (3d-{element_id}): upload_asset accepts model, texture, audio, or shader types. Invalid asset_type returns an error. list_assets queries up to 1000 assets. hot_reload is debug-only — it triggers a full rebuild and reports reload_time_ms. In release builds, hot_reload returns an error. Scaffold templates: minimal, scene-viewer, data-viz, world. Common mistake: calling hot_reload in production — it’s compiled out. Use build instead. WASM builds are slow; use clean:false (default) to leverage BuildForce caching.

Guide

Build and deploy interactive 3D experiences with Bevy, compiled to WebAssembly.

Overview

The 3D World element (three-d) creates GPU-accelerated, real-time 3D applications using the Bevy engine. Code is written in Rust, compiled to WASM via BuildForce, and served as static assets. It includes a dedicated asset management system for models, textures, audio, and shaders.

How It Works (physics/src/physics/impls/three_d.rs)

Build

Uses BuildForce with FrameworkHint::Bevy targeting wasm32-unknown-unknown. Key config:

• wasm_opt: true for size reduction
• Artifacts stored to S3 (exp-{element_id})
• Reports wasm_size_bytes in output from WASM metadata

Serve

Loads index.html from S3. Without a prior build, serves an interactive WebGL placeholder — a rotating icosphere with mouse tracking, gradient shading, and an FPS counter. The placeholder uses raw WebGL (no framework dependencies).

Asset Management

Three-D has a separate S3 namespace for assets (3d-{element_id}), distinct from build artifacts (exp-{element_id}):

Operation	Description
upload_asset	Store asset with type validation (model/texture/audio/shader)
list_assets	List up to 1000 assets from the 3D namespace

Asset type → MIME mapping:

• model → model/gltf-binary
• texture → image/png
• audio → audio/mpeg
• shader → application/x-glsl

Invalid asset_type values return an error.

Hot Reload

Debug-only operation (#[cfg(debug_assertions)]). Triggers a full rebuild and reports reload_time_ms. In release builds, returns an error. Use build in production.

Configuration

Key Properties

Property	Type	Description
source	string	Git URL or “local” (default: “local”)
code_ref	string	Code source reference
engine.bevy_version	string	Bevy version (default: “0.18”)
engine.render_backend	enum	webgpu, webgl2, auto (default: auto)
engine.msaa	enum	1, 2, 4, 8 (default: 4)
engine.hdr	boolean	HDR rendering (default: true)
canvas.fit_mode	enum	fill, contain, fixed (default: fill)
physics.enabled	boolean	Enable Rapier physics (default: false)
build.tool	enum	trunk, wasm-pack (default: trunk)
build.wasm_opt	boolean	Run wasm-opt (default: true)
networking.websocket	boolean	WebSocket to backend (default: true)
networking.data_bindings[]	array	Live data bindings from other elements

Scaffold Templates

Template	Description
minimal	Bare Bevy app with camera, light, ground plane
scene-viewer	Load and display glTF/GLB models with orbit camera
data-viz	3D data visualization with live backend data binding
world	Solar system visualization inspired by Triform World

Operations

Operation	Description
build	Compile Bevy to WASM via BuildForce. Returns build_hash, wasm_size_bytes, asset_count
serve	Serve cached WASM app or interactive WebGL placeholder
upload_asset	Upload model/texture/audio/shader to 3D namespace
list_assets	List all 3D assets (max 1000)
hot_reload	Debug-only: full rebuild with timing (errors in release)

Plus all category operations.

Quick Start

# Create a 3D world
POST /api/{circle}/frontend/three-d/
{
  "slug": "my-world",
  "spec": {
    "engine": { "render_backend": "auto", "hdr": true },
    "build": { "tool": "trunk", "wasm_opt": true }
  }
}

# Upload a model
POST /api/{circle}/frontend/three-d/my-world/ops/assets/upload
{
  "file": "<base64-encoded-glb>",
  "asset_type": "model",
  "path": "models/spaceship.glb"
}

# Build to WASM
POST /api/{circle}/frontend/three-d/my-world/ops/build
{ "environment": "production" }

# View at public URL
GET /{circle}/frontend/three-d/my-world/live

S3 Storage

Namespace	Purpose
exp-{element_id}	Build artifacts (WASM, HTML, JS)
3d-{element_id}	3D assets (models, textures, audio, shaders)

When to Use

• Interactive 3D visualizations
• Data visualization in 3D space
• Game-like experiences
• Scene viewers for glTF/GLB models
• Simulations with physics (Rapier)

When NOT to Use

• 2D web apps → use spa or view
• Server-rendered pages → use ssr
• Simple dashboards → use view

Related

• world/ — The existing Triform World app (reference implementation)
• SPA — For 2D client-side apps
• Frontend Category — Shared operations and routing

Relationships

• Attaches to: auth-policy
• Uses: variable, function, sql, document, vector, timeseries

Capabilities

• buildable: Supports build/serve/assets operations
• webgpu: WebGPU rendering (WebGL2 fallback)
• physics: Physics simulation (Rapier)
• gltf: glTF asset loading
• data-viz: Real-time data visualization
• multiplayer: WebSocket multiplayer
• cdn: CDN asset distribution

Properties

Property	Type	Default	Description
source	string	—	Git reference to source code directory
code_ref	string	—	Reference to the code source for the Bevy app
engine	object	—	Bevy engine configuration
canvas	object	—	Browser canvas configuration
physics	object	—	Physics engine configuration
assets	object	—	3D asset configuration
build	object	—	Build configuration
networking	object	—	Backend connectivity
environment	object	—	Environment variables
input	object	—	Input configuration
cdn	object	—	CDN and hosting
loading	object	—	Loading screen configuration
security	object	—	Security configuration

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

analytics

Get /ops/analytics | Auth: Read

Get experience usage analytics

Returns usage metrics for the frontend element. Use ?period query param (1d, 7d, 30d, 90d) to specify the time window. Returns views, unique_visitors, avg_session_duration_ms, bounce_rate, and top_paths. Useful for understanding user engagement with the frontend.

asset

Get /ops/assets/{asset_path} | Auth: Read

Serve a static asset from the build output (JS, CSS, WASM, images)

Serves a single asset by path from the build output. Returns binary content with appropriate Content-Type header. Used by the browser to load JS/CSS/WASM referenced in the served HTML. Typically called via /live URLs, not directly by agents.

assets

Get /ops/assets | Auth: Read

List bundled static assets

Lists all static assets from the last build output (JS, CSS, images, fonts). Each asset includes path, type, size_bytes, and content hash for cache busting. Returns total_size_bytes for the whole bundle. Only meaningful after a successful build.

attach

Post /ops/attach | Auth: Read

Attach this experience to a target element

Attaches this frontend to a target element (e.g., browser or user-browser). The target’s contract.yaml must declare this frontend type in attaches. Priority controls ordering when multiple frontends are attached. Returns attachment_id for later detach.

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

build

Post /ops/build | Auth: Write

Compile the Bevy app to WASM

Builds via BuildForce with FrameworkHint::Bevy targeting wasm32-unknown-unknown. Enables wasm-opt for size reduction. Source defaults to “local”. Stores artifacts to S3 (exp-{element_id}). Returns build_hash, wasm_size_bytes, asset_count, size_bytes, duration_ms, cache_hit. WASM builds are slow — avoid clean:true unless necessary to leverage caching.

build_status

Get /ops/build/{build_id} | Auth: Read

Get build status and logs

Poll this after triggering an async build. Returns status (pending/building/completed/failed), duration_ms, artifact list with sizes, build logs, and error message if failed.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

configure_domain

Post /ops/domain | Auth: Admin

Configure a custom domain for this experience

Maps a custom domain (e.g., app.example.com) to this frontend element. ssl_mode “auto” provisions a Let’s Encrypt certificate automatically. Returns status (pending_verification, active, error) and ssl_status. DNS must point to Triform before verification succeeds.

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

create_preview

Post /ops/preview/create | Auth: Write

Create a time-limited public preview link (no auth required to view)

Generates a shareable preview URL that expires after expires_in_hours (default 24). Anyone with the URL can view the frontend without authentication. Returns the token, full preview URL, and expiration timestamp. Use for stakeholder reviews or demos.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

detach

Post /ops/detach | Auth: Read

Detach this experience from a target element

Removes the attachment between this frontend and a target element. Requires target_id. This is a destructive action — the frontend will no longer be served through that target.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get_attached_modifiers

Get /ops/attached | Auth: Read

Get elements that are attached to this experience

Returns modifiers and resources attached TO this frontend (inverse of list_attachments). Includes rate-limit, auth-policy, and other modifier elements that affect this frontend.

hot_reload

Post /ops/reload | Auth: Admin

Trigger hot-reload of the 3D world (dev mode)

Debug-only operation — compiled out in release builds (returns error). Triggers a full rebuild via handle_build and reports total reload_time_ms including build duration. Use during development for rapid iteration. In production, use build instead.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

list_assets

Get /ops/assets/list | Auth: Read

List all 3D assets

Lists up to 1000 assets from the element’s 3d-{element_id} S3 namespace. Returns an array of assets with path, type, and size. Returns empty array for new elements with no uploaded assets. This is separate from the build artifacts namespace (exp-{element_id}).

list_attachments

Get /ops/targets | Auth: Read

List all elements this experience is attached to

Returns all target elements where this frontend is currently attached. Shows target_id, target_type, priority, and cascade_policy.

navigate

Post /ops/navigate | Auth: Read

Navigate to a route within the SPA (returns index.html for client-side routing)

For SPAs, this is identical to serve — always returns the same index.html regardless of the path parameter. Client-side JavaScript handles route resolution (history API fallback). Do not expect different HTML for different paths. For per-route server rendering, use ssr.

preview

Get /ops/preview | Auth: Read

Generate a preview/screenshot of the experience

Generates an image preview of the rendered frontend. Use query params ?width, ?height, ?path to customize. Returns image_url with an expiration timestamp. Useful for social cards and portal thumbnail previews.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

render

Post /ops/render | Auth: Read

Render the 3D experience (alias for serve)

Same as serve — loads built WASM from S3 or falls back to the interactive WebGL rotating icosphere demo. Use serve for GET-style retrieval; use render when you need POST with an input body (e.g. passing context data). Returns _html_content with _etag and _cache_control.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

serve

Get /ops/serve | Auth: Read

Serve the compiled WASM bundle and assets

Loads index.html from S3 (exp-{element_id}/builds/latest/index.html). Without a prior build, serves an interactive WebGL placeholder (rotating icosphere with mouse tracking and FPS counter). Returns _html_content with _etag and _cache_control.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

upload_asset

Post /ops/assets/upload | Auth: Write

Upload a 3D asset (model, texture, audio)

Stores a 3D asset to the element’s dedicated namespace (3d-{element_id}). asset_type must be one of: model (gltf-binary), texture (png), audio (mpeg), shader (x-glsl). Invalid types return an error. The path defaults to “assets/unnamed”. Returns asset_id ({element_id}/{path}) and a URL for retrieval. Size is estimated from the file input string length.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
THREE_D_BUILD_FAILED	internal	yes	3D build failed
THREE_D_ASSET_MISSING	not_found	no	Required asset not found
THREE_D_GPU_UNSUPPORTED	validation	no	GPU capabilities insufficient
THREE_D_WASM_LOAD_FAILED	internal	yes	WASM module failed to load