Skip to content

Flex UI

REDxEYE edited this page Nov 17, 2026 · 1 revision

From https://github.com/hisprofile/blenderstuff/blob/main/Guides/SourceIO/flex_ui.md

SourceIO for Blender - Flexes

Introduction

SourceIO's .mdl loading has been overhauled to preserve more data from an .mdl file. This includes:

  • Flex Controllers
  • Flex Expressions
  • Flex Stereo Weight Balance (the vertex mask used to separate the left and right face)
  • Wrinkle Maps

This guide aims to help you understand how these features work and how to use them in the UI.

Importing

image

Import options for the .mdl importer.

When importing with Create drivers for flexes enabled, SourceIO rebuilds the facial control scheme in Blender through a series of drivers and custom properties.

Custom properties act as flex controllers and are placed on the mesh data-block.

image image

Shape keys with drivers and the flex controllers (stored as custom properties) that control them.

Flex controllers provide an understandable interface to control the face. Because custom properties are drawn in alphabetical order, a prefix is used to help them keep their order. "aaa" is 000, "aab" is 001, and so on.

aaa_fs is always the first flex controller, and acts as a Flex Scale control to multiply the final result of the face.

Custom properties are used to simplify the share-ability of the model.

Flex Controller UI

Untitled

An example of the Flex Controller UI

The behavior of the UI is closely patterned after SFM's UI behavior. Because of UI restrictions in Blender, this behavior may confuse users.

Each flex UI controller is drawn with its value, a keyframe button, and a value viewer toggle.

When the Value Viewer is enabled, the custom property values are drawn. Default option for mono/single flex controllers.

When the Value Viewer is disabled, the Flex UI Controller is drawn instead. Default option for stereo/dual flex controllers.

Flex UI Controllers can drive one or two flex controllers at the same time, and uses a unique type of slider. Its values are purely additive, and will reset to 0.0 upon release! For Stereo Flex UI Controllers (like smiling), the value of the Left/Right balance is multiplied onto the Flex UI Controller's value and applied onto the face.

Again, Flex UI Controller values are additive. They will not retain their value in the UI, but their effect on the face will be saved unless canceled. These were specially developed to write to two other values at the same time, but not to read from them.

To the right, you have tools to:

  • Enable Auto-Keying
  • Insert a keyframe to all flex controllers on the active frame
  • Reset the face to default position

Wrinkle Maps

imageimage

First image shows the result of incorporating wrinkle maps. Second image shows the wrinkle map attribute.

When importing a supported .mdl file with Generate Wrinkle Map Nodes enabled, wrinkle map data will be reconstructed using geometry nodes and drivers. This data gets saved as an attribute named "tension" which can be used in the Shader editor.

Disabling this geometry node modifier in the viewport can improve performance.

Debug Stereo Flex Balance

When this import option is enabled, the stereo balance is not baked into the shape keys. Instead, it is saved as two distinct vertex groups named "blendleft" and "blendright". These vertex groups are then used to mask the shape keys. You may adjust these masks in Weight Paint mode.

Clone this wiki locally