Timbermesh Blender Plugin manual - mechanistry/timbermesh GitHub Wiki

Intro

Timbermesh Blender Plugin is a plugin for Blender that allows exporting Blender models to Timbermesh file format. This documentation will guide you through the installation process and usage of the plugin, as well as provide tips and best practices for exporting your models.

Detailed information about Timbermesh file format can be found here: https://github.com/mechanistry/timbermesh/wiki/Timbermesh-overview

Requirements

Timbermesh Blender Plugin is compatible with Blender version 2.80 and later. For the best experience we strongly recommend using stable branches of Blender. Using experimental or nightly builds may cause compatibility issues or unexpected behavior, as they are still in development and may not be fully tested. Always ensure that you are using a stable version of Blender before installing the Timbermesh Blender Plugin.

Installation

To install the plugin, follow these steps:

  1. Download the latest release of the plugin from the GitHub repository.
  2. Open Blender and go to the Edit menu.
  3. Select Preferences from the dropdown menu.
  4. In the Preferences window, click on the Add-ons tab.
  5. Click on the Install button at the top right of the window.
  6. Navigate to the location where you saved the downloaded plugin, select it and click on the Install Add-on button.
  7. Enable the plugin by clicking on the checkbox next to its name (in case it is not checked by default).

Upgrading

If you already have Timbermesh Blender Plugin installed you need to remove the old version first before installation of the new one. You can do this by going to Edit > Preferences > Add-ons, finding the Timbermesh Blender Plugin plugin and clicking the Remove button.
It is very important to restart Blender before installation of a newer version of the plugin.

Usage

Exporting a single collection

Timbermesh Blender Plugin utilizes the concept of Blender collections to organize 3D models in the scene hierarchy. Collections help to keep the model hierarchy organized and facilitate better management of complex models. Models must be placed in collection to be able to be exported.
More about Blender collections can be found at:
https://docs.blender.org/manual/en/latest/scene_layout/collections/collections.html

To export models stored in collection:

  1. Open a Blender file that contains the model you want to export.
  2. Select the collection with the models you want to export.
  3. Right-click the collection and select Export (*.timbermesh) from the context menu.
  4. Choose a file name and location for the exported file in the export window.
  5. Optionally change export settings in the right section of the window (see Export settings below).
  6. Click the Export Collection button to begin the export process.

Batch export

Timbermesh Blender Plugin also allows exporting multiple collections at the same time - this is called a โ€œbatch exportโ€. Contents of each collection will be exported as a separate file and its name will be automatically inherited from the collection name. The export process for multiple collections is similar to exporting a single one:

  1. Select collections you want to export while holding down the Ctrl key.
  2. Then right-click one of the selected collections and choose Batch Export (*.timbermesh) from the context menu.
  3. Choose a target directory for the exported files in the export window.
  4. Click the Export Collection button to begin the export process.

Export settings

There are several export options that user can change before export process:

  • Merge meshes - when this option is checked the export process will try to merge all meshes into a single one (see Mesh merging below).
  • Single animation - this option will export single animation based on global scene frame range settings (for more details see Animations below).
  • Use vertex animations - when this option is checked the exporter will export animations using Vertex Animation Texture (VAT) system if possible (for more details see Animations below).

Mesh merging

By default Timbermesh Blender Plugin merges all model meshes into a single large mesh. All vertex attributes and material information are preserved during the merge process - resulting mesh is visually identical to its source. Merging process starts with the root objects and then traverses the hierarchy, merging children into their parent nodes recursively. User can skip merging individual objects by prepending their name with # (hash) sign. Such objects will be treated as special and the merging process will preserve them (and their meshes) in the resulting model hierarchy. It may be useful in situations where these objects must be accessed programmatically (e.g. from a game engine) or if someone wants to keep them separated for any other reason. It must also be noted that mesh animated by Node animation cannot be merged and its node should stay separated.

Mesh merging can be completely disabled during export by switching off Merge meshes in settings.

Animations

Timbermesh Blender Plugin allows to export multiple animations per object by using Blender actions. Each action corresponds to a new animation being created (with given name, FPS rate and frame range). Additionally there is an option to export only one animation by using Single animation export setting. When this is enabled, the export process will create a single "Default" animation - its FPS rate, start and end frame will be taken from Blender global scene settings.

Detailed description and working principles of both animation types (Vertex animation and Node animation) can be found in Timbermesh format specification. Below are general comparison that should help to choose the appropriate type of exported animation based on model characteristics.

Vertex Animation

Vertex Animation can only be used on MESH type objects (with actual geometry).

Pros ๐Ÿ‘๐Ÿผ Cons ๐Ÿ‘Ž๐Ÿผ
Vertex animation can often replace skeleton animations (if pose blending is not important), thus reducing CPU and GPU resources needed for complex bone calculations. VAT implementation usually takes up much more graphics card memory (VRAM) and should be used with care, especially for models with complex geometry and detailed animations.
Because no individual object is animated (but mesh as a whole), it allows to merge multiple meshes into a single one (e.g. to reduce draw calls). This can significantly reduce rendering time in most game engines and simplify working pipeline.
It is open for various mesh deformation techniques such as morphing or UV animation (as it directly changes vertex properties).

Node Animation

Node Animation can be used on both EMPTY and MESH type objects.

Pros ๐Ÿ‘๐Ÿผ Cons ๐Ÿ‘Ž๐Ÿผ
Itโ€™s very lightweight - takes much less memory space than VAT animations This animation system can animate only simple transformations - translation, rotation and scale.
When using Node animation on a mesh object, it cannot be merged with other parts of the model (see Mesh Merging above).

Support

If you encounter any issues with the Timbermesh Blender Plugin please report them on the GitHub Discussions page (https://github.com/mechanistry/timbermesh/discussions).

License

Timbermesh Blender Plugin is licensed under the MIT License.