Mods

Recommended Precursors

• Finished set up for a .xdrv chart (file organization, metadata, and timing)
• Finished set up for .xdrv modding (.lua file created and linked)
• Started/finished patterning for a .xdrv chart
• Familiar with the Lua language

While background events can improve the emphasis and fullness of a chart, track and note mods are how XDRV charts truly get their visual identity. Unlike background events, which can be added to either the .xdrv file or the .lua modfile, mods can only be done in the modfile via Lua programming.

In XDRV, mods can manipulate a variety of different fields in your chart. The most common values for charts to manipulate are camera motion, track speed, and track motion / scale. Many more unique fields can also be modded, including the scale and position of certain note types, the opacity and color of certain track elements, the field of the view of the camera, and more.

Play

---

Writing Mods

Although a variety of mods exist for charters to manipulate, all mods can be controlled using just two functions: xdrv.Set and xdrv.Ease.

Setting Mod Values

The first of these two modding functions, xdrv.Set, sets the value of a moddable field at a specified time. Set mods have no easing or duration, meaning that a field’s value will change within a single frame. The set function can also be used to set values before the scene is visible.

xdrv.Set

xdrv.Set(modName, value, beatOrTime, time)

Sets the value of a moddable field at a given time.

Parameters:

• modName: string
  • The name of the moddable field to set.
• value: number
  • The value to set that field to.
• beatOrTime: string
  • Whether to measure timeValue as "beat"s or "time" in seconds.
• timeValue: number
  • The beat or time in seconds to apply the mod at, depending on what beatOrTime is.

In application, set mods in a .lua modfile look like this:

xdrv.Set("camera_move_y",1,"beat",12)
-- At beat 12, set the y position of the camera to 1

xdrv.Set("speed",0.5,"beat",-12)
-- At time -12, set the speed of the track to 0.5
-- Time -12 is reliably before the game scene is visible, so
- it will look like the chart starts at 0.5 speed!

Per-Frame Setting

Clever charters may realize that, by using mathematical easing functions and per-frame set functions, the effect of continuous motion can be achieved with xdrv.Set alone. While using set mods this way can be useful for specialized effects like flickers, generally, ease mods are heavily preferred because:

• Eases are more optimized than repeated set calls.
• Eases are interpreted differently by XDRV’s radar system than repeated set calls.

Easing Mod Values

The second of the two modding functions. xdrv.Ease, changes a moddable field over some duration of time. Since ease mods require a start value and end value be input, seamless mods must use the same starting value as the last value the field was set to.

The rate at which this value changes is determined by the ease function applied to it. A variety of eases of In, Out, and InOut varieties are supported by XDRV. A list of the supported eases can be found on the XDRV chart documentation.

Mod Name	(Typical) Effect
Linear	Rate of change is constant throughout.
InEASE	Rate of change starts at zero and increases throughout the motion.
OutEASE	Rate of change starts higher and decreases to zero throughout the motion.
InOutEASE	Rate of change starts at zero, increases until halfway through the motion, and decreases back to zero by the end.

Alternatively, a graphical representation of most eases supported by XDRV can be seen on this easing function resource.

xdrv.Ease

xdrv.Ease(modName, startValue, endValue, beatOrTime, startTime, lenOrEnd, endTime, easeType)

Eases the value of a moddable field over a certain duration of time.

Parameters:

• modName: string
  • The name of the moddable field to ease.
• startValue: number
  • The value to start that ease at.
• endValue: number
  • The value to end that ease at.
• beatOrTime: string
  • Whether to measure startTime and endTime as "beat"s or "time" in seconds.
• startTime: number
  • The beat or time in seconds to start the ease at, depending on what beatOrTime is.
• lenOrEnd: string
  • Whether to measure endTime as a "len" (length) or "end" value.
• endTime: number
  • The length or end of the ease in beats or seconds, depending on beatOrTime AND lenOrEnd.
