MAME

https://docs.mamedev.org/
Admin
MAME is a multi-purpose emulation framework that preserves decades of vintage software history by...
Tokens:823,292
Snippets:6,682
Trust Score:9.9
Update:47 minutes ago
Show doc for...
Tokens:
Raw
### Debugger help command examples

Source: https://docs.mamedev.org/_files/MAME.pdf

Shows how to use the debugger's help command to list top-level topics, get help on expression syntax, and get help on the wpiset command.

```mame-debugger
help
```

```mame-debugger
help expressions
```

```mame-debugger
help wpiset
```

--------------------------------

### Imgtool get example

Source: https://docs.mamedev.org/_files/MAME.pdf

Extracts a file from a disk image and saves it to a new file.

```text
imgtool get coco_jvc_rsdos myimage.dsk myfile.bin mynewfile.txt
```

--------------------------------

### Imgtool example usage

Source: https://docs.mamedev.org/tools/imgtool.html

Three example invocations: listing a directory, getting a single file, and getting all files from an image.

```text
imgtool dir coco_jvc_rsdos myimageinazip.zip
```

```text
imgtool get coco_jvc_rsdos myimage.dsk myfile.bin mynewfile.txt
```

```text
imgtool getall coco_jvc_rsdos myimage.dsk
```

--------------------------------

### traceover command examples

Source: https://docs.mamedev.org/debugger/execution.html

Starts or stops tracing for the specified CPU, skipping over subroutine calls. Accepts the same parameters as the trace command. Examples show logging to a file, specifying a CPU by absolute tag path, disabling loop detection, turning off tracing by CPU index, and using a tracelog action.

```text
traceover joust.tr
```

```text
traceover dribling.tr,maincpu
```

```text
traceover starswep.tr,,noloop
```

```text
traceover off,0
```

```text
traceover asteroid.tr,,,{tracelog "A=%02X ",a}
```

--------------------------------

### Memory Bank Creator Dynamic Installation (vegaeo_state)

Source: https://docs.mamedev.org/techspecs/object_finders.html

Example using memory_bank_creator to install a memory bank dynamically in an init function. The bank is configured with configure_entries and installed in the address space, taking care not to overlap internal RAM.

```cpp
class vegaeo_state : public eolith_state
{
public:
    vegaeo_state(machine_config const &mconfig, device_type type, char const *tag) :
        eolith_state(mconfig, type, tag),
        m_qs1000_bank(*this, "qs1000_bank")
    {
    }

    void init_vegaeo();

private:
    memory_bank_creator m_qs1000_bank;
};

void vegaeo_state::init_vegaeo()
{
    // Set up the QS1000 program ROM banking, taking care not to overlap the internal RAM
    m_qs1000->cpu().space(AS_IO).install_read_bank(0x0100, 0xffff, m_qs1000_bank);
    m_qs1000_bank->configure_entries(0, 8, memregion("qs1000:cpu")->base() + 0x100, 0x10000);

    init_speedup();
}
```

--------------------------------

### Use object finders as pointers after machine start (write_c0nx, read_cnxx)

Source: https://docs.mamedev.org/techspecs/object_finders.html

After the emulated machine has started, object finders can be used like pointers. This example reads an I/O port, writes to an output latch, and reads from a memory region. Object finders targeting base pointers of memory regions and shares can be indexed like arrays.

```cpp
void a2bus_parprn_device::write_c0nx(u8 offset, u8 data)
{
    ioport_value const cfg(m_input_config->read());

    m_printer_out->write(data & (BIT(cfg, 8) ? 0xffU : 0x7fU));
    m_printer_conn->write_strobe(BIT(~cfg, 3));
}


u8 a2bus_parprn_device::read_cnxx(u8 offset)
{
    offset ^= 0x40U;
    return m_prom[offset];
}
```

--------------------------------

### Use object finders as pointers after machine start

Source: https://docs.mamedev.org/_files/MAME.pdf

After the emulated machine has started, object finders can be used like pointers. This example shows reading an I/O port, writing to an output latch, and accessing a memory region. Object finders targeting memory regions can be indexed like arrays.

```cpp
void a2bus_parprn_device::write_c0nx(u8 offset, u8 data)
{
	ioport_value const cfg(m_input_config->read());
	m_printer_out->write(data & (BIT(cfg, 8) ? 0xffU : 0x7fU));
	m_printer_conn->write_strobe(BIT(~cfg, 3));
}

u8 a2bus_parprn_device::read_cnxx(u8 offset)
{
	offset ^= 0x40U;
	return m_prom[offset];
}
```

