[XP Script] Animated Message Profiles

Instructions/Configuration

Code:
#==============================================================================

# ** Animated Message Profiles

#------------------------------------------------------------------------------

#    by DerVVulfman

#    Version 1.1

#    06-12-2025 (MM/DD/YYYY)

#    RGSS / RPGMaker XP

#==============================================================================

#

#                     > INSTRUCTION / CONFIGURATION PAGE <

#

#==============================================================================

#

#  INTRODUCTION:

#  =============

#

#  This is an add-on for the default message systems, or for those custom mes-

#  sage systems that are compliant.  It permits the game developer  to present

#  an image behind the default message window, and even allow for the image to

#  display cel animation properties.

#

#  Essentially, one can present characters that appear to be talking.

#

#

#------------------------------------------------------------------------------

#

#  INSTALLATION:

#  =============

#

#  At bare minimum,  place both the Instruction / Configuration and the Engine

#  scripts below Scene_Debug and above Main.  

#

#  sage systems that are compliant.  It permites the game developer to present  

#  The configuration page defines the actual profiles that are displayed,  the

#  location where they are shown, and if they are indeed animated.

#

#

#------------------------------------------------------------------------------

#

#  CONFIGURATION SETTINGS:

#  =======================

#

#  There is only one thing you can do  within the configuration section at the

#  bottom of this page.  And that is to create profiles that appear behind the

#  message window, whether they are animated or not.

#

#  Profiles are defined within a hash array.  Each of these profiles are iden-

#  tified by a key,  a string value that can be easily referenced. And each of

#  these profiles points to an array indicating where the profiles are placed,

#  the speed in which the profiles circulate between animated frames,  and the

#  list of one (or more) profile animation frames.

#  

#    Syntax:  DATA[key]  = [ xpos, ypos, speed, repeat img, img, img... img ]

#    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#    * key:    A string (in quotes) that separates it from other profiles.

#    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#    * xpos:   X-Position or Coordinates where the sprite(s) will draw.

#    * ypos:   Y-Position or Coordinates where the sprite(s) will draw.

#    * speed:  (in frames per second) The number of frames between each image.

#    * repeat: (a true/false value) Indicating if multiple images repeat

#    * img:    An image file (or set of file) in the Graphics\Pictures folder.

#

#  You can show one single image behind the message box with the following

#  example:

#  DATA["LunarSmile"]  =   [50,120,4,true'actor1']

#  -- or --

#  DATA["LunarSmile"]  =   [50,120,4,true'actor1']

#

#  Or, you can render a profile that draws three images in the pictures folder

#  in rapid succession like so:

#

#  DATA["ZeldaIsLaughing"]  = [50,120,4, true 'actor1','actor1a','actor1b']

#  -- if the animation continues until closed --

#  DATA["ZeldaIsLaughing"]  = [50,120,4, false 'actor1','actor1a','actor1b']

#  -- if the animation ends after all three images have been shown --

#

#

#------------------------------------------------------------------------------

#

#  MESSAGE WINDOW COMMANDS:

#  ========================

#

#  DISPLAYING THE PROFILE:

#

#  You may display a profile by using the Message Code:  \AB[key].

#

#  While the key must have quotes when defined in the module, the message

#  code's key value does not use quotes.

#

#  EX:  \ab[ZeldaIsLaughing]That is so funny!!!

#

#  The above example would display an animated profile with the defined

#  profile name of 'ZeldaIsLaughing' with text following immediately.

#

#  Alternately, you may use a script call prior to the display of the 

#  message with the 'set_profile' command like so:

#    @>Script: set_profile("ZeldaIsLaughing")

#    @>Text: That is so funny!!!!"

#

#                             -    -    -    -    -

#

#  HOLDING A PROFILE PRESENT

#

#  Normally, the image vanishes when you close a window. However, there may be

#  instances where a character is delivering multiple message windows of text

#  and you want the image to remain for the very next message.

#

#  For this, you need to apply the 'hold_profile' script call on the message

#  the contains the current profile.  This is to prevent it from erasing the

#  profile before the message ends.  This may appear like so:

#

#    @>Script: set_profile("ZeldaIsLaughing")

#    @>Script: hold_profile

#    @>Text: That is so funny!!!!"

#    @>Text: I am just laughing uncontrollably!!!!"

#

#  This example would use the same profile image for both messages.  However,

#  the below exaple would have its third message window without the profile.

