                           ==========================
                           AdvanceMAME Script Machine
                           ==========================

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
=========

The scripts use a C like grammar.


2 SCRIPTS
=========

These are the available scripts:
    script_video - The video mode is set. It's the first event
        triggered.
    script_emulation - The emulation start. It's triggered after
        the MAME confirmation screens.
    script_play - The game play start. It happens after the
        `sync_startuptime'.
    script_led1,2,3 - The led controlled by the emulated
        game is enabled.
    script_turbo - The turbo button is pressed.
    script_coin1,2,3,4 - A coin button is pressed.
    script_start1,2,3,4 - A start button is pressed.
    script_safequit - The game enter in the safequit status.
    script_event1-14 - The events controlled by the
        event system.
    script_knocker - The knocker output is triggered.
        Like in the Q*bert game.

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


3 VALUES
========

You have two type of values. Numerical integer values and text
string values.

The numerical values are expressed with the following formats:
    ... - Number in decimal format.
    0x... - Number in hexadecimal format.
    0b... - Number in binary format.

The text values are expressed with the following formats:
    "..." - String.

Examples:
    10 - Decimal format of 10.
    0xA - Hexadecimal format of 10.
    0b1010 - Binary format of 10.
    "Text" - Generic string.


4 OPERATORS
===========

The values can be combined in expressions using some operators.

For numerical values the following operators are available:
     - Addition.
    - - Subtraction.
    & - Bitwise and.
    | - Bitwise or.
    ^ - Bitwise xor.
    ~ - Bitwise not.
    && - Logical and.
    || - Logical or.
    ! - Logical not.
    < - Less.
    > - Greater.
    == - Equal.
    <= - Less or equal.
    >= - Greater or equal.

For string values the following operators are available:
     - Concatenation.


5 COMMANDS
==========

These are the available commands:
    while (CONDITION) { ... } - Repeat until CONDITION is not 0.
    if (CONDITION) { ...  } - Execute if CONDITIDION is not 0.
    loop { ... } - Repeat forever.
    repeat (N) { ... } - Repeat N times.
    wait(CONDITION) - Wait until the CONDITION is not 0.
    delay(N) - Wait the specified N milliseconds.

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
===========

These are the available functions:
    event() - Return 0 if the event that started the
        script is terminated. Return 1 if the event
        is active.
    event(EVENT) - Return 0 if the specified event is
        not active. Return 1 if the event is active.
    simulate_event(EVENT,NUMBER) - Simulate the specified
        event for NUMBER milli seconds.
    simulate_key(KEY,NUMBER) - Simulate the specified key for
        NUMBER milli seconds.
    log(VALUE) - Output a texr or number value in the log file.
    msg(VALUE) - Print on screen a a text or number value.
    system(TEXT) - Execute the specified command TEXT as a
        shell script. Return the exit code.
    lcd(ROW_NUMBER, VALUE) - Display a value on the LCD at the
        specified row. The first row is 0.
    rand(NUMBER) - Generate a random number from 0
        to NUMBER - 1.

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
=======

External devices can be controlled using the keyboard led
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:

    set(ADDRESS, VALUE) - Set the port with the specified value.
    get(ADDRESS) - Return the value of the port
    on(ADDRESS, VALUE) - Enable the active bits in VALUE.
        Like set(ADDRESS, get(ADDRESS) | VALUE).
    off(ADDRESS, VALUE) - Disable the active bits in VALUE.
        Like set(ADDRESS, get(ADDRESS) & ~VALUE).
    toggle(ADDRESS, VALUE) - Toggle the active bits in VALUE.
        Like set(ADDRESS, get(ADDRESS) ^ VALUE).

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 predefinite symbols
available.

These are the event symbols available for the
`simulate_event(EVENT, TIME)' and `event(EVENT)'
commands :
    EVENT - p1_up, p1_down, p1_left, p1_right, p2_up, p2_down,
        p2_left, p2_right, p1_button1, p1_button2, p1_button3,
        p1_button4, p1_button5, p1_button6, p1_button7,
        p1_button8, p1_button9, p1_button10, p2_button1,
        p2_button2, p2_button3, p2_button4, p2_button5,
        p2_button6, p2_button7, p2_button8, p2_button9,
        p2_button10, start1, start2, start3, start4, coin1,
        coin2, coin3, coin4, service_coin1, service_coin2,
        service_coin3, service_coin4, service, tilt.

These are the user interface event symbols available for
the `simulate_event(EVENT, TIME)' and `event(EVENT)'
commands :
    EVENT - ui_mode_next, ui_mode_pred, ui_record_start,
        ui_record_stop, ui_turbo, ui_cocktail, ui_configure,
        ui_on_screen_display, ui_pause, ui_reset_machine,
        ui_show_gfx, ui_frameskip_dec, ui_frameskip_inc,
        ui_throttle, ui_show_fps, ui_snapshot, ui_toggle_cheat,
        ui_up, ui_down, ui_left, ui_right, ui_select,
        ui_cancel, ui_pan_up, ui_pan_down, ui_pan_left,
        ui_pan_right, ui_show_profiler, ui_show_colors,
        ui_toggle_ui, ui_toggle_debug, ui_save_state,
        ui_load_state, ui_add_cheat, ui_delete_cheat,
        ui_save_cheat, ui_watch_value.

These are the keyboard symbols available for the
`simulate_key(EVENT, TIME)' command :
    EVENT - key_a, key_b, key_c, key_d, key_e, key_f, key_g,
        key_h, key_i, key_j, key_k, key_l, key_m, key_n,
        key_o, key_p, key_q, key_r, key_s, key_t, key_u,
        key_v, key_w, key_x, key_y, key_z, key_0, key_1,
        key_2, key_3, key_4, key_5, key_6, key_7, key_8,
        key_9, key_0_pad, key_1_pad, key_2_pad, key_3_pad,
        key_4_pad, key_5_pad, key_6_pad, key_7_pad,
        key_8_pad, key_9_pad, key_f1, key_f2, key_f3,
        key_f4, key_f5, key_f6, key_f7, key_f8, key_f9,
        key_f10, key_f11, key_f12, key_esc, key_backquote,
        key_minus, key_equals, key_backspace, key_tab,
        key_openbrace, key_closebrace, key_enter, key_semicolon,
        key_quote, key_backslash, key_less, key_comma,
        key_period, key_slash, key_space, key_insert, key_del,
        key_home, key_end, key_pgup, key_pgdn, key_left,
        key_right, key_up, key_down, key_slash_pad,
        key_asterisk_pad, key_minus_pad, key_plus_pad,
        key_period_pad, key_enter_pad, key_prtscr, key_pause,
        key_lshift, key_rshift, key_lcontrol, key_rcontrol,
        key_lalt, key_ralt, key_scrlock, key_numlock,
        key_capslock, key_lwin, key_rwin, key_menu.

These are text symbols containing some game and emulation
information:
    info_desc - The game title. For example "PacMan".
    info_manufacturer - The game manufacturer. For example "Namco".
    info_year - The game year. For example "1980".
    info_throttle - The current game speed. For example "100%".


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 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
================

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

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


11 COPYRIGHT
============

This file is Copyright (C) 2003, 2004 Andrea Mazzoleni.
