Hammy - MKXP-Z Main Entry Point

じ☆ve冰风

Hammy - MKXP-Z Main Entry Point v1.02
Enhanced main entry point for mkxp-z with error handling, logging, screen resolution, and a built-in TracePoint profiler​

---

Introduction

This script provides an enhanced main entry point for mkxp-z RPG Maker VX Ace games, replacing the default Main script with improved error handling, configurable screen resolution, and F12 reset behavior.

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 Entry Point Features

• Deferred log file creation - files are only written to disk when output is actually produced
  
• Crash log capture independent of the session logging setting
  
• Enhanced error backtrace with readable script names instead of numeric indices
  
• Timestamped console output via puts override
  

Customization System

• Configurable screen resolution with automatic Yanfly Core Engine compatibility
  
• Configurable logging enable/disable as standalone setting
  
• Configurable F12 reset transition effect and duration
  
• Configurable profiler trigger key, output folder, and noise threshold
  

Technical Features

• Ruby 3.1 syntax with modern module instance variable conventions
  
• mkxp-z specific RGSSReset handling with optional snapshot transition
  
• TracePoint-based method call tracking with self and total time calculation
  
• LogDispatcher class for deferred IO with automatic stderr rebinding
  

---

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.

---

Configuration

Edit the constants in the Hammy::MainEntryPoint module to configure the screen resolution, test mode, reset transition, logging options, output buffering, timestamps, and profiler settings.

Screen Resolution Settings
Configure the game window dimensions in pixels. When Yanfly Ace Core Engine is present, these settings are ignored.

SCREEN_WIDTH
Width of the game window in pixels.
- Valid values: Any integer
- Default:544

Example
                Ruby:       

1. SCREEN_WIDTH = 544

复制代码

SCREEN_HEIGHT
Height of the game window in pixels.
- Valid values: Any integer
- Default:416

Example
                Ruby:       

1. SCREEN_HEIGHT = 416

复制代码

Test Mode Settings
Configure forced test mode for use with mkxp-z, where $TEST is not set automatically when launching via the RPG Maker VX Ace Test Play button.

FORCE_TEST_MODE
Force $TEST to true at startup ignoring launch mode.

Enable this when using mkxp-z to replicate the Test Play behavior. Disable this before distributing or building a release version.

- Valid values: true / false
- Default:false

Example
                Ruby:       

1. FORCE_TEST_MODE = false

复制代码

Reset Transition Settings
Configure the transition effect applied when F12 reset is triggered.

RESET_USE_SNAPSHOT_TRANSITION
Show transition effect on F12 reset.

When false, resets instantly without a transition effect.

- Valid values: true / false
- Default:false

Example
                Ruby:       

1. RESET_USE_SNAPSHOT_TRANSITION = false

复制代码

RESET_TRANSITION_DURATION
Duration of the reset transition in frames.

Only applies when RESET_USE_SNAPSHOT_TRANSITION is true.

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

Example
                Ruby:       

1. RESET_TRANSITION_DURATION = 10

复制代码

Log File Settings
Configure file-based logging for mkxp-z output, including errors.

LOGGING_ENABLED
Redirect stdout and stderr output to a log file.
- Valid values: true / false
- Default:false

Example
                Ruby:       

1. LOGGING_ENABLED = false

复制代码

LOG_ON_CRASH
Write a crash log when LOGGING_ENABLED is false.
- Valid values: true / false
- Default:true

Example
                Ruby:       

1. LOG_ON_CRASH = true

复制代码

LOG_FILENAME_PREFIX
Filename string prepended before the timestamp.
- Valid values: String
- Default:"mkxp-z_"

Example
                Ruby:       

1. LOG_FILENAME_PREFIX = "mkxp-z_"

复制代码

LOG_FILENAME_EXTENSION
File extension for log files without the dot.
- Valid values: String
- Default:"log"

Example
                Ruby:       

1. LOG_FILENAME_EXTENSION = "log"

复制代码

LOG_FOLDER
Subfolder path for log files, or nil for root directory.
- Valid values: String, or nil
- Default:"Logs"

Example
                Ruby:       

1. LOG_FOLDER = "Logs"

复制代码

Date Format Settings
Configure the date and time format used for log filenames and timestamps.

DATE_FORMAT
Timestamp format string using Ruby strftime syntax.
- Valid values: String (strftime format)
- Default:"%Y-%m-%d_%H-%M-%S"

Example
                Ruby:       

1. DATE_FORMAT = "%Y-%m-%d_%H-%M-%S"

复制代码

Output Buffering Settings
Configure how aggressively the log file is written to disk.

SYNC_MODE
Flush log output to disk immediately on each write.
- Valid values: true / false
- Default:true

Example
                Ruby:       

1. SYNC_MODE = true

复制代码

Timestamp Settings
Configure the automatic timestamp prefixing for console output.

TIMESTAMPS
Prepend a timestamp prefix to all puts output.
- Valid values: true / false
- Default:false

Example
                Ruby:       

1. TIMESTAMPS = false

复制代码

TIMESTAMP_FORMAT
Timestamp format string using Ruby strftime syntax.
- Valid values: String (strftime format)
- Default:"[%H:%M:%S]"

