In the last tutorial I walked you through discovering outputs in mame and setting up a simple function for a couple of outputs in digdug. Usually we use the function tool to help us write functions, like we did previously, but for the sake of this tutorial, we will write them manually to aid in the teaching process.

Please note that this is the most important tutorial! If you don't get this one read it over and over until you do!!!

In this tutorial we are going to use the INI you setup to explain some of the higher concepts of mamehooker. The first thing you need to do is open up the digdug.ini in mamehooker. You can do this when mame is not active by selecting "Script Editor/ Edit Specifc INI" in mamehooker's menu and then typing digdug.ini in the box that follows. You will get a display similar to the following....

[General]
MameStart=
MameStop=
StateChange=
OnRotate=
OnPause=
[Output]
led1=lws 1 16 %s%
led0=lws 1 15 %s%
[KeyStates]
RefreshTime=

Our first lesson is about the funny %s% flag added at the end of the two functions and why we used it. Many people think that the functions in mamehooker only fire when the value of an output is "on" or "1" but this isn't true. Functions defined in mamehooker's ini files fire every time the value of an output changes, so the "lws 1 16 %s%" command fires when led1 changes to 1 AND when led1 changes to 0. The lws (ledwiz set state) command needs the device number, the pin number and the value to turn on/off a pin. If the final variable would have been a 1 then the led would always be on as this command would also be passed when led1 is 0. Likewise if we had used a 0 then the led would always be off. This is where the %s% flag comes in. It is a special flag called "current output" that mamehooker replaces with the value of the output the function is binded to. So when led1 is off, or "0" the %s% flag passes a zero, turning the led off.... when led1 is "on" or "1", the %s% passes a one, turning the led on. Generally when it is appropriate, mamehooker has this as an option in the function tool, but if you need to use it an it isn't listed you can add it manually once you return to the editor. To do so, highlight any varible with the cursor and click "Add Special Flag / Current Output" from the menu. Of course you can also just type a %s% as well, but it's nice to have it as a menu item in case you forget.

Anyway, this is all well and good if you want to send the same function for each value of the output, but what if you want to send completely different functions for each value? What if, for example you are controlling a RGB led and you want a different color for the ON and Off states? Well first we better modify our ini file:

[General]
MameStart=
MameStop=
StateChange=
OnRotate=
OnPause=
[Output]
led1=lwc 1 02 48 0 0
led0=lwc 1 01 48 0 0
[KeyStates]
RefreshTime=

The functions above control a RGB led, with the variables being the device number, the pin number (starting pin only), the R value, the G value and the B value. If you learned anything from the last part you'll know that the functions defined aren't going to work. Since the same command is sent for each output value, the leds will constantly be "Red". Also a %s% flag isn't going to work seeing as how it takes a value of 48 for led wize to make a full-on red color and the only two values led1 and led0 give off are "0" and "1." So how do we fix this? With a State Break Flag. Mamehooker can send a unique function for every possible value of a output, but it need to know which functions are for which outputs... it does so with a State Break. You can add one to any function by typing a "|" or by putting your cursor at the end of a defined function and clicking "Add / StateBreak" from the menu. It's a hard concept to wrap around so let me just update our ini:

[General] MameStart=
MameStop=
StateChange=
OnRotate=
OnPause=
[Output]
led1=lwc 1 02 48 48 48|lwc 1 02 48 0 0
led0=lwc 1 01 48 48 48|lwc 1 01 48 0 0
[KeyStates]
RefreshTime=

Notice that each output now has two functions, divided by a "|" or "StateBreak." The first function furthest to the left is always the function sent when the value is 0, the next function is the one sent when the value is 1 and so on.... mamehooker can handle as many values as the output has. So now our ini will turn the RGB leds white when the outputs' value is 0 and red when the outputs' value is 1. This is how you can use unique functions for each output! Also note that the functions don't have to be the same like they are in this example, they can be totally different for each value. Just keep in mind that if you use a function to turn on a bit of hardware it won't turn off automatically unless the function defined for "0" turns it off.

But what if you are trying to do something complex with the output and need to do multiple things at once? Well for that, you use a "," or "Command Break".

Anyway.... Not to be confused with the State Break, which allows different functions for each output value, the Command Break allows for multiple functions on a single output value. What if we want to control two leds (non rgb this time, for sanity's sake) with an output? Just add two functions, divided by a "," or click "Add / Command Break" from the menu.

[General]
MameStart=
MameStop=
StateChange=
OnRotate=
OnPause=
[Output]
led1=lws 1 16 %s%,lws 1 18 %s%
led0=lws 1 15 %s%,lws 1 17 %s%
[KeyStates]
RefreshTime=

Now leds hooked up to pins 15 AND 17 are controlled by "led0" and likewise with "led1" and pins 16 and 18. It's as simple as that! You can do as many functions as you like, just keep dividing them by a comma. Also note that you can combine Command Breaks with State Breaks to send multiple and unique functions for each output value.

Now there are a few more special flags, but they are more self explanitory and are less often used. They can all be accessed via the "Add Special Flag" section of the menu. They are:

Current Rom(%rom%): Used for text-based functions, the flag %rom% is replaced by the romname of the currently playing game. Current Parent Rom(%parent%): Just like rom, but this time the parent rom is the value. Current Driver(%driver%): Again, just a flag replacement, only the driver name. Note that because a romname and driver name can be identical, a ".c" is added to the end of the driver name.

Buffers and Multipliers are too complex for this tutorial and will be handled later.

You now know how to use functions to their fullest, and thus concludes this tutorial.