Model IO

Export

Penumbra exports models in the glTF format (reasoning).

Below are recommended settings for using exported files in 3D workspaces. If your tool of choice is not listed, please reach out and we'll see if some recommendations can be included!

Blender

These settings are based on Blender 4.0. Older versions may have slightly different configuration or less options.

Click for visual example

• Bone Dir
  "Temperance" provides best results. If your model is covered in large balls, you likely imported with "Blender" selected in this option.

Issues & Errors

Exported models have patches of, or are covered in, strange colour tints These are vertex colours, and represent metadata that XIV uses for various rendering details. You can check the TexTools reference document for some information on what they can mean. There are plans to prevent this data showing up when not directly editing them, as it's recognised that they're a little visually disruptive in 3D workspaces.

Exported models have a lot of broken meshes in addition to correct ones These are "level of detail" meshes, also known as LODs. XIV stores up to 3 copies of every model, with 2 of those copies being increasingly low-detail smushed versions of the original, used to reduce the quality of things rendered in the distance. When present, Penumbra will export all 3 LODs, which is what you're likely seeing with the broken-looking meshes.

Authoring

Attributes

Attributes are imported and exported from glTF as "extras". You can edit these on a per-sub-mesh basis. Only boolean extras with the value of true will be considered.

Blender

In blender, glTF extras are imported and exported as object custom properties. These can be found and edited in the Properties pane, under Object Properties ➔ Custom Properties. If adding a new attribute, make sure to set the Type to Boolean.

Click for visual example

Import

Penumbra can import models in the glTF format (reasoning).

Below are recommended settings for exporting files from 3D workspaces. If your tool of choice is not listed, please reach out and we'll see if some recommendations can be included!

Blender

These settings are based on Blender 4.0. Older versions may have slightly different configuration or less options.

Click for visual example

• Format
  All options should work correctly, however "glTF Separate" is recommended if providing files for debugging purposes.
• Include ➔ Data ➔ Custom Properties
  Enable if using custom properties to author attributes.
• Mesh ➔ Tangents
  Typically should be enabled. While Penumbra can calculate tangents, it's recommended that you leave that up to blender unless receiving errors.
• Shape Keys ➔ Optimize Shape Keys ➔ Use Sparse Accessor if better
  Must be disabled, or imports will likely fail.

Issues & Errors

_bufferView: must be defined Typically, this is caused by a limitation of the glTF library Penumbra uses, related to the usage of "sparse accessors" (specification) for morph target data. To work around this in Blender, disable the "Use Sparse Accessor if better" option when exporting. See Blender export recommendations for more details.

Questions

Why glTF?

glTF is a open source industry standard format, published by the Khronos Group (OpenGL, Vulkan, et. al.). As a format, it offers all the features required for accurate model data import and export in Penumbra, and is well-supported in a growing number of 3D workspace tools.

There have been (fair) queries as to why we do not use FBX (another commonly used 3D data format), as support for glTF is lacking in many of Autodesk's products. Unfortunately, FBX is a proprietary format owned by Autodesk - implementing support in Penumbra would be in breach of the SDK's license.

If your preferred 3D workspace does not currently support glTF, Blender is free, and able to import and export both glTF and FBX, and as such can be used to convert between the two formats. This is recognised to be clunky, and a more robust solution may be implemented in future - but for now, we're focused on making the glTF output as watertight as possible!

Changelog

1.0.0.3

• both import and export can now report warnings if non-fatal issues occured.
• export has a new option that will generate missing bones.
  warning: this can hide misconfigured skeletons, and leave you with a useless export. only enable for models that you know have broken weighting.
• imports with 2 or more shape keys on the same mesh should no longer break.
• exports with missing materials will now fall back to a plain white material.
• documentation links have been added (you're looking at the page right now!)

1.0.0.2

• import will calculate main model bounding box
• import will copy element ids from the model it is replacing
• import will generate a white (1, 1, 1, 1) vertex colour attribute if none exists in the source file
• fixes for export path resolution when using file swaps

1.0.0.0

• import will now correctly calculate bitangents
• import will now attempt to calculate tangents (to use for bitangents) if they're missing

0.8.3.6

• export will now try to compose materials and textures

0.8.3.5

• materials and attributes are now exported and imported from gltf
• you can now instruct import to maintain existing materials and attributes already in penumbra
• errors during export and import are now reported correctly, in a nicer ui

0.8.3.4

• rudimentary .mdl↔.gltf import and export is now available in the models advanced editing tab!