Rpg Maker Developers Group

---

Introduction

This script provides an on-screen input device indicator HUD for RPG Maker VX Ace running on mkxp-z. It displays a small icon in the top-right corner of the screen reflecting the active input device tracked by the Input Device Tracker.

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

Core HUD Features

• Top-right corner device icon reflecting the active input device at all times
• Three display modes controlled by SHOW_BATTERY_ICON and BATTERY_CHANGES_DEVICE_ICON
• Optional battery icon drawn beside the device icon while a gamepad is active
• Optional battery-driven device icon override for per-charge-state gamepad icons
• Optional wide keyboard indicator via a flush-adjacent secondary icon forming a 48×24 px block
• Per-scene HUD suppression via a configurable scene list (blacklist or whitelist) - no viewport or sprite overhead in suppressed scenes
• Switch-based HUD hide via a configurable game switch ID - sprites persist and reappear instantly when the switch turns off

---

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.

HUD Visibility Control

$game_switches[Hammy::InputDeviceTrackerHUD::HIDE_SWITCH_ID] = true/false
Directly set the HUD hide switch state using the game switches array.
- true: Hides the HUD (all sprites become invisible)
- false: Shows the HUD normally

Examples

---

Usage

This section explains the three display modes and how to configure icons, margins, and scene exclusions.

Display Modes
The HUD display mode is controlled by two booleans: SHOW_BATTERY_ICON and BATTERY_CHANGES_DEVICE_ICON. Only one mode is active at a time. When both are true, SHOW_BATTERY_ICON takes precedence.

• Default mode (both false): A single device icon is shown at all times. The icon reflects the current device state using ICONS[:none], ICONS[:keyboard], or ICONS[:gamepad].
• Battery icon mode (SHOW_BATTERY_ICON = true): A second battery icon is drawn to the left of the screen edge beside the device icon while a gamepad is active. The battery icon index is resolved from BATTERY_ICONS by the current power_level symbol. When no gamepad is connected the battery icon is hidden and the device icon shifts back to its single-icon position automatically.
• Battery device icon mode (BATTERY_CHANGES_DEVICE_ICON = true): A single icon is shown at all times. While a gamepad is active the icon index is resolved from BATTERY_DEVICE_ICONS by the current power_level symbol instead of the fixed ICONS[:gamepad] value. Non-gamepad states use ICONS as usual.

Wide Keyboard Icon
Setting ICONS[:keyboard_ext] to an integer icon index enables a wide keyboard indicator that occupies a 48×24 px region formed by two standard icons placed flush against each other with no margin between them. The extended icon is only shown while the active device is :keyboard. All other device states use the standard 24×24 single-icon layout.

• Set ICONS[:keyboard_ext] to nil (default) to keep the single 24×24 icon.

Switch-Based HUD Hide
A single game switch can be used to hide the HUD at any time without removing it from the scene. The viewport and sprites persist; only their visibility is toggled, so the HUD reappears instantly when the switch is turned off again.

• Set HIDE_SWITCH_ID to any valid switch ID in your project.
• When this switch is ON, all HUD sprites are hidden.
• When this switch is OFF, the HUD displays normally.
• Usage via event command:
• Control Switches: Turn ON switch HIDE_SWITCH_ID → hides the HUD
• Control Switches: Turn OFF switch HIDE_SWITCH_ID → shows the HUD
• Usage via script call:
  
  Ruby:

  $game_switches[Hammy::InputDeviceTrackerHUD::HIDE_SWITCH_ID] = true
  $game_switches[Hammy::InputDeviceTrackerHUD::HIDE_SWITCH_ID] = false

• HUD suppression via SCENE_LIST takes priority over this switch. In suppressed scenes the HUD is never created, so the switch has no effect.

Scene Exclusion / Inclusion
SCENE_LIST holds scene class constants that control per-scene HUD visibility. Whether it acts as a blacklist or a whitelist is determined by SCENE_LIST_IS_WHITELIST. The HUD viewport and sprites are never created for suppressed scenes, so no update overhead is incurred.

• Blacklist mode (SCENE_LIST_IS_WHITELIST = false, default):
• The HUD is shown in every scene EXCEPT those listed in SCENE_LIST. An empty array means the HUD appears in every scene.
• Whitelist mode (SCENE_LIST_IS_WHITELIST = true):
• The HUD is shown ONLY in scenes listed in SCENE_LIST. Every other scene suppresses the HUD entirely. An empty array means the HUD never appears in any scene.
• SCENE_LIST uses class constants directly, not strings.

