Hammy - FF9 Dialog System

じ☆ve冰风

Hammy - FF9 Dialog System v1.05
Authentic Final Fantasy IX speech bubble dialog with message chaining, fade effects, and bubble positioning​

---

Introduction

This script provides an authentic Final Fantasy IX dialog system for RPG Maker VX Ace. It displays message windows as speech bubbles above or below characters, perfect for character dialogue, interactive conversations, and event-driven cutscenes.

The system supports escape codes for bubble positioning and arrow direction, automatic bubble placement above or below characters, message chaining for continuous dialogue, character fade-in effects, configurable text display speed and effect duration, compact spacing for empty lines, and integration with the Hammy FF9 Windowskin System for colored bubble arrows.

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.

---

Features

Core Dialog Features

• Speech bubble-style message windows above or below characters with arrow sprites
  
• Escape code-based bubble positioning with custom target, arrow direction, and position control
  
• Automatic bubble positioning based on available screen space
  
• Message chaining support for continuous dialogue sequences
  
• Character fade-in effects for text display
  
• Configurable text display speed and effect duration
  
• Compact spacing mode for empty lines (reduced line height)
  

Customization System

• Configurable dialog window display settings (line height, padding, compact spacing)
  
• Configurable bubble positioning offsets and arrow sprites
  
• Support for colored bubble arrow sprites via Hammy FF9 Windowskin System
  
• Enable/disable fade-in effects and adjust settings via script calls
  

Technical Features

• Automatic bubble positioning with boundary corrections
  
• Narrow window centering on bubble sprite when width < narrow_width
  
• Dynamic window sizing based on text content
  
• Pop-style messages require :C to advance, while default windows still support :B
  
• Pop message pause sprite automatically hidden when using bubble dialog
  
• RGSS3-compliant escape code processing and rendering
  

---

Screenshots

---

Configuration

Dialog Window Display Settings

LINE_HEIGHT
Height of each text line in pixels for dialog windows. Uses default font size by default, can be set to any integer value.
- Valid values: Any integer value
- Default:Font.default_size

Example
                Ruby:       

1. LINE_HEIGHT = 20

复制代码

STANDARD_PADDING
Window padding size in pixels for dialog windows. Controls the internal spacing between window borders and content.
- Valid values: Any integer value
- Default:12

Example
                Ruby:       

1. STANDARD_PADDING = 12

复制代码

COMPACT_SPACING
Enable compact spacing for empty text lines. When true, empty text lines use reduced height for separation.
- Valid values: true or false
- Default:true

Example
                Ruby:       

1. COMPACT_SPACING = true

复制代码

COMPACT_LINE_HEIGHT
Empty line height when compact spacing is enabled. Pixel height used for empty text lines when COMPACT_SPACING is true.
- Valid values: Any integer value
- Default:6

Example
                Ruby:       

1. COMPACT_LINE_HEIGHT = 6

复制代码

Message Effects Display Settings

FADE_DURATION
Default effect duration in frames for character fade-in. Controls how many frames it takes for characters to fully fade in.
- Valid values: Any integer value
- Default:6

Example
                Ruby:       

1. FADE_DURATION = 6

复制代码

FADE_SPEED
Default text display speed in characters per second. Controls how fast text characters appear on screen.
- Valid values: Any integer value
- Default:30

Example
                Ruby:       

1. FADE_SPEED = 30

复制代码

Bubble Positioning Settings

BUBBLE_POSITION
Hash containing all bubble positioning configuration.
- y_offset_below: Vertical offset for windows positioned below a target. Distance in pixels from character screen_y to window top when below.
- y_offset_above: Vertical gap for windows positioned above a target. Distance in pixels from the top of the target sprite to the bottom of the window. The sprite height is resolved dynamically.
- tag_y_offset_below: Vertical offset when arrow is below window. Distance in pixels from window bottom to arrow sprite position.
- tag_y_offset_above: Vertical offset when arrow is above window. Distance in pixels from window top to arrow sprite position.
- narrow_width: Threshold width for narrow window centering mode. Narrow windows center on arrow sprite rather than character.
- Valid values: Hash with defined symbol keys and integer values
- Default:{ y_offset_below: 16, y_offset_above: 16, ... }

Example
                Ruby:       

1. BUBBLE_POSITION = {
2.   y_offset_below: 16,
3.   y_offset_above: 16,
4.   tag_y_offset_below: -2,
5.   tag_y_offset_above: -2,
6.   narrow_width: 64
7. }

复制代码

Default Bubble Arrow Sprite

BUBBLE_SPRITESHEET
Sprite filename for bubble arrow graphics.
Sprite Sheet Layout (64x64 pixels):
- (0-31, 0-31): up_left
- (32-63, 0-31): up_right
- (0-31, 32-63): down_left
- (32-63, 32-63): down_right
- Valid values: String containing filename without extension
- Default:'BubbleTag'

