FBX structure

following pipeline is verified as compatible with 3dsMax, Maya and Blender
it is possible to export the FBX from any of the software and import it into any other software and edit it without loosing any data

General rules and habits

syntax is not case-sensitive (all can be written with both small and large letters)
do not use spaces or any special symbols /\<>:"|?*
- if such symbol is used in material name it gets converted to "_"(underscore) during FBX import, what causes inconsistency between source(fbx) vs. engine(xob.meta file) data, what prevents Bohemia Blender Tools addon to properly match material name(stored in FBX) -> emat

for good readability it is strongly recommended to use LARGE letters for prefixes and suffixes and small letter for text in the core name of an object
the import into Enfusion doesn't take into account any layers, so you can put your models into any layers you want. In other words, you can organize you source file however you want.
keep in mind that duplicated object names might problem from Blender and sometimes might confuse Workbench FBX importer, therefore it is recommend to use unique names for objects

Alignment

always align assets pointing along Z+ axis in Enfusion; for this asset must be oriented as pointing along/towards the Y+ axis in Blender, 3dsMax and Maya
Weapons: Barrel along Z+ (Enfusion)
Vehicles: Nose pointing along Z+ (Enfusion)
Buildings: Main entrance pointing along Z+ (Enfusion)

LODs

to detect what mesh object is part of what LOD, the engine is looking at a suffix in a name of a model
name for LOD model object must look like this = name_of_the_object_LODx = Car_LOD0, Bowl_big_LOD3....
LODs suffixes are starting with LOD0, LOD1, LOD2 and can go to whatever LODx number you want.
more meshes/models per LOD are possible = Car_LOD0, Trunk_LOD0, Wheel_LOD0 will all be imported to LOD0.
if the mesh doesn't meet any known prefix or suffix convention, it will go to LOD0
if mesh has for example only _LOD0, _LOD2 and LOD4 meshes, LOD2 will behave like LOD1 and LOD4 like LOD2


Blender setup	Enfusion after import

Collider shape


All possible collider shapes	3dsMax setup	Enfusion after import

name for collider shape model = COLLIDER SHAPE_name_of_the_object = UBX_Car or UCS_wall1_part1 for example.
collider shapes (primitives, which can be created in most 3d software):
- UBX_ - box
- UCX_ - convex
- USP_ - sphere
- UCS_ - capsule
- UCL_ - cylinder
- UTM_ - triangle mesh (trimesh)
most collider shapes can't be scaled just by one or two axis, otherwise they will lost their shape and will not be imported. The only scaling that will work will be scale along vertical axis of capsule and cylinder + trimesh and box can be scaled along all axis.
collider shape with corrupted/not recognized shape is ignored (current solution)

Collider hierarchy

collider hierarchy in FBX is important for correct hit-zone detection and possibly other simulations. Rules are simple:
- when asset contains animated and non-animated parts, The static colliders must not have any parent in the hierarchy. Only animated parts must be children of corespondent bones. In other words...if static collider, which always moves and rotates with asset's root, is child of root bone, it is wrong. There must simply be no parent for such a collider.

Collider usage

General rules

⚠

Two main rules apply

every collider should be as simple as possible
when artist is in doubt, refer to rule number 1

Other things worth to consider:

Primitives and Convex colliders can have only one physical material per collider
Triangle mesh collider (Trimesh) can have assigned physical material per triangle
- must have checked Merge Tri Meshes, otherwise all UTMs will stay separate even if they share the same Layer Preset
- UTMs with different Layer Preset (custom property) will not be merged even with "Merge Tri Meshes" ON

Trimesh objects should have closed mesh, as backface don't react. Can be left open if backface is not accessible (access closed by different mesh)
in Trimesh avoid very small, degenerated or huge triangles...make the triangle mesh as uniform as possible, even if its gonna have a bit more triangles because of that
the less triangles in Trimesh the better

the smaller number of colliders the better
avoid overlapping colliders as much as possible

Performance

- less amount of more complex colliders is much better than bigger amount of less complex colliders with the same amount of triangles

Restrictions

	Static	Dynamic
Collisions	All	NEVER Trimesh, otherwise all
Fire / View	All	All

How to use them

Static (buildings, infrastructure, trees)

prefer one triangle mesh over multiple primitive shapes (houses with lots of windows, doors etc....door and windows separate colliders though)
- try to make the triangle mesh as uniform as possible
- try to make the number of triangles as low as possible
prefer primitive or convex shapes where it makes sense
- street light can be approximated as two cylinders in collision
- simple street mail box could be one box shape in collision
- power transmitters can often be approximated by several (less than 10) convex shapes, if not use one triangle mesh in collision
if the geometry is very similar to View or Fire geometry, consider sharing View / Fire and Collision as one slightly more complex Collision layer that can be shared with Fire/View...it is better than to have multiple layers just because of few triangles

