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.

feat(engine-bridges): ship Unity, Godot and Unreal bridges against the public Forge API

nirholas40b30a5d06ed
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5f39139d8..9cef05356 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,8 +10,10 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
## 2026-10-12
+- **Docs · Engine bridges** (`/docs/engine-bridges`): One Forge API contract, three real editor integrations: a Unity UPM package, a Godot addon, and an Unreal plugin, each generating a mesh from a prompt and importing it with the engine's own native glTF pipeline.
- **Docs · Engine QA** (`/docs/engine-qa`): A free real-time-engine fitness grade for any 3D model: draw calls, material count, texel density, a per-level LOD triangle budget, and whether the mesh is cheap and closed enough to use as its own physics collider.
- **Engine QA: a free real-time-engine fitness grade, plus real LOD chains**: A new free grade answers the question a game engine's import step asks that neither glTF validation nor simulation readiness does: draw calls, material count, texel density against the mesh's real-world size, a per-level triangle budget for a LOD chain, and whether the mesh is cheap and closed enough to use as its own physics collider. GET/POST /api/3d/engine-qa grades any public GLB (format=stl exports a watertight mesh for printing); the same browser-only checks run with zero network cost in Rig Doctor, and the full grade with a one-click upgrade in the GLB viewer, through a shared <engine-qa> panel component. The underlying LOD builder (packages/glb-tools's buildLodChain, real meshoptimizer decimation tagged with MSFT_lod) is now also available on generation: send { "lods": true } to POST /api/forge and the finished creation gets a combined LOD-chain variant alongside its delivered mesh, the same opt-in, fire-and-forget pattern as the existing web-delivery variant. (`/docs/engine-qa`) `[feature]`
+- **Three new engine bridges: Unity, Godot, and Unreal, one prompt to a mesh in your editor**: A shared contract (specs/ENGINE_BRIDGE.md) and three real, independent implementations: a Unity UPM package that imports with glTFast, a Godot addon that imports with Godot's own native GLTFDocument, and an Unreal plugin that imports through Unreal's Interchange glTF pipeline. Each one calls only the public Forge API (POST /api/forge to submit, GET /api/forge?job=<id> to poll, a plain HTTPS GET to download), the same free-first routing and anonymous x-forge-client auth every other Forge caller gets, with the same four import settings (generate_colliders, import_materials, scale, destination) mapped onto each engine's own equivalent. A dropdown and a Generate button in each editor: type a prompt, get a mesh dropped into your scene. (`/docs/engine-bridges`) `[feature, sdk]`
## 2026-10-11
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 7340e6a23..b770b2454 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -154,6 +154,7 @@ bottom.
| Verifiable 3D provenance (content credentials) | Spec [specs/PROVENANCE_3D.md](specs/PROVENANCE_3D.md), pure core [api/_lib/provenance-3d.js](api/_lib/provenance-3d.js), Solana anchor [api/_lib/provenance-anchor.js](api/_lib/provenance-anchor.js), MCP tools [api/_mcp3d/tools/provenance.js](api/_mcp3d/tools/provenance.js) (`verify_provenance` free, `anchor_provenance` paid $0.05), free REST verify [api/provenance.js](api/provenance.js) `→ /api/provenance`, viewer badge [public/viewer.html](public/viewer.html), docs [docs/provenance.md](docs/provenance.md). | Live (verify) · anchor gated on issuer key + devnet funds | C2PA-style signed content credentials for AI 3D: creator, prompt, model/provider, lineage, timestamp, and the GLB's sha256, ed25519-signed by the three.ws issuer with the credential hash anchored on Solana. Free public `verify_provenance` / `GET /api/provenance?src=…` recompute the hash and return `verified | tampered | unknown` (a single changed byte → tampered); the verify path and response are coin-clean (both stores). `anchor_provenance` signs + writes the SPL Memo anchor + stores the credential in R2. Tests: [tests/provenance-3d.test.js](tests/provenance-3d.test.js). Evidence: [prompts/store-submissions/_generated/provenance/](prompts/store-submissions/_generated/provenance/). Store-submission prompt 19. |
| Simulation readiness (a physics grade for 3D assets) | Spec [specs/SIM_READINESS.md](specs/SIM_READINESS.md), pure core [api/_lib/sim-readiness.js](api/_lib/sim-readiness.js), storage [api/_lib/sim-readiness-store.js](api/_lib/sim-readiness-store.js) + migration [20260813180000_sim_readiness_grades.sql](api/_lib/migrations/20260813180000_sim_readiness_grades.sql), free MCP tool [api/_mcp3d/tools/sim-readiness.js](api/_mcp3d/tools/sim-readiness.js) (`grade_sim_readiness`), free REST [api/sim-readiness.js](api/sim-readiness.js) `→ /api/sim-readiness`, shared badge + details panel [public/sim-readiness-panel.js](public/sim-readiness-panel.js) (`<sim-readiness>`, used by [public/viewer.html](public/viewer.html) and [src/model-page.js](src/model-page.js)), write path in [api/_lib/forge-store.js](api/_lib/forge-store.js) `materializeCreation`, docs [docs/sim-readiness.md](docs/sim-readiness.md). | Live | The question a renderer never asks and a rigid-body solver always does: can this mesh be simulated as-is? Four verdicts (`simulation_ready`, `needs_scale`, `needs_repair`, `unusable`, plus `unreadable` for non-glTF bytes) over measurements derived entirely from the geometry: watertightness and winding via welded-position topology, real-world extents read as meters per the glTF unit convention, exact volume/centroid/inertia from the divergence theorem and tetrahedron covariance, and a convex-hull proxy with its convexity ratio. Nothing is guessed: where a value cannot be known from the mesh (true scale, density) the report says so. Grades are keyed by GLB content hash, not URL, so one row serves the forge creation, the Object Library entry, a remix and an arbitrary third-party URL; every finished generation is graded on the write path, so a model page renders its verdict with no extra request. Signed into the content credential as `simReadiness` (provenance v2), which is what makes the physics claim as forge-proof as the authorship claim. Free, no account, no coin surface, both stores. Tests: [tests/sim-readiness.test.js](tests/sim-readiness.test.js), [tests/api/sim-readiness-endpoint.test.js](tests/api/sim-readiness-endpoint.test.js), [tests/provenance-3d.test.js](tests/provenance-3d.test.js). |
| Engine QA (a real-time-engine fitness grade) | Isomorphic core [api/_lib/engine-qa-core.js](api/_lib/engine-qa-core.js) (thresholds + verdict math, zero imports), server grader [api/_lib/engine-qa.js](api/_lib/engine-qa.js), browser-only partial grader [src/engine-qa-client.js](src/engine-qa-client.js), free REST [api/3d/engine-qa.js](api/3d/engine-qa.js) `→ /api/3d/engine-qa` (`?lods=1` builds a real LOD chain first, `?format=stl` exports a watertight mesh), shared badge + details panel [public/engine-qa-panel.js](public/engine-qa-panel.js) (`<engine-qa>`, used by [public/viewer.html](public/viewer.html) and Rig Doctor's [src/rig-doctor-page.js](src/rig-doctor-page.js)), LOD chain builder [packages/glb-tools/src/lod.js](packages/glb-tools/src/lod.js) (`buildLodChain`, real meshoptimizer decimation tagged `MSFT_lod`), opt-in generation variant in [api/_lib/forge-store.js](api/_lib/forge-store.js) (`buildLodVariant`, wired through [api/_lib/forge-options.js](api/_lib/forge-options.js)'s `lods` option) + migration [20261015020000_forge_lod_variant.sql](api/_lib/migrations/20261015020000_forge_lod_variant.sql), docs [docs/engine-qa.md](docs/engine-qa.md) `→ /docs/engine-qa`. | Live | The question a game engine's import step asks that neither glTF validation nor [simulation readiness](docs/sim-readiness.md) answers: will this run at 60fps, and can it collide cheaply? Five checks, each `pass`/`warn`/`fail`/`skip`, overall the worst non-skip verdict: draw calls (real scene-graph walk, one per node+primitive pair actually reachable from the root, so instancing counts correctly), material count, texel density (texels per meter of real-world surface, `skip` honestly when nothing is UV-mapped to a texture), a per-LOD-level triangle budget plus the monotonic-decrease rule a chain must satisfy, and collider suitability (reuses the print pipeline's watertight/manifold analyzer). The thresholds and verdict math live in one zero-dependency core so the server grader and Rig Doctor's zero-network browser pass can never disagree. The same `buildLodChain` pipeline backs an on-demand upgrade in the panel and an opt-in `{ lods: true }` generation option that stores a combined `MSFT_lod` GLB as a third object alongside the delivered mesh, fire-and-forget, same pattern as the existing web-delivery variant. Tests: [tests/engine-qa-core.test.js](tests/engine-qa-core.test.js), [tests/engine-qa.test.js](tests/engine-qa.test.js), [tests/engine-qa-client.test.js](tests/engine-qa-client.test.js), [tests/forge-options.test.js](tests/forge-options.test.js), [tests/forge-store-materialize.test.js](tests/forge-store-materialize.test.js). |
+| Engine bridges (Unity, Godot, Unreal) | Shared contract [specs/ENGINE_BRIDGE.md](specs/ENGINE_BRIDGE.md), Unity UPM package [packages/unity-bridge](packages/unity-bridge) (`ThreeWsClient.cs` + `ThreeWsForgeImporter.cs` on [glTFast](https://github.com/atteneder/glTFast)), Godot addon [packages/godot-bridge](packages/godot-bridge) (`three_ws_client.gd` + `forge_importer.gd` on Godot's native `GLTFDocument`), Unreal plugin [packages/unreal-bridge](packages/unreal-bridge) (`FThreeWsClient` + `FThreeWsForgeImporter` on Unreal's Interchange glTF pipeline), docs [docs/engine-bridges.md](docs/engine-bridges.md) `→ /docs/engine-bridges`. | Live (Unity, Godot) · Unreal plugin ships source-complete, untestable in this environment (no license-free headless Unreal install) | One prompt-to-mesh contract, three independent implementations, each calling only the public Forge API: `POST /api/forge` to submit, `GET /api/forge?job=<id>` to poll (server-side failover keeps the same job id even if the lane dies mid-run), a plain HTTPS GET to download. Anonymous by default via a per-instance `x-forge-client` handle, same free-first routing every other caller gets; set a provider key for BYOK. The same four shared import settings (`generate_colliders`, `import_materials`, `scale`, `destination`) map onto each engine's own equivalent: a convex `MeshCollider` in Unity, a `ConvexPolygonShape3D` in Godot, a bounding-box `UBodySetup` in Unreal. Each package ships an editor window/dock (Unity: `Window > three.ws > Forge Bridge`; Godot: the **three.ws Forge** dock; Unreal: `Window > three.ws Forge Bridge`) plus a runnable example and a README. Godot's `test/smoke_test.gd` runs the full flow headlessly against the live API (`godot --headless --script test/smoke_test.gd`); Unity and Unreal require a licensed GUI install to exercise, so they're verified by code review against the shared contract instead. |
| OpenAI Select Partner (partner surface + announcement pack) | [pages/openai/index.html](pages/openai/index.html) `→ /openai`, badge assets [public/partners/openai/](public/partners/openai), announcement [blog/three-ws-openai-select-partner.html](blog/three-ws-openai-select-partner.html) `→ /blog/three-ws-openai-select-partner`, directory card in [pages/partners.html](pages/partners.html) `→ /partners`, press/social pack [marketing/openai-select-partner/](marketing/openai-select-partner/README.md), original OpenAI-supplied badge files + press-release template [OAI Select Tier Assets/](OAI%20Select%20Tier%20Assets/README.md) | Live | three.ws's OpenAI Partner Network Select-tier surface. `/openai` is the partner landing: the supplied badge (used unmodified, on a white plate), the four live OpenAI surfaces (the free keyless [3D Studio MCP connector](docs/mcp-studio.md) `→ /api/mcp-studio`, the custom-GPT Actions twin `→ /api/3d/studio`, [Spatial MCP](specs/SPATIAL_MCP.md), and [AR in ChatGPT](docs/chatgpt-ar.md)), the connect table, and the eleven-tool list. The marketing pack holds badge-usage rules and the press-release draft, which is gated on OpenAI's written approval before publishing (see its README). |
| NVIDIA Inception (membership surface + GPU docs cluster) | Landing page [pages/nvidia/index.html](pages/nvidia/index.html) `→ /nvidia` (vercel route + vite input + dev middleware, same wiring as `/openai`), membership doc [docs/nvidia-inception.md](docs/nvidia-inception.md) `→ /docs/nvidia-inception` + overview deck [docs/nvidia-inception/index.html](docs/nvidia-inception/index.html) `→ /docs/nvidia-inception/index.html`, free hosted-model map [docs/nvidia-models.md](docs/nvidia-models.md) `→ /docs/nvidia-models`, forum write-up [docs/nvidia-nemotron-spotlight.md](docs/nvidia-nemotron-spotlight.md) `→ /docs/nvidia-nemotron-spotlight`, tutorials [docs/tutorials/nvidia-3d-free.md](docs/tutorials/nvidia-3d-free.md) `→ /tutorials/nvidia-3d-free` and [docs/tutorials/nvidia-nim-self-host.md](docs/tutorials/nvidia-nim-self-host.md) `→ /tutorials/nvidia-nim-self-host`, engineering post [blog/image-to-3d-on-nvidia-l4-and-blackwell.html](blog/image-to-3d-on-nvidia-l4-and-blackwell.html) `→ /blog/image-to-3d-on-nvidia-l4-and-blackwell`, member badge [public/marks/nvidia-inception-badge.svg](public/marks/nvidia-inception-badge.svg) in [public/footer.html](public/footer.html), directory card in [pages/partners.html](pages/partners.html) `→ /partners` | Live | Everything NVIDIA on the platform, in two layers. **Free hosted lane:** one `NVIDIA_API_KEY` behind TRELLIS text-to-3D, FLUX.1-schnell, the Llama/Nemotron chat lineup, Nemotron vision, nv-embedqa, the reranker, NemoGuard, and Magpie speech (`nvidia-models`). **Self-hosted GPU fleet:** 12 Cloud Run GPU services, 11 on `nvidia-l4` and one on `nvidia-rtx-pro-6000` (Blackwell), covering text/image-to-3D, texture, remesh, rigging, and motion (see each `workers/model-*/README.md`). Membership was accepted July 2026 and is a startup program, not a partnership or an investment; the badge links to NVIDIA's startup program and must not imply endorsement. |
| Press kit (brand marks + media assets) | [pages/press/index.html](pages/press/index.html) `→ /press`, marks [public/brand/](public/brand), layout source [marketing/brand/](marketing/brand/README.md), renderer [scripts/render-brand-assets.mjs](scripts/render-brand-assets.mjs) `npm run build:brand-assets` | Live | The self-serve press surface: transparent-PNG marks (cube, horizontal and stacked lockups for dark and light grounds), the OpenAI announcement graphics, boilerplate at four lengths (one line, short, long, and a full-length bio) with copy buttons, fast facts, and the mark-usage rules. Everything is rendered from source rather than hand-exported, so a copy change re-renders the whole set; the renderer also builds `/brand/three-ws-press-kit.zip` with a README carrying the usage rules so the files cannot travel without them. Announcement cards come from [marketing/openai-select-partner/cards/social-card.html](marketing/openai-select-partner/cards/social-card.html) via `npm run build:openai-cards`. |
diff --git a/data/changelog.json b/data/changelog.json
index 5ff7f2bff..87850c325 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,16 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-12",
+ "title": "Three new engine bridges: Unity, Godot, and Unreal, one prompt to a mesh in your editor",
+ "link": "/docs/engine-bridges",
+ "summary": "A shared contract (specs/ENGINE_BRIDGE.md) and three real, independent implementations: a Unity UPM package that imports with glTFast, a Godot addon that imports with Godot's own native GLTFDocument, and an Unreal plugin that imports through Unreal's Interchange glTF pipeline. Each one calls only the public Forge API (POST /api/forge to submit, GET /api/forge?job=<id> to poll, a plain HTTPS GET to download), the same free-first routing and anonymous x-forge-client auth every other Forge caller gets, with the same four import settings (generate_colliders, import_materials, scale, destination) mapped onto each engine's own equivalent. A dropdown and a Generate button in each editor: type a prompt, get a mesh dropped into your scene.",
+ "tags": [
+ "feature",
+ "sdk"
+ ]
+ },
{
"date": "2026-10-12",
"title": "Engine QA: a free real-time-engine fitness grade, plus real LOD chains",
diff --git a/data/pages.json b/data/pages.json
index ac739dfdc..837871ed5 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -5895,6 +5895,14 @@
"priority": 0.6,
"changefreq": "monthly"
},
+ {
+ "path": "/docs/engine-bridges",
+ "title": "Docs · Engine bridges",
+ "description": "One Forge API contract, three real editor integrations: a Unity UPM package, a Godot addon, and an Unreal plugin, each generating a mesh from a prompt and importing it with the engine's own native glTF pipeline.",
+ "added": "2026-10-12",
+ "priority": 0.6,
+ "changefreq": "monthly"
+ },
{
"path": "/docs/remix",
"title": "Docs · The remix economy",
diff --git a/docs/engine-bridges.md b/docs/engine-bridges.md
new file mode 100644
index 000000000..2017f3390
--- /dev/null
+++ b/docs/engine-bridges.md
@@ -0,0 +1,64 @@
+# Engine bridges: Unity, Godot, and Unreal
+
+A glTF viewer answers "does the mesh load." A game engine's import step asks
+a different question: can this ship in *my* project, with *my* pipeline, and
+drop into my scene with one click? The Forge API already generates the
+mesh; these three packages are the one-click part, one per engine, each
+calling the exact same [public Forge API](./forge-pipeline.md) a browser
+would.
+
+- **Contract:** [`specs/ENGINE_BRIDGE.md`](https://github.com/nirholas/three.ws/blob/main/specs/ENGINE_BRIDGE.md), the shared auth/catalog/generate/poll/download/import contract all three bridges implement independently.
+- **Unity:** [`packages/unity-bridge`](https://github.com/nirholas/three.ws/tree/main/packages/unity-bridge), a UPM package using [glTFast](https://github.com/atteneder/glTFast) to import.
+- **Godot:** [`packages/godot-bridge`](https://github.com/nirholas/three.ws/tree/main/packages/godot-bridge), an editor addon using Godot's own native `GLTFDocument` glTF importer.
+- **Unreal:** [`packages/unreal-bridge`](https://github.com/nirholas/three.ws/tree/main/packages/unreal-bridge), a plugin using Unreal's own Interchange glTF pipeline.
+
+No bridge parses glTF itself. Each one is an HTTP client plus a thin adapter
+that hands the downloaded `.glb` to the engine's own first-party importer,
+the same split [`packages/blender-mcp`](https://github.com/nirholas/three.ws/tree/main/packages/blender-mcp) and the [Python Forge client](https://github.com/nirholas/three.ws/blob/main/integrations/_pyclient/three_ws_client.py) vendored into the Blender/ComfyUI/Modly plugins already use.
+
+## Why one spec, three implementations
+
+Unity (C#), Godot (GDScript), and Unreal (C++) have nothing in common at the
+language level, but the API they're calling is one surface:
+[`POST /api/forge`](./forge-pipeline.md) to submit, `GET
+/api/forge?job=<id>` to poll, and a plain HTTPS GET to download the
+finished `.glb`. Writing the contract down once in
+[`specs/ENGINE_BRIDGE.md`](https://github.com/nirholas/three.ws/blob/main/specs/ENGINE_BRIDGE.md)
+means a fourth engine (or a bug report against one of the three) has a
+single source of truth to check against, instead of three READMEs that can
+quietly drift.
+
+Every bridge exposes the same four import settings from the spec under the
+same names, mapped onto whatever each engine calls its own equivalent:
+
+| Setting | Unity | Godot | Unreal |
+|---|---|---|---|
+| `generate_colliders` | `MeshCollider` (convex) | `ConvexPolygonShape3D` | Bounding-box `UBodySetup` |
+| `import_materials` | glTFast materials, or a flat `Standard` | glTF PBR materials, or stripped | Interchange materials, or `UMaterial::GetDefaultMaterial` |
+| `scale` | Applied to the imported root's `localScale` | Applied to the imported root's `scale` | Applied by the caller at the actor level |
+| `destination` | Scene root / parent transform | Scene tree parent | Content-browser path (`/Game/...`) |
+
+## Auth and routing
+
+Generation is anonymous by default: each bridge generates a random
+`x-forge-client` handle per client instance, the same free-first routing
+and lane health every other Forge caller gets (see [the pipeline
+doc](./forge-pipeline.md#4-routing-free-first-subject-aware-health-tempered)
+for the backend grid and circuit breakers). Set a provider key on any client (`ProviderKey` in
+Unity/Unreal, `provider_key` in Godot) to use your own BYOK geometry
+provider instead of the free-tier lane.
+
+## Try it
+
+- **Unity:** install via Package Manager git URL, then **Window > three.ws
+ > Forge Bridge**. See [`packages/unity-bridge/README.md`](https://github.com/nirholas/three.ws/blob/main/packages/unity-bridge/README.md).
+- **Godot:** copy the addon into `addons/`, enable it in Project Settings,
+ use the **three.ws Forge** dock. See
+ [`packages/godot-bridge/README.md`](https://github.com/nirholas/three.ws/blob/main/packages/godot-bridge/README.md).
+- **Unreal:** copy the plugin into `Plugins/`, enable Interchange glTF
+ import, use **Window > three.ws Forge Bridge**. See
+ [`packages/unreal-bridge/README.md`](https://github.com/nirholas/three.ws/blob/main/packages/unreal-bridge/README.md).
+
+Related: [the Forge pipeline](./forge-pipeline.md) for how a submission is
+routed and served, [Engine QA](./engine-qa.md) for grading whether an
+imported mesh will actually run at 60fps once it's in the engine.
diff --git a/packages/godot-bridge/.gitignore b/packages/godot-bridge/.gitignore
new file mode 100644
index 000000000..0f1030258
--- /dev/null
+++ b/packages/godot-bridge/.gitignore
@@ -0,0 +1 @@
+.godot/
diff --git a/packages/godot-bridge/LICENSE b/packages/godot-bridge/LICENSE
new file mode 100644
index 000000000..b5ae2a4e1
--- /dev/null
+++ b/packages/godot-bridge/LICENSE
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2026 nirholas
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/packages/godot-bridge/README.md b/packages/godot-bridge/README.md
new file mode 100644
index 000000000..8166d0aca
--- /dev/null
+++ b/packages/godot-bridge/README.md
@@ -0,0 +1,67 @@
+# three_ws_bridge
+
+Godot 4 addon that calls the public [three.ws](https://three.ws) Forge API to
+generate a 3D mesh from a text prompt or reference image and imports the
+result with Godot's native glTF importer (`GLTFDocument`/`GLTFState`), no
+third-party import library required.
+
+Implements [`specs/ENGINE_BRIDGE.md`](../../specs/ENGINE_BRIDGE.md), the
+contract shared with [`packages/unity-bridge`](../unity-bridge) and
+[`packages/unreal-bridge`](../unreal-bridge).
+
+## Install
+
+1. Copy `addons/three_ws_bridge/` into your project's `addons/` directory
+ (or add this repository as a git submodule and symlink it there).
+2. In Godot: **Project > Project Settings > Plugins**, enable **three.ws
+ Forge Bridge**.
+3. A **three.ws Forge** dock appears in the editor (bottom panel) with a
+ prompt field and a Generate button.
+
+## Runnable example
+
+`example/` is a standalone Godot project that embeds the addon.
+
+```sh
+# Editor, interactive:
+godot --path packages/godot-bridge
+# press Play, type a prompt, click Generate.
+
+# Headless, non-interactive smoke test against the live API:
+godot --headless --path packages/godot-bridge --script test/smoke_test.gd
+```
+
+The example scene (`example/main.gd`) wires a `ThreeWsClient` node to a
+`LineEdit` + `Button` + `Label` UI: typing a prompt and pressing Generate
+submits it to `POST /api/forge`, polls `GET /api/forge?job=<id>` until the
+job finishes, downloads the `.glb`, and imports it into the scene with
+collision generated (`generate_colliders: true`).
+
+`test/smoke_test.gd` is the same flow run headlessly end to end against the
+live API for CI/local verification: catalog browse, text submit, poll,
+download, import, and a printed PASS/FAIL with a process exit code.
+
+## API surface
+
+- `ThreeWsClient` (`addons/three_ws_bridge/three_ws_client.gd`): add one as
+ a child of any node that stays in the tree for the life of a request (the
+ dock, an autoload, or a scene root). Methods: `catalog()`, `health()`,
+ `upload_reference_image(bytes, content_type)`, `submit_text(prompt, tier,
+ path, backend, aspect_ratio)`, `submit_image(image_urls, prompt, tier,
+ path, backend)`, `wait_for_glb(job_id, timeout_sec)`,
+ `download_glb(url, destination_path)`.
+- `ThreeWsForgeImporter` (`addons/three_ws_bridge/forge_importer.gd`):
+ `import_glb(path, import_settings)` wraps `GLTFDocument.append_from_file`
+ + `generate_scene()` and applies the shared import settings
+ (`generate_colliders`, `import_materials`, `scale`) from the spec.
+ `save_as_resource(node, destination_path)` packs the result into a
+ `.tscn` on disk.
+
+Generation is anonymous by default (`ThreeWsClient` generates a random
+`x-forge-client` handle per instance). Set `provider_key` on the client to
+use your own BYOK geometry provider key instead of the free-tier lane; see
+section 1 of the spec.
+
+## License
+
+Apache-2.0, see [`LICENSE`](./LICENSE).
diff --git a/packages/godot-bridge/addons/three_ws_bridge/forge_importer.gd b/packages/godot-bridge/addons/three_ws_bridge/forge_importer.gd
new file mode 100644
index 000000000..48f19fe26
--- /dev/null
+++ b/packages/godot-bridge/addons/three_ws_bridge/forge_importer.gd
@@ -0,0 +1,62 @@
+## Hands a downloaded Forge GLB to Godot's own GLTFDocument. No glTF parsing
+## lives here: this calls the engine's native importer, per
+## specs/ENGINE_BRIDGE.md section 6/7, and applies the four shared import
+## settings every bridge in this spec exposes under the same names.
+extends RefCounted
+class_name ThreeWsForgeImporter
+
+## import_settings keys (all optional, defaults shown):
+## generate_colliders: bool = false
+## import_materials: bool = true
+## scale: float = 1.0
+static func import_glb(glb_path: String, import_settings: Dictionary = {}) -> Node3D:
+ var doc := GLTFDocument.new()
+ var state := GLTFState.new()
+ var err := doc.append_from_file(glb_path, state)
+ if err != OK:
+ push_error("ThreeWsForgeImporter: failed to read %s (error %d)" % [glb_path, err])
+ return null
+
+ var root := doc.generate_scene(state)
+ if root == null:
+ push_error("ThreeWsForgeImporter: GLTFDocument produced no scene for %s" % glb_path)
+ return null
+
+ var scale: float = import_settings.get("scale", 1.0)
+ if scale != 1.0 and root is Node3D:
+ (root as Node3D).scale = Vector3.ONE * scale
+
+ if not import_settings.get("import_materials", true):
+ _strip_materials(root)
+
+ if import_settings.get("generate_colliders", false):
+ _add_convex_colliders(root)
+
+ return root
+
+## Writes the imported scene as a tracked .tscn resource under destination
+## (a res:// path), the Godot-native equivalent of Unity writing under
+## Assets/ or Unreal writing under /Game/.
+static func save_as_resource(root: Node, destination: String) -> Error:
+ var packed := PackedScene.new()
+ var err := packed.pack(root)
+ if err != OK:
+ return err
+ return ResourceSaver.save(packed, destination)
+
+static func _strip_materials(node: Node) -> void:
+ if node is MeshInstance3D:
+ var mi := node as MeshInstance3D
+ var flat := StandardMaterial3D.new()
+ for i in range(mi.get_surface_override_material_count()):
+ mi.set_surface_override_material(i, flat)
+ for child in node.get_children():
+ _strip_materials(child)
+
+static func _add_convex_colliders(node: Node) -> void:
+ if node is MeshInstance3D:
+ var mi := node as MeshInstance3D
+ if mi.mesh != null:
+ mi.create_convex_collision()
+ for child in node.get_children():
+ _add_convex_colliders(child)
diff --git a/packages/godot-bridge/addons/three_ws_bridge/plugin.cfg b/packages/godot-bridge/addons/three_ws_bridge/plugin.cfg
new file mode 100644
index 000000000..b1fec4d45
--- /dev/null
+++ b/packages/godot-bridge/addons/three_ws_bridge/plugin.cfg
@@ -0,0 +1,7 @@
+[plugin]
+
+name="three.ws Forge Bridge"
+description="Generate textured 3D models from a text prompt or reference photos with the free three.ws Forge pipeline, and import the result straight into the scene with Godot's own glTF importer."
+author="three.ws"
+version="0.1.0"
+script="plugin.gd"
diff --git a/packages/godot-bridge/addons/three_ws_bridge/plugin.gd b/packages/godot-bridge/addons/three_ws_bridge/plugin.gd
new file mode 100644
index 000000000..5f7a909b7
--- /dev/null
+++ b/packages/godot-bridge/addons/three_ws_bridge/plugin.gd
@@ -0,0 +1,94 @@
+## Editor dock for the three.ws Forge bridge: a prompt box, a Generate
+## button, and a status label. Builds the UI in code (no .tscn) so the
+## whole addon is plain-text GDScript.
+@tool
+extends EditorPlugin
+
+var _client: ThreeWsClient
+var _dock: Control
+var _prompt_edit: LineEdit
+var _status_label: Label
+var _generate_button: Button
+
+func _enter_tree() -> void:
+ _client = ThreeWsClient.new()
+ _client.name = "ThreeWsClient"
+ add_child(_client)
+
+ _dock = _build_dock()
+ add_control_to_dock(EditorPlugin.DOCK_SLOT_RIGHT_UL, _dock)
+
+func _exit_tree() -> void:
+ if _dock:
+ remove_control_from_docks(_dock)
+ _dock.queue_free()
+ if _client:
+ _client.queue_free()
+
+func _build_dock() -> Control:
+ var panel := VBoxContainer.new()
+ panel.name = "three.ws Forge"
+
+ var title := Label.new()
+ title.text = "three.ws Forge"
+ panel.add_child(title)
+
+ _prompt_edit = LineEdit.new()
+ _prompt_edit.placeholder_text = "a weathered lighthouse"
+ panel.add_child(_prompt_edit)
+
+ _generate_button = Button.new()
+ _generate_button.text = "Generate and import"
+ _generate_button.pressed.connect(_on_generate_pressed)
+ panel.add_child(_generate_button)
+
+ _status_label = Label.new()
+ _status_label.text = "Idle."
+ _status_label.autowrap_mode = TextServer.AUTOWRAP_WORD
+ panel.add_child(_status_label)
+
+ return panel
+
+func _on_generate_pressed() -> void:
+ var prompt := _prompt_edit.text.strip_edges()
+ if prompt == "":
+ _status_label.text = "Type a prompt first."
+ return
+ _generate_button.disabled = true
+ await _run_generation(prompt)
+ _generate_button.disabled = false
+
+func _run_generation(prompt: String) -> void:
+ _status_label.text = "Submitting..."
+ var submitted := await _client.submit_text(prompt)
+ if not submitted.ok:
+ _status_label.text = "Submit failed: %s" % submitted.error
+ return
+
+ var glb_url: String = submitted.glb_url
+ if glb_url == "":
+ _status_label.text = "Generating (%s)..." % submitted.get("backend", "")
+ var finished := await _client.wait_for_glb(submitted.job_id)
+ if not finished.ok:
+ _status_label.text = "Generation failed: %s" % finished.error
+ return
+ glb_url = finished.glb_url
+
+ _status_label.text = "Downloading..."
+ var dest := "user://three_ws_forge_tmp.glb"
+ var downloaded := await _client.download_glb(glb_url, dest)
+ if not downloaded.ok:
+ _status_label.text = "Download failed: %s" % downloaded.error
+ return
+
+ var root := ThreeWsForgeImporter.import_glb(ProjectSettings.globalize_path(dest))
+ if root == null:
+ _status_label.text = "Import failed: GLTFDocument could not read the downloaded file."
+ return
+
+ var edited_scene := EditorInterface.get_edited_scene_root()
+ if edited_scene:
+ edited_scene.add_child(root)
+ root.owner = edited_scene
+
+ _status_label.text = "Imported (%d bytes)." % downloaded.bytes
diff --git a/packages/godot-bridge/addons/three_ws_bridge/three_ws_client.gd b/packages/godot-bridge/addons/three_ws_bridge/three_ws_client.gd
new file mode 100644
index 000000000..04eb6f141
--- /dev/null
+++ b/packages/godot-bridge/addons/three_ws_bridge/three_ws_client.gd
@@ -0,0 +1,210 @@
+## Real HTTP client for the public three.ws Forge pipeline (/api/forge).
+##
+## Implements specs/ENGINE_BRIDGE.md: auth-free generation, catalog browse,
+## text/image submit, poll-to-completion, and GLB download. Add one
+## ThreeWsClient as a child of a node that stays in the scene tree for as
+## long as a request may be in flight (the editor dock, an autoload, or the
+## example scene's root all work); it parents a temporary HTTPRequest per
+## call and frees it when the call resolves.
+##
+## Mirrors the same contract packages/unity-bridge and packages/unreal-bridge
+## implement in their own languages. No glTF parsing happens here: the
+## caller hands the downloaded .glb to Godot's own GLTFDocument.
+extends Node
+class_name ThreeWsClient
+
+const DEFAULT_BASE_URL := "https://three.ws"
+const POLL_INTERVAL_SEC := 2.5
+const BRIDGE_VERSION := "0.1.0"
+
+var base_url: String = DEFAULT_BASE_URL
+var provider_key: String = ""
+## 60s, not 30s: a submit can retry across several lanes server-side
+## (free-first routing + failover) before it responds.
+var request_timeout_sec: float = 60.0
+
+var _client_handle: String = ""
+
+func _ready() -> void:
+ if _client_handle == "":
+ _client_handle = _make_client_handle()
+
+func _make_client_handle() -> String:
+ var rng := RandomNumberGenerator.new()
+ rng.randomize()
+ var out := ""
+ var hex := "0123456789abcdef"
+ for i in range(32):
+ out += hex[rng.randi_range(0, 15)]
+ return out
+
+func _headers(extra_content_type: bool) -> PackedStringArray:
+ var headers: Array[String] = [
+ "Accept: application/json",
+ "x-forge-client: %s" % _client_handle,
+ "x-engine-bridge: godot/%s" % BRIDGE_VERSION,
+ "User-Agent: three-ws-godot-bridge/%s" % BRIDGE_VERSION,
+ ]
+ if provider_key != "":
+ headers.append("x-forge-provider-key: %s" % provider_key)
+ if extra_content_type:
+ headers.append("Content-Type: application/json")
+ return PackedStringArray(headers)
+
+## Fire one HTTP request and await its result. Returns a Dictionary with
+## keys: ok (bool), status (int), body (Dictionary, parsed JSON or {} ),
+## error (String, only set when the request itself failed to complete).
+func _request(path: String, method: HTTPClient.Method, body: Variant = null) -> Dictionary:
+ var req := HTTPRequest.new()
+ req.timeout = request_timeout_sec
+ add_child(req)
+
+ var url := base_url + path
+ var body_str := ""
+ var has_body := body != null
+ if has_body:
+ body_str = JSON.stringify(body)
+
+ var err := req.request(url, _headers(has_body), method, body_str)
+ if err != OK:
+ req.queue_free()
+ return {"ok": false, "status": 0, "body": {}, "error": "request() failed with Godot error %d" % err}
+
+ var result: Array = await req.request_completed
+ req.queue_free()
+
+ var http_result: int = result[0]
+ var response_code: int = result[1]
+ var raw_body: PackedByteArray = result[3]
+
+ if http_result != HTTPRequest.RESULT_SUCCESS:
+ return {"ok": false, "status": response_code, "body": {}, "error": "transport error %d" % http_result}
+
+ var text := raw_body.get_string_from_utf8()
+ var parsed: Variant = {}
+ if text != "":
+ var json := JSON.new()
+ if json.parse(text) == OK:
+ parsed = json.data
+ var ok := response_code >= 200 and response_code < 300
+ return {"ok": ok, "status": response_code, "body": parsed, "error": ""}
+
+## GET /api/forge?catalog=1 -> the live tier/backend/cost matrix.
+func catalog() -> Dictionary:
+ return await _request("/api/forge?catalog=1", HTTPClient.METHOD_GET)
+
+## GET /api/forge?health=1 -> live per-lane up/down status.
+func health() -> Dictionary:
+ return await _request("/api/forge?health=1", HTTPClient.METHOD_GET)
+
+## POST /api/forge-upload -> presign a local reference image, then PUT it.
+## Returns {ok, public_url, error}.
+func upload_reference_image(bytes: PackedByteArray, content_type: String) -> Dictionary:
+ var ctx := HashingContext.new()
+ ctx.start(HashingContext.HASH_SHA256)
+ ctx.update(bytes)
+ var checksum := ctx.finish().hex_encode()
+
+ var presign := await _request("/api/forge-upload", HTTPClient.METHOD_POST, {
+ "content_type": content_type,
+ "size_bytes": bytes.size(),
+ "checksum_sha256": checksum,
+ })
+ if not presign.ok or not presign.body.has("upload_url") or not presign.body.has("public_url"):
+ var message: String = presign.body.get("message", "This deployment has no object storage configured. Pass a public https image URL instead.")
+ return {"ok": false, "public_url": "", "error": message}
+
+ var put := HTTPRequest.new()
+ put.timeout = request_timeout_sec
+ add_child(put)
+ var put_headers: PackedStringArray = PackedStringArray(["Content-Type: %s" % content_type])
+ if presign.body.has("headers"):
+ put_headers = PackedStringArray()
+ for key in presign.body["headers"].keys():
+ put_headers.append("%s: %s" % [key, presign.body["headers"][key]])
+ var err := put.request_raw(presign.body["upload_url"], put_headers, HTTPClient.METHOD_PUT, bytes)
+ if err != OK:
+ put.queue_free()
+ return {"ok": false, "public_url": "", "error": "upload request() failed with Godot error %d" % err}
+ var result: Array = await put.request_completed
+ put.queue_free()
+ var response_code: int = result[1]
+ if response_code < 200 or response_code >= 300:
+ return {"ok": false, "public_url": "", "error": "uploading the reference image failed with HTTP %d" % response_code}
+ return {"ok": true, "public_url": presign.body["public_url"], "error": ""}
+
+## POST /api/forge with a text prompt. Returns the submit response body
+## (job_id + status, or status: "done" + glb_url for a synchronous lane).
+func submit_text(prompt: String, tier: String = "standard", path: String = "image", backend: String = "", aspect_ratio: String = "1:1") -> Dictionary:
+ var body := {"prompt": prompt, "tier": tier, "path": path, "aspect_ratio": aspect_ratio}
+ if backend != "":
+ body["backend"] = backend
+ return await _submit(body)
+
+## POST /api/forge with one or more public https image URLs.
+func submit_image(image_urls: PackedStringArray, prompt: String = "", tier: String = "standard", path: String = "image", backend: String = "") -> Dictionary:
+ var body := {"image_urls": Array(image_urls), "tier": tier, "path": path}
+ if prompt != "":
+ body["prompt"] = prompt
+ if backend != "":
+ body["backend"] = backend
+ return await _submit(body)
+
+func _submit(body: Dictionary) -> Dictionary:
+ var result := await _request("/api/forge", HTTPClient.METHOD_POST, body)
+ if not result.ok:
+ return {"ok": false, "job_id": "", "status": "failed", "glb_url": "", "error": "submit failed with HTTP %d" % result.status}
+ var data: Dictionary = result.body
+ if data.has("error"):
+ return {"ok": false, "job_id": "", "status": "failed", "glb_url": "", "error": data.get("message", data["error"])}
+ return {
+ "ok": true,
+ "job_id": data.get("job_id", ""),
+ "status": data.get("status", "queued"),
+ "glb_url": data.get("glb_url", ""),
+ "backend": data.get("backend", ""),
+ "error": "",
+ }
+
+## Poll GET /api/forge?job=<id> until done or failed, or timeout_sec elapses.
+## Emits no signal: the caller awaits this coroutine directly.
+func wait_for_glb(job_id: String, timeout_sec: float = 600.0) -> Dictionary:
+ var started := Time.get_ticks_msec()
+ while true:
+ var result := await _request("/api/forge?job=%s" % job_id.uri_encode(), HTTPClient.METHOD_GET)
+ if not result.ok:
+ return {"ok": false, "glb_url": "", "backend": "", "error": "poll failed with HTTP %d" % result.status}
+ var data: Dictionary = result.body
+ var status: String = data.get("status", "running")
+ if status == "done" and data.has("glb_url"):
+ return {"ok": true, "glb_url": data["glb_url"], "backend": data.get("backend", ""), "error": ""}
+ if status == "failed":
+ return {"ok": false, "glb_url": "", "backend": "", "error": data.get("error", "Generation failed.")}
+ var elapsed_sec := float(Time.get_ticks_msec() - started) / 1000.0
+ if elapsed_sec > timeout_sec:
+ return {"ok": false, "glb_url": "", "backend": "", "error": "generation %s was still \"%s\" after %ds" % [job_id, status, int(elapsed_sec)]}
+ await get_tree().create_timer(POLL_INTERVAL_SEC).timeout
+ return {"ok": false, "glb_url": "", "backend": "", "error": "unreachable"}
+
+## Download a finished GLB to an absolute filesystem path. Returns
+## {ok, path, bytes, error}.
+func download_glb(url: String, destination_path: String) -> Dictionary:
+ var req := HTTPRequest.new()
+ req.timeout = request_timeout_sec
+ req.download_file = destination_path
+ add_child(req)
+ var err := req.request(url, PackedStringArray(["User-Agent: three-ws-godot-bridge/%s" % BRIDGE_VERSION]), HTTPClient.METHOD_GET)
+ if err != OK:
+ req.queue_free()
+ return {"ok": false, "path": "", "bytes": 0, "error": "download request() failed with Godot error %d" % err}
+ var result: Array = await req.request_completed
+ var response_code: int = result[1]
+ req.queue_free()
+ if response_code < 200 or response_code >= 300:
+ return {"ok": false, "path": "", "bytes": 0, "error": "downloading the GLB failed with HTTP %d" % response_code}
+ var file := FileAccess.open(destination_path, FileAccess.READ)
+ var bytes := 0
+ if file:
+ bytes = file.get_length()
+ file.close()
+ return {"ok": true, "path": destination_path, "bytes": bytes, "error": ""}
diff --git a/packages/godot-bridge/example/main.gd b/packages/godot-bridge/example/main.gd
new file mode 100644
index 000000000..28085d7f3
--- /dev/null
+++ b/packages/godot-bridge/example/main.gd
@@ -0,0 +1,58 @@
+## Runnable example for packages/godot-bridge: type a prompt, press Generate,
+## watch a real three.ws Forge generation land in the scene.
+##
+## Run it: `godot --path packages/godot-bridge` (opens the editor on this
+## project) then press Play, or headless with
+## `godot --headless --path packages/godot-bridge example/main.tscn`.
+extends Node3D
+
+@onready var client: ThreeWsClient = $ThreeWsClient
+@onready var prompt_edit: LineEdit = $UI/Panel/VBox/PromptEdit
+@onready var generate_button: Button = $UI/Panel/VBox/GenerateButton
+@onready var status_label: Label = $UI/Panel/VBox/StatusLabel
+
+var _imported_root: Node3D
+
+func _ready() -> void:
+ generate_button.pressed.connect(_on_generate_pressed)
+
+func _on_generate_pressed() -> void:
+ var prompt := prompt_edit.text.strip_edges()
+ if prompt == "":
+ status_label.text = "Type a prompt first."
+ return
+ generate_button.disabled = true
+ await _generate(prompt)
+ generate_button.disabled = false
+
+func _generate(prompt: String) -> void:
+ status_label.text = "Submitting \"%s\"..." % prompt
+ var submitted := await client.submit_text(prompt, "draft")
+ if not submitted.ok:
+ status_label.text = "Submit failed: %s" % submitted.error
+ return
+
+ var glb_url: String = submitted.glb_url
+ if glb_url == "":
+ status_label.text = "Generating on %s..." % submitted.backend
+ var finished := await client.wait_for_glb(submitted.job_id)
+ if not finished.ok:
+ status_label.text = "Generation failed: %s" % finished.error
+ return
+ glb_url = finished.glb_url
+
+ status_label.text = "Downloading..."
+ var dest := OS.get_cache_dir().path_join("three_ws_example.glb")
+ var downloaded := await client.download_glb(glb_url, dest)
+ if not downloaded.ok:
+ status_label.text = "Download failed: %s" % downloaded.error
+ return
+
+ if _imported_root:
+ _imported_root.queue_free()
+ _imported_root = ThreeWsForgeImporter.import_glb(dest, {"generate_colliders": true})
+ if _imported_root == null:
+ status_label.text = "Import failed."
+ return
+ add_child(_imported_root)
+ status_label.text = "Imported %d bytes from %s." % [downloaded.bytes, dest]
diff --git a/packages/godot-bridge/example/main.tscn b/packages/godot-bridge/example/main.tscn
new file mode 100644
index 000000000..34e3590be
--- /dev/null
+++ b/packages/godot-bridge/example/main.tscn
@@ -0,0 +1,41 @@
+[gd_scene load_steps=3 format=3]
+
+[ext_resource type="Script" path="res://example/main.gd" id="1"]
+[ext_resource type="Script" path="res://addons/three_ws_bridge/three_ws_client.gd" id="2"]
+
+[node name="Main" type="Node3D"]
+script = ExtResource("1")
+
+[node name="ThreeWsClient" type="Node" parent="."]
+script = ExtResource("2")
+
+[node name="Camera3D" type="Camera3D" parent="."]
+transform = Transform3D(1, 0, 0, 0, 0.866, 0.5, 0, -0.5, 0.866, 0, 1.5, 3)
+
+[node name="DirectionalLight3D" type="DirectionalLight3D" parent="."]
+transform = Transform3D(0.866, -0.433, 0.25, 0, 0.5, 0.866, -0.5, -0.75, 0.433, 0, 3, 0)
+
+[node name="UI" type="CanvasLayer" parent="."]
+
+[node name="Panel" type="Panel" parent="UI"]
+offset_left = 16.0
+offset_top = 16.0
+offset_right = 416.0
+offset_bottom = 132.0
+
+[node name="VBox" type="VBoxContainer" parent="UI/Panel"]
+offset_left = 8.0
+offset_top = 8.0
+offset_right = 392.0
+offset_bottom = 108.0
+
+[node name="PromptEdit" type="LineEdit" parent="UI/Panel/VBox"]
+custom_minimum_size = Vector2(384, 0)
+placeholder_text = "a weathered lighthouse"
+
+[node name="GenerateButton" type="Button" parent="UI/Panel/VBox"]
+text = "Generate"
+
+[node name="StatusLabel" type="Label" parent="UI/Panel/VBox"]
+text = "Idle."
+autowrap_mode = 3
diff --git a/packages/godot-bridge/project.godot b/packages/godot-bridge/project.godot
new file mode 100644
index 000000000..ec9ebc318
--- /dev/null
+++ b/packages/godot-bridge/project.godot
@@ -0,0 +1,16 @@
+; Engine configuration file.
+; This is a minimal project: it exists so the addon and the runnable example
+; below have a real project context, and so the headless smoke test
+; (test/smoke_test.gd) has a project.godot to run against.
+
+config_version=5
+
+[application]
+
+config/name="three.ws Forge Bridge example"
+run/main_scene="res://example/main.tscn"
+config/features=PackedStringArray("4.3", "Forward Plus")
+
+[editor_plugins]
+
+enabled=PackedStringArray("res://addons/three_ws_bridge/plugin.cfg")
diff --git a/packages/godot-bridge/test/smoke_test.gd b/packages/godot-bridge/test/smoke_test.gd
new file mode 100644
index 000000000..450e2ab91
--- /dev/null
+++ b/packages/godot-bridge/test/smoke_test.gd
@@ -0,0 +1,76 @@
+## Headless end-to-end smoke test against the LIVE three.ws Forge API.
+## No mock server: this is the exact contract in specs/ENGINE_BRIDGE.md
+## exercised for real. Run with:
+##
+## godot --headless --path packages/godot-bridge --script test/smoke_test.gd
+##
+## Exits 0 and prints PASS on success, exits 1 and prints FAIL on any
+## failure (network, submit, poll timeout, or a GLTFDocument import error).
+extends SceneTree
+
+func _initialize() -> void:
+ _run()
+
+func _run() -> void:
+ var client := ThreeWsClient.new()
+ root.add_child(client)
+ await process_frame
+
+ print("[smoke] GET /api/forge?catalog=1")
+ var cat := await client.catalog()
+ if not cat.ok:
+ _fail("catalog() returned HTTP %d" % cat.status)
+ return
+ print("[smoke] catalog OK, backends: %s" % str(cat.body.get("backends", cat.body.keys())))
+
+ print("[smoke] POST /api/forge (draft text prompt)")
+ var submitted := await client.submit_text("a small red cube", "draft")
+ if not submitted.ok:
+ _fail("submit_text() failed: %s" % submitted.error)
+ return
+ print("[smoke] submitted, job_id=%s backend=%s status=%s" % [submitted.job_id, submitted.backend, submitted.status])
+
+ var glb_url: String = submitted.glb_url
+ if glb_url == "":
+ var finished := await client.wait_for_glb(submitted.job_id, 600.0)
+ if not finished.ok:
+ _fail("wait_for_glb() failed: %s" % finished.error)
+ return
+ glb_url = finished.glb_url
+ print("[smoke] generation done, glb_url=%s" % glb_url)
+
+ var dest := OS.get_cache_dir().path_join("three_ws_smoke_test.glb")
+ var downloaded := await client.download_glb(glb_url, dest)
+ if not downloaded.ok:
+ _fail("download_glb() failed: %s" % downloaded.error)
+ return
+ if downloaded.bytes <= 0:
+ _fail("downloaded GLB is empty")
+ return
+ print("[smoke] downloaded %d bytes to %s" % [downloaded.bytes, dest])
+
+ var imported := ThreeWsForgeImporter.import_glb(dest)
+ if imported == null:
+ _fail("ThreeWsForgeImporter.import_glb() returned null")
+ return
+ var mesh_count := _count_mesh_instances(imported)
+ print("[smoke] GLTFDocument imported the scene, %d MeshInstance3D node(s)" % mesh_count)
+ if mesh_count <= 0:
+ _fail("imported scene has no MeshInstance3D nodes")
+ return
+
+ print("PASS")
+ quit(0)
+
+func _count_mesh_instances(node: Node) -> int:
+ var count := 0
+ if node is MeshInstance3D:
+ count += 1
+ for child in node.get_children():
+ count += _count_mesh_instances(child)
+ return count
+
+func _fail(message: String) -> void:
+ printerr("[smoke] FAIL: %s" % message)
+ print("FAIL")
+ quit(1)
diff --git a/packages/unity-bridge/Editor/ThreeWsBridge.Editor.asmdef b/packages/unity-bridge/Editor/ThreeWsBridge.Editor.asmdef
new file mode 100644
index 000000000..ebc2c6dbe
--- /dev/null
+++ b/packages/unity-bridge/Editor/ThreeWsBridge.Editor.asmdef
@@ -0,0 +1,20 @@
+{
+ "name": "ThreeWs.ForgeBridge.Editor",
+ "rootNamespace": "ThreeWs.ForgeBridge.Editor",
+ "references": [
+ "ThreeWs.ForgeBridge.Runtime",
+ "Unity.glTFast",
+ "Newtonsoft.Json"
+ ],
+ "includePlatforms": [
+ "Editor"
+ ],
+ "excludePlatforms": [],
+ "allowUnsafeCode": false,
+ "overrideReferences": false,
+ "precompiledReferences": [],
+ "autoReferenced": true,
+ "defineConstraints": [],
+ "versionDefines": [],
+ "noEngineReferences": false
+}
diff --git a/packages/unity-bridge/Editor/ThreeWsForgeWindow.cs b/packages/unity-bridge/Editor/ThreeWsForgeWindow.cs
new file mode 100644
index 000000000..5ed97a0b0
--- /dev/null
+++ b/packages/unity-bridge/Editor/ThreeWsForgeWindow.cs
@@ -0,0 +1,106 @@
+// Editor window: a prompt field, a tier dropdown, and a Generate button
+// that runs a real text-to-3D generation and imports the result into the
+// open scene using glTFast.
+using System.IO;
+using ThreeWs.ForgeBridge;
+using UnityEditor;
+using UnityEngine;
+
+namespace ThreeWs.ForgeBridge.Editor
+{
+ public class ThreeWsForgeWindow : EditorWindow
+ {
+ private string _prompt = "a weathered lighthouse";
+ private int _tierIndex = 1;
+ private static readonly string[] Tiers = { "draft", "standard", "high" };
+ private string _status = "Idle.";
+ private bool _busy;
+
+ [MenuItem("Window/three.ws/Forge Bridge")]
+ public static void Open()
+ {
+ GetWindow<ThreeWsForgeWindow>("three.ws Forge");
+ }
+
+ private void OnGUI()
+ {
+ EditorGUILayout.LabelField("three.ws Forge", EditorStyles.boldLabel);
+ EditorGUILayout.Space();
+
+ _prompt = EditorGUILayout.TextField("Prompt", _prompt);
+ _tierIndex = EditorGUILayout.Popup("Tier", _tierIndex, Tiers);
+
+ EditorGUILayout.Space();
+ using (new EditorGUI.DisabledScope(_busy || string.IsNullOrWhiteSpace(_prompt)))
+ {
+ if (GUILayout.Button("Generate and import"))
+ {
+ _ = RunGenerationAsync();
+ }
+ }
+
+ EditorGUILayout.Space();
+ EditorGUILayout.LabelField("Status", _status);
+ }
+
+ private async System.Threading.Tasks.Task RunGenerationAsync()
+ {
+ _busy = true;
+ _status = "Submitting...";
+ Repaint();
+
+ var client = new ThreeWsClient();
+ try
+ {
+ var submitted = await client.SubmitTextAsync(_prompt, Tiers[_tierIndex]);
+ if (!submitted.Ok)
+ {
+ _status = $"Submit failed: {submitted.Error}";
+ return;
+ }
+
+ var glbUrl = submitted.GlbUrl;
+ if (string.IsNullOrEmpty(glbUrl))
+ {
+ _status = $"Generating ({submitted.Backend})...";
+ Repaint();
+ var finished = await client.WaitForGlbAsync(submitted.JobId);
+ if (!finished.Ok)
+ {
+ _status = $"Generation failed: {finished.Error}";
+ return;
+ }
+ glbUrl = finished.GlbUrl;
+ }
+
+ _status = "Downloading...";
+ Repaint();
+ var destination = Path.Combine(Application.temporaryCachePath, "three_ws_forge_tmp.glb");
+ var downloaded = await client.DownloadGlbAsync(glbUrl, destination);
+ if (!downloaded.Ok)
+ {
+ _status = $"Download failed: {downloaded.Error}";
+ return;
+ }
+
+ _status = "Importing...";
+ Repaint();
+ var imported = await ThreeWsForgeImporter.ImportGlbAsync(destination);
+ if (imported == null)
+ {
+ _status = "Import failed: glTFast could not read the downloaded file.";
+ return;
+ }
+
+ Undo.RegisterCreatedObjectUndo(imported, "Generate from three.ws Forge");
+ Selection.activeGameObject = imported;
+ _status = $"Imported {downloaded.Bytes} bytes.";
+ }
+ finally
+ {
+ _busy = false;
+ Repaint();
+ }
+ }
+ }
+}
diff --git a/packages/unity-bridge/LICENSE b/packages/unity-bridge/LICENSE
new file mode 100644
index 000000000..b5ae2a4e1
--- /dev/null
+++ b/packages/unity-bridge/LICENSE
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2026 nirholas
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/packages/unity-bridge/README.md b/packages/unity-bridge/README.md
new file mode 100644
index 000000000..2280725dd
--- /dev/null
+++ b/packages/unity-bridge/README.md
@@ -0,0 +1,70 @@
+# com.three-ws.forge-bridge
+
+Unity UPM package that calls the public [three.ws](https://three.ws) Forge API
+to generate a 3D mesh from a text prompt or reference image and imports the
+result into your scene with [glTFast](https://github.com/atteneder/glTFast).
+
+Implements [`specs/ENGINE_BRIDGE.md`](../../specs/ENGINE_BRIDGE.md), the
+contract shared with [`packages/godot-bridge`](../godot-bridge) and
+[`packages/unreal-bridge`](../unreal-bridge). No glTF parsing lives in this
+package: `ThreeWsForgeImporter` hands the downloaded `.glb` straight to
+glTFast.
+
+## Install
+
+### Option A: Git URL (recommended)
+
+In Unity, open **Window > Package Manager > + > Add package from git URL**
+and enter:
+
+```
+https://github.com/nirholas/three.ws.git?path=/packages/unity-bridge
+```
+
+### Option B: Local path
+
+Clone this repository, then in Package Manager choose
+**+ > Add package from disk** and select
+`packages/unity-bridge/package.json`.
+
+Unity resolves the `com.unity.cloud.gltfast` and
+`com.unity.nuget.newtonsoft-json` dependencies automatically from the
+registry.
+
+## Runnable example
+
+1. After installing, open **Window > Package Manager**, select
+ **three.ws Forge Bridge** in the *In Project* list, and import the
+ **Generate From Prompt** sample.
+2. Open **Window > three.ws > Forge Bridge**.
+3. Type a prompt (e.g. "a weathered lighthouse"), pick a tier, and click
+ **Generate and import**. The window submits the prompt to
+ `POST /api/forge`, polls `GET /api/forge?job=<id>` until it finishes,
+ downloads the `.glb`, and imports it into the open scene as a selected,
+ undo-able `GameObject`.
+
+The imported sample script
+(`Samples~/GenerateFromPrompt/GenerateFromPromptSample.cs`) shows the same
+flow driven at runtime instead of from editor tooling: attach it to any
+`GameObject`, enter Play mode, and press **Space** to generate and drop a
+mesh in front of the main camera.
+
+## API surface
+
+- `ThreeWsClient` (`Runtime/ThreeWsClient.cs`): `GetCatalogAsync`,
+ `GetHealthAsync`, `UploadReferenceImageAsync`, `SubmitTextAsync`,
+ `SubmitImageAsync`, `WaitForGlbAsync`, `DownloadGlbAsync`.
+- `ThreeWsForgeImporter` (`Runtime/ThreeWsForgeImporter.cs`):
+ `ImportGlbAsync(path, parent, settings)` wraps glTFast's
+ `GltfImport.Load` / `InstantiateMainSceneAsync` and applies the shared
+ import settings (`generate_colliders`, `import_materials`, `scale`) from
+ the spec.
+
+Generation is anonymous by default (an `x-forge-client` handle is generated
+per `ThreeWsClient` instance). Set `ThreeWsClient.ProviderKey` to use your
+own BYOK geometry provider key instead of the free-tier lane; see section 1
+of the spec.
+
+## License
+
+Apache-2.0, see [`LICENSE`](./LICENSE).
diff --git a/packages/unity-bridge/Runtime/ThreeWsBridge.Runtime.asmdef b/packages/unity-bridge/Runtime/ThreeWsBridge.Runtime.asmdef
new file mode 100644
index 000000000..87c4ddd49
--- /dev/null
+++ b/packages/unity-bridge/Runtime/ThreeWsBridge.Runtime.asmdef
@@ -0,0 +1,17 @@
+{
+ "name": "ThreeWs.ForgeBridge.Runtime",
+ "rootNamespace": "ThreeWs.ForgeBridge",
+ "references": [
+ "Unity.glTFast",
+ "Newtonsoft.Json"
+ ],
+ "includePlatforms": [],
+ "excludePlatforms": [],
+ "allowUnsafeCode": false,
+ "overrideReferences": false,
+ "precompiledReferences": [],
+ "autoReferenced": true,
+ "defineConstraints": [],
+ "versionDefines": [],
+ "noEngineReferences": false
+}
diff --git a/packages/unity-bridge/Runtime/ThreeWsClient.cs b/packages/unity-bridge/Runtime/ThreeWsClient.cs
new file mode 100644
index 000000000..ffd995ee5
--- /dev/null
+++ b/packages/unity-bridge/Runtime/ThreeWsClient.cs
@@ -0,0 +1,314 @@
+// Real HTTP client for the public three.ws Forge pipeline (/api/forge).
+// Implements specs/ENGINE_BRIDGE.md: auth-free generation, catalog browse,
+// text/image submit, poll-to-completion, and GLB download. No glTF parsing
+// lives here: ThreeWsForgeImporter hands the downloaded bytes to glTFast.
+//
+// Mirrors the contract packages/godot-bridge and packages/unreal-bridge
+// implement in their own languages.
+using System;
+using System.Collections.Generic;
+using System.Security.Cryptography;
+using System.Text;
+using System.Threading.Tasks;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+using UnityEngine;
+using UnityEngine.Networking;
+
+namespace ThreeWs.ForgeBridge
+{
+ /// <summary>Result of a submit or poll call against POST/GET /api/forge.</summary>
+ public class ForgeJobResult
+ {
+ public bool Ok;
+ public string JobId = "";
+ public string Status = "";
+ public string GlbUrl = "";
+ public string Backend = "";
+ public string Error = "";
+ }
+
+ /// <summary>Result of downloading a finished GLB to a local path.</summary>
+ public class ForgeDownloadResult
+ {
+ public bool Ok;
+ public string Path = "";
+ public long Bytes;
+ public string Error = "";
+ }
+
+ public class ThreeWsClient
+ {
+ public const string BridgeVersion = "0.1.0";
+ private const float PollIntervalSeconds = 2.5f;
+
+ public string BaseUrl = "https://three.ws";
+ public string ProviderKey = "";
+ // 60s, not 30s: a submit can retry across several lanes server-side
+ // (free-first routing + failover) before it responds.
+ public int RequestTimeoutSeconds = 60;
+
+ private readonly string _clientHandle;
+
+ public ThreeWsClient()
+ {
+ _clientHandle = Guid.NewGuid().ToString("N");
+ }
+
+ private UnityWebRequest BuildRequest(string path, string method, byte[] body, bool hasBody)
+ {
+ var request = new UnityWebRequest(BaseUrl + path, method);
+ request.timeout = RequestTimeoutSeconds;
+ request.downloadHandler = new DownloadHandlerBuffer();
+ if (hasBody)
+ {
+ request.uploadHandler = new UploadHandlerRaw(body);
+ request.SetRequestHeader("Content-Type", "application/json");
+ }
+ request.SetRequestHeader("Accept", "application/json");
+ request.SetRequestHeader("x-forge-client", _clientHandle);
+ request.SetRequestHeader("x-engine-bridge", "unity/" + BridgeVersion);
+ request.SetRequestHeader("User-Agent", "three-ws-unity-bridge/" + BridgeVersion);
+ if (!string.IsNullOrEmpty(ProviderKey))
+ {
+ request.SetRequestHeader("x-forge-provider-key", ProviderKey);
+ }
+ return request;
+ }
+
+ private static async Task WaitFor(UnityWebRequestAsyncOperation op)
+ {
+ while (!op.isDone)
+ {
+ await Task.Yield();
+ }
+ }
+
+ private async Task<(bool ok, long status, JObject body, string error)> RequestAsync(
+ string path, string method, object jsonBody = null)
+ {
+ byte[] bodyBytes = null;
+ bool hasBody = jsonBody != null;
+ if (hasBody)
+ {
+ bodyBytes = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(jsonBody));
+ }
+
+ using var request = BuildRequest(path, method, bodyBytes, hasBody);
+ try
+ {
+ await WaitFor(request.SendWebRequest());
+ }
+ catch (Exception ex)
+ {
+ return (false, 0, new JObject(), $"request failed: {ex.Message}");
+ }
+
+ if (request.result == UnityWebRequest.Result.ConnectionError ||
+ request.result == UnityWebRequest.Result.DataProcessingError)
+ {
+ return (false, request.responseCode, new JObject(), request.error);
+ }
+
+ var text = request.downloadHandler.text;
+ JObject parsed = new JObject();
+ if (!string.IsNullOrEmpty(text))
+ {
+ try
+ {
+ parsed = JObject.Parse(text);
+ }
+ catch (JsonException)
+ {
+ // Non-JSON body (e.g. an upstream gateway HTML error page). Leave parsed empty;
+ // callers treat an empty body with a non-2xx status as a generic HTTP failure.
+ }
+ }
+
+ bool ok = request.responseCode >= 200 && request.responseCode < 300;
+ return (ok, request.responseCode, parsed, "");
+ }
+
+ /// <summary>GET /api/forge?catalog=1, the live tier/backend/cost matrix.</summary>
+ public async Task<JObject> GetCatalogAsync()
+ {
+ var (ok, status, body, _) = await RequestAsync("/api/forge?catalog=1", UnityWebRequest.kHttpVerbGET);
+ if (!ok)
+ {
+ throw new ForgeException($"catalog request failed with HTTP {status}");
+ }
+ return body;
+ }
+
+ /// <summary>GET /api/forge?health=1, live per-lane up/down status.</summary>
+ public async Task<JObject> GetHealthAsync()
+ {
+ var (ok, status, body, _) = await RequestAsync("/api/forge?health=1", UnityWebRequest.kHttpVerbGET);
+ if (!ok)
+ {
+ throw new ForgeException($"health request failed with HTTP {status}");
+ }
+ return body;
+ }
+
+ /// <summary>POST /api/forge-upload, then PUT the bytes. Returns the public URL.</summary>
+ public async Task<string> UploadReferenceImageAsync(byte[] bytes, string contentType)
+ {
+ string checksum;
+ using (var sha256 = SHA256.Create())
+ {
+ checksum = BitConverter.ToString(sha256.ComputeHash(bytes)).Replace("-", "").ToLowerInvariant();
+ }
+
+ var presignBody = new Dictionary<string, object>
+ {
+ ["content_type"] = contentType,
+ ["size_bytes"] = bytes.Length,
+ ["checksum_sha256"] = checksum,
+ };
+ var (ok, _, presign, _) = await RequestAsync("/api/forge-upload", UnityWebRequest.kHttpVerbPOST, presignBody);
+ if (!ok || presign["upload_url"] == null || presign["public_url"] == null)
+ {
+ var message = presign["message"]?.ToString() ??
+ "This deployment has no object storage configured. Pass a public https image URL instead.";
+ throw new ForgeException(message);
+ }
+
+ using var put = new UnityWebRequest(presign["upload_url"]!.ToString(), UnityWebRequest.kHttpVerbPUT);
+ put.uploadHandler = new UploadHandlerRaw(bytes);
+ put.downloadHandler = new DownloadHandlerBuffer();
+ if (presign["headers"] is JObject headerMap)
+ {
+ foreach (var pair in headerMap)
+ {
+ put.SetRequestHeader(pair.Key, pair.Value?.ToString() ?? "");
+ }
+ }
+ else
+ {
+ put.SetRequestHeader("Content-Type", contentType);
+ }
+ await WaitFor(put.SendWebRequest());
+ if (put.result != UnityWebRequest.Result.Success)
+ {
+ throw new ForgeException($"uploading the reference image failed with HTTP {put.responseCode}");
+ }
+ return presign["public_url"]!.ToString();
+ }
+
+ /// <summary>POST /api/forge with a text prompt.</summary>
+ public async Task<ForgeJobResult> SubmitTextAsync(
+ string prompt, string tier = "standard", string path = "image", string backend = null, string aspectRatio = "1:1")
+ {
+ var body = new Dictionary<string, object>
+ {
+ ["prompt"] = prompt,
+ ["tier"] = tier,
+ ["path"] = path,
+ ["aspect_ratio"] = aspectRatio,
+ };
+ if (!string.IsNullOrEmpty(backend)) body["backend"] = backend;
+ return await SubmitAsync(body);
+ }
+
+ /// <summary>POST /api/forge with one or more public https image URLs.</summary>
+ public async Task<ForgeJobResult> SubmitImageAsync(
+ IEnumerable<string> imageUrls, string prompt = "", string tier = "standard", string path = "image", string backend = null)
+ {
+ var body = new Dictionary<string, object>
+ {
+ ["image_urls"] = new List<string>(imageUrls),
+ ["tier"] = tier,
+ ["path"] = path,
+ };
+ if (!string.IsNullOrEmpty(prompt)) body["prompt"] = prompt;
+ if (!string.IsNullOrEmpty(backend)) body["backend"] = backend;
+ return await SubmitAsync(body);
+ }
+
+ private async Task<ForgeJobResult> SubmitAsync(Dictionary<string, object> body)
+ {
+ var (ok, status, data, _) = await RequestAsync("/api/forge", UnityWebRequest.kHttpVerbPOST, body);
+ var result = new ForgeJobResult();
+ if (!ok)
+ {
+ result.Error = data["message"]?.ToString() ?? $"submit failed with HTTP {status}";
+ return result;
+ }
+ if (data["error"] != null)
+ {
+ result.Error = data["message"]?.ToString() ?? data["error"]!.ToString();
+ return result;
+ }
+ result.Ok = true;
+ result.JobId = data["job_id"]?.ToString() ?? "";
+ result.Status = data["status"]?.ToString() ?? "queued";
+ result.GlbUrl = data["glb_url"]?.ToString() ?? "";
+ result.Backend = data["backend"]?.ToString() ?? "";
+ return result;
+ }
+
+ /// <summary>
+ /// Poll GET /api/forge?job=&lt;id&gt; until done or failed, or timeoutSeconds elapses.
+ /// Keeps polling the SAME job id throughout: poll-time failover is server-side.
+ /// </summary>
+ public async Task<ForgeJobResult> WaitForGlbAsync(string jobId, float timeoutSeconds = 600f)
+ {
+ var started = Time.realtimeSinceStartupAsDouble;
+ while (true)
+ {
+ var (ok, status, data, _) = await RequestAsync(
+ $"/api/forge?job={UnityWebRequest.EscapeURL(jobId)}", UnityWebRequest.kHttpVerbGET);
+ var result = new ForgeJobResult { JobId = jobId };
+ if (!ok)
+ {
+ result.Error = $"poll failed with HTTP {status}";
+ return result;
+ }
+ var jobStatus = data["status"]?.ToString() ?? "running";
+ if (jobStatus == "done" && data["glb_url"] != null)
+ {
+ result.Ok = true;
+ result.Status = jobStatus;
+ result.GlbUrl = data["glb_url"]!.ToString();
+ result.Backend = data["backend"]?.ToString() ?? "";
+ return result;
+ }
+ if (jobStatus == "failed")
+ {
+ result.Error = data["error"]?.ToString() ?? "Generation failed.";
+ return result;
+ }
+ if (Time.realtimeSinceStartupAsDouble - started > timeoutSeconds)
+ {
+ result.Error = $"generation {jobId} was still \"{jobStatus}\" after {(int)timeoutSeconds}s";
+ return result;
+ }
+ await Task.Delay(TimeSpan.FromSeconds(PollIntervalSeconds));
+ }
+ }
+
+ /// <summary>Stream a generated GLB to a local absolute path.</summary>
+ public async Task<ForgeDownloadResult> DownloadGlbAsync(string url, string destinationPath)
+ {
+ using var request = UnityWebRequest.Get(url);
+ request.SetRequestHeader("User-Agent", "three-ws-unity-bridge/" + BridgeVersion);
+ request.downloadHandler = new DownloadHandlerFile(destinationPath) { removeFileOnAbort = true };
+ await WaitFor(request.SendWebRequest());
+ var result = new ForgeDownloadResult { Path = destinationPath };
+ if (request.result != UnityWebRequest.Result.Success)
+ {
+ result.Error = $"downloading the GLB failed with HTTP {request.responseCode}";
+ return result;
+ }
+ result.Ok = true;
+ result.Bytes = (long)request.downloadedBytes;
+ return result;
+ }
+ }
+
+ public class ForgeException : Exception
+ {
+ public ForgeException(string message) : base(message) { }
+ }
+}
diff --git a/packages/unity-bridge/Runtime/ThreeWsForgeImporter.cs b/packages/unity-bridge/Runtime/ThreeWsForgeImporter.cs
new file mode 100644
index 000000000..9019dcd04
--- /dev/null
+++ b/packages/unity-bridge/Runtime/ThreeWsForgeImporter.cs
@@ -0,0 +1,100 @@
+// Hands a downloaded Forge GLB to glTFast, Unity's glTF importer. No glTF
+// parsing lives here, per specs/ENGINE_BRIDGE.md section 6/7. Applies the
+// four shared import settings every bridge in this spec exposes under the
+// same names.
+using System.Threading.Tasks;
+using GLTFast;
+using UnityEngine;
+
+namespace ThreeWs.ForgeBridge
+{
+ public struct ForgeImportSettings
+ {
+ public bool GenerateColliders;
+ public bool ImportMaterials;
+ public float Scale;
+
+ public static ForgeImportSettings Default => new ForgeImportSettings
+ {
+ GenerateColliders = false,
+ ImportMaterials = true,
+ Scale = 1f,
+ };
+ }
+
+ public static class ThreeWsForgeImporter
+ {
+ /// <summary>
+ /// Loads a local .glb file with glTFast and instantiates it as a child
+ /// of the given parent (pass null to create a free-standing root).
+ /// Returns null and logs an error if glTFast could not load the file.
+ /// </summary>
+ public static async Task<GameObject> ImportGlbAsync(
+ string glbPath, Transform parent = null, ForgeImportSettings? settings = null)
+ {
+ var resolved = settings ?? ForgeImportSettings.Default;
+
+ var gltf = new GltfImport();
+ var loadOk = await gltf.Load(glbPath);
+ if (!loadOk)
+ {
+ Debug.LogError($"ThreeWsForgeImporter: glTFast could not load {glbPath}");
+ return null;
+ }
+
+ var root = new GameObject(System.IO.Path.GetFileNameWithoutExtension(glbPath));
+ if (parent != null)
+ {
+ root.transform.SetParent(parent, false);
+ }
+
+ var instantiateOk = await gltf.InstantiateMainSceneAsync(root.transform);
+ if (!instantiateOk)
+ {
+ Debug.LogError($"ThreeWsForgeImporter: glTFast could not instantiate the scene from {glbPath}");
+ Object.Destroy(root);
+ return null;
+ }
+
+ if (resolved.Scale != 1f)
+ {
+ root.transform.localScale = Vector3.one * resolved.Scale;
+ }
+ if (!resolved.ImportMaterials)
+ {
+ StripMaterials(root);
+ }
+ if (resolved.GenerateColliders)
+ {
+ AddConvexColliders(root);
+ }
+
+ return root;
+ }
+
+ private static void StripMaterials(GameObject root)
+ {
+ var flat = new Material(Shader.Find("Standard"));
+ foreach (var renderer in root.GetComponentsInChildren<MeshRenderer>())
+ {
+ var materials = renderer.sharedMaterials;
+ for (var i = 0; i < materials.Length; i++)
+ {
+ materials[i] = flat;
+ }
+ renderer.sharedMaterials = materials;
+ }
+ }
+
+ private static void AddConvexColliders(GameObject root)
+ {
+ foreach (var filter in root.GetComponentsInChildren<MeshFilter>())
+ {
+ if (filter.sharedMesh == null) continue;
+ var collider = filter.gameObject.AddComponent<MeshCollider>();
+ collider.sharedMesh = filter.sharedMesh;
+ collider.convex = true;
+ }
+ }
+ }
+}
diff --git a/packages/unity-bridge/Samples~/GenerateFromPrompt/GenerateFromPromptSample.cs b/packages/unity-bridge/Samples~/GenerateFromPrompt/GenerateFromPromptSample.cs
new file mode 100644
index 000000000..e6e2b4417
--- /dev/null
+++ b/packages/unity-bridge/Samples~/GenerateFromPrompt/GenerateFromPromptSample.cs
@@ -0,0 +1,85 @@
+// Runtime sample: generates a mesh from a text prompt and drops it in front
+// of the camera when Space is pressed. No editor tooling involved, this is
+// the same Runtime API a shipped game would call.
+using System.IO;
+using ThreeWs.ForgeBridge;
+using UnityEngine;
+
+namespace ThreeWs.ForgeBridge.Samples
+{
+ public class GenerateFromPromptSample : MonoBehaviour
+ {
+ [TextArea]
+ public string Prompt = "a weathered lighthouse";
+ public string Tier = "draft";
+
+ private ThreeWsClient _client;
+ private bool _busy;
+
+ private void Awake()
+ {
+ _client = new ThreeWsClient();
+ }
+
+ private void Update()
+ {
+ if (!_busy && Input.GetKeyDown(KeyCode.Space))
+ {
+ _ = GenerateAsync();
+ }
+ }
+
+ private async System.Threading.Tasks.Task GenerateAsync()
+ {
+ _busy = true;
+ Debug.Log($"three.ws Forge: submitting \"{Prompt}\" ({Tier})...");
+
+ var submitted = await _client.SubmitTextAsync(Prompt, Tier);
+ if (!submitted.Ok)
+ {
+ Debug.LogError($"three.ws Forge: submit failed: {submitted.Error}");
+ _busy = false;
+ return;
+ }
+
+ var glbUrl = submitted.GlbUrl;
+ if (string.IsNullOrEmpty(glbUrl))
+ {
+ Debug.Log($"three.ws Forge: generating on {submitted.Backend}...");
+ var finished = await _client.WaitForGlbAsync(submitted.JobId);
+ if (!finished.Ok)
+ {
+ Debug.LogError($"three.ws Forge: generation failed: {finished.Error}");
+ _busy = false;
+ return;
+ }
+ glbUrl = finished.GlbUrl;
+ }
+
+ var destination = Path.Combine(Application.temporaryCachePath, "three_ws_sample.glb");
+ var downloaded = await _client.DownloadGlbAsync(glbUrl, destination);
+ if (!downloaded.Ok)
+ {
+ Debug.LogError($"three.ws Forge: download failed: {downloaded.Error}");
+ _busy = false;
+ return;
+ }
+
+ var imported = await ThreeWsForgeImporter.ImportGlbAsync(destination);
+ if (imported == null)
+ {
+ Debug.LogError("three.ws Forge: glTFast could not read the downloaded file.");
+ _busy = false;
+ return;
+ }
+
+ var cam = Camera.main;
+ if (cam != null)
+ {
+ imported.transform.position = cam.transform.position + cam.transform.forward * 3f;
+ }
+ Debug.Log($"three.ws Forge: imported {downloaded.Bytes} bytes as \"{imported.name}\".");
+ _busy = false;
+ }
+ }
+}
diff --git a/packages/unity-bridge/Samples~/GenerateFromPrompt/ThreeWsBridge.Samples.GenerateFromPrompt.asmdef b/packages/unity-bridge/Samples~/GenerateFromPrompt/ThreeWsBridge.Samples.GenerateFromPrompt.asmdef
new file mode 100644
index 000000000..242928211
--- /dev/null
+++ b/packages/unity-bridge/Samples~/GenerateFromPrompt/ThreeWsBridge.Samples.GenerateFromPrompt.asmdef
@@ -0,0 +1,18 @@
+{
+ "name": "ThreeWs.ForgeBridge.Samples.GenerateFromPrompt",
+ "rootNamespace": "ThreeWs.ForgeBridge.Samples",
+ "references": [
+ "ThreeWs.ForgeBridge.Runtime",
+ "Unity.glTFast",
+ "Newtonsoft.Json"
+ ],
+ "includePlatforms": [],
+ "excludePlatforms": [],
+ "allowUnsafeCode": false,
+ "overrideReferences": false,
+ "precompiledReferences": [],
+ "autoReferenced": false,
+ "defineConstraints": [],
+ "versionDefines": [],
+ "noEngineReferences": false
+}
diff --git a/packages/unity-bridge/package.json b/packages/unity-bridge/package.json
new file mode 100644
index 000000000..4a9a8476c
--- /dev/null
+++ b/packages/unity-bridge/package.json
@@ -0,0 +1,36 @@
+{
+ "name": "com.three-ws.forge-bridge",
+ "version": "0.1.0",
+ "displayName": "three.ws Forge Bridge",
+ "description": "Generate textured 3D models from a text prompt or reference photos with the free three.ws Forge pipeline, straight into the Unity Editor. Imports the result with glTFast, Unity's own glTF importer. No mock server: every call goes to the live public API documented in specs/ENGINE_BRIDGE.md.",
+ "unity": "2021.3",
+ "license": "Apache-2.0",
+ "author": {
+ "name": "three.ws",
+ "url": "https://three.ws"
+ },
+ "keywords": [
+ "3d",
+ "ai",
+ "forge",
+ "gltf",
+ "gltfast",
+ "three.ws"
+ ],
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/nirholas/three.ws.git",
+ "directory": "packages/unity-bridge"
+ },
+ "dependencies": {
+ "com.unity.cloud.gltfast": "5.1.0",
+ "com.unity.nuget.newtonsoft-json": "3.2.1"
+ },
+ "samples": [
+ {
+ "displayName": "Generate From Prompt",
+ "description": "A runnable example: a MonoBehaviour that performs a real text-to-3D generation and drops the imported mesh in front of the camera at runtime when Space is pressed.",
+ "path": "Samples~/GenerateFromPrompt"
+ }
+ ]
+}
diff --git a/packages/unreal-bridge/LICENSE b/packages/unreal-bridge/LICENSE
new file mode 100644
index 000000000..b5ae2a4e1
--- /dev/null
+++ b/packages/unreal-bridge/LICENSE
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2026 nirholas
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/packages/unreal-bridge/README.md b/packages/unreal-bridge/README.md
new file mode 100644
index 000000000..d449b5f51
--- /dev/null
+++ b/packages/unreal-bridge/README.md
@@ -0,0 +1,65 @@
+# ThreeWsBridge
+
+Unreal Engine plugin that calls the public [three.ws](https://three.ws) Forge
+API to generate a 3D mesh from a text prompt or reference image and imports
+the result through Unreal's own Interchange glTF pipeline, no third-party
+importer required.
+
+Implements [`specs/ENGINE_BRIDGE.md`](../../specs/ENGINE_BRIDGE.md), the
+contract shared with [`packages/unity-bridge`](../unity-bridge) and
+[`packages/godot-bridge`](../godot-bridge).
+
+## Requirements
+
+- Unreal Engine 5.3 or later.
+- Interchange glTF import enabled: **Edit > Project Settings > Editor >
+ Interchange Import > glTF** (on by default in 5.3+; the plugin's import
+ call fails cleanly with a descriptive error if it's off).
+
+## Install
+
+1. Copy `packages/unreal-bridge/` into your project's `Plugins/ThreeWsBridge`
+ directory (or add this repository as a git submodule there).
+2. Open the project; Unreal prompts to rebuild the plugin's modules. Accept.
+3. In the editor: **Edit > Plugins**, confirm **three.ws Forge Bridge**
+ (under *Importers*) is enabled.
+
+## Runnable example
+
+**Window > three.ws Forge Bridge** opens a dock tab with a prompt field, a
+tier dropdown, and a **Generate and import** button. Clicking it:
+
+1. Submits the prompt to `POST /api/forge` (`FThreeWsClient::SubmitText`).
+2. Polls `GET /api/forge?job=<id>` on the core ticker until the job
+ finishes (`FThreeWsClient::WaitForGlb`).
+3. Downloads the `.glb` to `Intermediate/ThreeWsForge/forge_tmp.glb`
+ (`FThreeWsClient::DownloadGlb`).
+4. Imports it via `UInterchangeManager::ImportAssetAsync` into
+ `/Game/ThreeWsForge/Generated` (`FThreeWsForgeImporter::ImportGlb`), then
+ spawns an `AStaticMeshActor` referencing the imported mesh into the
+ currently open level and selects it.
+
+Source: `Source/ThreeWsBridgeEditor/Private/ThreeWsForgeWindow.cpp`.
+
+## API surface
+
+- `FThreeWsClient` (`Source/ThreeWsBridge/Public/ThreeWsClient.h`):
+ `GetCatalog`, `GetHealth`, `UploadReferenceImage`, `SubmitText`,
+ `SubmitImage`, `WaitForGlb`, `DownloadGlb`. All calls are async and take a
+ `TFunction` completion callback; `WaitForGlb` polls on
+ `FTSTicker::GetCoreTicker()` so it works from editor-only code with no
+ active PIE session.
+- `FThreeWsForgeImporter` (`Source/ThreeWsBridge/Public/ThreeWsForgeImporter.h`):
+ `ImportGlb(path, settings, onComplete)` wraps
+ `UInterchangeManager::ImportAssetAsync` and applies the shared import
+ settings (`generate_colliders` as a bounding-box collision proxy,
+ `import_materials`) from the spec.
+
+Generation is anonymous by default (`FThreeWsClient` generates a random
+`x-forge-client` handle per instance). Set `ProviderKey` on the client to
+use your own BYOK geometry provider key instead of the free-tier lane; see
+section 1 of the spec.
+
+## License
+
+Apache-2.0, see [`LICENSE`](./LICENSE).
diff --git a/packages/unreal-bridge/Source/ThreeWsBridge/Private/ThreeWsBridgeModule.cpp b/packages/unreal-bridge/Source/ThreeWsBridge/Private/ThreeWsBridgeModule.cpp
new file mode 100644
index 000000000..fbe635861
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridge/Private/ThreeWsBridgeModule.cpp
@@ -0,0 +1,11 @@
+#include "ThreeWsBridgeModule.h"
+
+void FThreeWsBridgeModule::StartupModule()
+{
+}
+
+void FThreeWsBridgeModule::ShutdownModule()
+{
+}
+
+IMPLEMENT_MODULE(FThreeWsBridgeModule, ThreeWsBridge)
diff --git a/packages/unreal-bridge/Source/ThreeWsBridge/Private/ThreeWsClient.cpp b/packages/unreal-bridge/Source/ThreeWsBridge/Private/ThreeWsClient.cpp
new file mode 100644
index 000000000..8a4484317
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridge/Private/ThreeWsClient.cpp
@@ -0,0 +1,455 @@
+#include "ThreeWsClient.h"
+
+#include "Containers/Ticker.h"
+#include "GenericPlatform/GenericPlatformHttp.h"
+#include "HttpModule.h"
+#include "Dom/JsonValue.h"
+#include "Misc/FileHelper.h"
+#include "Misc/Guid.h"
+#include "Serialization/JsonReader.h"
+#include "Serialization/JsonSerializer.h"
+#include "Serialization/JsonWriter.h"
+
+namespace
+{
+ const FString BridgeVersion = TEXT("0.1.0");
+ constexpr float PollIntervalSeconds = 2.5f;
+
+ FString SerializeJson(const TSharedRef<FJsonObject>& Object)
+ {
+ FString Out;
+ TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&Out);
+ FJsonSerializer::Serialize(Object, Writer);
+ return Out;
+ }
+
+ TSharedPtr<FJsonObject> ParseJsonOrEmpty(const FString& Text)
+ {
+ TSharedPtr<FJsonObject> Parsed = MakeShared<FJsonObject>();
+ if (!Text.IsEmpty())
+ {
+ TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(Text);
+ TSharedPtr<FJsonObject> Candidate;
+ if (FJsonSerializer::Deserialize(Reader, Candidate) && Candidate.IsValid())
+ {
+ Parsed = Candidate;
+ }
+ }
+ return Parsed;
+ }
+
+ // Self-contained SHA-256 (FIPS 180-4). Engine's own "SHA" helpers
+ // (FSHA1 / FSHAHash) are SHA-1, not SHA-256, so the presign endpoint's
+ // checksum_sha256 field needs its own implementation here rather than a
+ // mismatched engine type.
+ FString Sha256Hex(const TArray<uint8>& Data)
+ {
+ static const uint32 K[64] = {
+ 0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,
+ 0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,
+ 0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,
+ 0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,
+ 0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,
+ 0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,
+ 0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,
+ 0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2,
+ };
+ uint32 H[8] = {
+ 0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,
+ 0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19,
+ };
+
+ TArray<uint8> Msg(Data);
+ const uint64 BitLen = (uint64)Data.Num() * 8;
+ Msg.Add(0x80);
+ while (Msg.Num() % 64 != 56)
+ {
+ Msg.Add(0x00);
+ }
+ for (int32 i = 7; i >= 0; i--)
+ {
+ Msg.Add((uint8)((BitLen >> (i * 8)) & 0xff));
+ }
+
+ auto Rotr = [](uint32 X, uint32 N) { return (X >> N) | (X << (32 - N)); };
+
+ for (int32 Chunk = 0; Chunk < Msg.Num(); Chunk += 64)
+ {
+ uint32 W[64];
+ for (int32 i = 0; i < 16; i++)
+ {
+ W[i] = (Msg[Chunk + i * 4] << 24) | (Msg[Chunk + i * 4 + 1] << 16) |
+ (Msg[Chunk + i * 4 + 2] << 8) | (Msg[Chunk + i * 4 + 3]);
+ }
+ for (int32 i = 16; i < 64; i++)
+ {
+ const uint32 S0 = Rotr(W[i - 15], 7) ^ Rotr(W[i - 15], 18) ^ (W[i - 15] >> 3);
+ const uint32 S1 = Rotr(W[i - 2], 17) ^ Rotr(W[i - 2], 19) ^ (W[i - 2] >> 10);
+ W[i] = W[i - 16] + S0 + W[i - 7] + S1;
+ }
+
+ uint32 A = H[0], B = H[1], C = H[2], D = H[3], E = H[4], F = H[5], G = H[6], Hh = H[7];
+ for (int32 i = 0; i < 64; i++)
+ {
+ const uint32 S1 = Rotr(E, 6) ^ Rotr(E, 11) ^ Rotr(E, 25);
+ const uint32 Ch = (E & F) ^ ((~E) & G);
+ const uint32 Temp1 = Hh + S1 + Ch + K[i] + W[i];
+ const uint32 S0 = Rotr(A, 2) ^ Rotr(A, 13) ^ Rotr(A, 22);
+ const uint32 Maj = (A & B) ^ (A & C) ^ (B & C);
+ const uint32 Temp2 = S0 + Maj;
+ Hh = G; G = F; F = E; E = D + Temp1;
+ D = C; C = B; B = A; A = Temp1 + Temp2;
+ }
+ H[0] += A; H[1] += B; H[2] += C; H[3] += D;
+ H[4] += E; H[5] += F; H[6] += G; H[7] += Hh;
+ }
+
+ FString Out;
+ for (uint32 Word : H)
+ {
+ Out += FString::Printf(TEXT("%08x"), Word);
+ }
+ return Out;
+ }
+}
+
+FThreeWsClient::FThreeWsClient()
+{
+ ClientHandle = FGuid::NewGuid().ToString(EGuidFormats::DigitsWithHyphens);
+}
+
+TSharedRef<IHttpRequest, ESPMode::ThreadSafe> FThreeWsClient::BuildRequest(const FString& Path, const FString& Verb) const
+{
+ TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Request = FHttpModule::Get().CreateRequest();
+ Request->SetURL(BaseUrl + Path);
+ Request->SetVerb(Verb);
+ Request->SetTimeout(RequestTimeoutSeconds);
+ Request->SetHeader(TEXT("Accept"), TEXT("application/json"));
+ Request->SetHeader(TEXT("x-forge-client"), ClientHandle);
+ Request->SetHeader(TEXT("x-engine-bridge"), TEXT("unreal/") + BridgeVersion);
+ Request->SetHeader(TEXT("User-Agent"), TEXT("three-ws-unreal-bridge/") + BridgeVersion);
+ if (!ProviderKey.IsEmpty())
+ {
+ Request->SetHeader(TEXT("x-forge-provider-key"), ProviderKey);
+ }
+ return Request;
+}
+
+void FThreeWsClient::GetCatalog(TFunction<void(bool, TSharedPtr<FJsonObject>)> OnComplete)
+{
+ TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Request = BuildRequest(TEXT("/api/forge?catalog=1"), TEXT("GET"));
+ Request->OnProcessRequestComplete().BindLambda(
+ [OnComplete](FHttpRequestPtr, FHttpResponsePtr Response, bool bConnectedSuccessfully)
+ {
+ const bool bOk = bConnectedSuccessfully && Response.IsValid() &&
+ EHttpResponseCodes::IsOk(Response->GetResponseCode());
+ OnComplete(bOk, Response.IsValid() ? ParseJsonOrEmpty(Response->GetContentAsString()) : MakeShared<FJsonObject>());
+ });
+ Request->ProcessRequest();
+}
+
+void FThreeWsClient::GetHealth(TFunction<void(bool, TSharedPtr<FJsonObject>)> OnComplete)
+{
+ TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Request = BuildRequest(TEXT("/api/forge?health=1"), TEXT("GET"));
+ Request->OnProcessRequestComplete().BindLambda(
+ [OnComplete](FHttpRequestPtr, FHttpResponsePtr Response, bool bConnectedSuccessfully)
+ {
+ const bool bOk = bConnectedSuccessfully && Response.IsValid() &&
+ EHttpResponseCodes::IsOk(Response->GetResponseCode());
+ OnComplete(bOk, Response.IsValid() ? ParseJsonOrEmpty(Response->GetContentAsString()) : MakeShared<FJsonObject>());
+ });
+ Request->ProcessRequest();
+}
+
+void FThreeWsClient::UploadReferenceImage(const TArray<uint8>& Bytes, const FString& ContentType,
+ TFunction<void(bool, FString, FString)> OnComplete)
+{
+ TSharedRef<FJsonObject> PresignBody = MakeShared<FJsonObject>();
+ PresignBody->SetStringField(TEXT("content_type"), ContentType);
+ PresignBody->SetNumberField(TEXT("size_bytes"), Bytes.Num());
+ PresignBody->SetStringField(TEXT("checksum_sha256"), Sha256Hex(Bytes));
+
+ TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Presign = BuildRequest(TEXT("/api/forge-upload"), TEXT("POST"));
+ Presign->SetHeader(TEXT("Content-Type"), TEXT("application/json"));
+ Presign->SetContentAsString(SerializeJson(PresignBody));
+
+ TWeakPtr<FThreeWsClient> WeakThis = AsShared();
+ Presign->OnProcessRequestComplete().BindLambda(
+ [this, WeakThis, Bytes, ContentType, OnComplete](FHttpRequestPtr, FHttpResponsePtr Response, bool bConnectedSuccessfully)
+ {
+ if (!WeakThis.IsValid())
+ {
+ return;
+ }
+ if (!bConnectedSuccessfully || !Response.IsValid() || !EHttpResponseCodes::IsOk(Response->GetResponseCode()))
+ {
+ TSharedPtr<FJsonObject> Body = Response.IsValid() ? ParseJsonOrEmpty(Response->GetContentAsString()) : MakeShared<FJsonObject>();
+ FString Message;
+ if (!Body->TryGetStringField(TEXT("message"), Message))
+ {
+ Message = TEXT("This deployment has no object storage configured. Pass a public https image URL instead.");
+ }
+ OnComplete(false, TEXT(""), Message);
+ return;
+ }
+
+ TSharedPtr<FJsonObject> Presigned = ParseJsonOrEmpty(Response->GetContentAsString());
+ FString UploadUrl, PublicUrl;
+ if (!Presigned->TryGetStringField(TEXT("upload_url"), UploadUrl) ||
+ !Presigned->TryGetStringField(TEXT("public_url"), PublicUrl))
+ {
+ OnComplete(false, TEXT(""), TEXT("Presign response was missing upload_url or public_url."));
+ return;
+ }
+
+ TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Put = FHttpModule::Get().CreateRequest();
+ Put->SetURL(UploadUrl);
+ Put->SetVerb(TEXT("PUT"));
+ Put->SetContent(Bytes);
+
+ const TSharedPtr<FJsonObject>* HeaderMap = nullptr;
+ if (Presigned->TryGetObjectField(TEXT("headers"), HeaderMap) && HeaderMap && HeaderMap->IsValid())
+ {
+ for (const auto& Pair : (*HeaderMap)->Values)
+ {
+ Put->SetHeader(Pair.Key, Pair.Value->AsString());
+ }
+ }
+ else
+ {
+ Put->SetHeader(TEXT("Content-Type"), ContentType);
+ }
+
+ Put->OnProcessRequestComplete().BindLambda(
+ [PublicUrl, OnComplete](FHttpRequestPtr, FHttpResponsePtr PutResponse, bool bPutConnected)
+ {
+ const bool bPutOk = bPutConnected && PutResponse.IsValid() &&
+ EHttpResponseCodes::IsOk(PutResponse->GetResponseCode());
+ if (!bPutOk)
+ {
+ const int32 Code = PutResponse.IsValid() ? PutResponse->GetResponseCode() : 0;
+ OnComplete(false, TEXT(""), FString::Printf(TEXT("uploading the reference image failed with HTTP %d"), Code));
+ return;
+ }
+ OnComplete(true, PublicUrl, TEXT(""));
+ });
+ Put->ProcessRequest();
+ });
+ Presign->ProcessRequest();
+}
+
+void FThreeWsClient::SubmitText(const FString& Prompt, const FString& Tier, const FString& Path,
+ const FString& Backend, const FString& AspectRatio, TFunction<void(FForgeJobResult)> OnComplete)
+{
+ TSharedRef<FJsonObject> Body = MakeShared<FJsonObject>();
+ Body->SetStringField(TEXT("prompt"), Prompt);
+ Body->SetStringField(TEXT("tier"), Tier.IsEmpty() ? TEXT("standard") : Tier);
+ Body->SetStringField(TEXT("path"), Path.IsEmpty() ? TEXT("image") : Path);
+ Body->SetStringField(TEXT("aspect_ratio"), AspectRatio.IsEmpty() ? TEXT("1:1") : AspectRatio);
+ if (!Backend.IsEmpty())
+ {
+ Body->SetStringField(TEXT("backend"), Backend);
+ }
+ SubmitInternal(Body, OnComplete);
+}
+
+void FThreeWsClient::SubmitImage(const TArray<FString>& ImageUrls, const FString& Prompt, const FString& Tier,
+ const FString& Path, const FString& Backend, TFunction<void(FForgeJobResult)> OnComplete)
+{
+ TSharedRef<FJsonObject> Body = MakeShared<FJsonObject>();
+ TArray<TSharedPtr<FJsonValue>> UrlValues;
+ for (const FString& Url : ImageUrls)
+ {
+ UrlValues.Add(MakeShared<FJsonValueString>(Url));
+ }
+ Body->SetArrayField(TEXT("image_urls"), UrlValues);
+ Body->SetStringField(TEXT("tier"), Tier.IsEmpty() ? TEXT("standard") : Tier);
+ Body->SetStringField(TEXT("path"), Path.IsEmpty() ? TEXT("image") : Path);
+ if (!Prompt.IsEmpty())
+ {
+ Body->SetStringField(TEXT("prompt"), Prompt);
+ }
+ if (!Backend.IsEmpty())
+ {
+ Body->SetStringField(TEXT("backend"), Backend);
+ }
+ SubmitInternal(Body, OnComplete);
+}
+
+void FThreeWsClient::SubmitInternal(TSharedPtr<FJsonObject> Body, TFunction<void(FForgeJobResult)> OnComplete)
+{
+ TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Request = BuildRequest(TEXT("/api/forge"), TEXT("POST"));
+ Request->SetHeader(TEXT("Content-Type"), TEXT("application/json"));
+ Request->SetContentAsString(SerializeJson(Body.ToSharedRef()));
+
+ Request->OnProcessRequestComplete().BindLambda(
+ [OnComplete](FHttpRequestPtr, FHttpResponsePtr Response, bool bConnectedSuccessfully)
+ {
+ FForgeJobResult Result;
+ if (!bConnectedSuccessfully || !Response.IsValid())
+ {
+ Result.Error = TEXT("submit failed: no response from server");
+ OnComplete(Result);
+ return;
+ }
+ TSharedPtr<FJsonObject> Data = ParseJsonOrEmpty(Response->GetContentAsString());
+ if (!EHttpResponseCodes::IsOk(Response->GetResponseCode()))
+ {
+ FString Message;
+ if (!Data->TryGetStringField(TEXT("message"), Message))
+ {
+ Message = FString::Printf(TEXT("submit failed with HTTP %d"), Response->GetResponseCode());
+ }
+ Result.Error = Message;
+ OnComplete(Result);
+ return;
+ }
+ FString ErrorField;
+ if (Data->TryGetStringField(TEXT("error"), ErrorField))
+ {
+ FString Message;
+ Result.Error = Data->TryGetStringField(TEXT("message"), Message) ? Message : ErrorField;
+ OnComplete(Result);
+ return;
+ }
+ Result.bOk = true;
+ Data->TryGetStringField(TEXT("job_id"), Result.JobId);
+ if (!Data->TryGetStringField(TEXT("status"), Result.Status))
+ {
+ Result.Status = TEXT("queued");
+ }
+ Data->TryGetStringField(TEXT("glb_url"), Result.GlbUrl);
+ Data->TryGetStringField(TEXT("backend"), Result.Backend);
+ OnComplete(Result);
+ });
+ Request->ProcessRequest();
+}
+
+void FThreeWsClient::WaitForGlb(const FString& JobId, float TimeoutSeconds, TFunction<void(FForgeJobResult)> OnComplete)
+{
+ struct FPollState
+ {
+ double StartedSeconds = FPlatformTime::Seconds();
+ bool bRequestInFlight = false;
+ bool bDone = false;
+ };
+ TSharedRef<FPollState> State = MakeShared<FPollState>();
+ TWeakPtr<FThreeWsClient> WeakThis = AsShared();
+
+ FTSTicker::GetCoreTicker().AddTicker(FTickerDelegate::CreateLambda(
+ [WeakThis, JobId, TimeoutSeconds, OnComplete, State](float) -> bool
+ {
+ TSharedPtr<FThreeWsClient> PinnedThis = WeakThis.Pin();
+ if (!PinnedThis.IsValid() || State->bDone)
+ {
+ return false;
+ }
+ if (State->bRequestInFlight)
+ {
+ return true;
+ }
+ State->bRequestInFlight = true;
+
+ TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Request = PinnedThis->BuildRequest(
+ FString::Printf(TEXT("/api/forge?job=%s"), *FGenericPlatformHttp::UrlEncode(JobId)), TEXT("GET"));
+ Request->OnProcessRequestComplete().BindLambda(
+ [JobId, OnComplete, State](FHttpRequestPtr, FHttpResponsePtr Response, bool bConnectedSuccessfully)
+ {
+ State->bRequestInFlight = false;
+ if (State->bDone)
+ {
+ return;
+ }
+ if (!bConnectedSuccessfully || !Response.IsValid())
+ {
+ FForgeJobResult Result;
+ Result.JobId = JobId;
+ Result.Error = TEXT("poll failed: no response from server");
+ State->bDone = true;
+ OnComplete(Result);
+ return;
+ }
+ TSharedPtr<FJsonObject> Data = ParseJsonOrEmpty(Response->GetContentAsString());
+ FString Status;
+ if (!Data->TryGetStringField(TEXT("status"), Status))
+ {
+ Status = TEXT("running");
+ }
+ FString GlbUrl;
+ if (Status == TEXT("done") && Data->TryGetStringField(TEXT("glb_url"), GlbUrl))
+ {
+ FForgeJobResult Result;
+ Result.bOk = true;
+ Result.JobId = JobId;
+ Result.Status = Status;
+ Result.GlbUrl = GlbUrl;
+ Data->TryGetStringField(TEXT("backend"), Result.Backend);
+ State->bDone = true;
+ OnComplete(Result);
+ return;
+ }
+ if (Status == TEXT("failed"))
+ {
+ FForgeJobResult Result;
+ Result.JobId = JobId;
+ FString ErrorMessage;
+ Result.Error = Data->TryGetStringField(TEXT("error"), ErrorMessage) ? ErrorMessage : TEXT("Generation failed.");
+ State->bDone = true;
+ OnComplete(Result);
+ return;
+ }
+ // Still running: the ticker keeps polling until done,
+ // failed, or timeout.
+ });
+ Request->ProcessRequest();
+
+ const double Elapsed = FPlatformTime::Seconds() - State->StartedSeconds;
+ if (Elapsed > TimeoutSeconds)
+ {
+ if (!State->bDone)
+ {
+ FForgeJobResult Result;
+ Result.JobId = JobId;
+ Result.Error = FString::Printf(TEXT("generation %s timed out after %ds"), *JobId, (int32)TimeoutSeconds);
+ State->bDone = true;
+ OnComplete(Result);
+ }
+ return false;
+ }
+ return true;
+ }), PollIntervalSeconds);
+}
+
+void FThreeWsClient::DownloadGlb(const FString& Url, const FString& DestinationPath,
+ TFunction<void(FForgeDownloadResult)> OnComplete)
+{
+ TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Request = FHttpModule::Get().CreateRequest();
+ Request->SetURL(Url);
+ Request->SetVerb(TEXT("GET"));
+ Request->SetHeader(TEXT("User-Agent"), TEXT("three-ws-unreal-bridge/") + BridgeVersion);
+
+ Request->OnProcessRequestComplete().BindLambda(
+ [DestinationPath, OnComplete](FHttpRequestPtr, FHttpResponsePtr Response, bool bConnectedSuccessfully)
+ {
+ FForgeDownloadResult Result;
+ Result.FilePath = DestinationPath;
+ if (!bConnectedSuccessfully || !Response.IsValid() || !EHttpResponseCodes::IsOk(Response->GetResponseCode()))
+ {
+ const int32 Code = Response.IsValid() ? Response->GetResponseCode() : 0;
+ Result.Error = FString::Printf(TEXT("downloading the GLB failed with HTTP %d"), Code);
+ OnComplete(Result);
+ return;
+ }
+ const TArray<uint8>& Content = Response->GetContent();
+ if (!FFileHelper::SaveArrayToFile(Content, *DestinationPath))
+ {
+ Result.Error = FString::Printf(TEXT("could not write %s to disk"), *DestinationPath);
+ OnComplete(Result);
+ return;
+ }
+ Result.bOk = true;
+ Result.Bytes = Content.Num();
+ OnComplete(Result);
+ });
+ Request->ProcessRequest();
+}
diff --git a/packages/unreal-bridge/Source/ThreeWsBridge/Private/ThreeWsForgeImporter.cpp b/packages/unreal-bridge/Source/ThreeWsBridge/Private/ThreeWsForgeImporter.cpp
new file mode 100644
index 000000000..d4e2dd338
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridge/Private/ThreeWsForgeImporter.cpp
@@ -0,0 +1,103 @@
+#include "ThreeWsForgeImporter.h"
+
+#include "InterchangeManager.h"
+#include "InterchangeSourceData.h"
+#include "Engine/StaticMesh.h"
+#include "Materials/Material.h"
+#include "Misc/Paths.h"
+#include "PhysicsEngine/BodySetup.h"
+#include "PhysicsEngine/BoxElem.h"
+
+namespace
+{
+ // Applies the shared import_materials / generate_colliders settings
+ // from specs/ENGINE_BRIDGE.md section 7. Mirrors what
+ // packages/unity-bridge does with a MeshCollider and packages/godot-bridge
+ // does with a ConvexPolygonShape3D: a simple, real collision proxy, not a
+ // convex decomposition (Interchange owns the glTF-specific pipeline
+ // options; this bridge only normalizes the cross-engine knobs).
+ void ApplyForgeImportSettings(UStaticMesh* Mesh, const FForgeImportSettings& Settings)
+ {
+ if (!Mesh)
+ {
+ return;
+ }
+
+ if (!Settings.bImportMaterials)
+ {
+ UMaterialInterface* Flat = UMaterial::GetDefaultMaterial(MD_Surface);
+ const TArray<FStaticMaterial>& Materials = Mesh->GetStaticMaterials();
+ for (int32 Index = 0; Index < Materials.Num(); Index++)
+ {
+ Mesh->SetMaterial(Index, Flat);
+ }
+ }
+
+ if (Settings.bGenerateColliders)
+ {
+ Mesh->CreateBodySetup();
+ if (UBodySetup* BodySetup = Mesh->GetBodySetup())
+ {
+ BodySetup->RemoveSimpleCollision();
+
+ FKBoxElem BoxElem;
+ const FBox Bounds = Mesh->GetBoundingBox();
+ BoxElem.Center = Bounds.GetCenter();
+ const FVector Size = Bounds.GetSize();
+ BoxElem.X = Size.X;
+ BoxElem.Y = Size.Y;
+ BoxElem.Z = Size.Z;
+ BodySetup->AggGeom.BoxElems.Add(BoxElem);
+ BodySetup->CollisionTraceFlag = CTF_UseSimpleAndComplex;
+ BodySetup->CreatePhysicsMeshes();
+ }
+ }
+
+ Mesh->PostEditChange();
+ }
+}
+
+void FThreeWsForgeImporter::ImportGlb(const FString& GlbPath, const FForgeImportSettings& Settings,
+ TFunction<void(UObject*, const FString&)> OnComplete)
+{
+ if (!FPaths::FileExists(GlbPath))
+ {
+ OnComplete(nullptr, FString::Printf(TEXT("ThreeWsForgeImporter: %s does not exist"), *GlbPath));
+ return;
+ }
+
+ UInterchangeManager& Manager = UInterchangeManager::GetInterchangeManager();
+ UInterchangeSourceData* SourceData = Manager.CreateSourceData(GlbPath);
+ if (!SourceData)
+ {
+ OnComplete(nullptr, TEXT("ThreeWsForgeImporter: could not create Interchange source data for the downloaded GLB"));
+ return;
+ }
+
+ FImportAssetParameters Params;
+ Params.bIsAutomated = true;
+ Params.bReplaceExisting = true;
+
+ UE::Interchange::FAssetImportResultRef Result =
+ Manager.ImportAssetAsync(Settings.DestinationPath, SourceData, Params);
+
+ Result->OnDone.AddLambda(
+ [Settings, OnComplete](UE::Interchange::FImportResult& ImportResult)
+ {
+ const TArray<UObject*> Imported = ImportResult.GetImportedObjects();
+ if (Imported.Num() == 0)
+ {
+ OnComplete(nullptr, TEXT("Interchange reported no imported objects for this GLB"));
+ return;
+ }
+
+ UObject* Primary = Imported[0];
+ ApplyForgeImportSettings(Cast<UStaticMesh>(Primary), Settings);
+
+ // Scale from FForgeImportSettings is applied by the caller at
+ // the actor level: the imported asset itself keeps its native
+ // scale, matching how the editor window and runtime sample
+ // place it (see README).
+ OnComplete(Primary, TEXT(""));
+ });
+}
diff --git a/packages/unreal-bridge/Source/ThreeWsBridge/Public/ThreeWsBridgeModule.h b/packages/unreal-bridge/Source/ThreeWsBridge/Public/ThreeWsBridgeModule.h
new file mode 100644
index 000000000..67a26e111
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridge/Public/ThreeWsBridgeModule.h
@@ -0,0 +1,11 @@
+#pragma once
+
+#include "CoreMinimal.h"
+#include "Modules/ModuleManager.h"
+
+class FThreeWsBridgeModule : public IModuleInterface
+{
+public:
+ virtual void StartupModule() override;
+ virtual void ShutdownModule() override;
+};
diff --git a/packages/unreal-bridge/Source/ThreeWsBridge/Public/ThreeWsClient.h b/packages/unreal-bridge/Source/ThreeWsBridge/Public/ThreeWsClient.h
new file mode 100644
index 000000000..d38ef0d6b
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridge/Public/ThreeWsClient.h
@@ -0,0 +1,86 @@
+// Real HTTP client for the public three.ws Forge pipeline (/api/forge).
+// Implements specs/ENGINE_BRIDGE.md: auth-free generation, catalog browse,
+// text/image submit, poll-to-completion, and GLB download. No glTF parsing
+// lives here: ThreeWsForgeImporter hands the downloaded bytes to Unreal's
+// own Interchange glTF pipeline.
+//
+// Mirrors the contract packages/unity-bridge and packages/godot-bridge
+// implement in their own languages.
+#pragma once
+
+#include "CoreMinimal.h"
+#include "Dom/JsonObject.h"
+#include "Interfaces/IHttpRequest.h"
+
+struct THREEWSBRIDGE_API FForgeJobResult
+{
+ bool bOk = false;
+ FString JobId;
+ FString Status;
+ FString GlbUrl;
+ FString Backend;
+ FString Error;
+};
+
+struct THREEWSBRIDGE_API FForgeDownloadResult
+{
+ bool bOk = false;
+ FString FilePath;
+ int64 Bytes = 0;
+ FString Error;
+};
+
+/**
+ * One client per logical session. Generation is anonymous by default: an
+ * x-forge-client handle is generated per instance. Set ProviderKey to use a
+ * BYOK geometry provider key instead of the free-tier lane (spec section 1).
+ */
+class THREEWSBRIDGE_API FThreeWsClient : public TSharedFromThis<FThreeWsClient>
+{
+public:
+ FThreeWsClient();
+
+ FString BaseUrl = TEXT("https://three.ws");
+ FString ProviderKey;
+ // 60s, not 30s: a submit can retry across several lanes server-side
+ // (free-first routing + failover) before it responds.
+ float RequestTimeoutSeconds = 60.0f;
+
+ /** GET /api/forge?catalog=1, the live tier/backend/cost matrix. */
+ void GetCatalog(TFunction<void(bool bOk, TSharedPtr<FJsonObject> Body)> OnComplete);
+
+ /** GET /api/forge?health=1, live per-lane up/down status. */
+ void GetHealth(TFunction<void(bool bOk, TSharedPtr<FJsonObject> Body)> OnComplete);
+
+ /** POST /api/forge-upload, then PUT the bytes. Calls back with the public URL. */
+ void UploadReferenceImage(const TArray<uint8>& Bytes, const FString& ContentType,
+ TFunction<void(bool bOk, FString PublicUrl, FString Error)> OnComplete);
+
+ /** POST /api/forge with a text prompt. */
+ void SubmitText(const FString& Prompt, const FString& Tier, const FString& Path,
+ const FString& Backend, const FString& AspectRatio,
+ TFunction<void(FForgeJobResult)> OnComplete);
+
+ /** POST /api/forge with one or more public https image URLs. */
+ void SubmitImage(const TArray<FString>& ImageUrls, const FString& Prompt, const FString& Tier,
+ const FString& Path, const FString& Backend,
+ TFunction<void(FForgeJobResult)> OnComplete);
+
+ /**
+ * Poll GET /api/forge?job=<id> until done or failed, or TimeoutSeconds
+ * elapses. Keeps polling the SAME job id throughout: poll-time failover
+ * is server-side. Uses the core ticker, not a UWorld timer, so this
+ * works from editor-only code with no active PIE session.
+ */
+ void WaitForGlb(const FString& JobId, float TimeoutSeconds, TFunction<void(FForgeJobResult)> OnComplete);
+
+ /** Stream a generated GLB to a local absolute path. */
+ void DownloadGlb(const FString& Url, const FString& DestinationPath,
+ TFunction<void(FForgeDownloadResult)> OnComplete);
+
+private:
+ FString ClientHandle;
+
+ TSharedRef<IHttpRequest, ESPMode::ThreadSafe> BuildRequest(const FString& Path, const FString& Verb) const;
+ void SubmitInternal(TSharedPtr<FJsonObject> Body, TFunction<void(FForgeJobResult)> OnComplete);
+};
diff --git a/packages/unreal-bridge/Source/ThreeWsBridge/Public/ThreeWsForgeImporter.h b/packages/unreal-bridge/Source/ThreeWsBridge/Public/ThreeWsForgeImporter.h
new file mode 100644
index 000000000..c3d22245f
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridge/Public/ThreeWsForgeImporter.h
@@ -0,0 +1,30 @@
+// Hands a downloaded Forge GLB to Unreal's own Interchange glTF pipeline.
+// No glTF parsing lives here, per specs/ENGINE_BRIDGE.md section 6/7.
+// Requires Interchange glTF import enabled: Project Settings > Editor >
+// Interchange Import > glTF, or UE 5.3+'s default-on setting.
+#pragma once
+
+#include "CoreMinimal.h"
+
+struct THREEWSBRIDGE_API FForgeImportSettings
+{
+ bool bGenerateColliders = false;
+ bool bImportMaterials = true;
+ float Scale = 1.0f;
+ /** Content-browser destination, e.g. /Game/ThreeWsForge/Generated. */
+ FString DestinationPath = TEXT("/Game/ThreeWsForge/Generated");
+};
+
+class THREEWSBRIDGE_API FThreeWsForgeImporter
+{
+public:
+ /**
+ * Imports a local .glb through UInterchangeManager::ImportAssetAsync and
+ * calls OnComplete with the primary imported UObject (a UStaticMesh or
+ * USkeletalMesh) once Interchange reports the import done, or nullptr on
+ * failure. Call from the game/editor thread; the callback also fires on
+ * the game/editor thread.
+ */
+ static void ImportGlb(const FString& GlbPath, const FForgeImportSettings& Settings,
+ TFunction<void(UObject* ImportedAsset, const FString& Error)> OnComplete);
+};
diff --git a/packages/unreal-bridge/Source/ThreeWsBridge/ThreeWsBridge.Build.cs b/packages/unreal-bridge/Source/ThreeWsBridge/ThreeWsBridge.Build.cs
new file mode 100644
index 000000000..1094a5708
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridge/ThreeWsBridge.Build.cs
@@ -0,0 +1,26 @@
+using UnrealBuildTool;
+
+public class ThreeWsBridge : ModuleRules
+{
+ public ThreeWsBridge(ReadOnlyTargetRules Target) : base(Target)
+ {
+ PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
+
+ PublicDependencyModuleNames.AddRange(new string[]
+ {
+ "Core",
+ "CoreUObject",
+ "Engine",
+ "HTTP",
+ "Json",
+ "JsonUtilities",
+ "InterchangeCore",
+ "InterchangeEngine",
+ });
+
+ PrivateDependencyModuleNames.AddRange(new string[]
+ {
+ "Projects",
+ });
+ }
+}
diff --git a/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Private/ThreeWsBridgeEditorModule.cpp b/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Private/ThreeWsBridgeEditorModule.cpp
new file mode 100644
index 000000000..bedb35de1
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Private/ThreeWsBridgeEditorModule.cpp
@@ -0,0 +1,51 @@
+#include "ThreeWsBridgeEditorModule.h"
+
+#include "Framework/Docking/TabManager.h"
+#include "ThreeWsForgeWindow.h"
+#include "ToolMenus.h"
+#include "Widgets/Docking/SDockTab.h"
+
+static const FName ThreeWsForgeTabName("ThreeWsForgeBridge");
+
+void FThreeWsBridgeEditorModule::StartupModule()
+{
+ FGlobalTabmanager::Get()->RegisterNomadTabSpawner(ThreeWsForgeTabName,
+ FOnSpawnTab::CreateLambda([](const FSpawnTabArgs&) -> TSharedRef<SDockTab>
+ {
+ return SNew(SDockTab)
+ .TabRole(ETabRole::NomadTab)
+ [
+ SNew(SThreeWsForgeWindow)
+ ];
+ }))
+ .SetDisplayName(FText::FromString(TEXT("three.ws Forge")))
+ .SetTooltipText(FText::FromString(TEXT("Generate a mesh from a prompt with the three.ws Forge pipeline")))
+ .SetMenuType(ETabSpawnerMenuType::Hidden);
+
+ UToolMenus::RegisterStartupCallback(FSimpleMulticastDelegate::FDelegate::CreateRaw(this, &FThreeWsBridgeEditorModule::RegisterMenus));
+}
+
+void FThreeWsBridgeEditorModule::ShutdownModule()
+{
+ FGlobalTabmanager::Get()->UnregisterNomadTabSpawner(ThreeWsForgeTabName);
+}
+
+void FThreeWsBridgeEditorModule::RegisterMenus()
+{
+ FToolMenuOwnerScoped OwnerScoped(this);
+ UToolMenu* Menu = UToolMenus::Get()->ExtendMenu("LevelEditor.MainMenu.Window");
+ FToolMenuSection& Section = Menu->FindOrAddSection("ThreeWs");
+ Section.AddMenuEntry(
+ "ThreeWsForgeBridge",
+ FText::FromString(TEXT("three.ws Forge Bridge")),
+ FText::FromString(TEXT("Generate a mesh from a prompt with the three.ws Forge pipeline")),
+ FSlateIcon(),
+ FUIAction(FExecuteAction::CreateRaw(this, &FThreeWsBridgeEditorModule::OpenForgeWindow)));
+}
+
+void FThreeWsBridgeEditorModule::OpenForgeWindow()
+{
+ FGlobalTabmanager::Get()->TryInvokeTab(ThreeWsForgeTabName);
+}
+
+IMPLEMENT_MODULE(FThreeWsBridgeEditorModule, ThreeWsBridgeEditor)
diff --git a/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Private/ThreeWsForgeWindow.cpp b/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Private/ThreeWsForgeWindow.cpp
new file mode 100644
index 000000000..48d5b6ae4
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Private/ThreeWsForgeWindow.cpp
@@ -0,0 +1,219 @@
+#include "ThreeWsForgeWindow.h"
+
+#include "Editor.h"
+#include "EditorViewportClient.h"
+#include "Engine/StaticMeshActor.h"
+#include "Components/StaticMeshComponent.h"
+#include "HAL/PlatformFileManager.h"
+#include "Misc/Paths.h"
+#include "ThreeWsForgeImporter.h"
+#include "Widgets/Input/SButton.h"
+#include "Widgets/Input/SComboBox.h"
+#include "Widgets/Input/SEditableTextBox.h"
+#include "Widgets/Layout/SBox.h"
+#include "Widgets/Text/STextBlock.h"
+
+void SThreeWsForgeWindow::Construct(const FArguments& InArgs)
+{
+ Client = MakeShared<FThreeWsClient>();
+ Tiers = { TEXT("draft"), TEXT("standard"), TEXT("high") };
+ SelectedTierIndex = 0;
+
+ TArray<TSharedPtr<FString>> TierOptions;
+ for (const FString& Tier : Tiers)
+ {
+ TierOptions.Add(MakeShared<FString>(Tier));
+ }
+
+ ChildSlot
+ [
+ SNew(SBox)
+ .Padding(16.0f)
+ [
+ SNew(SVerticalBox)
+ + SVerticalBox::Slot().AutoHeight().Padding(0, 0, 0, 8)
+ [
+ SNew(STextBlock).Text(FText::FromString(TEXT("three.ws Forge")))
+ ]
+ + SVerticalBox::Slot().AutoHeight().Padding(0, 0, 0, 8)
+ [
+ SAssignNew(PromptBox, SEditableTextBox)
+ .HintText(FText::FromString(TEXT("a weathered lighthouse")))
+ ]
+ + SVerticalBox::Slot().AutoHeight().Padding(0, 0, 0, 8)
+ [
+ SNew(SComboBox<TSharedPtr<FString>>)
+ .OptionsSource(&TierOptions)
+ .OnGenerateWidget_Lambda([](TSharedPtr<FString> Item)
+ {
+ return SNew(STextBlock).Text(FText::FromString(*Item));
+ })
+ .OnSelectionChanged_Lambda([this](TSharedPtr<FString> Item, ESelectInfo::Type)
+ {
+ if (Item.IsValid())
+ {
+ SelectedTierIndex = Tiers.IndexOfByKey(*Item);
+ }
+ })
+ .InitiallySelectedItem(TierOptions[0])
+ [
+ SNew(STextBlock).Text(FText::FromString(Tiers[0]))
+ ]
+ ]
+ + SVerticalBox::Slot().AutoHeight().Padding(0, 0, 0, 8)
+ [
+ SNew(SButton)
+ .Text(FText::FromString(TEXT("Generate and import")))
+ .IsEnabled_Lambda([this]() { return !bBusy; })
+ .OnClicked(this, &SThreeWsForgeWindow::OnGenerateClicked)
+ ]
+ + SVerticalBox::Slot().AutoHeight()
+ [
+ SAssignNew(StatusText, STextBlock).Text(FText::FromString(TEXT("Idle.")))
+ ]
+ ]
+ ];
+}
+
+void SThreeWsForgeWindow::SetStatus(const FString& Message)
+{
+ if (StatusText.IsValid())
+ {
+ StatusText->SetText(FText::FromString(Message));
+ }
+}
+
+FReply SThreeWsForgeWindow::OnGenerateClicked()
+{
+ if (bBusy || !PromptBox.IsValid())
+ {
+ return FReply::Handled();
+ }
+ const FString Prompt = PromptBox->GetText().ToString().TrimStartAndEnd();
+ if (Prompt.IsEmpty())
+ {
+ SetStatus(TEXT("Type a prompt first."));
+ return FReply::Handled();
+ }
+ bBusy = true;
+ RunGeneration(Prompt, Tiers[SelectedTierIndex]);
+ return FReply::Handled();
+}
+
+void SThreeWsForgeWindow::RunGeneration(FString Prompt, FString Tier)
+{
+ SetStatus(FString::Printf(TEXT("Submitting \"%s\"..."), *Prompt));
+
+ TWeakPtr<SThreeWsForgeWindow> WeakSelf = SharedThis(this);
+ Client->SubmitText(Prompt, Tier, TEXT("image"), TEXT(""), TEXT("1:1"),
+ [this, WeakSelf, Prompt](FForgeJobResult Submitted)
+ {
+ TSharedPtr<SThreeWsForgeWindow> Self = WeakSelf.Pin();
+ if (!Self.IsValid())
+ {
+ return;
+ }
+ if (!Submitted.bOk)
+ {
+ SetStatus(FString::Printf(TEXT("Submit failed: %s"), *Submitted.Error));
+ bBusy = false;
+ return;
+ }
+
+ auto HandleGlbUrl = [this, WeakSelf](FString GlbUrl)
+ {
+ TSharedPtr<SThreeWsForgeWindow> InnerSelf = WeakSelf.Pin();
+ if (!InnerSelf.IsValid())
+ {
+ return;
+ }
+ SetStatus(TEXT("Downloading..."));
+ const FString Destination = FPaths::Combine(FPaths::ProjectIntermediateDir(), TEXT("ThreeWsForge"), TEXT("forge_tmp.glb"));
+ Client->DownloadGlb(GlbUrl, Destination,
+ [this, WeakSelf](FForgeDownloadResult Downloaded)
+ {
+ TSharedPtr<SThreeWsForgeWindow> DlSelf = WeakSelf.Pin();
+ if (!DlSelf.IsValid())
+ {
+ return;
+ }
+ if (!Downloaded.bOk)
+ {
+ SetStatus(FString::Printf(TEXT("Download failed: %s"), *Downloaded.Error));
+ bBusy = false;
+ return;
+ }
+ OnGlbReady(Downloaded.FilePath);
+ });
+ };
+
+ if (!Submitted.GlbUrl.IsEmpty())
+ {
+ HandleGlbUrl(Submitted.GlbUrl);
+ return;
+ }
+
+ SetStatus(FString::Printf(TEXT("Generating on %s..."), *Submitted.Backend));
+ Client->WaitForGlb(Submitted.JobId, 600.0f,
+ [this, WeakSelf, HandleGlbUrl](FForgeJobResult Finished)
+ {
+ TSharedPtr<SThreeWsForgeWindow> WaitSelf = WeakSelf.Pin();
+ if (!WaitSelf.IsValid())
+ {
+ return;
+ }
+ if (!Finished.bOk)
+ {
+ SetStatus(FString::Printf(TEXT("Generation failed: %s"), *Finished.Error));
+ bBusy = false;
+ return;
+ }
+ HandleGlbUrl(Finished.GlbUrl);
+ });
+ });
+}
+
+void SThreeWsForgeWindow::OnGlbReady(const FString& GlbPath)
+{
+ SetStatus(TEXT("Importing..."));
+
+ FForgeImportSettings Settings;
+ Settings.bGenerateColliders = true;
+
+ TWeakPtr<SThreeWsForgeWindow> WeakSelf = SharedThis(this);
+ FThreeWsForgeImporter::ImportGlb(GlbPath, Settings,
+ [this, WeakSelf](UObject* ImportedAsset, const FString& Error)
+ {
+ TSharedPtr<SThreeWsForgeWindow> Self = WeakSelf.Pin();
+ if (!Self.IsValid())
+ {
+ return;
+ }
+ bBusy = false;
+ if (!ImportedAsset)
+ {
+ SetStatus(FString::Printf(TEXT("Import failed: %s"), *Error));
+ return;
+ }
+
+ if (UStaticMesh* Mesh = Cast<UStaticMesh>(ImportedAsset))
+ {
+ if (GEditor)
+ {
+ if (UWorld* World = GEditor->GetEditorWorldContext().World())
+ {
+ AStaticMeshActor* Actor = World->SpawnActor<AStaticMeshActor>();
+ if (Actor && Actor->GetStaticMeshComponent())
+ {
+ Actor->GetStaticMeshComponent()->SetStaticMesh(Mesh);
+ Actor->SetActorLabel(Mesh->GetName());
+ GEditor->SelectNone(false, true);
+ GEditor->SelectActor(Actor, true, true);
+ }
+ }
+ }
+ }
+
+ SetStatus(FString::Printf(TEXT("Imported %s."), *ImportedAsset->GetName()));
+ });
+}
diff --git a/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Private/ThreeWsForgeWindow.h b/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Private/ThreeWsForgeWindow.h
new file mode 100644
index 000000000..c22be599a
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Private/ThreeWsForgeWindow.h
@@ -0,0 +1,33 @@
+// Slate dock tab: a prompt field, a tier dropdown, and a Generate button
+// that runs a real text-to-3D generation and drops the imported mesh into
+// the active editor level.
+#pragma once
+
+#include "CoreMinimal.h"
+#include "ThreeWsClient.h"
+#include "Widgets/SCompoundWidget.h"
+
+class SEditableTextBox;
+class STextBlock;
+
+class SThreeWsForgeWindow : public SCompoundWidget
+{
+public:
+ SLATE_BEGIN_ARGS(SThreeWsForgeWindow) {}
+ SLATE_END_ARGS()
+
+ void Construct(const FArguments& InArgs);
+
+private:
+ TSharedPtr<FThreeWsClient> Client;
+ TSharedPtr<SEditableTextBox> PromptBox;
+ TSharedPtr<STextBlock> StatusText;
+ TArray<FString> Tiers;
+ int32 SelectedTierIndex = 0;
+ bool bBusy = false;
+
+ FReply OnGenerateClicked();
+ void SetStatus(const FString& Message);
+ void RunGeneration(FString Prompt, FString Tier);
+ void OnGlbReady(const FString& GlbPath);
+};
diff --git a/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Public/ThreeWsBridgeEditorModule.h b/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Public/ThreeWsBridgeEditorModule.h
new file mode 100644
index 000000000..79ee16118
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridgeEditor/Public/ThreeWsBridgeEditorModule.h
@@ -0,0 +1,15 @@
+#pragma once
+
+#include "CoreMinimal.h"
+#include "Modules/ModuleManager.h"
+
+class FThreeWsBridgeEditorModule : public IModuleInterface
+{
+public:
+ virtual void StartupModule() override;
+ virtual void ShutdownModule() override;
+
+private:
+ void RegisterMenus();
+ void OpenForgeWindow();
+};
diff --git a/packages/unreal-bridge/Source/ThreeWsBridgeEditor/ThreeWsBridgeEditor.Build.cs b/packages/unreal-bridge/Source/ThreeWsBridgeEditor/ThreeWsBridgeEditor.Build.cs
new file mode 100644
index 000000000..f104d8602
--- /dev/null
+++ b/packages/unreal-bridge/Source/ThreeWsBridgeEditor/ThreeWsBridgeEditor.Build.cs
@@ -0,0 +1,27 @@
+using UnrealBuildTool;
+
+public class ThreeWsBridgeEditor : ModuleRules
+{
+ public ThreeWsBridgeEditor(ReadOnlyTargetRules Target) : base(Target)
+ {
+ PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
+
+ PublicDependencyModuleNames.AddRange(new string[]
+ {
+ "Core",
+ "CoreUObject",
+ "Engine",
+ "ThreeWsBridge",
+ });
+
+ PrivateDependencyModuleNames.AddRange(new string[]
+ {
+ "Slate",
+ "SlateCore",
+ "UnrealEd",
+ "ToolMenus",
+ "InputCore",
+ "EditorStyle",
+ });
+ }
+}
diff --git a/packages/unreal-bridge/ThreeWsBridge.uplugin b/packages/unreal-bridge/ThreeWsBridge.uplugin
new file mode 100644
index 000000000..49671bd40
--- /dev/null
+++ b/packages/unreal-bridge/ThreeWsBridge.uplugin
@@ -0,0 +1,30 @@
+{
+ "FileVersion": 3,
+ "Version": 1,
+ "VersionName": "0.1.0",
+ "FriendlyName": "three.ws Forge Bridge",
+ "Description": "Generate textured 3D models from a text prompt or reference photos with the free three.ws Forge pipeline, straight into the Unreal Editor. Imports the result through Unreal's own Interchange glTF pipeline. No mock server: every call goes to the live public API documented in specs/ENGINE_BRIDGE.md.",
+ "Category": "Importers",
+ "CreatedBy": "three.ws",
+ "CreatedByURL": "https://three.ws",
+ "DocsURL": "",
+ "MarketplaceURL": "",
+ "SupportURL": "https://three.ws",
+ "EngineVersion": "5.3.0",
+ "CanContainContent": false,
+ "IsBetaVersion": true,
+ "IsExperimentalVersion": false,
+ "Installed": false,
+ "Modules": [
+ {
+ "Name": "ThreeWsBridge",
+ "Type": "Runtime",
+ "LoadingPhase": "Default"
+ },
+ {
+ "Name": "ThreeWsBridgeEditor",
+ "Type": "Editor",
+ "LoadingPhase": "PostEngineInit"
+ }
+ ]
+}
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index 0c551bd49..5c6ce9a06 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-10-12T00:08:55.039Z",
+ "generated_at": "2026-10-12T01:09:39.541Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 4036,
+ "total": 4038,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -19,6 +19,16 @@
"launch"
]
},
+ {
+ "date": "2026-10-12",
+ "type": "launch",
+ "title": "Docs · Engine bridges",
+ "summary": "One Forge API contract, three real editor integrations: a Unity UPM package, a Godot addon, and an Unreal plugin, each generating a mesh from a prompt and importing it with the engine's own native glTF pipeline.",
+ "link": "/docs/engine-bridges",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-10-12",
"type": "launch",
@@ -39,6 +49,17 @@
"feature"
]
},
+ {
+ "date": "2026-10-12",
+ "type": "update",
+ "title": "Three new engine bridges: Unity, Godot, and Unreal, one prompt to a mesh in your editor",
+ "summary": "A shared contract (specs/ENGINE_BRIDGE.md) and three real, independent implementations: a Unity UPM package that imports with glTFast, a Godot addon that imports with Godot's own native GLTFDocument, and an Unreal plugin that imports through Unreal's Interchange glTF pipeline. Each one calls only the public Forge API (POST /api/forge to submit, GET /api/forge?job=<id> to poll, a plain HTTPS GET to download), the same free-first routing and anonymous x-forge-client auth every other Forge caller gets, with the same four import settings (generate_colliders, import_materials, scale, destination) mapped onto each engine's own equivalent. A dropdown and a Generate button in each editor: type a prompt, get a mesh dropped into your scene.",
+ "link": "/docs/engine-bridges",
+ "tags": [
+ "feature",
+ "sdk"
+ ]
+ },
{
"date": "2026-10-11",
"type": "launch",
@@ -1521,27 +1542,6 @@
"tags": [
"docs"
]
- },
- {
- "date": "2026-10-09",
- "type": "update",
- "title": "A full setup guide for Grok Bot",
- "summary": "There is now one page that covers connecting Grok Bot to three.ws end to end: the exact connector settings, which sign-in to pick, how scheduled runs collect long renders and retry without generating twice, the rate limits, the rule that an agent can never spend, and a fix for every connection problem.",
- "link": "/docs/grok-bot",
- "tags": [
- "docs"
- ]
- },
- {
- "date": "2026-10-09",
- "type": "update",
- "title": "A new default engine for photo to 3D, with regional safeguards",
- "summary": "Photo to 3D in the Forge now starts with TRELLIS.2, an open-source model that makes textured assets with full material detail and keeps transparency for glass and leaves. You can pick a detail level of 512, 1024 or 1536 when you generate. We also made sure that requests from the European Union, the United Kingdom and South Korea never use models whose license does not cover those regions, and that a request with no location signal takes the safe path too. The engine switches on as soon as its GPU worker is deployed, and until then the existing engines keep serving every request.",
- "link": "/forge",
- "tags": [
- "feature",
- "improvement"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index 43ec038b7..62b0b0820 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-12T00:08:55.012Z",
+ "generated_at": "2026-10-12T01:09:39.498Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -16,6 +16,16 @@
"launch"
]
},
+ {
+ "date": "2026-10-12",
+ "type": "launch",
+ "title": "Docs · Engine bridges",
+ "summary": "One Forge API contract, three real editor integrations: a Unity UPM package, a Godot addon, and an Unreal plugin, each generating a mesh from a prompt and importing it with the engine's own native glTF pipeline.",
+ "link": "/docs/engine-bridges",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-10-12",
"type": "launch",
@@ -36,6 +46,17 @@
"feature"
]
},
+ {
+ "date": "2026-10-12",
+ "type": "update",
+ "title": "Three new engine bridges: Unity, Godot, and Unreal, one prompt to a mesh in your editor",
+ "summary": "A shared contract (specs/ENGINE_BRIDGE.md) and three real, independent implementations: a Unity UPM package that imports with glTFast, a Godot addon that imports with Godot's own native GLTFDocument, and an Unreal plugin that imports through Unreal's Interchange glTF pipeline. Each one calls only the public Forge API (POST /api/forge to submit, GET /api/forge?job=<id> to poll, a plain HTTPS GET to download), the same free-first routing and anonymous x-forge-client auth every other Forge caller gets, with the same four import settings (generate_colliders, import_materials, scale, destination) mapped onto each engine's own equivalent. A dropdown and a Generate button in each editor: type a prompt, get a mesh dropped into your scene.",
+ "link": "/docs/engine-bridges",
+ "tags": [
+ "feature",
+ "sdk"
+ ]
+ },
{
"date": "2026-10-11",
"type": "launch",
diff --git a/public/changelog.xml b/public/changelog.xml
index 717e19fe6..c301e4e8c 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -14,6 +14,14 @@
<category>launch</category>
<description>Decision record for staked Event Markets on Solana: the parimutuel model, fee and buyback split, limits, void and refund rules, and the jurisdiction and age questions that stay with the owner.</description>
</item>
+ <item>
+ <title>Docs · Engine bridges</title>
+ <link>https://three.ws/docs/engine-bridges</link>
+ <guid isPermaLink="false">2026-10-12:Docs · Engine bridges</guid>
+ <pubDate>Mon, 12 Oct 2026 12:00:00 GMT</pubDate>
+ <category>launch</category>
+ <description>One Forge API contract, three real editor integrations: a Unity UPM package, a Godot addon, and an Unreal plugin, each generating a mesh from a prompt and importing it with the engine's own native glTF pipeline.</description>
+ </item>
<item>
<title>Docs · Engine QA</title>
<link>https://three.ws/docs/engine-qa</link>
@@ -30,6 +38,14 @@
<category>feature</category>
<description>A new free grade answers the question a game engine's import step asks that neither glTF validation nor simulation readiness does: draw calls, material count, texel density against the mesh's real-world size, a per-level triangle budget for a LOD chain, and whether the mesh is cheap and closed enough to use as its own physics collider. GET/POST /api/3d/engine-qa grades any public GLB (format=stl exports a watertight mesh for printing); the same browser-only checks run with zero network cost in Rig Doctor, and the full grade with a one-click upgrade in the GLB viewer, through a shared &lt;engine-qa&gt; panel component. The underlying LOD builder (packages/glb-tools's buildLodChain, real meshoptimizer decimation tagged with MSFT_lod) is now also available on generation: send { &quot;lods&quot;: true } to POST /api/forge and the finished creation gets a combined LOD-chain variant alongside its delivered mesh, the same opt-in, fire-and-forget pattern as the existing web-delivery variant.</description>
</item>
+ <item>
+ <title>Three new engine bridges: Unity, Godot, and Unreal, one prompt to a mesh in your editor</title>
+ <link>https://three.ws/docs/engine-bridges</link>
+ <guid isPermaLink="false">2026-10-12:Three new engine bridges: Unity, Godot, and Unreal, one prompt to a mesh in your editor</guid>
+ <pubDate>Mon, 12 Oct 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>A shared contract (specs/ENGINE_BRIDGE.md) and three real, independent implementations: a Unity UPM package that imports with glTFast, a Godot addon that imports with Godot's own native GLTFDocument, and an Unreal plugin that imports through Unreal's Interchange glTF pipeline. Each one calls only the public Forge API (POST /api/forge to submit, GET /api/forge?job=&lt;id&gt; to poll, a plain HTTPS GET to download), the same free-first routing and anonymous x-forge-client auth every other Forge caller gets, with the same four import settings (generate_colliders, import_materials, scale, destination) mapped onto each engine's own equivalent. A dropdown and a Generate button in each editor: type a prompt, get a mesh dropped into your scene.</description>
+ </item>
<item>
<title>Classic Home</title>
<link>https://three.ws/classic</link>
diff --git a/public/features.json b/public/features.json
index 0bbe58e16..aa4ff4030 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-12T00:08:54.995Z",
+ "generated_at": "2026-10-12T01:09:39.462Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
@@ -9067,6 +9067,18 @@
"priority": 0.6,
"job": null
},
+ {
+ "path": "/docs/engine-bridges",
+ "title": "Docs · Engine bridges",
+ "description": "One Forge API contract, three real editor integrations: a Unity UPM package, a Godot addon, and an Unreal plugin, each generating a mesh from a prompt and importing it with the engine's own native glTF pipeline.",
+ "added": "2026-10-12",
+ "auth": null,
+ "indexable": true,
+ "tags": [],
+ "showcase": false,
+ "priority": 0.6,
+ "job": null
+ },
{
"path": "/docs/remix",
"title": "Docs · The remix economy",
diff --git a/public/llms-full.txt b/public/llms-full.txt
index 805217b75..ce154a72c 100644
--- a/public/llms-full.txt
+++ b/public/llms-full.txt
@@ -4561,6 +4561,12 @@ URL: https://three.ws/docs/engine-qa
A free real-time-engine fitness grade for any 3D model: draw calls, material count, texel density, a per-level LOD triangle budget, and whether the mesh is cheap and closed enough to use as its own physics collider.
+### Docs · Engine bridges
+
+URL: https://three.ws/docs/engine-bridges
+
+One Forge API contract, three real editor integrations: a Unity UPM package, a Godot addon, and an Unreal plugin, each generating a mesh from a prompt and importing it with the engine's own native glTF pipeline.
+
### Docs · The remix economy
URL: https://three.ws/docs/remix
diff --git a/public/llms.txt b/public/llms.txt
index 8030501d6..4038f7c21 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -100,6 +100,6 @@ Machine-readable entry points. Fetch these instead of scraping HTML.
## Optional
-- [llms-full.txt](https://three.ws/llms-full.txt): Every public page (1001), grouped by section, with full descriptions.
+- [llms-full.txt](https://three.ws/llms-full.txt): Every public page (1002), grouped by section, with full descriptions.
- [Sitemap](https://three.ws/sitemap): The same index for people, with search.
- [sitemap.xml](https://three.ws/sitemap.xml): XML sitemap for crawlers, including every agent and avatar page.
diff --git a/public/sitemap/index.html b/public/sitemap/index.html
index 469966d4a..7f2f909f6 100644
--- a/public/sitemap/index.html
+++ b/public/sitemap/index.html
@@ -96,7 +96,7 @@
<main class="sm-wrap">
<div class="sm-hero">
<h1>Sitemap</h1>
- <p><span>1060</span> <span data-i18n="sitemap_index.pages_grouped">pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</span></p>
+ <p><span>1061</span> <span data-i18n="sitemap_index.pages_grouped">pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</span></p>
<div class="sm-formats">
<a href="/everything"><code>/everything</code> · browse by goal, not by section</a>
<a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a>
@@ -109,7 +109,7 @@
</div>
<div class="sm-filter">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>
- <input id="sm-filter-input" type="search" placeholder="Filter 1060 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
+ <input id="sm-filter-input" type="search" placeholder="Filter 1061 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
<kbd id="sm-filter-kbd" aria-hidden="true">/</kbd>
</div>
<p class="sm-filter-count" role="status" aria-live="polite"><span id="sm-filter-count"></span><span id="sm-filter-hint" aria-hidden="true"></span></p>
@@ -133,6 +133,14 @@
<span class="sm-desc" data-i18n="sitemap_index.d_docs_engine_qa">A free real-time-engine fitness grade for any 3D model: draw calls, material count, texel density, a per-level LOD triangle budget, and whether the mesh is cheap and closed enough to use as its own physics collider.</span>
</a>
</li>
+ <li>
+ <a href="/docs/engine-bridges">
+ <span class="sm-new-date" translate="no">Oct 12, 2026</span>
+ <span class="sm-title"><span data-i18n="sitemap_index.t_docs_engine_bridges">Docs · Engine bridges</span></span>
+ <span class="sm-path" translate="no">/docs/engine-bridges</span>
+ <span class="sm-desc" data-i18n="sitemap_index.d_docs_engine_bridges">One Forge API contract, three real editor integrations: a Unity UPM package, a Godot addon, and an Unreal plugin, each generating a mesh from a prompt and importing it with the engine's own native glTF pipeline.</span>
+ </a>
+ </li>
<li>
<a href="/classic">
<span class="sm-new-date" translate="no">Oct 11, 2026</span>
@@ -181,14 +189,6 @@
<span class="sm-desc" data-i18n="sitemap_index.d_apps_seeker">Live on the Solana dApp Store: Seed Vault sign-in, Seeker Genesis Token verification, agents and the marketplace.</span>
</a>
</li>
- <li>
- <a href="/apps/ios">
- <span class="sm-new-date" translate="no">Oct 11, 2026</span>
- <span class="sm-title"><span data-i18n="sitemap_index.t_apps_ios">three.ws for iPhone and iPad</span></span>
- <span class="sm-path" translate="no">/apps/ios</span>
- <span class="sm-desc" data-i18n="sitemap_index.d_apps_ios">The App Store build is finished and pending Apple enrollment; what runs on iPhone today and what the native app adds.</span>
- </a>
- </li>
</ul>
</section>
<nav class="sm-toc" aria-label="Sections">
@@ -2955,7 +2955,7 @@
<section class="sm-section" id="learn">
<header>
- <h2><span data-i18n="sitemap_index.section_learn">Learn</span><span class="sm-count" data-count>497</span></h2>
+ <h2><span data-i18n="sitemap_index.section_learn">Learn</span><span class="sm-count" data-count>498</span></h2>
<p class="sm-section-desc">Docs, tutorials, and reference.</p>
</header>
<ul class="sm-list">
@@ -5465,6 +5465,13 @@
<span class="sm-desc" data-i18n="sitemap_index.d_docs_engine_qa">A free real-time-engine fitness grade for any 3D model: draw calls, material count, texel density, a per-level LOD triangle budget, and whether the mesh is cheap and closed enough to use as its own physics collider.</span>
</a>
</li>
+ <li>
+ <a href="/docs/engine-bridges">
+ <span class="sm-title"><span data-i18n="sitemap_index.t_docs_engine_bridges">Docs · Engine bridges</span></span>
+ <span class="sm-path" translate="no">/docs/engine-bridges</span>
+ <span class="sm-desc" data-i18n="sitemap_index.d_docs_engine_bridges">One Forge API contract, three real editor integrations: a Unity UPM package, a Godot addon, and an Unreal plugin, each generating a mesh from a prompt and importing it with the engine's own native glTF pipeline.</span>
+ </a>
+ </li>
<li>
<a href="/docs/remix">
<span class="sm-title"><span data-i18n="sitemap_index.t_docs_remix">Docs · The remix economy</span></span>
diff --git a/specs/ENGINE_BRIDGE.md b/specs/ENGINE_BRIDGE.md
new file mode 100644
index 000000000..b61ec38e1
--- /dev/null
+++ b/specs/ENGINE_BRIDGE.md
@@ -0,0 +1,119 @@
+# Engine Bridge Spec v1
+
+The contract every game-engine integration speaks against the public three.ws Forge API. [`packages/unity-bridge`](../packages/unity-bridge), [`packages/godot-bridge`](../packages/godot-bridge) and [`packages/unreal-bridge`](../packages/unreal-bridge) are three independent implementations of this one contract, each written in its engine's native language. None of them talk to a provider (NVIDIA NIM, Meshy, a self-hosted worker) directly, and none of them parse glTF themselves: they call the same orchestrator the website, the MCP tools and the Blender/ComfyUI/Modly plugins call ([`api/forge.js`](../api/forge.js), documented end to end in [docs/forge-pipeline.md](../docs/forge-pipeline.md)), and they hand the downloaded GLB to the engine's own glTF importer.
+
+Any future engine bridge (a Blender-class DCC, a different game engine, a CAD tool) should implement this same contract rather than invent a new one.
+
+## 1. Auth
+
+Generation is **auth-free** and IP rate-limited, scoped to an anonymous per-process client handle sent as a header on every request:
+
+```
+x-forge-client: <32 lowercase hex chars, generated once per process and reused>
+x-engine-bridge: <engine>/<bridge-version> (e.g. unity/0.1.0, godot/0.1.0, unreal/0.1.0)
+```
+
+`x-forge-client` is not a secret and carries no authority; it only lets the rate limiter and lane-health telemetry group a run of calls from one editor session. It is never persisted to disk and never shown in the UI beyond a debug log line.
+
+Two calls are authenticated, and a bridge only needs them if the user chooses to publish the result into a three.ws account rather than just import it into the local project:
+
+| Call | Auth |
+|---|---|
+| `POST /api/avatars/upload` or `POST /api/avatars` (save the generation as an account avatar) | Bearer API key from `https://three.ws/dashboard/api`, scope `avatars:write`, read from an engine-native secret store (Unity `EditorUserSettings`/env var, Godot `EditorSettings`, Unreal `GConfig`) and never from on-chain or asset-embedded data |
+| The BYOK geometry lane (`path: "geometry"`, Meshy/Tripo/Rodin) | The user's own provider key, sent as `x-forge-provider-key`, never in the body or a URL |
+
+Everything else below needs no key.
+
+## 2. Catalog browse
+
+```
+GET /api/forge?catalog=1
+```
+
+Returns the live tier/backend/cost matrix: which `(path, tier, backend)` triples are configured on this deployment, prices in USDC atomics, and ETA estimates. A bridge calls this once per editor session (cached in memory, not on disk, since lane health changes) to populate its tier and backend dropdowns, and never hardcodes a second copy of the matrix. `GET /api/forge?health=1` returns live per-lane up/down status for the same purpose.
+
+Known values (mirrors `TIERS`/`PATHS`/`BACKENDS` in [`api/_lib/forge-tiers.js`](../api/_lib/forge-tiers.js); treat the catalog response as authoritative over this list, which can grow):
+
+- `path`: `image` (default, text or reference photos), `geometry` (BYOK native mesh), `sketch` (drawing + prompt)
+- `tier`: `draft`, `standard`, `high`
+- `backend`: optional override; omitted lets free-first routing choose
+
+## 3. Generate (submit)
+
+Text prompt:
+
+```http
+POST /api/forge
+Content-Type: application/json
+
+{ "prompt": "a weathered lighthouse", "tier": "standard", "path": "image", "aspect_ratio": "1:1" }
+```
+
+Reference image(s), after uploading them (step 3a) or when the engine already has a public https URL (an asset already hosted on a CDN):
+
+```http
+POST /api/forge
+Content-Type: application/json
+
+{ "image_urls": ["https://..."], "prompt": "", "tier": "standard", "path": "image" }
+```
+
+Response is one of:
+
+- `{ "job_id": "...", "status": "queued", "backend": "trellis2" }` for an async lane, poll next (step 4).
+- `{ "status": "done", "glb_url": "https://...", "backend": "..." }` directly, for a synchronous lane (NVIDIA NIM, HF Spaces, a synchronous BYOK vendor). A bridge that only implements polling still works: treat this as a one-shot "poll" that is already resolved, never a special case.
+- `{ "error": "needs_key", "message": "..." }` when `path: "geometry"` was requested with no provider key. Surface the message and the free `image` path as the fallback, never a silent retry with a fabricated key.
+
+### 3a. Upload a local reference image
+
+A bridge that lets the user pick a file from their local project (not already a public URL) presigns and uploads it first:
+
+```http
+POST /api/forge-upload
+Content-Type: application/json
+
+{ "content_type": "image/png", "size_bytes": 182334, "checksum_sha256": "<hex>" }
+```
+
+returns `{ "upload_url": "...", "public_url": "...", "headers": {...} }`; `PUT` the raw bytes to `upload_url` with those headers, then use `public_url` as one of `image_urls` above. A deployment with no object storage configured returns a message instead of `upload_url`; the bridge's UI falls back to asking for a public https URL.
+
+## 4. Poll
+
+```
+GET /api/forge?job=<job_id>
+```
+
+Poll on a fixed interval (2.5s is what every existing client uses; do not poll faster) until `status` is `done` or `failed`, or a bridge-side timeout elapses (default 600s, configurable). `done` carries `glb_url`; `failed` carries `error`. A bridge must keep polling the same `job_id` across the whole wait: **poll-time failover is server-side** (`api/_lib/forge-failover.js`) and transparently re-dispatches a job whose lane died mid-run without changing the id, so a client that gives up and resubmits duplicates work and cost for no reason.
+
+## 5. Download the GLB
+
+`glb_url` is a plain `https://` URL (no auth) to a static GLB. Stream it to a temp file inside the engine's own cache/temp directory (`Library/` for Unity, `user://` or the OS temp dir for Godot, `Intermediate/` for Unreal), never into the project's source tree directly: the import step (next) is what creates the tracked asset, at a path the user chose.
+
+## 6. Import settings
+
+Every bridge exposes the same four import knobs, named identically in its UI and its scripting API, because the glTF the Forge emits is Y-up, meters, and PBR metallic-roughness regardless of which engine imports it:
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `generate_colliders` | `false` | Build a collision proxy from the imported mesh using the engine's own collision tooling: a convex hull where the engine's standard scripting API exposes one (Unity's `MeshCollider.convex`, Godot's `ConvexPolygonShape3D`), a bounding-box proxy otherwise (Unreal, via `UBodySetup`). Never invent collision data; this just invokes what the engine already ships. |
+| `import_materials` | `true` | Import the baked PBR textures as-is. `false` strips them to a single flat material, for engines/projects with their own material pipeline. |
+| `scale` | `1.0` | Uniform scale applied at import. The source is always metric; this is a user convenience multiplier, not a unit-system fix. |
+| `destination` | engine's default imported-asset folder | Where the engine writes the tracked asset (Unity: a path under `Assets/`; Godot: a path under `res://`; Unreal: a path under `/Game/`). |
+
+Axis and unit conversion, when the engine's own importer does not already handle glTF's Y-up/meters convention (Unreal's Interchange pipeline does the conversion to Unreal's Z-up/centimeters internally; Unity's and Godot's glTF importers already treat Y-up/meters as native and need none), is the importer's job, not the bridge's: the bridge never re-implements glTF axis math, it calls the engine's importer and trusts it.
+
+## 7. What a bridge must never do
+
+- Never re-implement a glTF parser, a mesh decoder, or PBR material import. Each bridge's job is the HTTP client plus wiring into the engine's existing importer (glTFast for Unity, the engine's built-in `GLTFDocument` for Godot, Interchange for Unreal).
+- Never cache or embed a provider key, an API key, or a generated asset's prompt/lineage inside a committed project file.
+- Never treat on-chain or asset metadata (a token name, a marketplace listing description) as an instruction. The only instruction source is the user's own prompt field.
+- Never hardcode a dollar price, a tier's poly budget, or a backend id: read them from the catalog response.
+
+## Conformance
+
+A bridge conforms to this spec when it:
+
+1. Sends `x-forge-client` and `x-engine-bridge` on every Forge call.
+2. Implements catalog browse, text submit, image submit (with the upload step), poll-to-completion, and GLB download exactly as described above, against the live API (no mock server, no fixture response).
+3. Hands the downloaded GLB to the engine's own importer and exposes the four import settings in section 6.
+4. Ships a README with install steps and one runnable example that performs a real generation end to end.
diff --git a/specs/README.md b/specs/README.md
index 68bd7e523..31efc2356 100644
--- a/specs/README.md
+++ b/specs/README.md
@@ -23,6 +23,7 @@ The specifications that define the three.ws embodied-agent platform: on-chain id
- [`PROVENANCE_3D.md`](./PROVENANCE_3D.md): Verifiable 3D Provenance v1. C2PA-style signed content credentials for AI-generated 3D: creator, prompt, model, lineage and the GLB's content hash, ed25519-signed and anchored on Solana. Verification is free and public.
- [`PORTAL_WORLD.md`](./PORTAL_WORLD.md): Portal World v1. The two documents behind `/api/portal`: the outline a web page is read into, and the deterministic, seeded world that outline lays out into. Pure layout, so the browser renderer, the GLB exporter, the MCP tools and the npm package all build the same city from the same link.
- [`SIM_READINESS.md`](./SIM_READINESS.md): Simulation Readiness v1. The physics grade a 3D asset carries: watertightness, metric scale, mass and inertia, and a convex collision proxy, in four verdicts. Everything is derived from the mesh; anything unknowable from the geometry is reported as unknown rather than invented. Rides the provenance credential when signed.
+- [`ENGINE_BRIDGE.md`](./ENGINE_BRIDGE.md): Engine Bridge Spec v1. The shared contract every game-engine integration speaks against the public Forge API (auth, catalog browse, generate, poll, download, import settings), implemented independently by [`packages/unity-bridge`](../packages/unity-bridge), [`packages/godot-bridge`](../packages/godot-bridge) and [`packages/unreal-bridge`](../packages/unreal-bridge).
- [`SKILL_ROYALTY_SPLIT.md`](./SKILL_ROYALTY_SPLIT.md): Skill Royalty Split v1. How a paid skill call divides between the author and the platform, and how that division is recorded: exact integer arithmetic that conserves value and rounds toward the creator, who the author of record is, which wallet a payout resolves to, and the ledger invariants both earning lanes must hold. The contract the x402 rail, the accrual writer, the settle cron and the earnings surface all read from.
- [`SKILL_REGISTRY_MANIFEST.md`](./SKILL_REGISTRY_MANIFEST.md): Skill Registry Manifest v1 (`three.ws/skill-registry@1`). The JSON document an external skill registry serves so three.ws can import its `SKILL.md` skills: required fields, the sha256 pin every body must match, licence and category fields, and how installed skills stay pinned until the owner approves an update. three.ws publishes its own users' skills in the same format.