Just a nameless weakling
Jan 2, 2014
Reaction score
First Language
Primarily Uses
Purpose of this tutorial

To help scripters outsource the most basic script usage part of the documentations/instructions/manuals of their scripts so they're less likely to have to answer them repeatedly, and script users to understand how to use scripts more effectively.

If script users continue to ask script usage 101 questions after reading this tutorial, then they or scripters can blame this tutorial for failing to help script users to understand script usage 101.

Scope of this tutorial

The most basic script usage knowledge and practice. Things like notetag/script call usage won't be covered here as they're a bit more advanced and not all scripts use them. Specifically:

1. Nature of scripts

2. Some possibly unspoken assumptions to users

3. Script Types

4. Script instructions and requirements

5. Script ordering in the script editor

6. Some types of errors faced by script users

7. Ways to report bugs more effectively

Nature of scripts

Scripts are RMVXA tools aimed to help users use RMVXA. Like many other tools, they've some specific purposes and limitations, and most of them need users to know how to configure and use them before they can serve their purposes.

It means that it's unrealistic to think that scripts alone can do everything for RMVXA users, or a non plug and play script will serve its purpose without being configured properly by users.

That's why it's important to know what scripts are needed and what the purposes of a particular script are, and know what's needed to use a particular script before picking any.
Some common assumptions to users

1. Script users know the non-script RMVXA basics. This(depending on things covering by those scripts) may include basic database usage, basic damage formula usage(Fomar's custom damage formula tutorial maybe too advanced here), basic eventing(including battle events), basic game variables usage, basic mapping(parallax mapping maybe too advanced here), and more.

This assumption is usually much less true for 100% plug and play(no user setup is needed) scripts though, as users just have to know what they do and place it into the materials sections of the script editor(between Materials and Main).

2. Script users will read the documentations/instructions/manuals before asking for help. They're to describe and explain how to use the script, so if users don't read them and ask for questions with their answers included in those documentations/instructions/manuals, those documentations/instructions/manuals will become pointless and the scripters' workload will probably be significantly increased.

Of course, the documentations/instructions/manuals themselves have to be good enough to serve their purposes, or they'll be useless(or even "destructive") from the very beginning.

3. Script users know how to use a particular script usage technique(like notetags, script calls, advanced custom damage formula manipulations) needed to use that script. If those scripts state that a particular script usage technique is needed to use that script but that script didn't teach users how to use that technique, it probably assumes that users know how to use that technique.

4. Script users check if there's any newer versions of the scripts and use the newest version available. It's because there are chances that the issues users faced are already addressed by the newest version, and usually scripters only support the newest versions of their scripts. It can significantly increase their workload if they'd have to support the older versions as well.

5. There maybe more, but right now the above are what I can think of.
Script Types

I'm not talking about types like battle systems, menu/huds, pixel movements, etc, but a more generic classifications for general script usage:

1. Main Custom Script/Snippet - New main scripts/snippets written by scripters(like a new battle system, menu engine, core engine, etc)

2. Custom Script/Snippet Bug Fix - Fixes bugs of existing custom scripts/snippets(fixing default RMVXA bugs is another thing)

3. Custom Script/Snippet Compatibility Fix - Fixes compatibility issues of existing custom scripts/snippets

4. Custom Script/Snippet Addon - Add something new to existing custom scripts/snippets

5. Custom Script/Snippet Edit - An edited version of existing custom scripts/snippets(usually the author of the former is different from that of the latters)

6. There maybe more, but right now the above are what I can think of.
Script instructions and requirements

1. Most, if not all, scripts have documentations/instructions/manuals. If they're poorly done, then this tutorial will be much less useful; if not, then you'll want to read and understand them.

Reading them is one thing, while understanding them is another. Sometimes users will have to do some experiments to really understand an instruction, while sometimes users just can't understand it themselves.

Nevertheless, it's better to ask for clarifications of the instructions than to ask for help for using scripts when the answers lie within the instructions(you'll know what it means if you do the latter to Victor XD).

Of course there can be cases where users thought they understand the instructions clearly while they're actually misunderstanding them, but these cases should be rare if the instructions are good enough.

