FollicleFX Documentation

Complete guide to professional hair grooming with FollicleFX for Blender 4.0+.

Quick Start

Get up and running with FollicleFX in 5 minutes. Watch the demo video below or follow the step-by-step guide.

Step-by-Step Guide

Download and install the EXE installer
Open Blender 4.0 or newer
Go to Edit → Preferences → Add-ons
Search for "FollicleFX" and enable it
Select a mesh object
Press N to open the sidebar, find the FollicleFX panel
Click "Create Hair System"

Installation

System Requirements

Blender: 5.0 or newer
OS: Windows 10/11 64-bit
RAM: 8GB minimum, 16GB recommended
GPU: NVIDIA GPU with CUDA support recommended for GPU-accelerated operations

EXE Installer

The recommended installation method. Run the EXE installer and it will automatically install to the correct Blender addons folder.

Manual Installation

                        1. Extract the addon zip to:
   %APPDATA%\Blender Foundation\Blender\4.2\scripts\addons\folliclefx

2. Ensure these files exist:
   - __init__.py
   - folliclefx_core.pyd (Python module)
   - folliclefx_core_lib.dll (C++ core)

3. Enable in Blender preferences
                    

Generator Tab

The Generator tab controls guide curve creation. Guides define the overall flow and direction of hair.

Distribution Methods

Random: Randomly scatter guides across the surface
Poisson Disk: Evenly distributed guides with minimum spacing
Grid: Regular grid pattern
Vertices: Place guides at mesh vertices
Face Centers: Place guides at polygon centers
Even: Uniform distribution across surface area

Generator Parameters

Parameter	Range	Description
`guide_count`	1 - 10,000	Number of guide curves to generate
`min_distance`	0.0 - 1.0	Minimum distance between guides (Poisson mode)
`guide_length`	0.1 - 10.0	Initial length of generated guides
`control_points`	2 - 32	Number of control vertices per guide
`noise_amplitude`	0.0 - 1.0	Random variation in guide placement
`random_seed`	0 - 9999	Seed for reproducible randomization

Primitive Tab (Density & Strand Shape)

The Primitive tab controls strand generation from guides and defines strand shape properties.

Density Settings

Parameter	Range	Description
`density`	1 - 10,000	Base number of strands per guide
`density_multiplier`	0.0 - 10.0	Multiplier for final strand count

Strand Shape

Parameter	Description
`cv_count`	Control vertices per strand (0 = inherit from guide)
`interpolation_radius`	How far strands spread from guides
`interpolation_variation`	Random variation in strand positions
`follow_guide`	How closely strands follow guide shape

Length Settings

Parameter	Range	Description
`length_multiplier`	0.1 - 5.0	Scale factor for strand length
`length_variation`	0.0 - 1.0	Random length variation per strand

Width & Taper

Parameter	Description
`root_width`	Strand width at root
`tip_width`	Strand width at tip
`width_variation`	Random width variation per strand
`taper_start`	Position where taper begins (0-1)
`taper_end`	Position where taper ends (0-1)
`taper_curve`	Taper curve exponent

Tip: All parameters support texture maps and expressions for spatial control. Click the texture button next to any parameter to paint a map.

Modifiers Tab

FollicleFX provides a stack of procedural modifiers that can be combined in any order. Add modifiers from the dropdown menu.

Available Modifiers

Clumping: Group strands into natural clumps
Frizz: Add natural frizz and flyaway variation
Coil: Create curls and spiral patterns
Cut: Trim strand lengths
Braid: Generate braided patterns
Loc: Create dreadlock styles
Flow Direction: Control hair flow with arrows or curves

Clumping Modifier

Groups strands into natural clumps with XGen-style hierarchical control. Supports multiple clump modes.

🎨 Before → After preview coming soon

Clumping creates natural hair groupings

Clump Modes

Use Guides: Each guide becomes a clump center
Use Clump Points: Generate N procedural clump points via K-means clustering
Use Control Maps: Hierarchical sub-clumps within parent clumps

Core Parameters

Parameter	Range	Description
`amount`	0.0 - 1.0	Overall clumping strength
`clump_radius`	0.01 - 10.0	Radius of clump influence
`clump_scale`	0.1 - 3.0	Scale factor for clump size
`variation`	0.0 - 1.0	Per-clump random variation
`num_clump_points`	1 - 1000	Number of clumps (Clump Points mode)
`seed`	0 - 9999	Random seed for reproducibility

