From Upload to Embed — The Vectreal Publisher Walkthrough

Before You Begin#

The Vectreal Publisher is available at vectreal.com/publisher. No account is required to upload and configure a model — you will only be prompted to sign in when you want to save a scene to your account and publish it.

If you want to follow along, grab any GLB or glTF file you have on hand. If you do not have one, the three.js editor can export examples, or you can pull a model from Khronos glTF samples.

Step 1 — Upload#

Drag your 3D file onto the Publisher canvas. The parser identifies the format, resolves any external references, and loads the model into the viewport.

Supported formats:

glTF bundles: glTF separates geometry, binaries, and textures into multiple files. To upload a full bundle, drag the entire folder onto the upload area, or select all files at once in the file picker. The parser identifies the .gltf root and resolves all referenced .bin and texture files automatically.

There are no hard file size limits enforced in the Publisher UI, though very large files (above 500 MB) may slow browser-side parsing. For production-grade assets, the optimization step in the next section helps significantly.

Common upload errors:

Step 2 — Optimize#

Once your model is in the viewport, the right sidebar shows the quality presets. These are the fastest way to reduce file size for web delivery.

Quality presets:

Presets are non-destructive: switching between them re-processes from the original uploaded file. Nothing is lost. Advanced users can override the preset ratio and texture quality values manually in the settings panel.

What is happening under the hood:

Mesh simplification uses the glTF-Transform simplify function. The ratio controls the fraction of triangles retained — 1.0 means no simplification, 0.5 means 50% of triangles are kept.

Texture compression uses the KTX2 / Basis Universal pipeline, running asynchronously in a Web Worker. The viewport preview uses the uncompressed original while compression runs in the background, so you can keep working without waiting.

For server-side optimization (via @vctrl/core), Sharp is used for texture compression. When Sharp is unavailable, the pipeline falls back to deduplication and pruning rather than failing.

Step 3 — Configure#

Beyond file size, the Publisher gives you full control over how the scene looks and behaves.

Lighting and Environment#

Choose from a set of HDR environment presets — including studio, sunset, and warehouse options — that determine ambient lighting, reflections, and image-based lighting (IBL). You can adjust environment intensity and background blurriness, and optionally override the transparent background with a solid color using the background color picker.

The Stage component from React Three Fiber's Drei library positions the model automatically and adjusts the camera to fit. The adjustCamera setting controls how tightly the camera frames the model.

Camera#

Set the camera's starting world-space position (x, y, z). The camera will animate to this position when the scene loads. Adjust field of view in degrees: wider (e.g. 90°) exaggerates depth; narrower (e.g. 30°) produces a flatter, more orthographic feel.

Auto-rotate: enable continuous orbit around the model. Configure the rotation speed and the pause delay after user interaction (in milliseconds) — so the model stops rotating when a visitor interacts with it, and resumes after they stop.

Shadows#

Two shadow types are available:

• Contact shadows — lightweight and sharp, good for most use cases. Configurable opacity, blur, scale, and color.
• Accumulative shadows — physically richer, with configurable temporal sampling, frame count, and a nested light configuration for softness and intensity.

Grid#

Grid controls are currently not active in the viewer render flow. This section will be updated when grid rendering is available.

Step 4 — Save the Scene#

Click Save in the Publisher header.

• If you are signed in, the scene saves to your account immediately and appears in the Dashboard.
• If you are in an anonymous session, you will be prompted to sign in or create a free account. Your configuration is preserved — nothing is lost.

After saving, the scene appears in your Dashboard. From the Dashboard, you can also replace the model (drag a new file onto the canvas in an open scene — camera, lighting, and publish settings are preserved) and manage multiple scenes across projects.

Step 5 — Publish#

From the Dashboard, open the scene. In the Publish sidebar section, click Publish.

Publishing transitions the scene from draft to published status and generates a stable embed URL.

Draft scenes are never accessible to external iframe embeds. They remain viewable only by authenticated collaborators with project access.

To revert, click Unpublish. The embed URL becomes inaccessible to external principals immediately.

Step 6 — Set Up a Preview API Key#

External iframe embeds require a preview API key scoped to the project that owns the scene. This is how Vectreal ensures scenes can only be embedded by authorized principals — not hotlinked by arbitrary sites.

To create a key:

1. Go to Dashboard → API Keys.
2. Click New API Key.
3. Select the project(s) the key should have access to.
4. Copy the key — it is shown only once.

Pass the key as the token query parameter in the embed URL, or as a Bearer token in the Authorization header for API requests.

Restricting embed domains (optional):

To prevent hotlinking from unauthorized domains, open Dashboard → Projects, select your project, click Edit, and add entries to Allowed embed domains. Supported patterns:

Requests from unlisted domains receive a 403 Forbidden response. Note: localhost and 127.0.0.1 are always allowed regardless of the domain allowlist, so local development always works.

Step 7 — Embed#

Copy the embed snippet from the Embed section in the publish sidebar or from the scene detail page in the Dashboard.

Responsive 16:9 snippet:

<div style="position:relative;padding-top:56.25%;width:100%">
  <iframe
    src="https://vectreal.com/preview/fullscreen/<projectId>/<sceneId>?token=YOUR_PREVIEW_API_KEY"
    style="position:absolute;top:0;left:0;width:100%;height:100%;border:0"
    allow="autoplay"
    loading="lazy"
  ></iframe>
</div>

Fixed size snippet:

<iframe
  src="https://vectreal.com/preview/fullscreen/<projectId>/<sceneId>?token=YOUR_PREVIEW_API_KEY"
  width="800"
  height="450"
  style="border:0"
  allow="autoplay"
  loading="lazy"
></iframe>

Paste either snippet into any HTML page. The embedded viewer loads your published scene.

Two preview layout variants are available:

Both modes support the token query parameter and Authorization: Bearer authentication.

Status Code Reference#

Worth bookmarking for debugging:

The Whole Workflow in One Place#

What to Do Next#

• Try it now: vectreal.com/publisher — no account required.
• Create a free account to save scenes, manage projects, and publish embeds.
• Use the packages directly in your React app: install @vctrl/viewer and @vctrl/hooks from npm to build a custom 3D loading and rendering flow without the Publisher UI.
• Contribute: the full source is on GitHub. Issues, PRs, and discussions are open.
• Join the community: discord.gg/A9a3nPkZw7 for support, feature requests, and direct conversation with the team.

Connect with the community: vectreal.com · Discord · GitHub · npm · Reddit · Stack Overflow · X · Product Hunt