--------------------------------

### Abbreviated output example

Source: https://docs.mamedev.org/_files/MAME.pdf

Shows how output is abbreviated with '...' in examples.

```bash
A B C ... Z
```

--------------------------------

### space:install_write_tap(start, end, name, callback)

Source: https://docs.mamedev.org/_files/MAME.pdf

Installs a pass-through handler that receives notifications on writes to the specified range of addresses. The start and end addresses are inclusive. The callback is passed three arguments: access offset, data written, and memory access mask. To modify the data being written, return the modified value as an integer. Returns the new pass-through handler.

```APIDOC
## space:install_write_tap(start, end, name, callback)

### Description
Installs a pass-through handler that receives notifications on writes to the specified range of addresses. The start and end addresses are inclusive. The callback is passed three arguments: access offset, data written, and memory access mask. To modify the data being written, return the modified value as an integer. Returns the new pass-through handler.

### Method
Lua method

### Parameters
- **start** (integer) - Required - The starting address of the range (inclusive).
- **end** (integer) - Required - The ending address of the range (inclusive).
- **name** (string) - Required - The name of the tap.
- **callback** (function) - Required - The callback function to be invoked on writes.

### Returns
Pass-through handler object.
```

--------------------------------

### Instantiate and configure SBus with object finders

Source: https://docs.mamedev.org/techspecs/object_finders.html

Shows how to create the CPU, address space, and SBus device, then configure the SBus using the same object finders. This is the recommended approach to avoid tag duplication.

```cpp
SPARCV7(config, m_maincpu, 20'000'000);

ADDRESS_MAP_BANK(config, m_type1space);

SBUS(config, m_sbus, 20'000'000);
m_sbus->set_cpu(m_maincpu);
m_sbus->set_type1space(m_type1space, 0);
```

--------------------------------

### example_renderer constructor implementation

Source: https://docs.mamedev.org/techspecs/poly_manager.html

Initializes poly_manager and allocates two display buffers and a depth buffer with the given width and height.

```cpp
example_renderer::example_renderer(running_machine &machine, uint32_t width, uint32_t height) :
    poly_manager(machine),
    m_draw_buffer(0)
{
    // allocate two display buffers and a depth buffer
    m_display[0].allocate(width, height);
    m_display[1].allocate(width, height);
    m_depth.allocate(width, height);
}
```

--------------------------------

### cheatinit command example

Source: https://docs.mamedev.org/_files/MAME.pdf

Initializes cheat search for 8-bit unsigned values. Output shows 36928 locations initialized.

```text
>cheatinit ub
```

--------------------------------

### mame.exe -help

Source: https://docs.mamedev.org/usingmame/usingmame.html

Displays a basic summary of command-line options for MAME.

```bash
mame.exe -help
```

--------------------------------

### Memory Bank Finders in Address Map (qvt70_state)

Source: https://docs.mamedev.org/techspecs/object_finders.html

Example using required_memory_bank and required_memory_bank_array in an address map to install memory banks. The finders are used in place of literal tags when installing memory banks.

```cpp
class qvt70_state : public driver_device
{
public:
    qvt70_state(machine_config const &mconfig, device_type type, char const *tag) :
        driver_device(mconfig, type, tag),
        m_rombank(*this, "rom"),
        m_rambank(*this, "ram%d", 0U),
    { }

private:
    required_memory_bank m_rombank;
    required_memory_bank_array<2> m_rambank;

    void mem_map(address_map &map);

    void rombank_w(u8 data);
};

void qvt70_state::mem_map(address_map &map)
{
    map(0x0000, 0x7fff).bankr(m_rombank);
    map(0x8000, 0x8000).w(FUNC(qvt70_state::rombank_w));
    map(0xa000, 0xbfff).ram();
    map(0xc000, 0xdfff).bankrw(m_rambank[0]);
    map(0xe000, 0xffff).bankrw(m_rambank[1]);
}
```

--------------------------------

### List system names and descriptions with -listfull

Source: https://docs.mamedev.org/commandline/commandline-all.html

Displays a list of system driver names and descriptions. The example shows the command and its output for the pattern 'galaxian*'.

```bash
mame -listfull galaxian*
```