Advanced Options

Volumize: Preserve strand thickness while clumping
Profile Curve: Control clumping intensity along strand length
Clump Noise: Add coherent noise to entire clumps
Mask Texture: Paint areas where clumping applies

Clump Noise

Parameter	Description
`clump_noise_amp`	Noise displacement amplitude
`clump_noise_freq`	Noise frequency (scale)
`clump_noise_octaves`	Noise detail level (1-6)

Frizz Modifier

Adds natural frizz, flyaway variation, and breakup to hair strands using multi-octave Perlin noise.

🌊 Before → After preview coming soon

Frizz adds natural variation and flyaways

Core Parameters

Parameter	Range	Description
`amount`	0.0 - 1.0	Frizz displacement strength
`frequency`	0.1 - 10.0	Noise frequency (smaller = larger waves)
`octaves`	1 - 8	Noise detail layers
`persistence`	0.0 - 1.0	How much each octave contributes

Profile Along Strand

Parameter	Description
`root_strength`	Frizz intensity at root (usually 0)
`tip_strength`	Frizz intensity at tip (usually 1)
`profile_curve`	Custom curve for frizz distribution

Direction Bias

Parameter	Description
`x_scale`	Frizz strength in X direction
`y_scale`	Frizz strength in Y direction
`z_scale`	Frizz strength in Z direction

Flyaway Settings

Parameter	Description
`flyaway_percent`	Percentage of strands that become flyaways
`flyaway_strength`	How much flyaways deviate from normal hair
`flyaway_lift`	Upward lift for flyaway strands
`flyaway_kink`	Kinkiness of flyaway strands

Coil Modifier

Creates curls, coils, and spiral patterns with precise control over radius, frequency, and range.

🌀 Before → After preview coming soon

Coil creates beautiful curls and spirals

Shape Parameters

Parameter	Range	Description
`radius`	0.001 - 1.0	Curl radius (primary control)
`frequency`	0.1 - 20.0	Number of coils per strand length
`phase`	0.0 - 6.28	Starting phase offset (radians)
`phase_variation`	0.0 - 1.0	Random phase offset per strand

Range Settings

Parameter	Description
`start_position`	Where coiling begins (0=root, 1=tip)
`end_position`	Where coiling ends (0=root, 1=tip)
`ramp_in`	Fade-in length at start
`ramp_out`	Fade-out length at end

Variation

Parameter	Description
`frequency_variation`	Random frequency variation per strand
`amplitude_variation`	Random amplitude variation per strand
`use_clump_phase`	All strands in same clump coil together

Cut Modifier

Trim strand length with multiple cut modes and texture map control.

Cut Modes

Percentage: Cut to percentage of original length
Absolute: Cut to absolute length value
From Tip: Remove length from tip
From Root: Remove length from root

Parameter	Description
`cut_amount`	Cut amount (0.0 - 1.0 for percentage mode)
`cut_variation`	Random length variation
`min_length`	Minimum strand length after cut
`cut_map`	Texture map for per-strand length control

Braid Modifier

Generate braided patterns with customizable strand count and tightness.

🎀 Before → After preview coming soon

Braid weaves strands into beautiful patterns

Braid Structure

Parameter	Range	Description
`strand_count`	2 - 8	Number of strands in braid
`frequency`	0.1 - 10.0	Braid weave frequency
`amplitude`	0.0 - 1.0	Braid wave amplitude
`tightness`	0.0 - 1.0	How tightly strands are woven

Range & Variation

Parameter	Description
`start_position`	Where braiding begins along strand
`end_position`	Where braiding ends along strand
`phase_variation`	Random phase offset per strand

Loc Modifier

Create dreadlock and loc styles with authentic coiled sections and natural buildup.

✨ Before → After preview coming soon

Loc creates authentic dreadlock styles

Loc Structure

Parameter	Description
`loc_tightness`	Overall tightness of the loc
`loc_thickness`	Loc thickness/diameter
`loc_variation`	Random variation in loc shape

Coil Parameters

Parameter	Description
`coil_frequency`	Frequency of tight coiled sections
`coil_amplitude`	Amplitude of coils
`coil_tightness_variation`	Variation in coil tightness

Profile Along Strand

Parameter	Description
`root_tightness`	Tightness at root (usually looser)
`mid_tightness`	Tightness in middle (usually tighter)
`tip_tightness`	Tightness at tip

