===============================================================================

GanzoFX - Procedural chain rigs and snap-in sockets for any bone

Version 1.2.0 | Auron3D | GPL-3.0-or-later

===============================================================================

GanzoFX builds two kinds of rigs on top of the bones you already have:

CHAIN A chain of bones (tail, tentacle, hose, cable, neck) that travels

into a channel: it slides in, follows the channel's curve and

stops at the bottom.

SOCKET A rigid part (magazine, plug, key, blade, lid) that snaps into a

socket: it aims at the socket, gets funnelled onto its axis,

slides in and stops at the seat, however sloppy the animation.

Every animation below was captured straight from the Blender viewport. The

orange box or arrow is the control the animator moves; the solid part is what

the rig does with it.

Socket - magazine into a moving gun. The LED turns green when seated.

-------------------------------------------------------------------------------

1. REQUIREMENTS

-------------------------------------------------------------------------------

Blender 4.2 LTS or newer. Tested on 4.2, 4.5, 5.1 and 5.2 LTS.

Platforms Windows, macOS and Linux. Pure Python, nothing to compile.

Dependencies None. No internet access, no telemetry, no online licensing.

License GPL-3.0-or-later. Full text ships as LICENSE in the package.

Rigs keep working without the add-on installed and with Python auto-run

disabled: every driver GanzoFX creates is a Blender "simple expression". You

can send a .blend to a render farm or a client and it plays back as is.

-------------------------------------------------------------------------------

2. INSTALLATION

-------------------------------------------------------------------------------

1. Edit > Preferences > Get Extensions

2. Arrow at the top right > Install from Disk...

3. Pick ganzofx-1.2.0.zip

4. The add-on enables itself on install.

5. The panel lives in the 3D viewport N-panel, under the GanzoFX tab.

Updating from 1.0 or 1.1: install the new zip over the old one. Rigs built

with an older version keep working; rebuild them to get the 1.2 fixes.

-------------------------------------------------------------------------------

3. QUICK START

-------------------------------------------------------------------------------

3.1 CHAIN

1. Enter Pose Mode on your armature.

2. Select the chain you want to rig, from base to tip.

3. Open the N-panel > GanzoFX tab and pick Rig Type: Chain.

4. Press Create Rig.

5. Animate it: drag the orange GZ-push arrow along its axis, or keyframe

the Depth slider in the Animation Controls panel.

3.2 SOCKET

1. Pose the part so it sits fully INSERTED in rest pose (the magazine in the

gun, the plug in the outlet). That rest position becomes the seat.

2. In Pose Mode select the part's bone. Optionally Shift-select the host

bone last, so it is the active one (the gun body, the wall...).

3. N-panel > GanzoFX > Rig Type: Socket. Check Host and Insert Axis.

4. Press Create Socket.

5. Animate the box-shaped control. Use Pull Out and Seat in the Sockets

panel to key an insertion in two clicks.

Remove Rig and Remove Socket give the original bones back, untouched.

3.3 THE DEMO SCENE

N-panel > GanzoFX > Demo > Build Demo Scene creates a NEW scene with five

animated examples (your scene is not touched). Press Play. Cameras CAM_01 to

CAM_05 frame each example. It is the quickest way to see every feature.

-------------------------------------------------------------------------------

4. THE PANEL

-------------------------------------------------------------------------------

GanzoFX Rig Type (Chain / Socket), build settings and the

Create button.

Animation Controls Chain rigs. The sliders you keyframe.

Sockets One box per socket on the active armature: its live

sliders, outputs, Seat / Pull Out and space buttons.

Demo Build Demo Scene.

Operators:

Create Rig / Remove Rig Build or remove the chain rig.

Edit Path Selects the channel curve, enters Edit Mode.

Mechanism Shows or hides the mechanism bones (debugging).

Create Socket Builds a socket on the selected bone.

Remove Socket Removes that socket only.

Seat / Pull Out Puts the socket control fully in, or just

outside the capture zone. Keys it when Auto

Keying is on.

Space buttons Switch the control's parent (Armature, Host,

Alt) WITHOUT a jump.

Build Demo Scene The five examples, in a new scene.

-------------------------------------------------------------------------------

5. CHAIN RIGS

-------------------------------------------------------------------------------

Chain - the push arrow drives the hose through a curved channel; it stops at the bottom.

5.1 BUILD SETTINGS

These are read when you press Create Rig. Changing them afterwards does

nothing until you rebuild.

Method How the existing bones follow the control system.

- Spline IK : the bones follow a curve. Smooth bending,

squash & stretch with volume preservation.

Default.

- Stretch To : a Stretch To chain between trackers. More

