Room related functions

The functions on this page are available by loading the room.lua extension. It is loaded by default.

level:setuprooms(beat)

Creates some helpful room events at beat beat: a Move Room event which moves the rooms to 50x 50y and scales them to 100%x 100%y and a Set Room Content Mode event that makes the rooms stretch.
beat can be omitted and they will be created at the start of the level.

Example:

level:setuprooms() -- it's that simple!

level:getroom(index)

Returns the room at index index (0-3 for regular rooms, 4 for the ontop room) in the form of an object with functions to modify values of it.

Example:

mycoolroom = level:getroom(0) -- Get the first room.
-- Now you can do stuff with it, such as
mycoolroom:movex(1, 75, 1, 'Linear')
-- to move it.
-- The function used above will be explained later.

room:movex(beat, x, duration, ease)

Moves the room to x% on the x axis at beat beat with a duration duration and ease ease.

Example:

mycoolroom:movex(4, 75, 1, 'OutExpo') -- at beat 4, move mycoolroom's x position to 75% with a duration of 1 beat and OutExpo ease

room:movey(beat, y, duration, ease)

Moves the room to y% on the y axis at beat beat with a duration duration and ease ease.

Example:

mycoolroom:movey(6, 30, 0, 'OutQuad') -- at beat 6, move mycoolroom's y position to 30% with a duration of 0 beats and OutQuad ease

room:movesx(beat, x, duration, ease)

Scales the room on the x axis to x% with a duration duration and ease ease.

Example:

mycoolroom:movesx(8, 200, 1, 'InQuint') -- at beat 8, set mycoolroom's horizontal size to 200% with a duration of 1 beat and InQuint ease.

room:movesy(beat, y, duration, ease)

Scales the room on the y axis to y% with a duration duration and ease ease.

Example:

mycoolroom:movesy(6, 150, 1, 'InQuint') -- at beat 6, set mycoolroom's vertical size to 150% with a duration of 1 beat and InQuint ease.

room:rotate(beat, rot, duration, ease)

Rotates the room to rot degrees with a duration duration and ease ease.

Example:

mycoolroom:rotate(3, 90, 0.5, 'OutSine') -- at beat 3, rotate mycoolroom to 90 degrees with a duration of 0.5 beats and OutSine ease.

room:movepx(beat, x, duration, ease)

Moves the room's pivot to x% on the x axis at beat beat with a duration duration and ease ease.

Example:

mycoolroom:movepx(4, 75, 1, 'OutExpo') -- at beat 4, move mycoolroom's x pivot to 75% with a duration of 1 beat and OutExpo ease

room:movepy(beat, y, duration, ease)

Moves the room's pivot to y% on the y axis at beat beat with a duration duration and ease ease.

Example:

mycoolroom:movepx(4, 75, 1, 'OutExpo') -- at beat 4, move mycoolroom's y pivot to 75% with a duration of 1 beat and OutExpo ease

room:move(beat, p, duration, ease)

A helper function to make creating multiple movements at once easier. p is a key-value table where the key is what function to call and the value is the parameter.

Example:

mycoolroom:move(2, {     -- at beat 2,
    x = 40,         -- move the room to 40% on the x axis,
    sy = 0.5,       -- scale the room to half its size on the y axis,
    rotate = 90,        -- rotate the room by 90 degrees, (you can also use rot!)
}, 1, 'Linear')         -- with a duration of 1 beat and Linear ease.

room:camx(beat, x, duration, ease)

Moves the room's camera to x% on the x axis at beat beat with a duration duration and ease ease.

Example:

mycoolroom:camx(4, 75, 1, 'OutExpo') -- at beat 4, move mycoolroom's camera's x position to 75% with a duration of 1 beat and OutExpo ease

room:camy(beat, y, duration, ease)

Moves the room's camera to y% on the y axis at beat beat with a duration duration and ease ease.

Example:

mycoolroom:camy(6, 30, 0, 'OutQuad') -- at beat 6, move mycoolroom's camera's y position to 30% with a duration of 0 beats and OutQuad ease

room:camzoom(beat, zoom, duration, ease)

Zooms in the room's camera to zoom%.

Example:

mycoolroom:camzoom(8, 200, 1, 'InQuint') -- at beat 8, zoom in mycoolroom's camera to 200%.

