xmap: smbx world map utilities

chocomap.lua

redraw basegame overworld with lua, simple camera locking. library settings are at the top of the file.

item settings

this library allows for use of text files for overworld elements placed in your episode folder. attributes are listed below and have the same names in the text files as well as within the lua code itself.

width
width of the sprite used for the given element.
height
height of the sprite used for the given element.
frames
number of animation frames.
framespeed
amount of ticks between individual animation frames.
priority
rendering priority for the given element. must be 0 or above for the element to display.
pframes
used for level id 33-36. amount of animation frames if the corresponding switch palace has been pressed.

fields

tiles
table indexed by id containing relevant information for tiles.
[id]
texture
sprite used for the given element.
config
a table that contains settings (see above) for the given tile.
maxID
(const.) 400
filePrefix
(const.) "tile-"
defaultConfig
(const.) "tiles"
frameTable
table indexed by id that stores the current animation frame for individual tiles.
scenery
table indexed by id containing relevant information for sceneries.
[id]
texture
sprite used for the given element.
config
a table that contains settings (see above) for the given scenery.
maxID
(const.) 100
filePrefix
(const.) "scene-"
defaultConfig
(const.) "scenery"
frameTable
table indexed by id that stores the current animation frame for individual sceneries.
paths
table indexed by id containing relevant information for paths.
[id]
texture
sprite used for the given element.
config
a table that contains settings (see above) for the given path.
maxID
(const.) 100
filePrefix
(const.) "path-"
defaultConfig
(const.) "paths"
frameTable
table indexed by id that stores the current animation frame for individual paths.
levels
table indexed by id containing relevant information for levels.
[id]
texture
sprite used for the given element.
config
a table that contains settings (see above) for the given level.
LEVEL0
table which stores the settings for level id 0.
texture
sprite used for level id 0.
config
a table that contains settings for level id 0.
maxID
(const.) 100
filePrefix
(const.) "level-"
defaultConfig
(const.) "levels"
frameTable
table indexed by id that stores the current animation frame for individual levels.
LEVEL0
the current animation frame for level id 0.
cameraBoundaries
numerically indexed table with each element signifying a region which the camera is bound by whenever the player is inside it. regions equal to 1 are ignored.
[index]
x
left x coordinate of the given region.
y
top y coordinate of the given region.
width
width of the given region. ensured to be 800 or greater.
height
height of the given region. ensured to be 600 or greater.
*_PRIORITY
default rendering priorities for various overworld elements. PLAYER_PRIORITY and HUD_PRIORITY can be changed during play.
defaultConfigs
table indexed by the defaultConfig strings of the tables above. each of those sub-tables are then indexed by id and contain the default settings for each overworld element. by default, those are:
some elements deviate from this configuration, listed below:
tile-8
tile-9
tile-12
tile-13
tile-14
tile-27
tile-241
tile-325
scene-1
scene-4
scene-5
scene-6
scene-9
scene-10
scene-12
scene-15
scene-16
scene-17
scene-18
scene-20
scene-21
scene-24
scene-27
scene-28
scene-29
scene-30
scene-33
scene-34
scene-35
scene-36
scene-37
scene-38
scene-39
scene-44
scene-50
scene-51
scene-52
scene-53
scene-54
scene-55
scene-57
scene-58
scene-59
scene-60
scene-61
scene-62
scene-63
level-2
level-8
level-9
level-12
level-13
level-14
level-15
level-21
level-22
level-23
level-24
level-25
level-26
level-28
level-29
level-31
level-32
level-37
level-38
level-39
level-40
playerVisible
if set to false, the player's sprite will not be drawn.

methods

