Built in functions

The functions on this page are available without loading any extensions. They provide a base that most extensions build off of.

level:init(beat)

Initializes the level, as well as all extensions. This is called automatically by the program, so you should not need to use this.

level:offset(beat)

Changes the global event offset by beat beats.

Example:

level:comment(4, 'oh wow') -- Places a comment on beat 4. :comment is available in the core extension.

level:offset(2) -- Changes the global event offset to 2. All events from this point on will be placed 2 beats later.

level:comment(6, 'haha') -- Places a comment on beat 8.

level:offset(-4) -- The beat parameter can be negative. It causes the beats to be placed earlier.

level:comment(16, 'awesome') -- Places a comment on beat 12.

level:tag(tag, func)

tag is a string and func is an omittable function.
If func is omitted, causes all events from this point onwards to have the tag tag (until changed or ended). If func is not omitted, runs it and then automatically clears the tag.

Example:

level:tag("CoolTag")
level:comment(2, "woah!", "FF0000") -- this is tagged with `CoolTag`..
level:comment(3, "hi!!", "0000FF") -- ..and so is this!

level:tag("CoolTag2", function()
    level:comment(4, "haha!!!", "00FF00") -- this is tagged with `CoolTag2`..
end)

level:comment(5, "aw.") -- ..but this is not tagged at all!

level:endtag()

Clears the tag for new events.

Example:

level:tag("CoolTag")
level:comment(2, "woah!", "FF0000") -- this is tagged with `CoolTag`..
level:endtag()
level:comment(3, "hi!!", "0000FF") -- ..but this is not!

level:durationmult(dmult)

Causes all events created after this to have their duration multiplied by dmult.

Example:

level:speed(2, 1.5, nil, 'Linear', 1) -- Explained in the Core functions part of the Wiki. Has a duration of 1.5 beats
level:durationmult(2)
level:speed(5, 1.5, nil, 'Linear', 1) -- This has a duration of 3 beats!
level:durationmult(1)
level:speed(10, 1.5, nil, 'Linear', 1) -- Back to 1.5 beats

level:getbm(beat)

Returns two numbers, beat and measure. This is calculated using existing SetCrotchetsPerBar events, and is one-indexed.

This function is not affected by level:offset().

Example:

-- This example assumes that level.rdlevel contains the events seen above.

print(level:getbm(0)) --  Prints "1, 1" in the console when main.lua is run.

print(level:getbm(7)) --  Prints "1, 8"

print(level:getbm(8)) --  Prints "2, 1"

print(level:getbm(12)) -- Prints "3, 1"

print(level:getbm(13)) -- Prints "3, 2"

level:addevent(beat, event, params)

Adds an event to the level. Most functions in extensions are based on this function.

Example:

level:addevent(4, -- The beat to place this event at
   'PulseCamera', -- The event type
   {
      rooms = level:roomtable(0), -- Please see the level:roomtable() documentation below for more info
      count = 2, -- How many times to pulse
      frequency = 1, -- How far apart the pulses will be
      strength = 1 -- Strength of the pulse
   }
)

-- Note that the above code is equivalent to this function, available in the rooms extension.
level.rooms[0]:pulsecamera(4, 2, 1, 1)
-- Most events in RD have similar shortenings, making level:addevent() really only useful for developers!

level:addfakeevent(beat, event, params)

Adds a fake event to the internal fake event table. When level:push() or level:save() is called, these events are added to the level properly through a level:fakehandler(). level:save() is called at the end of every script by default.

This function is only useful for developers, in conjunction with level:fakehandler()

Example:

--TODO

level:roomtable(room)

Converts integers, tables, and room objects to a table that can be used in an .rdlevel

Example:

rt1 = level:roomtable(1)
-- rt1 = {1}

rt2 = level:roomtable({0, 3})
-- rt2 = {0, 3}

coolroom = level.rooms[2] -- only available with the rooms extension

rt3 = level:roomtable(coolroom)
--rt3 = {2}

level:getcondensable(event_list, properties)

Returns a table of groups that based on the properties table can be condensed into one event. Only useful for developers.

Example:

-- TODO

level:mergegroup(group)

Merges a group of events generated by level:getcondensable() into one and returns it. Only useful for developers.

Example:

-- TODO

level:condenser(etype,func)

Creates a condenser for the specified event type. Only useful for developers.

Example:

-- TODO

level:fakehandler(etype,func)

Creates a fake event handler for the specified event type. Only useful for developers.

Example:

-- TODO

level:makereal(fakeevent)

Adds all fake events to the level via fakehandlers. Called by level:push(). Only useful for developers.

Example:

-- TODO

level:push(beat)

Makes all fake events real, and if provided, re-initializes the level at beat.

Example:

-- TODO

level:save(filename)

Calls level:push(), condenses events that have a condenser defined for them, saves the level to a file. Called at the end of the script by default. Only useful for developers.

Example:

-- TODO