How we use Timbermesh in Timberborn - mechanistry/timbermesh GitHub Wiki

Intro

Timbermesh was originally designed and developed as a replacement for a standard FBX format that we've used in our game - Timberborn. Its main goal was to simplify asset creation workflow and boost rendering performance. It allowed us to replace standard Unity animation components with our custom animation system (using Vertex Animation Texture). As it proved to be an effective and very performant solution, we would like to share some insight on how we use it in our project. This document serves as a general guideline for all Mechanistry artists that work with Timbermesh. It contains many technical details about how Timberborn models are made and we hope it'll be an informative read for anyone interested in using Timbermesh.

Organizational and naming guidelines

  • All models must be organized into Blender collections. Each building should be placed in a separate collection, where collection name should match the building name. If you want to keep some temporary, old, or WIP models that shouldn't be exported but are worth keeping, you should stash them in a collection named _Trash, _Temp or _Misc. It is a good practice to distinct collections by setting different color tags for each one. image

  • Single Blender file may contain several different models (e.g. buildings).

  • Each collection should be named using the following pattern: BuildingName.FactionName. This will help ensure that each building is easily identifiable within the scene.

  • Each building mesh (Timbermesh) file should be named using the following pattern (where timbermesh is the file extension): BuildingName.FactionName.Model.timbermesh. This pattern is required for buildings to be loaded correctly in game.

  • A single model can be composed of many separate meshes (all within a single collection). They can be optionally combined into one mesh during the export process (see Mesh merging below).

  • Special elements (model parts) that should not be merged during export must contain a # (hash) prefix in their name. This will prevent those elements from being merged during export and will preserve their position in model hierarchy. For more information about model merging see Mesh merging below.

  • Slots must be named as #Slot#SlotName. This will ensure that each slot is easily identifiable and properly used by game logic (see Slots below).

  • Materials attached to meshes must match the exact name of their respective materials in Unity (case sensitive). Attaching a material that does not exist in game will result in a game crash during the model loading process.

Timbermesh Blender Plugin

All models must be exported into Timbermesh format using the Timbermesh Blender Plugin. Detailed instructions on how to use this plugin can be found here.

Mesh merging

By default Timbermesh Blender Exporter merges all model meshes into a single large mesh. This way objects (e.g. buildings) can be created from many smaller reusable parts and still require less draw calls during rendering. The 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. In Timberborn this is generally used in three cases:

  • Slots (see Slots below).
  • Model parts animated by Node Animations (see Animations below) - buildings or character attachment points.
  • Elements that must be accessed or controlled (e.g. scaled or moved) programmatically in game - by skipping the merging process they are preserved within model hierarchy and can be referenced as separate objects.

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

Slots

Slots are special types of objects used to mark specific places (locations) within the building geometry. Those locations are then used by game logic to position characters according to slot position and rotation (e.g. when character visits a building and sits in a designated spot). A slot is usually an EMPTY Blender object type with name set according to pattern #Slot#SlotName. Slot name can vary depending on its purpose - most common slot names include:

  • Entrance
  • Swimming
  • Floating
  • Seat

In case of several slots of the same type they can have different name postfixes that are later ignored by game logic (e.g. #Slot#Entrance.001 or #Slot#Seat_1).

Animations

Detailed technical information about animation export can be found in the Timbermesh Blender Plugin manual here. When exporting Timberborn compatible models a few additional rules should be followed:

  • For characters all animations should be divided into Blender actions. Each action will result in a separate animation ready to be use in the animator controller (with given name, FPS rate and frame range).
  • Same rule can also apply to buildings, but as they usually have only one looped animation there’s no need to keep it as a specific action. When using a Single animation setting, the export process will create a single "Default" animation - its FPS rate, start and end frame will be taken from Blender global scene settings. This default animation will then be used by all building animation controllers.
  • When exporting characters Vertex animation should be used, as it allows to animate complex character movement without need for any skeleton and rig (along with costly bone calculations).
  • For any non-character animations (e.g. buildings or character attachment points) Node animation should be used as these animations are almost always simple transformations, rotations or scaling. In very special cases Vertex animation might still be used (e.g. very complex animation or blending between meshes), but it will result in a greater VRAM consumption and might cause in-game stability or performance issues.

Default export settings

Default settings that should be used to export Timberborn models.

Characters:

  • Merge meshes - FALSE
  • Merge animations - FALSE
  • Use vertex animations - TRUE

Buildings and other environment objects:

  • Merge meshes - TRUE
  • Merge animations - TRUE
  • Use vertex animations - FALSE

Technical guidelines

  • Number of draw calls for animated buildings should not exceed 3 (slightly more in special cases). Static buildings usually shouldn’t require more than one draw call (as long as they use a standard shader).
  • Please keep poly count (per tile) within a reasonable range to avoid performance loss:
    • Less than 200 - great
    • 200 - 250 - fine in most cases
    • 250 - 300 - only in justified circumstances
    • Above 300 - too many
  • Please keep proper unit scale and rotation of all root objects along with their orientation on scene. image