Skip to content

Latest commit

 

History

History
500 lines (403 loc) · 26.2 KB

README.md

File metadata and controls

500 lines (403 loc) · 26.2 KB
Raw

RGSS Script Editor

This extension should be used for development purposes only!

Table of Contents

Introduction

This is an extension for Visual Studio Code that makes VSCode usable as the script editor for any RPG Maker editor based on the RGSS framework:

  • RPG Maker XP
  • RPG Maker VX
  • RPG Maker VX Ace

In a nutshell, this extension extracts each script from the bundle file that RPG Maker uses into individual ruby files. Once the extraction is done, it creates a backup of the original bundle file (Scripts.rxdata, Scripts.rvdata or Scripts.rvdata2) as a security measure, subsequently it overwrites the original bundle file with a script loader bundle file that loads ruby scripts inside a relative folder based on a text file that dictates the loading order.

Since this extension uses a different approach for loading scripts, you can use the RPG Maker editor and edit scripts in Visual Studio Code at the same time without worrying about RPG Maker overwriting the bundled file with outdated data.

Long explanation

RPG Maker loads all data (database, maps, scripts...) at startup when the editor is launched, so you can modify anything of the project and save it into their appropiate data file (scripts are saved into: Scripts.rxdata, Scripts.rvdata or Scripts.rvdata2), this happens with every modification you do inside the editor.

The problem is that RPG Maker does not save these modifications individually, all files are saved at the same time, this means that even if you do not change anything in the game's scripts and modified something else (for example: the database) all scripts will be overwritten with the initial data that was loaded.

This produces an incompatibility with any external script editor or Visual Studio Code extension that works by overwriting the Scripts bundle data file since the editor will overwrite it everytime the project is saved, so the easy solution is not working with the RPG Maker editor and the external script editor at the same time.

This extension tries to circumvent this limitation by overwriting the script bundle data file with a script loader that will load external scripts inside a relative path within the project's folder, this way you can work on your project inside the RPG Maker at the same time you are creating/modifying the game's scripts externally.

It also allows to specify a load order, skip specific scripts and load all Ruby files inside a folder recursively if you want to organize the scripts inside subfolders, the script loader will read the load_order.txt file and load each script/folder until end of line is reached.

As a security measure, the extension will not allow overwriting the script bundle file (Scripts.rxdata, Scripts.rvdata or Scripts.rvdata2) with the script loader if there are still scripts inside of it that have not yet been extracted.

