Skip to content

Documentation

Jump to bottom
moo-sama edited this page Aug 4, 2020 · 30 revisions

Setting up

TL.Attach()

TLE uses love's callbacks to test some of the conditions for it's built in triggers. This function will automatically attach all the necessary functions to love's callbacks without replacing your code. Just call this function inside of your love.load() callback. If you don't want that for whatever reason you can call the callbacks below in your own code, which mirror love's callbacks.

TL.update(...)
TL.mousepressed(...)
TL.mousereleased(...)
TL.mousemoved(...)
TL.wheelmoved(...)
TL.mousefocus(...)
TL.focus(...)
TL.resize(...)
TL.visible(...)
TL.joystickpressed(...)
TL.joystickreleased(...)
TL.joystickadded(...)
TL.joystickremoved(...)
TL.joystickaxis(...)
TL.joystickhat(...)
TL.gamepadpressed(...)
TL.gamepadreleased(...)
TL.gamepadaxis(...)
TL.keypressed(...)
TL.keyreleased(...)
TL.textinput(...)

Basic functions

timeline = TL.Do(run, [args...])

Create a new timeline (exactly as you would to the timeline constructor), but let TLE update it automatically. run must be a function or callable table. You can also pass in arguments for the run function if you like. Returns the created timeline. 

dt = TL.GetDT()

Get the time between the last frame in seconds. This value is equivalent to the dt parameter in love.update(dt) 

frame = TL.GetFrame()

Get the number of frames that have passed up to this point. 

success, results... = TL.Peek(trigger)

Peek at the results of a trigger without stopping execution. Returns a boolean success as it's first result, and whatever the if success is true then it also returns whatever the trigger returned. This function can be called outside of timelines. 

results... = TL.GetPeekResults()

Get whatever results were returned by the last TL.Peek(trigger) call. 

success = TL.DidPeekTrigger()

Get whether or not the last TL.Peek(trigger) call triggered or not. 

timeline = TL.Require(path)

Require a file and load it directly into a Timeline object.

The Timeline Object

timeline = TL(run, [args...])

Create a new Timeline. run is a function or callable table to be used for timeline execution, args... is whatever arguments you want to give to run. 

is_alive = timeline:Step()

Update a timeline. Returns a boolean true if the timeline is still running or false if the timeline has finished. 

timeline = timeline:Branch(run, [args...])

Create a new child timeline from outside of timeline execution (see TL.Event.Branch). Branches will update along with the timeline when Timeline:Step is called. The calling order of branches is the order they were added, if a branch has it's own subbranches then the subbranches will be called before the next branch in the top level. Branches created with Timeline:Branch will initialize the next time Timeline:Step is called.

Returns the branch's timeline object. 

status = timeline:GetStatus()

Get the status string of a timeline. The statuses are as follows:

  • Running when a timeline is currently in execution
  • Delegating when a timeline is running it's branches
  • Suspended when a timeline is not running, but has execution left
  • Dead when a timeline has finished execution 

is_running = timeline:IsRunning()

Returns boolean whether or not a timeline is_running or not, this includes when the timeline's status is "Delegating". 

is_done = timeline:IsDone()

Returns boolean is_done if a timeline's status is "Dead". 

has_results = timeline:HasResults()

Returns boolean has_results from a finished timeline stating whether or not the timeline's run function has returned any results at the end. 

results... = timeline:GetResults()

Return the results, if any, of a finished timeline. 

for branch in timeline:Branches()

Iterate through all of a timeline's branch Timeline objects in their respective order (does not include subbranches). 

timeline:Pause()

Pause a timeline, this will ignore any calls to Timeline:Step until the timeline is unpaused. 

timeline:Unpause()

Unpause a timeline. 

is_paused = timeline:IsPaused()

Returns boolean is_paused on whether or not a timeline has been paused. 

timeline:Die()

Kill a timeline, this will automatically kill all of a timeline's branches and subbranches as well. The timeline's status will be set to "Dead" after calling this function. 

timeline:KillBranches()

Kill all of a timeline's branches and, subsequently subbranches too. 

"Timeline" = timeline:type()

Returns the type string "Timeline" of this object.

The Event API

The event API includes all of the functions inside of TimelineEvents that MUST be called within a timeline. If you call any of the functions on this page outside of a timeline TLE will return an error.

TL.Step()

The heart of events. It's job is simple, it will stop execution for one frame, or until the next time timeline:Step() is called. 

TL.Current()

Simply returns the timeline object that is currently running. 

TL.Event.Kill([index])

Kill a timeline relative to the currently running timeline based on index. A positive index returns an error. An index of 0 will kill the current timeline. The default value for index is 0. 

TL.Event.Die()

Kill the currently running timeline. Equivelant to TL.Event.Kill(0) 

TL.Event.Branch(run)

Branch a timeline from within the timeline. Timelines created this way will initialize immediately. 

TL.Event.Wait(time)

Hold execution until the amount of time in seconds has elapsed. 

TL.Event.Suspend(steps)

Hold execution until the amount of steps have elapsed.

The Trigger API

Triggers are just another type of event with the specific purpose of waiting for certain program states to be met. See the triggers and events tutorial to know more. 

TL.Trigger.OnTimelineDone(timeline)

Hold execution until a given timeline has finished.

LOVE Triggers

These triggers are simply reflections of the LOVE's built-in events. They all follow the same format and simply return what you would expect from LOVE's usual events. However, if you pass the string "All" into the function you will get an iterator for all of the events of this type that occurred this frame.

TL.Trigger.KeyPressed([all])
TL.Trigger.KeyReleased([all])
TL.Trigger.MousePressed([all])
TL.Trigger.MouseReleased([all])
TL.Trigger.MouseMoved([all])
TL.Trigger.WheelMoved([all])
TL.Trigger.TouchPressed([all])
TL.Trigger.TouchReleased([all])
TL.Trigger.TouchMoved([all])
TL.Trigger.GamepadPressed([all])
TL.Trigger.GamepadReleased([all])
TL.Trigger.GamepadAxis([all])
TL.Trigger.JoystickPressed([all])
TL.Trigger.JoystickReleased([all])
TL.Trigger.JoystickAxis([all])
TL.Trigger.JoystickHat([all])
TL.Trigger.JoystickAdded([all])
TL.Trigger.JoystickRemoved([all])
TL.Trigger.TextInput([all])
TL.Trigger.Visible([all])
TL.Trigger.Resize([all])
TL.Trigger.MouseFocus([all])
TL.Trigger.Focus([all])

The next set of triggers are similar to the above, but will take parameters and only trigger when that particular input was given.

TL.Trigger.OnKeyPressed(key)
TL.Trigger.OnKeyReleased(key)
TL.Trigger.OnMousePressed(butt)
TL.Trigger.OnMouseReleased(butt)
TL.Trigger.OnJoystickPressed(butt)
TL.Trigger.OnJoystickReleased(butt)
TL.Trigger.OnGamepadPressed(butt)
TL.Trigger.OnGamepadReleased(butt)
Clone this wiki locally