predictable and faster.

Fit Spline IK only. How the curve follows the controls.

- Exact : the curve passes THROUGH every control, so the

chain hugs the channel even in tight bends.

Default.

- Soft : the curve only approximates the controls

(pre-1.2 behaviour). Softer, cuts the inside of

bends.

Thrust - Follow Canal : the part already inside follows the

channel. Default.

- Stay Straight : the chain goes in straight, like a

rigid body. Sets the starting value of

the Follow Canal slider to 0.

Extra Controls Intermediate controls between base and tip. Default 3,

range 1 to 12.

Entry Points With 1, the channel is a straight editable curve parented

to the entry bone. With 2 or more, the entry bones ARE the

channel: it is a smooth curve that passes exactly through

each of them, so you shape it by posing bones.

Default 1, range 1 to 8.

Entry Parent What the entry bones hang from: Unparented (default),

Master control (GZ-root) or a Specific bone.

Parent Bone The bone for Specific bone. It cannot belong to the chain:

GanzoFX refuses a circular dependency.

Prefix Prefix for every bone and object created. Default GZ.

Path Create New (straight editable path from the tip, default)

or Use Existing (a curve you already have).

Curve The existing curve, when Path is Use Existing.

Path Depth Channel length as a multiple of the chain length.

Path Points Control points of the generated straight channel.

Rigid Thrust 1 = the base follows and the chain keeps its length

(default). 0 = the base stays put and the chain stretches.

Squash & Stretch Starting value of the Squash slider. Default 1.0.

Entry Squeeze Narrowing while crossing the entry. Default 0.

Extra Taper Additional taper on top of the mesh's own shape.

Control Size Multiplies the size of every control widget.

Hide Deform Bones Hides the chain on build so only the controls remain.

Auto Scale Drivers Thickness and volume drivers used by the sliders.

Rotation Conform Orients the chain to the channel curvature. On.

Push Control Adds the GZ-push arrow (see 5.2). On.

Limit Scale Limit Scale on the controls. Off.

Hider Empty Optional ring: chain geometry that crosses it is hidden,

so the chain disappears as it goes in. Needs a mesh

weighted to the chain.

5.2 ANIMATION CONTROLS

Every slider is a custom property on GZ-root and is keyframed like any other

property.

Depth 0 = fully out, 1 = at the bottom of the channel.

Rigid Thrust Live version of the build setting.

Aim At Entry How much the base orients towards the entry.

Follow Canal 0 = straight, 1 = the part inside hugs the channel.

Squash Amount Compression / stretch intensity.

Entry Squeeze Live narrowing at the entry.

Bend Up/Down Vertical bend.

Bend Side Sideways bend.

Thickness Global thickness.

Length Global length.

Effective Depth Read only: Depth plus the push arrow, clamped 0 to 1.

The push arrow (GZ-push) sits behind the base, on the thrust axis. Drag it

along its arrow and the chain goes in; it adds to the Depth slider. However

far you push it, the chain stops at the bottom of the channel: the clamp is a

hard stop, so overshooting in the animation never breaks the rig.

5.3 SHAPING THE CHANNEL

With one entry point press Edit Path, move the curve points, go back to Pose

Mode: the rig follows at once. With two or more, pose the entry bones; they

can carry constraints, so the channel can follow a moving character or prop.

-------------------------------------------------------------------------------

6. SOCKET RIGS

-------------------------------------------------------------------------------

How a socket behaves, from far to near:

Far The part only AIMS at the socket (Auto Aim).

Capture Its orientation blends into the socket axis and it is funnelled

onto that axis. Small sideways errors still snap in perfectly.

Inside Locked on the axis: it can only slide, and it stops at the seat

however far the control is pushed.

Socket - a sloppy hand, a perfect plug-in. The LED is driven by the Insertion output.

6.1 BUILD SETTINGS

Socket Name Used in the bone names. Empty = the part's bone name.

Host Bone the socket belongs to. Empty = the part's parent.

Selecting two bones (host active) overrides it.

Alt Parent Optional third parent space (a hand, the rig root...).

Empty = the top-most parent of the host.

Insert Axis Axis of the part's bone that points INTO the socket.

Insert Depth Travel from the mouth to the seat, as a multiple of the

part's bone length. Tunable live afterwards.

Capture Radius How far outside the mouth the part starts to align, as a

multiple of the insert depth. Tunable live afterwards.

Start Space Parent space of the control after building.

Auto Aim The part points at the socket while outside the capture

zone. Animatable afterwards.

Hide Inserted Bone Hides the original bone; it returns on removal.

Allow Twist Lets the part turn around the insertion axis once it is

