Tile Swap

This script provides functionality for swapping tiles. In a single script call, you can change entire groups of tiles from one tile to another. The changes may be reverted as well using simple script calls.



Script: download here


There are some concepts and terminology that you would need to be familiar with before effectively using this script.

RMVX Ace’s tileset design takes a single tileset and splits it into 5 different pages (A, B, C, D, E). It then takes the A-page and breaks it down into 5 more parts (A1, A2, A3, A4, A5)

This script uses the custom concept of a “tile ID”, which is a special string that represents a particular tile on your tileset page.

The format of a tile ID is a letter, followed by a number.

  • The letter is the tileset page.
  • The number is the position of the tile on that page.

So for example, “A3” would be the the third tile in tileset A, whereas
“B12” would be the 12th tile of tileset B.

It is very easy to look up the position of a tile: just look at your tileset page and number the top-left tile as 1. Then, numbering left-to-right, top-to-bottom, you would get something like this


For page A, it is a little different. This is assuming you have all 5 parts.
If you are missing any parts, you will need to skip them appropriately.
To avoid all the unnecessary math, simply fill up the empty slots with dummy tilesets to make things easier.


The script supports three ways to swap tiles:

  1. Swap by tile ID
tile_swap(old_tileID, new_tileID, layer, map_id)

This is a very simple swap. It takes all of the old tiles and swaps them to the new tile. For maps where you simply want to swap out an unwanted tile, this is the easiest to use.

2. Swap by region ID

region_swap(regionID, tileID, layer, map_id)

This swaps all tiles within a region to the new tile.

  1. Swap by position
pos_swap(x, y, tileID, layer, map_id)

This swaps the tile on the specified position to the new tile.

You can undo any changes by using the following calls

tile_revert(tid, layer, map_id)
pos_revert(x, y, layer, map_id)
region_revert(rid, layer, map_id)

Each method has its own uses in different situations depending on which tiles need to be swapped.


KilloZapit, for providing the code for auto-tile generation.

You may also like...

