Documentation of the AdvanceMAME scripts.

AdvanceMAME support a scripting language to control external device like lamps, keyboard leds... You can assign a simple script at various events like key press, game led state change or others. When the event is triggered the script is started.

1 Grammar

2 Scripts

You can assign a script at every event. The script is started when the event is triggered.

3 Values

The numerical values are expressed with the following formats:

The text values are expressed with the following formats:

Examples:

4 Operators

For numerical values the following operators are available:

For string values the following operators are available:

5 Commands

The 'wait()' and 'delay()' commands are used to maintain the synchronization with the game emulation. When these commands are executed, the script is temporarily suspended. All others commands are executed continuously without any delay.

The granularity of the delay command is the frame rate period. Approx. 16 ms for a 60 Hz game. Delays under this limit may don't have the desired effect.

IT'S VERY IMPORTANT THAT EVERY 'loop', 'while' AND 'repeat' COMMANDS CONTAIN A 'delay()' CALL. Otherwise the script may loop forever and the executable will lock! For example the statement :

loop { toggle(0, 1); }

completely STOP the emulation and you CAN'T EXIT from the program. A correct one is :

loop { toggle(0, 1); delay(100); }

6 Functions

The 'event()' command can be used to determine the end of the event that started the script. For example for the 'coin1' event the function return 0 when the key is released.

7 Ports

Generally the parallel ports are mapped at the addresses 0x378, 0x278 and 0x3bc. To maintain the same interface the keyboard leds are mapped to the virtual port 0 at the lower 3 bits. All the other ports are mapped to the PC hardware ports.

These are the available functions to read and write the ports:

In DOS the hardware ports are accessed directly. In Linux 386 they are directly accessed if you are root, otherwise they are accessed using the /dev/port interface. In Windows you cannot access the hardware ports. On other systems you can access the ports if the inb() and outb() C functions are available on your system.

8 Symbols

These are the event symbols available for the `simulate_event(EVENT, TIME)' and `event(EVENT)' commands :

These are the user interface event symbols available for the `simulate_event(EVENT, TIME)' and `event(EVENT)' commands :

These are the keyboard symbols available for the `simulate_key(EVENT, TIME)' command :

These are text symbols containing some game and emulation information:

9 Examples

script_video wait(!event()); set(0,0);

Activate all the parallel data bits when the game start, flash the bit 0 during the emulation and clear them then the game stop :

script_start \
    set(0x378, 0xff); \
    while(event()) { \
        toggle(0x378, 1); \
        delay(500); \
    } \
    set(0x378, 0);

Map the first MAME led to the first keyboard led:

script_led1 on(0, 0b1); wait(!event()); off(0, 0b1);

Map the second MAME led to the first keyboard led:

script_led2 on(0, 0b10); wait(!event()); off(0, 0b10);

Flash the third keyboard led when the 'turbo' is active :

script_turbo \
    while (event()) { \
        toggle(0, 0b100); \
        delay(500); \
    } \
    off(0, 0b100);

Light the third keyboard led when the 'coin1' key is pressed :

script_coin1 on(0, 0b100); delay(500); off(0, 0b100);

Add 3 coins automatically:

script_play \
    delay(1000); \
    repeat(3) { \
        simulate_event(coin1,100); \
        delay(200); \
    }

Add a coin when the player start:

script_start1 \
    wait(!event());
    simulate_event(coin1,100); \
    delay(500); \
    simulate_event(start1,100);

Display continously the game speed on the LCD:

script_video loop { lcd(0,"Speed " + info_throttle); delay(1000); }

10 Configuration

For example:

script_video wait(!event()); set(0,0);
script_led1 on(0, 0b1); wait(!event()); off(0, 0b1);
script_led2 on(0, 0b10); wait(!event()); off(0, 0b10);
script_coin1 on(0, 0b100); delay(500); off(0, 0b100);
script_turbo \
    while (event()) { \
        toggle(0, 0b100); \
        delay(500); \
    } \
    off(0, 0b100);
script_start1 \
    set(0x378, 0xff); \
    while(event()) { \
        toggle(0x378, 1); \
        delay(500); \
    } \
    set(0x378, 0);
script_video loop { \
        lcd(0,"Speed " + info_throttle); \
        delay(1000); \
    }