Rpg Maker Developers Group

---

Introduction

This script provides an input device tracking system for RPG Maker VX Ace running on mkxp-z. It detects whether the player is using a keyboard or a gamepad and exposes that state as a queryable symbol: :none, :keyboard, or :gamepad.

AI Disclaimer: Generative AI was used to refine the documentation and presentation of this script, as I am not a native English speaker. Additionally, AI was used for naming conventions in some places and for general beautification of the script.

mkxp-z Disclaimer: This script is made exclusively for RPG Maker VX Ace running on mkxp-z (Ruby 3.1). It will not run on standard RPG Maker VX Ace without mkxp-z. See the mkxp-z section below for more information.

---

Features

Input Device Tracker Features

• Queryable active device state as a symbol (:none, :keyboard, :gamepad)
• Gamepad detection via SDL controller button polling (buttons 0-14)
• Keyboard detection via mkxp-z native raw key state array
• Gamepad input takes priority over simultaneous keyboard input
• API availability checked once at startup and cached for the process lifetime

---

mkxp-z

mkxp-z is an open-source, cross-platform player for RPG Maker XP, VX, and VX Ace games. It is a heavily modified fork of mkxp originally built to run games based on Pokémon Essentials, which depends heavily on Windows APIs. It is best described as MKXP but supercharged - capable of running all but the most demanding RGSS projects with a bit of porting work.

mkxp-z supports Windows, Linux (x86, ARM, and POWER), and both Intel and Apple Silicon versions of macOS. Because it ships with Ruby 3.1 rather than the original Ruby 1.9.2 bundled with RPG Maker VX Ace, scripts written for mkxp-z can take advantage of modern Ruby syntax and standard library features.

This script requires mkxp-z and will not run on default RPG Maker VX Ace.

---

Script Calls

The following script calls are available for use in events and other scripts.

Device State
Hammy::InputDeviceTracker.device
Returns the current device symbol: :none, :keyboard, or :gamepad.
- Parameters: None
- Returns: Symbol

Example

Hammy::InputDeviceTracker.keyboard?
Returns true when the active device is :keyboard.
- Parameters: None
- Returns: Boolean

Example

Hammy::InputDeviceTracker.gamepad?
Returns true when the active device is :gamepad.
- Parameters: None
- Returns: Boolean

Example

Hammy::InputDeviceTracker.none?
Returns true when no device has been detected yet (:none).
- Parameters: None
- Returns: Boolean

Example

Hammy::InputDeviceTracker.reset
Resets the device state back to :none.
- Parameters: None
- Returns: Nil

Example

---

Usage

This section explains how device detection works and how to query the active device state from other scripts or events.

Detection Strategy
The tracker polls for gamepad input first on every frame. If any SDL controller button is held, the device switches to :gamepad regardless of any simultaneous keyboard activity. Keyboard input is only registered when no gamepad button is active. The device state remains at its last detected value until a different device fires.

• Gamepad input takes priority over keyboard input at all times.
• The device state does not revert automatically when input stops.
• Only digital buttons (0-14) are polled. Analog stick movement and trigger axis input do not register as gamepad activity.
• Call Hammy::InputDeviceTracker.reset to return the state to :none manually.

API Availability
Both the controller API and the keyboard API are mkxp-z exclusive. Their availability is checked once at startup and memoized for the lifetime of the process. If either API is absent, the corresponding detection path is skipped silently and the tracker stays at :none.

• This script requires mkxp-z and will not function on standard RGSS3.

---

Installation

• Copy the script to an open slot below ▼ Materials but above ▼ Main

---

Compatibility

This script is made strictly for RPG Maker VX Ace running on mkxp-z (Ruby 3.1). It will not run on default RPG Maker VX Ace without mkxp-z.

---

License

MIT License - Free for commercial and non-commercial use.

---

Credits

No credits are required.

---

Why VX Ace?

You might wonder why I'm still making scripts for VX Ace instead of MV/MZ. The answer is simple: Ruby is pure beauty, while JavaScript is a terrible language. Ruby's elegant syntax, intuitive design, and expressive power make scripting a joy. JavaScript, on the other hand, is a chaotic mess of inconsistencies and quirks that I simply despise.

I work with RPG Maker VX Ace for my own game project, and I share the scripts I create with the community. If you're still using VX Ace, you're in good company!

---

Download

Script: Download from GitHub
Demo: Download from GitHub

---