Tuesday, February 16, 2016

Plugin: Terrain Battle Backs (MV)

The struggle to adapt my game to the latest version of RPG Maker continues, in spite of the frustrating limitations of developing a game inspired by classics that were designed for the desktop on a mobile platform.

You might remember my efforts at customizing the battle backgrounds automatically chosen based on terrain type on designated world maps in VX Ace, which I detailed in this post from two years ago (egads, has it really been that long?). That there isn't a built-in, user-friendly way to adjust these choices is one of those things in RPG Maker that amazes me.

Previously, I had opted to run a Parallel Process event on the world map to constantly check the tile ID (and thus, type of terrain) of the spot the player was standing on at any given time, in order to manually override the choice of battle background. It's a testament to how much has changed in the past couple of years that my first instinct this time around was to try and develop a scripted solution that modifies the way the backend code functions, instead.

So, I opened up the hood and jumped into the code. As a potentially relevant side note, MV is programmed in JavaScript. Trying to make sense of the tens of thousands of lines of code - and, particularly, trying to find the parts that do the stuff you want to modify - is no easy task. But I was able to track down the very function(s) that determine which battle background goes with which type of terrain. They are located (for reference) in rpg_sprites.js on lines 2530-2572. I'll copy them here:
Spriteset_Battle.prototype.terrainBattleback1Name = function(type) {
    switch (type) {
    case 24: case 25:
        return 'Wasteland';
    case 26: case 27:
        return 'DirtField';
    case 32: case 33:
        return 'Desert';
    case 34:
        return 'Lava1';
    case 35:
        return 'Lava2';
    case 40: case 41:
        return 'Snowfield';
    case 42:
        return 'Clouds';
    case 4: case 5:
        return 'PoisonSwamp';
    default:
        return null;
    }
};

Spriteset_Battle.prototype.terrainBattleback2Name = function(type) {
    switch (type) {
    case 20: case 21:
        return 'Forest';
    case 22: case 30: case 38:
        return 'Cliff';
    case 24: case 25: case 26: case 27:
        return 'Wasteland';
    case 32: case 33:
        return 'Desert';
    case 34: case 35:
        return 'Lava';
    case 40: case 41:
        return 'Snowfield';
    case 42:
        return 'Clouds';
    case 4: case 5:
        return 'PoisonSwamp';
    }
};
If you're not familiar with switch statements, they're basically extended conditionals, which check the value of a variable - each "case" basically tells the program "if this, then do that". The first thing you should note is that there are in fact two separate functions, corresponding to the two parts of the battle background - the bottom or ground section, and the top or wall section. This should be familiar to you if you've ever worked with the battle backgrounds, or looked at the associated image files that are named in these functions.