setSwitchPalaceAnim()
called when the world map loads. sets the correct animation frame for instances with level id 33 through 36.
calibrateElementDisplaySize()
called when the library is loaded. finds the maximum possible size of an element which is to be used for the optimized drawing method. IMPORTANT: you should call this method whenever changing width or height configurations on the fly, otherwise things might not display correctly.
updateFrameData()
called by doDraw(). advanced every overworld element to it's next animation frame.
renderPauseMenu()
called by doDraw(). if the game is paused, draws the vanilla pause menu.
enforceCameraBoundaries()
called by doDraw(). makes sure that the camera stays within defined boundaries if applicable.
doDraw()
called at the start of the draw cycle. draws a black rectangle over the normal viewport and then redraws every overworld element, the player and the HUD.
addCameraBoundary(xPos, yPos, w, h)
adds a new camera boundary region and returns it's index inside cameraBoundaries.
xPos
left x coordinate of the given region.
yPos
top y coordinate of the given region.
w
width of the given region. set to 800 if lesser than 800.
h
height of the given region. set to 600 if lesser than 600.
removeCameraBoundary(idx)
sets a camera boundary region to the number value -1.
idx
index of the given region inside cameraBoundaries.

coinsign.lua

star coin signs from nsmb (except they don't actually deduct any star coins). to use, create a path leading out from a level's "none" type exit and add a sign over it in your onStart() event (to work properly, must be placed directly next to the level in question).

data

SaveData.coinSign
numerically indexed table containing boolean values with the indexes matching individual signs. a value of true means it's been cleared and is no longer an obstacle.

fields

signs
numerically indexed table containing information pertaining to individual star coin signs. indexes correspond with SaveData.coinSign.
[i]
x
x coordinate of the given sign.
y
y coordinate of the given sign.
coins
amount of star coins required to clear the given sign.
saveOnClear
if set to true, the game will automatically save after a star coin sign is cleared.
requireClear
if set to true, star coin signs cannot be cleared until their adjacent level has been cleared (checked via xpath.levelCleared()).

methods

addSign(x, y, reqCoins)
adds a new star coin sign and returns it's index inside signs.
x
x coordinate of the given sign.
y
y coordinate of the given sign.
reqCoins
amount of star coins required to clear the given sign.
removeSign(index)
clears a given star coin sign and opens the path that it covers.
index
index of the given region inside signs.
doDraw()
called at the start of the draw cycle. draws each star coin sign (the rendering priority by default is the greater between chocoMap.LEVEL_PRIORITY and chocoMap.PATH_PRIORITY, plus 0.1).
onTick()
checks if the player is attempting to walk in the direction of a given sign. if they are and the required conditions are met, that sign is removed.

wanime.lua

allows for creation of custom animations on the overworld.

item settings

custom animations should have images in the normal smbx format and text files inside your episode directory with the names in the format of "wanime-id.(png/txt)" (e.g. "wanime-1.png", "wanime-1.txt", ...).

width
width of the sprite used for the given animation.
height
height of the sprite used for the given animation.
frames
number of frames of the given animation.
framespeed
amount of ticks between individual frames of the given animation.
priority
rendering priority for the given animation. must be 0 or above for the element to display.

fields

DEFAULT_PRIORITY
the default priority of animations. changing this during play has no effect.
maxID
(const.) 100
filePrefix
(const.) "wanime-"
activeAnimations
numerically indexed table that holds information regarding the currently active animations. values inside are equal to -1 for destroyed animations.
[i]
id
id of the given animation.
x
x coordinate of the given animation.
y
y coordinate of the given animation.
speedX
horizontal speed of the given animation.
speedY
vertical speed of the given animation.
accelX
horizontal acceleration of the given animation.
accelY
vertical acceleration of the given animation.
lifetime
remaining number of ticks before the animation is destroyed. if nil, the animation won't be automatically destroyed.
currentFrame
the current frame of the given animation, starting from 0.
currentFrameTimer
counts up and when it reaches a certain number (depending on framespeed), resets to 0 and the animation's frame increases.
idx
auxiliary field that holds the index of the given animation within activeAnimations.
textures
table indexed by id that stores the image for each type of animation.
config
table indexed by id that stores the settings for each type of animation. sub-tables have the same fields as the item settings listed above.
defaultConfig
the default configuration for animations. these values are used for settings that aren't explicitly listed within the text files.

methods

addAnimation(id, x, y, speedX, speedY, accelX, accelY, lifetime, startFrame)
spawns a new animation and returns it's index within wanime.activeAnimations.
id
id of the given animation.
x
x coordinate of the given animation.
y
y coordinate of the given animation.
speedX
horizontal speed of the given animation.
speedY
vertical speed of the given animation.
accelX
horizontal acceleration of the given animation.
accelY
vertical acceleration of the given animation.
lifetime
remaining number of ticks before the animation is destroyed. if nil, the animation won't be automatically destroyed.
startFrame
the starting frame of the animation. if nil, the starting frame will be 0.
destroyAnimation(ind)
destroys a given animation.
ind
index of the animation to destroy within wanime.activeAnimations.
updateActiveAnimations()
updates the position and remaining lifetime of every active animation.
updateFrameData()
updates the current frame of every active animation.
doDraw()
called at the start of the draw cycle. calls updateActiveAnimations() and updateFrameData(), then draws each animation.

xmusic.lua

overrides the overworld's music playing logic. not enabled by default, not recommended to enable if you have any other music libaries loaded. compatible with music.ini.

events

onMusicChange(prev, next)
called immediately before the overworld music changes.
prev
the id of the previous overworld music.
next
the id of the overworld music that's about to start playing.

methods

isSeized()
returns true if xmusic is currently in control of the music stream.
currentMusic()
returns the id of the currently playing overworld music, 0 if silence.
seize()
seizes the music stream and plays the current music id signified by currentMusic(). must be called for xmusic to function.
play(id)
plays a given overworld song.
id
id of the song to play, from 1 to 16. to stop music, pass 0 to this method.
release()
relinquishes control of the music stream back to smbx. called automatically when the player exits the overworld.
onInputUpdate()
checks if the player is colliding with any music boxes and changes the current music accordingly.

xpath.lua

overrides smbx's default path unlocking and overworld warping routine, and allows for manual unlocking of paths. respects the default rules of path unlocking, prioritized directions are counter-clockwise starting from upwards, to match with the level exit ordering in the official documentation. to use, it's necessary to require it inside your global "luna.lua" file.

special features

you can place "special paths" on the map. if their position matches that of a given normal path's, xpath will behave in a different way than usual, but they can't be used in conjunction with paths leading out from the game's start point.

blockade
no further paths leading out from the given path will be unlocked.
skip
the given path will not be unlocked (though it will still be passed to onPathOpened()), but paths leading out from it will be unlocked like normal.
wait
after the given path is unlocked, the game will "unlock" a given number of non-existent paths (i.e. wait a given number of cycles) before continuing, passing nil to onPathOpened() each time.

data

GameData.xpath
table of persistent values used to carry data between levels and the overworld.
realWinState
the win state of the last level that's been exited. IMPORTANT: while using xpath, onExitLevel() will always have LEVEL_WIN_TYPE_NONE passed to it. to check the actual win state, please use this value instead of levelWinType.

fields

SP_BLOCKADE
(const.) 0 - signifies a special path of type "blockade".
SP_SKIP
(const.) 1 - signifies a special path of type "skip".
SP_WAIT
(const.) 2 - signifies a special path of type "wait".
pathDelay
while paths are being revealed, this value signifies the amount of ticks that the game waits before revealing the next path segment/level. setting it very low might make part of the path reveal before the game even starts to render everything properly.
lastWarp
table that holds the coordinates of the location that the player has just been warped to. all values inside equal -1 after all the paths leading out of a warp location have been revealed. IMPORTANT: while said values aren't equal to -1, the actual warp location of the level that the player used to warp is set to (-1, -1).
X
x coordinate of the current warp.
Y
y coordinate of the current warp.
specialPaths
numerically indexed table that holds information regarding special paths.
[i]
x
x coordinate of the given special path.
y
y coordinate of the given special path.
ptype
type of the special path (see above).
wait
amount of cycles to wait after the corresponding normal path is unlocked. nil for special paths not of type "wait".

events

onPathOpened(path)
called immediately after a singular path is revealed via openPath().
path
the path object that was opened. nil if the event was called as a result of a "wait" type special path.
onLevelOpened(idx)
called immediately after a singular level is revealed via openPath().
idx
the index of the level that was opened.
onWarp(x, y)
called immediately after the player warps.
x
x coordinate that the player warped to.
y
y coordinate that the player warped to.

methods

doPause()
pauses the game, used to prevent the player from moving or switching characters while paths are being revealed.
doUnpause()
unpauses the game, called automatically when the script has no more paths to reveal.
paused()
returns true if the game has been paused by doPause().
addSpecialPath(ptype, x, y, wait)
registers a new special path. returns it's index within xpath.specialPaths.
ptype
type of the special path (see above).
y
x coordinate of the given special path.
y
y coordinate of the given special path.
wait
amount of cycles to wait after the corresponding normal path is unlocked. only to be passed if the special path is of type "wait".
unlockNode(nodes, index)
in charge of focusing the camera onto and revealing individual path segments or levels. not meant to be called outside of xpath itself, only mess with it if you know what you're doing.
nodes
expected to be a numerically-indexed table of tables. each sub-table represents a specific overworld element is a pair containing it's index within smbx's internal array of elements, and it's type (path/level).
index
index of the element within nodes that is to be revealed.
openPath(pathX, pathY)
reveals all of the paths (and all adjacent paths, recursively) inside a 32x32 square with the top-left point given.
pathX
left x coordinate of the aforementioned square.
pathY
top y coordinate of the aforementioned square.
checkPaths()
called when the overworld loads. checks if the player has beaten the level they just exited and if so, unlocks any paths which qualify.
catchWinState(levelWinType)
called when a level is completed. sets GameData.xpath.realWinState and then forces the level to exit with LEVEL_WIN_TYPE_NONE, to prevent the base game path unlock routine from being called.
levelWinType
the win type passed to the event.
onInputUpdate()
locks the player's inputs if the game has been paused by xpath, also checks if the player has entered a level that warps to a different location on the world map and overrides that accordingly. IMPORTANT: xpath prevents use of the jump button entirely while the player is moving. please handle this accordingly.
pauseStateUpdate()
called at the start of the draw cycle. advances the unlocking of paths while the game has been paused by doPause(). also calls chocoMap.enforceCameraBoundaries().
levelGetIntersecting(x1, y1, x2, y2)
utility function that returns a table of level objects that intersect with a given rectangle.
x1
left x coordinate of the rectangle to check against.
y1
top y coordinate of the rectangle to check against.
x2
right x coordinate of the rectangle to check against.
y2
bottom y coordinate of the rectangle to check against.
levelCleared(level)
returns true if a level object meets any of the following conditions:
level
the level object to check.

xtile.lua

easily manipulate chunks of tiles. also allows permanent changes to tiles within a save file.

data

SaveData.xtile
table of permanent changes made to tiles. individual elements correspond to method calls, and this table isn't meant to be used outside of xtile itself.
GameData.xtile
table of miscellaneous persistent data.
actionsLoaded
boolean value that equals true if loadActions() has been called before.

methods

translateGroup(x, y, w, h, th, tv, noLog)
moves all tiles within a specified rectangle.
x
left x coordinate of the rectangle to find tiles in.
y
top y coordinate of the rectangle to find tiles in.
w
width of the rectangle to find tiles in.
h
height of the rectangle to find tiles in.
th
horizontal distance to move each tile by.
tv
vertical distance to move each tile by.
noLog
if set to true, the change isn't permanent. doesn't have to be explicitly passed otherwise.
setIDGroup(x, y, w, h, id, noLog)
transforms all tiles within a specified rectangle.
x
left x coordinate of the rectangle to find tiles in.
y
top y coordinate of the rectangle to find tiles in.
w
width of the rectangle to find tiles in.
h
height of the rectangle to find tiles in.
id
the id of the tile to transform the given tiles into.
noLog
if set to true, the change isn't permanent. doesn't have to be explicitly passed otherwise.
swapGroup(x1, y1, x2, y2, w, h, noLog)
exchanges the places of all tiles within two specified rectangles of the same size.
x1
left x coordinate of the first rectangle to find tiles in.
y1
top y coordinate of the first rectangle to find tiles in.
x2
left x coordinate of the second rectangle to find tiles in.
y2
top y coordinate of the second rectangle to find tiles in.
w
width of both rectangles.
h
height of both rectangles.
noLog
if set to true, the change isn't permanent. doesn't have to be explicitly passed otherwise.
loadActions()
called when the world map loads. performs all of the previously done permanent actions if it hasn't been called before.