Features

  • Workspace Support
    • You can change the active folder easily in a workspace.
    • If an important setting is modified, it will re-open the current workspace folder automatically.
  • Run Game
    • You can run the game within VSCode using a customizable key shortcut (F12 by default)
    • Both test (debug) and console (RPG Maker VX Ace) modes are supported.
    • Optionally, custom arguments can be used instead of the default ones.
    • You can also specify a custom path to the game, in case you want to run an MKXP-Z executable.
    • You can set the behavior of the extension when running the game executable:
      • Nothing: Does nothing, this how RPG Maker Editor behaves (default)
      • Kill and Run: Kills the current game process and runs it again
      • Allow Multiple: Allows the user to start more than one game process at the same time
  • Backup Creation
    • A back up of the original scripts bundle file will always be created upon script extraction
      • Thus, the script loader will be created
    • You can freely create a bundle file of all scripts as a back up at any time.
      • All back ups are named with a timestamp of when they were created.
      • The back up bundle file will include all editor sections (whether they are enabled or disabled)
    • All back ups are saved into the specified folder in the extension's settings.
  • Scripts Extraction
    • You can extract all scripts inside the bundle file to a custom folder within the project's folder.
    • Each RPG Maker script entry will be converted into the appropiate equivalent for the extension's script editor in the process.
      • Every nameless entry with no code will be treated as a separator.
      • Any other entry, will be treated as a script file.
      • An entry with no code besides an specific comment this extension creates will be treated as a folder.
    • If you are extracting a bundle file previously created by this extension, the tree structure will be recreated.
  • Bundle File Creation
    • This process is heavily recommended when sharing a copy of your game.
    • You can create an RPG Maker bundle file (Scripts.rxdata, Scripts.rvdata or Scripts.rvdata2) using the current enabled scripts.
      • If you do not want to include a folder or a certain script in the final bundle file, you can just uncheck them and it will be ignored when creating the bundle file
    • You can create a new bundle file from the selected scripts on the extension's tree view
      • You must select manually all editor sections in the tree view you want to include in the package file
    • The bundle file is always created keeping the order and tree structure the user creates (subfolders, separators...)
      • You can later rebuild the tree from any bundle file created by this extension (as well as the loading order) if it is not improperly modified by the user.
  • Import Bundle File
    • You can import all scripts from an RPG Maker scripts bundle file into the extension.
    • Optionally, you can set whether the import operation can overwrite existing scripts or not.
  • Script Loader
    • The game will load all scripts files individually based on a load order.
    • Any script can be ignored and not loaded when the game runs.
      • Instead of the old way of commenting the whole script code or deleting it, you can disable it and it won't be loaded.
    • You can reset this script loader on runtime raising an specific exception (EXPERIMENTAL)
  • Script Editor
    • This extension enables a view in VSCode where you can create a tree of script sections and perform several operations on them:
      • Create new sections.
        • You can create new sections of an specific type, the current types available are:
          • Script: Self-explanatory.
          • Folder: You can use it to organize scripts inside folders, all folders are collapsable.
          • Separator: An empty section (no name, no icon...) used to separate sections.
      • Enable/Disable sections.
        • You can enable or disable any section or group of sections.
          • If a section is enabled, it will be loaded when the game runs.
          • If a section is disabled, it will be ignored.
      • Delete sections.
        • Any section can be deleted along with all of its children.
        • Keep in mind that this action is irreversible!
      • Rename sections.
        • You can rename sections.
        • All changes will be reflected in its children sections.
      • Move sections.
        • The tree can be arranged in any order desired.
        • The load order is defined by the order of the editor, before running the game.
      • Collapse/Expand sections.
        • You can expand or collapse folder sections.
      • Reveal active script on the tree view
      • Reveal sections on VS Code explorer
        • You can reveal a script section on the VS Code built-in explorer
      • Reveal sections on the OS file explorer
        • You can reveal a script section on the operating system file explorer
      • Editor Mode.
        • There are two editor modes available, you can switch freely between them:
          • Merge Mode: Merges any supported section with the section in which they are dropped.
          • Move Mode: Moves the selected sections to the next position of the section where they are dropped inside the same parent section.
  • Game Exception Processing
    • This extension can process the exception that killed the game in the last test game session.
    • The extension backtrace will be shown in a markdown file besides the active editor.
    • VSCode built-in peek menu will be used to show each backtrace location.

Screenshots

Extension Editor View

Editor View

Editor View 2

Editor View Collapsed

Run Game Process

Run Game

Game Exception Processing

Game Exception

Requirements

Windows

Linux

  • Visual Studio Code
  • Wine (preferably the latest version)
    • Wine should available on your system, which will be used to run the Windows game executable.
    • You can check if Wine is installed in your system with: wine --version
    • IMPORTANT: If you use MKXP-Z for Linux you won't need to install Wine.
      • Wine is only required for RPG Maker Windows executables.
    • You can also use any other Wine fork with this extension.

macOS

Download Links

Extension Commands

The commands in this list that has the "Usable only in the tree view editor" are commands that do not work if called from the command palette.

