Overlay Maps – layered maps in Ace


This script allows you to create “overlay maps” on top of each other. In other words, map layers.

Overlay maps allow you to create much more visually attractive maps since
you now have control over different “layers”, though you are unable to walk from one layer to another. For now anyways.


Script: download here
Addon: Overlay Map Zoom
Demo: very quick demo

Note that in the demo, the castle maps are set up properly, but the sky island map is not. I have left this as an exercise for you to figure out how to use the script by fixing the specific map to get it to work. Hint: it’s related to note-tags.


  • Patch for Khas Awesome Light Effects


In the script editor, place this script below Materials and above Main.


An overlay map is just another map, except it is drawn over your current
map. The overlay map comes with the following properties

  • It does not need to use the same tileset as your current map. This means you can merge multiple tilesets together in a single map
  • Events on the overlay map are processed in the current map, although you are still not able to reference events from different maps.
  • The player is unable to directly interact with the overlay map, or anything on the overlay map.
  • The player, however, can indirectly interact with events on the overlay map by setting switches or variables that will trigger the events.
  • To transfer between layers, you must use player transfer events
  • Map layers can re-use each other, so if one map uses another map as the top layer, then that map can use the previous map as the bottom layer
  • You can have an unlimited number of overlay maps.
  • Overlay maps that are smaller than the current map will loop. This may be useful for creating patterns
  • Each layer has its own screen effects


A single map can contain multiple overlay maps, so you can mix and match layers to create all sorts of maps.


Create your maps as usual, taking into consideration how you want to layer them.
You might separate your maps into “floor” and “ceiling” or “floor, walls, ceiling”, depending on how you like to organize things.

Note that because maps and overlay maps cannot interact with each other, all events on each overlay map are effectively bound to their own overlay map.

There are two types of note-tags: compact, and extended.
The compact note-tag is short and easy to type, but the extended note-tag
is probably better for organization. Note that the compact note-tag is deprecated and will no longer be supported, meaning new options will only be available in the extended note-tag.

To assign overlay maps to a map, tag the map with either


<overlay map: map order ox oy scroll_rate sync zoom>


<overlay map>
map: x
order: x
offset: ox oy
scrollrate: x
sync: 0/1
zoom: x
opacity: x
</overlay map>

You can have multiple overlay maps by simply adding more tags. See the reference section for details about the values of each option.



The map  is the ID of the map that will be drawn as an overlay.

  • The order determines whether it will be drawn above or below the current map.
  • If it is negative, then it will be drawn under.
  • If it is positive, then it will be drawn over.
  • If it is not specified, then it assumes to be over, in the order that the
    tags are specified.


ox and oy determine the offset of the origin. By default, the map’s origin
is drawn at (ox = 0, oy = 0), but you can change this if necessary.
The x-value specifies the horizontal offset. Positive values shift it to the
right, while negative values shift it to the left.

The y-value specifies the vertical offset. Positive values shift it down,
while negative values shift it up.

Scroll Rate

The scroll rate specifies how fast the overlay map scrolls per step taken.
The default scroll rate is 32, which means it will scroll
32 pixels per move, or basically one tile. Higher scroll rates mean the
overlay map will scroll faster for each step you take, while slower scroll
rates results in less scrolling for each step you take.

Sync Effects

Sync specifies whether the overlay map is synchronized with the current
map. This means that any screen effects such as shaking or weather will affect
the overlay map as well.
0 = not synchronized
1 = synchronized

Map Opacity

The opacity value specifies the opacity of the overlay map.


Zooming Level

The zoom value is a special option if you have installed the Overlay Map Zoom script. Refer to that script for more details.




You may also like...

