Funscript Utils
A set of TypeScript utilities for working with .funscript files
Installation
npm i funscript-utils
Modules
Types
Contains some useful type definitions for working with funscripts
Funscript
- Contains an array of
Action
s, and aFunscriptMetadata
object
FunscriptMetadata
- Contains some basic metadata about the funscript, extracted from its actions
- For now, this is just its duration (in milliseconds) and the average intensity
Action
- The basic elements of a funscript
- 'at' value which refers to their time from the beginning of the script
-
pos
value from 0 - 100 which represents the shuttle position at that time - There are also additional options which are added by various modules in funscript-utils
FunConverter
FunConverter contains functions used to convert funscripts from one format to another.
getFunscriptFromString(funscript: String)
- Takes a raw string read straight from a .funscript file, and outputs a Funscript object with populated metadata
getIntensity(a1: Action, a2: Action)
- Gets an intensity value for an interval between two actions
- Intensity is measured in 'positional movement per half-second'
- So an intensity of 100 indicates a movement speed equivalent to moving from 0 -> 100 over 0.5 seconds
- This means that an intensity of 100 can also be thought of as 'one full stroke per second'
- For example, moving from pos=20 to pos=60 over 0.3 seconds gives an intensity value of 67
- The formula for intensity is
500 * abs(a2.pos - a1.pos) / abs(a2.at - a1.at)
addFunscriptMetadata(funscript: Funscript)
- Primarily used internally, takes in a funscript object that's been directly parsed from a string, and calculates the average intensity and duration from its actions
convertFunscriptToCsv(funscript: Funscript)
- Converts a funscript string into a csv blob for upload to the handyfeeling.com servers (to be loaded onto a Handy)
FunHalver
FunHalver contains one important function, and a variety of helper functions that it uses.
getHalfSpeedScript(funscript: Funscript, options)
- Halves the intensity of a script without changing its cadence. It will turn each 'up/down' stroke into alternating up and down strokes.
- To do this, it splits the actions up into 'action groups', which are groups of actions separated by large gaps
- Options:
- removeShortPauses: if true, when two actions share a position value and are within
shortPauseDuration
milliseconds of each other, they will be merged - shortPauseDuration: the duration threshold that two actions need to be within to be merged if removeShortPauses is true. If not set, this value is 2000 milliseconds
- matchFirstDownstroke: If true, ensures that the first downstroke in the original funscript will be matched by a corresponding downstroke in the half-speed script. This is important for matching scripts that are intended to follow a beat. If this isn't true, then the half-speed script can sometimes end up off the beat by exactly half a beat (since the actions that are being removed are the ones that originally fell on the beat)
- matchGroupEndPosition: If true, will ensure that the half-speed script's position during rests between groups will match that of the original funscript
- resetAfterPause: if true, will ensure that the first action in each group will have a position value of 100
- debugMode: If true, the function will spit out a bunch of console.log lines for debugging
- removeShortPauses: if true, when two actions share a position value and are within
FunMapper
Used to visualize funscripts in various ways.
getColor(intensity: number)
- Converts a color into an RGB couplet (as an array of three numbers from 0 - 255) based on a standard funscript heatmap color palette (originally by Lucifie)
renderHeatmap(canvas: HTMLCanvasElement, script: Funscript, options)
- Renders a funscript heatmap into a provided canvas object
- Options:
- showStrokeLength: If set to false, the funscript will be presented as a solid rectangle with a gradient of colors representing intensities. If true (or not set), the funscript's shape will correspond to stroke lengths
renderActions(canvas: HTMLCanvasElement, script: Funscript)
- Renders a funscript's actions into a provided canvas object, as a series of lines showing the action's movements
- Options:
- clear: If set to false, the canvas will not be cleared before rendering
- background: CSS string for the background color to be set (if clear has not been set to false) - defaults to #000
- timeOnlyColor: CSS string for the line color - defaults to #FFF
- lineWeight: Thickness of rendered lines - defaults to 3
- position: Time from the start of the script, in milliseconds, that should be rendered
- duration: Duration of actions that should be rendered - defaults to the full duration of the script
- onlyTimes: If set to true, the action positions will not be shown, and instead only vertical lines at each action's time will be shown using
positionColor
- onlyTimeColor: CSS string for the color of the lines indicating line time, if
onlyTimes
is set to true - defaults to rgba(255,255,255,0.2) - offset: An x/y positional offset for all rendering. Given as an object with shape
{x: number, y: number}