Buildup Sections

Parameter	Description
`use_buildup_sections`	Enable clogged/buildup sections
`buildup_position`	Where buildup occurs along strand
`buildup_intensity`	How pronounced the buildup is
`buildup_thickness_mult`	Thickness multiplier at buildup

Flow Direction Modifier

Control hair flow direction using painted arrows or curves. Can apply to guides or strands.

Direction Modes

Arrows: Place directional arrows on UV space
Curves: Draw flow curves (Houdini-style velocity field)
Guides: Use existing guides for direction

Parameters

Parameter	Description
`strength`	Overall flow influence strength
`root_strength`	Flow influence at root
`tip_strength`	Flow influence at tip
`preserve_length`	Maintain strand length during flow
`blend_radius`	Blending between flow regions

Interpolation Modes

Nearest: Use closest arrow direction
Linear: Linear interpolation between arrows
RBF: Radial basis function (smoothest)

Advection Mode (Curves)

Parameter	Description
`use_advection`	Enable Houdini-style curve advection
`advection_steps`	Number of advection iterations
`advection_step_size`	Step size per iteration

Simulate Modifier

Physics-based hair simulation using Position-Based Dynamics (PBD). Simulates gravity, collision, and strand dynamics.

Simulation Settings

Parameter	Description
`enabled`	Enable/disable simulation
`gravity`	Gravity strength
`damping`	Motion damping factor
`stiffness`	Strand stiffness
`iterations`	Solver iterations per frame

Collision

Parameter	Description
`collision_enabled`	Enable collision detection
`collision_object`	Mesh object for collision
`collision_margin`	Collision detection margin

Guides Tab

Manage guide curves directly. Guides are the control curves that define hair flow and can be sculpted in Blender's Curves Sculpt Mode.

Guide Operations

Add Guides: Manually add guide curves by painting on the surface
Remove Guides: Delete selected guide curves
Smooth Guides: Smooth guide curve shapes
Align to Surface: Snap guides to surface normals

Surface Tab

Control how hair binds to and follows the surface mesh.

Surface Binding

Bind Method: How guides attach to surface (UV, Barycentric, Closest Point)
Follow Deformation: Hair follows mesh deformation in real-time
Surface Offset: Distance hair lifts from surface

Display Tab

Control viewport display settings for guides and strands.

Viewport Settings

Parameter	Range	Description
`max_strands`	100 - 1,000,000	Maximum strands to display in viewport

Color Modes

Solid: Single color for all strands
Random: Random color per strand
UV Mapped: Color from UV texture
Vertex Color: Color from vertex colors

Visibility Options

Show Guides: Toggle guide visibility
Show Strands: Toggle strand visibility
Debug Mode: Show performance metrics

Hair Cards Tab

Generate hair cards (strips/planes) from groomed hair for game engines and real-time rendering.

⚠️ Development Status: Hair card generator is still in active development and may produce unexpected results.

Card Generation

Parameter	Description
`card_count`	Number of hair cards to generate
`card_width`	Width of each card
`segments`	Number of segments per card
`auto_uv`	Automatically unwrap UVs

Sculpting Guides

FollicleFX integrates with Blender's native Curves Sculpt Mode for interactive grooming. Select your guides and enter Sculpt Mode to use Blender's powerful curve brushes.

Entering Sculpt Mode

Select your FollicleFX guides object
Press Tab or switch to Sculpt Mode in the mode dropdown
Use Blender's built-in curve sculpt brushes

Available Brushes (Blender Native)

Comb: Redirect curves by combing through them
Snake Hook: Pull curves along with the brush
Grow/Shrink: Extend or shorten curve length
Pinch: Pull curves together toward brush center
Puff: Push curves outward from the surface
Smooth: Reduce noise and relax curve shapes
Slide: Move curve roots along the surface
Add: Add new curves by painting
Delete: Remove curves
Density: Add or remove curves based on density

Brush Settings

Access brush settings in Blender's Tool panel (press N in the viewport):

Radius: Brush size (use F key to adjust)
Strength: Effect intensity (use Shift+F to adjust)
Falloff: How effect fades from center

Tips

Use X-Mirror in Tool Options for symmetric grooming
After sculpting guides, click Generate Hair to update strands
Hold Ctrl while brushing to invert brush effect

FollicleScript Expression Language

