Background Events

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

In EX-XDRiVER, the importance of background events are often overlooked, as the camera and track motions that compose mods typically steal the spotlight. Despite this, background events are very important. A chart with mods but no background events may still feel as if it is missing something.

In XDRV, background events take a variety of forms. One common type of background event is the manipulation of alpha values (opacities) of visual elements in the background. Similarly, background events can be used to change the alpha values of UI components and the intensity and diffusion of bloom. Many backgrounds have additional, more specialized events. Whether it be visual overlays or moving components, the background you pick for your chart determines what background events you’ll have access to.

Play

---

Writing Background Events

Which background you use is not the only decision behind background events, however. Before you write any background events, you can decide whether to write your events directly into the .xdrv file or into the .lua file with function calls. Both approaches have pros and cons.

Method 1: .xdrv Events

To write background events directly into a .xdrv file, you must open the file and navigates to the beat (the line of notes at that beat) that you want the event to occur at. You must then create a #EVENT line above the beat, populating it with the necessary information for the mod to work.

#EVENT

#EVENT=EventName,AdditionalParameters...

Performs a background event at the next beat subdivision in the .xdrv file.

Parameters:

• EventName: The name of the event to call.
• AdditionalParameters: A sequence of additional parameters. The type and quantity of these parameters depends on which event (and therefore, which event name) is being called.
  • Check the XDRV Background Documentation for this information.

All together, an event timing segment within a chart looks like this:

--
// B100
010-010|00|0
#EVENT=EasePathAlpha,0.5,1,false,InOutQuad
010-010|00|0 // background event starts here
--

This event eases the background’s path alpha to 0.5 using an InOutQuad ease function. The event starts at beat 100.5 and lasts 1 beat, ending at beat 101.5.

Noteless Background Events

If you want an event to start at a beat value where no notes exist, you can add empty note lines to break the beat up into smaller subdivisions, ensuring that you do not accidentally change the timing of the notes, and then add the event in the desired place.

--
// B100
010-010|00|0
000-000|00|0 // empty line
000-000|00|0 // empty line
#EVENT=EasePathAlpha,0.5,1,false,InOutQuad
000-000|00|0 // empty line, background event starts here
--

The event now starts at B101.75, even though no notes exist at that beat.

Method 2: .lua Events Recommended

If you would rather add their events to your modfile as opposed to your .xdrv file, you can do so using function calls. In specific, the xdrv.RunEvent function allows you to execute any supported background event from within your .lua modfile.

xdrv.RunEvent

xdrv.RunEvent(eventName, beatOrTime, timeValue additionalParameters...)

Performs a background event at a particular beat or time.

Parameters:

• eventName: string
  • The name of the event to call.
• beatOrTime: string
  • Whether to measure timeValue as "beat"s or "time" in seconds.
• timeValue: number
  • The beat or time in seconds to start the background event at, depending on what beatOrTime is.
• additionalParameters…
  • A sequence of additional parameters. The type and quantity of these parameters depends on which event (and therefore, which event name) is being called.
  • Check the XDRV Background Documentation for this information.

An event call within a .lua modfile looks like this:

xdrv.RunEvent("EasePathAlpha","beat",100.5,0.5,1,false,"InOutQuad")
-- Eases the background path alpha to 0.5
-- Starts at beat 100.5 and lasts 1 beat (ends at beat 101.5)
-- Follows the InOutQuad easing function.

When used in tandem with Lua functionality such as loops, helper functions, and reading note data, background events can be automated to initiate several events with only a few lines. (If you’re not sure what that functionality looks like, you should check the Lua guide in this charting guide).

Evaluating the Event Methods

Depending on your skill level and the software you use to create charts, you may find one method of creating background events more appealing than the other. Generally, if you are decently familiar with the Lua language and can write a few lines, doing background events in the .lua file is more efficient. If coding isn’t your forte, however, you may find writing background events in the .xdrv file to be more ideal. With that said, pros and cons for each method do exist:

Method One: #EVENT

Pros

• Patterns and background events are placed side-by-side
• No programming required
• Promotes simpler, less complex background events

Cons

• Automation is not possible
• Copy-pasting is required for repeated events
• Can cause background events to be disjointed from mods
• Subdivisions in the .xdrv file may need to be edited
• Can only place events at beat values

Method Two: xdrv.RunEvent

This method is recommended for those actively learning the XDRV chart design process.

Pros

• Mods and background events are placed side-by-side
• Subdivisions in the .xdrv file do not need to be edited
• Automation is possible via Lua functionality
• Copy-pasting background events can be minimized via good coding conventions (i.e. helper functions)
• Promotes more complex & intricate mods
• Can place events at beat or time values

Cons

• Requires programming
• Can cause background events to be disjointed from patterns

---

Technical Limitations

Before Trackmaker was widely adopted for XDRV charting, ArrowVortex was the main charting tool used. ArrowVortex had rudimentary support for creating, cloning, and editing background events. Trackmaker, in comparison, does not offer full support for background event editing.

Since Trackmaker edits the .xdrv file as opposed to the modfile, it may become more viable to add events directly to a chart file in the future. For now, however, it’s best to learn how to do background events in Lua, since it’s the standard approach and supports the most automation.

Example File

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

mods.lua

-- Events example file!

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

-- At beat zero, ease the left and right path alpha to 0
xdrv.RunEvent("EaseLeftPathAlpha","beat",0,0,2)
xdrv.RunEvent("EaseRightPathAlpha","beat",0,0,2)

-- At beat 4, turn on left alpha
xdrv.RunEvent("EaseLeftPathAlpha","beat",4,1,0.125)

-- At beat 5, turn on left alpha and off right alpha
xdrv.RunEvent("EaseLeftPathAlpha","beat",5,0,0.125)
xdrv.RunEvent("EaseRightPathAlpha","beat",5,1,0.125)

-- At beat 6, set left and right alpha to same value
xdrv.RunEvent("EaseLeftPathAlpha","beat",6,0.75,0.125)
xdrv.RunEvent("EaseRightPathAlpha","beat",6,0.75,0.125)

-- At beat 7, enable bloom beat and recording overlay
xdrv.RunEvent("SetRecordingOverlayState","beat",7,true,1)
xdrv.RunEvent("EnableBloomBeat","beat",7)

-- At beat 10, disable recording overlay
-- Also fade static overlay in, disable bloom beat, and lower background and building brightness
xdrv.RunEvent("SetRecordingOverlayAlpha","beat",10,0,3)
xdrv.RunEvent("SetStaticOverlayAlpha","beat",10,0.5,3)
xdrv.RunEvent("DisableBloomBeat","beat",10)
xdrv.RunEvent("EaseLightBrightness","beat",10,0,0.25)
xdrv.RunEvent("EaseLeftPathAlpha","beat",10,0.25,0.25)
xdrv.RunEvent("EaseRightPathAlpha","beat",10,0.25,0.25)

-- At beat 13, set the static overlay to invisible
-- For our purposes, this is where the modfile ends :]
xdrv.RunEvent("SetStaticOverlayAlpha","beat",13,0)

---

Knowing how to create background events is a great place to start. Creating interesting background events for a chart can make the chart feel more full and impactful. With that in mind, knowing the most optimal way to use different types of background events is a challenge in of itself; this challenge will discussed in the next section.