Metroid Construction

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Introduction ======

SMART is a program that can export and import rooms and all data associated with the rooms from a Super Metroid ROM. This gives the ability for better version control of a SM project and allows multiple designers to work on the same project at the same time more easily.

The other purpose of SMART is to automatically repoint all the room data as the size of the data changes. Adding data such as PLMs, Enemies, States, FX1, LevelData, ScrollData, and Doors are very simple and require no hex knowledge or advance understanding of the SM ROM.

Finally, SMART has many specialized editors for visualizing and modifying SM data. All these structures are automatically repointed and arranged as they are added, removed, or resized.

===== Disclaimer =====

This software is AS IS. That means that it's possible that all of your work might be completely annihilated because something wasn't properly handled or understood. Please back up all of your work before using this software. Some form of version control is highly recommended.

===== Installation =====

Create a new folder and place SMART.exe and the Data folder in it.

The Data folder contains images used for entities that can be shown in the Level Editor. If you create custom enemies, you can add additional images to these folders to match the ID of the appropriate entity.

When started for the first time, SMART will create a config.xml file in the same directory. This file contains a global configuration, such as the location of optional external tools and the default project.

==== Upgrading ====

If you are upgrading an existing installation you will want to overwrite SMART.exe and merge in any new files in the Data folder.

Most of the time, this is all that's needed to complete the upgrade. Occasionally, new features are added to SMART to enable repointing new data. When this happens, the exported data will be incomplete in the new version. However, the ROM should still have a copy of the data, so you will want to be sure to save to ROM before upgrading and load from ROM after the upgrade.

Additionally, as SMART starts reading loading more parts of the ROM, you might find that some previous ROM corruption interferes with loading the ROM. Many other tools will cause unexpected changes to the ROM as well as just accidently typing something in a hex editor. You should save to a clean ROM and then use that to load the after the upgrade. For this reason, it's highly recommended that you maintain all your patches and ASMs so that they can be reapplied.

===== Starting a New Project =====

When SMART is started it will load the main window, but no data will be loaded. Before anything can be loaded, SMART needs a project configuration to know what files to load. Use the Config menu to open the config window.

First use the Load Project button to select a directory that will contain your project. This will create project configuration files in that directory. You do not have to place your ROM in this directory, but it will help organize things.

Set the ROM file path to your ROM file that you want SMART to work with.

Optional: Set the SMILE.exe path to a copy of SMILE RF. SMART will update the MDB file to match the new locations or rooms when the data is saved to ROM.

Optional: Set the Assembler path to a copy of xkas. SMART can use this to automatically remove areas used by customized code from the default free space.

Once this is done, click OK to save the updated configs. Now the load menu on the main window can be used to load data from the ROM for the first time.

===== About Loading and Saving Data =====

Exporting the rooms will search the ROM file for all rooms and save their data structure into XML files. These files can be edited to add, remove, or modify an element of the room.

Note: SMART will search for rooms be moving starting with all the save rooms and moving through every accessible room via doors. Ceres and the Debug room have a save station data, so they are found in the search. However, if there is a room or group of rooms that do not connect to the rest of the room graph, they will not be found by SMART. Make sure that there are doors setup when adding new rooms before using SMART.

Importing the rooms will load all the XML files and save their data into the ROM. It will automatically repoint all the data so that there will always be space. When importing, if the SMILE MDB.txt file is provided, then SMART will update the MDB.txt file for all the new addresses. The import will still happen even if the MDB.txt is not given, but SMILE will not be able to open the ROM unless the MDB.txt file is updated. The level_entries.txt file in the same location as the MDB.txt file will also be updated. This file is only used for SMILE to calculate the amount of available space in the room's level data.

The value called “Level Buffer” is the number of bytes (in decimal) that are padded as free space for each room's level data. Setting to 0 will mean that all the rooms are compacted with no free space available. It should also be noted that when a room level data is modified in SMILE, and then exported and re-imported with SMART, then the data will be expanded so that there is the same amount of available free space in the level data. This should make level editing much easier since SMART automatically repoints the data to ensure more free space.

