search

SnowSzn / rgss-script-editor

RGSS Script Editor is a Visual Studio Code extension for RPG Maker XP, RPG Maker VX and RPG Maker VX Ace
GNU General Public License v3.0
17 stars 0 forks source link
developer-tools rgss rpg-maker-vx rpg-maker-vxace rpg-maker-xp rpgmaker rpgmakervx rpgmakervxace rpgmakerxp script-loader typescript vscode-extension

readme

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:

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), 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

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

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...").

Extension Settings

This extension contributes the following settings:

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:

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/

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:

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.

Contributors