Example
                Ruby:       

1. BUBBLE_SPRITESHEET = 'BubbleTag'

复制代码

Colored Bubble Arrow Sprites

BUBBLE_ARROWS_COLORED
Hash mapping color themes to sprite filenames. Each sprite sheet uses the same 2x2 grid layout as the default.
- grey: Grey-themed arrow sprite sheet for grey windowskins.
- blue: Blue-themed arrow sprite sheet for blue windowskins.
- Valid values: Hash with Symbol keys and String values
- Default:{ grey: 'BubbleTag_Grey', blue: 'BubbleTag_Blue' }

Example
                Ruby:       

1. BUBBLE_ARROWS_COLORED = {
2.   grey: 'BubbleTag_Grey',
3.   blue: 'BubbleTag_Blue'
4. }

复制代码

Shadow Spritesheet

SHADOW_SPRITESHEET
Shadow sprite filename for bubble tag arrows. Shadow sprite sheet uses the same layout as the main bubble tag.
- Valid values: String containing filename without extension
- Default:'BubbleTag_Shadow'

Example
                Ruby:       

1. SHADOW_SPRITESHEET = 'BubbleTag_Shadow'

复制代码

Bubble Tag Shadow Settings

SHADOW_POSITION
Hash containing bubble tag shadow configuration.
- shadow_offset_x: Horizontal offset for shadow sprite in pixels. Positive values move shadow to the right.
- shadow_offset_y: Vertical offset for shadow sprite in pixels. Positive values move shadow downward.
- shadow_opacity: Opacity value for shadow sprite (0-255). Lower values create more transparent shadows.
- Valid values: Hash with defined symbol keys and integer values
- Default:{ shadow_offset_x: 2, shadow_offset_y: 2, ... }

Example
                Ruby:       

1. SHADOW_POSITION = {
2.   shadow_offset_x: 2,
3.   shadow_offset_y: 2,
4.   shadow_opacity: 128
5. }

复制代码

---

Script Calls

Message Effects Configuration

$game_system.message_speed = n
Sets the default text display speed to n characters per second. Minimum value is 0 (no maximum limit).

$game_system.message_duration = n
Sets the default effect duration to n frames for character fade-in. Minimum value is 0 (no maximum limit).

$game_system.message_fading = true
Enables fade-in effects for text display. Characters fade in with effect (default).

$game_system.message_fading = false
Disables fade-in effects for text display. Uses standard RGSS3 letter-by-letter drawing without effects.

Examples
                Ruby:       

1. # Set text speed to 60 characters per second
2. $game_system.message_speed = 60
4. # Set effect duration to 12 frames
5. $game_system.message_duration = 12
7. # Disable fade-in effects
8. $game_system.message_fading = false

复制代码

---

Escape Codes

This section explains proper escape code usage and bubble positioning for optimal dialog display results.

Insert escape codes directly into your message window text to control bubble positioning, text timing, database references, and special inline rendering. Escape codes can be placed anywhere in the message text and are processed before display.

Positioning Escape Code Usage

Insert these codes to control who the bubble targets and how it is positioned around the character.

• \bm[x]  Set bubble target character
  Sets the message window to position as a bubble above or below character x.
  
  
  
  • x = 0: Player character
    
  • x > 0: Map event with that ID (1, 2, 3, ...)
    
  • x < 0: Follower (party member) (-1, -2, -3, ...)
    
  
  
• \bmc[x]  Set bubble target character (chained mode)
  Same as \bm[x] but enables message chaining for continuous dialogue. Multiple consecutive "Show Text" commands will be merged into a single message window when this code is present.
  This tag is intended to be used in the first message of a chained sequence.
  
• \bmd[d]  Force bubble arrow direction
  Forces the arrow sprite direction. Must be used after \bm[x] or \bmc[x].
  
  
  
  • d = l or L: Left-pointing arrow
    
  • d = r or R: Right-pointing arrow
    
  
  
• \bmp[p]  Force bubble position
  Forces the window position relative to the character. Must be used after \bm[x] or \bmc[x].
  
  
  
  • p = a or A: Above character
    
  • p = b or B: Below character
    
  
  

Timing Escape Code Usage

Insert these codes to control text speed, effect duration, and pauses during message display.

• \sp[n]  Change text display speed
  Changes text display speed to n characters per second.
  
  
  
  • Setting n = 0 displays text instantly
    
  • Resets to default when the message window closes
    
  
  
• \ed[n]  Change effect duration
  Changes effect duration to n frames for character fade-in.
  
  
  
  • Resets to default when the message window closes
    
  
  
