xmapgui: limited gui editor for xmap

foreword

(also check the forum thread)

xmapgui is an independent piece of software used to automatically generate lua scripts that utilize the xmap library, based on input given through a graphical user interface. it does not act as a stand-in for, nor does it have the capabilities of the actual smbx2 editor. it does not automatically modify any actual files associated with your episode and works only with the files that it itself generates. this page acts as a basic tutorial to outline the features and limitations of the program.

to extract any usefulness from this program, you must download the xmap library (linked above) and place the scripts it contains into your episode folder. also, checking the documentation wouldn't hurt. before the tutorial itself, some questions you may have:

"is this related to the development of smbx2?"
nope. i am not part of the smbx2 dev team nor is this program part of the pge toolchain. xmap is a library i wrote in my own free time.

"is this safe to download?"
creating and distrubuting malware is not only beyond my skill level, but i also stand to gain very little. the source code for the program is publicly available in case you're really paranoid.

"i did look at the source code, why is it so terrible?"
i don't write orderly and scalable code for free.

"can i contribute to the repo?"
if you have an immediate fix to a bug, sure. but at any rate there's much better things to expend your energy on.

"there's a lua error that i'm pretty sure is caused by xmapgui?"
remove the line from your "map.lua" that imports the generated code until you resolve the issue. most of the time this is caused by malformed syntax inside trigger arguments, so that's the first place to look. if you're sure you've done everything correctly, report it as a bug in the forum thread.

"how do i use (feature)? i followed the steps outlined on this page but it's not working."
there may be a caveat that you missed relating to how xmap handles said feature. please read the documentation linked above before asking a question in the forum thread.

fundamentals

this section and the ones after cover the features which are necessary to understand should one hope to use the program.

file menu

open
lets you select a WLD file. opening one is necessary before any other features can be used. xmapgui expects exclusively smbx64 WLD files. WLD files generated by any other version and WLDX files cannot be read.
save
generates two files inside your episode directory. "xgui.bin" is a file used by xmapgui to keep track of custom elements and is not used by smbx (deleting it makes you unable to make further changes within xmapgui). "xgui.lua" is a library file that contains the generated lua code. to make it actually work inside your episode, require it inside your "map.lua" file.
reload current world
equivalent to clicking "open" and selecting the world file you already have open. useful for when you change item configurations or add new animations (just remember to save first!). note: editing your world map in parallel to using xmapgui is typically fine, but please refrain from removing path and level objects as much as possible because doing this may cause serious issues with the event ordering.

edit menu

set grid alignment
same functionality as in pge. allows you to place and move items with a finer constraining grid.

mode menu

vanilla item selection mode
when checked, allows you to select path and level objects.
xmap item selection mode
when checked, allows you to select custom elements like coin signs and animations.

once the world has been loaded, use the arrow keys to move your viewport.

vanilla items

by left clicking on a level or path, you can edit the configuration for all instances of the same id or set an event to trigger when that object is revealed during gameplay. you will also see some information about the selected item on the right panel.

xmap items


to add a new item, click on it within the left panel and then left click again on the world map to place it. right clicking on the world map will cancel this operation. while xmap selection mode is active, you can: move these items around by left clicking and dragging, delete them by right clicking, or select them by just left clicking, which lets you view information about them and edit any related configuration.

configuration


type-wide

available for levels, paths and animations. applies to every object of the same type with the same id. the fields should be self-explanatory (just note that width and height refer to displayed size, not physical size). "frames (pressed)" refers to the amount of frames that a switch palace has after being pressed.

save to file
generates a txt file containing the given configurations inside the episode folder. changes will not be visible inside xmapgui until the world is reloaded.

per-instance

available for xmap items. fields will become active/inactive depending on the type of item you select. unlike the previous configurations, these apply only to the currently selected item and no others.

events

events contain sets of specific actions and can be triggered when a path or level is revealed. the top view contains events, while the bottom one contains the actions for the currently selected event.

add event
creates a new, empty event.
remove event
removes the selected event. events created after it will have their id number decreased by one. (e.g. removing event#1 will make event#2 become #1, #3 become #2, etc.)
remove action
removes the selected event action.

event actions

the building blocks of events. provide access to most of the features present within xmap. they can be added to the selected event by pressing the "+" button at the top of each frame containing the parameters. (an action might not be added if the formatting of the parameters is incorrect)

tile actions

translate/set id/swap
determines the type of operation over a given group of tiles.
(parameters)
for the significance and order of parameters, please check the xmap documentation.
save
if checked, the action will be written into the save file when it is performed.

path actions

x/y
the top-left corner of a 32x32 square within which all path(s) will unlock. connected paths are then unlocked recursively.

music actions

id
starts playing the song with the given id. 0 means silence.

player actions

set player visibility
makes the player visible (checked) or invisible (unchecked).

camera actions

x/y/width/height
adds a new camera boundary determined by the given rectangle.

animation actions

(parameters)
creates a new animation with the given parameters. setting the lifetime to 0 will mean the animation will by itself stay visible until the player exits the overworld.

triggers

triggers allow you to set specific conditions which will be checked when any path or level is opened, and will execute a specific event if they are met. you are also able to specify custom expressions to be put in the place of different parameters that get passed to specific event actions only if said event is called through the given trigger. the top view lists the triggers (their conditions and bound event) while the bottom one lists custom arguments.

add trigger
creates a new trigger without any conditions. an event must be selected in the menu above.
remove trigger
removes the selected trigger.

trigger conditions

x/y
whether to compare the x or y position of the revealed level/path.
(operators)
which logical comparison to make (left-right, top-bottom: equal, not equal, greater than, lesser than).
to:
which numeric value to compare it to.
add condition (conjunctive)
adds the condition to the selected trigger (conjunctive: to evaluate to true, it and the previous conditions must all evaluate to true).
add condition (disjunctive)
adds the condition to the selected trigger (disjunctive: to evaluate to true, either it or the previous conditions together must evaluate to true).
clear conditions
removes all conditions from the selected trigger.

custom arguments

custom arguments are expressions which are used to substitute arguments of function calls made by events. each set of custom arguments corresponds to an action performed by the event tied to the trigger which it belongs to. you can use special wildcard values to indicate the x and y position of the revealed path/level: _x and _y respectively. (custom arguments do not apply to actions which modify player visibility)
example:

event
queuePathAction(100, 100)
addCameraBoundary(100, 100, 1000, 1000)
custom arguments
_x+100,,,,,,,,
,_y+100,326,,,,,,
resulting call
queuePathAction(_x+100, 100)
addCameraBoundary(100, _y+100, 326, 1000)

add
adds a set of custom arguments to the selected trigger. (based on values from text boxes, ordered top to bottom)
remove
removes a selected set of custom arguments.