This software is used to streamline the process of importing tilesets to the SMBX2 game engine by automating the most tedious parts of the process. I created it after importing a tileset myself and finding the process very dull and time-consuming.

Using this program instead of importing manually eliminates 80 to 90 percent of the time spent on importing, allowing the user to quickly move forward to the more interesting process of level design and scripting.

The software is available to the public on GitHub, both in the form of source code and as an executable for Windows 7 and above. It is written in Python 3.8. It has been well-received by tileset creators in the SMBX community for the time it saves.

Key Terms

To understand this software and its purpose, there are a few terms that must be defined.

The SMBX2 engine, like many pixel-art-based 2D platformer game engines, utilizes tiles for the terrain that the player will interact with, as well as for decoration. These are typically placed on a grid, and are known as tiles because placing them in the level is similar, in many ways, to tiling a floor.

A block is a tile that the player can interact with. It is mainly used as part of the terrain in a level.

A background object (commonly referred to as a BGO) is a tile that the player cannot directly interact with. These are primarily used for decoration in a level.

A tileset is simply a collection of tiles. Every level created in the engine uses one or more of these.

An episode is a collection of levels that together form a game. These are created and distributed by members of the SMBX community on its official online forum.

The Tileset Importing Process

There are two ways to get a tileset in the SMBX2 engine. The first way is to simply use one or more of the tilesets that come with the engine. This is the easiest way, but offers no customization.

The second way is to import a custom tileset. This custom tileset might be found online, or it may have been handmade by the user. SMBX community members have created many custom tilesets and provided them to be used by others. These are generally ready for engine use and only need to be downloaded and copied to the right location. However, if a user gets a tileset from some other online source or creates a custom one, they must import it themselves. This is where the SMBX2 Tileset Importer comes in.

Most tileset creators will keep all their tiles in one image, as pictured to the left. This is the most convenient way to do it. SMBX2 expects tilesets to be stored as pictured to the right. Note that each tile has its own image and a text file to go along with it. The text files contain configurations for the properties of each tile, such as the "shape" of the tile and its animation settings.

Importing Without the Tileset Importer

Before the Tileset Importer was created, users needed to repeat the following steps (or something similar) for each tile in the tileset:

1. Crop the image to contain a single tile.
2. Select a block ID or a background ID for the tile to occupy in the engine.
3. Save the image containing the single tile as an image named "block-X.png" or "background-X.png", where X is the chosen ID.
4. Create a text file with the same name as the image file (but with ".txt" as its file extension instead of ".png")
5. Set the tile's configurations inside the text file. This requires a knowledge of several configuration options and how they work.

This process is straightforward once a user gets the hang of it, and it doesn't take too long for a single tile. However, that time starts to add up when the process needs to be repeated dozens of times. The tileset shown in the example contains 61 individual tiles, and this is a typical amount. If a user needs to repeat these steps 61 times, it quickly becomes tedious.

Even after all that, the user is still not done importing the tileset, because they need to tell the level editor how the buttons for selecting the tiles should be laid out. This is done with the level editor's built-in Tileset Editor, pictured below.

This is used by selecting a tile from the list on the left, then clicking and dragging it into the grid on the right. There are some filtering options, but they are not very useful. The search box allows users to search tiles by name, but many users do not take the time to give custom names to each tile because it just adds more tedium to an already dull, repetitive process. This means that tiles most often have their default names and cannot be searched for easily.

The "Show custom only" option is more useful than the search box, but in an episode, there are likely hundreds of custom tiles, so the list may still be rather long. When there is a long list and there are many tiles that are similar in appearance, it can be difficult to find all the tiles a user is importing.

Once this is finished, the user can finally save the tileset file and use the tileset in their level.

Importing Using the Tileset Importer

Using the Tileset Importer, the process of importing is done as follows:

1. Open the tileset image.
2. Select the ID ranges to use for each tile type. The Importer will assign IDs from this list automatically. The ID can be set manually for an individual tile if desired.
3. Configure the grid. The grid may be reconfigured later if necessary.
4. Select a tile by clicking and dragging over the part of the image containing it. The boundaries of this selection are snapped to the grid so selections can be made quickly.
5. Set the tile's properties quickly and intuitively using the UI. The value for each option defaults to the most common configuration: a solid, rectangular block.
6. Repeat steps 4 and 5 for each tile after the first.
7. Use the Export function to generate all the files needed by the SMBX2 engine and the level editor. This includes the tileset files used by the level editor.

In addition to automatically generating all the needed files when ready, a user can save their work at any time and return to it later.

These images demonstrate some of the software's functionality. Note that these were captured during various stages of development, so some notable differences with the current version may be present.

Splash Screen

This is what the user will see before opening an image.

Grid

These images demonstrate the grid configuration options and the Pixel Scale option, as well as opening a file. The Pixel Scale and grid settings can be changed between tile placements if necessary. These were captured at different times during development.

Highlight Color and Tile Placement

This image demonstates the highlight color option and tile placement. This was captured before the actual creation of tiles was implemented, so nothing happens after the mouse button is released.

Tile Creation and Editing

This image demonstates the placement and editing of tiles. Tiles change in appearance based on their collision properties. Of course, this does not affect the appearance of the exported images.

Scrollbars

This image demonstates the scrollbars. There are configurable limits to the width and height of the image. If these limits are exceeded, the scrollbars are enabled for moving the image. The default maximum dimensions have since been reduced for compatibility with smaller screens.

Successful Export

This dialog window will appear when the Export function is successful. The amounts of tiles of each type are shown.

Export Failures

These are different error messages that will be displayed to the user when the export fails, depending on the cause of failure.