These commands are identified with ellipses (such as the command "Create Section...").

  • rgss-script-editor.setProjectFolder
    • Sets the extension's working folder to the selected project folder
  • rgss-script-editor.openProjectFolder
    • Opens the current project folder in the OS file explorer
  • rgss-script-editor.extractScripts
    • Extracts all valid script files from the RPG Maker Scripts bundle file
    • You can extract the script files as many times as you want if you have included new scripts in it
    • Beware that the script files inside the bundle file will overwrite existing files on the extracted scripts folder
  • rgss-script-editor.importScripts
    • Imports all scripts available inside a RPG Maker bundle scripts file
    • You can choose to whether let the extension overwrite existing scripts or not
    • Useful to import scripts previously exported using this extension
  • rgss-script-editor.createScriptLoader
    • Creates the script loader bundle file
    • The command will fail if there are valid script files inside the bundle file
    • You can use this command to recreate the script loader in case it was modified or updated in a future version of the extension
  • rgss-script-editor.createBundleFile
    • Creates a bundle file with the current enabled sections (scripts/folders...) in the tree view
    • The bundle file created keeps the same load order and tree structure as the tree view
  • rgss-script-editor.createBackupBundleFile
    • Creates a backup bundle file with all sections (scripts/folders...) in the tree view
    • All sections are included, whether they are enabled or disabled
    • The bundle file is automatically saved on the extension's back up folder
    • The bundle file created keeps the same load order and tree structure as the tree view
  • rgss-script-editor.createSelectedBundleFile
    • Creates a bundle file with the selected scripts in the tree view
    • All selected sections are included, whether they are enabled or disabled
    • The bundle file created keeps the same load order and tree structure as the tree view
  • rgss-script-editor.runGame
    • Runs the game
  • rgss-script-editor.processGameException
    • Process the last game exception that was captured by the extension
  • rgss-script-editor.chooseEditorMode
    • Chooses the current tree view editor mode
    • Each mode makes the tree view editor behave differently
  • rgss-script-editor.openLoadOrder
    • Opens the load order file in the VSCode editor
  • rgss-script-editor.sectionCreate
    • Creates a new section on the tree view
    • Usable only in the tree view editor
  • rgss-script-editor.sectionDelete
    • Deletes an existing section on the tree view
    • Usable only in the tree view editor
  • rgss-script-editor.sectionRename
    • Renames an existing section on the tree view
    • Usable only in the tree view editor
  • rgss-script-editor.sectionMove
    • Move section/s on the tree view
    • Usable only in the tree view editor
  • rgss-script-editor.sectionToggleLoad
    • Toggles the load status (enabled/disabled) of the section/s on the tree view
    • Usable only in the tree view editor
  • rgss-script-editor.sectionToggleCollapse
    • Toggles the collapsible status (collapsed/expanded) of the section/s on the tree view
    • Usable only in the tree view editor
  • rgss-script-editor.sectionRevealInVSCodeExplorer
    • Reveals the selected section (script/folder) in the VSCode explorer tab
    • Usable only in the tree view editor
  • rgss-script-editor.sectionOpenInExplorer:
    • Reveals the selected section (script/folder) in the OS file explorer
    • Usable only in the tree view editor

Extension Settings

