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

Limitations

The .mdl file format used by FFXIV imposes a number of limitations on the models you create. Below are a few of the notable limits.

• Materials: 4 per model, 1 per mesh
  A model can reference up to 4 separate materials, with each mesh being able to reference 1 of those 4. Multiple meshes may use the same material. This is a fairly lenient limitation, given how much control materials give you, however you may encounter it if creating mashups from multiple pieces of gear. The only workaround is to modify the materials/textures to reduce the number of materials required.
• Attributes: 32 unique attribute names per model
  Two separate sub-mesh using the attribute atr_hij will only consume one slot, as the name is the same. You are unlikely to hit this unless adding a significant number of plugin-specific attributes (i.e. for SimpleHeels).
• Bones: 64 weighted bones per mesh
  Each mesh within a model has its own bone table, which supports a maximum of 64 mappings. This can be worked around by splitting a mesh into multiple, and ensuring each resulting mesh is mapped to less bones than the limit.
• Shape Keys: 65535 modified indices per model
  All meshes in a model file share vertex mapping space for shape keys. While 65535 sounds high (it is), it's very easy to hit this limit if you leave body type shape keys (common in some body model dev kits) unbaked. As alluded to, the simplest work around is to bake any shape keys that will not be modified by the game's engine.

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.
• Data ➔ Mesh ➔ Tangents
  Typically should be enabled. While Penumbra can calculate tangents, it's recommended that you leave that up to blender unless receiving errors.
• Data ➔ Mesh ➔ Attributes
  Penumbra uses custom attributes for vertex colours. While Blender does export these as colour by default, keeping this enabled is recommended as a safety net.
• 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.4

• export will no longer error out on models with invalid attribute data (it'll warn about it though).
• exported materials now also utilise specular factor as well as color, which should fix Blender 3.6 export compatibility.
• export will now use the _FFXIV_COLOR custom attribute for vertex colour data. This should result in it still being editable in vertex paint mode, but not visible by default (no more blue skin!).
• import will also check for the _FFXIV_COLOR attribute, falling back to COLOR_0 if it does not exist.
• import now uses 32bit floats for normals and UVs.
• import can now import meshes with multiple primitives. As with multiple submeshes, only the first material will be used - XIV does not support more than one material per mesh.
• import and export will now correctly clear errors and warnings between runs.

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!