room:camrot(beat, rot, duration, ease)

Rotates the room's camera to rot degrees with a duration duration and ease ease.

Example:

mycoolroom:camrot(3, 90, 0.5, 'OutSine') -- at beat 3, rotate mycoolroom's camera to 90 degrees with a duration of 0.5 beats and OutSine ease.

room:cam(beat, p, duration, ease)

A helper function to make creating multiple movements at once easier. p is a key-value table where the key is what function to call and the value is the parameter.

Example:

mycoolroom:cam(2, {     -- at beat 2,
    x = 40,             -- move the room's camera to 40% on the x axis,
    zoom = 200,         -- zoom in the room's camera to 200%, (you can also use z!)
    rot = 90,        -- rotate the room's camera by 90 degrees, (you can also use r!)
}, 1, 'Linear')         -- with a duration of 1 beat and Linear ease.

room:xflip(beat, state)

Flips or unflips the room horizontally based on the state at beat beat.
Omit state in order to toggle it instead!

Example:

mycoolroom:xflip(2, true) -- flips horizontally at beat 2
mycoolroom:xflip(5, false) -- unflips horizontally at beat 5
mycoolroom:xflip(6) -- flips horizontally at beat 6

room:yflip(beat, state)

Flips or unflips the room vertically based on the state at beat beat.
Omit state in order to toggle it instead!

Example:

mycoolroom:yflip(2, true) -- flips vertically at beat 2
mycoolroom:yflip(5, false) -- unflips vertically at beat 5
mycoolroom:yflip(6) -- flips vertically at beat 6

room:stretchmode(beat, state)

Sets the room's stretch mode based on the state at beat beat.
Omit state in order to toggle it instead!

Example:

mycoolroom:stretchmode(2, true) -- room stretches from beat 2
mycoolroom:stretchmode(5, false) -- room no longer stretch 😔 at beat 5
mycoolroom:stretchmode(6) -- room stretch again at beat 6

room:mask(beat, filenames, fps)

Sets the room's mask to the array filenames, with an fps fps at beat beat.
You can omit filenames if you want to unset the room's mask, or you can set it to a single string if you're just using one image.
Note you still need the file extensions.

Example:

mycoolroom:mask(2, {'bg.png', 'fg.png'}, 30) -- set the room's mask to the two images 'bg.png' and 'fg.png' at beat 2
mycoolroom:mask(5, {'bg.png'}) -- set the room's mask to the single image 'bg.png' at beat 5
mycoolroom:mask(6, '') -- unset the room's mask at beat 6
mycoolroom:mask(7, 'fg.png') -- set the room's mask to the single image 'fg.png' at beat 7
mycoolroom:mask(8) -- unset the room's mask at beat 8

room:setperspective(beat, pos, duration, ease)

Sets the room's perspective to the array pos at beat beat.
pos is an array of points: {x, y}, the point's x position and y position respectively.
Points are in this order: bottom-left (default: {0, 0}), bottom-right (default: {100, 0}), top-left (default: {0, 100}), top-right (default: {100, 100}).
You can omit one coordinate from the points or an entire point.

Example:

mycoolroom:setperspective(2, { -- at beat 2,
    {20, 0}, -- move the bottom-left point to 20 on the x and 0 on the y,
    {}, -- don't move the bottom-right point at all,
    nil, -- don't move the top-left point at all,
    {80, nil} -- move the top-right point to 80 on the x and don't move it on the y,
}, 1, 'OutExpo') -- with a duration of 1 beat and OutExpo easing.

room:floatingtext(beat, text, times, x, y, size, angle, mode, showChildren, color, outlineColor, anchor, fadeOutRate)

TO-DO: this
dear god

room:settheme(beat, theme)

Set the room's theme to theme at beat beat.

Example:

mycoolroom:settheme(2, "OrientalTechno") -- set the theme to Samurai Techno at beat 2

room:setpreset(beat, preset, state)

Enable or disable the preset preset according to state.
Omit state in order to toggle it instead!
More preset options later.

Example:

mycoolroom:setpreset(2, 'rain', true) -- enable rain at beat 2
mycoolroom:setpreset(4, 'rain', false) -- disable rain at beat 4
mycoolroom:setpreset(5, 'sepia') -- enable sepia at beat 5