This extension contributes the following settings:

  • rgssScriptEditor.debug.logToConsole
    • Enables this extension to log information to a VSCode output channel.
  • rgssScriptEditor.debug.logToFile
    • Enables this extension to log information to a file inside the project's folder.
  • rgssScriptEditor.extension.quickStart
    • This setting enables/disables the extension's quick start mode.
    • Quick start will set the extension's active project folder automatically based on the current context:
      • If only one folder is opened and it is a valid RPG Maker project it will be activated.
      • If a workspace is opened (several folders) you will be able to choose the appropiate folder to activate with a button in the status bar.
      • If no folder is opened or the opened folders are not valid RPG Maker projects the extension will deactivate its UI elements.
  • rgssScriptEditor.extension.autoReveal
    • Allows the extension to reveal the active script file on the extension's script editor view.
  • rgssScriptEditor.extension.filesEndOfLine
    • Sets the EOL characters that the extension will use when creating script files.
    • Available types:
      • CRLF (\r\n)
      • LF (\n)
      • auto (Based on the OS)
  • rgssScriptEditor.extension.recreateScriptLoader
    • Allows the extension to re-create the script loader every time an RPG Maker project is opened.
    • Useful to let the extension update the script loader between updates.
    • Optionally, you can disable this behavior.
  • rgssScriptEditor.extension.importScriptsOverwrite
    • Sets whether to allow the extension to overwrite script files when importing a bundle scripts file or not
    • If set to false, a folder will be created where all imported scripts will be placed.
  • rgssScriptEditor.external.backUpsFolder
    • The relative path within the project's folder where all back ups will be saved.
  • rgssScriptEditor.external.scriptsFolder
    • The relative path within the project's folder where all scripts will be extracted.
  • rgssScriptEditor.gameplay.gameExecutablePath
    • The relative path to the game executable inside the project folder.
      • You can change this option to allow MKXP-Z executable to be launched.
  • rgssScriptEditor.gameplay.useWine
    • Sets the command to invoke Wine to run the game executable. (Linux Only!)
    • If a Linux-specific executable is used to run the game, you won't need to use this setting.
  • rgssScriptEditor.gameplay.runGameBehavior
    • Choose how the game executable is handled when it is already running.
    • Behaviors available:
      • Nothing: Does nothing, this how RPG Maker behaves (default)
      • Kill and Run: Kills the current game process and runs it again
      • Allow Multiple: Allows the user to start more than one game process at the same time
  • rgssScriptEditor.gameplay.automaticArgumentsDetection
    • Enables/disables automatic arguments detection mode.
    • If enabled, the extension will automatically choose the appropiate arguments based on the RPG Maker version detected.
    • IMPORTANT:
      • If you want to use custom arguments you must disable this mode.
  • rgssScriptEditor.gameplay.editorTestMode
    • Enables/disables test (debug) mode.
    • If enabled, the extension will run the game on debug mode.
    • If custom arguments are used, this option is ignored.
  • rgssScriptEditor.gameplay.nativeConsole
    • Enables/disables RPG Maker native console. (RPG Maker VX Ace only!)
    • If enabled, the extension will run the game allocating a console window.
    • If custom arguments are used, this option is ignored.
  • rgssScriptEditor.gameplay.customArguments
    • Set your own custom arguments to run the game with.
    • Arguments must be separated by a whitespace.
    • IMPORTANT:
      • You must disable rgssScriptEditor.gameplay.automaticArgumentsDetection to use this
  • rgssScriptEditor.gameplay.gameExceptionAutoProcess
    • Enables/Disables game exception automatic process mode.
    • The extension will show you an information window about the last detected exception.
  • rgssScriptEditor.gameplay.gameExceptionShowInEditor
    • Allows the extension to show a markdown file besides the active editor with the backtrace information.
      • This is pretty much required since VSCode peek menu does not support ordering the files.

Known Issues

I have listed here all errors I have encountered while testing the extension along with their respective solution.

If you find an issue not listed here, feel free to report it back.

[SyntaxError] Invalid Multibyte char (US-ASCII) Exception

There is a high chance that this will happen using RPG Maker VX Ace since that's the only RPG Maker editor running RGSS3 which it is based on Ruby 1.9+.

The other versions of the engine (XP and VX) runs with older versions of Ruby in which $KCODE is supported, this global variable is used to determine the encoding of a script file when Ruby is trying to load it.

So basically, when using RPG Maker VX Ace, errors may occur because Ruby 1.9+ does not "detect" the script file encoding, so it fails when trying to load it using Kernel.load or Kernel.require.

This error is easily fixed by adding # encoding: utf-8 in the first line of the script contents like:

# encoding: utf-8

module MyModule
  # ...
end

It is very important that the encoding is specified at the very first line of the script!

Like I said before, this workaround is not needed for older versions of RPG Maker that still uses $KCODE, but to avoid problems, I have made the extension add this line in every script that it is extracted from the bundle file or created using the extension's editor view automatically so you won't have to.

[LoadError] no such file to load -- Exception

This exception may happen for a number of reasons:

  • The file trying to load simply does not exists

Make sure that all files within the text file that defines the load order exists in the specified path.

If you don't want to load a script file you can simply remove the script or ignore it disabling it using the script editor view (or with a # character at the start of the line)

script.rb
another script.rb
Subfolder/
#skipped script.rb
#another skipped script.rb
#Skipped Subfolder/
  • The file exists, but it still crashes

If the file exists and the game still crashes you should make sure the path to the script file does not have special characters, specially in the script's name.

I made sure to remove all of them that I know from all scripts when extraction is done, but to be fully sure try not to use special characters to name your scripts.

For example, these characters are invalid:

  • '▼': Character that RPG Maker uses to define sections.
    • ./Scripts/▼ Modules.rb
  • '■': Some community plugins may have this character too.
    • ./Scripts/■ My Ruby Script.rb

