Hology Vite Plugin

Prepares data for

Usage

Add the plugin to your vite config like below.

// vite.config.ts
import hologyBuild from '@hology/vite-plugin'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    hologyBuild()
  ]
})

Optional FBX to GLB conversion

FBX model assets can be converted to binary glTF during production builds. This is disabled by default. The plugin ships FBX2glTF through its fbx2gltf dependency, but an explicit tool path can still be provided when needed.

hologyBuild({
  optimize: {
    models: {
      fbxToGlb: {
        enabled: true,
        exclude: [
          'characters/problematic.fbx',
          'legacy-props/*'
        ]
      }
    }
  }
})

To force a specific converter build, set optimize.models.fbxToGlb.tooling.fbx2gltfPath.

Use optimize.models.fbxToGlb.exclude to leave selected FBX assets unconverted. Exclusion entries match asset ids, asset names, fileKey, or originalFileKey. Exact strings and simple * / ? glob patterns are supported.

When an FBX asset has Hology's default centimeter import scale (mesh.rescale: 0.01), the converted GLB metadata removes that rescale so the scale correction is not applied twice. Scene objects referencing that converted asset are also scaled up by 100 in the bundled scene blob so existing scenes keep the same visual size. Set optimize.models.fbxToGlb.preserveFbxRescale to keep the original rescale metadata and skip that scene-object compensation.

The conversion also preserves material assignment color keys by default. If an FBX material slot was assigned by Hology as #e7e7e7 and FBX2glTF emits that slot as white in the GLB, the plugin patches the GLB material base color back to the assignment color so existing color/name based material assignments continue to match. Set optimize.models.fbxToGlb.preserveMaterialAssignmentColors: false to disable this behavior.

Embedded model material extraction

When optimize.models.extractEmbeddedMaterials.enabled is set, embedded GLB/GLTF/FBX material textures are extracted into generated Hology material and texture assets before texture compression runs. This lets texture array packing include model-owned textures while runtime material assignments replace the model's imported material slots with the generated Hology materials.

FBX extraction only supports image payloads embedded in the FBX file. It leaves the source FBX model resource unchanged, so it does not inherit the scale, hierarchy, or UV differences that can come from FBX-to-GLB conversion.

Standard material normalization

When optimize.models.normalizeMaterials.enabled is set, standard material texture slots can be filled with generated build-time default texture assets before texture compression runs. This helps texture array packing batch more materials together because missing texture slots become real texture assets.

hologyBuild({
  optimize: {
    models: {
      normalizeMaterials: {
        enabled: true,
        standard: {
          textureParams: [
            'map',
            'roughnessMap',
            'metalnessMap',
            'aoMap',
            'alphaMap',
            'normalMap',
            'emissiveMap'
          ]
        }
      }
    }
  }
})

Generated defaults are marked as build-only metadata and removed from the final bundle after compression. The texture assets remain in the bundle like any other generated texture asset.