101 Responses

  1. Alex G says:

    Hello and thank you for your work. I was wondering if you know of Galv’s Region Effects 1.9 script and its compatibility issue with this script. Is there a simple fix to this problem? I really want to use both scripts for my project.

  2. Guido says:

    Hello!!! your work is absolutely awesome, i was wandering if there may be compatibility issues with the LUNA ENGINE and the Yanfly core engine

  3. Mireneye says:

    I can’t for my life figure out how I’m supposed to set up the scrollrates. It seems whatever I set (I only have negative value maps) They seem kind of fixed. It might be that I’m setting up the multiple maps wrongly. This is what I’m doing, on the first maps notebox:

    map: 78
    scrollrate: 128
    </overlay map>

    map: 79
    order: -2
    scrollrate: 256
    </overlay map>

    Maybe I’m misunderstanding something?

    • Hime says:

      Try it on a new project.

      When you’re standing on the map with those two overlays underneath, you should see map 78 moving pretty fast for every step you take, and map 79 moving even faster.

  4. MadMaus says:

    Hey Hime!

    This script is awesome, though I’m having a little problem with it:

    I’ve made a test map with two cliffs connected by a bridge. The player can access the upper layer via transfer event, but when the player go back to the bottom layer, the character sprite is duplicated and then disapear after some seconds.

  5. sapiboong says:

    I experience an error when I make a map entirely using tile B to E. The RGSS3 player keeps stopping (it works fine for ordinary map). I tried making the map entirely from tileset B to E because the parallax mapping script that I use won’t work (yami overlay mapping).

    • Hime says:

      Are you using the “zoom” add-on that requires a custom DLL?

      • sapiboong says:

        Yes, I use the zoom add-on, too, and have added the .DLL.

        • Hime says:

          See if things work without the zoom add-on. Take out the DLL as well. Not sure if it conflicts with the mapping.

          • sapiboong says:

            Ah, yeah, I took out the .DLL and now it works all right 🙂

            Do you have any suggestion on using overlay mapping with parallax script? Since it can show up alright but the parallax map won’t scroll at all :/

          • sapiboong says:

            Ah, yeah, I took out the .DLL and now it works all right 🙂

            Do you have any suggestion on using overlay mapping with parallax script? Since it can show up alright but the parallax map won’t scroll at all :/

          • Hime says:

            Sounds like it would require a patch to properly update the parallax map. Not sure.

  6. cris says:

    Thank you soo much for the script but I cannot seem to get it to work. I have my overlay map set to be above my main map but ive tried so many times but just cannot seem to get the overlay map to show. here is what I have in the main map note section.
    Main is map 002 and the over lay is 003

    map002 =

    much appreciated for the help!

    • Hime says:

      The comment system may have eaten your note-tag. Can you re-post it, or maybe post it on pastebin and then send me the link? You should be able to copy the example note-tag in the script description and modify it to suit your needs.

  7. Paramecium13 says:

    I’m using Khas Awesome Light Effects and whenever I open the menu or enter a battle on a map with an overlay, it gives the error

    Script ‘Khas Awesome Light Effects’ line 940: NoMethodError occurred

    undefined method ‘bitmap’ for nil:NilClass

    It works fine on other maps. I am also using the Luna Engine and many other scripts.

  8. Hypnotic Paradox says:

    This is a great script, but I am using it with the XAS Hero Edition ACE scripts (and in Mode 7 , but the problem still exists when the Mode 7 script is removed.) When I attempt to transfer to another map I get a "disposed bitmap" error. Is there a way this could be fixed?

  9. ricardodeleo says:

    For some reason, when I transfer to a map and have the screen tint (like when transfer to a cave and make it dark), the overlay map doesn’t change, it stays at regular color. Don’t know if it’s a bug or I’m doing something wrong.

    map: 013
    order: 0
    offset: 0 0
    scrollrate: 32
    sync: 1
    opacity: 255

    Besides that, this script is awesomesauce!

  10. I really like this script, but the events on the overlay map don’t work. I’ve set them to parallel process, but nothing happens. They are two npcs that are supposed to move via move route event.

    • Hime says:

      The reason why that happens is because I made it so that events from overlay maps can affect events on the current map.
      So when you move events on an overlay map, they’re actually telling the events with the same ID’s on the current map to move.

      A better solution will probably be required.

      • Hm, okay, I tried to transfer the player from the current map (lower tunnel) to the overlay (higher plattform) so that the events would function properly, but when I reuse the tunnel map as overlay for the higher plattform map it gives me an error starting the game, saying the stack level is too deep.
        These are the notetags for the lower tunnel (003):

        map: 004
        order: 1
        scrollrate: 32
        sync: 1

        and these for the higher plattform (004):

        map: 003
        order: -1
        scrollrate: 32
        sync: 1

        What did I do wrong?

  11. ObsidiansRealm says:

    Didn’t see if it was addressed, Opacity needs to be set to 255 for it to be completely opaque.

  12. I’ve ran into a problem lol. I’m also using Khas Awesome Light Effects like Chameleon1333 was. My issue is that when you activate the tint command from Khas’s script, the overlay map is tinted as well even when properly set up. I tried this in the demo as well with Khas’s script and got the same result. Is there any way to stop this?

  13. Chameleon1333 says:

    i’ve come across another issue here. When i have an airship on a map that is using an overlay, the airship is doubled on the overlay map and it also reacts to with the same movements when i enter and fly the one on my may. After flying around for a few seconds usually the game will crash. Sometimes depending on the overlay placement i can trigger the the landing action with the airship im actually in to land on the overlay, but this causes an instant crash just before it touches the ground.

    • Hime says:

      I am unable to reproduce the issue. I just get the airship appearing under the overlays, which is also a problem, but I’m not getting the duplicate airships.

      • Chameleon1333 says:

        in your demo, on sky city, i placed an airship on the lower layer and when i went to fly it i could see another airship on the sky island. (airship was placed at 22,23). I see what you’re saying about going under a layer, the airship disappears but the shadow shows through. I noticed when doing this on your demo that the game wasn’t crashing when the bug occurred. I couldn’t get the landing bug to happen, but that was a hard one to get to happen.

        • Hime says:

          I’ve updated the script so that the vehicles are drawn correctly. I’ve also made it so that the shadow disappears when you’re under an upper-layer.

          • Chameleon1333 says:

            Thank you. That fixed that issue, but now in this new version of the script the extended note-tags do not work for layers beneath the current one (they end up showing above the current layer). Changing over to the the compact version fixed this, but i see in the description of the script that this entry type will not be supported anymore and it’s missing the ability the set opacity. Extended note-tag seems to now have an issue with setting the xy offsets. Seems to be always setting it at 0,0. works fine using the compact method On a side note there doesn’t seem to be anyway to get parallax mapping to work on an overlay (trying to get lighting effects on the overlay.

          • Hime says:

            I just realized the copy I updated was an older version. See if it works now. The layering was never a problem for me though, so I’m not sure what happened there.

          • Chameleon1333 says:

            well i’ve tried a few different way of trying to get parallax overlays to work (GDS’s Ultimate Parallax Control, Yami’s Overlay Mapping, Woratana: Multiple Fogs, using a fixed “show picture” event, a blank map using the built in parallax function in the map properties. What i’ve seen is that and parallax image set on an overlay map will not show up (using the built in parallax function, it will show but cannot be locked in place). If i set any parallax on the current map, they will show behind any overy maps above the current map, making lighting a building that is suppose to look like it is a part of the base map (like the castle in your demo) wont work. If i use a show picture event it will show above everything, but this isn’t good if the map includes overlay map the have a scroll other than 32.

          • Hime says:

            Yes, those scripts operate on the current map’s parallax, not the overlay maps, so they won’t work the way you expect it to work as if it is the current map. The show picture commands use the current screen, but I should probably separate those out into each layer as well.

  14. Kerykeion says:

    Is there any way to layer multiple overlays in a single map?

    I’m trying to create a map at the peak of a mountain and attempting to create an illusion of depth by overlaying another map beneath it, zoomed out to make it look smaller. I want to add another layer beneath that one, zoomed out even further. I want to potentially do this multiple times to really get an illusion of depth.

    Am I shit out of luck, other than resorting to making the final layer a parallax background made in Photoshop?

  15. Master Daisy says:

    i have question about overlay maps,

    i did the overlay maps to add more building into the map… basically, it works but the player can go through the buildings, i already edit the tilesets in the settings…

    here img as example for the result

    the character standing in front of the building
    1- http://i1292.photobucket.com/albums/b576/MrDaisy/1_zpsd080b789.jpg

    the character pass through it
    2- http://i1292.photobucket.com/albums/b576/MrDaisy/2_zpse826d909.jpg

  16. Seiken says:

    In a new project with only this script, tints and flashes don’t seem to sync properly. Fadeouts work when transferring the player, but not at all through event commands. Shaking works perfectly, though.

  17. Chameleon1333 says:

    I ‘ve caught a bug here. Don’t know if this relates to my previous post. If an event on the current my has the same id number (not name) as one on another layer, it will cause issues with them interfering with each other. such as the effects of one event occurring on the other instead.

    • Tsukihime says:

      Yes, that is a bug. However, it is not clear how it should be resolved because some people might want events from one layer to control events on another layer. A way to resolve this would be to create a bunch of dummy events (eg: empty events) so that you can manually offset the ID’s yourself.

  18. Chameleon1333 says:

    Is there anyway to have an event trigger on a over map. i know you can’t get up to one to interact with an event, but can u set an “autorun” or “parallel process” event to run?

  19. Seiken says:

    I wanted to the player event to be semi-transparent when hidden by the overlay. Because I’m enjoying having an upper layer so much, it’s been really easy to lose the player behind tall structures. ^^;

    Thanks for the script, btw.

  20. Seiken says:

    Is there a way to check when the player is obscured by an overlaying map?

  21. Flip says:

    When I use this script and set a certain map as the layer map I get this error

    Script ‘Game_Interpreter’ line 450: NoMethodError occurred.

    undefined method `x’ for nil:NilClass

    Works for every other map as a layer to that map though.

  22. Chameleon1333 says:

    “Script ‘Khas Awesome Light Effect’ line 931: NoMethodError occurred. undefined method ‘bitmap’ for nil:NilClass.”

    Line 931 of the script is : $game_map.light_surface.bitmap.dispose

    • Tsukihime says:

      It was a bug. I have fixed the issue. MGC has also updated his tilemap. I have updated my resource pack with the new library so just re-download it and put it in your project’s System folder.

      • Chameleon1333 says:

        Thank you. Works great now. Do u know of any lighting scripts out there that are compatible with the overlays. I’ve been messing around with a few and they all seem to have issues. same issues seem to happen with MGC zoom script (lights show up in wrong place/layer or don’t scroll with the layer they are on). I’ve tried Khas, FyxLFX, and Edison. all with basically the same issues. Any help would be greatly appreciated

  23. Chameleon1333 says:

    I seem to be having an issue with this. When using this with any 8-directional movement script (tried a few), when you moving diagonally when an overlay comes into view random sections of the overlay map will be missing. any help on this?

    • Tsukihime says:

      This is actually caused by the “overlay map zoom” script, not the overlay maps. The bug occurs from the library that I use provided by MGC. I’ve submitted a bug report.

      • Chameleon1333 says:

        Thanks for the quick response. Disabling the Zoom script fixed that. hope that get’s fixed, because i really like the visual effect that creates. Really great stuff. Another question. I’m working with “Khas Awesome Light Effects” and there’s an issue where when you’re on a map that has an overlay enabled and go into a battle the game crashes with an error from the lighting script. Maybe i should be asking them, but it only happens with using the overlay. Is there maybe a more compatible lighting script out there. I was looking for one that was free for commercial use just in case i decided to go that way at some point

  24. Michael Ponder Jr says:

    I am not sure what the problem is, but for some reason, the events on maps either lower than me or higher than me are always offset a bit.

    • Michael Ponder Jr says:

      I figured out the problem i think.
      It’s the size of my event’s graphics.
      Anything that’s only 32 pixels wide will sit just right it seems…
      I think that’s it.. but i am not sure.

      • Michael Ponder Jr says:

        Yup, it is the event sizes… if the graphics are more than 32 x 32, they end up offset.
        For instance, i’m using a chest that is 64 x 64, so it shifts down and to the right when it’s on a different “layer”.
        Sorry for all the replies, but i did not see an edit comment button.

        • Tsukihime says:

          Thanks for letting me know. If you look at the event closely, you’ll notice that it is positioned with the event’s origin at the upper-left corner. I will have to figure out how to adjust the event accordingly to take into consideration larger (or smaller) sprites.

  25. IceSage says:


    I found a strange bug where if you’re teleporting to a new map and the map uses the same Parallax background as the old map you teleported from, the background won’t appear.

    For example,

    1st map uses Starlit Background.
    Teleport to a Map that has
    -1st Map (No Parallax)
    -2nd Layered Bottom Map (Starlit Parallax)

    When I get there, no Parallax will be displayed. (Black)

    I can circumvent this back changing the Parallax Background just before the teleport to a different one, freeing up the one in use. (Thus, it’s displayed on the map I’m teleporting to.)

    This is a bit.. tedious. Any way to fix this?

  26. encapturer says:

    Huh… wrong links, sorry

    50 opacity : http://i44.tinypic.com/158xh2.jpg

    0 opacity: http://i41.tinypic.com/16gd2x5.jpg

  27. encapturer says:


    Shadows don’t seem to be affected by the opacity setting at all

  28. encapturer says:

    This is great, but while testing it out, I ran into an bug.

    If you add an overlay map to a base map with the overlay having the following settings:
    – Above base map (positive value)
    – Transparency < 100%, even at 0%

    Any shadows on the base map will not have any transparency at all.

  29. Sangmanjin says:

    Wow thanks to this update and your tile tutorial,i can now reach the effect i wanted! If i touch the wall it instantly disappear showing whats behind!Thank you very much!

  30. Sangmanjin says:

    map: 002
    order: -1
    offset: ox oy
    scrollrate: x
    sync: 1
    zoom: x
    opacity: 50

    • Sangmanjin says:

      Also opacity seems to not work.So the wall let it be over or underdrawn wont change in transparency…or opacity .
      (is opacity same kind of thing like transparency?sorry for asking this but opacity in my language is really close to transparency….)

    • Tsukihime says:

      Check whether it is a compatibility issue. Also, you should not include any options with invalid values. Yes, opacity refers to the transparency.

      • Sangmanjin says:

        Okay thanks for advice,can i ask your opinion about whether its possible or not to make a map,where a wall is seen(by overlay map)and if i go there the wall is gone showing the floor tiles,and re-appears while im gone,and not there?I was trying to do this effect by combining your tiel swap,overlay map and a call event script(from yanfly) that calls an event fro ma different map(where the wall is).

  31. Sangmanjin says:

    This is great i love it,and thats what i was searching for!Great!Now i just hope there wont be any errors 🙂

    • Sangmanjin says:

      For some reason,i cant make it to be drawn under me..i add only one layer to be drawn under my map,but it still shows itself as an overdrawn layer covering some view…i checked everything to be right(negative number)…..is it might be related to some kind of tile issue?

  32. IzanaginoOokami says:

    that reminds me of the village of summoned monsters/eidolons from final fantasy 4

  33. Reaver says:

    That really is amazing, great work!!

  34. Wow that is absolutely awesome ^_^ I love your work man, Wonder’s what other new awesome stuff you will be releasing next ^_^ (Hope’s it is some character based tech tree or skill tree systems *hint hint* lol)

Leave a Reply

Your email address will not be published. Required fields are marked *