• easeType: string
  • The type of ease to use.

Ease mods in a .lua modfile look like this:

xdrv.Ease("camera_move_y",0,1,"beat",12,"len",2,"InOutQuad")
-- Ease the y position of the camera from 0 to 1.
-- Starts easing at beat 12 and has a length of 2 beats (ends at beat 14).
-- Follows the InOutQuad easing function.

xdrv.Set("speed",0.5,1,"beat",0,"end",4,"InSine")
-- Ease the speed of the tracks from 0.5 to 1.
-- Starts easing at beat 0 and ends at beat 4 (has a length of 4).
-- Follows the InSine easing function.

Easing Defaults

In EX-XDRiVER, if the ease field is omitted from an ease or background event function call, the easing function of the mod will default to “InOutSine”.

Example .lua File

The video at the top of the page uses the following modfile to achieve its mods:

mods.lua

-- Mods example file!

-- Before the chart starts, set the UI alpha to 0
xdrv.RunEvent("SetUIAlpha","beat",-12,0)

-- At beat 4, bring the camera up
xdrv.Ease("camera_move_y",0,0.9,"beat",4,"len",0.75,"InOutQuad")

-- At beat 5, bring the camera down
-- Use additional mods to make the camera feel less claustrophobic
xdrv.Ease("camera_move_y",0.9,-0.1,"beat",5,"len",0.75,"InOutQuad")
xdrv.Ease("camera_move_z",0,-0.1,"beat",5,"len",0.75,"InOutQuad")
xdrv.Ease("camera_rotate_x",0,-6,"beat",5,"len",0.75,"InOutQuad")

-- At beat 6, bring the camera back to zero position
xdrv.Ease("camera_move_y",-0.1,0,"beat",6,"len",0.75,"InOutQuad")
xdrv.Ease("camera_move_z",-0.1,0,"beat",6,"len",0.75,"InOutQuad")
xdrv.Ease("camera_rotate_x",-6,0,"beat",6,"len",0.75,"InOutQuad")

-- At beat 7, make the left track bounce out
xdrv.Ease("trackleft_move_x",0,-0.8,"beat",7,"len",0.5,"OutSine")
xdrv.Ease("trackleft_move_x",-0.8,0,"beat",7.5,"len",0.5,"InSine")

-- At beat 8, make the right track bounce out
xdrv.Ease("trackright_move_x",0,0.8,"beat",8,"len",0.5,"OutSine")
xdrv.Ease("trackright_move_x",0.8,0,"beat",8.5,"len",0.5,"InSine")

-- At beat 9, make the left track 360 and bring the camera left
-- Start at 360 to end at "rest" rotation
xdrv.Ease("trackleft_rotate_z",-360,0,"beat",9,"len",1,"OutCubic")
xdrv.Ease("camera_move_x",0,-0.65,"beat",9,"len",0.75,"OutCubic")

-- At beat 10, make the right track 360 and bring the camera right
xdrv.Ease("trackright_rotate_z",360,0,"beat",10,"len",1,"OutCubic")
xdrv.Ease("camera_move_x",-0.65,0.65,"beat",10,"len",0.75,"OutCubic")

-- At beat 11, bring the camera back to the center
-- Also stretch FOV super crazy
xdrv.Ease("camera_move_x",0.65,0,"beat",11,"len",0.75,"OutCubic")
xdrv.Ease("camera_fov",100,130,"beat",11,"len",2,"InQuad")

-- At beat 13, reset the FOV to default
-- For our purposes, this is where the modfile ends :]
xdrv.Set("camera_fov",100,"beat",13)

---

As with background events, being able to write mods is a necessary skill for charters interested in making high-quality and game-ready XDRV charts. Making good mods is not just dependent on your programming skills, however; knowing how to leverage mods in a way that is visually appealing and/or challenging is a skill in of itself. Using mods optimally is the focus of the next section.