SLIP INTO RUBY - UNDER THE HOOD PART 11: DO NINE MEN INTERPRET(ER)? NINE MEN, I NOD.

Okay, so it's been over a year. But it's back! Tell all your friends! If you don't have any friends tell your cat! The time has finally come for the next exciting edition of



So if you remember last time (it was October 2015, I wouldn't blame you if you didn't) we looked at everything from Game_CommonEvent up to Game_Event. Now it's time. The time I never wanted to come. Yes, it's time to crack open the behemoth that makes this whole mother do what it does. It's time to look at Game_Interpreter.

Game_Interpreter

This is going to take up a whole episode by itself, so fasten your seatbelts and get ready to unravel one of the biggest scripts in the entirety of RPG Maker VX Ace. This is the one responsible for making all your fancy event commands -do stuff-, so it's an important one to understand. An in-depth understanding of the interpreter and how it works will enable you to change the behaviour of existing event commands however you see fit.

For future reference, Game_Map, Game_Troop and Game_Event all have their own instance of the interpreter, which is why event commands still work in battle etc.

To begin with, it has two public instance variables:



They're pretty self-explanatory: Map ID is the ID of the map the interpreter is for (when used on Game_Map), and Event ID is the ID of the event the interpreter is for (when used on Game_Event).



As you can see here, the constructor takes one argument, depth. The instance variable @depth is set to the supplied value (default of 0), then we call check_overflow (which we'll look at in a sec) and finally we call clear (which we'll also look at in a sec).



As stated in the comments for this method, under normal conditions depth will not exceed 100. This method is basically here to catch infinite loops resulting from recursive event calls (events calling themselves). Essentially, if @depth is ever equal to or greater than 100, an event overflow error is displayed and the game quits.



