SMBX64

From PGE Wiki
Jump to: navigation, search
Smbx64 standard.png

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 PGE 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 compatibility layer with SMBX-made levels, world maps, and episodes.


Name

Why SMBX version 64?

The Standard name it is a name of game SMBX and last internal version number which you can read in 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 contains any unpublished alpha-builds (numbers of those versions you will find in the SMBX64-LVL file format specification). More detail history of every public build of SMBX Engine has own article.

SMBX1 - The first version of the standard which 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-38A - The unofficial continuation of SMBX64 Standard used in Chinese SMBX. New standard has much more features and introduces new LVL/WLD file formats which going with the incompatible file format syntax

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 PGE 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

World map

Common

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

Content formats

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, MID and MP3.

Editor Tech Standard

Declaration of level and world map editors for SMBX64 standard.

Level Items

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

Level graphical layaring

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

Value Name Description
-100.0 SMBX Level Background The Level Background
-95.0 SMBX BGO SMBX BGOs which are rendered on the furtherst back of the scene.
-90.0 SMBX Sizeable Blocks All SMBX sizeable blocks
-85.0 SMBX BGO SMBX BGOs which are rendered on the back.
-80.0 SMBX Special BGO (i.e. locks) All special BGOs like locks.
-75.0 SMBX Background NPCs SMBX background NPCs like vines, piranah plants, diggable sand, mother brain, things in MB jars.
-70.0 SMBX Held NPCs SMBX NPCs which are held by the player.
-65.0 SMBX Normal Blocks All normal SMBX blocks.
-60.0 SMBX Effects Some effects, which are on the background: doors, pressed p-switches, some other stuff
-55.0 SMBX NPC Some SMBX NPCs like: coins, clown car, chompy, herb, wood rocket, koopaling fire
-50.0 SMBX NPC Some SMBX NPCs like ice blocks.
-45.0 SMBX NPC All common SMBX NPCs.
-40.0 SMBX Chat Icon The SMBX chat icon, which is displayed, when you can talk with an NPC.
-35.0 SMBX Player Mounts The player mounts: Yoshi, Clowncar, Shoe
-30.0 SMBX Player Mounts? Maybe is the same as -35.0
-25.0 SMBX Players All active players on screen.
-20.0 SMBX BGO All foreground BGOs.
-15.0 SMBX NPC All foreground NPCs.
-10.0 SMBX Block All foreground Blocks.
-5.0 SMBX Effect All foreground Effects.
5.0 SMBX HUD All elements of the SMBX HUD.

Definition of drawing order of items by types (old internal PGE 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 a 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.

Background object Order Priority table
Value BGO ID list Comment
10 14, 75, 76, 77, 78 background-2 layer Backgrounds
20 11, 12, 60, 61 SMB3 Goal zone
25 66, 158, 159, 172 background-1 layer Waterfall
26 26, 65, 82, 83, 164, 165, 166, 167, 168, 169 Water
30 52, 79 Blk. dungeon block, Tree Trunk
75 2, 3, 4, 5, 6, 7, 8, 9, 10, 13, 15, 16, 17, 18, 19, 20, 21, 22, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 47, 53, 54, 55, 56, 57, 58, 59, 62, 63, 64, 67, 80, 81, 84, 85, 86, 89, 90, 91, 93, 94, 95, 96, 97, 98, 100, 101, 102, 103, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 132, 133, 134, 135, 136, 142, 144, 146, 147, 148, 149, 150, 151, 152, 153, 160, 161, 162, 163, 170, 171, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 189, 190 Most of BGOs
76 129, 130, 131 Wooden fence
77 1 Small bush
80 48, 139, 140 Ghost house
90 70, 71, 72, 73, 74, 141 Rails, Rail lift buffer, Ghosthouse door
98 87, 88, 92, 104, 105, 107 Doors
99 99 Glass window fragment
125 23, 24, 25, 45, 46, 49, 50, 51, 68, 69, 106, 137, 138, 143, 145, 154, 155, 156, 157, 187, 188 Foreground-1 layer BGOs

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. 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 a same result on every file save. PGE File Library uses recursion-less Quick sort algorithm.

World map items

Sizes

All world map items has 32 px tile size except level points which has different sizes of sprites, but physical size still be 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 prevents 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 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.

Tip: if your block image size is bigger or smaller than the original block is, in PGE Editor, you can place them with no problem, unlike in SMBX Editor. That way you can create custom blocks of any size, which will work in SMBX Engine.

Warning: don't select custom blocks in the SMBX Editor or they will shrink to their original sizes!!

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 special npc.txt configuration file.

Backgrounds

Backgrounds do support custom graphics and they can have any image sizes.

Playable Characters

Each playable character uses a sprite sheet with a size 1000x1000 pixels, and totally contains 100 frames in each of them.

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. PGE fixes 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 same as legacy SMBX Engine without any customizations, hacks or extensions. Even PGE Engine itself is not allowed, you is able to use PGE Editor to create a compatible level which 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 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 from the rules of 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 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 must don't use decimal speed values in the npc.txt's because the legacy editor is crashing.
  • you must don't use dummy elements (reserved element slots are not available for regular usage) because picking up of them from a map will crash SMBX Editor.
  • you must don't use "system" BGOs (door star and key hole used for the warps) because picking up of them will crash SMBX Editor.
  • sizable blocks are MUST NOT have the size smaller than 64x64, picking up of 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 PGE Editor and PGE 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.

Trivia

  • Fun fact: Wohlstand had no idea about "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.