Home > Technical > How to Use MacroLua

How to Use MacroLua

August 10th, 2010 Leave a comment Go to comments

After the premieres of Super Fireball Battle and style exhibition v.one at Evo2k10, quite a few people asked me about the tool-assistance methods used to capture oldschool game clips. With a new version (1.08) of MacroLua released yesterday, i thought now would be a good opportunity to introduce the program.

Here’s the basic concept. You create a save state using any supported emulator, then you write down a sequence of inputs frame by frame in a text file. MacroLua loads that state and tells the emulator to begin running your commands from that fixed point. If you tell it to execute R.D.L.U1. then Zangief will perform an LP Spinning Piledriver in 4 frames.

There are many advantages to this method, but the most obvious one is consistency. Let’s look at a game like SF2HF where damage and dizzies are randomized. If you script a fireball on the 10th frame followed by another fireball on the 80th frame and it dizzies the opponent, then it’ll always dizzy every time you run that state/script. On the other hand, if you try the same thing using a programmable controller with two fireballs set 70 frames apart, the outcome will be random because your starting point would be random.

To begin, simply download the latest version of MacroLua and follow the installation directions. I don’t want to get into details because those steps might change in the future, but if you run into any problems that you can’t solve in ten minutes, please feel free to ask here.

MacroLua’s custom input language is intuitive. It might take you a day to get the hang of those symbols, but after that it’s easy to read and understand. All you’re doing is writing out basic controller commands one frame at a time. Here are some straightforward examples.

# SF2 Ryu HP Hadoken

# SF2 Guile LP Sonic Boom

# SF2CE Balrog walk backward vs Dhalsim walk forward
# s.LK xx LK Dash Upper, LK Dash Upper (Dhalsim dizzy), whiff HP Dash Straight
# jump forward, s.LK xx LK Dash Upper, c.LK xx LK Dash Upper, LK Dash Upper, s.HP

Obviously these assume the performing characters face right, but that’s not hard to change. Also there’s no combo counter in SF2CE, so the opponent has to start blocking at the proper time to verify that all the attacks do indeed combo. The -_D_R command takes care of that.

If a valid script doesn’t work for whatever reason, try gradually increasing the initial wait number. When dealing with fluctuating factors such as damage, dizzies, turbo speed frame skipping, projectile slowdown, etc., the outcome changes based on the starting frame.

MacroLua was coded by Dammit, who recorded those awesome VS and DDSoM scenes. It’s based on an older program called FrameMAME, coded by CrowBait. It uses an input scripting language based on Kawaks macros, further adapted by CrowBait, jchensor, NKI, and myself. If you’ve ever tried Kawaks macros, this should seem familiar – albeit much more versatile.

