RMEx

RMEBuilder

Package Manager for RPGMaker VXAce

If you're using Windows 10, you have to change the properties of the console (just before the bug) : Simply select the 'Use Legacy console' on the Options tab. (To find it right click the top left corner of the CMD window and select properties) Special thanks to this thread.

RMEBuilder is a tool for installing scripts in RPGMaker VXAce. It makes dependency management easier. On top of the comfort it provides, RMEBuilder is free software, licensed under LGPL.
RMEBuilder synchronizes via internet with the latest versions of scripts in order to guarantee that they are always up-to-date (and cover all known bugs)!

Overview

The idea behind RMEBuilder is to allow script users to easily and quickly install scripts. Indeed, RMEBuilder is a tiny executable that permits the adding of scripts to one or several projects. Here is an example of a typical method of using RMEBuilder.

It's also possible to update scripts and, obviously, any script writer can add to the database of available scripts (we hope they do)!

Downloading

RMEBuilder can be obtained really easily, just go to the Releases page and download the file RMEBuilder.zip.

Installing

In order for RMEBuilder to work perfectly, configuring your antivirus/firewall is sometimes necessary so that it lets RMEBuilder download files.

Installing RMEBuilder is very straightforward, just unzip RMEBuilder.zip in the chosen folder (not necessarily inside an RPGMaker project folder, you can use RMEBuilder to build several projects at once).

Normal use

First launch

To launch RMEBuilder, you simply need to click on RMEBuilder.bat (which is a shortcut to launch the application). Upon starting for the first time, the application will ask you to choose the target project. Choosing a valid RPGMaker VXAce project is mandatory.
Once the application knows the target project, a command line device can be accessed. With it, you can enter commands relating to project building.

You can change your target project at any time by entering the target command, which, on top of giving you the current target project path, allows you to change it.

Here is an example of RMEBuilder's first launch.

launch RME! Zoom in!

Composition of a schema

After a project has been chosen in the application, you can now add to it any scripts you want. To do so, you can use the show command which displays the list of available packages on the internet.
The about package-name returns information (description, authors, etc.) about a package.

launch RME! Zoom in!

In order to add packages to a project, simply use the add package-name command. This command's effect is to add a package to the list of packages to be added to the project.
The schema command displays the list of packages to be installed.

launch RME! Zoom in!

It is obvious that if RMEBuilder is closed, all scripts in the schema will be saved and will still be there when you reopen it!

Modifying the schema

By default, during the compilation step (which we will see later), scripts are installed in the order in which they were added. Obviously, you can change the order:

launch RME! Zoom in!

Haha I made a typo in the gif (mouwe instead of mouse, aha) :D sorry!

Compiling the project

Once your schema is complete, you can compile your project. Compiling in RMEBuilder consists in downloading the scripts currently in the schema and assembling them in the Scripts.rvdata2 file.

Be aware that, before compiling your project, it is mandatory that you close it in RPGMaker. You will be able to open it back later, once the compilation is done.

launch RME! Zoom in!

When the build command is used, the application will download all unknown scripts, and will then make a Scripts.rvdata2 file, which it will merge with the other scripts. This means your project can have pre-installed scripts without problem.
Each time the build command is called, elements built by RMEBuilder are purged. Thus, if you decide to remove an element from your schema after compiling (with the remove command), then it will be taken into account upon recompiling (build).

Managing assets

When compiling your project, RMEBuilder sometimes will ask you if you want to merge assets. It happens when packages contain external files (images or DLLs for example). Upon first compiling the project with a script that requires assets, it is recommended to answer Yes (Y). However, after the script has been added once, you do not need to merge its assets again. If you edit the images, merging the assets again will override all your edits, it would be bad!

At any time, you can fetch a package's assets with the get assets of package-name command.

Updating packages

Upon launch, RMEBuilder will check if updates for your installed scripts exist. It's very useful for keeping up-to-date with script versions and edits:

launch RME! Zoom in!

You can also use the check updates command, which will check if packages are up-to-date.

Once a package is updated, running the build command (after closing the RPGMaker project) is mandatory in order to take the update into account!

Dependency management

If a package depends on another package, it's not necessary to reference the latter in the schema. When building the project (with the use of the build or build dev commands), the application will download and install all dependencies. If a package with dependencies is removed from the schema, the dependencies will be removed as well (unless they were explicitly added (with add) to the schema).

Temporary compilation

The problem with RMEBuilder is that you have to close it after every edit. In order to address this, it is possible to compile temporarily. Using the build dev command will make a temporary file that, when the project is launched, will read the scripts from where they were downloaded. This allows you to only use build dev (and so, close the RPGMaker project) when adding or removing a file in the schema. Package updates don't force a project rebuild. It's very convenient for oft-updated scripts.
However, before distributing your project, executing a build is mandatory so that your project does not rely on temporary files anymore!

Updating RMEBuilder

When an update for RMEBuilder is available, the application will warn you. You simply need to confirm it and it will update itself.

launch RME! Zoom in!

Before publishing your project

