Plugins

Level-Headed works off of a plugin system. There are 3 types of plugins: Generators, Interpreters, and Writers. Generators create the levels as human readable text files. Interpreters "translate" these text files into something that the Writer plugin can understand. The Writer plugin then writes the actual game/ROM/etc.

Generator Plugins

Generator plugins are where the random level generation happens. Ideally, they should create human readable text files. This makes it easy to edit the generated scripts by hand. However, there is nothing in place to enforce this, meaning that future level generator plugins won't be required to generate levels in plain text.

Interpreter Plugins

Interpreter plugins bridge the gap between Generators and Writers. The main function of an interpreter plugin is to "translate" the text files that a Generator plugin generates into something that the writer plugin can understand. Interpreters also handle the plugin settings, as they are always specific to that Generator/Writer combination. It should be noted that a separate Interpreter plugin is necessary for every supported Generator/Writer combination. However, Interpreters are the easiest plugins to write.

Writer Plugins

Writer plugins handle writing the actual game. In the case of SMB1, the "SMB1_Writer" plugin is what handles hacking the ROM itself. Writer plugins expect data to be sent to them from an Interpreter in order to function.

The SMB1_Compliance Format

The "SMB1_Compliance" format is a human readable text format that is theoretically compatible with nearly any Mario game or platformer due to its simplicity. Levels are broken up into three major sections: a Header section, an Objects section, and an Enemies section. All x coordinates are relative while y coordinates are absolute. In theory, literally any side-scrolling platformer could work within these simple limitations.

Patterns

Patterns are small pieces of a level with certain rules that control how they get constructed. This is a little different than what many people call "chunks", as one single pattern can sometimes create a wide variety of different designs. As of v0.3.0, patterns are all programmatic. There are currently only about 5-10 patterns per level type. All patterns are created by hand, though many are inspired by Mario games.

Passes

Many level generators create levels in multiple passes. The SMB1_Compliance Generator is no different in this regard, although it is limited by its relative nature. As of v0.3.0, only two passes are made over the level. This will likely change in the future. The first pass handles objects (via patterns). The second pass then crawls over the objects and places enemies on them where possible. Enemies can't be too close to each other, as the original Super Mario Bros. couldn't handle displaying too many enemies at once. Enemies also can't be too far apart, as Super Mario Bros. relies on a relative coordinate system that can possibly break if enemies are more than 16 blocks apart. This tends to result in some empty sections towards the end of longer levels.