107 Responses

  1. LynX says:

    Hi Hime is there a way to delete shadows ?After swap ?

  2. Anonymous says:

    Just another person hoping to see this for MV at some point. Love your plugins and videos! Keep hangin’, bro!

    • Hime says:

      It is currently in development, though auto-tiles and auto-layers will not be supported at this point.

      • Robert says:

        Awesome. This is another of my favorites I’d love to see for MV eventually. I originally used it for creating more elaborate spike traps. I’ve found uses for it everywhere though.

  3. Bobadubub says:

    Is it possible to prevent a pos_swap if standing on certain tile IDs?

    e.g. I want to turn the square I am standing on into tile ID X, but only if that tile has ID Y

  4. Cellar says:

    Can you please explain me how you detect tiles, making a game and didn’t undestand that part.

  5. Sara says:

    Can this be used comercially?

  6. Rerre says:

    Hi! First off I gotta say, I love your script! I used it quite a bit in VXAce ^^
    But, to my question, do you have any plans on making it for MV?

    Best Regards,

    • Hime says:

      Yes, I will port it over to MV at some point. Currently, the list of scripts to port over is pretty big and the rate I’m going at them is pretty slow since I’m making videos for each of them as I go

  7. RodStef says:

    Hey, Hime. I have a problem: “Script ‘Nameofmyscript’ line 634: SyntaxError occurred: unexpected ‘:’ alias :tsuki_tile_swap_setup_map: setup”. What should I do? Thanks.

    • RodStef says:

      Hmmm… Sorry, man. That’s not the problem anymore, I solved it. This is the problem: “Script ‘Game_Interpreter’ line 1411: TypeError occurred. can’t convert String into Integer”. I’ve put the script between Materials and Main, I’ve just Ctrl+C and Ctrl+V the script… I’m using this script: “region_swap(1, “A17”, “A46″, 0)” that’s triggered by an event in parallel process. Thanks. Sorry, my english sucks.

  8. Quanah Martinez says:

    Hello. I went to download Tile Swap but the link sends me to a text file. I would really like this Script 🙂

  9. joshua says:

    hey sorry but im completely new too rpg maker and i just cant get this too work?? what am i doing wrong this is my script tile_swap( A98, A37, 1, 2)

  10. Corona MacGuinness says:

    This script is truly marvelous, but I’m having some problems with it. Tiles will swap just fine in button press, collision, touch or even autorun events, but it won’t work for parallel processes. Is this intentional?

    • Hime says:

      I have tested the script in a new project with a parallel process event and it seems to work for me. I only tested the “tile_swap” script call.

      I created a new map, created a patch of water (“A1”) and then used a script call to change “A1” to “A8”. It then waits 60 frames, before changing “A8” to “A1”, and waits another 60 frames. This occurs as a parallel process.

      The result is the patch of water toggling between lava and water in one second intervals.

  11. koldsack says:

    thank you so much hime, this script is no less than amazing!

  12. Hello! How to work with Mask?

    • Hime says:

      I haven’t used the mask very much so not too sure, as I did not write that part of the script. Sorry about that!

  13. Calvin says:

    I downloaded the script, but I keep getting the error Script ‘Game_Interpreter’ line 1411: NoMethodError occurred. undefined method ’tile_swap’.
    Do I need to move the script to a specific location to make it work and if so where?

  14. Japhasca says:

    Sorry if it was asked already, I looked through a bunch and searched but couldn’t find it.
    Does the tile change persist through map transitions and save/load? Or do I need to do a script call when entering a map, if the tile change I want is different than the default map?

  15. X says:

    Hey. Interesting script but : Why this gives me a bug
    with words – " interpreter A ? " It shouldnt happen. It's against logic

    pos_swap(26, 32, A, 17, 2)

    I replaced A with a number and gives me another bug…

    What must be written instead of numbers if i want use switches/variable as arguments (switches/variables – from games and switches/variables from ruby)

    • Hime says:

      Check the usage instructions. The proper way to reference a tile is something like "A24" or "B12".

      You can just use normal ruby for variables. $game_variables can be accessed if you want the game variables.

  16. Harry says:

    Sorry i have to report a Bug again. I hope that is OK.

    If i use the pos revert command within a paralell event, the game crashes.
    even if the code is just running once and than with switch to the seccond event page,
    it crashes also.
    If i select the Action Button Trigger on the Event, it works fine.
    That is strange.

    Besides that one Question:
    Is is possible to use a autotile from for example A1 on layer 2?
    it works, but without autotile functionality. Is it possible that it works like a autotile on layer 2? (Just a question, no emergent need for it at the moment)

    (Iam still learning English, so i hope you can understand what i tryed to explain and ask)

    • Hime says:

      When I fixed the crashing error, I found another bug where the map tiles are constantly being reloaded. Will need to figure out something for that.

      I've updated it so you can draw auto-tiles on layer 2.

      • Harry says:

        The Autotiles on Layer2, it seems to work fine.
        You are right, everytime a pos revert command took action, the
        original map gets loaded for a seccond, and after that all swapped tiles reapear on the map. Did you ment that?

        • Hime says:

          Yes, the way the "revert" is not very clean right now.

          • Harry says:

            Hello Hime,
            I didnt found a Solution for the Buggy
            "revert Command".
            Can you Safe my Day? 🙂

          • Hime says:

            I haven't found a way to address the problem. Consider asking the question on rpgmakerweb forums and see if someone might have an idea.

  17. Harry says:

    pos_revert command isnt working as supposed.
    If i swap around all tiles between x 0to10 and y 0t10 it works perfectly.
    But when i want to revert only one specific tile, he will not let me do that,
    insteed he keeps deleting on tile on the y axis on every call, until it reaches the chosen coordinate.
    (My English isnt the best, hope u can understand) I realy could need that revert command).

    Edit: Your explanation above is wrong:
    pos_revert(x, y, tid, layer, map_id)
    its called:
    pos_revert(x, y, layer, map_id)
    and i used:
    pos_revert(4, 3, 2, map_id)

    • Hime says:

      The problem should be fixed now. See if it works. I have also updated the documentation to show correct usage.

      • Harry says:

        Thank you so much Hime. It seem to work perfect fine now.
        Thank you thank you thank you for answering this so quick.
        If iam able to create a (workaround) Fog of War with this,
        i will share it.

  18. Dijek says:

    Is it possibe to use this script with variables? as in, "pos_swap($Game_Variables[18], $Game_Variables[19], "A27", 1)"?
    It doesn't seem to work for me, though it could be something else in my project…

  19. samdy1 says:

    I get an error 629 – Unidentified method 'setup' in class 'Game_Map'. This is my first time using a script in rpg maker so im not sure where it should have been added. How can I resolve this?

  20. Arsist says:

    For general interest, I want to state that this and Sheolshade’s Minimap
    are compatible.
    You can’t use $game_map.refresh to reset the minimap but you can teleport to a base map then teleport back to the same spot and the minimap will be updated.

    • Hime says:

      I think the mini-map needs to be completely re-drawn from scratch, since there are new tiles. I don’t know how that would be done. Does that minimap work with fomar’s script? Cause both scripts change tiles; it would be strange if one updated the minimap and the other didn’t.

      • Arsist says:

        They are both compatible and update if you teleport. You can just go to a black map or set the screen black for a second, almost as if blinking then seeing a change of scenery.

        • Hime says:

          That’s because the map is only redrawn when you change the map. If you want the map to change if any tiles on the map changes, first update the Tile Swap script, then in the minimap script go to line 344 and change the condition to

          if @map_id != $game_map.map_id || $game_map.need_refresh_tiles
  21. Arsist says:

    Didn’t you have something where you have a house in an area and you swap it to a new location?
    I can’t find all your stuff since it’s in different places

  22. Hey Hime! I keep getting an error,
    “Script ‘Game_Interpreter’ Line1441: NameError Occured.
    Uninitialized constant Game_INterpreter::A11

    that error pops out for every tileID I input.

  23. ObsidiansRealm says:

    I thank you for your help, I will just start a new project since this was only a tutorial map for me.

  24. ObsidiansRealm says:

    Okay, it works on a new project, but not my existing one…. not sure what is going on.

    • Hime says:

      You’ll have to debug the issue on your own as I don’t know what might conflict with the tile swap (or overlay maps). Disabling scripts one at a time to find the problem, etc.

  25. ObsidiansRealm says:

    maybe there is something wrong with my program.

  26. ObsidiansRealm says:

    So for simplicity, if I wanted to do a region swap on the overlay map, region_swap(10, B1, 0, 7) should work?

      • ObsidiansRealm says:

        region_swap(10, “B1”, 0, 7) doesn’t work O_o
        Any other event settings that I should turn off/on like priority or Options?

        • Hime says:

          No, you should be able to just insert the scripts and make the script call. I tried it on a new project with the new updates (oct 23 versions) and the tiles on the overlay map were swapped as expected.

  27. ObsidiansRealm says:

    Invalid Octal Digit.
    pos_swap(009, 003, “B1”, 0, 007)

    • Hime says:

      Don’t have extra 0’s in your numbers. 009 is not the same as 9.

      • ObsidiansRealm says:

        Have seen this discussed, but not spelled out. I am trying to make tiles on an overlay map vanish when I trigger an event. I have tried pos and region both to no effect.
        region_swap(10, A31, all layers tried, tried 007 & 7)
        pos_swap(9, 3, A31, all layers, tried 007 & 7)
        Please help or let me know what I need to do exactly? I am trying for your disappearing fog but with overlay map and tile swap.

        • Hime says:

          Sorry, it looks like there was a bug in the scripts that prevented overlay maps from updating properly. I’ve updated both the overlay maps script as well as the tile swap script to address the issues. Please download the scripts and see if it works.

  28. ObsidiansRealm says:

    I am using your overlay maps & tile swap to create hidden paths. I am using VX Ace if that makes any difference. I can get everything to work until I try region or pos swapping on overlay layer. Region swap doesn’t detect and position swap gives ruby errors.

  29. ObsidiansRealm says:

    Is it possible to swap “overlay” tiles with this? It doesn’t seem to detect the overlay map correctly?

  30. TotalerBob says:

    Are you still giving support for this script? Or not anymore? Because I’m getting an error as I’m starting my game, which say’s: “Script ‘TileSwap’ line 727: SyntaxError occurred. Invalid Text”

    Any idea what this is about?

  31. Buba says:

    It’s possible to change a single tile to anoher tile, from a diferente tileset?
    an exemple, change the normal window to a light window (the last in a different tileset)

  32. Sangmanjin says:

    Is it normal for the shadows to remain after swap?Its not a big problem because it looks good anyway,its like it shows that something is there.

  33. yamicloud05 says:

    Tiles from A5 doesn’t swap, this is one of the script call i used
    tile_swap(“A217”, “A222”, 2, 3)
    other tiles are swapping fine only tiles from A5 doesn’t swap, Help please? Thanks.

  34. Sangmanjin says:

    Here is a video showing it in work 🙂

    • Tsukihime says:

      Looks good. Maybe I can add some functions to make it easier to modify overlay map properties such as changing the opacity or the position.

  35. Sangmanjin says:

    Thank you now because of your tutorial and tile layer teaching i can reach the effect i wanted!If you want to know the main problem was that,i used a different tilesset to make the wall and a different tileset had the transparent tiles,so when it applied the transparent effect it went to a different layer covering nothing.So the wall remained.Anyway….i still have to learn about tiles layers and photoshop,but without your help i may never reached to this,thank you.

  36. Sangmanjin says:

    Sorry i wrote this into the bad category this is the tile swap category…..im just using the overlay map too,and because of this combination its a bit hard to tell what im doing wrong xD

  37. Sangmanjin says:

    Im not sure,because opacity too seems to be out of order.But i think yes because aside form the current map im on with the player,there is only one map with the same size that serves as the wall layer…..or am i misundnerstood the meaning of layer?

    • Tsukihime says:

      There are three tile layers: 0, 1, and 2. Auto-tiles are drawn on layers 0 and 1, while the other tiles are drawn on layer 2. I am unable to automatically determine which layer your tile is on, so you’ll have to explicitly say which tile you are modifying.

      • Sangmanjin says:

        I use now layer 1…but becuase i assume i cant effect tiles that are shown by overlay map i have to use a call event script so i can call an event from other maps that change the overlay map tiles….So i did this but either nothing happens….or im too noob to understand whats going on….i still re-reading your tile swap tutorial every 5min to find out what im doing wrong with tiles and layers….and thanks for the note,yes i understand now that there are 3layer,but i added my transparent tileset first in D-sheet which used layer….2…..now i added the set into A3(BUILDINGS)(that was the only empty space)which should treat it like layer 0?Ok first of all thanks for trying to help me(a noob)…..and answering this fast :'(

        • Tsukihime says:

          I have updated the script so that it supports overlay maps. If you look at the documentation for the functions, you will see that the last argument is “map_id”. By default, this is the current map if you don’t specify one, but you can pass in the ID of the overlay map instead and it will update THAT map instead of the current map. This was always in the script; the only change I made was to update the overlay maps as well.

  38. Sangmanjin says:

    Big thanks for this cool script!

    Can i ask a little help about this script?I switch a region of tiles into transparent tiles,but after the swap,the tiles are still visible.Is that normal?If yes,how can i reach that kind of effect that a wall is there blocking view and when i got there it disappears leaving the floor tiles to be seen.

    Thanks for help!

  39. Tsukihime says:

    Fixed bug where specifying a tile on pages C to E was not handled properly and the script chose a tile from page B.

  1. May 30, 2014

    […] dynamically change a map based on player actions, based on variables, based on anything you want. Tsukihime (Hime) has not only built an incredibly powerful script to handle tile swapping, he’… In this post, will explore some more intricate uses. Download it, and install it, and away we […]

  2. August 10, 2015

    […] Tile Swap par Tsukihime / […]

  3. October 6, 2015

    […] Tile Swap by Tsukihime / […]