Once your project is complete, you can remove the build_schema.rb file from the project folder (don't forget to build, in order to make sure all your scripts are installed). Now all that's left is to encrypt (or not) your project and diffuse it!

For script writers

RMEBuilder is obviously not destined to be used to publish and store only our scripts. We hope that it will be used by a lot of people to easily share scripts throughout the world! (starry eyes)

Make a script available in RMEBuilder

Publishing medium

In order for a script to be available in RMEBuilder, it is important to understand that it must be available on the internet. For that, we personally use Github, which allows us to manage versions of our scripts. You can also use Dropbox, but Github is really suited for the job!

Packages

In order for a script to be fully compatible with RMEBuilder, its structure must be described in a file that will always be named package.rb.

Example with a simple package

The package used in this example is nuki-break-scene, which allows users to easily create pause systems. Its Github folder can be found here.
The package's structure is simple enough: script.rb is the script (elementary!) and package.rb describes the package:

# Package description
  Package.new(
  	name: 'nuki-break-scene',
  	version: vsn(1, 0, 0),
  	authors: {'Nuki' => 'xaviervdw@gmail.com'},
  	components: ['script.rb'],
  	description: 'Provide a little customizable scene for InGame\'s pause',
  )
As you can see, you simply need to instantiate a Package object. This is the minimum required for a package.

Example with several files

This time we are going to use the RMD package as an example. As you can see, there is not a lot of changes, except that there are several authors and several files:

# Package description
Package.new(
  name: 'RME',
  version: vsn(0, 0, 5),
  authors: {
    'Nuki' => 'xaviervdw@gmail.com',
    'Grim' => 'grimfw@gmail.com',
    'Raho' => '',
    'Joke' => 'joke@biloucorp.com',
    'Mspawn' => ''
  },
  components: [
    'SDK.rb',
    'SDK.Gui.rb',
    'Database.rb',
    'Internal.rb',
    'EvEx.rb',
    'Commands.rb',
    'Incubator.rb',
    'EE4Cmds.rb',
    'Tools.rb',
    'DocGenerator.rb',
    'Doc.rb'
  ],
  description: 'RME is a powerful tool to improve your RPGMaker VXAce experience!'
)

Example with dependencies

The DisplayText script (which can be found here) requires installing the StandardizeRGSS script beforehand. You simply need to specify it in a dependancies argument, which takes a list of scripts on which the current script depends:

# Package description
Package.new(
  name: 'display-text',
  version: vsn(1, 0, 0),
  authors: {'Nuki' => 'xaviervdw@gmail.com'},
  components: ['script.rb'],
  description: 'Provide a full customisable text engine',
  dependancies: ["standardize-rgss"]
)
That's it, you know enough to start correctly packaging your scripts!

Example with assets

It may be that a script contains additional files: assets. For example, a DLL or images. To include them you simply need to add an assets parameter, which is a Hash whose keys are resource URLs (relative or not) and values are their positions in the project. For example, here is the "raho-useless" package file which doesn't have any use except demonstrating how assets work:

# Package description
Package.new(
	name: 'raho-useless',
	version: vsn(1, 0, 0),
	authors: {'Hyperaho' => ''},
	components: ['script.rb'],
	assets: {
		'assets/raho1.png' => 'Graphics/Pictures/raho1.png',
		'http://full.ouplo.com/f/12/AgkA.png' => 'Graphics/Pictures/raho2.png'
	},
	description: 'Epic script for Epic projects'
)
This package uses two images: one with a relative paht and the other with an absolute path.

Beware! Don't forget that RMEBuilder's goal is to be used by lots of people, so consider prefixing your assets in order to avoid collisions! For example, if I publish a menu that uses an image, I should name the image nuki-menu-my-image.png in order to guarantee that it does not override (and that it is not overriden by) any other image.

Submit a package as an RMEBuilder patch

The package list is a Github respository. To contribute, you simply need to "fork" this project. To add a package, just edit the list of available packages in the packages.rb file, and add a relation as such: "package name" => "URL of the corresponding package.rb".

Be careful that the URL must point to a raw file, not to an HTML page. For Github you have to use the raw link so that only the file contents are exported, and not the entire HTML page.

About package naming semantics

There aren't any formally stated semantics. However, in order to avoid package collisions, we suggest that you prefix your package names with the author's nickname. If the package is major and/or renowned, it is possible not to prefix it. However, we reserve the right to reject a package list edit if a package would override another.

The customPackages folder

In the RMEBuilder/customPackages folder, you can add your in-progress scripts. It allows for reading packages without them being hosted. This means you can make folders for your WIPs in there and work on them as if they were already published. This prevents you from having to publish an unfinished script.
Moreover, thanks to the build dev compilation command, you can also edit your code from your favorite editor (like emacs), without having to constantly copy-paste after every minor edit.

Cloning existing packages

For whatever reason, you might want to edit a package already published by someone else. In RMEBuilder you can use the clone package-name command and the package will be copied into your RMEBuilder/customPackages folder. A package in RMEBuilder/customPackages will always be added at the expense of an external package in the building step, so if you want to revert to the original package, you will have to remove it from RMEBuilder/customPackages or use the reclone package-name command to override the local copy with the latest published version.

Conclusion

That's it with the RMEBuilder, presentation tour, we hope that it will be really useful and that it will change (and simplify) users' ways of installing scripts. We also hope that script writers won't hesitate in publishing their scripts! The more the merrier :D
GOODBYE.