The config file is automatically updated by SMART, except the locations of 'free space'. The free space includes all the original space used for each bank that is being overwritten. The defaults work fine for the original ROM, but if patches are being used that change what space is available then the ranges should be updated.

===== The Main Window =====

Menus:

  *     Load Room: load all data (not just rooms) from the configured ROM file or from previously exported XML.
  *     Save Room: save all data (not just rooms) to the configured ROM file or generate an XML export.
  *     Config: open the config window
  *     Tools: open special editors or apply various utility operations
  *     About: Show the About box

Upper Left: Console log. Displays information and error messages.

Upper Right: Shows ROM usage as allocated by SMART

  *     Blue: No data is placed here. Either because the area is too small or because no more space is needed
  *     Red: Data that must be located in the particular bank
  *     Yellow: Data that can be moved into another bank to make space for more Red data
  *     Gray: Space that is not part of the free space in the project configuration
  *     Magenta: Space that is removed from any free space configuration before use.

Lower Right: Simple preview of the current selected room.

Lover Left: Room list and operations

Each area is shown in order by area number. Each room in the area is listed in order by its room id (index). This is also the order that rooms are placed in the ROM.

Room data toolbar:

  *     Edit: Open the room editor for the selected room. This can also be opened by double clicking on a room in the list.
  *     Add: Create a new room in the current area. The room gets assigned the first free id in the area, a default name, level data for a single blank screen, and a two-way door connecting to the current selected room.
  *     Delete: Removes the selected room and any associated data such as save locations, doors, and level data.
  *     Copy: Copies the room to the internal clipboard.
  *     Paste: Creates a new room with an independent copy of all the data in the copied room.

===== Room Names =====

SMART can save the room name into ROM if the an ASM patch is used that will display the names in game. When importing, the room name is the same as the filename of the XML. When exporting, SMART will try to load the name from ROM, and if it does not exist then it will try to load the room name from the matching XML file. If the name does not exist in either of these places, then it will default to the name to be the room's address.

===== Command Line Interface =====

SMART can be ran from command line. Use the parameters 'import' or 'export' import or export data respectively without running the GUI. SMART outputs the same logging over the Console Out as appears in the GUI, but it seems to be suppressed. To show the output, pipe the command into 'findstr “^”':

SMART.exe export | findstr "^"
SMART.exe import | findstr "^"

When SMART is ran without the GUI, it will not save a default config file if it does not exist, since the file locations need to be specified. Please make sure the config file exists before attempting to run SMART without the GUI.

===== Project Folder Structure =====

Export: Folder containing exported ROM data. This can be loaded into SMART or replaced by saving from SMART.

config.xml: Contains the project configuration such as free space.

quickmet.xml: Contains quickmet settings such as custom controls and Samus' loadout.

The export folder contains folders for each kind of data, the file formats and arrangement of the data depends on the data itself.

===== Room Editor =====

==== Room States ====

State list. Select a state to open it in the level data editor. This will also check the state. The selected state is what's visible, while all the checked states are modified by any edits made in the level editor. This allows for easily keeping different states in sync while editing.

When a state is selected the Room Data tab is populated with data about the state where it can be edited. When selecting the Room instead of a state, the Room Data tab is populated by general room data instead.

Use the toolbar to, add new states, remove states, copy and paste states, and reorder states.

Layers: A list of all the layers shown in the level editor are shown here. Selecting a layer enables tools and operations that modify the data shown on that layer.

Unchecking a layer hides it in the level editor.

Collision: Quick selector for setting collision data. Use the copy button, ctrl-c, or auto copy on select to copy to the clipboard. Use the Raw View to show all possible values in a grid for a tile type instead of known useful values.

==== Room Data ====

Room Data Upper: Shows a list of different editable things for the room or for a particular state depending on what is selected in the Room States section. Selecting items here will display properties of that item below.

Right clicking something showing another room shows a menu where the editor for that room can be loaded.

Right clicking a save gives the option to start quickmet using properties from the save.

Room Data Lower: Properties of the currently selected item - the Room, the States, or something contained in one of these. Descriptions of the properties are shown at the bottom. The values can be modified as well.

==== Level Editor Toolbar ====

From left to right:

Zoom: Change the zoom of the level editor.