2. Some scripts need some other scripts in order to work, while some scripts need some other scripts to be absent in order to work. The former is script prerequisites while the latter is script conflicts. Usually the former will be clearly stated in the instructions of the scripts(unless the documentations are really poorly done), but it's not so true for the latter. Still, there are some indicators for probable script conflicts:

- If 2+ scripts do extremely similar things, especially when they're complex and colossal systems like core engines, battle systems, etc, then they'll probably be more prone to some script conflicts.

- If 2+ scripts needs 2+ separate complicated scripts and the latters aren't stated to be compatible with each other, then the formers will probably be more prone to some script conflicts.

- If the purposes of 2+ scripts seem to have some serious conflicts, then they'll probably be more prone to some script conflicts.

- There maybe more, but right now the above are what I can think of.

There are also some notorious script conflicts, like some YEA scripts with some VE scripts. Sometimes scripters will state possible script conflicts in their blogs rather than the scripts themselves.
Script ordering in the script editor

For example:

MaterialsCustom Script ACustom Script BMainIs a particular script ordering. In this case, both Custom Script A and B are placed between Materials and Main while Custom Script A is placed above Custom Script B and Custom Script B is placed below Custom Script A.

Script ordering can be extremely important when using scripts. Some scripts(like Victor's ones) will check it for you, but many others won't. If the script specifies some script ordering rules, you'll want to follow them. These rules maybe included as parts of each script's documentations, or stated in the scripter's blog like what Yanfly did:

In some cases these rules aren't stated but are still present. If that's the case, users can try to change the script ordering to see if anything changes and hope they'll figure out the script ordering rules.

There are some rules that may be unspoken as it's probably assumed to be understood:

1. Put the prerequisite scripts of script A above script A

2. Put bug/compatibility fixes of script A below script A

3. Put addons/edits to script A below script A(and probably below bug and even compatibility fixes of script A)

4. There maybe more, but right now the above are what I can think of.
Some types of errors faced by script users

1. User errors. Not every part of a script is supposed to be edited by users, and those "editable" places aren't meant to be edited without knowing anything. If users edited something they're not supposed to edit, then a user error(like syntax error) can occur; if users set some invalid values in the script configurations, then a user error(like division by 0) can also occur.

Some scripts check the validity of its configurations to reduce the chance of facing user errors, but some other scripts don't. So it's important for users to ensure that they didn't edit anything they're not supposed to edit, and every part of the script configurations is valid. A decently documented script should give users at least some ideas for judging if a configuration value is valid.

2. Old saves errors. If some scripts are added, edited or removed, then errors can occur due to the old saves failing to work with those new changes. So it's a good practice to start a new game whenever there's a change in the script editor. If the errors are gone with a new game, then they're probably old saves errors.

3. Copy/Download/Upload errors. Some contents of the scripts are changed due to copying/downloading/uploading. It's a rather strange error, but sometimes it does happen. I've seen 1 case where I found that all square brackets that are supposed to exist in the script are gone in his/her version and he/she didn't edit anything, but the original script doesn't have this problem. In this case it's a copy/download error; When I was still new to RMN, I didn't know I've to use the code ruby tag to post my scripts there and all square brackets are gone in my scripts. 1 users stated that my scripts have bugs and then I realized I've to use that, but at that time I already posted 10+ scripts. In this case it's an upload error.

While users can only report the issues even if it's an upload error, they can try to check the original script versus their copied/download version(or just copy/download again) to see if there's any difference to find any possible copy/download error.

There's, however, at least 1 rather strong indicator that it's probably a copy/download/upload error if users didn't edit anything they're not supposed to edit and every configuration value is valid:

Script 'Script Name' line x: SyntaxError occured.DetailsIt's because a script with SyntaxError should never run in any situation, meaning that scripters would know this error if they've tested it before publishing it. If it's indeed not a copy/download/upload error, it means that either the scripters didn't even test it before publishing it, or they publish it even when they know it's syntax errors. This tutorial will be much less useful if users use scripts written by scripters like this.

4. RMVXA bugs. RMVXA isn't bug free, so script users may experience bugs from the RMVXA itself instead of the custom scripts. Although it's usually hard for users to tell if it's a RMVXA bug, they can still try to prevent this from happening by using some RMVXA bug fix scripts/snippets:

There's however, at least 1 rather strong indicator that it's unlikely a RMVXA bug:

Script 'Script Name' line x: SystemStackError occured.stack level too deep.A rigid explanation probably needs some scripting knowledge to understand, but if it were indeed a RMVXA bug, then it should occur even without any custom script.

5. Script bugs. Ideally, custom scripts should be nearly bug-free, but in practice, it's rather hard for almost all scripters to write such scripts. If just a single custom script along with RMVXA bug fixes are added with a correct ordering to a fresh working project and users did the script setup properly but there's still errors, then it's quite likely that that custom script itself has bugs, although it's possible that it's an unhandled RMVXA error instead.

6. Compatibility Issues. It's just unrealistic to think that almost every custom scripts are compatible with each other as there are so many custom scripts and scripters writing them. If only 1 of the 2 scripts is used and there's no errors but when they're used together there are errors(with all possible script orderings tested), then it's probably a compatibility issue although in some cases it can be some well-hidden script bugs instead.

7. There maybe more, but right now the above are what I can think of.
Ways to report issues more effectively

Different forums/scripters may "enforce" different script issue reporting guidelines and/or even rules, but in general there are some points to bear in mind when reporting script issues:

1. Elaborate the issues themselves. "The party command window has bugs" isn't elaborating, but "The party command window opens even when an actor command window is opened" is.

2. Describe the ways to reproduce the issues. This can be done by just describing what you've done before the issues rise. If you somehow find some possible triggers behind the issues(like "it happens when I just canceled an actor's input"), it's better to mention them as well.

3. Try to figure out the nature of the issues. Usually you don't want to report user errors, old saves errors or copy/download errors as they've nothing to do with the scripters. For other types of issues though, if the scripters know the nature of the issues, they'll probably be able to deal with them more effectively. Also, some scripters don't support compatibility issues so sometimes stating the nature of the issues is a must.

4. Quote the entire error log if there's any. The general form of the error log is:

Script 'Script Name' line x: Exception occured.DetailsEvery part of the error log can help, so don't just mention parts of it. You can probably report errors much more efficiently if you use some error backtrace scripts like this though:

It's to be placed below all other custom scripts and you'll have to show the console to show the full error backtrace log.

5. Articulate the settings of the project you're talking about. Usually the most important information you'll want to tell is the list of all custom scripts(with their versions mentioned) used and their ordering.

6. Sometimes you'll want to give scripters your script demo. Usually it should only consists of the bare minimum to reproduce the errors, or it can be overwhelming for scripters to figure out the cause.

7. There maybe more, but right now the above are what I can think of.

To use scripts(RMVXA tools aimed to help users use RMVXA) more effectively:

1. Know what scripts are needed and what a particular script can do

2. Know the non-script RMVXA basics

3. Read and understand the script documentations/instructions/manuals(ask when you don't understand them)

4. Check if there's any newer versions of the scripts and use the newest version available

5. Check the script prerequisites, conflicts and orderings(testing maybe needed)

6. Figure out(by testing systemactically) the nature of the script issues to report them more accurately(and don't report user errors, old saves errors or copy/download errors as you should try your best to avoid them)

7. Elaborate the issues, ways to reproduce them, the nature of the issues, the error log(or a full error backtrace) and the settings of the project(or just give the script demo to scripters)

8. There maybe more, but right now the above are what I can think of.

P.S.: If there's anything missing or problematic with this tutorial, I'll be glad to see them being pointed out.
Last edited by a moderator:

Latest Threads

Latest Posts

Latest Profile Posts

I had one goal when I set out to make my Game Jam game. It didn't have to be super good and the game didn't have to have the best writing - it just had to NOT CRASH.

So yeah, someone was streaming it and it crashed.
Add Special Effects on Map with Tilesets | RPG Maker News #105

Come, join Move That Box! DISCORD!
Excited to see all the entries for the 2021 Touch the Stars Gamejam.
just finished playing one shot. im kinda disappointed with return the sun ending ngl. i was hoping there would be some after credits scene that would play with my emotions

Forum statistics

Latest member