room:getpreset(beat, preset, property)

If property is omitted, returns whether the preset's enabled. Otherwise, returns the value of the property.

Example:

print(mycoolroom:getpreset(2.5, 'rain')) -- print whether or not the rain preset active at beat 2.5
print(mycoolroom:getpreset(3, 'rain', 'intensity')) -- print the rain preset's intensity at beat 3

TO-DO: all presets lmao

room:flash(beat, startcolor, startopacity, endcolor, endopacity, duration, ease, bg)

Flashes the room at beat beat, starting at the color startcolor with an opacity of startopacity, transitioning to a color of endcolor with an opacity of endopacity for duration beats, with ease easing.
If bg is true, it will flash in the background layer.
startcolor and endcolor are strings in hexadecimal format, like "ffffff", where the first two characters represent the red color, the next two represent green and the last two represent blue.
Omitting endcolor and endopacity will set them to startcolor and startopacity respectively.

Example:

mycoolroom:flash(2, 'ffffff', 100, nil, 0, 2, "InQuint", false) -- flash the room in the foreground at beat 2, starting at white with an opacity of 100 and ending at white with an opacity of 0, over 2 beats and with InQuint easing.

## room:pulsecamera(beat, count, frequency, strength)
Pulse the room's camera at beat `beat` for `count` times (must be at least 1), with `frequency` beats between each pulse and `strength` strength.  
`strength` must be 0, 1 or 2.