Brush: When a tile layer is selected, the brush tool pastes the clipboard at the point clicked.

Brush options:

  *     When the brush is applied, use the Layer 1 data from the clipboard and paste it on the currently selected layer (Layer 1 or Layer 2).
  *     When the brush is applied, use the Layer 2 data from the clipboard and paste it on the currently selected layer (Layer 1 or Layer 2).
  *     When the brush is applied, use the Layer 1 data from the clipboard and paste it onto Layer 1 and use the Layer 2 data from the clipboard and paste it onto Layer 2.
  *     When the brush is applied, use the Collision Layer data from the clipboard and paste in onto the Collision Layer.
  *     Only paste tiles over tiles inside the current selected area on the level editor.

Fill: Paste the clipboard into the current selected area so that it is repeated as needed to fill the area.

Selection Mode - New: Clear the current selection and select a new rectangular area.

Selection Mode - Union (AKA binary OR): Select a rectangular area and add it to the current selection.

Selection Mode - Intersect (AKA binary AND): Select a rectangular area and keep only areas in the selection that are also contained in both parts.

Selection Mode - Relative Compliment (AKA subtract): Select a rectangular area and remove it from the current selected area.

Selection Mode - Symmetric difference (AKA binary XOR; invert): Select and area and invert the selection state of areas inside. Select the entire room in with this to perform a standard invert.

Copy: Copy the current selected area to the clipboard. Copies Layer 1, Layer 2, and the Collision Layer if available. This can also be done using ctrl-c in the level editor.

Auto Copy: Automatically copy to the clipboard when the selection is updated.

Paste: Paste the clipboard into floating layers. The floating layer will appear where it was copied from if possible. This can also be done with ctrl-v in the level editor.

Anchor to Layer 1: Merge the data from the currently selected layer onto Layer 1.

Anchor to Layer 2: Merge the data from the currently selected layer onto Layer 2.

Anchor to the Collision Layer: Merge the data from the currently selected layer onto the Collision Layer (only applies to floating Collision Layers).

Remove Floating Layer: Remove the currently selected floating layer.

Horizontal Flip Floating Layer: Flip the currently selected layer horizontally. Some collision structures are modified so that they still make sense when flipped.

Vertical Flip Floating Layer: Flip the currently selected layer vertically. Some collision structures are modified so that they still make sense when flipped.

Undo: Revert the last edit to the level data. Some changes are not reversable and some changes destroy the previous history (such as resizing the room).

Redo: Reapply a previously undone edit to the level data.

==== Level Editor ====

Displays the currently selected state. What the mouse does depends on what layer is selected (or tool in the toolbar if applicable).

Left Click:

  *     Error Layer - nothing
  *     Floating Layer - Click and drag to reposition
  *     Screen Scroll Bounds - Click to change a screen's camera scroll types
  *     Sprite Layer - Click to select enemies or click and drag to move enemies
  *     Actor Layer - Click to select PLMs to click and drag to move PLMs
  *     Save/Load Locations - Click to select saves or click and drag to move saves
  *     Collision Layer/Layer 1/Layer 2 - Action depends on the tool selected in the toolbar.
  *     BG Pointer - nothing

Right Click: Open a context menu. The context menu allows for actions, such as starting quickmet from the selected location and opening rooms for door tiles. It also shows a list of all the tiles and entities in that location. clicking on a tile will select it in the Tilemap Selector Window.

Middle Click: Click and drag to scroll the level editor.

==== Tilemap Selector ====

This window is opened with the level editor and is reopened if it was closed when a new level editor is opened. This window is good for selecting tiles from the tileset and copying them to the clipboard. The selection controls are the same as in the level editor. Use the copy button, ctrl-c, or auto copy to copy the selection to the clipboard.

===== Additional Tools =====

==== Load ASM files ====

Populate the list of areas that should be removed from the free space before allocating. This is done by applying the assembler configured in the config on each file in the ASM folder under in the project folder. The differences are noted, and any changed areas are marked as used.

==== Reassign item PLM IDs ====

Looks at the first few instructions of every PLM type used rooms for the standard item bit checking instruction. Using this list of PLM types, each room is scanned for these item PLMs. When an item appears in multiple states of the same room in the same position, it is considered to be the same item and is grouped together. Each item group is then sequentially assigned item ids.

