Lua API

TAS Editor v1.0 comes with the library of 24 functions available for Lua scripts running in FCEUX emulator. With Lua scripts you can automate some aspects of TASing and even create your own tools for movie editing.

In FCEUX folder there's /luaScripts folder with /taseditor subfolder in it. There you can find examples of scripts using functions of this library.

If you don't know how to make and run Lua scripts in emulators, read Advanced Features and also refer to FCEUX Help.

Full list of functions:

taseditor.registerauto(function func)

taseditor.registermanual(function func, [string name])

bool taseditor.engaged()

bool taseditor.markedframe(int frame)

int taseditor.getmarker(int frame)

int taseditor.setmarker(int frame)

taseditor.removemarker(int frame)

string taseditor.getnote(int index)

taseditor.setnote(int index, string newtext)

int taseditor.getcurrentbranch()

string taseditor.getrecordermode()

int taseditor.getsuperimpose()

int taseditor.getlostplayback()

int taseditor.getplaybacktarget()

taseditor.setplayback(int frame)

taseditor.stopseeking()

table taseditor.getselection()

taseditor.setselection(table new_set)

int taseditor.getinput(int frame, int joypad)

taseditor.submitinputchange(int frame, int joypad, int input)

taseditor.submitinsertframes(int frame, int number)

taseditor.submitdeleteframes(int frame, int number)

int taseditor.applyinputchanges([string name])

taseditor.clearinputchanges()

taseditor.registerauto(function func)

Registers a callback function ("Auto Function") that runs periodically. The Auto Function can be registered and will be called even when TAS Editor isn't engaged.

When FCEUX is unpaused, your function will be called at the end of every frame (running 60 times per second on NTSC and 50 times per second on PAL).

When FCEUX is paused, your function will be called 20 times per second.

User can switch on/off auto-calling by checking "Auto function" checkbox in TAS Editor GUI.

Like other callback-registering functions provided by FCEUX, there is only one registered callback at a time per registering function per script. If you register two callbacks, the second one will replace the first, and the call to taseditor.registerauto() will return the old callback. You may register nil instead of a function to clear a previously-registered callback.

If a script returns while it still has registered callbacks, FCEUX will keep it alive to call those callbacks when appropriate, until either the script is stopped by the user or all of the callbacks are de-registered.

taseditor.registermanual(function func, [string name])

Registers a callback function ("Manual Function") that can be called manually by TAS Editor user. The function can be registered even when TAS Editor isn't engaged.

The Manual function doesn't depend on paused or unpaused FCEUX status. It will be called once every time user presses Run function button in TAS Editor GUI.

You can provide a new name for this button.

The Manual function cannot be run more often than TAS Editor window updates (60/50 FPS or 20FPS when emulator is paused).

In FCEUX code Manual function runs right after Auto Function.

You can use this feature to create new tools for TAS Editor. For example, you can write a script that reverses currently selected input, so user will be able to reverse input by selecting a range and clicking Run function button.

Like other callback-registering functions provided by FCEUX, there is only one registered callback at a time per registering function per script. If you register two callbacks, the second one will replace the first, and the call to taseditor.registermanual() will return the old callback. You may call taseditor.registermanual(nil) to clear a previously-registered callback.

bool taseditor.engaged()

Returns true if TAS Editor is currently engaged, false if otherwise.

Also when TAS Editor is engaged, movie.mode() returns "taseditor" string.

bool taseditor.markedframe(int frame)

Returns true if given frame is marked in TAS Editor, false if not marked.

If TAS Editor is not engaged, returns false.

int taseditor.getmarker(int frame)

Returns index number of the Marker under which given frame is located.

Returns -1 if TAS Editor is not engaged.

int taseditor.setmarker(int frame)

Sets Marker on given frame. Returns index number of the Marker created.

If that frame is already marked, no changes will be made, and the function will return the index number of existing Marker.

You can set markers even outside input range.

If TAS Editor is not engaged, returns -1.

taseditor.removemarker(int frame)

Removes marker from given frame. If that frame was not marked, no changes will be made.

If TAS Editor is not engaged, no changes will be made.

string taseditor.getnote(int index)

Returns string representing the Note of given Marker.

Returns nil if TAS Editor is not engaged.