Dynamic objects (vehicles, weapons, magazines, small destructible objects (also tree _dst parts), etc.)

the process of selecting a correct shape should follow these rules:
- use one primitive shape if possible (ideal case)
- if multiple primitive shapes can be replaced with one convex shape then use the convex
- avoid trimesh ( just static parts of vehicles should be merged in trimesh in fire/view; wheels can by cylinders)

Avoid overlaps

overlap of more objects is totally unacceptable
overlap of just two object is acceptable in edge-cases when necessary
best is to split the the overlapping collider

Setting Layer Preset on colliders (usage parameter)

we are talking here about models for simulations like Collision, and possible others like NavMesh, Fire geometry, View geometry or others
one collider shape can have many usages (can serve for different simulations), different mix of usages are defined through a Layer preset as custom parameter/attribute/property in the data...we name it COLLIDER USAGE
rules:
- it is a string parameter
- its name is "usage" and in value are/will be all defined usages like this: "FireGeo" (only for detection of bullet impacts in this case) and possible others
- for list of Layers, LayerPresets and how collision matrix is setup for AR, visit this page - Collision layers page
- if a collider shape has no usage parameter, then it collides (simulates) in every layer
- for creating custom attributes in 3dsMax, use only the Parameter editor in Animation menu, otherwise the properties in exported FBX can't be edited in Maya. So doing it with Object Properties/User defined is FORBIDDEN

Setting Layer Presets in Workbench

Blender - manual input

Blender - using plugin

3Ds Max example

Maya example

Physical material (Game material)

Game materials (used for physics, vehicles, sound, vfx) like dirt, concrete, glass, snow, etc. are being assigned to colliders through material name in 3D software (3dsMAx, Maya, Blender,...)
If you want to have your material automatically linked to existing game material, you should use following naming convention for material
- NameOfMaterial_GUIDofMaterial - example: Weapon_metal_3B2D2687F56BB4EF
- GUID of material can be obtained by clicking with right mouse button on gamemat and then selecting "Get Resource GUID(s)" option from contextual menu
- Blender users can use Collider Setup menu if they have Enfusion Blender Tools installed
triangle mesh collider shape (trimesh) can have more materials assigned (each polygon different), other colliders shapes can have only one material per object assigned

Resetting Geometry Params

ⓘ

Whenever you wanna changed Game material on any collider, first reset Geometry Parameters in Import Settings for an asset (.xob), otherwise new .gamemat won't be assigned and you will still see the old one. This can be done in two ways

By clicking with Right Mouse Button on Geometry Params property and selecting Reset do default value option
By clicking on arrow on the right side of Geometry Params property

Once that is done, Reimport resource button can be pressed. After resource was reimported, proper Layer Presets should be visible in the Geometry Params array

Reimport button

Materials

names of the materials in your 3D software are used by Enfusion, when Enfusion creates materials automatically after import. So name them carefully, so we don't have names of materials like Default1 and so on.
please avoid using special characters in material's name as Enfusion alter them during FBX import
- in case of: /\<>:"|?* , Enfusion replaces them with _ (underscore) character
- in case of: . (dot) , Enfusion strip string eg. M923A1_Base_Grating.008 -> M923A1_Base_Grating, mainly Blender user should pay attention as Blender names duplicates with .xxx
- both cases cause inconsistency between source(fbx) vs. engine(xob.meta file) data, what prevents Bohemia Blender Tools addon to properly match material name(stored in FBX) -> emat

Center of mass

center of mass can be defined through empty dummy/null object, with prefix COM_
when FBX doesn't have center of mass defined via empty object with COM_ prefix, engine will create center of mass in 0,0,0 coordinates
when there are two or more COM_dummies, engine will take the first one it find and ignore the rest

Occluders

occluders are defined as plane / box mesh with prefix OCC_
general hint about occluders:
- Make them as big as possible. If it covers only small part of building, it's not worth it. Choose another place instead.
- You can extend them little bit under ground. 1-2m is enough. If you'll extend them too much, you'll make them artificially bigger so the system will count with them on mucg bigger distance without a benefit - they become burden instead of speed-up.
- Total number per building should be rather low. Max 3-4 is reasonable
- Occluder must be aligned with one of the axes (X, Y, Z)
- Minimum reasonable size is about 4-5 m
- Boxes thinner than 30 cm are turned into planes
- Occluders cannot be triangulated!!!

Probes and Probe Volumes