#

#    @>Script: set_profile("ZeldaIsLaughing")

#    @>Script: hold_profile

#    @>Text: That is so funny!!!!"

#    @>Text: I am just laughing uncontrollably!!!!"

#    @>Text: Okay, I'm done now."

#

#  To continue with the image remaining in place, you must use the hold_profile

#  command before each message that you want to PREVENT the profile's erasure.

#

#                             -    -    -    -    -

#

#  SWAPPING A PROFILE PRESENT

#

#  For use in tandem with the above  'hold_profile' call,  this is a special

#  command that lets you switch  from one profile set to another without the

#  profile sprite erasing.  Unlike the hold_profile call, the 'swap_profile'

#  is run right before the new message is shown, and used in tandem with the

#  application of a new profile like so:

#

#    @>Script: set_profile("ZeldaIsLaughing")

#    @>Script: hold_profile

#    @>Text: That is so funny!!!!"

#    @>Script: swap_profile

#    @>Text: \AB[ZeldaCry]Waaahhh!"

#

#  This would provide a more seamless change in character behavior between

#  messages without the character needing to vanish and be redrawn.

#

#

#------------------------------------------------------------------------------

#

#  PAPERDOLL/BITMAP COMPATABILITY:

#  ===============================

#

#  paper doll (noun)

#   1. A paper or cardboard representation of a person usually in two dimen-

#      sions for children to play with. 

#   2. Figures cut out of paper or thin card, with separate clothes, also made

#      of paper, that are usually held onto the dolls by paper folding tabs.

#

#  Sometimes called a Visual Equipment script,  a paperdoll system is one that

#  can change a character's appearance based on the gear attached.

#

#  While Animated Message Profiles does not have  a built-in paperdoll system,

#  it contains an area where changes to a profile's appearance may be made. It

#  is within the Window_Message class, and is a specifically defined method to

#  grant a would-be scripter access to the bitmaps to adjust.

#

#  In short, I made a method a scripter can mess with. ^_^   

#

#  Line # 316:  update_profile_reader

#

#

#------------------------------------------------------------------------------

#

#  NOTES ON THE EXAMPLE CONFIG:

#  ============================

#

#  The two profiles are using images found in the 'Graphics\Profiles' folder.

#  And in that folder, there are only two files, "Ikuno1.png" & "Ikuno2.png".

#

#  You use multiple image files to creat an animation, and at least one file

#  to create a portrait if static and not animated.

#

#  The first profile is that of "Ikuno".  The profile will appear  at coordi-

#  nates  80,140  which would line up nice with the default message window if

#  it is at the bottom of the screen.  The speed is set to 4, which means the

#  individual cels change after 4 frames (in framerate).  It is set to false,

#  this indicates it will only cycle through all the animation cels once. And

#  it only has two images:  "Ikuno1.png" and "Ikuno2.png". This means that it

#  only plays the two images in sequence once... and stops.

#

#  The second profile is that of "Ikuno2". The profile will appear  at coordi-

#  nates  80,140  the same as the first. The speed is set to 0, however, this

#  is an illegal value  as the animation speed rate cannot go below '1'.  The

#  repeat value is set to 'true' so it will play every animation frame in its

#  set over and over aggain.  And it lists "Ikuno1", "Ikuno2" and "Ikuno1".

#

#  The third profile is that of "Ikuno3".  And this one is merely a static,

#  one frame/image profile.  Ergo, it will not appear animated.

#

#                             -    -    -    -    -

#

#  Example I used with the three profile settings:

#

#

#    @>Script: hold_profile

#    @>Text: \AB[Ikuno]What? Yeah, my mouth isn't moving.

#    @>Script: swap_profile

#    @>Text: \AB[Ikuno2]Yap Yap Yap!

#    @>Text: Peekaboo... you don't see me

#    @>Script: set_profile("Ikuno3")

#    @>Text: Now you do.

#

#

#------------------------------------------------------------------------------

#

#  VERSION HISTORY:

#  ================

#  YYYY MM DD

#  2025-06-08 - Original release

#  2025-06-12 - Fix: Disposed portrait sprite issue when exiting the field map.

#

#

#------------------------------------------------------------------------------

#

#  COMPATABILITY:

#  ==============

#

#  Designed for message systems compliant with RPGMaker XP's default system.

#  All default scripts aliased.

#

#

#==============================================================================

#

