SMBX64



SMBX64 (Super Mario Bros. X Standard version 64) is the name of the technical standard used by Super Mario Bros. X version 1.3. This standard contains the file formats, references, item lists, and game-wide default values. The specifics of this standard were researched by Wohlstand in early 2014. This standard is very strictly defined. Each item and behavior algorithm are linked directly to a specific ID value.

The SMBX 1.3 Compatible configuration package for Moondust Project is a full implementation of SMBX64 Itemset: blocks, BGO's, NPC's, Music list map, Sound list map, Tiles, Paths, Level entrances, effects. This configuration package completely provides a compatibility layer with SMBX-made levels, world maps, and episodes.

Name
The Standard name is the name of the game SMBX and the last internal version number which you can read in the first line of any .lvl file with notepad (it is 64).

Standard history
This is a partial history researched from available builds of SMBX. This history doesn't contain any unpublished alpha-builds (numbers of those versions you will find in the SMBX64-LVL file format specification). A more detailed history of every public build of SMBX Engine has own article.

SMBX1 - The first version of the standard came with Super Mario Bros. X 1.0, written by Andrew 'Redigit' Spinks. Blocks can hold 1-99 coins or one of the following NPCs: goomba, flower, leaf, shoe, or mushroom.

SMBX2 - Added support for custom music

SMBX8 - Added support for inter-level warps, added "stars-needed" lock for warps, added "Door" warp type

SMBX10 - Added support for layers and events in levels. Para-Koopas, Para-Goombas, and Cheep-Cheeps were given multiple behavior algorithms. Added NPC Generators. Added talk messages, "friendly" flag, and "not movable" flag for NPCs. Boss NPCs no longer all use the same algorithm, so the flag "Legacy Boss" was added to re-enable those algorithms. Added intro levels of episodes. Added "restart level on death" support. Added "hub-style" system for episodes, togglable in the world map. Added credits field for a world map. Added support for entering to the specified warp ID of a level from the world map.

SMBX17 - Added star count field into level file.

SMBX18 - Blocks can contain any available NPC by its ID. Added play sound event.

SMBX20 - Added "Number of stars" field for world maps.

SMBX28 - Added "Locked", "No Yoshi" and "Allow NPC" flags for warps. Added support for event triggers. Added support for forcing the player's control key events. Added "Always visible" flag for levels on a world map. Added support of background image under the level icon. Added "Game start" flag for level: allows for using any level location as the episode start point. Added support for warping between two locations on the world map.

SMBX32 - Added support for "Water" physical environment zones. Added auto-start ability of events, added layer motion events.

SMBX49 - Added auto-scrolling support.

SMBX55 - Added support to disable specified characters in the episodes.

SMBX62 - Added "level title" field. Added slippery block support.

SMBX63 - Allowed layers to be attached to an NPC, which will move layers with NPC's motion. Added "Quicksand" physical environment zone type.

SMBX64 - The latest and final version of the SMBX standard which was created in 2011 with "Super Mario Bros. X 1.3". After this version, "Super Mario Bros. X" development was permanently ended.

SMBX65 - A possible continuation of a standard in the possible SMBX 1.3.1, found in a published source code. There are was plans to add the support for variables and "saved events", which was never completed due to a sudden SMBX's end of life.

SMBX65-38A - The unofficial continuation of SMBX64 Standard used in Chinese SMBX-38A. The new standard has much more features and introduces new LVL/WLD file formats which going with the incompatible file format syntax

SMBX64-X2 - The another unofficial continuation of SMBX64 Standard used in SMBX2 project. The new standard also has much more features but is different from the SMBX64-38A.

File formats
SMBX64 standard uses a text format with unmarked values.

SMBX1...64 Standard specifications:

.LVL - level file format. Download specification: ODT, PDF

.WLD - world file format. Download specification: ODT, PDF

.SAV - game save file format. Download specification: ODT, PDF

SMBX-38A Standard specifications:

Documentation is available in the Moondust Project repository.

Limits
SMBX64 Standard has some limits about placing elements on the level map and world map:

Levels

 * Player start points: 2
 * Blocks: 16384 (because max index size in VB6 is a half of the max value of two-byte signed integer value)
 * Sizable Blocks (these count as normal blocks too): 1000
 * NPCs: 5000
 * Background Objects: 8000
 * Warps: 200
 * Water/Quicksand areas (doesn't matter how big): 450
 * Events: 100
 * Layers: 100

World maps

 * Tiles: 20000
 * Paths: 2000
 * Music-Boxes: 1000
 * Scenery: 5000
 * Levels: 400

In Game

 * Max episodes in "worlds" folders: 100 (declared internally, but in fact is 126) (exceeding results into a crash or to a list of empty names with a blank world map)
 * Stars: 10000
 * Effects: 1000

Note: information about SMBX's limits here is NOT taken from the Debugger box of SMBX Editor, because it shows incorrect limits for some of the elements, and it doesn't have a debug box for world maps.

Standard item list
Here are lists of the total item settings which are defined by the SMBX64 standard

Level

 * Playable characters
 * Blocks
 * Background Objects
 * Non-playable Characters
 * Backgrounds

World map

 * Terrain tiles
 * Sceneries
 * Paths
 * Level entrance tiles

Common

 * Sound effects
 * Music
 * Hardcoded images (Impossible to customize without LunaLUA ≥ 0.7.3)

Accessible properties
A full list of data properties which can be defined and changed with SMBX64-compatible editors and used in the SMBX based games.

Level Settings

 * Level title string
 * Max total number of sections: 21
 * Per section properties
 * Left-Top-Right-Bottom positions values
 * Background color (accessible from SMBX1 to SMBX2, later unused)
 * Level warp flag (Connect left and right sides)
 * Off-screen exit flag
 * No turn back(right direction walk only) flag
 * Underwater flag
 * Background-ID number
 * Music-ID number (Music-ID=24 is a reserved value which enables custom music playback)
 * Custom music file string

Level items

 * Blocks (Should be sorted by Y and grouped with sorting by X in array)
 * X-Y position
 * W-H Size of sizable block (Multiple 32 only, minimal size is 64x64 px)
 * Slippery flag
 * Invisible flag
 * Contents (Nothing 0, Coins 1...99, NPC-9 100, NPC-1 101, NPC-14 102, NPC-34 103, NPC-35 104, coins 105...999, NPCID+1000, 1001...1392)
 * Layer name string
 * "Destroyed" event slot string
 * "Hit" event slot string
 * "No more objects in the layer" event slot string
 * Background objects (Should be sorted by special sorting priority table)
 * X-Y position
 * Layer name string
 * NPC
 * X-Y position
 * Direction left-random-right
 * Friendly flag
 * No move flag
 * Legacy boss flag (accessible for three NPC's: Boom-boom, Birdo, Bowser III'rd)
 * Message text string
 * Generator flag
 * Generator direction left-up-right-down
 * Generator period delay
 * Generator type number
 * Layer name string
 * Attached layer name string
 * "Activated" event slot string
 * "Died" event slot string
 * "Talk" event slot string
 * "No more objects in layer" event slot string
 * Player's spawn point
 * X-Y Position
 * Warp points
 * X-Y of entrance point position
 * X-Y of exit point position
 * Layer name string
 * Warp type number
 * Entrance direction left-up-right-down
 * Exit direction right-down-left-up
 * No Yoshi (Deny vehicles) flag
 * Allow carried NPC's flag
 * Locked flag
 * Stars needed number
 * Level Entrance flag
 * Level Exit flag
 * Target Level filename string
 * Target warp Array-ID number
 * Target world map X-Y coordinates (-1 and -1 are reserved with "empty fields")
 * Water/Quicksand zone
 * X-Y Position
 * W-H Size (Multiple 32 only)
 * Is Quicksand flag
 * Layers
 * Layer name
 * "layer is hidden" flag
 * Events
 * Event title string
 * Pop-up Message box text string
 * 21 slots for layers of "hide" task (21'st must be empty!)
 * 21 slots for layers of "show" task (21'st must be empty!)
 * 21 slots for layers of "toggle visibility" task (21'st must be empty!)
 * "Disable smoke effect" flag
 * Task to switch background ID's of each 21 section
 * Task to switch music ID's of each 21 section
 * Task to change boundaries of each 21 section
 * Auto-triggerable flag
 * Trigger&hold player control key flags for UP-DOWN-LEFT-RIGHT-JUMP-ALTJUMP-RUN-ALTRUN-DROP-START
 * Set movement for layer name string
 * Set movement for layer X-Y speeds in pixels per frame
 * Set autoscrolling for section number
 * Set autoscrolling of section X-Y speeds in pixels per frame

World map settings

 * Episode title
 * Intro level file name string
 * 5 fields of "Episode credits"
 * "No world map" flag
 * "Restart on fail" flag
 * Total stars number
 * Episode without Mario flag
 * Episode without Luigi flag
 * Episode without Peach flag
 * Episode without Toad flag
 * Episode without Link flag

World map items

 * Terrain tiles
 * X-Y position
 * Scenery
 * X-Y position
 * Paths
 * X-Y position
 * Music Boxes
 * X-Y position
 * Level entrance tiles
 * X-Y position
 * "Background path" flag
 * "Big background path" flag
 * "Always visible" flag
 * "Game start point" flag
 * Target level file name string
 * Target WARP-ID number
 * Open path condition by exit type for left side
 * Open path condition by exit type for top side
 * Open path condition by exit type for right side
 * Open path condition by exit type for bottom side
 * Target teleportation X-Y world map coordinates

Measure units
Internal measure units and constants in the SMBX Engine
 * Size units: 1 block = 32 pixels.
 * Time unit: 1 frame = 1/65 second. (used in the animation frame delay, movement speeds, event timer and generator timer)
 * Speed unit: Pixels per frame.
 * Acceleration units: pixels-seconds per frames (add or subtract speed value per frame)
 * Common grid alignment size: 32 pixels

Graphics
SMBX's Graphics uses GIF format. SMBX Engine imitates transparency by using a bit masks: an image which drawing in the frame buffer with applying to each pixel value AND bitwise operation, and then drawing foreground image with applying OR bitwise operation with each pixel. This algorithm disallows having a semi-transparency images and in result a dirty colors.

Musics and sounds
SMBX uses MP3 file format. Custom music can use other formats, however, such as: WAV, WMA, MID and MP3.

Editor Tech Standard
Declaration of level and world map editors for SMBX64 standard.

Sizes
All item sizes are pre-defined for each item and can't be changed except to sizable blocks, water zones and NPC's with npc.txt files.
 * All blocks and most of background objects has a 32x32 px size or multiple 32 px size.
 * All sizable blocks uses 96x96 sprite which dividing to 9 pieces of sizable block.

Aligning
All items has default grid size in 32 pixels where they are should be aligned. But some exceptions are presented.


 * Blocks
 * Aligning relative to left-top corner with 32 px or 16 px grid size
 * Background objects
 * Aligning relative to left-top corner with 32 px or 16 px grid size
 * NPC's
 * Has a special aligning rule:
 * bottom aligned to 32px or 16px grid size
 * Side aligning by formula: Target position = (Offset from grid cell left side: 32px/2)-((Width of NPC)/2) if NPC aligns to grid cell center or when NPC aligns by center to grid line, horizontal offset formula is '-((Width of NPC)/2)'.
 * Any "Generators" aligning with 16 px grid size.
 * Warps
 * Aligns with 16px grid size
 * Water/Quicksand zone
 * Aligns with 16px grid size
 * Player's spawn points
 * Aligning with 4 px vertical and 2 px horizontal aligning grid sizes.

Collisions
Collisions prevents placement of items over each other by special rules:


 * Blocks
 * Colliding with any other blocks except sizable blocks.
 * Colliding with any NPC's except vines, red herb container, red door.
 * Background objects
 * Colliding with background object of same BGO-ID.
 * NPC's
 * Colliding with any blocks except sizable blocks.
 * Colliding with any NPC's except vides, red herb container, red door.
 * Water/Quicksand zone
 * Doesn't colliding with others.
 * Warps
 * Doesn't colliding with others.
 * Player's spawn point
 * Doesn't colliding with others.
 * Effects
 * Denied to placement in the editor.

Render Z-Order


A full table of SMBX Engine internal rendering order priorities (Z-Layers)

Definition of drawing order of items by types (old internal Moondust draft standard) of Z-Layers: Lowerest: Background images -160: Background-2: BGO's -150: Sizable blocks -100: Background-1: BGO's -50: Warp - Derived BGOs (locks on doors and stuff) -10: Background NPC's -5: Held NPC's 1: Normal blocks 15: Furthest Back Effects (doors, pressed p-switches, some other stuff) 30: Normal NPC's 31: Normal NPC's (Ice block) 32: Player Vehicles / Mounts 35: Playable characters 50: Foreground-1: BGO's 100: Foreground NPC's 150: Foreground blocks 160: Foreground-2: BGO's Highest: Foreground effects

Blocks array order
All blocks in the file are must be sorted by way [X-position] -> [Y-position] -> [ArrayID]. That required by SMBX's collision detection algorithm which uses binary ranges. If blocks are will not be ordered, NPCs are will always miss up collisions with any blocks.

Background objects array order
All BGOs are ordering by special order priority coefficient which groups specific BGO-ID's inside.

How SMBX orders BGOs in a list: There's a mix of using a hardcoded conditions, but also some lookup from a table of Boolean values, where this table of boolean values is only written once and not changed. Used an Insertion sort algorithm. The algorithm is stable itself, but implementation inside SMBX is not stable, therefore every file save of same data, resulted file always has a different order of BGOs.

PGE File Library orders BGOs by this order priorities table and by order of placement which gives the same result on every file save. PGE File Library uses recursion-less Quick sort algorithm.

Sizes
All world map items have 32 px tile size except level points which have different sizes of sprites, but the physical size still is 32 px.

Aligning
All items aligns with 32 px grid size except 'sceneries' which aligns with 16 px grid size.
 * Terrain tiles, Paths, Music Boxes
 * Aligns with 32 px grid size
 * Sceneries
 * Aligns with 16 px grid size
 * Level entrance tiles
 * Has a special aligning rule:
 * bottom aligned to 32px or 16px grid size
 * Side aligning by formula: Target position = (Offset from grid cell left side: 32px/2)-((Width of NPC)/2) if NPC aligns to grid cell center or when NPC aligns by center to grid line, horizontal offset formula is '-((Width of NPC)/2)'.

Collisions
Collisions prevent placement of items over each other by special rules:
 * Terrain tiles
 * Collides with any other tiles
 * Sceneries
 * Doesn't collide. (which a technical mistake of SMBX! To prevent it, they should collide with other sceneries with the same SCENERY-ID in 16x16 px cell of the left-top picture side)
 * Paths
 * Collides with any other paths and with level points
 * Level entrance tiles
 * Collides with any other level points and with paths
 * Music boxes
 * Collides with any other music boxes

Render Z-Order
Definition of drawing order of items by types 0: Terrain tiles 5: Sceneries 10: Paths 15: Level entrance tiles 20: Music boxes

Customization of contents
SMBX64 Standard supports customization.

Blocks
Blocks do support custom graphics. You need to use an image in GIF format with the same size or the same number of animation frames as the original block had.

Background Objects (BGOs)
Background Objects do support custom graphics. You need to use an image in GIF format with the same size or the same number of animation frames as the original BGO had. If the image will be bigger than the original BGO's sizes, it will look cut, but if the image will be smaller than the original BGO, it will work in both SMBX and PGE.

Non-Playable Characters (NPCs)
NPCs are fully customizable, but you need to use a special npc.txt configuration file.

Backgrounds
Backgrounds do support custom graphics and they can have any image sizes. The main condition: images should have the height at least 600 pixels. The "SMB2 Underground" and "SMB3 Pipes" background also must have the width at least 800 pixels. The "SMB3 Blocks", "SMB3 Hills", "SMB3 Snow Hills", "SMB3 Snow Trees", and "SMB3 Waterfall" (Lower part of splitted backgrounds) suggests the same height as original.

Playable Characters
Each playable character uses a sprite sheet with a size 1000x1000 pixels and contains 100 frames in each of them. The SMBX game uses special frame indexes system to split the sheet into two halves: the left half contains frames for the left direction and the right half for the right direction. Every frame has its special index that was made to easily "turn" playable characters between left and right directions by changing the sign.

To compute X pixels coordinate at the sprite from the frame index, this formula can be used:

$$x = \left \lfloor \frac{fi + 49}{10} \right \rfloor \times 100$$

The similar formula for the Y pixels coordinate:

$$y = ({(fi + 49) \bmod 10}) \times 100$$

Where $$fi$$ - The frame index between -49 and +50. Where 0 is the neutral frame, positive are frames of the right direction, and negative are frames of the left direction. To retrieve the cell x and y coordinates, remove the $$\times 100$$ multiplication from the formula.

To get the frame index from $$x \times y$$ cell coordinate (zero-based from 0 to 9 for each dimension), this formula can be used:

$$fi = (y - 10 \times x) - 49$$

Terrain tiles
Terrain tiles do support custom graphics.

Sceneries
Sceneries do support custom graphics, but custom sceneries from 33 to 65 will crash SMBX while trying to save the file or switching to Level Editor. Moondust Editor doesn't have that problem.

Paths
Paths do support custom graphics..

Level entrance tiles
Level entrance tiles do support custom graphics.

Musics and sounds
You can use custom music in Level Mode, but you can't use custom music in World Map mode. You can't use custom sounds in both modes.

Tips for the Vanilla level Contests participation
There are contests where is required to follow the SMBX64 standard and don't use external frameworks or engines which are not the same as legacy SMBX Engine without any customizations, hacks, or extensions. Even Moondust Engine itself is not allowed, you are able to use Moondust Editor to create a compatible level that will don't cause a crash in the legacy editor and engine.

This is a list of tips you must follow to be granted for participation in those contests:


 * you must don't include into blocks or NPC Containers (such as herbs, eggs, Lakitu, and bubbles) impossible objects (elements are locked or not listed as available items for including into blocks or NPC Containers)
 * you must don't customize BGO order priority (keep the value of order priority be -1)
 * you must don't use any scripts or INI-files in the levels. Just have a level file, graphics, and music (or just level only without any custom stuff, dependent on the rules of a specific contest).
 * you must use music formats compatible with a vanilla engine (MP3 or WAV). While you converting music is suggested to always compress with a bitrate equal to 320 to have fewer quality damages.
 * you must use compatible graphics with vanilla engine formats (A pair of the GIF files ready for bitmask algorithm: front image with black background and mask - black shape on white background). You can use PNG to GIFs conversion utility to make compatible graphics of any complexity easier.
 * you must save into SMBX-64 (or older) LVL format, no LVLX or SMBX-38A levels.
 * you should don't use decimal speed values in the npc.txt's because the legacy editor is crashing.
 * you should don't use dummy elements (reserved element slots are not available for regular usage) because picking up them from a map will crash SMBX Editor.
 * you must don't use "system" BGOs (door star and keyhole used for the warps) because picking up of them will crash SMBX Editor.
 * sizable blocks are MUST NOT have a size smaller than 64x64, picking up this block will cause a crash.
 * sizable blocks are MUST HAVE size multiple 32 because the legacy engine will show holes between image segments and it can't smartly fill empty space between them like Moondust Editor and Moondust Engine is doing.
 * firebars are must not be longer than 32 cells.

And any other features which are impossible to make on the legacy editor.

Super Mario Bros. X
It's the original implementation from which the standard was developed. This game is used in its original form as a core for LunaLua-SMBX, and then, for the SMBX2 project.

Moondust
A game engine and toolkit, developed by Russian developer Wohlstand. It doesn't implement the SMBX64 standard directly because of the config packs system that was developed with a purpose to make the game engine being more universal than the original SMBX game was. At the same time, Editor has built-in validators which noticing a possible SMBX64 violation when saving level or world files into SMBX64 format.

Super Mario Bros. X by 38A
An unofficial reconstruction of SMBX game, developed by Chinese developer 5438A38A. It has different physics and some logical behavior than the original game. Also, it automatically converts any opened levels, episodes, and resources into its own SMBX-38A format. Therefore, it's the partial implementation of the SMBX64 standard which does work for data import only. It can't be used to produce SMBX64-compatible levels and episodes.

TheXTech
A cross-platform port of SMBX game, developed by Russian developer Wohlstand. This game is a full and accurate implementation of the SMBX64 standard. At the same time, it has some small piece of additional functionality and limits expansion that wasn't available in the original SMBX game.

Extensions of SMBX64 standard
While time is going, there are new engines has introduced. Here is the table that shows the difference between various engines.


 * * - Cannon pipes at SMBX2 do work via special lua script and won't be configured via level file parameters yet.
 * ** - Z-Layer doesn't work for SMBX2. Z-Offset declares the order of elements of the same Z-priority between each other.
 * *** - The NPC-192 checkpoint at SMBX2 doesn't support multi-points. The multipoint for SMBX2 requires the use of NPC-400 and NPC-430.

Trivia

 * Fun fact: Wohlstand had no idea about the "Sceneries 33-65 will crash SMBX while saving" bug, until h2643 told him that!
 * In the original SMBX World Map editor, there is a bug, which allows you to place sceneries multiple times on the SAME position with no limits. This causes appearing of junk scenery items while you place them with a mouse.