• \a  Disable instant text display
  Disables instant text display with the confirm key, preventing the player from skipping directly to fully drawn text.
  
• \.  Wait 15 frames (quarter-second pause)
  Adds a brief pause in text display.
  
• \|  Wait 60 frames (one-second pause)
  Adds a longer pause in text display.
  
• \w[n]  Wait n frames
  Waits for n frames during text display (1/60th of a second per frame).
  Useful for custom-timed pauses inside a single message.
  

Database Escape Code Usage

Insert these codes to reference database entries directly in your text. Available in all windows that render text.

• \nc[n]  Insert class name
  Inserts the name of Class ID n from the database.
  
• \ni[n]  Insert item name
  Inserts the name of Item ID n from the database.
  
• \nw[n]  Insert weapon name
  Inserts the name of Weapon ID n from the database.
  
• \na[n]  Insert armor name
  Inserts the name of Armor ID n from the database.
  
• \ns[n]  Insert skill name
  Inserts the name of Skill ID n from the database.
  
• \nt[n]  Insert state name
  Inserts the name of State ID n from the database.
  
• \ii[n]  Insert item icon and name
  Inserts the icon and name for Item ID n.
  
• \iw[n]  Insert weapon icon and name
  Inserts the icon and name for Weapon ID n.
  
• \ia[n]  Insert armor icon and name
  Inserts the icon and name for Armor ID n.
  
• \is[n]  Insert skill icon and name
  Inserts the icon and name for Skill ID n.
  
• \it[n]  Insert state icon and name
  Inserts the icon and name for State ID n.
  

Special Escape Code Usage

Insert these codes for special rendering behavior such as inline pictures. Available in all windows that render text.

• \pic[filename]  Draw picture
  Draws the picture from Graphics/Pictures with the given filename at the current text position.
  

Examples
                Ruby:       

1. \bm[1]Hello there!
2. \bmc[1]First line of dialogue.
3. \bm[1]\bmd[l]Arrow points left.
4. \bm[1]\bmp[b]Window forced below character.
5. \sp[60]Fast text!
6. \ed[12]Slower fade effect.
7. \aText that can't be skipped.
8. Hello\. There!
9. Wait\| for it...
10. \w[60]Pause for a second.
11. \ni[1]Item ID 1's name appears here.
12. \ii[1]Item ID 1's icon and name appear here.
13. \pic[some_pic]Show picture with message.

复制代码

---

Message Chaining

When using \bmc[x], multiple consecutive "Show Text" commands are automatically merged into a single bubble message window. This allows for longer dialogue sequences without manually managing long lines.

Chaining behavior

• A "Show Text" command whose text includes \bmc[x] merges its own text and any immediately following "Show Text" commands into one window
  
• Chaining stops when:
  
  
  
  • A non-"Show Text" command is encountered
    
  • A new message contains bubble positioning codes (\bm, \bmc, \bmd, \bmp)
    
  
  
• Face graphic, background, and position are taken from the first message in the chain
  

---

Bubble Positioning

When a bubble target is set via \bm[x] or \bmc[x], the window automatically:

• Positions itself above or below the character based on available screen space
  
• Centers horizontally on the character (or on the arrow sprite for narrow windows)
  
• Adjusts position to stay within screen bounds
  
• Displays an arrow sprite pointing to the character
  

For narrow windows (width < narrow_width), the window centers on the bubble arrow sprite rather than the character for better visual alignment.

Arrow direction is automatically determined by:

• Character facing direction (if facing left/right)
  
• Window position relative to the intended position
  
• Screen boundary constraints
  

You can override automatic behavior at any time using \bmd[] and \bmp[] escape codes.

---

Installation

• Copy the script to an open slot below ▼ Materials but above ▼ Main
  
• If using Hammy FF9 Windowskin System, place this script ABOVE the Windowskin System script
  
• If using Hammy Window Shadows, place this script ABOVE the Window Shadows script
  
• If using Hammy Window Headers, place this script ABOVE the Window Headers script
  
• If using Hammy FF9 Choice Window, place this script BELOW the Choice Window script
  
• Ensure your bubble arrow sprites are saved in Graphics/System with the names defined in the configuration section
  
• Recommended: Install Text Cache v1.04 by Mithran for optimal text rendering
  

---

Compatibility

This script is made strictly for RPG Maker VX Ace. It is highly unlikely that it will run with RPG Maker VX without adjusting.

---

License

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

---

Credits

This script includes code and concepts from:

• Jupiter Penguin's Message Effects script (Text fade effect)
  
• Yami's Pop Message script (Used as base for this script)
  
• Yanfly's Ace Message System script (Extended escape codes)
  

---

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

---

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