RSTW: Reedo's Scrolling Text Window

じ☆ve冰风

Reedo's Scrolling Text Window (RSTW)

Version 1.0

September 24, 2013

By Reedo

References

None. This is an original script by Reedo.

However, this idea came about after I read this script request, having just finished work on my quest journal scene.  So I decided to dig deeper into Window classes and this is the result.

Description

This script provides a simple window that supports a large amount of scrolling, formatted text (that is, text which supports the game's slash-commands for color, font size, etc.).  The text is loaded from a plain text file and offers a couple of different processing options.  The script also include a new scene, available from a menu option, which shows a full-screen text window and the loaded text file.  The user can scroll through the text at two different speeds, or jump to the top or bottom.

The scene can load text in "block mode" allowing the script to "count paragraphs" and only display a certain number of text-blocks based on a game variable or scene property.  In this way it is very easy to write out a series of text entries for display in the scene and use a game variable to control how many of the entries are actually shown.

Features

• New scene with single-window scrolling text area.
  
• Menu option for displaying scene, or various script calls.
  
• Scene loads plain text file automatically when shown.
  
• Text file supports game message slash-command mark-up.
  
• Text is scrolled using up/down arrows, sped up with "Z" key (A button),
  and can jump to top or bottom with page up (L) and page down ®.
  
• Text can be loaded in "Block mode" to only read up to a specified
  number of text blocks (paragraphs, separated by a blank line).
  
• Block mode index (max blocks shown) can be controlled automatically
  via an associated game variable value, or by script using a static
  property on the scene itself.
  
• Scene can always be shown "own demand" via script calls with the
  supplied message text, even if a text file was loaded.
  
• Text files can be up to 15K or so with reasonable performance.
  (the upper limit of text size is not fully tested)
  
• The Window_Reedo_ScrollText class can be reused by other scenes.
  
• The Scene_Reedo_ScrollText class can be used as a basis for other scenes. 
  

Known Bugs

None at this time.

Please report any bugs found.

Requirements

Optional text file containing text to display.

Installation

Plug-and-Play

Just insert a new script directly under Materials, name it RSTW, and paste in the script code.

Compatibility

Should be compatible with most other scripts.

Configuration

There are just a few user options that you can modify to determine how you want to use this script.

Set USE_MENU_COMMAND true or false to enable the menu command for showing the scene. If you don't want to use the in-game menu command, you can also call the static method Scene_Reedo_ScrollText.display(text) to show the scene immediately with the provided text, or use the standard script commands for loading a new scene and the show_text(text) method on the scene instance.

The MENU_COMMAND_NAME option sets the word displayed in the game menu when the use menu option is set to true.

Setting LOAD_ON_START to true tells the script to execute the specified processing mode whenever the scene is shown.  Since the text is loaded whenever the scene is shown, it would be easy to have a script that modifies the text file at run-time to change the displayed contents.

The LOAD_MODE option must be set to one of the RSTW_LoadMode values of NONE, ALL, BLOCK, or CUSTOM.

The NONE option will simply skip any file loading, while the CUSTOM option will execute the read_custom() method on the scene.  This method does nothing in the base scene, but another custom scene could inherit this one and make use of the custom text loading feature.

The ALL option will simply read all of the text in the text file and load it into the scene.  This text is easily edited in Notepad and can parse the standard slash commands for colors, font size, word replacement, etc.

The BLOCK option is similar to the ALL option, but the loading process counts blank lines in the text file to find individual paragraphs, or "blocks", of text.  The block index value is then used to determine how many of the available blocks to actually show in the scene.  This allows the contents of the text file to easily unfold as the game progresses.

For the BLOCK_INDEX_VARIABLE value, you have two choices.  You can provide the Id number of a game variable and then the script will automatically use the value of this variable as the block index.  Or you can set this value to nil and the scene will use its own internal block index (there is only one block index for all scenes) that you manipulate via script commands.

Set the TEXT_FILE option to the name and path of the text file to load.  The Data folder of your game project is a good place to put this file.

The FILE_READ_ERROR message is displayed in the scene whenever there is an error opening or processing the text file.  You can set this message to whatever you choose because hopefully it will not be shown in your game.   


Finally you can adjust the WINDOW_SCROLL_SPEED if desired.  Note that this is the "fast" speed, so the normal scroll speed is half of this value.

Example Text File

Here is an example of what a text file might look like.  This file has multiple blocks, each representing a stage of progress within a game. The script that uses this file would have a game variable set to control the progress.  As the value of the variable increases from zero, additional blocks of the text file are shown when the scene is opened.

Spoiler\{\{\C[12]        Progress Journal\}\C[0]\C[14]The Journey Begins\C[0]\}You begin your journey through the world, only tofind that there is much you still need to learn.The first thing you have to do is find all ofthe trainers in the town so that you can learnhow to be a grand adventurer.\{\C[14]Testing Your Skills\}\C[0]Having learned all about a great many things fromeach of the trainers with whom you visited, youare now tasked with venturing out into the wildto find the entrance to the gloomy cave andretrieve a Gloomshroom which can only be found inthe cave's deepest depths.\{\C[14]Stew and Brew\}\C[0]You proved that you can use your adventuringskills by retrieving a Gloomshroom from deep withinthe gloomy cave. Now it is time to learn again!You are going to use that mushroom to learn tomake food and drink items.\{\C[14]Follow the Fat Cat\}\C[0]Now that you know how to make tasty food andbeverage, you can use that knowledge to makesnacks that animals will like. Use your new foundknowledge to capture a cat as a pet.



When loaded into the scene in game, this text file looks like:

Spoiler[url=https://forums.rpgmakerweb.com/attachments/rstw1-jpg.8402/][/url]



I've copied these blocks until there were 55 of them.  It made a 15K file.  While there is a noticeable delay of about one second when opening the scene, the performance afterward is fine and that small delay should generally be acceptable.

Script

Here is the complete RSTW script:

Spoiler#################################################################################  RSTW - Reedo's Scrolling Text Window##  Version 1.0##  September 24, 2013##  By Reedo#################################################################################  REFERENCES####  None.  This is an original script by Reedo.#################################################################################  FEATURES####  + New scene with single-window scrolling text area.##  + Menu option for displaying scene, or various script calls.##  + Scene loads plain text file automatically when shown.##  + Text file supports game message slash-command mark-up.##  + Text is scrolled using up/down arrows, sped up with "Z" key (A button),##    and can jump to top or bottom with page up (L) and page down (R).##  + Text can be loaded in "Block mode" to only read up to a specified##    number of text blocks (paragraphs, seperated by a blank line).##  + Block mode index (max blocks shown) can be controlled automatically##    via an associated game variable value, or by script using a static##    property on the scene itself.##  + Scene can always be shown "own demand" via script calls with the##    supplied message text, even if a text file was loaded.##  + Text files can be up to 15K or so with reasonable performance.##    (the upper limit of text size is not fully tested)##  + The Window_Reedo_ScrollText class can be reused by other scenes.##  + The Scene_Reedo_ScrollText class can be used as a basis for other scenes.###################################################################################  COMPATIBILITY####  Should be compatible with most other scripts.#################################################################################  REQUIREMENTS####  None.##  Optional text file containing text to display.#################################################################################  INSTALLATION####  Plug-and-play####  Insert below Materials, above other add-on scripts.#################################################################################  RIGHTS & RESTRICTIONS####  As with most Reedo scripts, this script is free to re-use, as-is, ##  in personal, educational, and commercial RPGVX Ace development projects, ##  providing that:  this script is credited in writing displayed readily ##  to the user of the final compiled code assembly.####  Reedo retains all rights of intellect and ownership.##  You forego all rights of warranty by utilizing this script.#################################################################################  Values from this class are used for settings in the module below.##  Do not modify this class directly.class RSTW_LoadMode  NONE = 0    # Specifies that the loading process do nothing.  ALL = 1     # Reads the entire text file into the window.  BLOCK = 2   # Reads the text file in blocks (up to a blank line) for the              #   maximum number of blocks defined by the block index.  CUSTOM = 3  # Allows for custom loading by overriding read_custom.end#################################################################################  USER OPTIONS###############################################################################module RSTW  # Display a command in the menu for opening the scene.  USE_MENU_COMMAND = true  # The name of the command when displayed.  MENU_COMMAND_NAME = "Journal"      # True to load the specified text file whenever the scene opens.  LOAD_ON_START = true  # The processing mode used to load the text file.  LOAD_MODE = RSTW_LoadMode::BLOCK  # The Id of the game variable used to store the index of the last displayed  # text block when using block-mode processing, or nil to use the scene's  # static block_index property.  BLOCK_INDEX_VARIABLE = nil    # The name of the text file to load when LOAD_ON_START is true.  TEXT_FILE = "Data/Journal.txt"  # The message displayed in the window when the text file fails to load.  FILE_READ_ERROR = "[ERROR READING FILE]"  # The fastest scroll speed for the window; normal scroll is half this value.  WINDOW_SCROLL_SPEED = 8end#################################################################################  MAIN SCRIPT#################################################################################  EDITS BEYOND THIS POINT ARE AT YOUR OWN RISK!!!################################################################################ Base class override to add menu commandclass Window_MenuCommand  alias rstw_wmc_add_original_commands add_original_commands  def add_original_commands    rstw_wmc_add_original_commands    add_command(RSTW::MENU_COMMAND_NAME, :RSTWCommand, main_commands_enabled) if RSTW::USE_MENU_COMMAND  endend# This is the core scrolling text window which can be reused in other scenes.class Window_Reedo_ScrollText < Window_Base  attr_accessor :text  attr_accessor :text_scroll_speed  attr_accessor :terminate_at_end  def initialize    super(0, 0, Graphics.width, Graphics.height)    self.arrows_visible = true    @handler = {}    @text = ""    @text_scroll_speed = RSTW::WINDOW_SCROLL_SPEED    @terminate_at_end = false    @scroll_pos = 0    @scroll_on = false    @scroll_dir = 1    hide  end  def update    super    update_message if @text    process_handling  end    def process_handling    @scroll_on = false    return unless open? && active    return process_ok       if ok_enabled?        && Input.trigger?
C)    return process_cancel   if cancel_enabled?    && Input.trigger?
    scrollDelta = contents.height - height + standard_padding * 2    if Input.trigger?
L) && (@scroll_pos > 0) then      @scroll_pos = 0    end    if Input.trigger?
R) && (@scroll_pos < scrollDelta) then      @scroll_pos = scrollDelta    end    if Input.press?
UP) && (@scroll_pos > 0) then      @scroll_on = true       @scroll_dir = -1      return    end    if Input.press?
DOWN) && (@scroll_pos < scrollDelta) then      @scroll_on = true      @scroll_dir = 1      return    end  end    def ok_enabled?    handle?
ok)  end  def cancel_enabled?    handle?
cancel)  end  def process_ok    if current_item_enabled?      Sound.play_ok      Input.update      deactivate      call_ok_handler    else      Sound.play_buzzer    end  end  def call_ok_handler    call_handler
ok)  end  def process_cancel    Sound.play_cancel    Input.update    deactivate    call_cancel_handler  end    def call_cancel_handler    call_handler
cancel)  end  def set_handler(symbol, method)    @handler[symbol] = method  end  def handle?(symbol)    @handler.include?(symbol)  end  def call_handler(symbol)    @handler[symbol].call if handle?(symbol)  end  def start_message(messageText = nil)    @text = messageText if messageText    refresh    show  end  def refresh    reset_font_settings    update_all_text_height    create_contents    draw_text_ex(4, 0, @text)  end  def update_all_text_height    @all_text_height = 1    convert_escape_characters(@text).each_line do |line|      @all_text_height += calc_line_height(line, false)    end    reset_font_settings  end  def contents_height    @all_text_height ? @all_text_height : super  end  def update_message    @scroll_pos += (scroll_speed * @scroll_dir) if @scroll_on     self.oy = @scroll_pos    terminate_message if ((@scroll_pos >= contents.height) && @terminate_at_end)  end  def scroll_speed    @text_scroll_speed * (show_fast? ? 1.0 : 0.5)  end  def show_fast?    (Input.press?
A) || Input.press?
C))  end  def terminate_message    @text = nil    hide  endend# Base class override to provide menu option handlerclass Scene_Menu  alias rstw_sm_create_command_window create_command_window  def create_command_window    rstw_sm_create_command_window    @command_window.set_handler
RSTWCommand,    method
command_reedo_show_stw))  end    def command_reedo_show_stw    SceneManager.call(Scene_Reedo_ScrollText)  endend# The custom scene class.  This class can be extended to make other scenes that# use the scrolling text window. Additional windows can be added as needed.class Scene_Reedo_ScrollText < Scene_Base  @@selfshow = false  @@selftext = ""  @@block_index = 0    def self.display(text)    @@selfshow = true    @@selftext = text    SceneManager.call(Scene_Reedo_ScrollText)  end    def self.block_index    @@block_index  end  def self.block_index=(value)    @@block_index = value  end    def start    super        create_background    create_text_window    if @@selfshow      @@selfshow = false      show_text(@@selftext)    else      show_text(load_scene_text) if RSTW::LOAD_ON_START    end  end  def load_scene_text    case RSTW::LOAD_MODE    when RSTW_LoadMode::NONE    when RSTW_LoadMode::CUSTOM      read_custom    when RSTW_LoadMode::ALL      read_all_text    when RSTW_LoadMode::BLOCK      read_block_text    end  end    # override to provide custom text loading when scene begins  # method should return a string containing the text to display  # should provide acceptable performance up to 10,000 characters  def read_custom  end    def read_all_text    result = ""    begin      File.open(RSTW::TEXT_FILE) do |file|        result = file.read      end    rescue      result = RSTW::FILE_READ_ERROR    end    return result  end    def read_block_text    result = ""    max = $game_variables[RSTW::BLOCK_INDEX_VARIABLE] if RSTW::BLOCK_INDEX_VARIABLE    max = @@block_index if !max    index = 0    begin      File.open(RSTW::TEXT_FILE) do |file|        file.each_line do |line|          break if index > max          result += line #+ "\n"          index +=1 if line == "\n"        end      end    rescue      result = RSTW::FILE_READ_ERROR    end    return result  end    def terminate    super    dispose_background  end  def create_background    @background_sprite = Sprite.new    @background_sprite.bitmap = SceneManager.background_bitmap    @background_sprite.color.set(16, 16, 16, 128)  end  def dispose_background    @background_sprite.dispose  end  def create_text_window    @text_window = Window_Reedo_ScrollText.new    @text_window.set_handler
cancel,    method
return_scene))  end    def show_text(text)    @text_window.start_message(text)    @text_window.activate  end    def close_text    @text_window.terminate_message  endend



Extensibility

The Window_Reedo_ScrollText class is a generic window for scrolling text.  This window is designed with the same pattern as other game windows and can be easily reused by other scene scripts.  It is intended for use by other scene developers and the functionality of the included scene is a usable demonstration of how the window can be used.

The Scene_Reedo_ScrollText class is a basic custom scene implementation which can be extended or used as a model for other custom scenes.  Additional windows can be added and the instance of Window_Reedo_ScrollText can be resized and repositioned to create a composite window scene.

The two simple overrides of game menu classes also lay the foundation for easy addition of other custom menu options.

Summary

With this script you can easily add a scrolling text window for showing general information or revealing a story line using an in-game control variable or script commands.  The window and scene classes in this script are also easily reused in other custom scenes.

As always, comments and suggestions are welcome.


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