```text
Name:             Description:
galaxian          "Galaxian (Namco set 1)"
galaxiana         "Galaxian (Namco set 2)"
galaxianbl        "Galaxian (bootleg, set 2)"
galaxianbl2       "Galaxian (bootleg, set 4)"
galaxiani         "Galaxian (Irem)"
galaxianm         "Galaxian (Midway set 1)"
galaxianmo        "Galaxian (Midway set 2)"
galaxiant         "Galaxian (Taito)"
galaxian_sound    "Galaxian Custom Sound"
```

--------------------------------

### screen:time_until_vblank_start()

Source: https://docs.mamedev.org/_files/MAME.pdf

Gets the time remaining until the start of the vertical blanking interval. Returns a floating-point number in seconds.

```APIDOC
## screen:time_until_vblank_start()

### Description
Gets the time remaining until the start of the vertical blanking interval. The result is a floating-point number in units of seconds.

### Method
Lua method

### Endpoint
screen:time_until_vblank_start()

### Parameters
None

### Return Value
- **number** (float) - Time in seconds until the start of the vertical blanking interval.
```

--------------------------------

### Display MAME version and copyright with -help

Source: https://docs.mamedev.org/commandline/commandline-all.html

Run `mame -help` to display the current MAME version and copyright notice.

```bash
mame -help
```

--------------------------------

### ui.menu_active (property)

Source: https://docs.mamedev.org/_files/MAME.pdf

Gets a Boolean indicating whether an interactive UI element is currently active. Examples include menus and slider controls.

```APIDOC
## ui.menu_active (property)

### Description
Gets a Boolean indicating whether an interactive UI element is currently active. Examples include menus and slider controls.

### Access
Read-only

### Type
Boolean

```

--------------------------------

### Choose mouse provider with -mouseprovider

Source: https://docs.mamedev.org/commandline/commandline-all.html

Selects how MAME gets mouse input; default is auto. Example uses win32 for indy_4610.

```bash
mame indy_4610 -mouseprovider win32
```

--------------------------------

### save examples

Source: https://docs.mamedev.org/debugger/memory.html

Three examples showing how to save memory from different address spaces and devices.

```text
save venture.bin,0,10000
```

```text
saved harddriv.bin,3000:3,1000
```

```text
save vram.bin,0:sms_vdp:videoram,4000
```

--------------------------------

### trackmem example: begin tracking for visible CPU

Source: https://docs.mamedev.org/debugger/general.html

Begins or continues tracking memory writes for the visible CPU.

```text
trackmem
```

--------------------------------

### screen:time_until_vblank_start()

Source: https://docs.mamedev.org/luascript/ref-devices.html

Gets the time remaining until the start of the vertical blanking interval. The result is a floating-point number in units of seconds.

```APIDOC
## screen:time_until_vblank_start()

### Description
Gets the time remaining until the start of the vertical blanking interval. The result is a floating-point number in units of seconds.

### Method
Function call

### Endpoint
`screen:time_until_vblank_start()`

### Parameters
None

### Returns
- **time** (number) - Time remaining in seconds (floating-point).

```

--------------------------------

### Imgtool getall example

Source: https://docs.mamedev.org/_files/MAME.pdf

Extracts all files from a disk image.

```text
imgtool getall coco_jvc_rsdos myimage.dsk
```

--------------------------------

### List system details in XML with -listxml

Source: https://docs.mamedev.org/commandline/commandline-all.html

Outputs comprehensive details for all supported systems and devices in XML format. The example shows the command and a sample of the XML output, which is typically redirected to a file for parsing.

```bash
mame galaxian -listxml
```

```xml
<?xml version="1.0"?>
<!DOCTYPE mame [
<!ELEMENT mame (machine+)>
        <!ATTLIST mame build CDATA #IMPLIED>
        <!ATTLIST mame debug (yes|no) "no">
        <!ATTLIST mame mameconfig CDATA #REQUIRED>
        <!ELEMENT machine (description, year?, manufacturer?, biosset*, rom*, disk*, device_ref*, sample*, chip*, display*, sound?, input?, dipswitch*, configuration*, port*, adjuster*, driver?, feature*, device*, slot*, softwarelist*, ramoption*)>
                <!ATTLIST machine name CDATA #REQUIRED>
                <!ATTLIST machine sourcefile CDATA #IMPLIED>
...
<mame build="0.216 (mame0216-154-gabddfb0404c-dirty)" debug="no" mameconfig="10">
    <machine name="galaxian" sourcefile="galaxian.cpp">
                <description>Galaxian (Namco set 1)</description>
                <year>1979</year>
                <manufacturer>Namco</manufacturer>
        ...
    <machine name="z80" sourcefile="src/devices/cpu/z80/z80.cpp" isdevice="yes" runnable="no">
                <description>Zilog Z80</description>
    </machine>
</mame>
```