#  TERMS AND CONDITIONS:

#  =====================

#

#  Free to use,  even in commercial projects.  However, I will need some form

#  of due credit.

#

#

#==============================================================================

module Profiles

  # --------------------------------------------------------------------------

  DATA = {} # Do Not Touch

  # --------------------------------------------------------------------------

  # Profile w Key     X     Y     Spd   Repeat  Animation frames...

  # ===============   ====  ====  ====  ======  =============================

  DATA["Ikuno"]   = [ 80,   140,  4,    false,  'Ikuno1', 'Ikuno2' ]

  DATA["Ikuno2"]  = [ 80,   140,  0,    true,   'Ikuno1', 'Ikuno2', 'Ikuno1' ]

  DATA["Ikuno3"]  = [ 80,   140,  0,    false,  'Ikuno2' ]

end

Main Code

Code:
#==============================================================================

# ** Animated Message Profiles

#------------------------------------------------------------------------------

#    by DerVVulfman

#    Version 1.1

#    06-12-2025 (MM/DD/YYYY)

#    RGSS / RPGMaker XP

#==============================================================================

#

#                             > MAIN SYSTEM PAGE <

#

#==============================================================================

#==============================================================================

# ** RPG::Cache

#------------------------------------------------------------------------------

#  The module that loads each of RPGXP's graphic formats, creates a Bitmap

#  object, and retains it.

#==============================================================================

module RPG::Cache

  #------------------------------------------------------------------------

  # * Profile image

  #     filename : filename of the cached bitmap

  #------------------------------------------------------------------------

  def self.profiles(filename)

    begin

      self.load_bitmap("Graphics/Profiles/", filename)

    rescue 

      self.load_bitmap("Graphics/Profiles/", "")

    end

  end

end

#==============================================================================

# ** Game_System

#------------------------------------------------------------------------------

#  This class handles data surrounding the system. Backround music, etc.

#  is managed here as well. Refer to "$game_system" for the instance of 

#  this class.

#==============================================================================

class Game_System

  #--------------------------------------------------------------------------

  # * Public Instance Variables

  #--------------------------------------------------------------------------

  attr_accessor :profile_name             # Name of profile image data

  attr_accessor :profile_hold             # Profile do not erase flag

  attr_accessor :profile_swap 

  #--------------------------------------------------------------------------

  # * Alias Listings

  #--------------------------------------------------------------------------

  alias msg_profiles_game_system_initialize initialize

  #--------------------------------------------------------------------------

  # * Object Initialization

  #--------------------------------------------------------------------------

  def initialize

    #

    msg_profiles_game_system_initialize

    @profile_name       = nil

    @profile_hold       = false

    @profile_swap       = false

    #

  end

end

#==============================================================================

# ** Window_Message

#------------------------------------------------------------------------------

#  This message window is used to display text.

#==============================================================================