FollicleScript is FollicleFX's expression language for procedural hair control. Expressions are compiled to bytecode and evaluated on the GPU for real-time performance on 100k+ strands.

Quick Start

Click the ƒ button next to any parameter to open the Expression Editor.

0.8                         # Constant value
rand(index)                 # Random value per strand  
0.5 + rand(index) * 0.3     # Base + random variation

Variables

Variable	Description
`u`	UV X coordinate (0-1)
`v`	UV Y coordinate (0-1)
`x`	World X position
`y`	World Y position
`z`	World Z position
`t`	Position along strand (0=root, 1=tip)
`index`	Strand index
`count`	Total strand count
`length`	Strand length
`width`	Strand width
`clump_id`	Clump index

Constants

Constant	Value
`pi`	3.14159...
`tau`	6.28318... (2π)
`e`	2.71828...

Operators

Operator	Description
`+` `-` `*` `/`	Basic arithmetic
`^` or `**`	Power
`()`	Grouping

Comparison Operators

Operator	Description
`<` `>`	Less than, Greater than
`<=` `>=`	Less or equal, Greater or equal
`==` `!=`	Equal, Not equal

Comparisons return 1.0 for true, 0.0 for false.

Ternary Operator

condition ? value_if_true : value_if_false

Examples:

v > 0.5 ? 1.0 : 0.5         # Returns 1.0 if v > 0.5, else 0.5
rand(index) < 0.3 ? 0 : 1   # 30% chance of 0, 70% chance of 1

Functions

Random & Noise

Function	Description
`rand(seed)`	Deterministic random 0-1
`rand3(min, max, seed)`	Random in range [min, max]
`noise(x)`	1D noise
`noise(x, y)`	2D noise
`noise(x, y, z)`	3D noise

Math Functions

Function	Description
`abs(x)`	Absolute value
`sqrt(x)`	Square root
`pow(x, y)`	Power
`exp(x)`	e^x
`log(x)`	Natural logarithm
`sign(x)`	Returns -1, 0, or 1
`mod(x, y)`	Modulo
`min(a, b)`	Minimum
`max(a, b)`	Maximum

Trigonometry

Function	Description
`sin(x)`	Sine
`cos(x)`	Cosine
`tan(x)`	Tangent

Rounding

Function	Description
`floor(x)`	Round down
`ceil(x)`	Round up
`frac(x)`	Fractional part

Interpolation

Function	Description
`clamp(x, min, max)`	Clamp to range
`lerp(a, b, t)`	Linear interpolation
`smoothstep(edge0, edge1, x)`	Smooth S-curve
`select(cond, a, b)`	If cond > 0 then a, else b

Texture Sampling

Function	Description
`map(u, v)`	Sample bound texture at UV

Custom Variables

Use $varName syntax to create dynamic UI sliders:

$amount * rand(index) + $offset

This automatically creates "amount" and "offset" sliders in the UI. Up to 16 custom variables are supported.

Expression Examples

Per-Strand Randomization

rand(index)                     # Random 0-1 per strand
0.8 + rand(index) * 0.4         # Range: 0.8 to 1.2
rand3(0.5, 1.5, index)          # Random in range
clamp(rand(index), 0.2, 0.8)    # Clamped random

Gradients

v                               # Bottom to top
1.0 - v                         # Top to bottom  
u                               # Left to right

Along-Strand Effects

t                               # 0 at root, 1 at tip
1.0 - t                         # 1 at root, 0 at tip
lerp(1.0, 0.1, t)               # Taper from 1.0 to 0.1
smoothstep(0.0, 1.0, t)         # Smooth root-to-tip

Conditional Logic

v > 0.5 ? 1.0 : 0.5             # Ternary operator
select(v > 0.5, 1.0, 0.5)       # Same using select()
index < 100 ? 0.8 : 1.0         # First 100 strands different

Center/Edge Falloff

1.0 - abs(u - 0.5) * 2.0        # Dense in center
abs(u - 0.5) * 2.0              # Dense at edges

Patterns

sin(u * tau) * 0.5 + 0.5        # Sine wave (0-1)
sin(v * tau * 2) * 0.5 + 0.5    # Vertical stripes

Noise Variation

noise(u * 10, v * 10)           # Organic pattern
noise(u * 5, v * 5, index)      # 3D noise with strand variation

Per-Clump Variation