Clear is a method that basically just starts you off with a fresh slate interpreter with no data. The map ID and event ID are both set to 0, the list of commands is set to nil, the command index is set to 0, the data of the current branch is set to an empty array, and fiber is set to nil (we'll cover fiber shortly).



Setup is a method for setting up map events and takes two arguments: a list of event commands and the ID of the event in question. First, we call the clear method, same as with the constructor. The @map_id instance variable is set to the ID of the map the player is currently on ($game_map being a global variable containing all data for the current map, as we've covered before). @event_id is set to the supplied event ID, which defaults to 0. @list is set to the supplied list of commands, and then we call create_fiber. This isn't part of a balanced diet, it's an integral part of how RPG Maker VX Ace even works.



Well. This is...not very illuminating, is it? To put it in layman's terms: "if @list contains data, set @fiber to a new instance of Fiber, and then...do something with run in brackets?"

To quote the Ruby documentation: "Fibers are primitives for implementing light weight cooperative concurrency in Ruby. Basically they are a means of creating code blocks that can be paused and resumed, much like threads. The main difference is that they are never preempted and that the scheduling must be done by the programmer and not the VM."

A Fiber will not run automatically when created; it must be explicitly asked using the Fiber.resume method (which, you guessed it, we'll look at in a bit). You can also have the fiber give up control to the code that called it using Fiber.yield, which, again, we'll see in a bit.

This is a lot to take in for people who aren't used to Object-Oriented Programming or multithreading, so suffice to say that Fiber basically starts a self-sufficient bit of code which retains state and can be paused/resumed as needed, and in this case, all it's doing is calling the "run" method of Game_Interpreter, which is coming up soon.



This method returns an array consisting of the depth, the map ID, the event ID, the list of commands, the current index incremented by 1, and the branch data. Although you won't see a call to this method anywhere in the default scripts, it's kind of built-in to the language and will be called whenever Ruby is trying to serialise an interpreter. Without this, you wouldn't be able to save games.



This is the counterpart to marshal_dump, used when loading data (again, because fibers are not compatible with Marshal); it takes one argument, obj (which is an array of data as defined in marshal_dump) and simply sets each respective instance variable to the element of obj corresponding to it, then creates the fiber using that data.

This also demonstrates a pretty nifty feature of Ruby that I don't think I've ever really gone into, which is that you can assign multiple values in one line by setting a list of variables to an array. For example, if I were to do



basically what would happen is that the array would be iterated, and each value would be assigned to the next variable specified. So @test1 would hold the value 1, @test2 the value 2, and so on. If you supply fewer values in the array than there are variables, the other variables will be set to nil.

To see in action the ramifications of not having this set of methods here, try commenting out marshal_dump and then save your game. What's that? You can't do it? Yeah, that's because Ruby isn't able to serialise your interpreter. :D (similarly, if you comment out marshal_load, you can save your game but can't load it).



This method is used to determine if the map the event started on is the same as the one the player is on currently, and is used for a few purposes which we'll see later. It simply compares the @map_id variable to the map_id method of $game_map, returning true if they're equal and false if they're not.



This method sets up reserved common events: you probably don't remember, but we looked at common_event_reserved? way back in Slip into Ruby: Under the Hood part 3.

So first what we're doing is checking to see if a common event has even been reserved in the first place, and simply returns false if there isn't: if there isn't one waiting to run, what's the point in setting one up?

If an event is waiting to run, we call the setup method, supplying the list of commands for that common event, then clear the common event ID from $game_temp (so that it doesn't keep setting up the same common event forever) and finally returns true to show that the event is ready to run.



This is the meat and potatoes of the interpreter, and is essentially what makes it work. You'll remember from create_fiber that this method is the only thing the Fiber block contains, so as soon as we call resume on a fiber it'll call this method.

First we call wait_for_message, which as we'll see a bit later simply...waits for a message (as in the boxes you use for dialogue and stuff). Then it starts a while loop for as long as @list contains data in the element corresponding to @index. Each loop all that will happen is that execute_command will be called, then the index will be incremented by 1. Once the list has been fully iterated through, we call Fiber.yield (which returns control to the code that called the fiber) and set @fiber to nil.

Interestingly enough, because the fiber is only resumed in frame update methods (as, you guessed it, we'll see soon), I'm not actually sure what Fiber.yield even -does- here. As far as I can tell everything still works fine without it, because all it's doing is returning control to a method that it goes back to after it runs anyway. If anyone can shed some light on this please feel free.



This method determines whether the interpreter is running or not, and simply returns true if @fiber is not nil, and false otherwise.



The frame update method. If @fiber contains data, resume it. As we've already seen, this means that every frame during which a fiber exists, the interpreter's "run" method will be called (if the fiber isn't already running), which will take over control until the event has run its course (which is also why other non-parallel-process events on a map stop what they're doing when you interact with an event).



This method is an actor ID iterator, which takes one parameter (param); as specified in the comments, if the value is 0, goes through each actor. If 1 or more, yields the actor corresponding to that ID.

This looks more complicated than it is, and once we come across a command that uses this and upcoming iteration methods I'll go through the logic in detail.



Actor variable iterator, taking two parameters: param1 and param2. param1 specifies whether the variable being used is fixed (0) or itself a variable (1), while param2 specifies the actor or variable ID. If param1 is 0, then we call iterate_actor_id with param2 as the param. If it's 1 or more, we call iterate_actor_id using element param2 of $game_variables and yield that actor instead.



Actor index iterator, taking one parameter: param. If it's 0 or more, yields the actor corresponding to that value. If -1, yields the whole party.



Enem index iterator, taking one parameter: param. If it's 0 or more, yields the enemy corresponding to that value. If -1, yields the whole enemy troop.



Battler iterator, taking two parameters: param1 and param2. param1 specifies whether to iterate enemies (0) or actors (1), while param2 specifies the enemy index or actor ID. This check is only done if the party is in battle.



Determines the target of a command that affects the screen. If the party is in battle, return the screen of $game_troop; otherwise, return the screen of $game_map.



This method is the one that actually executes event commands. First, the variable command is set to the element of @list corresponding to the current @index. @params is set to the parameters of that command, @indent is set to the indent of the command, the method name is set to the string "command_" followed by the code of the command, then if that method name responds to calls, send it.

WTF did you just say, Trihan? Okay, so not sure if I've already covered this but you can call a method in Ruby by using send(name_of_method) as well as calling it directly by name. This allows you to call methods with dynamically-generated names, as is the case here. respond_to? simply checks that the object in question (in this case, Game_Interpreter) responds to (or can call) the given method. This is why all of the event command methods are named command_ (as we'll see), so that they can be called dynamically.



This method skips commands which are deeper than the current index and increments it.

To put it more simply, while the indent of the next command in the list is greater than that of the current one, increment the index. I'll explain this in more detail when we get to a method that calls it.



This method simply gets the code of the next event command, by returning the .code property of the element of @list corresponding to 1 more than @index.



This method returns a particular character and takes one parameter, param. If the party is in battle, returns nil. If the parameter is -1, returns the player. If any other value, gets a list of events on the map if we're still on the same map as the event started on (otherwise an empty array) and then returns events if param is greater than 0, or events[@event_id] if it's 0 (in other words, "this event").



This method calculates operated values, given three parameters: operation, operand type, and operand.

Sets the variable "value" to the value of operand if operand_type is 0, or the game variable with index operand if it's 1. Sets the variable "operation" to value if it's 0, and the negative of value if it's 1. I'll explain further once we get to a method that calls it.



This method "waits" a number of frames, specified by the parameter duration. Simply yields the fiber to its caller for as many times as the supplied duration.



This method waits while a message is displaying (without this messages would never actually show as the event would just blow past them without waiting for input). Simply yields the fiber to its caller as long as $game_message.busy? returns true. For those who don't remember the time we covered this, it'll return true as long as the message has text, a choice, number input, or an item choice.



That's right, we're only just now getting to the first event command. We're going to be here a while...

All this time you've just been using the "Show Text..." command without really thinking about it. Well, that's all about to change, because we're about to dive into its innards and find out exactly how it works.

First, we call wait_for_message, so if a message is displaying, it'll yield to the caller. I honestly don't actually think the first call here is needed, as it's also called at the end and that'll stop to wait for input anyway.

The face_name property of $game_message is set to @params[0], which is the filename of the face graphic you choose when you double click the box in the "Show Text..." dialog. face_index is set to @params[1], which is the face that you choose from the box on the right showing the actual graphic. background is set to @params[2], which is the numerical value corresponding to "Normal Window", "Dim Background" and "Transparent" in the "Background:" drop-down list. position is set to @params[3], which is the numerical value corresponding to "Bottom", "Middle" and "Top" in the "Position:" drop-down list.

Unfortunately there's no way to change the parameters supplied to these commands without hacking into the actual editor since they're tied into the dialog boxes themselves, but it's handy to know that everything you select in an event command dialog box is stored in the params array so you can refer to it in your code.

Then we enter a while loop, for as long as next_event_code returns 401. This is the internal code used by the event editor to denote "text data" and this is how multiple messages are displayed "smoothly" without the box closing and opening after each one. The while loop simply goes to the next index and adds the parameters[0] property of the element of @list corresponding to @index to $game_message. In English, we add the text of the next message command to the content of the global message variable.

You may have noticed something interesting from this: although "101" is the code of the "Show Text..." command, the actual text to be displayed is created as an entirely separate command with code 401. This is why parameters[0] of command 101 is the faceset name, while parameters[0] of command 401 is the text.

Once the while loop has processed all of the continuous text, we check the next_event_code again to see if it's a command that needs to display something alongside the message box. If it's 102 (Show Choices), we increment the index and call setup_choices with the parameters of the command as an argument. If it's 103 (Input Number), we increment the index and call setup_num_input with the parameters of the command as an argument. If it's 104 (Select Item), we...you get the idea. This basically just sets up choices, numbers or item selection so that they appear alongside the message. If we didn't have this, you'd have to close the message box before the other windows appeared, which would be pretty terrible game design.

And finally, we call wait_for_message, which we've already looked at.



The code for Show Choices is surprisingly brief. It calls wait_for_message, then setup_choices supplying @params as the argument (this is the list of choices and the cancellation choice), and yields the fiber to its caller while $game_message.choice? returns true. For those who don't remember that lesson, it returns true if the size of @choices is > 0, which will obviously be the case if you've put choices in the boxes.

So here we come to another interesting note. Although Show Choices can be used by itself, if you have a Show Choices command following a Show Text, command_102 will never actually be called, because the Show Text does the choice processing for you! I actually think the way Enterbrain did this is pretty neat.



This method sets up the choices you select from when using the Show Choices event command. It iterates through each element of params[0] (which is the list of choices you wrote in the boxes) and runs a block on it, with s as the block variable (meaning each time it iterates, s will be whatever string you put in the next choice box, and it will be pushed to the choices array of $game_message).

The choice_cancel_type of $game_message is set to params[1]; this is the numerical representation of "Disallow", "Choice 1", "Choice 2", "Choice 3", "Choice 4", or "Branch" depending on what you chose in the dialog.

Finally, choice_proc of $game_message is set to a new Proc, with block variable n, where the element of @branch corresponding to @indent is set to n. Wait, what?

Okay, so Proc is basically just a fancy way to write a block of code that can be called in different contexts; if choice_proc is called, the value passed to it will be passed as "n", which will then be stored in @branch[@indent]. We'll revisit this when we finally get to Window_ChoiceList, which won't be for a while yet.



command_402 is a special one which is called when the interpreter reaches a choice branch. It skips the command if @branch[@indent] (which contains the index of the chosen option) is not equal to @params[0] (the ID of the current choice).



Here's another interesting one. The comment says "When Cancel" so you'd think it would be connected to the cancellation of a choice, but as far as I can tell it's never called by anything. What it does is skips the command if @branch[@indent] isn't equal to 4. Intriguingly, although command_403 never seems to be called by Show Choice, it does try to call command_404...which doesn't exist. I'm not sure whether this is a mistake in the coding of the editor. Another interesting note is that as far as I'm aware it's not actually possible for @branch[@indent] to ever equal 4 in a choice window anyway, as it's 0-indexed and there are only 4 options (0, 1, 2, 3).

er.yield while $game_message.num_input?
end

This method processes number input (when it's not immediately following Show Text). Simply waits for messages, calls setup_num_input with @params as the argument, and yields the fiber to the caller while num_input? from $game_message returns true (which is the case as long as @num_input_variable_id > 0, which will be true for the duration of the number input since this is the variable you picked in the dialog of the command).



And here we see the ever-so-complicated code for setting up number input, which is...setting the num_input_variable_id property of $game_message to params[0], which is the variable you picked in the dialog, and num_inputs_digits_max to params[1], which is the value you entered in the "Digits:" box.



This method processes the "select item" box (when it's not immediately following Show Text). Simply waits for messages, calls setup_item_choice with @params as the argument, and yields the fiber to the caller while item_choice? from $game_message returns true (as above, but for the item_choice_variable_id instead).



Pretty much the same as setting up number input, only we don't have max digits to worry about this time.



Show Scrolling Text! So it yields the fiber to the caller while $game_message.visible is true (so that if a message is currently showing, the scrolling text won't interfere with it) then sets some properties in $game_message: scroll_mode is set to true, scroll_speed is set to @params[0], which is the value you set in the dialog, and scroll_no_fast is set to @params[1], which determines whether or not the text can be fast forwarded.

We then enter a while loop as long as next_event_code is 405 (the scrolling text equivalent of 401 for text) and in each iteration increment the index and add parameters[0] (the text) to $game_message.

And finally, we wait for the message to finish scrolling.



This method is for the "Comment" command. The @comments array is populated with an array consisting of @params[0], which is just the comment text. Then we enter a while loop as long as next_event_code is 408, where we increment @index and push parameters[0] to @comments. I honestly have no idea what this loop does as I've never been able to engineer an event that had a command with code 408 in it, regardless of how many comments I created and where.



Conditional Branch is an absolute monster. Let's slay it.

So the first line is as simple as they come: set result to false. Moving on.

Then we have a case statement for @params[0]: this is the value of the radio button in the dialog determining whether it's Switch, Variable, Self Switch, Timer, Actor, Enemy, Character, Vehicle, Gold, Item, Weapon, Armour, Button, or Script.

When 0 (Switch), result is set to the result of comparing $game_switches[@params[1]] to (@params[2] == 0)--in other words, whether the two values are the same. @params[1] is the ID of the switch you chose from the selection dialog. @params[2] is 0 if you chose ON, and 1 if you chose OFF. So if you're doing a branch for switch 43 being ON, @params[1] will be 43, @params[2] will be 0, and it'll then be comparing $game_switches[43] to (0 == 0); if the switch is on, this will end up being [switch state] == true, which will return true if the switch is true, and false otherwise. Obviously this is turned around if checking for the switch being false, as the comparison then becomes (1 == 0) which is false, so if the switch is also false it'll return true.

When 1 (Variable), value1 is set to $game_variables[@params[1]] (the ID of the variable you set in the dialog); then if @params[2] is 0 ("Constant" in the dialog), value2 is set to @params[3], otherwise it's set to $game_variables[@params[3]] ("Variable" in the dialog). We then have a case statement for @params[4]; if it's 0 (Equal to), result is set to value1 == value2. If it's 1 (Greater than or equal to) result is set to value1 >= value2. You've done maths before, you should be able to work out the rest: 2 is less than or equal to, 3 is greater than, 4 is less than, 5 is not equal to.

When 2 (Self Switch), first we check whether @event_id is greater than 0 (because only events can have self switches), then key is set to an array consisting of the current map ID, the current event ID, and @params[1] (the letter of the self switch being checked) and result is set to $game_self_switches[key] == (@params[2] == 0)). So if we're currently on map 5 and checking that event 6 has self switch B ON, key becomes [5, 6, "B"] and result becomes $game_self_switches[[5, 6, "B"]] == (0 == 0); if the self switch is on, this will return true, otherwise it'll return false.

When 3 (Timer), first we check whether $game_timer.working? is true (because there's no point in checking if there isn't even a timer running); if so, and if @params[2] == 0, result is set to $game_timer.sec >= @params[1]. Otherwise, it's set to $game_timer.sec <= @params[1]. @params[2] is 0 if you chose "or More" and 1 if you chose "or Less", while @params[1] is the total number of seconds in the timer, which I believe the editor automatically calculates from the minutes and seconds boxes.

When 4 (Actor), the variable actor is set to $game_actors[@params[1]] (the ID of the actor you chose in the dialog). Then if actor exists, we have a case statement for @params[2]: when 0 (in party) result is true if $game_party includes the given actor, and false otherwise. When 1 (name), result is true if the actor's name is equal to @params[3] (the string entered in the name box). When 2 (Class), result is true if the actor's class ID is equal to @params[3] (the ID of the class selected in the box). When 3 (Skills), result is true if the actor has learned the skill with ID @params[3]. When 4 (Weapons), result is true if the actor has equipped the weapon with ID @params[3]. When 5 (Armours), result is true if the actor has equipped the armour with ID @params[3]. When 6 (States), result is true if the actor has the state with ID @params[3].

When 5 (Enemy), the variable enemy is set to $game_troop.members[@params[1]] (The enemy ID chosen in the dialog). Then if enemy exists, we have a case statement for @params[2]: when 0 (Appeared) result is true if the enemy with the given ID is currently alive. When 1 (State) result is true if the enemy with the given ID has the state with ID @params[3].

When 6 (Character), the variable character is set to the result of calling get_character with @params[1] as its argument. As we saw earlier, this will either be -1 (player), 0 (this event), or the ID of an event on the map. Then if character exists, result is true if the character's direction is equal to @params[2]. Note that internally directions have a numerical representation: down is 2, left is 4, right is 6, up is 8 (which is, incidentally, also the number on a numpad corresponding to that arrow key).

Interesting note: although "Vehicle" is the next option in the list, it actually has a higher number internally.

When 7 (Gold), we have a case statement for @params[2]: when 0 (greater than or equal to) result is true if the party's gold >= @params[1] (the entered value). When 1 (less than or equal to) result is true if the party's gold <= @params[1]. When 2 (less than) result is true if the party's gold < @params[1].

When 8 (Item), result is true if the party possesses the item with the ID @params[1].

When 9 (Weapon), result is true if the party possesses the weapon with ID @params[1]. If you checked the "include equipment" box, @params[2] will be true, false otherwise.

When 10 (Armour), result is true if the party possesses the armour with ID @params[1]. If you checked the "include equipment" box, @params[2] will be true, false otherwise.

When 11 (Button), result is true if the player is pressing the button corresponding to @params[1]. The directions are the same as previously mentioned (down = 2, left = 4, right = 6, up = 8), button A is 11, B is 12, C is 13, X is 14, Y is 15, Z is 16, L is 17 and R is 18.

When 12 (Script), result is true if the evaluated script stored in @params[1] (whatever you entered in the box) returns true.

When 13 (Vehicle), result is true if $game_player.vehicle is the same as $game_map.vehicles[@params[1]]. 0 is Boat, 1 is Ship, 2 is Airship.

Finally, @branch[@indent] is set to result, and we call command_skip if the result was false (because if the condition wasn't met, we don't want to process the code inside it)



This method is basically just there to skip the commands in an "else" if the branch result was true (the method itself will be called when the interpreter reaches the "else" line because its internal code is 411). Without this, the code in the else would still run even if one of the other branches had its conditions met.



It's...an empty method. Yep, the command method for "Loop" doesn't actually do anything. In fact, you can delete this method and loop will still work fine. I think it's basically just there for completion's sake.



This is what makes the loop actually work. The contents of the begin-end block will repeat until the indent of the current line of code is equal to the current indent. The only thing in the block is a decrement of the index.

Think about how indenting works in event commands, and you'll realise how this actually results in a loop. Picture a loop with a message in it:

Loop
Show Text: "Hello World!"
Repeat Above

112 is the "Loop", 413 is the "Repeat Above", and both have an indent of 0. The Show Text, 101, would have an indent of 1. So what the command_413 is doing is going backwards in the event commands until it finds another command with an indent of 0...which will basically take us back to the Loop. Execution will then continue from there, so it'll execute everything inside the loop again, at which point it'll go backwards until it finds indent 0...and so on and so forth. Unless...



This is how Break Loop works. Oddly enough, breaking a loop starts...with a loop. Inside that loop, we increment the index by 1, and return if the new index is greater than or equal to the size of the event commands list less 1. We also return if the code of the new command is 413 (Repeat Above) and the indent of the new command is less than the one we've just come from.

Note that the first return means that putting a Break Loop command in an event outside of a Loop-Repeat Above block will cause anything after the break to be ignored. GreatRedSpirit has also pointed out that there's a bug where having a Break Loop inside a conditional branch before a nested loop where there are no more commands between the Repeat Above of the inner loop and the Repeat Above of the outer loop will soft lock your game.



Exit Event Processing couldn't be simpler. All it does is set the current index to the size of the commands list, so the next time it tries to process a command it's at the end of the event.



This is the method for Call Common Event. First, common_event is set to the data pertaining to the common event specified by @params[0] (the event chosen in the dialog). If that common event exists, child is set to a new instance of Game_Interpreter with depth 1 greater than the current depth, we call setup on the child event, and then call its run method. Note that due to the recursive creation of new interpreters, if you have a map event call a common event which calls itself you'll eventually end up running afoul of the check_overflow method. Don't do this.



Another one that doesn't do anything! The method for Label is just as pointless as the one for Loop.



Jump to Label is, as with looping, the meat and potatoes of the block. First, label_name is set to @params[0] (which is the label name specified in the dialog). Then we enter a times loop with @list.size iterations (in other words, a number of iterations equal to the number of commands in the event) using i as an iteration variable. If the code of the list element with index i is 118 (label) and its parameters[0] (which for a label is its name) is equal to label_name, we set @index to i and return (in other words, if we find a label with the supplied name, we'll continue processing the event from that label).



Control Switches is simple enough. If a single switch is selected, I believe @params[0] and @params[1] will be the same value, while "Batch" will result in 0 being the lower bound and 1 being the upper. Then for each value from the first value to the last (inclusive), we loop through using i as an iteration variable and set $game_switches[i] to @params[2] == 0, which will be true if you selected ON, and false if you selected OFF (since they have values of 0 and 1 respectively).



Control Variables is a little more complex, obviously because it has more options. First of all, value is set to 0. Then we have a case statement for @params[3], which as the comment says is for the operand. When 0 (constant), value is set to @params[4] (the value in the box). When 1 (Variable), value is set to the element of $game_variables corresponding to @params[4]. When 2 (Random), value is set to @params[4] (the value in the first box) plus a random number from 0 to 1 less than the difference between @params[5] (the value in the second box) and @params[4]. Basically, if you wanted, say, a random number from 20 to 40, value would be 20 + a random number from 0 to 21 exclusive (so 0-20). When 3 (Game Data), value is set to the result of calling game_data_operand with @params[4] (type), @params[5] (param 1) and @params[6] (param 2) as arguments. We'll look at game_data_operand in a sec. When 4 (Script), value is set to the result of evaluating the script entered in the box, stored in @params[4].

Finally, we'll loop through each value from @params[0] to @params[1] (which will either be a single value or a lower and upper bound for "Batch" as with switches) using i as the iteration variable, and each iteration we'll call operate_variable with i, @params[2] and value as arguments. Again, we'll look at that in a sec.



This is the method which returns the game data being used for the "Game Data" setting of Control Variables. It takes three parameters: type, param1 and param2.

First, we have a case statement for type.

When 0 (Items), we return the party's currently-held number of the given item.

When 1 (Weapons), we return the party's currently-held number of the given weapon.

When 2 (Armour), we return the party's currently-held number of the given armour.

When 3 (Actors), we set actor to the element of $game_actors with ID param1 (the actor chosen in the box), then if the variable contains data we have another case statement for param2 (the parameter in the second box). When 0 (Level), we return the actor's level. When 1 (Exp), we return the actor's experience. When 2 (HP), we return the actor's HP. When 3 (MP) we return the actor's MP. When between 4 and 11 inclusive (Parameters) we return the actor's parameter with ID param2 - 4 (because obviously the internal parameter IDs start at 0 but param2 starts at 4, so we need to subtract the difference).

When 4 (Enemies), we set enemy to the element of $game_troop with ID param1, then if the variable contains data we have another case statement for param2. When 0 (HP), we return the enemy's HP. When 1 (MP), we return the enemy's MP. When between 2 and 9 inclusive (Parameters) we return the enemy's parameter with ID param2 - 2.

When 5 (Character), we set character to the result of get_character with param1 as its argument, then if the variable contains data we have a case statement for param2. When 0 (X coordinate), we return the character's x. When 1 (Y coordinate), we return the character's Y. When 2 (Direction), we return the character's direction. When 3 (Screen X), we return the character's screen x. When 4 (Screen Y), we return the character's screen y.

When 6 (Party), we set actor to the element of $game_party.members with ID param1, then if the variable contains data we return the actor's ID, otherwise we return 0 (because they're not in the party).

When 7 (Other), we have a case statement for param1. When 0 (Map ID), we return the map ID from $game_map. When 1 (Number of party members) we return the size of $game_party.members. When 2 (Gold), we return the gold of $game_party. When 3 (Steps), we return the steps of $game_party. When 4 (Play time), we return the number of passed frames divided by the frame rate (so for example, say the frame_count is 5938 frames, we divide that by the frame rate (60 fps by default) to see that we've been playing for 98 seconds. When 5 (Timer), we return the number of seconds elapsed in $game_timer. When 6 (Save count), we return the number of times the player has saved the game. When 7 (Battle count), we return the number of battles the player has fought.

Finally, we return 0 if no other case has been hit.



The operate_variable method executes the variable operation selected in the Control Variables command, and takes three parameters: variable ID, operation type, and value. First we have a case statement for operation_type. I shouldn't have to go through it at this point after everything else I've covered, but basically 0 sets the variable to value, 1 adds value to it, 2 subtracts value from it, 3 multiplies it by value, 4 divides it by value, and 5 divides it by value and returns the remainder. The rescue part of the begin-end block will catch any exceptions (if we try to divide by 0, for example) and set the variable to 0 instead.



This is the method for the Control Self Switch command. First we make sure @event_id is greater than 0, because if we're not in a map event there's no point in doing anything with self switches. key is set to an array consisting of the map ID, event ID and @params[0] (which is the letter of the self switch being checked), then $game_self_switches[key] is set to @params[1] == 0. So if, for example, you're turning self switch C of event 5 on map 3 OFF, $game_self_switches[3, 5, "C"] will be set to (1 == 0), or false.



This is the method for the Control Timer command. If @params[0] is 0 (start), call the start method of $game_timer with @params[1] multiplied by the frame rate as an argument (which converts the seconds of the timer dialog into the number of frames). If it's 1 (stop), we call $game_timer's stop method. Simples!



This is the method for the Change Gold command. Sets value to the result of operate_value with @params[0], @params[1] and @params[2] as arguments. As you'll no doubt remember from way earlier when we still had hopes and dreams and this episode wasn't the length of all the previous ones combined, these are for the parameters operation (increase or decrease), operand type (constant or variable), and operand (numeric value of variable ID). Then calls the gain_gold method of $game_party with value as the argument.

So carrying on our fine tradition of worked examples, if I choose "Increase", "Constant" and value 500, the values passed to operate_value will be 0, 0 and 500. Then the check for value setting will end up being 500 because operand_type is constant, and operation is increase so the returned value is still value. Had it been "decrease", the value returned would have been -500.



Exactly the same thing as before but with items. Only thing to add is that gain_item takes an additional parameter, which is the item object being gained.



Same thing as before but with weapons. Again we're adding an additional parameter for the "include equipment" checkbox, but that's only relevant if we're subtracting weapons.



Exactly the same thing as before but with armour. This time I have nothing more to say.



This is the method for the Change Party Member command. First, sets actor to the element of $game_actors with ID @params[0]. If the actor exists, then checks to see whether @params[1] is 0 (Add). If so, first checks whether @params[2] is 1 (Initialise checkbox) and if so calls the actor's setup method. Then regardless of the value of @params[2], we call the add_actor method of $game_party, with @params[0] as the argument. If @params[1] is 1 (Remove), we simply call the remove_actor method of $game_party, with @params[0] as the argument.



The Change Battle BGM command. Simply sets the battle_bgm property of $game_system to @params[0]. This will end up being an instance of RPG::BGM consisting of the filename, volume and pitch.



Same thing but for the battle_end_me, the ME that plays when a battle finishes (to this day I can't figure out what ME stands for).



This is the method for the Change Save Access command, and simply sets the save_disabled property of $game_system to the result of @params[0] == 0. As with everything else using this pattern, 0 is ON, 1 is OFF.



Same thing but for the Change Menu Access command.



Same thing but for Change Encounter Disable. Calls make_encounter_count in case you're re-enabling encounters after they've been disabled, otherwise the encounter count won't be re-initialised properly.



Same thing but for Change Formation Access.



This is the method for the Change Window Colour command. Sets the window_tone property of $game_system to @params[0], which will be the R, G, B and grey values of the chosen colour (grey will always be 0 as you can't modify it in the window colour dialog).



This is the method for the Transfer Player command. Returns if the party is in battle (because there's no map for the player to be transferred from/to). Yields the fiber to its caller while the player is in the process of transferring or a message is visible.

If @params[0] is 0 (direct designation), map_id is set to @params[1], x is set to @params[2] and y is set to @params[3]. If params[0] is 1, these variables are set to the element of $game_variables with ID @params[1], @params[2] and @params[3] instead.

Then, we call the reserve_transfer method of $game_player, passing in the map id, x, y and @params[4] (the direction to face after transfer, using the usual values for directions), and the fade_type property of $game_temp is set to @params[5] (which will be the numerical value for normal, white or none) and finally we once again yield the fiber to its caller if the player is transferring.



More or less the same thing but for Set Vehicle Location. The main differences are that we have a parameter for which vehicle to move, no parameter for direction, and we're using its set_location method.



More or less the same thing but for Set Event Location. Uses get_character as usual to get the character object being moved, and uses the moveto method. Note that unlike the previous two methods, this one can't move an event to a different map (which makes sense, as events data is tied to the map it's created on; in order to have the same event on multiple maps, you'd have to make a copy of it) though we do have an additional option for @params[1], which is 2 (Exchange with another event) which just uses the swap method we looked at way back when we covered Game_Character. Finally, if @params[4] > 0 (we didn't choose "retain" for the direction) we call set_direction supplying @params[4] as the argument.



This is the method for the Scroll Map command. Returns if the party is in battle, as there's no map to scroll. Yields the fiber to its caller while the map is in the process of scrolling, then calls the start_scroll method of $game_map, providing @params[0], @params[1] and @params[2] as arguments (the direction, distance and speed for the scroll).



This is the method for the Set Move Route command. Calls the refresh method of $game_map if need_refresh is true. Calls get_character with @params[0] as the argument and assigns the return value to the character variable, then if that variable contains data calls the force_move_route method with @params[1] as the argument. Yields the fiber to its caller while the character is being forced into a move route if the "wait for completion" box was checked.



This is the method for the Get on/off Vehicle command, and simply calls the get_on_off_vehicle method of $game_player.



This is the method for the Change Transparency command, and simply sets the transparent property of $game_player to the result of @params[0] == 0; as with most other assignments that use this structure, a value of 0 means transparency ON and 1 turns it OFF.



This is the method for the Show Animation command. Stores the return value of get_character in the character variable, with @params[0] as its argument, then if the character exists sets its animation ID to @params[1]. Yields the fiber to its caller while the character's animation ID is greater than 0 if the "wait for completion" box was checked.



Exactly the same for Show Balloon Icon, only difference is that we're setting balloon_id instead of animation_id.



This is the method for the Temporarily Erase Event command. Calls the erase method of the current event if the player is on the same map as the event is and @event_id is greater than 0 (you may not remember from last time, but all the erase method does is set a flag that stops event pages from processing).



This is the method for the Change Player Followers command. Sets the visible property of $game_player.followers to @params[0] == 0 (this works exactly the same as every other method that's used for setting boolean properties) and then calls $game_player's refresh method.



This is the method for the Gather Followers command. Returns if the party is in battle (because obviously battle doesn't have any followers) then calls the gather method of $game_player.followers. Yields the fiber to its caller until all followers are in the same tile.



This is the method for the Fadeout Screen command. Yields the fiber to its caller while $game_message.visible returns true. Then calls the start_fadeout method of screen, with 30 as the argument (by default fades take 30 frames), and finally calls wait(30) to wait for 30 frames as well.



Exactly the same as previous but calls start_fadein instead of fadeout.



This is the method for the Tint Screen command. Calls the start_tone_change method of screen, with @params[0] and @params[1] as arguments (@params[0] is a Tone object containing the RGBGr values chosen for the tint, @params[1] is the time in frames) and then also calls wait for @params[1] frames if the "wait for completion" box was checked.



Same thing but for Screen Flash.



Same thing but for Screen Shake. There's actually a bug here because the second line should be "wait(@params[2]) if @params[3]"; they got the indexes wrong. The way it's written, it's waiting for [speed] frames if a duration is set (which is always true). This means that by default waiting for completion on a screen shake doesn't work.



This is the method for the Wait command, and simply waits for @params[0] frames.



This is the method for the Show Picture command. If @params[3] is 0, meaning direct coordinate designation, then x is set to @params[4] and y to @params[5] (obviously, these are the X and Y coordinates you entered in the dialog). Otherwise, the same variables are used as indexes for $game_variables instead. Regardless, we call the show method of screen.pictures[@params[0]], which is the picture number entered in the dialog. As parameters, we supply the name, origin, x, y, zoom x, zoom y, opacity and blend type, as defined by the various elements of @params.



This is the method for the Move Picture command, which is almost identical to Show Picture, but calls the move method instead of show, and waits for @params[10] frames if the wait until completed box was checked. The main difference in the arguments is that we don't have a picture number, and we're adding an additional argument for duration. command_232 doesn't actually have a @params[1], presumably to keep the parameter indexes the same for variables common to showing and moving.



This is the method for Rotate Picture. Not much to say about this one, it simply calls the rotate method of the given picture with @params[1] (speed) as the argument.



This is the method for Tint Picture. Again quite a simple one, calls start_tone_change on the chosen picture with @params[1] (the tone) and @params[2] (duration) as arguments, waiting for duration frames if the wait for completion box was checked.



This is the method for Erase Picture. Calls the erase method of the picture. We should be getting the idea by now.



This is the method for Set Weather. Slightly more complex this time but not that bad: returns if the party is in battle, because weather effects can't happen in battles (though all you really have to do to enable weather in battles is comment out that line and add the appropriate creation/disposal/update of a Spriteset_Weather instance to Spriteset_Battle). Calls the change_weather method of screen with @params[0] (weather type), @params[1] (power) and @params[2] (duration) as arguments. As with everything else that has a wait until completion checkbox, will wait @params[2] frames if it's checked.



This is the method for Play BGM, and simply calls the play method of @params[0], which is the BGM object created by the dialog.



This is the method for Fadeout BGM, and calls the fade method of the RPG::BGM class with the number of seconds * 1000 as an argument (because the parameter for fade is in milliseconds).



This is the method for the Save BGM command, and simply calls the save_bgm method of $game_system.



This is the method for Resume BGM. Surprise surprise, same thing as before but with replay_bgm instead.



Play BGS, pretty much identical to Play BGM.



Fadeout BGS, identical to Fadeout BGM. Noticing a pattern?



Play ME.



Play SE.



Stop SE! I'm honestly not sure why they didn't include a fadeout/stop ME command, but there's nothing stopping you from setting up commands you can call via script if you need them. RPG::ME does have fade and stop methods.



This is the method for Play Movie. Yields the fiber to its caller while a game message is visible, then yields the fiber again (this gives any message box preceding the movie time to fully close before the movie plays; without this line it ends up still being partially visible), sets name to @params[0] (the filename of the movie you chose in the dialog) then calls the play_movie method of the Graphics class with the relative path to the movie as its argument, unless the name is an empty string (this prevents exceptions from trying to play a movie when the choice was "none").



This is the method for the Change Map Name Display command. Simply sets the name_display property of $game_map to true if you picked ON (0) and false if you picked OFF (1).



This is the method for the Change tileset command, and simply calls the change_tileset method of $game_map with @params[0] as the argument, which is the ID of the tileset to change to.



This is the method for the Change Battle Background command, and calls $game_map's change_battleback method with @params[0] (the name of the first background) and @params[1] (the name of the second background) as arguments.



This is the method for the Change Parallax Background command, and calls $game_map's change_parallax method with @params[0] (background name), @params[1] (whether scroll horizontal is checked), @params[2] (horizontal speed), @params[3] (whether scroll vertical is checked) and @params[4] (vertical speed) as arguments.



This is the method for the Get Location Info command. If @params[2] is 0 (direct designation) then x is @params[3] (the X coordinate of the target tile) and y is @params[4] (the Y coordinate of the target tile). If it's 1 (designation with variables) those parameters are used as indexes to $game_variables instead. We then have a case statement for @params[1] (info type). When 0 (terrain tag), value is set to the terrain tag set at the given X/Y. When 1 (event ID), value is set to the ID of the event at the given X/Y. When 2 to 4 inclusive (tile ID layers 1, 2 and 3), value is set to the ID of the tile on the chosen layer (subtracting 2 from @params[1] because the tile IDs are 0-indexed). Otherwise (technically 5, region ID), value is set to the ID of the region the given tile is part of. Following the case statement, we set the variable with index @params[0] to value.



This is the method for the Battle Processing command. Returns if the party is in battle (do I really have to explain why?). If @params[0] is 0 (direct designation of troop), then troop_id is set to @params[1] (the ID of the troop you'll be fighting). If it's 1 (designation with variables), @params[1] is used as an index for $game_variables instead. Otherwise, it's a map-designated troop so we call the make_encounter_troop_id method of $game_player to figure out what the encounter is. If there's a troop corresponding to the calculated ID, we call the setup method of BattleManager, passing in the troop ID, @params[2] (whether the player can escape) and @params[3] (whether the player can lose) as arguments.

Then we set the event_proc property of BattleManager to a new Proc where @branch[@indent] is set to the passed-in value n. This allows the battle end method of BattleManager to set @branch[@indent] to 0, 1 or 2 depending on whether the player won, escaped or lost, via BattleManager.event_proc.call, which you may not remember us looking at way back in Under the Hood part 2. After that we call the make_encounter_count method of $game_player, which refreshes the encounter counter on the map (because it would kind of suck to end up in a random battle immediately after fighting a boss) and then the call method of SceneManager is called, with Scene_Battle as its argument. This obviously transitions the scene to the battle scene. Finally, we yield the fiber to its caller, which prevents the rest of the event commands from processing before the battle is finished.



601 is the code for the "win" branch of a battle. Skips the command if @branch[@indent] isn't 0, because that means the player didn't win.



Same as before, but for 602 (escape).



Same as before, but for 603 (lose).



This is the method for the Shop Processing command. Returns if the party is in battle (though who wouldn't want to buy some potions during a boss fight?) and sets goods to @params as an array element.

Initially, @params is just an array consisting of the item type (0 = item, 1 = weapon, 2 = armour), item ID, standard price flag (0 = standard, 1 = specific), 0 if standard or the price if specific, and a true/false value for whether the shop is purchase-only. We then have a while loop as long as the next event code is 605 (additional shop goods), in which the index is incremented and we push the current event command's parameters to goods (those parameters will be an array with the same elements as the initial one, with the exception of the purchase-only flag). Then we call the call method of SceneManager, with Scene_Shop as the argument, and call the prepare method of SceneManager's scene property (which is now an instance of Scene_Shop), with goods and @params (the purchase-only flag) as arguments. This just initialises the instance variables of Scene_Shop, as we'll see when we eventually get to it. Then, as before, the fiber is yielded to its caller so that further event commands aren't processed before we're done shopping.



This is the method for the Name Input Processing command. Returns if the party is in battle (seriously, Enterbrain, you're missing a trick here. If Alex does terribly in battle I want to rename him to something mean). If an actor exists with the ID @params[0], we call Scene_Name, and the prepare method of the scene with @params[0] (the ID of the actor) and @params[1] (the maximum number of characters) as arguments. Then, we yield the fiber to prevent processing of further commands.



This is the method for the Change HP command. Sets value to the result of calling operate_value with the options chosen in the dialog (I shouldn't have to explain the inner workings of this by now, we've gone over it so many times). We call iterate_actor_var passing in @params[0] (0 for fixed actor, 1 for variable) and @params[1] (actor or variable ID) and use the method as an iterator for a loop, using actor as the iteration variable. We go to the next iteration if the current actor is dead; if not, we call change_hp using value and @params[5] (whether the actor can die) as arguments. If the actor is now dead, we call perform_collapse_effect (only relevant in battle). Once the loop is done, we go to Scene_Gameover if the entire party has died. (You may not remember from when we looked at the modules, but goto is similar to call but doesn't use a stack, because if we're going to the game over screen there are no further scenes to transition to anyway).

As I promised we'd look into iterate_actor_var more when we got to it, let's look at a practical example. I've chosen to decrease Eric's HP by the value of variable 50 (let's say it contains 25), not allowing him to die.

This makes the first line: value = operate_value(1, 1, 50). In operate_value, value becomes the value of variable 50, which is 25, and because it's a decrease this is converted to -25.

We then call: iterate_actor_var(0, 1) and as param1 is 0, we call iterate_actor_id(1) with the block {|actor| yield actor}. In iterate_actor_id, param is 1 so actor is set to $game_actors, and because actor exists the "yield actor" line is processed. This passes the actor object to the block from iterate_actor_var, which then yields the actor to command_311, and the object is stored in the "actor" iteration variable. Alex isn't dead, so we skip the next line. We call actor.change_hp(-25, 0), which sets Alex's self.hp to += -25, so his HP ends up going down by 25. He's not dead, so we don't perform the collapse effect, and the party isn't dead so we don't have to switch to the game over scene.



This is the method for the Change MP command. Sets value using operate_value as usual, then iterates through the actors chosen in the same way as Change HP does. Then actor.mp is increased by value (which obviously results in a decrease if value is a negative number).



This is the method for the Change State command. Iterates through the actors chosen in the same way as usual. Sets already_dead to true if the actor is dead and false otherwise. If @params[2] is 0 (add state), we call the actor's add_state method with @params[3] (the ID of the state chosen) and if it's 1 (remove state) we call remove_state instead with the same argument. After this, we call perform_collapse_effect if the actor is now dead and wasn't already before the state was added/removed, and after the iteration loop we call clear_results on $game_party (which clears each party member's result property). I'm honestly not quite sure why the call to clear_results is there, as adding a state like this doesn't show in the battle log anyway.



This is the method for Recover All. Iterates through the actors chosen using iterate_actor_var and then calls recover_all for each actor.



This is the method for Change EXP. Pretty much the same as the other Change commands, but calling change_exp instead. @params[5] is the value of the "show level up message" checkbox.



Same as before, but for Change Level.



Same as before but for Change Parameters. @params[2] contains the ID of the parameter to be changed.



This is the method for Change Skills. Iterates through the chosen actors; if @params[2] is 0 (learn skill) we call the actor's learn_skill method. If it's 1 (forget skill) we call the actor's forget_skill method. In both cases, @params[3] is used as the argument (the ID of the skill to learn/forget).



This is the method for Change Equipment. Gets the actor with ID @params[0] and calls their change_equip_by_id method, passing in @params[1] (slot ID) and @params[2] (item ID) if the actor exists.



This is the method for Change Name. Gets the actor with ID @params[0] and calls their name method, passing in @params[1] (new name) if the actor exists.



Same as before but for Change Class. @params[1] is the ID of the chosen class, and there's an additional validation check to make sure that class actually exists in $data_classes.



This is the method for Change Actor Graphic. I'm not sure why the if statement was done as a block here instead of having it on one line like the others, but whatever. After calling set_graphic on the actor with @params[1] (character name), @params[2] (character index), @params[3] (face name) and @params[4] (face index) as arguments, we call the refresh method of $game_player (this refreshes the character name/index and followers).



This is the method for Change Vehicle Graphic. @params[0] contains the ID of the vehicle chosen in the dialog. We call the set_graphic method of the vehicle with @params[1] (character name) and @params[2] (character index) if the vehicle exists.



This is the method for Change Nickname. Gets the actor with ID @params[0] and calls their nickname method, passing in @params[1] (new nickname) if the actor exists.



This is the method for Change Enemy HP. It's pretty much identical to Change HP, only it uses iterate_enemy_index and you can't use a variable to determine which enemy is affected.



This is the method for Change Enemy MP. Pretty much the same as Change MP. Again, it uses iterate_enemy_index and you can't use a variable for the enemy ID.



This is the method for Change Enemy State. Again, pretty much the same as Change State with the aforementioned changes.



This is the method for Enemy Recover All. Second verse, same as the first.



This is the method for Enemy Appear. Calls iterate_enemy_index as usual and calls the chosen enemy's appear method, which just sets its hidden flag to false. We then call the make_unique_names method of $game_troop in case there are already living enemies of the same type in the battle.



This is the method for Enemy Transform. Calls iterate_enemy_index as before and calls the chosen enemy's transform method with @params[1] (The ID of the enemy to transform into) as the argument. Then, as before, we call make_unique_names in case there are already living enemies of the same type.



This is the method for Show Battle Animation. Calls iterate_enemy_index and then sets the chosen enemy's animation_id to @params[1] (the ID of the animation to show) if the enemy is alive.



This is the method for Force Action. Calls iterate_battler (because we don't know whether we're forcing an action for an actor or an enemy) with arguments @params[0] (0 for enemy, 1 for actor) and @params[1] (ID of the actor or enemy) using the iteration variable battler. We go to the next iteration if the battler has the death state, because you can't force dead people to do anything. Next, we call the force_action method of the battler, passing in @params[2] (ID of the skill to force) and @params[3] (the index of the target). Then we call the force_action method of BattleManager passing in the battler, which removes the battler from the main action order and flags it as having its action forced.

Finally, we yield the fiber to its caller while an action is being forced, so that no other battle event commands will be processed until the action is done.



This is the method for Abort Battle. Calls the abort method of BattleManager, which sets the phase to :aborting, as we already looked at in an earlier episode. Finally, yields the fiber to its caller to stop any remaining event commands from executing.



This is the method for Open Menu Screen. Returns if the party is in battle, then calls SceneManager's call method passing in Scene_Menu. Directly calls the init_command_position of the Window_MenuCommand class (which sets the class variable @@last_command_symbol to nil) then yields the fiber to its caller so that any further event commands won't process.



This is the method for Open Save Screen. Pretty much identical to the menu one above.



This is the method for Game Over. As mentioned previously, we use goto here instead of call because logic dictates that no scenes are going to be called after game over.



This is the method for Return to Title Screen. Nothing more to say.



And this is the method for Script. Sets script to the event command's parameters[0] (which is the first line of the script) plus a newline character. While the next event code is 655 (further script lines), we increment index by 1 and add the new command's parameters[0] to the script. Finally, we evaluate the full script and return the result.

And...that's it! We're finally done! That is the whole interpreter! This took me like three days! I'm overusing exclamation marks and I don't care!

Now that we're done with the behemoth that is the game objects, we're moving on to sprites. This shouldn't take too long as for the most part these scripts are pretty small. After that, we'll cover windows, then scenes. I promise the next part won't take as long as this one did, either. :)

As usual, if you have any comments, queries, criticisms, corrections or death threats, you know where to write it. I'm expecting a fair few clarification questions as we've covered a couple of pretty advanced topics, especially Fiber and Proc.

Until next time.