--------------------------------

### Choose joystick provider with -joystickprovider

Source: https://docs.mamedev.org/commandline/commandline-all.html

Selects how MAME gets joystick and game controller input; default is auto. Example uses winhybrid for mk2.

```bash
mame mk2 -joystickprovider winhybrid
```

--------------------------------

### Choose light gun provider with -lightgunprovider

Source: https://docs.mamedev.org/commandline/commandline-all.html

Selects how MAME gets light gun input; default is auto. Example uses x11 for lethalen.

```bash
mame lethalen -lightgunprovider x11
```

--------------------------------

### debug:go()

Source: https://docs.mamedev.org/_files/MAME.pdf

Runs the emulated CPU.

```APIDOC
## debug:go()

### Description
Runs the emulated CPU.

### Method
go
```

--------------------------------

### step command example: step 4

Source: https://docs.mamedev.org/_files/MAME.pdf

Steps forward four instructions on the current CPU.

```mame-debugger
step 4
```

--------------------------------

### install_write_tap(start, end, name, callback)

Source: https://docs.mamedev.org/luascript/ref-mem.html

Installs a pass-through handler that will receive notifications on writes to the specified range of addresses in an address space.

```APIDOC
## install_write_tap(start, end, name, callback)

### Description
Installs a pass-through handler that will receive notifications on writes to the specified range of addresses in an address space.

### Method
install_write_tap

### Endpoint
manager.machine.devices[tag].spaces[name]:install_write_tap(start, end, name, callback)

### Parameters
- **start** (number) - Required - The start address of the range to monitor.
- **end** (number) - Required - The end address of the range to monitor.
- **name** (string) - Required - The display name for the pass-through handler.
- **callback** (function) - Required - The callback function to be invoked on writes.

### Response
No return value documented.
```

--------------------------------

### install_read_tap(start, end, name, callback)

Source: https://docs.mamedev.org/luascript/ref-mem.html

Installs a pass-through handler that will receive notifications on reads from the specified range of addresses in an address space.

```APIDOC
## install_read_tap(start, end, name, callback)

### Description
Installs a pass-through handler that will receive notifications on reads from the specified range of addresses in an address space.

### Method
install_read_tap

### Endpoint
manager.machine.devices[tag].spaces[name]:install_read_tap(start, end, name, callback)

### Parameters
- **start** (number) - Required - The start address of the range to monitor.
- **end** (number) - Required - The end address of the range to monitor.
- **name** (string) - Required - The display name for the pass-through handler.
- **callback** (function) - Required - The callback function to be invoked on reads.

### Response
No return value documented.
```

--------------------------------

### Create mame.ini on Windows with mame -createconfig

Source: https://docs.mamedev.org/initialsetup/configuringmame.html

Run from the MAME installation directory (e.g., C:\Users\Public\MAME) to generate the default mame.ini configuration file.

```bash
cd C:\Users\Public\MAME
```

```bash
mame -createconfig
```

--------------------------------

### history command examples

Source: https://docs.mamedev.org/_files/MAME.pdf

Displays recently visited PC addresses and disassembly. The first argument selects the CPU (defaults to visible CPU), the second limits the number of addresses shown. Examples show limiting to five, selecting the fourth CPU, and selecting a CPU by absolute tag.

```mame-debugger
history ,5
```

```mame-debugger
history 3
```

```mame-debugger
history audiocpu,1
```

--------------------------------

### Run MAME with software list entry

Source: https://docs.mamedev.org/_files/MAME.pdf

Starts a software list item by specifying the system and software shortname. For example, 'mame.exe nes metroidu' loads the USA version of Metroid for the NES.

```text
mame.exe <system> <software>
```

```text
mame.exe nes metroidu
```

--------------------------------

### draw_triangle_flat: Setup for Flat-Shaded Triangle

Source: https://docs.mamedev.org/techspecs/poly_manager.html

Sets up object data and vertex parameters for a flat-shaded triangle. Stores a constant color in example_object_data, copies X, Y, and 1/Z into vertex_t objects, then calls render_triangle<1> with a render_delegate pointing to render_flat. Uses 1/Z as the iterated parameter because it is linear in screen space.