The extension uses a regular expression to remove invalid characters from the script's name, I tried to include as many invalid combinations as possible but I may have missed some.

[SystemStackError] stack level too deep

You may encounter this problem if you try to restart the script loader at runtime.

Restarting game scripts at runtime is a task that is not recommended due to the numerous problems and undefined behavior issues it can cause.

A SystemStackError error can be caused by many reasons, and if you are not resetting the script loader it is probably it is not this extension's fault, but in case you are using the "reset script loader" feature, it is very likely it could be the definition of aliases in classes and modules.

For example this is the code I used to trigger the reset (on RPG Maker VX Ace):

class Scene_Base
  alias reset_script_loader update # <- Error here

  def update
    reset_script_loader
    raise ScriptLoader::ResetLoader if Input.press?(:F5)
  end
end

If you allow the scripts to reload again, Ruby will alias the method again, causing a SystemStackError when the method Scene_Base#update is called (since it was aliased before the restart).

A simple solution will be checking if the alias exists before doing it

class Scene_Base
  alias reset_script_loader update unless method_defined?(:reset_script_loader)

  def update
    reset_script_loader
    raise ScriptLoader::ResetLoader if Input.press?(:F5)
  end
end

Nevertheless this feature should not be used, hence the EXPERIMENTAL label on it, since scripts are loaded on top of the previous scripts causing possible undefined or unexpected behavior problems.

Latest Release Notes

[1.3.1] - 21/06/2024

Fixed

  • Fixed an issue reveal script on the tree view
    • Due to VS Code limitations, the reveal depth allows up to three levels
      • The reveal operation failed when the script is more deep than three levels
  • Fixed a problem when collapsing and expanding folders
    • The extension did not update the collapsible status of the folder
      • When the tree was refreshed, the collapsible status was reset to the default state

Changed

  • Changed debug to file option default value to false
    • Avoids unnecesary file write calls
    • Users can enable it manually when reporting bugs

[1.3.0] - 20/06/2024

Added

  • The extension now automatically re-creates the script loader every time the user opens a folder if the scripts are already extracted
    • It is recommended to leave it active, so the extension can update the script loader between updates.
    • Optionally, it can be disabled, but the user will have to update the script loader manually with the corresponding command.
  • Added run game behavior option
    • The user can choose how the extension behaves when trying to launch the game again.
    • You can choose between the following behaviors:
      • Nothing: Does nothing, this how RPG Maker behaves (default)
      • Kill and Run: Kills the current game process and runs it again
      • Allow Multiple: Allows the user to start more than one game process at the same time
  • Added files EOL (End-of-File) option
    • Scripts are now created with the appropriate EOL characters
    • You can force the extension to use a specific EOL type (LF, CRLF)
    • You can also let the extension determine the appropriate EOL automatically
      • This is based on the operating system
  • Import scripts from bundle files
    • You can import all scripts inside an RPG Maker scripts bundle file
    • Optionally, you can allow whether to overwrite existing scripts or not
  • Added a file system watcher to detect the output file the game creates when an exception kills the game
    • In previous versions, the extension processes the game exception only it the game was launched from VS Code
    • If the extension is running. you can launch the game out of VS Code, and it will process the game output file
  • Added a new command to reveal a script or folder on the operating system file explorer
    • Available in the context menu when selecting a script or a folder in the script editor view
  • Added the possibility for developers to reload scripts on runtime (EXPERIMENTAL)
    • The script loader will load scripts again if a ResetLoader exception is raised
    • You can raise this exception anywhere on your code

Fixed

  • The extension now gets the appropriate game process PID instead of the shell process PID
    • The game processes are now properly killed when closing VS Code or switching between projects
  • Fixed game process Errno::EBADF exceptions
    • Errno::EBADF was raised sometimes on RPG Maker VX Ace projects
      • The game fails to redirect output to the console output
    • Output is redirected to the null device if this happens to avoid crashes

Changed

  • Changed extension's auto process game error option
    • If enabled, the extension will automatically show the exception without asking the user to peek the backtrace
    • If disabled, it will ask the user before showing the exception information.

Contributors