Example:
```lua
mycoolroom:pulsecamera(2, 3, 0.5, 1) -- at beat 2, pulse the camera 3 times every 0.5 beats at a strength of 1

room:showhand(beat, hand, instant, align)

Shows either the left, right or both hands at beat beat. instant dictates whether the hand(s) show up instantly or they smoothly move into view. If align is true, the hands will align with the room's visible area.
hand is a string and should either be "Left", "Right" or "Both", changing which hand is shown (or both, in the case of Both).

Example:

mycoolroom:showhand(1, 'Left', false, true) -- at beat 1, show the left hand smoothly and align it to the room's visible area

room:hidehand(beat, hand, instant, align)

Hides either the left, right or both hands at beat beat. instant dictates whether the hand(s) hide instantly or they smoothly move out of view. If align is true, the hands will align with the room's visible area.
hand is a string and should either be "Left", "Right" or "Both", changing which hand is hidden (or both, in the case of Both).

Example:

mycoolroom:hidehand(1, 'Left', false, true) -- at beat 1, hide the left hand smoothly and align it to the room's visible area

room:togglehand(beat, hand, instant, align)

Shows/hides either the left, right or both hands if they're already hidden/shown, respectively, at beat beat. instant dictates whether the hand(s) show/hide instantly or they smoothly move into/out of view. If align is true, the hands will align with the room's visible area.
hand is a string and should either be "Left", "Right" or "Both", changing which hand is shown/hidden (or both, in the case of Both).

Example:

mycoolroom:togglehand(1, 'Left', false, true) -- at beat 1, show the left hand smoothly and align it to the room's visible area
mycoolroom:togglehand(2, 'Left', true, true) -- at beat 2, hide the left hand instantly and align it to the room's visible area

room:setbg(beat, filenames, bgtype, fps, mode, sx, sy, color, filter)

If bgtype is "Image", sets the background image to filenames with fps fps, mode content mode, filter filter and colored color. Additionally, if mode is set to "Tiled", the background will scroll by sx and sy pixels per second.
If bgtype is "Color", sets the background to a solid color, color.
Valid content modes are "ScaleToFill", "AspectFit", "AspectFill", "Center" and "Tiled".
color is a string in hexadecimal format, like ffffffff, where the first two characters represent red, next two represent green, next two represent blue and the last two represent the opacity.
filenames can either be an array of strings or one string.
filter can either be "NearestNeighbor" or "Bilinear".

Example:

mycoolroom:setbg(1, {'bg.png', 'fg.png'}, 'Image', 30, 'ScaleToFill', nil, nil, 'ff0000ff') -- at beat 1, set the room's background to 'bg.png' and 'fg.png' with a fps of 30, with 'ScaleToFill' content mode and colored 'ff0000ff', or red

room:setfg(beat, filenames, fps, mode, sx, sy, color, filter)

Sets the foreground image to filenames with fps fps, mode content mode, filter filter and colored color. Additionally, if mode is set to "Tiled", the foreground will scroll by sx and sy pixels per second.
Valid content modes are "ScaleToFill", "AspectFit", "AspectFill", "Center" and "Tiled".
color is a string in hexadecimal format, like ffffffff, where the first two characters represent red, next two represent green, next two represent blue and last two represent the opacity.
filenames can either be an array of strings or one string.
filter can either be "NearestNeighbor" or "Bilinear".

Example:

mycoolroom:setfg(1, {'bg.png', 'fg.png'}, 30, 'ScaleToFill', nil, nil, 'ff0000ff') -- at beat 1, set the room's foreground to 'bg.png' and 'fg.png' with a fps of 30, with 'ScaleToFill' content mode and colored 'ff0000ff', or red

room:fade(beat, opacity, duration, ease)

At beat beat, fade the room to opacity opacity for duration beats with ease easing.

Example:

mycoolroom:fade(2, 50, 1, "OutQuint") -- at beat 2, fade the room to 50% opacity for 1 beat with OutQuint easing

room:bassdrop(beat, strength)

At beat beat, play a bassdrop effect with strength strength.
strength should be a string, either Low, Medium or High, dictating the strength of the effect.

Example:

mycoolroom:bassdrop(1, 'Medium') -- at beat 1, play a medium bass drop effect

room:shake(beat, shakelevel)

At beat beat, play a shake effect with shakelevel strength.
shakelevel should be a string, either Low, Medium or High, dictating the strength of the effect.

Example:

mycoolroom:shake(1, 'Medium') -- at beat 1, play a medium shake effect

room:invertcolors(beat, state)

Sets whether or not the room's colors are inverted at beat beat. Omit state in order to toggle it instead!

Example:

mycoolroom:invertcolors(1, true) -- invert the colors at beat 1
mycoolroom:invertcolors(2, false) -- revert the colors at beat 2
mycoolroom:invertcolors(3) -- invert the colors again at beat 3
mycoolroom:invertcolors(4) -- revert the colors again at beat 4

room:textexplosion(beat, text, color, mode, direction)

Creates a text explosion effect at beat beat, with the text text, color mode mode, direction direction and color color.
color is a string in hexadecimal format, like '000000', where the first two characters represent red, next two represent green and the last two represent blue.
mode is a string and should be either 'OneColor' or 'Random'. direction is a string and should be either 'Left' or 'Right'.

Example:

mycoolroom:textexplosion(1, 'Text', 'ff0000', 'OneColor', 'Right') -- create a text explosion at beat 1, each with the text `Text` and colored `ff0000`, or red, moving from the left to the right

room:stutter(beat, action, sourcebeat, length, loops)

Creates or removes a stutter effect at beat beat, depending on action.
action should be either Add or Cancel, with Add creating a stutter effect and Cancel cancelling it.
sourcebeat is the beat to stutter from.
length is how long each loop is, in beats.
loops is how many loops we do.

Example:

mycoolroom:stutter(2, 'Add', 1, 0.5, 4) -- create a new stutter at beat 2, with the source beat 1, length 0.5 and 4 loops
mycoolroom:stutter(3, 'Cancel', 1, 0.5, 4) -- cancel the previous stutter. note that the parameters after Cancel do not affect this in any way

level: functions

Additionally, each room-specific function can be called in the form: level:function(beat, room, ...), where room is the room's index and ... are the function parameters.
For functions that can be applied on-top, they can also be called level:ontopfunction(beat, ...).
On-top functions: setbg, setfg, flash, bassdrop, shake, xflip, yflip, floatingtext, camx, camy, camzoom, camrot, sepia, tile2, tile3, tile4, noise, glitchobstruction, hallofmirrors, hom, blackandwhite, grayscale, tilen, screentile, customscreenscroll, screenscroll.

Example:

level:sepia(1, 1, true) -- enable sepia on room 2 at beat 1
level:ontopsepia(2, true) -- enable sepia on-top at beat 2
level:sepia(3, 4) -- toggle (thus, disable) sepia on-top at beat 3