Multi-Axis Funscripts & T-Code: A Practical Introduction

What T-code is, the 8 axes HaptiQ works with, how a T-code command reads, and what HaptiQ's multi-axis export, import and derive (Pro) really do.

Most funscripts describe one motion: a stroke position from 0 to 100 over time. Multi-axis devices can also twist, tilt, slide and vibrate, and the format that carries those extra motions is T-code. This introduction explains the eight axes, what a T-code command looks like, how it relates to an ordinary funscript, and exactly what HaptiQ does and does not do with multi-axis scripts.

Funscript vs. T-code

A .funscript is a file: a list of actions, each with a time in milliseconds and a position from 0 to 100. It describes one axis. T-code is a text command format for haptic devices. Each command names an axis, gives a value from 0 to 999 and usually an interval in milliseconds. A multi-axis script can therefore be stored either as one funscript per axis or as T-code text, and HaptiQ can convert between them.

The 8 axes

HaptiQ works with eight T-code axes:

AxisNameMotion
L0StrokePrimary linear motion
L1SurgeForward / back
L2SwayLeft / right
R0TwistRotation
R1RollRoll
R2PitchPitch
V0VibrationVibration
A0AuxiliaryAuxiliary / valve

L0 is the primary stroke axis, the one an ordinary single-axis funscript describes. The other seven describe the extra motions in the table above.

Reading a T-code command

The format per axis is the axis name, then the value (0-999), then "I" and the interval in milliseconds since the last command. For example, L0500I100 means: L0, value 500, interval 100 ms. Several axes at the same moment go on one line, separated by spaces:

L0500I100 R0300I100 V0800I100

HaptiQ maps the 0-100 funscript position scale to the 0-999 T-code range, so position 50 becomes about 500 and position 100 becomes 999. The interval is the time since the last command, and HaptiQ's parser also accepts a command without one.

A worked example

Take a one-stroke funscript with three actions: position 0 at 0 ms, position 100 at 100 ms, and back to 0 at 200 ms. HaptiQ's T-code export writes one line per timestamp:

L0000I0
L0999I100
L0000I100

The first line starts at the bottom, the second moves to the top over 100 ms, and the third returns over the next 100 ms. Values are always written with three digits, so the bottom is 000. When you export several axes, each line lists only the axes that have a keyframe at that timestamp; an axis without one keeps its last position and is left off the line. The same data as CSV has a time_ms column and an L0 column, with one row per timestamp. With several axes, an axis that has no keyframe at a given time gets an empty cell in that row.

Which format to pick depends on what reads it next. Per-axis funscript JSON keeps one standard .funscript per axis. T-code text puts every axis in one stream of commands. CSV puts every axis side by side in columns, and HaptiQ can import it back.

What HaptiQ does with multi-axis scripts

The generator makes the stroke

HaptiQ's automatic generator analyses the motion in your video with OpenCV optical flow and produces the primary stroke script: one axis, L0. It does not measure twist, roll or pitch from the video.

Deriving extra axes from the stroke

HaptiQ's multi-axis API has a derive step (Pro) that builds a secondary axis from the stroke with fixed formulas. It supports four targets:

Target axisHow /derive makes it from the stroke
R0 (twist)Follows the speed of the stroke: half the position change per second, capped at 100
V0 (vibration)Follows the change in speed (acceleration magnitude), capped at 100
L1 (surge)A copy of the stroke shifted 200 ms later, at 60 hundredths of the amplitude around 50
L2 (sway)The same copy, shifted 400 ms later
R1, R2, A0Not derived (the request is refused)

There are no settings to tune: the formulas are fixed. Treat a derived axis as a starting point made from the stroke, not as motion measured from the video.

Export and import

The multi-axis API (Pro) exports your axes in three formats: per-axis funscript JSON, T-code text, or CSV with a time_ms column plus one column per axis. It also imports T-code text or CSV and turns it back into per-axis data.

Viewing axes in the editor

In HaptiQ's editor, View → Multi-Axis Timeline shows one lane per active axis on a shared time axis, and View → Axis Configuration opens the axis selector: all 8 axes with enable/disable, a colour per axis, range sliders and invert toggles. The editor's own Download HaptiQ Script button saves the stroke script as a .funscript.

Which devices use multi-axis data

The open-hardware OSR2 and SR6 family has the most capable multi-axis motion of any consumer-accessible device. HaptiQ's device index lists the TempestVR OSR2, OSR2.1, OSR3, SR6 and SSR1 with a USB (Serial) connection and no Buttplug support, so HaptiQ does not drive them directly. You play your scripts on them from a player that talks to them over that serial connection. Our OSR2 and SR6 setup guide covers this side.

Single-axis toys, from The Handy to Bluetooth strokers, use the stroke. HaptiQ plays the stroke script on the toys it connects to directly.

A practical workflow

  1. Upload your video to HaptiQ and generate the stroke script.
  2. Clean it up in the editor: smoothing, a speed limit, range and timing (see our guide to the 14 transform plugins).
  3. With Pro, derive the secondary axes you want (R0, V0, L1 or L2) from the finished stroke.
  4. Export as T-code, CSV or per-axis funscripts, and load the result into the player that drives your multi-axis device.

Derive from the finished stroke, because the derived axes follow it: if you smooth the stroke afterwards, derive again.

Free and Pro

Generating the stroke script works on the Free plan (2 full-quality scripts, then 1 free script a month). Multi-axis T-code export, import and derive are part of HaptiQ Pro. You can create a free account to start with the stroke.

Frequently asked questions

What hardware do I need to use multi-axis T-Code scripts?

A device with motors for more than one axis, such as the open-hardware OSR2 or SR6. HaptiQ's device index lists them with a USB (Serial) connection, so you play multi-axis scripts on them from a player that talks to them over serial.

Can I play T-Code scripts on The Handy or other single-axis devices?

Single-axis devices use the stroke. In HaptiQ you play the stroke script (L0) on The Handy or a Bluetooth toy; the extra axes are for hardware that has motors for them.

How does HaptiQ decide which axes to populate in a T-Code export?

The generator makes the stroke (L0) from optical-flow motion analysis. An export includes only the axes you ask for. The Pro derive step can add R0 from the stroke's speed, V0 from its acceleration, and L1 or L2 as copies shifted 200 or 400 ms at 60 hundredths of the amplitude. R1, R2 and A0 are not derived.

Can I edit T-Code scripts after export from HaptiQ?

The stroke script opens in HaptiQ's editor, where you can edit points and run transform plugins before you derive and export. The multi-axis API (Pro) also imports T-code text or CSV back into per-axis data, and the editor's Multi-Axis Timeline shows one lane per axis.

Create a free HaptiQ account to generate a funscript from your own video.