Documentation of the AdvanceMAME scripts.

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

1 Grammar

The scripts use a C-like grammar.

2 Scripts

These are the available scripts:

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

3 Values

You have two types of values: numerical integer values and text string values.

The numerical values are expressed with the following formats:

The text values are expressed with the following format:

Examples:

4 Operators

The values can be combined in expressions using some operators.

For numerical values the following operators are available:

For string values the following operator is available:

5 Commands

These are the available 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 other 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 not 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 stops the emulation and you can't exit from the program. A correct one is:

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

6 Functions

These are the available functions:

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

7 Ports

External devices can be controlled using the keyboard leds or the PC ports, like the parallel port.

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

This is the complete list of all the predefined symbols available.

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

This script clears all the keyboard leds at the emulation end:

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

Activate all the parallel data bits when the game starts, flash the bit 0 during the emulation and clear them when the game stops:

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 second 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 starts:

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

Display continuously the game speed on the LCD:

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

10 Configuration

The scripts must be inserted in the `advmame.rc` file. You can split complex scripts terminating any split row with the `\` character.

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); \
    }