Statamic 3D Field Laravel Package

Getting Started

This addon ships a Statamic Control Panel fieldtype that wraps Google's <model-viewer> web component, so editors can upload and preview 3D assets (.glb / .gltf) inside the publish form. 1.1.0 widens the constraint to statamic/cms ^5.0|^6.0, so the same tagged release covers both Statamic 5 and 6 installs.

1. composer require <vendor>/<package> — the service provider is auto-discovered via extra.statamic; run php artisan vendor:publish --tag=statamic-... only if you intend to override views/Vue.
2. Clear caches after install/upgrade: php artisan config:clear && php artisan view:clear && php artisan statamic:stache:clear.
3. Create an asset container (e.g. models) with glb,gltf,bin,png,jpg allowed — glTF references sibling files, so a dedicated container beats dumping models into assets.
4. Add the fieldtype to a blueprint (CP → Blueprints, or the YAML in resources/blueprints/), restricting it to that container.
5. First use case: upload a .glb on an entry, confirm the 3D preview renders in the CP, then render it yourself in Antlers with <model-viewer src="{{ model:url }}" camera-controls auto-rotate>.

Where to look first: src/Fieldtypes/*.php for component() and the config() keys the fieldtype actually accepts (container/folder/restrictions), and resources/js for the Vue component if you need to know what the preview does. The compiled bundle is shipped — no npm run build required for consumers.

Implementation Patterns

• Blueprint-first configuration. Treat the fieldtype like any other Statamic field: declare container/folder restrictions in the blueprint and let editors pick from the asset browser rather than typing paths. Keeps the field portable across environments.
• Render as a partial. Wrap <model-viewer> in resources/views/partials/model-viewer.antlers.html taking src, poster, and a controls flag, so every 3D block on the site has consistent AR/camera behaviour.
• Load the front-end runtime yourself. The addon's Vue 3 build only registers model-viewer inside the CP compiler. On the front end add <script type="module" src=".../@google/model-viewer.min.js"> via a @push('head') stack or a Vite entry.
• Store a poster image. Add a sibling assets field for a still frame and pass it as poster; it doubles as the mobile fallback and keeps LCP reasonable.
• Asset augmentation is your friend. The value augments to an asset, so {{ model:url }} / $entry->model->url() works in Antlers, Blade, and API resources — no manual path juggling.
• CI matrix. Now that one tag spans both majors, run statamic/cms:^5.0 and ^6.0 in your pipeline before bumping the lockfile; the CP fieldtype bundle is shared, so a green matrix is the real compatibility signal.

Gotchas and Tips

• CP-only custom element. 1.1.0 registers model-viewer in the Vue compiler and inside Statamic.booting(). That does nothing for your public site; forgetting the front-end script yields an empty inline element that silently collapses to zero height.
• Don't rebuild the bundle on Vue 2. The release swaps @vitejs/plugin-vue2 for @vitejs/plugin-vue, externalizes Vue, and emits an IIFE with a FieldtypeMixin banner shim. If you forked the JS, rebase rather than merge — a stale Vue 2 build against Statamic 6 throws resolve errors at runtime.
• this. in templates is illegal in Vue 3. If you copied the fieldtype component to customise it, any {{ this.foo }}-style template reference must be removed or the field renders blank with only a console warning. Same for the removed toggle-input global — it is now ui-switch, and overridden views referencing the old component break silently.
• Cache layers bite. Statamic's addon manifest, view cache, and browser cache all need clearing after upgrading; a hard refresh is often required before a new CP bundle replaces the cached Vue 2 one. If the fieldtype simply doesn't appear, first check config/statamic/addons.php (cached config) and that you're not on Statamic 4.
• glTF 404s. .gltf + .bin + textures break the moment a relative path or CDN URL is off. Prefer self-contained .glb unless you have a reason not to.
• Large files hurt the publish form. The model loads inside the CP; a 60 MB GLB makes the entry editor crawl. Downscale previews, or keep a poster and rely on the field value rather than the live preview.
• AR needs HTTPS. Android/Scene Viewer and iOS ios-src USDZ both require a secure origin; test on a real device, not just php artisan serve.
• Extension points: extend the fieldtype class and override component(), or publish/override the Vue component; keep Vue externalized in your own build if you register a second addon on the same page, otherwise you double-load Vue and the CP breaks in confusing ways.