==== Reassign door PLM IDs ====

Looks at the first few instructions of every PLM type used rooms for the standard door bit checking instruction. Using this list of PLM types, each room is scanned for these door PLMs. When a door appears in multiple states of the same room in the same position, it is considered to be the same door and is grouped together. Each door group is then sequentially assigned door bit ids.

==== Title Demo Editor ====

Left: Demo Collection List

Demo collections are a set of demos that are played together before going back the title screen animation. The first few sets are always available, while others can be locked behind completing the game. The number of locked collections can be changed at the bottom. New collections can be added, collections can be moved, and collections can be removed using the toolbar.

Middle: Demo List

This is the list of individual demos played together. Demos can be moved, copied and pasted, and removed using the toolbar. New demos can be created by importing Snes9x movie files using the import button on the toolbar.

When recording a movie for importing as a demo, the movie needs to be started from after the room is loaded so that the movie file contains a save state that describes the room and other needed information.

Right: Demo properties

View various statistics about the demo as well as modify some values such as Samus' loadout. These are best set by importing the correct values from a movie file, but small tweaks are useful here.

==== Tileset Editor ====

Top Left: List of CREs. MultiCRE is required to add additional CREs. CREs can be added, removed, and reordered using the toolbar. The solid (left) move operations modify rooms so that the reordering the CREs does not change the appearance of rooms. The hollow (right) move operations reorder CREs without updating rooms to match.

Bottom Left: List of SCEs. SCEs can be added, removed, and reordered using the toolbar. The solid (left) move operations modify rooms so that the reordering the SCEs does not change the appearance of rooms. The hollow (right) move operations reorder SCEs without updating rooms to match.

Right: A list of rooms that are affected by the currently selected combination of CRE and SCE.

Select, copy, and paste colors using the Palette selector. Selecting a color also makes that palette active for drawing graphics tiles. The current color is used for drawing on graphics tiles as well.

Once a color is selected the color can be modified using the color sliders. The replace colors button opens a tool for reordering the colors on the currently selected palette.

Transparency Preview changes the color currently used as the transparent color in the Tilemap and Graphics.

Top: Change the zoom of the Graphics in the Graphics viewer.

Bottom Left: Change the size of the SCE. Normal CREs are all 0x240 tiles; however, they can be 0x280 tiles before interfering with the CRE. The maximum size it 0x400, which is used for special tilesets like Kraid's that overwrite the CRE when they load.

Middle: The currently selected graphics tile number and the graphics for the tile. Clicking here will color pixels with the currently selected color. The buttons to the right will rotate or flip the tile's graphics.

Right: A display showing which colors are actually being used by this tile. Replacing colors will swap colors used for the selected tile.

Copy: Copy the selected tile (also ctrl-c)

Paste: Paste the tile onto the selected tile (also ctrl-v)

Select: Select the clicked graphics tile.

Clone Selection Here: Paste a copy of the selected graphics onto the clicked tile.

Swap With Selection: Paste a copy of the selected graphics onto the clicked tile and also paste a copy of the existing graphics of the clicked tile onto the selected tile.

Transpose With Selection: Same as swap but it updates the tilemap so that the tiles are not graphically affected by the change.

Ignore: nothing

Arrow keys: Select the next tile in the appropriate direction.

Left: Change the zoom of the tiles in the Tilemap.

Right: Tilemap Tile Editor

Select graphics tiles and paste them into each of the four parts of a tile using right click here. Set the palette, priority, horizontal flip and vertical flip of each part.

Copy: Copy the selected tile (also ctrl-c)

Paste: Paste the tile onto the selected tile (also ctrl-v)

Select: Select the clicked tilemap tile.

Clone Selection Here: Paste a copy of the selected graphics onto the clicked tile.

Swap With Selection: Paste a copy of the selected tilemap tile onto the clicked tile and also paste a copy of the existing tilemap tile of the clicked tile onto the selected tile.

Transpose With Selection: Same as swap but it updates all rooms using the tiles, so they are not graphically affected.

Ignore: nothing

Arrow keys: Select the next tile in the appropriate direction.