AnimEngine Blender Add-On Utilities

AnimEngine is designed around the open glTF 2.0 format, and is not designed around any particular 3D content creation software or animation tool. However, as a free and open source 3D creation suite Blender is commonly used to create scenes and assets for AnimEngine.

Likewise, a utility add-on for blender has been developed as a companion to AnimEngine. This add-on is intended to provide a variety of utilities augmenting the glTF import/export process and integrating additional tools for controlling how AnimEngine loads glTF files.

Installation

The add-on is installed like other Blender add-ons. The easiest method is to download the add-on source as a zip file from the github repository releases page. Then use Blender’s ‘install’ button from the add-ons menu (Preferences → Add-ons → Install). The add-on still needs to be enabled from the add-ons menu once installed.

Features

The AnimEngine Blender utilities currently includes two categories of utilities: Armature Normalization and glTF AnimEngine Markup. Additional utilities will be added in the future as new needs arise.

Armature Normalization

Armature normalization is a tool designed to automatically adjust armature rigged assets for export to glTF. Many armature rigs which are perfectly valid in Blender, cannot be captured in glTF, and will not function after export. Most common armature issues can be corrected quickly using the Normalize Armature Relationships Operator operator found in the Objects menu of the 3D viewport.

Despite this, it is still preferable that assets be created in a manner compatible with glTF from the start. Doing so makes issues less likely to arise, and reduces the risk that rigging or animation need to be redone in order to accommodate the glTF format. See Armature Rigged Assets for a guide on creating assets with armatures.

Normalize Armature Relationships Operator

Correction of a rig exporting incorrectly can usually be accomplished through a single use of this operator. The operator applies to all selected objects, and may modify the parents of selected objects as well. It is generally recommended that you select all parts of a rigged asset before using the operator. Selecting all objects (mesh or otherwise) and armatures.

When used successfully the selected asset should exhibit no change in appearance, but should export to glTF correctly. In more extreme cases, normalization may alter or break the asset instead in which case manual correction of the asset will be needed. The operator supports Blender’s undo/redo so if normalization fails ctrl+z should be your goto.

_images/normalize_props.png

Operator properties are described in the function signature below.

bpy.ops.object.normalize_armature_relationships(fix_parent_type=True, apply_scale=True)

Attempt to reduce unusual transforms on meshes and objects rigged with an armature.

Parameters

  • fix_parent_type (bool) – When an object has a parent which is an armature, but the object’s parent type is flagged as ‘OBJECT’, this can cause issues in some cases. Enable this option to detect and fix this issue. Defaults to True

  • apply_scale (bool) – Apply the armature objects scale. Should maintain size, but make scale value (1,1,1). Defaults to True

glTF AnimEngine Markup

glTF markup tools markup a Blender scene and it’s objects with additional information about how it should be loaded in AnimEngine.

Note

Markup tools create custom data on Blender objects which are later read by AnimEngine. In order for this data to be written to exported glTF files the option to include Custom Properties must be enabled in the glTF export add-on as shown below. From more information about exporting Blender scenes for AnimEngine see Exporting assets and scenes from Blender.

_images/custom_properties.jpg

glTF Markup Animation Action

The glTF format supports animation through actions representing a specific set of keyframed properties. glTF files may contain many actions potentially animating the same object(s) multiple ways. However, glTF does not store information about which actions to play or when to play them. Likewise in order to prevent chaos upon loading of a glTF scene, AnimEngine cannot play all animations by default. To workaround this limitation, this utility and the corresponding glTF extras extension ExpandedAnimationControlExt were created to provide information about exported animations.

In order to ensure animated characters are similarly animated within AnimEngine, the glTF Markup Animation operator under the Objects menu should be used. The operator is applied to selected objects, and will also affect parents and/or children of selected objects depending on the Relationship Mode. Affected objects will be marked such that their current Blender action is flagged in the glTF as either enabled or disabled and will be played by AnimEngine accordingly.

bpy.ops.anim.gltf_markup_action(relations_mode='ARMATURE', mark_type='ENABLED')

Mark actions as enabled or disabled

Parameters

  • relations_mode (RelationsEnum*) – Specify whether or not to apply this operator to the parents and/or children of the selected objects as well. Ignored outside of 3D view context.

  • mark_type (MarkTypeEnum*) – Marking actions as enabled will flag them within exported glTF so that the CSC 572 base-code will enabled them by default.

RelationsEnum(

  • 'NONE': Only mark selected objects

  • 'ARMATURE': Mark action on selected object and its parent only if the parent is an armature

  • 'PARENTS': Traverse parents of selected objects

  • 'CHILDREN': Traverse children of selected objects

  • 'BOTH': Traverse both children and parents of selected objects)

MarkTypeEnum(

  • 'CLEAR': Remove all markup data for selected objects

  • 'ENABLED': Enable current action of all selected

  • 'DISABLED': Disable current action of all selected

glTF Many Lights Compatibility

The add-on provides additional support for many light’s global illumination rendering in AnimEngine via the GlobalIlluminationFlags extras extension. This utility allows for the flagging of objects for rendering with or without global illumination, and for the creation of many lights point lights.

Mark Many Lights Globally Illuminated Operator

This operator marks or unmarks the selected objects as entities which should be rendered with global illumination through many lights. It can be found in the 3D viewport under Object → Mark many light illuminated

Mark Many Lights Point Light Operator

This operator marks or unmarks selected point lights as point lights to be used by many light rendering. Non-point light objects are ignored by this operator. It can be found in the 3D viewport under Object → Mark many lights point light

Add Many Lights Point Light Operator

This operator directly adds a many lights point light into the scene. It can be found under the add object menu lights section.