QUICKSTART: Modding
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. Making modding can take some time, so be prepared to spend a decent amount of time learning and carrying out the process.
Modding Tools
Section titled “Modding Tools”To set up your chart file to read 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.
DirectoryMy_Custom_Charts
DirectorySTRUT_TheBlockiest
- audio.ogg
- HYPER.xdrv
- jacket.jpg
- HYPER_mods.lua
To create mod files, 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:
- Notepad++
- Visual Studio
- Visual Studio Code
Lua Functionality
Section titled “Lua Functionality”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 consulting Lua: Abridged for XDRV (WIP) to learn a bit about the language for XDRV modding. If you want to learn the whole language, consider reading from the Lua documentation.
Background Events
Section titled “Background Events”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 the chart file, insert an #EVENT before the line containing the note row where you want the event to happen. The first parameter of this event is the name of the event, and all parameters after are specific to the event called.
To call an event from the mod file, call 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 called.
Basic Mods
Section titled “Basic Mods”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 in the game, though these mods are sparsely used in most XDRV content. For a list of mod options, see the XDRV Mod Documentation.
To set a physical property to a certain value, call xdrv.Set(…). The first parameter is the name of the mod, the second is the value to set the mod to, the third is whether the timing value is measured by “beat” or “time,” and the fourth is the timing value when the set will occur.
To ease a physical property from one value to another, call xdrv.Ease(…). The first parameter is the name of the mod, the second and third are the starting and ending values to ease the mod between, the fourth is whether timing values are measured by “beat” or “time,” and the fifth is the timing value when the ease will start. The fifth parameter is whether the end of the ease will be determined by an exact “end” or “len,” the sixth is the timing value when the ease will end, and the seventh is what type of easing the mod will have. The easing options available in XDRV can also be read from the XDRV Mod Documentation.
Principles of Modding
Section titled “Principles of Modding”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:
- Timing and Momentum: Easing can be used to make objects feel more dynamic when linear motion would feel robotic.
- Anticipation: Easing families like “Back” and manual corrective movements can make certain movements more appealing.
- Exaggeration: An effect can often have its appeal heightened by increasing its intensity (without sacrificing readability / playability).
- Secondary action: Having multiple mods occur simultaneously or having one mod respond to the another mod makes for mods that are more dynamic.
While these tools can be great for creating visually interesting mods, it is important to remember that mods can make charts harder to read. Furthermore, some mods can cause unnecessary reading challenges for players. The biggest perpetrator is mod misalignments, which happen when the previous mod’s end point is not aligned with the new mod’s starting point. These often cause the player’s eyes to briefly lose focus. This issue can be mitigated by ensuring that the start and end values of mods line up. Another important factor is to ensure that physical properties return to their default position if they are moved out of place.
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 levels.