Orbit 3D theme guide

Orbit is a paid storefront theme where a 3D product model stays on screen and moves with the scroll. This page shows how to swap the model, find camera coordinates and tune everything from the builder.

How Orbit works

Orbit shows one sticky 3D stage behind four story sections that scroll over it:

1. Hero: intro with a gentle floating animation and your call-to-action buttons.
2. Features: the camera moves in on a detail, with overlay text and floating hotspot labels.
3. Inspect: the product is pulled apart. Every named part slides outward. A model without separable parts turns slowly under a moving spotlight instead.
4. Buy: back to the full view with your real product, its options (stock aware), quantity, Buy now and Add to cart.

Below the story come the product grid (all products with images and a category filter), the review wall (real reviews, zero state included), the FAQ and the footer with legal links, newsletter and the shop report link.

Orbit is a paid theme: it is bought separately, once, on any plan. A Premium or Pro subscription does not include it.

Where the settings live

Every 3D setting is in one place: open Builder, pick the 3D showcase story section and edit its fields. The fields are turned into one configuration object, described field by field in themes/orbit.config.schema.json. The shop colours, the header, the footer and the product grid use the normal theme settings.

Swap the 3D model, step by step

1. Prepare the file. Export your product as a single .glb (or .gltf) with the front facing +Z and Y up. Scale and position do not matter: Orbit centres the model and scales its largest side to 2 units. Keep it under 8 MB (hard limit 25 MB): fewer polygons and textures up to 2048 px load fastest.
2. Name the parts. For the exploded view give every separable part its own top-level node with a clear name (for example Screen, Battery, Lens). Orbit lists those names in the Inspect section. One wrapper node around everything is fine: Orbit looks through it.
3. Put the file on the site. Copy it to frontend/assets/models/ of your installation, for example my-product.glb. See Where the file can live.
4. Set the URL. In the 3D showcase story section set 3D model URL to /assets/models/my-product.glb. A wrong URL is refused with a clear message in the builder preview, and the default model keeps showing.
5. Tune the camera with the camera debug below, then paste the coordinates into the section fields.
6. Add a poster. Export a still image of the product and set it as Poster image. It is shown while the model loads and as the fallback.

Where the file can live

The URL must be https://host/path/model.glb (or .gltf), or a same-site path under /uploads/ or /assets/models/. These are refused with a message: javascript:, data:, blob:, plain http:// (localhost for development is allowed), //host addresses, paths with .. and any other file type.

Two platform rules apply. The storefront Content-Security-Policy only lets pages download files from the same site (connect-src 'self'), and Orbit does not loosen it, so a model on another host loads only if the policy allows that host. The public /uploads/ folder serves images only today, so the dependable place for a model is /assets/models/. Draco, Meshopt and KTX2 compression need WebAssembly and workers and are not supported: export a plain GLB.

Find camera coordinates

Open your storefront while you are signed in as the owner and add ?orbitDebug=1 to the address (inside the builder preview it is available too). A small panel shows the live camera as JSON:

{ "camera": [0, 0.3, 6.6], "target": [0, 0, 0], "fov": 30, "section": "inspect", "rotation": [0.32, -0.85, 0.06] }

1. Scroll to the section you want to tune. The panel shows the pose of that section.
2. Press Free look, drag to orbit and use the mouse wheel to zoom until the view is right.
3. Press Copy JSON and paste camera and target into that section's camera position and camera looks at fields (type them as x, y, z).

The panel is only shown to the signed-in owner (and in the builder). Visitors never see it.

Advanced JSON

The advanced field accepts any part of the config and merges it over the simple fields. Example: a stronger explosion, a bigger float and an extra hotspot on the lens:

{
  "float": { "amplitude": 0.1 },
  "explodeDistance": 0.9,
  "sections": { "inspect": { "explode": 1 } },
  "hotspots": [ { "label": "Lens", "position": [0.26, 0.78, -0.1], "section": "features" } ]
}

Invalid JSON or out-of-range values are reported in the builder preview and clamped. Nothing in it is ever executed.

How the exploded view works

• Top-level named children of the model are the parts (single wrapper nodes are skipped).
• Parts that sit around the centre of the model slide apart along its thinnest axis, like layers.
• Parts far from the centre move outward along their direction from the centre.
• With fewer than two separable parts the model turns slowly and a spotlight sweeps across it, and the Inspect section shows your note instead of the part list.

Performance, phones and fallbacks

• The 3D code is only loaded on pages that show the Orbit story. All libraries (three.js, GSAP with ScrollTrigger, optional Lenis) are served from this site.
• Rendering pauses when the story is off screen or the tab is hidden.
• A short frame-time check lowers the quality step by step on slow devices: high, medium, low, then a static poster with a CSS-only scroll parallax. Without WebGL the poster is used straight away. The setting Quality, or ?orbitQuality=high|medium|low|static, forces a level.
• Visitors who prefer reduced motion get stepwise sections: the model jumps to each pose without scrubbing, floating or turning.
• The canvas never takes clicks: all text and buttons stay clickable. Everything is released again when the page is re-rendered.

Troubleshooting