rand(clump_id)                  # Random per clump
0.5 + rand(clump_id) * 0.5      # Clump strength variation

Tips & Best Practices

Use index for per-strand randomization — rand(index) gives each strand a unique but consistent value.
Use t for along-strand effects — Perfect for tapering, where t=0 is root and t=1 is tip.
Use clump_id for per-clump variation — Makes each clump behave slightly differently.
Use ternary for conditionals — condition ? a : b is cleaner than select().
Use smoothstep for natural transitions — Smoother than linear interpolation.
Clamp extreme values — clamp(rand(index), 0.2, 0.8) avoids outliers.
Custom variables for tweaking — Use $varName to create sliders you can adjust in real-time.

Performance Tip: Expressions are compiled to GPU bytecode and cached. Complex expressions with many function calls may impact real-time performance on very high strand counts (500k+).

Rendering & Strand Attributes

FollicleFX exports per-strand attributes that can be accessed in any render engine that supports curve attributes (Cycles, Arnold, RenderMan, etc.).

Available Attributes

These attributes are automatically created on the curves object and can be accessed via the Attribute node in your shader:

Attribute Name	Type	Description
`uv`	Float2	UV coordinates at strand root (u, v)
`clump_id`	Float	Which clump the strand belongs to (raw ID)
`clump_id_normalized`	Float	Normalized clump ID (0-1 range) for easier shader use
`random_value`	Float	Per-strand random value (0-1) for color/width variation
`melanin`	Float	Per-strand melanin value for realistic hair color
`is_flyaway`	Float	Flyaway flag (0 or 1) - marks strands designated as flyaways
`surface_uv`	Float2	Barycentric UV coordinates for surface binding (if available)

Note: Some attributes like surface_uv are only available when surface binding data is present. The clump_id_normalized is computed automatically from clump_id for easier use in shaders (0-1 range instead of raw IDs).

Using Attributes in Cycles

In Cycles shader editor:

Add an Attribute node
Enter the attribute name (e.g., random_value)
Connect the output to your shader parameters

Example: Random color per strand
Attribute (random_value) → ColorRamp → Principled BSDF (Base Color)

Example: Different color per clump
Attribute (clump_id_normalized) → ColorRamp → Principled BSDF (Base Color)

Example: Highlight flyaways
Attribute (is_flyaway) → Mix Shader (Factor) → Different materials

Example: Melanin-based hair color
Attribute (melanin) → ColorRamp → Principled Hair BSDF (Melanin)

Exporting Attributes

Attributes are automatically created when you generate hair. To manually refresh attributes:

Select your hair curves object
In the FollicleFX panel, click Export Strand Attributes

Render Engine Compatibility: These attributes work with any render engine that supports curve attributes, including Cycles, Arnold, RenderMan, Octane, and V-Ray.

Export & Import

Export Formats

Access export via File → Export → FollicleFX Hair or the panel button.

FollicleFX Binary (.ffx)

Native binary format - fast and compact. Best for archiving and transferring between FollicleFX projects.

FollicleFX ASCII (.ffxa)

Human-readable text format for debugging and manual inspection. Larger file size but useful for troubleshooting.

USD (.usd / .usda)

Universal Scene Description - industry standard format. Compatible with Houdini, Maya, and modern pipelines.

OBJ Polylines (.obj)

Simple polyline format for maximum compatibility with other applications.

Export Options

Option	Description
Include Guides	Export the guide curves (control curves)
Include Strands	Export the generated hair strands
Include Attributes	Export per-strand attributes (width, color, clump_id, UV, etc.)
Scale	Scale factor for export (default 1.0)

Coordinate Systems

Choose the coordinate system matching your target application:

Preset	Applications
Y-Up Right-Handed	Blender, Maya
Z-Up Right-Handed	3ds Max
Y-Up Left-Handed	Unity
Z-Up Left-Handed	Unreal Engine

Import Formats

Access import via File → Import → FollicleFX Hair.

FollicleFX (.ffx, .ffxa) - Native formats with full attribute support
USD (.usd, .usda, .usdc) - Universal Scene Description

Strand Cache (.ffxcache)

FollicleFX uses a high-performance binary cache format for fast strand reload:

Target: <50ms load time for 100,000 strands
Automatic caching during generation
Uses LZ4 compression for minimal file size
Stores positions, widths, colors, and custom attributes

Need Help? Contact support@folliclefx.com or check the GitHub repository for updates.