---

Configuration

Edit the constants in the Hammy::InputDeviceTrackerHUD module to configure the HUD layout, display modes, scenes exclusions, hide switch, and icon graphics.

Layout Settings
Configure the spacing and render depth of the HUD icons.

MARGIN
Gap in pixels between icons and from the screen edges.

Applied between the device icon and the battery icon when both are visible, and between the rightmost icon and top-right screen edge.

- Valid values: Any non-negative integer
- Default: 4

Example

Z_LEVEL
Z-depth used for the HUD viewport and all HUD sprites.

A very high value ensures the HUD renders above all scene content.

- Valid values: Any integer
- Default: 9999

Example

Display Mode Settings
Configure which display mode the HUD uses. See the General Setup & Usage Guide for a full explanation of each mode.

SHOW_BATTERY_ICON
Shows a battery icon beside the device icon.

When true, a second battery icon is drawn beside the device icon while a gamepad is active. Takes precedence over BATTERY_CHANGES_DEVICE_ICON when both are true.

- Valid values: true / false
- Default: false

Example

BATTERY_CHANGES_DEVICE_ICON
Replaces the device icon with a battery-level-specific icon while a gamepad is active.

Only active when SHOW_BATTERY_ICON is false.

- Valid values: true / false
- Default: true

Example

Scene Exclusion Settings
Configure which scenes suppress the HUD entirely. The HUD viewport and sprites are never created for suppressed scenes.

SCENE_LIST_IS_WHITELIST
Controls how SCENE_LIST is interpreted.

When false (blacklist), the HUD is shown in every scene except those listed in SCENE_LIST. When true (whitelist), the HUD is shown only in scenes listed in SCENE_LIST.

- Valid values: true / false
- Default: false

Example

SCENE_LIST
List of scene classes used as a blacklist or whitelist depending on SCENE_LIST_IS_WHITELIST (see above).
- Valid values: Array of scene class constants
- Default: [Scene_Title, Scene_Menu]

Example

Switch Settings
Configure the game switch used to hide the HUD at runtime.

HIDE_SWITCH_ID
Controls HUD visibility via a game switch.

When this switch is ON, all HUD sprites are hidden. When OFF, the HUD displays normally. The viewport and sprites are kept alive while hidden so the HUD reappears instantly when the switch is turned off.

- Valid values: Any valid switch ID (1 to max switches in project)
- Default: 12

Example

Icon Settings
Configure the icon indices used by the HUD. All indices refer to the Graphics/System/Iconset sheet using the standard 24x24 px icon grid with 16 icons per row - the same layout as Window_Base#draw_icon.

ICONS
Primary device icon indices keyed by device state symbol.

none: Icon shown when no device has been detected yet keyboard: Icon shown while the active device is :keyboard keyboard_ext: Optional second icon rendered flush-right of the keyboard icon to form a 48x24 wide indicator. Set to nil to keep the standard 24x24 single icon. gamepad: Icon shown while the active device is :gamepad

- Valid values: Hash of { symbol => integer or nil }
- Default: { none: 0, keyboard: 1, keyboard_ext: nil, gamepad: 2 }

Example

BATTERY_ICONS
Battery state icon indices used in battery icon mode.

Keys match the symbols returned by Input::Controller.power_level. Only active when SHOW_BATTERY_ICON is true.

- Valid values: Hash of { symbol => integer }
- Default: { WIRED: 3, MAX: 4, HIGH: 5, MEDIUM: 6, LOW: 7, EMPTY: 8, UNKNOWN: 9 }

Example

BATTERY_DEVICE_ICONS
Device icon overrides per battery state.

Applied only while the active device is :gamepad. Only active when BATTERY_CHANGES_DEVICE_ICON is true.

- Valid values: Hash of { symbol => integer }
- Default: { WIRED: 10, MAX: 11, HIGH: 12, MEDIUM: 13, LOW: 14, EMPTY: 15, UNKNOWN: 16 }

Example

---

Installation

• Copy the script to an open slot below ▼ Materials but above ▼ Main
• This script requires Hammy - MKXP-Z Input Device Tracker and must be placed BELOW it

---

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

---