gbs-MetatilePlugin

Metatile plugin for gbstudio (version 16px and 8px)

Contains 3 version of the plugin that allows metatiles in gbstudio

• First version "Metatile16" uses 16px metatiles and is more general purpose, the example project showcases a large map that will allow tile editing and persistance, dimensions can be edited in the metatile.h file.

• Second version "Metatile16_ScreenScroll" uses 16px metatiles and is a single screen scene that can scroll into another scene a la Link's awakening (basicaly a merge of Metatile16 and this plugin: https://github.com/Mico27/GBS-scrollScenePlugin) (Requires latest dev version of gbstudio)

• Third version "Metatile8" uses 8px metatiles and is more general purpose, the example project showcases a large map that will allow tile editing and persistance, dimensions can be edited in the metatile.h file.

How to use:

• Create a tileset that will contains all the unique tiles needed, those will be assigned to the common tileset of both the metatile scene and the main scene.

• Create a metatile scene that will contain all the metatiles (max 256) the metatile scene must be 256 pixel wide (for the 16px version) or 128 pixel wide (for the 8px version)

• In the scene that will use the metatiles, put the "Load meta tiles" event and assign it the metatile scene. When compiling, the tilemap will be reconstructed by selecting matching metatile from its scene and the metatile scene. additional options can be checked:

  • "Must match metatile color attributes" will try to match the color attributes (Useful if you have metatiles that uses the same tile but with a different color)
  • "Must match metatile collision" will try to match collision attributes (Useful if you have metatiles that uses the same tile but with different collision)

• the "Get meta tile at position" event allows you to get which metatile ID is at a given position in the current scene

• the "Replace meta tile" event allows you to replace at metatile at a given position with the option to commit the render or not (have this unchecked if you replace a metatile that is offscreen)

• the "Submap metatiles" event allows you to copy a section of metatiles from another scene and paste it at a given position in the current scene with the option to commit the render or not (have this unchecked if offscreen)

Since the tilemap is loaded in memory, any metatile replacement are kept in memory and wont reset even if offscreen. This also allows you to replace metatiles in the scene's init script before it is rendered. You could even dynamicaly generate the scene this way.

• The main scenes must respect the dimensions described as such: (the width in tiles rounded to the upper power of two) x (the height in tile) must not exceed the maximum map size configured in the settings (width x height) cannot exceed (8px version) 7936 bytes/tiles (256 bytes are used for dynamic collision data, ex: 255 x 31 in 8px tiles) / (16px version) 7168 bytes/tiles (1024 bytes are used for dynamic collision data, ex: 127 x 56 in 16px tiles).

• Save data is now stored from SRAM bank 2 and 3, while the metatiles uses SRAM bank 0 and the extended scene stack feature uses SRAM bank 1

Events:

• Load meta tiles. The main event that allows to mark a scene as having metatiles and specifie the scene that contains the set of metatiles. Each tiles in the scene must match the tiles in the metatile scene. If using color only, check the "must match metatile color attributes" and color the scene accordingly. Check "Must match metatile collision" if you have metatiles that have the same tile/color data but have different collision data.

• Get meta tile at position. Store the Id of the metatile specified its position in the scene into a variable.

• Get meta tile collision at position. Store the collision data of the metatile specified its position in the scene into a variable.

• Assign meta tiles. Assign a metatile at a position by specifying its ID. Check commit render to update the change on screen, keep unchecked if offscreen.

• Assign meta collision. Change the collision data of a metatile specified by its ID.

• Reset meta tiles. Reset the any changed metatile at the specified position. Check commit render to update the change on screen, keep unchecked if offscreen.

• Copy scene submap to background. Submap a section of metatiles from a separate scene into the active scene.

• Attach a script to a metatile event. run a script on one of the following events:
• Metatile Enter. Will run the script whenever the player's collision box enters a new tile. the position and ID of the entered tile is stored in the engine fields: Entered Metatile Id, Entered Metatile X position, Entered Metatile Y position.

You can optimize the event by specifying the Minimum metatile index to start checking for the entered metatile event in the settings.

• Metatile Collision

MetaTile16_ScreenScroll.2025-02-13.02-22-36.mp4

MetaTile16.2025-02-13.02-24-06.mp4

MetaTile8.2025-02-22.02-54-13.mp4