class Window_Message < Window_Selectable

  #--------------------------------------------------------------------------

  # * Alias Listings

  #--------------------------------------------------------------------------

  alias msg_profiles_windows_initialize initialize

  alias msg_profiles_windows_dispose dispose

  alias msg_profiles_windows_terminate_message terminate_message

  alias msg_profiles_windows_refresh refresh

  alias msg_profiles_windows_update update

  #--------------------------------------------------------------------------

  # * Original methods Aliased

  #--------------------------------------------------------------------------

  #--------------------------------------------------------------------------

  # * Object Initialization

  #--------------------------------------------------------------------------

  def initialize

    #

    msg_profiles_windows_initialize               # Run the original method

    initialize_message_profile                    # Create profile data

    #

  end

  #--------------------------------------------------------------------------

  # * Dispose

  #--------------------------------------------------------------------------

  def dispose

    #

    @profile.dispose                              # Dispose of profile sprite

    msg_profiles_windows_dispose                  # Run the original method

    #

  end

  #--------------------------------------------------------------------------

  # * Terminate Message

  #--------------------------------------------------------------------------

  def terminate_message

    #

    msg_profiles_windows_terminate_message        # Run the original method

    terminate_message_profile                     # Terminate profiledata

    #

  end

  #--------------------------------------------------------------------------

  # * Refresh

  #--------------------------------------------------------------------------

  def refresh

    #

    refresh_message_profile                       # Perform profile refresh

    msg_profiles_windows_refresh                  # Run the original method

    #

  end

  #--------------------------------------------------------------------------

  # * Frame Update

  #--------------------------------------------------------------------------

  def update

    #

    update_message_profile if @contents_showing   # Perform update if showing

    msg_profiles_windows_update                   # Run the original method

    #

  end

  #--------------------------------------------------------------------------

  # * New Content

  #--------------------------------------------------------------------------

  #--------------------------------------------------------------------------

  # * Object Initialization : Creation of clear profile data variables

  #--------------------------------------------------------------------------

  def initialize_message_profile

    #

    @profile          = Sprite.new                # Create the profile sprite

    @profile.z        = self.z - 5                # Set it behind the message

    @msgprofile       = []                        # Create empty filename array

    @msgwait_count    = 0                         # Reset the wait count

    @profilerepeat    = true                      # Reset repeat function

    #

  end

  #--------------------------------------------------------------------------

  # * Terminate Message : Resetting of profile

  #--------------------------------------------------------------------------

  def terminate_message_profile

    #

    terminate_message_profile_erase               # Clear profile image

    $game_system.profile_hold = false             # Clear profile hold flag

    #

  end

  #--------------------------------------------------------------------------

  # * Terminate Message : Erasing of profile image and data

  #--------------------------------------------------------------------------

  def terminate_message_profile_erase

    #

    return if $game_system.profile_hold           # Clear profile hold

    return if @profile.nil?                       # Exit if profile set to nil

    return if @profile.disposed?                  # Exit if profile disposed

    @profile.visible = false                      # Make profile sprite hidden

    unless @profile.bitmap.nil?                   # Only if there is a bitmap

      @profile.bitmap.dispose                     # ..dispose of the bitmap

    end

    @profile.bitmap = nil                         # Nil out the profile bitmap

    @msgprofile = []                              # Clear the filename array

    $game_system.profile_name = nil               # Erase the profile name

    @profilerepeat            = true

    #

  end

  #--------------------------------------------------------------------------

  # * Refresh : Acquiring and setting profile data name and updating message

  #--------------------------------------------------------------------------

  def refresh_message_profile

    #

    return if $game_temp.message_text.nil?        # Exit if there's no message

    text = $game_temp.message_text                # Get the message text  

    text.gsub!(/\\[Aa][Bb]\[(.*?)\]/) do          # Substitute the \ab code

      $game_system.profile_name = $1              # ..and set the profile name

      ""

    end

    $game_temp.message_text = text                # Replace the message text

    #

  end

  #--------------------------------------------------------------------------

  # * Frame Update:  Profile display and animation

  #--------------------------------------------------------------------------

  def update_message_profile 

    #

    unless $game_system.profile_swap              # Unless swapping profiles

      return if @profilerepeat == false           # Exit method on no repeat

    end

    #

    if @msgwait_count > 0                         # If a wait count exists

      @msgwait_count -= 1                         # ..reduce the wait count

      return                                      # ..and exit the method 

    end

    #

    update_profile_generator                      # Run the profile generator

    #

    return if @bitmap.nil?                        # Exit if not valid bitmap 

    return if @profile.bitmap.nil?                # Exit if no profile bitmap

    return if @pattern.nil?                       # Exit if no defined pattern

    return if @sprite_numbers.nil?                # Exit if no sprite number set

    return if @msgprofile.nil?                    # Exit if no configed profile 

    #

    @pattern = (@pattern + 1) % @sprite_numbers   # Set animation pattern

    if @pattern == (@sprite_numbers-1)            # If at end of loop

      @profilerepeat = @msg_repeat                # .. determine if repeating

    end

    #

    sx = @pattern * @cw                           # Define which image to use

    src_rect = Rect.new(sx, 0, @cw, @ch)          # Acquire the sprite image

    @profile.bitmap.clear                         # Clear the sprite bitmap

    @profile.bitmap.blt(0, 0, @bitmap, src_rect)  # Apply the new bitmap

    @msgwait_count  = @msg_count                  # Reset the wait count 

    @profile.visible = true                       # Show the provile sprite 

    #

  end

  #--------------------------------------------------------------------------

  # * Update:  Generate the Profile Animation Strip

  #--------------------------------------------------------------------------

  def update_profile_generator

    #

    return if $game_system.profile_name.nil?       # Exit if no profile name

    return if $game_system.profile_name == ""      # Exit if profile name empty

    name   = $game_system.profile_name             # Get the profile name

    #

    return unless update_profile_empty?            # Exit if exist or is to swap

    return if Profiles::DATA.nil?                  # Exit if no configured data

    return unless Profiles::DATA.has_key?(name)    # Exit if no profile configed

    #

    if $game_system.profile_swap == true           # If profiles are swapped

      @profilerepeat = true                        # Ensure repeat at restart

    end

    #

    unless $game_system.profile_swap == true      # If profiles are not swapped

      @profile        = Sprite.new                # ..make a new profile sprite

    end

    #

    @msgprofile     = Profiles::DATA[name]        # Acquire configured profile 

    @profile.z      = self.z - 5                  # Set profile behind message

    @profile.x      = @msgprofile[0]              # Set x-coordinate of profile

    @profile.y      = @msgprofile[1]              # Set y-coordinate of profile

    @msg_count      = @msgprofile[2]              # Set Message wait count

    @msg_repeat     = @msgprofile[3]              # Set Message repeat flag

    files           = @msgprofile[4]              # Set first file in list

    @msg_count      = 1 if @msg_count < 1         # Set wait count minimum

    @pattern        = 0                           # Reset profile pattern

    #

    @sprite_numbers = @msgprofile.size-4          # Get size of configed profile

    bitmap          = RPG::Cache.profiles(files)  # Set first bitmap

    @cw             = bitmap.width                # Get profile strip width

    @ch             = bitmap.height               # Get character height

    width           = @cw * @sprite_numbers       # Get single-image width

    @bitmap         = Bitmap.new(width, @ch)      # Create simgle-image bitmap

    #

    for i in 0...@sprite_numbers                  # Cycle through sprites

      src = update_profile_reader(@msgprofile,i)  # Acquire individual sprite

      src_rect    = Rect.new(0, 0, @cw, @ch)      # Acquire sprite rectangle

      @bitmap.blt(@cw*i, 0, src, src_rect)        # Blit sprite

    end

    #

    @profile.bitmap  = Bitmap.new(@cw, @ch)       # Create clean profile bitmap

    @profile.visible = true                       # Make visible

    $game_system.profile_swap = false             # And clear swap flag

    #

  end

  #--------------------------------------------------------------------------

  # * Update:  Testing if there is no image, or if image is to be replaced.

  #--------------------------------------------------------------------------

  def update_profile_empty?

    #

    if $game_system.profile_swap == true          # If swapping profiles set

      return true                                 # ..Exit method true

    end

    if @profile.bitmap.nil?                       # If there is no bitmap

      return true                                 # ..Exit method true

    end

    return false                                  # Exit method false

    #

  end

  #--------------------------------------------------------------------------

  # * Update:  Acquire each Profile from the Animation Strip

  #     name  : used to identify the profile for possible editing

  #     index : index within the animation strip

  #--------------------------------------------------------------------------

  def update_profile_reader(name, index)

    #

    # Acquire the cached bitmap

    src_bitmap  = RPG::Cache.profiles(@msgprofile[index+4])

    # Possible edits to the bitmap may go here... before the returned bitmap

    return src_bitmap

    #

  end

