If you want to quickly learn how to create fun and fluid mods for your XDRV charts, this QUICKSTART aims to help you do just that. Modding can be time-intensive, so be prepared to spend a decent amount of time learning and carrying out the process.
To connect your chart file to a mod file, you must add a .lua file to your chart’s folder. Typical convention is to name the file the name of the chart’s difficulty, followed by “_mods.” Then, you must open the .xdrv file that you want to add mods to and fill in the MODFILE_PATH field with the name of the .lua file you created.
To write a mod file, you can use any code editor, text editor, or IDE you prefer. Most code editors have keyword coloring for Lua, though some have debuggers (either natively or via an extension). Consider the following software for making mods:
While this article assumes that you have knowledge of Lua (or are willing to learn Lua on your own), it should be stated that the most optimal structures for optimizing your mods are loops and helper functions.
If you do not know Lua and want a push in the right direction, consider reading Lua: Abridged for XDRV to learn a bit about the language. If you want to learn the whole language, consider reading from the Lua documentation.
Background events are one of the two types of visual effects that can be done in XDRV charts. Background events are responsible for changing the lighting on the sides of the track, which can be set or eased. While “PathAlpha” is a generic term for lighting control, some backgrounds have additional strings that control different, smaller parts of the background’s lighting. Additionally, many backgrounds have unique events that charts can call. For a list of specific and universal events, see the XDRV Background Documentation.
There are two ways that you can call an event in XDRV: through the .xdrv file OR through the .lua file. To call an event from a chart file, insert an #EVENT before the note row you want the event to happen at. The first parameter of this event is the name of the event, and all parameters after are specific to the event name chosen.
To call an event from a mod file, use xdrv.RunEvent(...). The first parameter of this function is the name of the event, the second is whether the timing value is measured by “beat” or “time,” and the third is the timing value when the event will happen. All parameters after are specific to the event name chosen.
Mods are the second type of visual effect possible in XDRV charts. Mods control the physical properties of objects within the game space by setting or easing their values. For most objects, physical properties of position, rotation, and scale can be altered. The most common objects for mods to alter the properties of are the camera, the tracks (both jointly and individually), the notes, and scroll speed. Many of these mods can also be applied to individual notes, though these mods are sparsely used in base-game content. For a list of mod options, see the XDRV Mod Documentation.
Mod values can be changed, either instantaneously, or gradually, using xdrv.Set(...) and xdrv.Ease(...).
xdrv.Set
xdrv.Set(modName, value, beatOrTime, time)Sets the value of a moddable field at a given time.
Parameters:
"beat"s or "time" in seconds.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:
"beat"s or "time" in seconds."len" (length) or "end" value.When it comes to XDRV modding, the principles of visually appealing mods share a lot with the principles of visually appealing animation. The four most applicable principles of animation to modding in XDRV are:
While these tools can be great for creating visually interesting mods, it is important to remember that mods can make charts harder to read. The biggest perpetrator is mod misalignments, which happen when one previous mod’s end value is not aligned with a proceeding mod’s start value. Misalignments can cause the player to momentarily lose track of elements. This issue can be mitigated by ensuring that the start and end values of mods line up.
There are many sources that you can use to get inspiration for your chart’s mods. While you should be careful not to plagiarize another creator’s work, you can always look at other players’ modcharts (both those made for and beyond XDRV), audio visualizers, and BGMs.
The process of modding for XDRV is ultimately very difficult, but it has the potential to heighten your chart’s quality and memorability.