define area which is affected by interior lighting probe
they are defined either as box primitive which can be scaled in any axis. They must be named following naming conventions (even for SPHVOL create box shape. It will transform to sphere during import in engine. It must be done with box as engine can't currently recognize object transformations from actual sphere mesh):
- name BOXVOL_n = box volume where n stands for volume ID number like (01, 02, etc.)
- name SPHVOL_n = sphere volume where n stands for volume ID number like (01, 02, etc.)
- example: BOXVOL_01 , SPHVOL_02 , BOXVOL_03 , SPHVOL_04 , ...
- assign them material named "dummyvolume"
  - upon FBX import dummyvolume.emat is created. In Matterial Assignes re-link the material to the one in https://a4-svn.bistudio.com/A4Data/trunk/Common/Materials and delete the newly created one.
we are able to cut off peaces of volume by defining cutting planes with plane primitive. We can do this in order to make volume shapes more precise and matching actual visual model. They must be created following some rules:
- create them as mesh part (mesh element) of the volume (BOXVOL or SPHVOL) objects. In other words, after you created the planes for a particular volume, merge them with the volume object.
- planes create infinitely large cutting planes in the engine
- orient them with vertex normals pointing towards the area you want to cut out
- you can create 4 cutting planes per volume as maximum. These influence only the volume they are merged with.
we can set how hard or smooth the border of the volume is by:
- legacy support should not be used on new assets
- correct way - setting it in Enfusion workbench, in building *.xob import settings in Visual/Volume Params
Probe itself must be created in engine as a child of building entity in the building prefab. Upon creation the probe is paired with volumes existing in the model.
Probes should be inherited from respective base prefabs:
- \Prefabs\Structures\Core\ProbeHouse_Base.et
- \Prefabs\Structures\Core\ProbeExterior_Base.et
- \Prefabs\Structures\Core\ProbeEnvCave_base.et
When you wanna have an extra probes using its custom volumes in a building prefab, the only way right now is by creating the volumes in engine in world editor, ideally inheriting from respective prefab and attaching the volume as a child of the second probe that is child of the building prefab.
- these volumes created in engine can't be adjusted by cutting planes and are just simple box or sphere shapes.
- volume base prefab: \Prefabs\Structures\Core\ProbeVolume_Base.et

Portals

Single portal

Shared portal

Define openings in the geometry through which light and sound can be propagated from the outside of the model to the inside and even between inside rooms in the model, i.e., doors and windows
They are specified as plane primitive with 4 vertices w/o triangulation (see screenshot below), their normal should be facing inwards the model (if they are representing door or windows to the exterior)
- The size should be slightly larger than the actual opening in the geometry - consider the UTM static collider as your reference geometry
- The position should be in the middle of the window/opening - must not be aligned with one of the walls as that can lead to degenerate cases
- Name PRT_n = portal where n stands for portal id
- A material specifying portal properties must be assigned - material class must be set to MatLightPortal (see below)
- There are rules to the hierarchy inside the FBX:
  - One window/door <==> one portal - portal model should be child of window/door socket
  - More windows/doors <==> one shared portal - both portal and all windows are child (on the same level) of "portal_group_win/door_n" parent bone
- Upon import, portals will be consumed and used for BSP construction - you first need to visit Import settings in Workbench, go to general and check that you want to Generate BSP and reimport the model

Sockets

defined as dummy/null object
dummies/sockets can be parented into hierarchical structure if needed
points of origins for various things like particle effects, prefabs,...
based on purpose of these, there are various naming conventions for different types of assets (weapon, vehicle, character,..)
currently there is no naming convention that will influence the import, except for COM_ (center of mass)

Land Contacts

defined as dummy/null object, with prefix LC_
used for snapping object to the ground and at least 2 Land Contact points must be created for this to work
object will be snapped and skewed following the ground slope under the object

Import process in the Workbench

Resource Browser

1. Put the FBX into your game template data structure and find it in the Resource browser

2. Right-click on it and you have two options: Register or Register and Import

Import as model

Import Settings

3. Upon clicking on Register, then as a Model, a meta file is created and you can set Import Settings

4. Upon clicking on Register and Import, then as a Model, it will give you Import Settings and create .txo and .xob (binary version of .txo) file, which is now our converted FBX.

Import Settings:

Merge Meshes: means merge all meshes of each visual LOD geometry with the same material into one mesh (optimization for faster render) - meshes with different number of UV sets don't merge!
Export Skinning: loads skinning data (required only if there is skeleton available, maximum 4 bones can affect single vertex)
Export Scene Hierarchy: loads bones/dummies as a sockets (slot, snap points and others)
Modify material names: ...
Legacy Support: turns ON old import pipeline, which overrides the new one. It shouldn't be used!

Reimport option in context menu

5. When the Import Settings are set, click either on Import Resource button (above Import Settings tab) or right-click on the FBX or XOB file in resource browser and click on Reimport

Skeleton

6. After import, more files are created. All materials and meta files are automatically created in data folder next to FBX, using names from materials in the FBX.

Reimport button

7. If you were importing model with skinning or hierarchy, you can verify skeleton in Bones section'

bones

FBX Export