end

#==============================================================================

# ** Interpreter

#------------------------------------------------------------------------------

#  This interpreter runs event commands. This class is used within the

#  Game_System class and the Game_Event class.

#==============================================================================

class Interpreter

  #--------------------------------------------------------------------------

  # * Set Message Profile outside of Show Text box

  #     key : key as defined in the Profiles Module

  #--------------------------------------------------------------------------

  def set_profile(key=nil)

    #

    if key.nil?                                   # If no valid key supplied

      $game_system.profile_name = nil             # ..set erased profile name

      return                                      # ..and exit method.

    end

    unless Profiles::DATA.has_key?(key)           # If no valid profile given

      $game_system.profile_name = nil             # ..set erased profile name

      return                                      # ..and exit method.

    end

    $game_system.profile_name = key               # Set the profile name

    #

  end

  #--------------------------------------------------------------------------

  # * Set image hold/freeze to use in next message

  #--------------------------------------------------------------------------

  def hold_profile

    #

    $game_system.profile_hold = true              # Set the profile hold flag

    #

  end

  #--------------------------------------------------------------------------

  # * Set sprite frozent to allow profile image and animation swapping

  #--------------------------------------------------------------------------

  def swap_profile

    #

    $game_system.profile_swap = true              # Set the profile swap flag

    #

  end

end