TAS Emulator Implementation Roadmap

== EmuLua Implementation Roadmap ==

1. Embed Lua engine + emulator-independent functions
   * Add LuaBitOp functions
   * Add print, tostring, addressof, copytable
   * Add emu.persistglobalvariables
2. Add very basic functions
   * Add emu.atframeboundary, emu.emulating
   * Add emu.framecount, emu.lagcount, emu.lagged (they should always return a raw value, with no timing hack)
   * Add emu.registerbefore (it must be called at the beginning of frame boundary)
   * Add emu.registerafter (it must be called at the end of frame boundary)
   * Add emu.registerstart
   * Add emu.registerexit (it must work on both closing a script and closing an emulator)
   * Add gui.register
3. Add very basic memory functions
   * Add memory.[read|write][byte|word|dword][signed], memory.readbyterange
      * They must be "sync-free" memory I/O functions (which doesn't count up cycle-count).
4. Add Lua GUI function (90% of the code can be copied from other TAS emulator)
5. Add joypad.get[up|down], input.get
   * If your emulator is not smart enough, you need to separate input buffer to intermediate/final.
   * joypad.get should return intermediate input rather than final input. (due to support of round-trip I/O)
   * The emulator needs a coordinate conversion function among the GUI and the game screen, for mouse support.
6. Add savestate functions
   * Add movie.rerecordcounting
   * Add movie.readonly, movie.setreadonly
   * Add savestate.save, savestate.load
   * Add savestate.registersave, savestate.registerload
   * Add savestate.savescriptdata, savestate.loadscriptdata
7. Add advanced memory functions
   * Add memory.registerread, memory.registerwrite, memory.registerexec
   * Add memory.getregister, memory.setregister
   * Add memory.isvalid
8. Add movie functions
   * Add movie.active, movie.recording, movie.playing, movie.finished, movie.mode
   * Add movie.name, movie.length, movie.rerecordcount, movie.setrerecordcount
   * Add movie.play, movie.replay, movie.stop
9. Add other functions
   * Add emu.loadrom
   * Add emu.openscript
   * Add emu.frameadvance
   * Add emu.speedmode
   * Add emu.emulateframe[fast|invisible], emu.wait, emu.redraw
   * Add joypad.peek[up|down]
   * Add input.registerhotkey
   * Add cheat functions
   * Add sound functions
   * Add peripheral support

== Emulator I/O Diagram ==

function Main()
{
    while (true)
    {
        // it can be processed on WM_KEYDOWN, as for Windows
        Joypad.IntermediateInput = ReadUserInput();

        FrameAdvance();
    }
}

function FrameAdvance()
{
    // Frame Advance cannot be nested.
    assert(Emulator.AtFrameBoundary);

    StartFrameBoundary();
    EmurateFrame();
    EndFrameBoundary();
}

function StartFrameBoundary()
{
    if (Movie.Playing()) {
        // Movie.ReadInput() returns the next movie input.
        // Movie reset should be done in Movie.ReadInput(),
        // unless the emulator has sub-frame precision.
        Joypad.IntermediateInput = Movie.ReadInput();
    }

    // Reset joypad-read flag.
    Emulator.Lagged = false;

    // Callback must not be invoked before ReadMovie(),
    // or, script cannot get any input from movie.
    Lua.InvokeCallback(CALLBACK_REGISTERBEFORE);

    // Determine final joypad state.
    Joypad.FinalInput = Joypad.IntermediateInput;

    // Movie.WriteInput() can be done in EndFrameBoundary() instead.
    if (Movie.Recording()) {
        Movie.WriteInput(Joypad.FinalInput);
    }

    // Timing to apply cheats is somewhat debatable.
    // Doing it after Lua callback allows to apply new cheats which are added by Lua.
    // On the other hand, doing it before the callback allows Lua to read modified memory value.
    // Maybe we should call it twice? It sounds a bit too redundant.
    Cheat.ApplyCheats();

    // Enter to emulation core.
    Emulator.AtFrameBoundary = false;
}

function EndFrameBoundary()
{
    // Exit from emulation core.
    Emulator.AtFrameBoundary = true;

    // Increment frame counter
    Emulator.FrameCount++;
    if (Emulator.Lagged) {
        Emulator.LagCount++;
    }

    // Invoke Lua callback.
    Lua.InvokeCallback(CALLBACK_REGISTERAFTER);

    // Update HUD after everything has been done.
    GUI.UpdateHUD();
}