Arcade Coin Limiter Lua

A small MAME Lua plugin/script that adds a coin wallet with timed refills. It is meant for arcade emulator setups where unlimited credits make coin-op games too easy.

The plugin blocks normal coin inputs at runtime, watches your configured coin buttons, and only pulses the game's coin line when the wallet has coins available.

Features

• Configurable coin wallet, e.g. 6 coins.
• Timed refill, e.g. 1 coin every 4 minutes.
• Works with COIN1, COIN2, COIN3, and other detected coin inputs.
• Tiny status display using MAME's message overlay, e.g. C 4/6 R 2:15.
• Uses emu.register_periodic, not a per-frame hook, to avoid slowdown on heavier 3D drivers.
• Restores coin input mappings when the machine stops.
• Optional gauntdlbots plugin for experimental Gauntlet Dark Legacy P2-P4 companion input bots.

Keywords: MAME Lua script, arcade emulator coin limiter, credit limiter, coin-op wallet, refill timer, retro arcade challenge, coin insert blocker.

Requirements

• MAME with Lua scripting support.
• A working game/driver and legally usable ROM/CHD files.
• Basic command-line access.

This project does not include ROMs, CHDs, BIOS files, or game assets.

Install As A Global Plugin

1. Download or clone this repository.
2. Copy the folder plugins/coinlimiter into your MAME plugins folder.
3. Make sure plugins are enabled in mame.ini:

plugins                   1
pluginspath               plugins

4. Enable the plugin in plugin.ini:

coinlimiter               1

After that, launch MAME normally. No -autoboot_script, no wrapper script, and no alternate cfg directory are required.

Quick Start

Example MAME folder after install:

C:\mame\
  mame.exe
  mame.ini
  plugin.ini
  plugins\
    coinlimiter\
      plugin.json
      init.lua

Then run MAME however you normally do:

.\mame.exe

or launch a machine directly:

.\mame.exe gauntdl

Configuration

Edit the values at the top of plugins/coinlimiter/init.lua:

local MAX_COINS = 6
local REFILL_SECONDS = 4 * 60
local COIN_PULSE_FRAMES = 4
local POLL_SECONDS = 0.016
local SHOW_STATUS_MESSAGE = true
local SHOW_DEBUG_POPUPS = false

Common changes:

• MAX_COINS: starting wallet size and refill cap.
• REFILL_SECONDS: time to add one coin back.
• SHOW_STATUS_MESSAGE: shows compact status like C 2/6 R 1:42.
• SHOW_DEBUG_POPUPS: shows accepted/blocked debug popups. Keep this off for normal play.

Fallback Script Mode

The standalone file scripts/coin_limiter.lua can still be used with -autoboot_script, but the plugin is the recommended setup.

.\mame.exe gauntdl -autoboot_delay 1 -autoboot_script C:\path\to\arcade-coin-limiter-lua\scripts\coin_limiter.lua

Optional Gauntlet Dark Legacy Bots

The plugins/gauntdlbots plugin is an experimental input-level companion bot layer for gauntdl and gauntdl24.

Install it the same way as coinlimiter:

C:\mame\
  plugins\
    coinlimiter\
      plugin.json
      init.lua
    gauntdlbots\
      plugin.json
      init.lua

Enable both plugins in plugin.ini:

coinlimiter               1
gauntdlbots               1

The bots do not understand the game world yet. They are simple input bots. They stay idle at boot and must be triggered from MAME's plugin menu:

• Open MAME's plugin menu.
• Choose Gauntlet Bots.
• Select Join P2-P4 now.
• Bot coins are requested through the coin limiter API, so they still consume the wallet.
• Bots follow P1 movement with staggered delay.
• Bots wander when P1 is idle.
• Bots press Turbo while moving and Fight on a simple rhythm.
• Magic use is disabled by default.

This is useful as a toy companion mode, not as real object-aware AI.

How Refill Works

The refill is a real-time token bucket.

• You start at MAX_COINS.
• Each accepted coin insert subtracts 1.
• Once below full, a timer starts.
• Every REFILL_SECONDS, one coin is restored.
• Refill stops at MAX_COINS.

Example with MAX_COINS = 6 and REFILL_SECONDS = 4 * 60:

• Use all coins: C 0/6.
• After 4 minutes: C 1/6.
• After 8 minutes: C 2/6.
• After 24 minutes: C 6/6.

How It Works

At runtime the plugin scans MAME I/O ports for coin inputs such as COIN1, COIN2, COIN3, and COIN4.

For each coin input it:

1. Saves the default input sequence.
2. Temporarily overrides the default coin input sequence in memory.
3. Watches the saved input sequence itself.
4. If coins are available, decrements the wallet and pulses the coin line.
5. If no coins are available, ignores the press.
6. Restores the original default input sequences when the machine stops.

Troubleshooting

Coins no longer work without the script

Use the plugin version. It uses runtime default-sequence overrides and should not save coin inputs as NONE.

If you used an older autoboot test version, check the affected game cfg file under MAME's cfg folder and remove coin entries saved as NONE, or delete that machine cfg and let MAME recreate it.

The game feels slow

Use the current plugin. Older test versions used a per-frame Lua callback and could slow down heavy games. This version uses emu.register_periodic.

The status looks too minimal

That is intentional. The plugin uses MAME's native message overlay because it works without the expensive per-frame render callback.

Notes

• This limits coin insertions, not credits already stored inside the game.
• Free Play DIP settings, service credits, save states with existing credits, or game-specific credit behavior can bypass the challenge.
• Coinage DIP settings still apply. One accepted coin may equal more than one credit depending on the game settings.
• This project is not affiliated with MAMEdev.