```cpp
void example_renderer::draw_triangle_flat(example_vertex const *verts)
{
    // allocate object data and populate it with information needed
    example_object_data &object = object_data().next();
    object.dest = &m_display[m_draw_buffer];
    object.depth = &m_depth;

    // in this case the color is constant and specified in the object data
    object.color = verts[0].color;

    // copy X, Y, and 1/Z into poly_manager vertices
    vertex_t v[3];
    for (int vertnum = 0; vertnum < 3; vertnum++)
    {
        v[vertnum].x = verts[vertnum].x;
        v[vertnum].y = verts[vertnum].y;
        v[vertnum].p[0] = 1.0f / verts[vertnum].z;
    }

    // render the triangle with 1 iterated parameter (1/Z)
    render_triangle<1>(m_display[0].cliprect(),
                        render_delegate(&example_renderer::render_flat, this),
                        v[0], v[1], v[2]);
}
```

--------------------------------

### load example: load videoram space

Source: https://docs.mamedev.org/debugger/memory.html

Loads the videoram space for the device with absolute tag path :sms_vdp starting at address 0000 with the entire content of vram.bin.

```text
load vram.bin,0:sms_vdp:videoram
```

--------------------------------

### Create mame.ini on Linux/macOS with ./mame -createconfig

Source: https://docs.mamedev.org/initialsetup/configuringmame.html

For compiled or binary installations, cd into the MAME directory (e.g., /home/myusername/mame) and run ./mame -createconfig to generate the default mame.ini.

```bash
cd /home/myusername/mame
```

```bash
./mame -createconfig
```

--------------------------------

### List network adapters with -listnetwork (adapters found)

Source: https://docs.mamedev.org/commandline/commandline-all.html

Run -listnetwork to list available network adapters for use with emulation. This example shows the output when network adapters are available, listing each adapter by name.

```bash
mame -listnetwork
Available network adapters:
    Local Area Connection
```

--------------------------------

### step command example: s

Source: https://docs.mamedev.org/_files/MAME.pdf

Steps forward one instruction on the current CPU.

```mame-debugger
s
```

--------------------------------

### Getting buffer pointers for source and destination

Source: https://docs.mamedev.org/techspecs/audio_effects.html

Use these calls to obtain contiguous sample pointers. source_index must be in [-history_size()..samples-1] and destination_index in [0..samples-1].

```cpp
const sample_t *source = src.ptrs(channel, source_index); // source_index must be in [-history_size()..samples-1]
sample_t *destination = dest.ptrw(channel, destination_index); // destination_index must be in [0..samples-1]
```

--------------------------------

### List MIDI devices with -listmidi

Source: https://docs.mamedev.org/commandline/commandline-all.html

Run -listmidi to list available MIDI I/O devices for use with emulation. The example shows the command and its output, which lists MIDI input and output ports.

```bash
mame -listmidi
MIDI input ports:

MIDI output ports:
Microsoft MIDI Mapper (default)
Microsoft GS Wavetable Synth
```

--------------------------------

### space:install_read_tap(start, end, name, callback)

Source: https://docs.mamedev.org/_files/MAME.pdf

Installs a pass-through handler that receives notifications on reads from the specified range of addresses. The start and end addresses are inclusive. The callback is passed three arguments: access offset, data read, and memory access mask. To modify the data being read, return the modified value as an integer. Returns the new pass-through handler.

```APIDOC
## space:install_read_tap(start, end, name, callback)

### Description
Installs a pass-through handler that receives notifications on reads from the specified range of addresses. The start and end addresses are inclusive. The callback is passed three arguments: access offset, data read, and memory access mask. To modify the data being read, return the modified value as an integer. Returns the new pass-through handler.

### Method
Lua method

### Parameters
- **start** (integer) - Required - The starting address of the range (inclusive).
- **end** (integer) - Required - The ending address of the range (inclusive).
- **name** (string) - Required - The name of the tap.
- **callback** (function) - Required - The callback function to be invoked on reads.

### Returns
Pass-through handler object.
```

--------------------------------

### mame.exe -showusage

Source: https://docs.mamedev.org/usingmame/usingmame.html

Displays the full list of available command-line options for MAME.

```bash
mame.exe -showusage
```

--------------------------------

### Choose keyboard provider with -keyboardprovider

Source: https://docs.mamedev.org/commandline/commandline-all.html

Selects how MAME gets keyboard input; default is auto. On Windows, user-mode tools like joy2key may require win32. Example uses win32 for c64.

```bash
mame c64 -keyboardprovider win32
```
Tokens:
Raw