Another thing you might notice is the numbers that are being dealt with here. The function takes an argument (named "type") that, as you might guess, corresponds to the terrain-dependent tile ID, which is then evaluated in the switch statement. What's interesting is that these numbers are much smaller than the unwieldy tile IDs we dealt with before, which ran the gamut from 2048-4350. There's a rather obvious reason for this, that I must admit I discovered in an embarrassingly roundabout fashion. Those larger numbers are still relevant, as by using the Get Location Info event command, you'll find in-game that they haven't changed from VX Ace to MV. But for coding purposes, a little bit of math has been performed to make them more palatable. You can find that calculation in another function located on lines 5912-5915 of rpg_objects.js:
Game_Map.prototype.autotileType = function(x, y, z) {
    var tileId = this.tileId(x, y, z);
    return tileId >= 2048 ? Math.floor((tileId - 2048) / 48) : -1;
};
Basically, what this function does is take the tile ID corresponding to a location on the map determined by the x, y, and z (or layer level) coordinates, passed into the function as arguments. It then subtracts 2048 (since, I don't know why, but the IDs start at - and are thus offset by - a base value of 2048), and divides that number by 48. This makes sense because if you take the time to scrutinize, as I have, you'll find that there is a space of 48 numbers between each different type of terrain. These correspond to the various orientations of autotile placement which I have annotated in detail in my previous post for VX Ace.

But since choosing a battle background doesn't depend on whether you're standing on a "border" tile or a "center" tile (or what have you), you can essentially boil each set of 48 IDs down to a single terrain-dependent index. Which is exactly what the above calculation is doing (note also that if the tile ID doesn't fall into the expected range, the function returns a -1 instead, presumably for fallback purposes). Now, the thing that made me feel stupid for not realizing it sooner was the fact that, after you perform the calculation, what you're left with is nothing more than the placement index (starting at 0) of the tiles as they appear in the editor for the World_A tileset!

To illustrate, where we had this before:


We now have something much simpler (and more predictable!):


I'm not sure if this had crossed my mind before, but the indices (and the tile IDs they correspond to) are all unique. Meaning that, although they're stacked on either of two separate layers - so that a given tile can have both a Layer 1 ID and a Layer 2 ID - the numbers on either layer never overlap. So if you give me a number, I can tell you exactly what type of terrain it corresponds to without knowing whether it's a Layer 1 or a Layer 2 ID. Which, it turns out, is exactly what the functions with the long switch statements that I copied above are doing. So then, you might ask, are those functions evaluating Layer 1 or Layer 2 IDs? And how is that determined? Exploring the functions that call those two functions will answer those questions. You can find them in rpg_sprites.js at lines 2518-2528. Here they are:
Spriteset_Battle.prototype.normalBattleback1Name = function() {
    return (this.terrainBattleback1Name(this.autotileType(1)) ||
            this.terrainBattleback1Name(this.autotileType(0)) ||
            this.defaultBattleback1Name());
};

Spriteset_Battle.prototype.normalBattleback2Name = function() {
    return (this.terrainBattleback2Name(this.autotileType(1)) ||
            this.terrainBattleback2Name(this.autotileType(0)) ||
            this.defaultBattleback2Name());
};
As well as I can figure, these functions run when the game is trying to load a battle and determine which battle background to use. Again, you'll note that there are two separate functions, one for each half of the battle background. They each do essentially the same thing, however, which is to call the long switch functions we've already seen (hereafter referred to as "the terrainName function(s)") to determine which battle background to use based on the terrain corresponding to the index evaluated via the autotileType function (the one with the math that we examined above).

If you're paying attention, you'll note that here the function only takes a single argument, whereas before it took three. This is confusing, but the explanation for it is quite simple. The previous autotileType function belonged to the Game_Map class. But here, we're dealing with the Spriteset_Battle class, which has defined its own autotileType function. But before you throw your arms up in frustration, this local version of the function is nothing more than a shortcut to that other version, but with the x and y arguments already predetermined to be the player's x and y map coordinates. You can examine the function yourself. It is located in rpg_sprites.js at lines 2590-2592, which I will reproduce here:
Spriteset_Battle.prototype.autotileType = function(z) {
    return $gameMap.autotileType($gamePlayer.x, $gamePlayer.y, z);
};
So, returning to the normalBattlebackName functions (hereafter referred to as "the normalName function(s)"), when they call the terrainName functions, they're passing in an index corresponding to a tile ID at either the first or second layer, depending on whether the autotileType function is being passed a 0 or a 1 (note that since counters in programming usually start at 0, the 0 corresponds to Layer 1, and the 1 corresponds to Layer 2 - try not to get confused). There's something a little weird going on here, though, because each normalName function is trying to return the value of a call to the corresponding terrainName function (which would be the name of the battle background file associated with the given terrain), but it's tangled up in an OR operator ("||"). Let's take a closer look:
return (this.terrainBattleback1or2Name(this.autotileType(1)) ||
            this.terrainBattleback1or2Name(this.autotileType(0)) ||
            this.defaultBattleback1or2Name());
It took me a while to get a firm grasp on what exactly is going on here, even though it's largely intuitive. (Sometimes explicit instructions are helpful). For a detailed explanation of the behavior of JavaScript's OR operator, read this. Suffice to say, the operator responds not just to true/false evaluations, but also to the wishy-washy properties of truthiness/falsiness. Sounds messy, doesn't it?

I'm pretty confident, though, that what's going on in these normalName functions is that they're trying to call the corresponding terrainName function first with the Layer 2 ID (giving it precedence). If the tile the player is standing on has no Layer 2 ID (presumably resulting in a "falsey" value), then it calls the function instead using the Layer 1 ID. And then, if for some reason there's no Layer 1 ID either, it falls back to a default (calling a simple function that does nothing more than return the 'Grassland' battleback - whether top or bottom).

---------

Are you with me so far? Because here's where we get to start customizing things. Now that we know which indices correspond to which terrains (see the second image above), it would be a simple matter to just change the names of the battle backgrounds in those functions with the long switch statements, or even to add new cases to designate other battle backgrounds for terrains that the default function doesn't account for.

(Disclaimer: I don't advise changing the original JavaScript files that come packed in with the program. But if you copy the important functions into a new JavaScript file, and make your adjustments there, then you can add it in the same way you do with your other plugins (MV terminology for scripts), and add it to your game via the plugin manager. That way, if there are any problems in the future, you have the simple option of either turning off or getting rid of the plugin completely, and reverting to the game's default functionality).

But in the process of doing this, I hit a little snag, because I like to have a little bit more fine-tuned control over the choice of battle background depending not just on either the Layer 1 or Layer 2 ID, but in some cases the result of their combination. In different cases, the Layer 2 ID might take precedence, whereas in others, the Layer 1 ID will be more important. My way of dealing with this via the eventing solution I used in VX Ace was to simply handle both Layer IDs simultaneously and check them against each other. But the functions we're dealing with here only consider one ID at a time. So what to do?

I tried a few different ways to get around this limitation, but I ultimately decided to modify the function itself to actually take two arguments instead of just one - one for each of the first two Layer IDs. I checked through all the core scripts (Ctrl-F is your friend), to make sure I knew every place the terrainName functions were being called, so as to avoid any discrepancies in the code. And it turns out that the only time the functions come up is in those cases we've already explored here.

(Another disclaimer: if you use another plugin that attempts to use or modify these same functions, you may encounter problems. I'm only a beginner MV scripter right now, so I wouldn't know how to minimize that possibility, e.g. by aliasing or whatever. Feel free to add in some contingency code yourself if you know how to go about doing that).

So all I had to do was change the (type) part of the function to a (type1, type2), and then in the normalName functions where the terrainName functions are being called, replace the first part of the confusing OR evaluation (while preserving the default fallback), so as to call the terrainName function just once with both arguments - one that retrieves the autotileType for Layer 1, and one for Layer 2. This is what the modified functions look like:
Spriteset_Battle.prototype.normalBattleback1Name = function() {
    return (this.terrainBattleback1Name(this.autotileType(0),
            this.autotileType(1)) || this.defaultBattleback1Name());
};

Spriteset_Battle.prototype.normalBattleback2Name = function() {
    return (this.terrainBattleback2Name(this.autotileType(0),
            this.autotileType(1)) || this.defaultBattleback2Name());
};
All that was left then was to modify the terrainName functions, by manipulating the switch statement(s), and in my case, adding in a couple of extra if/else statements for better flow, to tie the proper battle backgrounds to the proper combination of terrains. Here's what I ended up with (although I may make some more fine-tuned adjustments in the future):
Spriteset_Battle.prototype.terrainBattleback1Name = function(type1, type2) {
    if (type2 === 29) {
        return 'Cobblestones2';
    } else if (type2 === 37) {
        return 'Cobblestones4';
    } else {
        switch (type1) {
        case 4: case 5:
            return 'PoisonSwamp';
        case 8:
            return 'Ship';
        case 10: case 40:
            return 'Snowfield';
        case 16: case 18:
            switch (type2) {
            case 17: case 19:
                return 'Meadow';
            case 20: case 21:
                return 'GrassMaze';
            default:
                return 'Grassland';
            }
        case 24: case 26:
            return 'Wasteland';
        case 32:
            if (type2 === 33) {
                return 'Desert';
            } else {
                return 'Sand';
            }
        case 34:
            if (type2 === 35) {
                return 'Lava2';
            } else {
                return 'Lava1';
            }
        case 42:
            return 'Clouds';
        default:
            return null;
        }
    }
};

Spriteset_Battle.prototype.terrainBattleback2Name = function(type1, type2) {
    if (type2 === 30 || type2 === 38 || type2 === 41 || type2 === 46) {
        return 'Cliff';
    } else if (type2 === 21 || type2 === 36 || type2 === 44) {
        return 'Forest1';
    } else {
        switch (type1) {
        case 4: case 5:
            return 'PoisonSwamp';
        case 8:
            return 'Bridge';
        case 10:
            return 'Snowfield';
        case 16: case 18:
            if (type2 === 20) {
                return 'GrassMaze';
            } else {
                return 'Grassland';
            }
        case 24: case 26:
            return 'Wasteland';
        case 32:
            if (type2 === 33) {
                return 'Desert';
            } else {
                return 'Sea';
            }
        case 34:
            return 'Lava';
        case 40:
            return 'Snowfield';
        case 42:
            return 'Clouds';
        }
    }
};
A couple of notes to help you understand what's going on here. In the first function, I used an overriding if statement to return the appropriate ground textures for map tiles that feature roads (indicated by a Layer 2 ID), no matter what Layer 1 terrain is involved (grass, desert, snow, etc.). The rest of the cases are pretty straightforward, except that I provided some alternatives such as a different lower background for plains (indicated by a Layer 1 ID) versus grassy plains (indicated by a Layer 2 ID), and a similar alternative for ashy wasteland versus cracked lavafield (the subtle difference between the Lava1 and Lava2 battle backgrounds).

In the second function, I've used another conditional to override the texture for any tiles that require the Cliff or Forest1 wall texture, since they tend to crop up over a number of different Layer 1 ID terrains. The rest of the switch statement is again pretty straightforward, although here you'll see that I've designated one of the two desert terrains as a "beach" (as opposed to a landlocked desert) by giving it the Sea wall texture instead of the usual Desert wall texture.

And that's pretty much it! Feel free to take these code snippets and play around with them to suit your purposes. I'd love to make a fully customizable plugin out of what I've done here, but I fear that the individual needs of each user will be so specific as to require a heavily personalized combination of conditionals. Come to think of it, that may be why the original programmers haven't already done it.

Just a few last notes. It should be mentioned that in these examples, I've replaced all of my MV image files with resized versions of the VX Ace graphics (because I like them better). So my filenames may not match yours (although many - but not all - of the battleback filenames have remained the same from VX Ace to MV). Make sure the names you use in your code match the filenames in your img/battlebacks folders (1 and 2), minus the file extensions.

On a related subject, if you want to change the default battle background for use while riding the ship, you'll find that in a separate pair of functions that are really simple to modify. Look for them in rpg_sprites.js at lines 2582-2588.

I don't know how or to what extent the solution I've come up with here will dovetail with an airship encounter system, as I haven't tackled that problem in the MV version of my game yet. But if I have anything to say about that in the future, you can be sure to find it here on this blog!

No comments:

Post a Comment