If given index is invalid (if Marker with this index number doesn't exist), returns note of the zeroth marker.

taseditor.setnote(int index, string newtext)

Sets text of the Note of given Marker.

If given index is invalid (if Marker with this index number doesn't exist), no changes will be made.

If TAS Editor is not engaged, no changes will be made.

int taseditor.getcurrentbranch()

Returns number from 0 to 9 representing current Branch.

Returns -1 if there's no Branches or if TAS Editor is not engaged.

string taseditor.getrecordermode()

Returns string representing current recorder mode.

"All"
"1P"
"2P"
"3P"
"4P"

Returns nil if TAS Editor is not engaged.

When you want to check Recorder's read-only state, use emu.readonly().

int taseditor.getsuperimpose()

Returns number representing current state of Superimpose checkbox in TAS Editor GUI.

0 – unchecked

1 – checked

2 – indeterminate (you can interpret is as half-checked)

If TAS Editor is not engaged, returns -1.

int taseditor.getlostplayback()

Returns the number of the frame where Playback cursor was before input was changed.

If Playback didn't lose position during Greenzone invalidation, returns -1.

If TAS Editor is not engaged, returns -1.

int taseditor.getplaybacktarget()

If TAS Editor's Playback is currently seeking, returns number of target frame.

If Playback is not seeking or if TAS Editor is not engaged, returns -1.

taseditor.setplayback(int frame)

Sends Playback cursor (current frame counter) to given frame.

If given frame wasn't found in TAS Editor Greenzone, starts seeking to the frame.

If TAS Editor is not engaged, nothing will be done.

taseditor.stopseeking()

Stops Playback seeking and pauses emulation.

If Playback wasn't seeking, this function only pauses emulation.

If TAS Editor is not engaged, nothing will be done.

table taseditor.getselection()

Returns a table (array) containing numbers of currently selected frames. These numbers are sorted in ascending order.

If no frames are selected at the moment, returns nil.

If TAS Editor is not engaged, returns nil.

taseditor.setselection(table new_set)

Changes current selection to the given set of frames. Frame number in your table don't have to be sorted.

Call taseditor.setselection(nil) to clear selection.

If TAS Editor is not engaged, nothing will be done.

int taseditor.getinput(int frame, int joypad)

Returns a number representing input of given joypad stored in current movie at given frame.

If given frame is negative, returns -1.

If given frame is outside current input range, returns 0, which can be interpreted as a blank frame (no buttons pressed at this frame yet).

Joypad value must be one of the following:

0 – to get hardware commands (bit 0 = reset, bit 1 = poweron, bit 2 = FDS insert disk, bit 3 = FDS switch side)

1 – to get 1P buttons (bit 0 = A, bit 1 = B, bit 2 = Select, bit 3 = Start, bit 4 = Up, bit 5 = Down, bit 6 = Left, bit 7 = Right)

2 – to get 2P buttons

3 – to get 3P buttons

4 – to get 4P buttons

You should handle returned number (if it's not equal to -1) as a byte, each bit corresponds to one button (e.g. if bit 1 is set that means A button is pressed). Use Bitwise Operations to retrieve the state of specific buttons.

If given joypad is outside [0-4] range, returns -1.

If TAS Editor is not engaged, returns -1.

taseditor.submitinputchange(int frame, int joypad, int input)

Sends request to TAS Editor asking to change input of given joypad at given frame.

Actual movie input won't be changed until the moment you call taseditor.applyinputchanges().

Using several consecutive requests and then calling applyinputchanges() at the end, you can change several frames of current movie in one moment.

When applying the pile of requests, TAS Editor will execute them in consecutive order.

If given frame is negative, TAS Editor will ignore such request.

If given frame is outside current input range, TAS Editor will expand movie during applyinputchanges() to fit the frame.

If given joypad is outside [0-4] range, TAS Editor will ignore such request.

Given input will be treated by TAS Editor as a sequence of bits representing state of each button of given joypad (bit 0 = A, bit 1 = B, bit 2 = Select, bit 3 = Start, bit 4 = Up, bit 5 = Down, bit 6 = Left, bit 7 = Right).

If TAS Editor is not engaged, nothing will be done.

taseditor.submitinsertframes(int frame, int number)

Sends request to TAS Editor asking to insert given number of blank frames before given frame.

Actual movie won't be changed until the moment you call taseditor.applyinputchanges().

Insertion can move down some old input and Markers (if "Bind Markers to Input" option is checked by user).

If given number is less or equal to zero, TAS Editor will ignore such request.

If given frame is negative, TAS Editor will ignore such request.

If given frame is outside current input range, TAS Editor will expand movie during applyinputchanges() to fit the frame.

If TAS Editor is not engaged, nothing will be done.

taseditor.submitdeleteframes(int frame, int number)

Sends request to TAS Editor asking to delete given number of frames starting from given frame.

Actual movie won't be changed until the moment you call taseditor.applyinputchanges().

Deletion can move up some old input and Markers (if "Bind Markers to Input" option is checked by user).

If given number is less or equal to zero, TAS Editor will ignore such request.

If given frame is negative, TAS Editor will ignore such request.

If given frame is outside current input range, TAS Editor will expand movie during applyinputchanges() to fit the frame.

If TAS Editor is not engaged, nothing will be done.

int taseditor.applyinputchanges([string name])

Instantly applies the list of previously requested changes to current movie. If these requests actually modified movie data, new item will appear in History Log (so user can undo these changes), and Greenzone may become truncated, Playback cursor may lose its position, auto-seeking may be triggered.

Returns number of frame where first actual changes occurred.

If no actual changes were found (for example, you asked TAS Editor to set buttons that were already pressed), returns -1.

If pending list of changes is empty, returns -1.

You can provide a name that will be assigned to this change. This name will be shown in History Log. If you don't provide a name, TAS Editor will use default name ("Change").

After applying all requests TAS Editor clears the list of requests.

If TAS Editor is not engaged, nothing will be done.

taseditor.clearinputchanges()

Clears the list of previously requested changes, making TAS Editor forget about them before you call applyinputchanges(). Use this function to discard previously submitted input changes.

It's also recommended to call this function before making several requests in a row, so that you'll be sure that only your new changes will apply.

If TAS Editor is not engaged, nothing will be done.

Created with the Personal Edition of HelpNDoc: Full-featured EPub generator