Example
                Ruby:       

1. TIMESTAMP_FORMAT = "[%H:%M:%S]"

复制代码

Profiler Settings
Configure the TracePoint profiler including activation, trigger key, output location, noise filtering, and class exclusions.

PROFILER_ENABLED
Enable the TracePoint performance profiler.

When false, the profiler is not initialized for zero overhead.

- Valid values: true / false
- Default:false

Example
                Ruby:       

1. PROFILER_ENABLED = true

复制代码

PROFILER_TRIGGER_KEY
Input key that triggers profiler report output.
- Valid values: RGSS symbol
- Default::F9

Example
                Ruby:       

1. PROFILER_TRIGGER_KEY = :F9

复制代码

PROFILER_SHOW_MSGBOX
Show a confirmation msgbox after saving a report.

When false, the report is written silently without pausing gameplay.

- Valid values: true / false
- Default:true

Example
                Ruby:       

1. PROFILER_SHOW_MSGBOX = true

复制代码

PROFILER_MIN_PERCENT
Minimum time percentage for inclusion in report.

Methods below this threshold are excluded; set to 0.0 to include all.

- Valid values: Float
- Default:0.1

Example
                Ruby:       

1. PROFILER_MIN_PERCENT = 0.1

复制代码

PROFILER_FILENAME_PREFIX
Filename string prepended before timestamp.
- Valid values: String
- Default:"profiler_"

Example
                Ruby:       

1. PROFILER_FILENAME_PREFIX = "profiler_"

复制代码

PROFILER_LOG_EXTENSION
File extension for profiler report files.
- Valid values: String
- Default:"log"

Example
                Ruby:       

1. PROFILER_LOG_EXTENSION = "log"

复制代码

PROFILER_FOLDER
Subfolder path for profiler files, or nil for root.
- Valid values: String, or nil
- Default:"Logs/Profiler"

Example
                Ruby:       

1. PROFILER_FOLDER = "Logs/Profiler"

复制代码

PROFILER_EXCLUDED_CLASSES
Array of class name prefixes to exclude.

Classes are matched by prefix using start_with? against their name.

- Valid values: Array of Strings
- Default: (See array below)

Example
                Ruby:       

1. PROFILER_EXCLUDED_CLASSES = [
2.   "Kernel", "NilClass", "TrueClass", "FalseClass", "Symbol",
3.   "String", "Array", "Hash", "Comparable", "Enumerable",
4.   "Integer", "Float", "Math",
5.   "IO", "File", "FileTest",
6.   "Class", "Module", "GC", "Marshal", "Regexp", "MatchData"
7. ]

复制代码

---

Usage

This section explains how to use the built-in profiler and interpret its output reports.

Triggering a Profiler Report
Press the configured trigger key (default: F9) during gameplay to write a profiler report to the configured output folder. The profiler session resets automatically after each report is written.

• Report files are named: profiler_TIMESTAMP_INDEX.log
  

Reading the Report Format
Each row in the report represents one method tracked during the session. Rows are sorted by self time, placing the largest bottlenecks at the top.

• Report column reference:
  

                Ruby:       

1.      %   cumulative  self             self     total
2.    time   seconds   seconds   calls  ms/call  ms/call   name
3.   45.23      2.34      2.34     150    15.60    15.60   Game_Character#update

复制代码

• % time:    Percentage of total session time spent in this method
  
• self sec:  Time spent inside this method excluding called methods
  
• total sec: Cumulative time including all methods called from this one
  
• calls: Number of times this method was invoked
  
• ms/call:   Average milliseconds per invocation
  

Profiling Tips
Follow these best practices to ensure accurate and actionable profiling results when diagnosing performance issues.

• Profile for at least 30-60 seconds for statistically meaningful data
  
• Test specific scenarios separately (menus, battles, map movement)
  
• High % time indicates an optimization candidate
  
• High call count with low time indicates normal getters or setters
  

---

Installation

• Open your script editor and locate ▼ Main
  
• Delete or comment out the original Main script contents
  
• Copy and paste this script in its place and save
  
• This script REPLACES the default Main script - do not place it in a slot below ▼ Materials. It must be placed in the ▼ Main section at the bottom of the script list
  

---

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.

When Yanfly Ace Core Engine is present, the screen resolution settings in this script are automatically ignored in favor of the Core Engine's own resolution configuration.

---

License

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

---

Credits

This script includes code and concepts from:

• 姫HimeWorks' Custom Main - Full Error Backtrace script (Enhanced error backtrace processing)
  
• Archeia & Neonblack's RPG Maker VXAce Profiler script (set_trace_func-based profiler implementation)
  

---

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

---

本贴来自国际rpgmaker官方论坛作者:buddysievers处,因国际论坛即将永久关站,为了存档多年珍贵资料,署名转载到本论坛存档,由于官方帖子为英文原帖，需要中文翻译请点击论坛顶部切换语言为中文就可以将帖子翻译成中文浏览,方便大家随时查看,原文地址：https://forums.rpgmakerweb.com/threads/hammy-mkxp-z-main-entry-point.183528/