in: keys, bayonet mounts, screw caps.

Twist Min / Max Turn limits. Tunable live afterwards.

Only When Seated The part cannot turn until it is fully in, like a key.

Control Size, Prefix As for chains.

6.2 SOCKETS PANEL (LIVE)

Helpers 0 = the part follows the control freely. 1 = aim,

capture, rail and seat stop are active.

Auto Aim Key it to 0 to rotate the part freely in a hand.

Insert Depth Travel from the mouth to the seat.

Capture Radius Size of the capture zone.

Twist Min / Max When the socket allows twist.

Capture Read only. 0 = free, 1 = snapped.

Insertion Read only. 0 = at the mouth, 1 = seated.

Seat / Pull Out Snap the control in or out (keys with Auto Keying).

Space Armature / Host / Alt, switched without a jump.

Capture and Insertion are made to drive other things: right-click either

value > Copy as New Driver, then paste it on an LED, a shape key, a slide

lock or a sound trigger.

Socket with twist - the key turns only once seated, and its turn opens the shackle.

Socket - long travel into a swinging sheath. The host can move freely.

-------------------------------------------------------------------------------

7. WHAT GETS CREATED

-------------------------------------------------------------------------------

Chain rig (all prefixed with your Prefix):

GZ-root Master control. Holds every animation slider.

GZ-push Push arrow on the thrust axis.

GZ-ctrl-NN The controls you shape the chain with.

GZ-entry-NN The entry points / channel waypoints.

GZ-hider Places the hider ring.

GZ-aim, GZ-thrust, GZ-mech-NN, GZ-trk-NN

Mechanism. Hidden; the Mechanism button shows them.

Socket (Prefix-Name, for example GZ-Magazine):

-ctrl The control you animate.

-space Parent switch (Armature / Host / Alt).

-seat Child of the host: where the part rests. Holds the

Capture and Insertion outputs.

-mouth, -deep, -wall, -aim, -orient, -rail, -twist, -out

Mechanism. Hidden.

The part's own bone gets one Copy Transforms constraint named "GZ Socket".

Collections: WGT_GanzoFX (widgets, hidden), GanzoFX_Internal (riders and

curves, hidden), GanzoFX_Hider (the hider ring, visible).

The armature stores manifests in the custom properties ganzofx_data (chain)

and ganzofx_sockets (sockets). Remove Rig / Remove Socket read them to undo

exactly what was done. Do not delete them by hand.

-------------------------------------------------------------------------------

8. NOTES AND LIMITATIONS

-------------------------------------------------------------------------------

* One chain rig per armature, and any number of sockets next to it.

* Select a chain from base to tip. A branching selection falls back to

spatial ordering and GanzoFX warns you.

* Armature scale: you can scale the character AFTER building, at any time.

Every length is measured live.

* A socket's part must be seated in rest pose. The host cannot be the part

itself or hang from it.

* The chain's entry Parent Bone cannot belong to the chain.

* The hider ring needs a mesh weighted to the chain; without one it is

skipped and reported.

* Build settings are read once. Everything in 5.2 and 6.2 is live.

* Do not enter Edit Mode on an armature with a rig built: remove the rig,

edit, then rebuild.

-------------------------------------------------------------------------------

9. CHANGELOG

-------------------------------------------------------------------------------

1.2.0

* New: socket twist with limits and Only When Seated (keys, bayonets).

* New: Insertion output (0 to 1) next to Capture, to drive anything.

* New: Seat / Pull Out buttons: an insertion in two clicks.

* New: Build Demo Scene with five animated examples.

* New: Fit option for Spline IK. Exact (default) makes the chain pass

through every control and hug tight bends.

* Improved: channels with several entry points are now a smooth curve

through the waypoints instead of straight segments.

* Fixed: at full depth the chain tip could leave the channel.

* Fixed: squash and entry squeeze drivers needed Python auto-run; every

driver now works with auto-run disabled.

* Tested on Blender 4.2, 4.5, 5.1 and 5.2, Windows and Linux.

1.1.0

* New: Socket rig type (auto aim, capture, rail, seat stop, parent

spaces, several sockets per armature).

* New: push arrow for chain rigs, with a hard stop at the bottom.

* Fixed: scaling the armature after building stretched the chain.

1.0.0

* First public release.

-------------------------------------------------------------------------------

10. SUPPORT

-------------------------------------------------------------------------------

Author Auron3D

Store https://superhivemarket.com/creators/auron3d

License GPL-3.0-or-later. The full text ships as LICENSE inside the

add-on package.

Include your Blender version and, where possible, a small .blend that shows

the problem.

===============================================================================