Categories: Technical Tags:
  1. August 11th, 2010 at 02:25 | #1

    If anyone decides to give this a try, please let me know what you think of it. If there’s enough interest in emu combo scripting, i can write more articles about advanced tips and tricks; and maybe even babble a little more about how this all came about.

  2. August 11th, 2010 at 03:36 | #2

    you should probably at least mention frame advance and savestateing as that’s as that’s what people normally mean by tool assisted and is an equally valid way to go about it.

    is cropped out of the above code, (at least at my resolution)

  3. CPS2
    August 11th, 2010 at 03:40 | #3

    Yeah I think frame advance is a lot easier to use. Still it helps to know how to use the scripts as well, it can make it easier to make small changes without having to redo a long sequence. And you can record something with frame advance, capture the input with MacroLua, then play back the macro with different backgrounds or colours… a combination of both seems like a good way to go imo.

  4. August 11th, 2010 at 04:05 | #4

    To be honest, i don’t like the frame advance method at all. I had to use it for a couple of SNES clips a long time ago and it was a chore. Especially with charge characters where it’s all about counting frames, a lot of times i had to start from scratch and it wasn’t pleasant.

    It’s definitely nice having the option to view things frame by frame, but for actually constructing combos, i prefer scripting. Not even close, like 100 to 1.

    If nothing else, scripting allows you to have the inputs written out in a legible fashion. That way you can compare, analyze, share, etc. I think it’s a huge advantage to be able to answer a question by copy/pasting a chunk of script instead of struggling to describe it, especially when it comes to charge tricks.

    error1: That’s weird, it looks fine to me. I’m at 1280×800 but it doesn’t get cropped even when i resize my browser window.

  5. August 11th, 2010 at 05:09 | #5

    I’m at 1920×1080 and it’s fine too. How compatible is this then in terms of emulators?

  6. CPS2
    August 11th, 2010 at 09:18 | #6

    If anyone wants to have a look, I wrote a guide for using frame advance a while back.

  7. shinjigohan
    August 11th, 2010 at 09:30 | #7

    lua is in several different emulators with varying degrees of compatability.

    http://code.google.com/p/macrolua/wiki/MacroLuaDocumentation at the bottom of the pages lists lua support in other emulators.

  8. August 11th, 2010 at 12:04 | #8

    CPS2: Thank you sir, that guide is awesome. It’s good to have alternatives represented because i’m sure some people will be more comfortable with that option. It’s probably just a personal preference thing, but since i don’t see myself using frame advance in the near future (unless i absolutely have to), i wouldn’t be the best person to explain it anyway. It’s more visual but to me it’s more tedious and less portable.

  9. Doopliss
    August 11th, 2010 at 13:54 | #9

    Personally I like Frame Advance, so I’m using that. Really simple to use.

  10. harejordan
    August 11th, 2010 at 18:21 | #10

    Completely off topic, but I thought this would be interesting enough to share.
    On the SF4 iPhone, Gief has +hit on green hand…(the computer hit me with an 8 hit combo, 3 shorts green hand, 3 shorts, green hand) Abel’s 2nd hit of c.hp creates a free juggle state, sooo infinite, and an assortment of other things that are different.

  11. August 11th, 2010 at 23:17 | #11

    Hey would it be possible to add some kind of safeguard against people using MacroLua during online matches? I’m not sure what would be the best way to implement something like that, but maybe a warning that both players can see? Or maybe a comment added to the replay file?

    Trying to use tool-assistance during online matches is a massive waste of time for everyone involved, especially the user. Only an idiot would resort to that and risk tarnishing their reputation forever when they get caught.

    But unfortunately, people do dumb things. Is there any way to make it obvious for everyone else’s benefit?

    (Haha can you imagine someone starting a match by saying, “Disclaimer: This is a tool-assisted match performance. En garde!”? Somehow i doubt anyone would be that honest willingly.)

    harejordan: Yeah there’s a lot of outrageously broken combos in that ghetto version. I’d watch a cell phone SF4 combovid, but all the people who threatened to make one never did. Anyway i’d rather not go off on tangents here. (Normally i like random tangents but i just want to keep this area clear for people who have questions about MacroLua.)

  12. Dammit
    August 11th, 2010 at 23:53 | #12

    The safeguard is it’s not usable in the programs used for online play. It requires a Lua framework which is not easy to set up and which developers outside of the TAS community don’t care about.

    If you could use Lua in GGPO and such, there would be much more efficient ways to cheat than this. MacroLua is strictly for combo research. =)

  13. Diggler
    August 12th, 2010 at 02:37 | #13

    Having trouble setting this up. Lua is properly installed, I extracted the package to my FBR-RR folder, having downloaded the latest one so that I could use the latest version of macro lua. I set the options, run macro lua, and nothing seems to work. Tried to follow along with the tutorial, putting the same inputs into my test.mss file, refreshing macro lua and pressing semicolon to trigger the macro. Nothing. My OS is windows 7, 64 bit. Could this be causing a problem?

  14. August 12th, 2010 at 03:00 | #14

    you need to set your hotkey in fba. Do input/configure hotkeys and set lua custom hotkey 1 to “;”. the key bindings in macro-options.lua only applies to emulators without Lua hotkeys

  15. Rufus
    August 12th, 2010 at 09:28 | #15


    In non-competitive situations, it can be amusing as a novelty. I did tool assisted demo of walk forward Sonic Booms on-line to show people they were still there. I took the SNES->Xbox adapter I’m building to Wednesday Night Fights, and people were chuckling about abusing the 30Hz turbo and slowmotion functions on the SuperAdvantage in casual play.

    Generally speaking, I don’t really see the point of putting special restrictions on MacroLua since there are other, easier, macro tools out there – for example the Alienware gaming keyboards. IMHO developer time is better spent on other things. In practical terms, it would be laughably easy to sneak a cheat stick into Evo, but AFAIK people don’t.

  16. August 12th, 2010 at 12:05 | #16

    Dammit: Dang, good answer. That takes care of my concerns. And you’re right about there being plenty of other ways people can do the same thing. Even turbo buttons are a massively unfair competitive advantage, especially when netplay lag is involved.

    Anyway now the only thing we have to worry about is people meticulously choreographing entire matchvids with MacroLua and claiming they beat Daigo. Or worse, COTA Magneto. (Like anyone would ever believe that.)

  17. Diggler
    August 12th, 2010 at 13:23 | #17

    Got it working now, thanks.

  18. phoenix
    August 12th, 2010 at 14:15 | #18

    This was really helpful, I had been trying to get Autoit to work with emulators, but it really was a big hassle, working much better now.

    I’ve been trying to script some combos for The King of Fighters 2002, and either the kof2k2 buffering system is really weird or MacroLua has some kinda of bug.

    With Mature I was trying to get a certain MAX combo to work, I tried a lot of things, but for very mysterious reasons it would not work.

    I isolated the problem I ran into by programming the following combo:

    While in MAX mode qcb D (1 hit) xx qcb C.

    Written as follows it works just fine:


    But if I place 15 wait frames behind it (or any number) Only qcb D comes out.

    Does anyone have any idea what I’m doing wrong or what is going on in kof/macrolua that this happens?

  19. phoenix
    August 12th, 2010 at 14:23 | #19

    Crap, wordpress swallowed the code becaose of the smaller than/larger than signs what I meant was these bits of code respectively.



  20. August 12th, 2010 at 14:42 | #20

    I’m having problems setting this up myself. I download the fba-rr and macrolua. I read the readme’s about how to set up the folders. I’m trying to figure this out. Do I need to create a macro folder in the fba-rr directory? If so do I have to put the .lua files in there? Also for savestates does it have to be .mis format or can I also use .fs? Any help would be great thanks.

  21. August 12th, 2010 at 15:00 | #21

    I think I understand how it works now but I still don’t get how you create a .mis file. When I do a savesate I just put it in the save state folder correct? How would I go about creating the .mis file.

  22. August 12th, 2010 at 15:04 | #22

    I figured it out. I guess you just name it what you want. Thanks anyways.

  23. August 12th, 2010 at 15:18 | #23

    apparently emulators run at a variable framerate so using autoit with one can be a lot of trouble.
    I think you will find this
    is the same as
    if you don’t put a wait after a button it essentially holds it down for 0 frames.

    you can put the files wherever you want, by default it will look for the .mis file 1 directory up in the macro folder. so you can can put in in the base directory and make a macro folder or you can put it in a lua folder and make a lua\macro folder.
    savestate is .fs
    .mis is not a savestate it’s the script file
    you shouldn’t have to worry about savestates unless you tell it to load one at the start of the script.

  24. August 12th, 2010 at 21:00 | #24

    K I’m having a new problem now. Now FBA wont load the game I want at all. It was working fine a few hours ago but now it’s just not working correctly. I’ll try to re-download it and try it again.

  25. August 12th, 2010 at 22:10 | #25

    is it giving an error, or just crashing? could it be that it somehow lost the path?

  26. August 13th, 2010 at 22:39 | #26

    I got it working again after I deleted everything and replaced it all. It just dind’t load up the game at all. It would just sit still on a black screen. It works fine now though so I don’t know why it did it. I didn’t get any error from it.

  27. phoenix
    August 15th, 2010 at 03:24 | #27


    I think you mixed it up. When I run
    qcb D xx qcb C does come out.
    When I run
    it doesn’t. So essentially it’s just the other way around. It’s almost as if the Button press doesn’t register for any frames at all if you put frames behind it.

    Even 23.w25.D.DR.R.4.w14.D.DR.R.3. does not give the cancel.

  28. August 15th, 2010 at 14:07 | #28

    it should give the same result as

  29. August 15th, 2010 at 14:07 | #29

    First of all, periods always advance one frame. If you add a period after a wait count, it adds 1 frame to the total. For instance, this causes KoF2k2 Mature to whiff standing C twice in a row:

    # KoF2k2 Mature whiff s.C, whiff s.C

    This causes her to whiff one s.C and then the second s.C fails to come out:

    # KoF2k2 Mature whiff s.C, failed s.C attempt

    This causes her to whiff s.C twice again:

    # KoF2k2 Mature whiff s.C, whiff s.C

    That’s because the period after W33 brings up the wait total to the equivalent of W34 – so if you want your pause timings to be accurate, use commas (or some other meaningless command) instead of periods after wait numbers.

    Regarding your script, i have no idea what’s going on with that first line, but it shouldn’t work at all. That last 3 basically shouldn’t get processed without a period behind it. The only explanation i can think of is that maybe you have two lines of code in your script file and they’re getting mixed up. At any rate, this works consistently for me:

    # KoF2k2 Mature MAX Activation, QCB+D (one hit) xx QCB+C

    (From the right side and only from point blank range, because the timing changes if she has to travel forward before slashing.)

  1. August 11th, 2010 at 03:01 | #1
  2. August 12th, 2010 at 00:32 | #2
  3. August 24th, 2010 at 22:54 | #3
  4. September 21st, 2010 at 23:40 | #4
  5. October 5th, 2010 at 21:13 | #5
  6. October 13th, 2010 at 11:18 | #6
You must be logged in to post a comment.