# MegaZeux 2.93b (20240910) - Help File

- Contents
- Editor Keys
- Robotic Manual
- Commands
- Counters
- Changelog

M E G A Z E U X

Table of Contents

1) Basics and Gameplay

FREQUENTLY ASKED QUESTIONS. Overview of MegaZeux - First Time Users Read This! Help on Help (Press F1 Within Help to Read This) The Config File Mouse Support in MegaZeux Dialog Boxes Controls Nondescript Play Tips The Mirth of Built-ins

2) The Editor

The World Editor General Editing Tips Editing Keys and Options Reference The Character Editor The Palette Editor Super MegaZeux Modes Global Info Options Board Info Options MegaZeux's Sound System Editing and Using the Overlay Signs and Scrolls in the Editor

3) Coding With Robotic

Robots - What They Are and How to Use Them Robotic Tutorial Robotic Reference Manual Debug Modes Sensors - What They Are and How to Use Them A ZZTer's Guide to MegaZeux

4) Miscellaneous

The MegaZeux Updater Error Messages MegaZeux Limitations If You Find a Bug... NEW in MegaZeux!

** Credits and Acknowledgments **

Programming and Overall Design by Gilead Kutnick (Exophase),

Alistair Strachan (ajs), Alice Rowan (Lachesis) and Lancer-X

Based off of original program and source code by Alexis Janson

Help file by Terryn

Default SMZX palette by Joel Lamontagne (LogiCow)

ccv utility by Lancer-X

png2smzx utility by Alan Williams (Mr_Alert)

checkres utility by Josh Matthews (Revvy), ajs and Lachesis

Port contributors: Adrian Siekierka (asiekierka) [3DS],

Mr_Alert [Wii], Kevin Vance [NDS], Simon Parzer [GP2X]

Renderer code contributors: LogiCow, Mr_Alert

Shader code contributors: David Cravens (astral), GreaseMonkey

Icon by Quantum P.; Extra icons by LogiCow

GDM conversion by ajs and MadBrain

Other past contributors: Spider124, Koji, JZig, Akwende,

MenTaLguY.

** Special Thanks **

Dizzy (.deb Builds)

mzxgiant (MSVC Testing, Bug Fixes)

mzxrules (Testing)

Quantum P. (OS X Testing / Builds)

Spectere (OS X Builds)

Terryn (Testing)

Wervyn (Testing)

MegaZeux 2.80 Thanks & Beta Testers:

Exophase

ZoMbIeGuY

Wervyn

Quasar84

Lancer-X

KenOhki2112

Terryn

Inuchance (Macintosh testing)

Everyone who submitted a bug report

Table of Contents

Help on Help

Using MegaZeux's help system is very simple. Press F1 at almost any time to bring up context-relevant help. Within help, use the arrow keys to scroll the current section. Press PageUp and PageDown to scroll faster. Many sections of help contain selections, like this: Selection Scroll the section until the pointer is aligned with the arrows on the edges of the help box, and press Enter. You will jump to a help section indicated by the selection. Example: If a selection says "Controls", scroll until the word is aligned with the arrows on the left and right, and press Enter. You should now be reading help on Controls. Press F1 within help to jump to this section. Press Alt+F1 within help to jump to the Table of Contents (Table of Major Help Topics). Press ESC to exit the help system. Table of Contents

Overview of MegaZeux

Welcome to MegaZeux! Use the arrow keys to scroll

this text, and ESC when you are done reading.

Press END to learn about the NEW FEATURES in

MegaZeux!

As you may already know, MegaZeux is a game system which allows you to play almost limitless worlds with dated-yet-charming graphics and with excellent digitized music and sound. Not only are there several MZX worlds out there already, but new worlds are being uploaded to large websites like DigitalMZX. However, the best feature of MegaZeux is the World Editor. Using the World Editor, ANYONE can create the world of their dreams. Make it as simple or complex (well, almost), as easy or difficult, as long or short as you please. We aren't just talking about worlds made up of petty, pre-programmed enemies and objects; MegaZeux has its own, easy-to-use PROGRAMMING LANGUAGE called Robotic that allows you to create objects, engines and worlds that do almost anything you desire. Not only can you make your own game with the editor, but every world MegaZeux can play can be opened in the editor. Take a look at how other games tick! For the newest user, it's recommended that you play Caverns, the first ever MegaZeux game, to get the feel of simple yet well-designed games in MegaZeux. You may wish to read the help section entitled "Controls" to learn how to play MegaZeux. If you're more adventurous, start with a more complex game like Demon Earth or Bernard the Bard, or a prettier game like & or Fritz Blitz to see what kind of graphics functions, bells and whistles MZX can offer. Once you have the feel for the game, feel free to dive into the World Editor and get messy! You should probably read the help section entitled "The World Editor" first. To go to one of these sections now, hit Enter after aligning the arrows with one of these choices. Press ESC now to exit to the game. Table of Contents Controls The World Editor NEW in MegaZeux!

A ZZTer's Guide to MegaZeux

ZZT and MegaZeux are worlds apart, although one can convert from making ZZT games to making basic MegaZeux games with (mostly) minimal effort. This section is to help seasoned ZZTers adjust to MegaZeux. Firstly, some mechanistic differences exist. Here are some of the more prominent examples. -MegaZeux uses counters instead of flags; however, counters can easily be used as flags if set only to 1 and 0. -MegaZeux has an incredibly high amount of available counters. -There is no default mechanism for torches. -No equivalent of centipedes exists as a default enemy. -Multiple MegaZeux keys of the same color can be picked up at once. -There is no board setting controlling the amount of player shots that can be on a given board, outside of preventing the player from shooting altogether. -Cloning the player has no use in MZX; uses of player clones need simulated in Robotic. -Unlike ZZT Objects, MZX Robots can detect being shot when the player shoots them point-blank. -ZZT prevents moving between boards if the other board has an object where the player would end up, but MZX simply overwrites the object on the other board with the player. -Bomb explosions are not instantaneous but instead radiate out from the center. They are also diamond-shaped as opposed to a flattened oval shape and do not ignore walls. -MegaZeux uses cycle 1 as default (as opposed to ZZT's cycle 3). -No equivalent of duplicators exists. -Seekers (aka "stars") and bears do not destroy Breakaway territories in MegaZeux. -MegaZeux water is not equivalent to ZZT water, as it can be traversed. ZZT water is most similar to MZX's "goop". -MZX Sharks can be shot. They do not swim in water, but can in lava or goop. They can also shoot any type of projectile. -MZX Scrolls cannot execute code. Use a Robot ending with the "die" command to emulate ZZT scrolls with code instead. -Terrains that give out a distinctive message on first touch (fakes, forests) give out no such message in MZX. -There are two types of Gems; the one that best emulates ZZT gems is the Magic Gem. -Lasers will not push the player into other objects. This makes some ZZT laser configurations a lot less deadly. -Scrolls with only one line launch a message box (instead of using the message line for the line). -The Shift-? hotkey (often used for inventory engines) does not exist in MegaZeux but can be emulated with Robotic. -ZZT has one less bullet type than MZX; shift MZX types one tier of "friendliness" for each typical shooter to get ZZT-equivalent bullets. -Putting in fake commands for comedic effect (e.g. putting in #GOSUCKANEGG to make ZZT beep and go "ERR: Bad command GOSUCKANEGG") does not work in MegaZeux and has to be emulated. -Special exploits (e.g. black holes, monitors, speed-up exploit, flag overloading) have no direct MZX equivalent. -Other, extremely minor, differences best left for total wonks or for ZZT port authors, while others are implicitly understood and do not require spelling out. Secondly, here is how the ZZT-OOP commands convert to Robotic. --------------------------------------------------------------- Key: [*] = There's no direct (i.e. one-line) way to make Robots do commands on IF statements. A label pointing to the command will have to do. [+] = There is no good analogue for this command, due to bound objects sharing zap/restore settings in ZZT. Without these concerns, COPYROBOT is the closest match. Also, ZZT objects using BIND use only as much memory as the object had before in ZZT, while Robots using COPYROBOT will use as much memory as the target Robot once copied. [#] = You need to manually add a label at the top of the Robot for this in MZX. --------------------------------------------------------------- @object_name = . "@Robot_name" /direction/direction = PERSISTENT GO (works only for cardinal directions and idle: n s e w i) ?direction = / "directions" 'comment = . "comment" one line of text = * "text" multiple lines of text = % "text" !label;text = ? "label" "text" $ text = % "~ftext" (by default palette) #BECOME thing = BECOME color thing param #BIND object_name = COPYROBOT "Robot" [+] #CHANGE thing newthing = CHANGE color thing param newcolor newthing newparam #CHAR # = CHAR # #CLEAR flag = SET "counter" 0 #CYCLE # = CYCLE # #DIE = DIE #END = END #ENDGAME = ENDGAME #GIVE item # failure_label = GIVE # item (MZX version has no optional failure label) #GO direction = GO direction # #IDLE = WAIT # #IF flag label;text = ? "counter" "label" "text" #IF flag THEN command = IF "counter" = 1 THEN "label" [*] #IF ANY object THEN command = IF ANY color thing param "label" [*] #IF NOT flag THEN command = IF "counter" = 0 THEN "label" [*] #IF condition THEN command = IF condition THEN "label" [*] #IF NOT condition THEN command = IF NOT condition THEN "label" [*] #LOCK = LOCKSELF #PLAY notes = PLAY "notes" #PUT direction thing = PUT color thing param direction #RESTART [#] #RESTORE label = RESTORE "label" # #SEND label = GOTO "label" #SEND Objectname:"label" = SEND "Robotname" "label" #SEND ALL:command = SEND "All" "label" [*] #SET flag = SET "counter" 1 #SHOOT direction = SHOOT direction #TAKE item # failure_label = TAKE # item "failure_label" (failure label optional) #THROWSTAR direction = SHOOTSEEKER direction #TRY direction label = TRY direction "label" #UNLOCK = UNLOCKSELF #WALK direction = WALK direction #ZAP label = ZAP "label" # --------------------------------------------------------------- As for conditions, a few are changed: ALLIGNED is now ALIGNED CONTACT is now TOUCHING ANYDIR ENERGIZED is no longer a condition but the "invinco" label. --------------------------------------------------------------- This should be all one needs to make most ZZT-style games for MegaZeux, except for a little Robotic knowledge to replicate things like torches and duplicators. Of course, much more powerful games can be made with MegaZeux; see corresponding help for details. Table of Contents

Dialog Boxes

Much of MegaZeux's interface is made of dialog boxes. A dialog box is a form of inputting various information. An example of a dialog box is the Save Game box or the Settings box, both in-game. To use a box is simple - Use TAB and SHIFT+TAB to highlight an element, and type or use the cursor keys to change the value. Press ENTER on a button (Rectangle with a label) to exit the dialog or produce an effect. MZX also utilizes mouse control. You can click on a dialog box element to select it, or click on a selected element to change it. The mouse wheel will cycle up/down the choices in the current section. Click on a selected button to activate it. You can usually use HOME to jump to the first section of the dialog box, and END to jump to the OK or NEXT button. TAB jumps forward a section, while SHIFT+TAB goes backwards a section. The different dialog box elements and special related keys are explained in detail for the remainder of this section. INPUT - This is where you type in a series of characters, usually letters and numbers. You can move the cursor around within the line, type to insert characters, move to the start with Home, and move to the end with End. Alt + Backspace deletes the entire line, while Ctrl + Backspace deletes the last typed word. NUMBER - This is where you have a number and you change it with the arrow keys or mouse clicks on buttons. Up, Down, and the mouse wheel will change it by 1, Alt+Up, Alt+Down and Alt+Wheel will change it by 10, and PageUp and PageDown will change it by 100. You can also hold the mouse button down on one of the arrows to change the number or press 0-9 to set the last digit. Pressing 0-9 on the keypad changes the current digit to that value. Finally, Backspace deletes the last digit. NUMBER LINE - This is a line of numbers, with one highlighted. It functions in a manner similar to the above, but in a limited range. CHARACTER - This is where you can select characters. Press a character to use that character; click on it or press Enter to get a large menu of characters (32x8) to select from. COLOR - This is where you can select a single color. Press Enter or click on it to get a large menu of colors to choose from. CHECK BOXES - These are On/Off switches. Use Up/Down or the mouse wheel to move within the list of choices, and use Space, Enter, or mouse clicks to toggle choices on and off. Press Tab to jump out of a check box section. An [X] means the option is currently on. RADIO BUTTONS - These are similar to Check Boxes, but are mutually exclusive. The mouse or arrow keys will select the current and ONLY option that is on. The ( ) shows the current option. BUTTON - These are rectangles with labels. When selected, press Enter or click to activate. OK or Done will verify the contents of the dialog box. Cancel will cancel any changes you've made. (ESC will usually do this as well.) Next and Previous move between multiple dialog boxes. Other buttons do what their label signifies and are explained in the appropriate help section. LISTS - These show a selection from a list of choices. The current selection is shown. Press Enter or click on it to bring up a list of choices from which you can select a new choice. Table of Contents

Controls

Universal controls are as follows: -Tab goes forward one section; Shift+Tab goes backward one section. -Esc cancels. -Enter selects. -Alt+Backspace deletes the entire line. -Ctrl+Backspace deletes the last typed word. -Ctrl+Left jumps to the previous word; Ctrl+Right jumps to the next word. -0 thru 9 sets the last digit in a number box (such as setting amounts of items in a chest); backspace deletes the last digit. On Mac platforms, any command that uses the Alt key can take  (the command key) instead. File access controls are as follows: -(0-9 and A-Z) will jump to the first file/directory starting with that character. More specific seeking can be done by typing characters in quick succession (for instance, s+e+c would jump to the first file starting with sec). -Del will delete the highlighted file/directory. You will be asked for confirmation. -Alt+R will rename the highlighted file/directory. -Alt+N will create a new directory. In-game controls are as follows: F1 - Help Use this at any time to bring up context-relevant help. While in a loaded world, this key will load the Controls section. Some games may have this menu disabled or replaced with their own help menus. Enter - Menu/Status Use this to bring up a menu of options and a list of your current stats, such as Score, Gems, any custom-defined status counters, etc. Some games may have this key do nothing, or even something different entirely. Clicking on the key shortcuts (everything but move/shoot/bomb) will perform the given action. Certain key shortcuts will not be listed if the current MZX world prevents their default actions from happening. "Help", "Save game", "Restore game", "Quicksave" and "Quickload" can be filtered out this way, while "Exit to title" and "Settings" are always available and still work when clicked even if otherwise locked out. ESC - Exit to Title This will load a prompt to quit the current game and return to its title screen. In yes/no dialog boxes, this key triggers the "no" option. Some games may disable using ESC to trigger the exit prompt, but other methods (such as Alt+F4 or clicking on the "ESC - Exit to Title" text in the Enter menu) will always work. F2 or Ctrl+F2 or Alt+F2 - Settings This will bring up a dialog box where you can change the current game settings: Game Speed (if allowed), Music/sample SFX toggle, PC speaker SFX toggle, and Audio Volumes (Music, Samples, and PC Speaker). Speed 1 is the fastest; speed 16 is the slowest. A speed of 1 will run MZX as fast as possible and as such acts differently between computers; it will also cause flicker in fullscreen mode, so it is not recommended unless it is your only option. (Please note that some games may have the speed change by itself and/or enforce a set speed.) No changes to sound options will go into effect until the Settings menu is left. In addition to these settings, one can change the current renderer with the "Select renderer..." button, and can change the scaling shader if running MegaZeux with the GLSL or auto_GLSL renderers. Settings for game speed will only apply for the current world; all other settings are global. Note that some games may block access to the F2 menu entirely. Ctrl+F2 or Alt+F2 will ignore this setting and allow access to the menu even if it is prohibited otherwise, as will clicking on the "F2 - Settings" text in the Enter menu. Ctrl+F2/Alt+F2 will not override any F2 block while MZX is in standalone mode. F3 - Save Game This will load a prompt for a filename, allowing the saving of the exact state of the current game. Some games may not allow manual saving on some (or any) of its screens, or will only allow manual saving in certain spots of a board. Saving lets you quit your game in the middle or take precautions against unknown dangers. F4 - Restore Game This will let you select a saved game from a list of filenames. The game will then be reloaded from the same point you left off. While most games will allow loading anywhere, some will restrict loading to certain times or will use a custom mechanism for loading games instead. MegaZeux will refuse to load any save made in a version older than 2.84 or newer than the current version number. (For instance, 2.92 can load saves made in 2.92c and 2.90b, but not saves made in 2.93 or 2.83.) MegaZeux has the ability to save and load games in save slots instead of choosing a file. Save slots are tied to the current MZX world, and each MZX world gets 10 save slots. This can be enabled in the config file. NOTE: A few games may save or load automatically, and high-caliber games may have completely different methods of saving and loading games. The Config File F5 or Ins - Toggle Bomb Type This will switch your current bomb type between High Strength and Low Strength. F6 - Debug Window This will bring up a small box in the lower left corner of the screen, detailing several statistics. The top-right of the box displays the world version of the current world; X/Y lists the current x,y position of the player; Board lists the current board number; Robot mem lists the amount of Robot memory currently consumed by the current board's Robots; the space below lists the currently playing music, with "(no module)" for none and "*" for the module wildcard; finally, the bottom right numbers list the key_code (green) and key_pressed (magenta) values of the last pressed key. Press F6 again to turn the box off. This shortcut will only work during playtesting in the editor. F7 - Items Cheat This will set ammo, coins, gems, hibombs and lobombs to 32767, fill health (set to maxhealth), fill lives (set to maxlives), and set keys to one of each color. This is a cheating function, so do not use unless fully necessary; a few games punish the player for using this function. This may be limited to playtesting sessions in the editor, or limited to MZXRun builds, depending on config.txt settings. F8 - Zap Cheat This will destroy everything in all eight directions directly around the player, replacing all eight squares with spaces. This is a cheating function, so do not use unless fully necessary; a few games punish the player for using this function. This may be limited to playtesting sessions in the editor, or limited to MZXRun builds, depending on config.txt settings. F9 - Quicksave This will save the game, like F3, but will automatically save to the last filename you used. The old file will be overwritten. If no game has been saved since MegaZeux was started, the save will have the default filename listed in the config.txt file. If saving is blocked, quicksaving will be blocked as well. The Config File F10 - Quickload This will load the last save that was saved with F3 or F9. If no game has been saved since MegaZeux was started, the default save filename will be used. The same caveats about save versions still apply here. If loading is blocked, quickloading will be blocked as well. F11 - Counter Debug Mode This will load a screen listing which counters and strings have been set, as well as values for default counters and strings. Counter debug mode allows considerable manipulation of counters and strings, among other things. This shortcut only works when playtesting in the editor. For more detail, go to its specific section. Debug Modes - Counter Debug Mode Alt+F11 - Robotic Debugger This will launch the config menu for the built-in Robotic debugger. The Robotic debugger can monitor running Robotic code and allow step-by-step reading and manipulation of running Robots as they execute. This shortcut only works when playtesting in the editor. For more detail, go to its specific section. Debug Modes - The Robotic Debugger F12 - Take Screenshot Pressing F12 will make a 640x350 screenshot (in PNG format by default) in the working directory, using the software renderer. The file naming starts from "screen0". The config file may disallow taking screenshots, depending on setting. Arrows - Move The arrow keys will move the player and allow it to interact with most objects in most games. Space - Shoot If Space is held, pressing an arrow key fires a bullet from the player in the selected direction, with each shot taking one ammo. The player will not move with the arrow keys while trying to fire a bullet, even if the player can't shoot or is out of ammo. Some games may have Space shoot different shots or even give Space different uses. Del - Bomb By default, this will drop a bomb of the current type BENEATH the player. Move off of it to activate it, then run before it explodes! Uses of the del key may vary from game to game. Tab / Left Arrow / Right Arrow - Select Option In yes/no dialog boxes, these keys toggle between yes and no. Other games may have other controls, such as 'S' to cast a spell or 'I' to bring up an inventory screen, but they should be detailed within the game. The following keys are active at the title screen: F1 - Help (see above) Enter - Menu This is similar to default Enter within the game. However, it brings up a list of key bindings instead. ESC - Exit MegaZeux Pressing ESC will load a prompt where the user can exit MegaZeux. F2 / Ctrl+F2 / Alt+F2 / S - Settings (see above) F3 or L - Load World This will allow you to load up the title screen of any MegaZeux world. A list of choices will be presented to you to select from. After the world is loaded, you may watch the title screen, then press 'P' to play. F4 or R - Restore Game (see above) F5 or P - Play Game This will stop the title screen and actually begin game play. F7 or U - Updater This will load the updater, if it is enabled. The updater will connect to an online repository and check if a new MegaZeux version is available. If so, the user gets the option to update MegaZeux. MZX will then list the files added/changed/deleted in the update, and if the user decides to update, MZX will restart when the update is finished. WARNING: This will most likely replace your config.txt file, so if you want to keep your settings, make a backup first so you can apply your settings to the new file! F8 or N - New World This will quit the gaming portion of MegaZeux and enter the integrated World Editor, set to an empty MZX world. Alt+N will act the same, but skip the prompt to name and create a starting board. F9 or E - Edit World This will quit the gaming portion of MegaZeux and enter the integrated World Editor, set to edit the currently-loaded world. When no world is loaded, this acts the same as New World, and Alt+E with no world loaded will also skip the prompt to name and create a starting board. Note that "MZXRun" builds of MegaZeux do not contain the editor. For detailed info on using the World Editor, view the appropriate help sections. The World Editor F10 - Quickload (see above) -= About MegaZeux =- Selecting this will display various information about the currently-running MegaZeux build, such as version, architecture, and library build versions. Table of Contents

Nondescript Play Tips

First, let me warn you that many worlds you get from archives or (especially) from personal webpages may not be of acceptable quality. They may be unfair, boring, have numerous bugs, and/or not give proper instructions. On a related note, PLEASE try to get feedback and try acting on it before uploading your game, even in these days where games are fewer and farther between. Really old games of bad quality, on the other hand, are tolerated somewhat better. Don't let a few dull games ruin the fun. With that out of the way, some basic play tips: * RTFM (Read the Flipping Manual). Whatever information the game has to give is probably important. Some authors include info files in their distributions or custom F1 help; make sure these are read. It saves everybody time and effort. To authors, it saves time and effort to include at least one of these in your submissions. * Make sure you visit every screen possible. * Save your game! It is rather simple - in most games, Press F3 to save your game to disk at the EXACT point you are [if allowed]. Press F4 to reload a saved game. You can use F9 and F10 to quick-save and quick-load, which work on the last game you saved. Remember to save often and keep multiple saves- If something ends your game, you'll want to lose as little progress as possible. * Touch everything! Even things of seemingly little value may prove worthy of your attention. If it kills you, then... well... hope you saved (see above). * Collect supplies! Make sure you grab every coin, gem, ammo dump, bomb, chest, pouch, and foobar you see! You will often be in want of supplies, so don't push things. * Remember how things work. Most things in MegaZeux have patterns, even Robots, and the same object will usually do the same thing all the time. (However, two objects may look alike and not really be the same thing.) * Don't take anything for granted. If it looks like a spike, it probably is. _Probably_. Although it is rare that these types of puzzles must be solved to complete a game, there are often bonuses, hidden rooms, etc. behind illusions. * Try things twice, even thrice. Sometimes objects respond differently at other times. If you get a new treasure, go talk to all the citizens - maybe one of them will say something new. If some place seems inaccessible, come back later! * If doing the same thing over and over keeps failing, try something else. It helps to look at new methods and to put distance between yourself and the problem. * Bullets can stop spitting fire, but only sometimes. If trying to gun down an enemy that spits fire, stagger your shots somewhat; holding down the spacebar often results in ALL of your shots being cancelled. * If all else fails, look in the game with the editor. This depends on the clarity of the author(s)'s code, but looking in the editor can help if all other solutions have been exhausted. Searching functions can make this easier: the world editor can (e.g.) show Robots with Shift+F2, and the Robotic editor can do searches with Ctrl+F. Table of Contents

Mouse Support in MegaZeux

Use of the mouse is very simple. Move the mouse to move the mouse cursor. Press the Left mouse button to select something, activate something, etc. Press the Right mouse button to grab whatever's under the cursor in the World Editor. Certain games may make use of the mouse during gameplay. The scroll wheel will always emulate up/down presses in dialog boxes and the list menu on top of whatever functions it may have in the current game. Table of Contents

The Mirth of Built-ins

The following help section contains a list of the different objects, enemies, items, and terrains you will find within the different MegaZeux worlds. Want to make a (very) quick and (very) dirty game? Built-ins are the way to do it! However, outside of a select few built-ins (such as certain terrains, Robots and items) heavy usage of these built-ins for long-term projects is best-suited for beginners and savants.

 Terrains 

Space This is the simplest terrain; it does absolutely nothing! Normal  Solid  Tree  Line  Custom Block ? These are all basic obstacles; they just get in the way. Sometimes trees can be burned down. Breakaway  Custom Break ? These block movement as well, but they can be destroyed with most weapons (such as bullets or bombs). Certain other things can destroy them as well. Fake  Carpet  Floor  Tiles  Custom Floor ? These are all treated as flooring, or "background". Anything, including yourself, can move onto and over these. They are primarily for decoration. Web  Thick Web  These are another type of flooring. However, webs are often the home for spiders, so watch your step! Forest  This terrain will block the path of almost any built-in. You, however, can move through it with ease, clearing a pathway. Enemies can move along a cleared path. Invis. Wall This LOOKS like just an empty space... until you bump into it. Then it becomes a normal wall, blocking your path.

 Items 

Gem  Magic Gem  Gems are a collectible. Your total number of gems is shown on the status screen, and each gem gives you one point. Many older games also use them as a type of currency, where you can trade gems for stuff like food, ammo, weapons, or hints. Gems are fragile, and will be destroyed when shot or bombed. Magic Gems count as Gems and act like Gems, but they also increase health by one point apiece when taken. Health  This will improve your outlook dramatically. Collecting one of these increases health by a certain amount. The amount varies for different hearts. Keep in mind that if you're currently at your maximum health, running into a heart will still collect it. Energizer  After grabbing an energizer, the player will flash colors for a limited time (specifically, for 113 cycles). During this period, you are invincible against enemies, bullets, fire, lava, poison damage, and most other forms of pain. Be careful not to get into a dangerous situation as its energy runs out! Any energizer grabbed while already energized resets the timeout period to 113 cycles. Ammo   When you grab ammunition, it will add a certain amount of ammo to your supplies. The small piles hold 0-9 shots, and the large piles 10-255. The amount may be different for each pile. Bomb  Each bomb you grab adds another to your supply. The sound made when you grab the bomb will be high-pitched for a high strength bomb and low-pitched for the rare low strength bomb. Hibombs will explode for five tiles in all directions, while lobombs explode for only three tiles in all directions. Some boards may not allow the player to collect bombs, and instead will have bombs ignite on touch. Key  Collect keys to open locks, doors, and gates later on. The key and the lock/etc. must match foreground colors, and a key will only work once. (For example, a dark blue key will open any dark blue lock, regardless of the lock's background color.) You can carry up to sixteen keys at once. The default status screen, if viewable, will show your current supply of keys. If you've played ZZT games, you'll be interested to know that you can carry multiple keys of the same color. Lock  A lock will only open if you have a key of the same foreground color to unlock it. The key can only be used once and will disappear along with the lock. Coin  Collecting coins is a good idea. Coins not only increase your score by one, but can often be used to purchase valuable items or services from vendors. Unlike Gems, Coins can withstand being shot or bombed. Life  A life orb will give you yet another chance for survival in MegaZeux. Keep in mind that if you're currently at your maximum amount of lives, running into a life orb will still collect it. Pouch  A pouch is usually filled with coins, gems, or even both. The amount varies, but often you will find yourself pleasantly rich...as long as you can get to it before a Bomb can destroy it. Chest  A chest can contain numerous things. The contents will be one of the following: Empty, a Key, Coins, Lives, Ammo, Health, a Potion or Ring, Bombs, or Gems. Once you grab the contents, the chest itself will remain, but be empty. Chests will not survive being bombed, empty or not. Ring o Potion  These mystical items will bestow a magical effect on you when you wear or drink them. The effect, however, is unknown to you until you try it... and some effects aren't so nice. All rings and potions increase score by 5 when collected.

 Potion and Ring Effects 

Effects are limited to the current room only, except for healing, hurting, and invinco. No Effect This effect does absolutely nothing. Invinco Just like an energizer, you will become invulnerable to most forms of pain until you stop flashing. Blast Scatters plentiful, random explosions around the screen. Health x10 Health x50 Gives the player 10 or 50 additional health points, respectively. Poison Reduces the player's health by 10. Blind Temporarily blinds the player. The entire viewport, except for the player, will look like dark gray floors. You can still move and interact, but you won't be able to see anything distinct but the player. Kill Enemies Kills all enemies in the room, including "Invincible" enemies. Lava Walker Allows the player to temporarily walk on lava and fire. Detonate Explodes all bombs and lit bombs in the room. Banish (Dragons) Turns all dragons on the board into ghosts. Each ghost made this way will have intelligence set to 4, movement speed set to 4, and the "Invincible" flag set to off. Summon (Dragons) Turns all creatures on the board - excepting guns - into dragons. (This includes other dragons.) Each dragon made this way will have a firing rate of 3, 4 hit points, and the "Moves" flag set to on. Avalanche Scatters boulders randomly around the screen. Freeze Time Freezes ALL non-player on-screen objects (including all Robots except the Global) for a short time. This will also freeze any active board timer. Wind The player retains control but will also move additional random steps for a limited time. The wind will blow the player in all directions. Slow Time Slows ALL non-player on-screen objects (including all Robots except the Global) for a short time. The resulting speed is approximately half normal speed. This will also slow any active board timer.

 Creatures 

Snake  Runner  A snake moves in a straight line until it hits an obstruction, then aims itself in another direction and continues. Hitting a snake (like all enemies hereafter unless noted) will cause you to lose health, then kill the snake, while hitting the snake with a player bullet will kill the snake and increase score by 3. Runners act like snakes and will take up to four hits, but will only go the opposite direction when obstructed. Eye  An eye chases you down like any ordinary enemy, but when it catches you or dies, it explodes! The size of the explosion can vary with each eye. As eyes float, they can traverse both goop and lava. Ghost  Thief  A ghost is the simplest enemy, simply chasing you. While some of them are invincible, most can be killed. Thieves chase but don't do damage. They steal your gems on touch instead, and can do so multiple times until killed. Ghosts can traverse lava and goop; thieves cannot. Ghosts give no score when killed by a player bullet. * Slime Blob ** * A slime blob usually doesn't hurt you, but it can quickly become incredibly annoying because of its habit of dividing into more slime blobs, then hardening into "solid slime" (i.e. breakables), quickly filling rooms.... You can often kill slime by touching or shooting it, but some slimes can be invincible, and others can be harmful to touch. Slime blobs give no score when shot by a player bullet. Dragon   * Some dragons move around slowly, but their main advantage is their offense - they can shoot barrages of scorching flame. Dragons also have a strong defense, taking up to eight hits to kill, and take only one hit of damage from explosions. Touching them will take away health, but will NOT hurt the dragon. Dragons can traverse lava but not goop. Fish  Shark  Spitting Tiger     Fish have to stay in the water and often can't hurt you. Those that can, however, will hurt you if you're adjacent to them, even if you're on land. Some fish take two hits to kill. Sharks, however, swim in lava or goop, are always hostile, and can attempt to shoot you with fire, bullets or seekers. Spitting Tigers act like sharks, but are restricted to land.  Spider   Spiders, although eager to catch you, are usually restricted to movement on webs. Certain spiders, however, can actually leave the webs. Some spiders take two hits to kill. Goblin  Goblins chase but periodically stop, making them an easy built-in villain. Bear  Bears only move if you get too close, then they lumber over for the attack. Many require 2 hits to kill. Bear Cub  Bear cubs are very lively, rushing all over the place. Since they move so fast in a seemingly random manner, they are often hard to kill. Bullet Gun    Spinning Gun *  Bullet and spinning guns, both indestructible, fire any type of normal projectile (bullets, fire or seekers). The bullet gun, however, is fixed while the spinning gun can fire from all cardinal directions. Lazer Gun  The indestructible lazer guns fire off lazer walls at regular intervals, and sustain these walls for a specific length of time. Unlike in ZZT, getting hit by a laser does not push the player into objects, though it will push the player if a space is open. The beam can be obstructed by nearly anything not a ground type, even including a bullet. Missile Gun  Missile guns fire missiles in one direction. Some fire just once while others can fire missiles indefinitely. The gun itself is indestructible.

 Puzzle Pieces 

The following objects are often used to create mind-twisting puzzles requiring you to push objects all over the place to reach a goal. Be warned. Boulder  Crate  Custom Push ? Boulders and crates can be pushed in any direction, with any number of pushable things in a row. They can be blown up. Box  Custom Box ? Boxes can also be pushed in any direction, but cannot be blown up. Pusher   Pushers cannot hurt you, but they constantly try to move in one given direction, pushing almost anything in their path - Boxes, crates, and even you! Slider NS  Slider EW  Sliders can be pushed, but ONLY in certain directions. A Slider NS can only be pushed north/south, while a Slider EW can only be pushed east/west.

 Transport 

Stairs  Cave (or door)  Whirlpool  When you enter any one of these, you are transported to another location within the current world. These are not always two-way connections. The specific destination is determined as follows, from highest priority to lowest, scanning right-to-left from the lower-right corner to the upper-left: * Same passage type, same exact color * Same exact color * Same passage type, same foreground color * Same foreground color * Same passage type * Default player position on destination board If the current board and destination board are the same, no teleport will happen. CW / CCW \ These rotate in the given direction (ClockWise or CounterClockWise), rotating everything around them at the same time. Walls and other solid objects will not be affected. v Transport } { ~ Most transporters face a single direction. Entering these on the "open" side, or pushing other things into them, will cause a jump to another location. Some transporters rotate; those can be entered from any side. The destination of a transport is somewhat complex, but the search pattern is as follows: 1. If the other side of the entered transport is empty, move there. If there is something there that can be pushed out of the way, move there and push it out of the way. 2. If the other side is blocked, continue in that direction looking for the first non-blocked transporter facing the OPPOSITE direction, or an "any-direction" transport. 3. If neither condition can be met, no transport takes place.

 Elements 

Still Water  N Water  S Water  E Water  W Water  Water is a type of floor that can be moved onto by the player, some enemies, and certain other objects. Sometimes, water has a current, moving you constantly in a certain direction. Ice \ Ice is another type of floor. However, the player will slide on it, constantly moving in the last direction the player moved until running into a non-pushable obstacle. Attempting to move in another direction while still on ice will cause the player to slide in that direction instead. Lava  Lava is another floor. However, it is (almost always) very deadly. Only a few things can traverse it, puzzle pieces cannot be pushed onto it, and any player unfortunate enough to walk on it will typically suffer rapid and massive amounts of damage. Fire  Fire is yet another type of floor. It often will spread across the board, turning things such as trees, fakes, brown objects, and sometimes even empty space into more fire. It can damage the player at random intervals when merely standing near it, and cause constant damage while standing ON it, but by default fire does far less damage than lava. Most fires will eventually burn out, and the objects it burns are determined by the board settings. Lit Bomb  Mine  A lit bomb is an explosion on a fuse. You DON'T want to be nearby when the fuse runs out... mines, on the other hand, only blow up when touched, shot, or hit with an explosion.   Explosion    An explosion starts at a certain point, quickly spreading outward, wreaking havoc in its wake and destroying most creatures. Some explosions are smaller than others. Explosions will also cause explosives such as bombs to explode, leading to some very cool chain reactions. Goop  Goop is pretty much non-traversable terrain to anything landborne. Sharks may occasionally inhabit it, and select Robots may be able to walk in it. Bullets, lazers, and other projectiles will traverse it freely. Goop may also be treated as water or other terrains in certain worlds.

 Miscellaneous 

Door  Gate  A door is what you would expect - When you touch it, it will open itself, pushing obstacles in its path out of the way, and then close after a brief pause. Doors require two free spaces in the direction it moves to open fully. Certain doors are locked and require you to use a matching key to open them. They then remain unlocked. Gates act similarly, but do not move; they can be moved over directly when open. Ricochet Panel / Ricochet * When a bullet hits a ricochet panel, it is reflected to travel in a new direction, depending upon the way the panel is facing. When a bullet hits a ricochet, it is reflected back in the original direction. Any bullet that hits a ricochet panel or a ricochet will have its type set to neutral when reflected. Spike  Custom Hurt ? Spikes and other painful devices will simply hurt you if you touch them. These are often used in conjunction with ice or with sidescroller engines. Text ? Another type of wall. Cannot be walked on, but can provide hints or other enlightening messages. Moving Wall N ? Moving Wall S ? Moving Wall E ? Moving Wall W ? Moving walls are like Runners - they just move back and forth, to and fro... They can't hurt you by touch, but can get in the way very easily.

 Objects 

Player  This is you. Really. Well, sometimes. The player is often locked, with a Robot or sprite representing the player character, but exactly one player object is always present. Scroll  Sign  Touch this to display a given message. The message will be in a message box. A scroll will disappear after you finish reading it; signs will not. Unlike in ZZT, scrolls and signs are text-only: they cannot execute any commands. Also unlike ZZT, messages only one line long will still be shown in a message box. Missile  Missiles fly around the room, turning at obstructions. They will explode if they hit the player or when they cannot turn. Bullet  Bullets will fly in a straight line until they hit something (and disappear) or do damage to someone or something. Ricochets can change the direction a bullet is traveling in, as well as change its type to neutral. There are three types of bullets: Player (the player shoots these by default), Neutral (Robots shoot these in a default shoot command), and Enemy (built-in enemies shoot these by default). Player bullets cannot harm the player; Enemy bullets cannot harm default enemies; Neutral bullets can harm both the player and default enemies. Seeker | A seeker, thrown by a Tiger, Shark, or other enemy, will chase the player all over the screen until they collide and do damage. Collision with most projectiles will not destroy it, only pause it. They have a limited life, however, and will expire after a certain amount of time or when caught in an explosion. They are still one of the deadliest weapons you will face; more than only a few at once can easily ruin a game, especially in cramped spaces. Shooting Fire  * Shooting fire will continue in a straight line until it hits the player (resulting in direct damage) or another object (resulting in a small fire). The fire may quickly spread out of control in some areas, or just burn out in others. Bullets can sometimes destroy shooting fire, but other times the shooting fire simply absorbs the bullet. Sensor ? Sensors are a form of floor that only the player can move onto. They will usually then produce some form of effect, by interacting with a Robot; other times they act as "save points". Other objects will push them around instead. Sensors - What They Are and How to Use Them Robot ? Pushable Robot ? Robots are the workhorses, the artisans, the... nearly everythings of MegaZeux. They are highly flexible objects which can do almost anything. They utilize their own full-scale programming language, dubbed Robotic. If another object can do something, a Robot can almost always do it better. They can show messages, fight the player, play music or sound, set the entire gameplay structure, and do countless other things. See the appropriate help sections for more information. Robots - What They Are and How to Use Them Table of Contents

The Config File

One of the first things a new MegaZeux user should do is edit the options in the config file; even experienced MZXers may find some of the customization options novel and useful. Go open config.txt in any text editor. There is ample commentary to let the user know how to change the options. Make sure to remove the # sign from any option you want set! Editing the options can result in better sound, better / more customizable graphics, more fitting defaults, a more personalized Robotic editor, joystick support, extended macros, automated backup and much more. New versions - even minor version changes - can add new options to the config file or rename old ones, so it is helpful to keep this file current. Table of Contents

If You Find a Bug...

..we want to know! We're very interested in any problems or bugs you find in MegaZeux. We also welcome any comments, criticism, or suggestions. We especially appreciate older MegaZeux worlds. Here's the contact information as of this writing: Check the reports on DigitalMZX's Bug Tracker (https://www.digitalmzx.com/forums/index.php?app=tracker) to see if your problem has already been addressed. Active problems and bugs that are only fixed in a development version of MegaZeux are listed, as of this writing, in the "MegaZeux" category, while the bugs that are fixed in a stable version are in the "Closed MegaZeux Bugs" category. Feature Requests are handled similarly. To make things sane for all parties, do this before submitting: 1) Make sure you have the most current version of MegaZeux. 2) Make sure that the Bug Tracker or development version doesn't already address your issue. 3) Try to be specific in explaining what happens. The more precise, the better. 4) List what platform(s) you know show this problem. 5) Try to pinpoint the problem to a specific Robotic line or MZX function; at the very least, try to narrow it down. Pinpointing which version introduced the bug is very helpful, if possible. 6) If it is a crash, try to run a debug build through GDB and post a backtrace of the crash. Instructions for running a debug build through GDB are on the MZXWiki at DigitalMZX, in the New MegaZeux Release FAQ. 7) If you're unsure if the bug's been addressed, try to build a version from GitHub's GIT repository and see if the bug is still present in the test build. The MZXWiki has instructions for doing so in the article Compiling MegaZeux. 8) Optimally, if the problem is a regression caused by the port, upload a world made in 2.70 that works in 2.70 but does not in the current version to best isolate the problem. Additionally, contacting the developers in real-time can help illuminate the problem. Table of Contents

Frequently Asked Questions

The following is a list of questions that have been received about MegaZeux innumerable times in some form or another. Q: I read that newer versions of MegaZeux break old games. Which version should I get to play games? A: The most recent version. MegaZeux development places enormous importance on backwards compatibility, and contrary to what some others have stated, there are very few cases where an older version is needed to play a specific game. Q: I hate that MegaZeux is always windowed! Could you change this? A: There's already a way to switch between fullscreen and windowed modes - press Ctrl+Alt+ENTER. Also, the config file has options that start MZX in fullscreen mode (either true fullscreen or as a borderless window at desktop resolution) at launch. Q: How can I get option (foobar) in the config file to work? A: Make sure the pound / hash sign in front of the command is deleted. Otherwise, the option is treated as a comment and ignored. Q: Are there any MZX-specific tools that can make developing an MZX game easier? A: Yes, plenty! MegaZeux comes with two helpful tools: "Checkres" will detect what files are referenced by an MZX world and which are present, and "ccv" can take an image file and output a conversion of it in .chr/.mzm form for MZX use. There are also several graphical conversion programs such as CharCon. MZX has natural time-savers, of course. Automated backups, macros, Robotic code import/export, expressions, repeated block copying, sprites and other features can help speed up development time. Q: This MZX game has some neat things in it! Can I use some of these things in my own game? A: It's usually okay to do this, as long as you give definite credit to the original creator(s). Unless it was made specifically for the game, music and sound from other MZX games generally doesn't need direct attribution, but re-used artwork and code definitely should get attribution. If you're unsure whether the original creator(s) would like you using their work in your own game, ask! What we don't want to see, though, is passing the work of others - especially graphics, writing, and code - as your own. DON'T PLAGIARIZE. JUST BECAUSE THEY DID NOT EXPLICITLY FORBID YOU FROM USING THEIR WORK DOES NOT MEAN YOU CAN PASS IT OFF AS YOUR OWN. Q: Can I distribute a world I made with MegaZeux? Is it legal? Must I/can I include MegaZeux with it? Can they be shareware worlds? A: Of course you can distribute your worlds! That is what MegaZeux is for! However, while there are those who would help point out your game's flaws in a forgiving manner, not everyone is capable of constructive criticism. Playtest your game before uploading it, with at least one other person evaluating the game for bugs, play balance, and text/plot/grammatical errors (when relevant). Get creative and make your game worth playing! Please include any WAV, module, OGG, CHR, MZM, PAL and all other files with the games, as well as a cohesive and helpful description file or manual. (Using checkres to guarantee that every relevant file is included can be helpful.) While you can simply distribute your game with a copy of MegaZeux included, or even just post the game's files in an archive by itself, consider releasing your game as both a standalone archive and as pure game files in separate downloads. MegaZeux games can also be embedded in a webpage for accessibility and player ease. Typically, MegaZeux worlds are freeware, but if you've made an assuredly epic and ground-breaking game, then you can attempt to ask for registration money in a shareware demo version. Just don't get your hopes up. Alternatively, consider uploading your game to a platform that allows optional donations, such as itch.io. Q: I WANT FUNCTION (FOOBAR) ADDED OR I LEAVE THE COMMUNITY FOREVER :< A: Before you go bugging the maintainer(s) of MegaZeux to add new functions, consider these things: 1) Some things require massive work to implement. These things require changing the world, save or board format, and format changes are explicitly reserved for version number changes. 2) Some things have been purposely ignored because the maintainer(s) deems these things not worth including. In this case, it's probably best to pick up the source and figure out how to add this function yourself. 3) You may not be the first to ask for any certain feature. Current feature requests are listed in DMZX's Bug Tracker. If you are not the first, then you'll often find out why a feature is not implemented or, better yet, you'll end up finding out that it is going to be implemented after all! Either way, you learn more about the feature and what would need to be done to include it. 4) It's technically possible to add new commands, but currently the method of storing Robotic severely limits the amount of new commands. Until this system is retooled, there will be no new commands. Features that are most cleanly implemented through a new command may possibly be implemented in other ways, however. Q: Is adding network capabilities to MegaZeux planned? A: Short answer: Possibly. This has been discussed at-length; the biggest problems with adding these to GAMES are thorny implementation issues (how the MZX programmer would insert network capabilities into a MegaZeux world, as well as the structure in general). It's definitely possible, and possible to do soundly, but developers don't have netplay as a high priority. As for other networking capabilities and MZX, this has already been done to some extent (starting with 2.82b, MZX ships with an updater program). Implementing tools and aids for MZX relying on networking is a lot less thorny of an issue, and might be considered. Q: Will MegaZeux games ever be playable without MegaZeux itself? A: In a sense, they can be now. MZXRun, the editor-less version of MegaZeux, can now be set to run in "standalone mode", a configuration designed for only playing a specific world. This mode changes several MZX mannerisms to better accommodate a standalone version of a game. The title screen can also be completely skipped. Additions to Robotic (such as exiting the game through code or blocking the default escape menu) have also facilitated standalone releases. Read the comments for standalone_mode in config.txt for more information, if interested. MegaZeux has also been ported to Emscripten, which means that MZX games can now be embedded into web pages, allowing play without any extra program download or web plugin necessary. Q: I need more than 256 characters! Could you help with this? A: Then you'll need to carefully utilize the Robot command LOAD CHAR SET and ration your characters carefully. The 256-char limit is set within the world format and will currently be left alone. Also, you might not REALLY need 256 characters at once. If you're wanting more characters because of heavy character use in animation, partial character set loading will probably be the best solution. Otherwise, find out which characters will never be shown when other characters are and replace them with characters you actually will use. (Alphanumeric characters, for instance, may see limited use in certain games, or are used heavily in some sections and sparsely in others.) Alternatively, make use of unbound sprites. Using unbound sprites (and ONLY unbound sprites) allows display of 15 full character sets at once instead of just one, on top of their other benefits. Partial Character Sets Unbound Sprites Q: How can I load sounds at different volumes in my game? A: Unfortunately, MegaZeux currently has no way of doing this via Robotic. The best you can do for now is load versions of your sound that are louder/quieter. Volume settings for music, on the other hand, can be manipulated freely. Q: Why is my MegaZeux world starting on the title board? A: The first board has to be set. Press 'G' in the editor, then set the board using the "First board" field at the top left. As of version 2.91, MZX will default to creating and naming a starting board when making a new world, greatly lowering the chance of mistakenly starting on the title. Q: Whenever I place a string on the overlay, the spaces aren't acting like overlay at all! Is this a bug? A: No, it's not. Char 32 (the natural space) is never part of the overlay. You have to reserve an extra character or use the solid character for spaces, or otherwise convert spaces to useable replacements during run-time. If this issue is arising from using the overlay to display messages, consider using multi-line * messages instead. * "string" Q: How can I input a number over 32767 or under -32768 in Robotic? A: You must use an expression. Encase the number in parentheses, as shown here: set "largesse" to "(2000000000)" Q: My Robot can't change its/the player's characters! I use CHAR "A" but it turns invisible! What am I doing wrong? A: Use CHAR 'A' instead. You MUST use single quotes (apostrophes) or it will use the value of the COUNTER A, which is probably 0. Q: Can I use the music from Caverns in my games? How about the music from the registered games? How about the SAM files? A: It'd be preferred if you did not use Caverns music in any games you distribute, because Caverns music was ancient aeons ago. The music from the registered games was illegal to distribute; it's now under the GPL, but should be avoided for the same reasons Caverns music should. The SAM files are public domain and may be used as you please. Q: Where can I get module files? A: If you can't make them, search webpages for good ones. https://www.modarchive.com has a very large tracked music library, as do many old CD-ROM shareware collections. (It is best practice to stick to modules that openly permit free usage.) Another popular option is to convince a friend to do it for you. If your game shows exceptional promise, then an established musician in the community might make music for you. In any case, remember to give credit where it is due (yes, even to yourself). Be careful when inserting OGG files into your game. OGG files often present considerable bloat to a game if used as music. Also, not only may you be chided for putting in a popular song if you do so, but you could be violating copyright law. Chances are that if you can make a coherent argument on "fair use" of copyrighted songs, you will be far less likely to be in this position to begin with.  Q: What is some good software to create module files? A: It's a matter of personal preference. Many people prefer OpenMPT because it works well with Windows. Others prefer to work with Schism Tracker. Finally, a few are still fond of Fast Tracker II, and therefore use the similar MilkyTracker. DOS-based trackers like IT and FT2 understandably need outside tools such as DOSBox to run as expected. If you don't mind pumping up your game's filesize, you could use any typical composition software (like FL Studio) and convert your wave to ogg format. A third alternative would be Reality Tracker. This tracker creates music based on the once-common OPL3 chip found in typical shareware-era DOS sound cards. MegaZeux now directly supports files made in this tracker. Q: How do I make WAV files? A: There are three easy ways to create WAV files. First, you get recording software and a mic. Set it all up (read the instructions if necessary) and go for it. Second, you can download them or get them from outside sources (such as The Freesound Project). Third, you can take existing files and change them with effects like echo. Converting .wav files intended for sound effects into OGG format is a worthwhile idea; the drop in file size compared to the drop in quality is huge. Q: Why do I get garbage when I try reading a file? A: You likely have it open for writing. To close a file, use the command SET "" to "FWRITE_OPEN". Q: Why does MegaZeux slow down significantly when I set the "commands" counter to a high value? A: You're likely using an idle loop without a CYCLE 1 or WAIT 1 command inserted. Find the offending loop and add one; if you're wary about possible delay effects, rest assured that adding either of these will not unnecessarily add delays. It will simply end a cycle. By default, MZX will warn you if you exceed 2000000 commands in a cycle (but only in test sessions). For further information, look up the Cycles and Board Scans section. Cycles and Board Scans - How MZX Processes Robots Q: I don't like that anyone can open up my game and see how it works, or that anyone can use the editor functions to cheat at my game. Is there an easy way to prevent people from opening my game in the editor? A: Nope. MegaZeux used to be able to protect worlds from being edited or even played without a password, but this feature has long since been removed. Releasing games in standalone form can possibly help. While anyone who has even cursory knowledge of MegaZeux can still fully look through a standalone game, people who have no knowledge of MegaZeux beforehand will lack the immediate means to heavily manipulate or look through your game. Q: I've seen that "certain renderers" are unable to display unbound sprites. What are renderers, what does this mean, and what should I be worried about? A: MegaZeux has several different video settings to accommodate a wide range of hardware. The engines used to provide video are called renderers, and can be set in the config file or changed on the fly in the F2 settings menu. Renderers range from basic support (software, does not utilize video hardware functions) to features-oriented (glsl, featuring customizable filters). Certain platforms and renderers cannot show extended graphics (in other words, unbound sprites and SMZX mode 3 custom indices). Right now, this is only a concern for very weak platforms that cannot handle much to begin with, such as the DS. Pretty much anyone running MegaZeux on an even remotely modern computer should be able to view extended graphics. (Besides the Nintendo DS, the other platforms and renderers currently unable are the GP2X and any use of the weak and obseleted "overlay2" renderer.) Q: I heard only certain graphics cards can properly show Super MZX mode games. Is this true? A: Not anymore. Any computer that can display normal games in MegaZeux can now display Super MZX mode games. Q: How can I get "mod *" as the default board mod? A: To set "mod *", use either Shift+8 or the asterisk (*) on the numpad. Q: What's with these "~roboclp.tmp" files packed with so many games? A: Those held clipboard information in DOS versions of MegaZeux. They are useless and can be freely deleted. Q: Why doesn't [ work for taking screenshots? A: It has been changed to F12 and now works in any area in MZX, including any part of the editor. Instead of PCX, it now currently outputs PNG files by default, but will output MS BMP format files on platforms unable to support PNG. Table of Contents

MegaZeux Limitations

MegaZeux has to impose a number of limitations to ensure worldfile compatibility with MZX 2.x worldfiles.

Memory Limitations

No single Robot can exceed 2 megabytes in size. No single sign or Scroll can exceed 64 kilobytes in size.

Quantity Limitations

Item: Largest number allowed: Robots 255 per board plus Global Robot Scrolls/Signs 255 per board Sensors 255 per board Sprites 256 per world Boards 250 per world Local Counters 32 per Robot plus specialized local counters (e.g. loopcount, lava_walk, bullettype)

Length Limitations

Robot Name Length 14 characters Board Name Length 24 characters String Length 4,194,304 characters (4 megabytes) Editor Line Length 241 characters (INCLUDING "extra" words) * Message Length 512 characters Input String Length 512 characters Macro Length 64 characters (for single-line macros) Mod Filename Length 512 characters (including subdirectories, if applicable)

Theoretical Limitations

Board size maximum is roughly 16.7 million characters ((2^24) - 1). Vlayer size maximum is roughly 16.7 million characters ((2^24) - 1). Board width or height maximum is 32767. The maximum number of counters and strings depends on the platform (e.g. between 32 or 64-bit) but is sufficiently large. You should be fine utilizing hundreds of thousands, or even millions. These limitations are mostly theoretical because of the utter improbability of meeting these limits and the amount of RAM (up to hundreds of gigabytes if fully utilized) they consume.

Other Limitations

Numbers less than -32768 or more than 32767 cannot be directly used in Robotic. This problem is a worldfile issue and can be circumvented by using a constant expression (parentheses). No board can have a width of a multiple of 256 chars because this corrupts the board if it lacks an overlay. This problem is a worldfile issue and widths set to a multiple of 256 will increased by one more horizontal character regardless of the status of the board's overlay. Expressions Table of Contents

The World Editor

Ready to start creating your own worlds? Then, let's get started! This section is a short editor tutorial. It will teach you the basics of creating your own worlds. To get into the editor, press N or F8 from the title screen. You will be asked to name a starting board: one can type an appropriate name and create a second starting board, or press Escape to cancel and remain on your new world's title screen. When this prompt is dealt with, you will be presented with a blank board with a small status bar at the bottom. You can use Alt+H to pop up a listing of key shortcuts at the bottom. PageUp and PageDown change its currently shown key shortcuts. The mouse also works to change pages (but not to select actions). Feel free to play around with these various options. Press Alt+R to restart and clear everything (you will be asked for confirmation, to make sure you really want to go through with it). (On Mac platforms, any key shortcut containing Alt can work with  replacing Alt. So, for above, +H would pop up the help listing, and +R would restart the world.) For your first world, you should start simple. The very first board in the board listings is the title board, so name that board after your game. (If you opted to create a starting board, you have to switch to the first board with the B key.) Press I for board info. This screen will display a bunch of options; there are loads of important options, but the most relevant option for now is the "Board name" option. Type in the name of your game and then click on "OK" or press Tab until OK is highlighted and press Enter. Now that the title board is named, its design begins... or is put aside for later (or even the end). If you made a starting board upon creating your world, simply press B to move to it. If you skipped making a starting board, you may need to create the first playable board, or location, of your game. Press A to add a board, then type in a short description of the board, such as "Starting Board". Press Enter to go to this new board. This board also needs to be set as the starting board. Press G to load the Global Settings screen. Once there, select the First Board option and set it to your starting board. Now you are free to doodle around. Use C to change the active color. Use F3 through F9 to bring up menus of items, terrains, and creatures. Selecting one with the arrows and Enter will allow you to place it using arrow keys and space. For example, press F3 for terrains, and select Line. (This is a form of wall.) Now move around, placing walls. To ease this, you can press Tab to toggle draw mode. When draw mode is active, every move of the cursor will place the current item/color. The current item and color is shown on the top line of the menu. Try to create a pleasing-looking screen, regardless of its planned function. Some items will require that you set settings to determine their behavior. To place the player's starting position, move the cursor to the destination, press F10, and select Player. Alternatively, press Enter while highlighting the Player and press Space on the desired destination. When you are done, press G to go to the Global Info screen. TAB to the Next button and press Enter. You will now be highlighting the option "First Board". Press Enter, and select the starting board (this is where gameplay starts... NOT the title board in the vast majority of cases) from the list and press Enter. Then TAB to OK and press Enter. You could now press Alt+N to select a module (music) file for the board, if you wish. Then press S to save the world, and type in a filename. (The extension of .MZX will automatically be added.) Press Enter to save the world. Press ESC to exit the editor, and now you can play your game! You can use L to reload your world in the editor to make changes, if necessary. See General Editing Tips for more advanced editing info. New in the 2.8+ line of MegaZeux is the protection of colors and characters the editor uses. The editor uses sets outside of the currently used sets to keep the editor GUI consistent. The character set for the editor is mzx_edit.chr; only edit if you want to change the editor's appearance. General Editing Tips Table of Contents

General Editing Tips

The following is a list of important editing tips. They assume you are familiar with MegaZeux's dialog box system, and that you can navigate the editor's menus.

Linking Boards

Simple, one-board games can get boring REALLY fast. There are five ways to move between boards. A simple method of connecting boards is with the Board Exits dialog, accessed by pressing X. Here, you can select boards that you will reach if the player moves off of the screen in a given direction. The destination board shouldn't have anything in the way, and will not automatically lead back - you must set the exit on that board too. This menu will not allow linking boards to the title board. The player will appear on the other board at the appropriate edge at the same position (if board sizes allow). For example, if the player triggers the north exit of a board while at its upper-left corner, it will appear in the lower-left corner of the destination board. If the player triggers a board exit and anything on the destination board is in the way of the player moving to the next board, the player replaces it upon entering the board (effectively destroying it). Another way is to use a Robot to teleport a player with the teleport player "boardname" X Y command. This assumes that you are familiar with using Robots, but is the only way to go to another board without having the player moved past a board edge, moving the player into a teleport, requiring the player to have been on the destination board earlier, or reloading the current world. Robots can also dynamically set board exits using the BOARD [dir] "boardname" command, including disabling exits by inputting NONE instead of the board name. TELEPORT PLAYER "string" # # BOARD [dir] "string" BOARD [dir] NONE The third way is to add stairs, caves and whirlpools using the Transport (F7) menu. After one is picked, you select a destination board. The destination board should contain a similar transport leading back. The two entrances will now lead to each other. The fourth way is by saving and restoring player positions using Robotic. The save player position # command will remember the current board and player position and save this info in the given slot #, and the restore player position # command returns the player to the saved position. The last way - the most kludge-like - is to load the current world with a 'swap world' command. This will send the player to the starting board of the current world, but will restore the world to its original state. Set counters and strings will be preserved. This method is used for its powerful restorative properties. To switch to other boards in the editor, use B. To add boards, press A, or press B and select (add board) from the board list.

Board Sizes

You can change the size and placement of a board's viewport with Alt+P. You can also choose to center the viewport; this will automatically set the viewport placement to display the center of the screen. You can also change the actual size of the board. The highest possible size is 16.7 million tiles, though a board that size would require unreasonably high RAM requirements (128MB). Note that reducing the size of a board will permanently destroy anything outside of the new limits.

Other Important Editing Keys

You can use Ins to "grab" the object beneath the cursor, or Enter to edit it and then grab it as well. Use P to modify the settings of the object in the buffer. Use Alt+N to select music for the current board, or turn the music off if it is already selected. Use Alt+Z to clear the current board entirely (you will be asked for confirmation). You can edit important Board Options with I, and important Global (world) Options with G. This is only a small selection of key shortcuts in the editor; the full reference is linked at the end of this article.

The Mouse in the Editor

The left mouse button acts like space: it places a copy of the current item over the mouse cursor. The right mouse button acts like insert: it grabs the current thing over the mouse cursor. Editing Keys and Options Reference Table of Contents

Editing Keys and Options Reference

The following is an alphabetical listing of keys within the World editor. This is followed by a detailed description of what each one does. On Mac platforms, any command that uses the Alt key can take  (the command key) instead. A - Add (board) B - Select Board C - Color D - Delete (board) F - Fill G - Global Info I - Info (board) L - Load M - Move Board P - Parameter S - Save V - View X - Exits - - Goto Previous Board + - Goto Next Board Alt+A - Select Char Set Alt+B - Block Alt+C - Char Edit Alt+D - Default Colors Alt+E - Palette Alt+F - Sound Effects Alt+G - Edit Global Robot Alt+H - Hotkey Toggle Alt+I - Import Alt+L - Test WAV Alt+M - Modify Alt+N - Music Alt+O - Edit Overlay Alt+P - Size/Pos Alt+R - Restart Alt+S - Status Info Alt+S - Show Level Alt+T - Test Alt+X - Export Alt+Y - Debug Window Alt+Z - Clear (Board) Alt+Number - Load Editor Position Ctrl+G - Goto Position Ctrl+N - Test Music Ctrl+Y - Redo Ctrl+Z - Undo Ctrl+Number - Save Editor Position Shift+8 OR Numpad * - Mod Wildcard Shift+Arrow - Goto Linked Board F1 - Help F2 - Text F3 - Terrain F4 - Item F5 - Creature F6 - Puzzle F7 - Transport F8 - Element F9 - Misc. (thing) F10 - Objects F11 - Select Screen Mode F12 - Take Screenshot Alt+F11 - Robotic Debugger Shift+F1 - Show InvisWalls Shift+F2 - Show Robots Shift+F3 - Show Fakes Shift+F4 - Show Spaces Arrow - Move Alt+Arrow - Move 10 BackSpace - Delete (Main Layer Only) Delete - Delete End - L/R Corner Enter - Modify+Grab [Board Mode] Enter - Character [Overlay Mode] Escape - Exit/Cancel Mode Home - U/L Corner Insert - Grab Spacebar - Place Tab - Draw PageDown - Next Menu PageUp - Previous Menu A - Add (Board) Press A to add another board to the current world. You will be asked for the name of the new board, and then a new board will be created. The settings for the new board will be the defaults. After adding a board, you will be moved to the new board. There is a limit of 250 unique boards per world. Alt+A - Select Char Set Press Alt+A and select one of the four different character sets. This will change the current character set to one of the four defaults. ASCII is the default EGA ASCII character set (code page 437). MegaZeux default is the default MegaZeux character set. Blank is the MegaZeux default, but with most graphical characters blank instead. Text, lines, arrows, blocks, and certain other symbols are not affected. SMZX set is the default character set for SMZX modes. B - Select Board Press B to change the current board by selecting from a list. Selecting (add board) will prompt the user to name the new board; once named, the board is created and becomes the current board. Alt+B - Block Press Alt+B to start block mode, then move the cursor to the opposite corner of a rectangular block and press Alt+B again. You can then select an action to perform upon the block. In all copy/move operations, the cursor marks the new UPPER LEFT corner. Copy block will allow you to duplicate the block by moving the cursor to a destination and pressing Enter. Copy block (repeated) will allow same as Copy block, but will allow copying the same block to multiple places. Move block will allow you to move the block to a new location. Clear block will erase the contents of the block. Flip block will flip the block upside down. Mirror block will flip the block left to right. Paint block will change the entire block to the current color. Copy to overlay will copy the block to the given spot of the overlay. Copy to vlayer will copy the block to the given spot of the vlayer. Save as ANSi/TXT will save the block as an ANSi or TXT file. Save as MZM will save the block as a board-type MZM file. Destinations for Move and Copy can overlap the original block safely. You can block copy to other boards by going to the desired board when prompted to pick the destination of the block; just press B and pick the desired board. Also, one can move the cursor across the width or height of the block by using Ctrl+Dir. This is very helpful for tiling blocks using the repeated copy function. C - Color Press C to select a new current color from a menu. The thing under the cursor is not affected. One can jump to a color by typing its hex code in the color menu; for example, typing "0D" would jump to color 013 (background color 0, foreground color D). A quirk to keep in mind: any entity with a background color of 0 will display the background color of anything beneath it. Alt+C - Char Edit Press Alt+C to edit the character set. The character editor is a separate section of the world editor and is discussed in another section. The Character Editor D - Delete (board) Press D to select a board from a list to be deleted. You cannot delete the first board (the title board). A deleted board will be pruned out, with the next actual board taking its place. A deleted board cannot be recovered or undone, so make sure this is the desired action. Alt+D - Default Colors Press Alt+D to toggle forcing default colors for placing built-ins (defaults to on). Turning this off causes built-ins to be placed with the colors of the object held in the buffer. The buffer object listed in the status bar will have a red dot at the end when default colors are off. Only some types of built-ins, such as creatures and items, have default colors. Alt+E - Palette Press Alt+E to edit the palette (colors). The palette editor is a separate section of the world editor and is discussed in another section. The Palette Editor F - Fill Press F to fill in an enclosed area with the current thing and color. The area must be completely surrounded by things other than the thing beneath the cursor. For example, you can fill over a solid square of Fakes with something else. The current fill command may not work accurately for very large and complex areas - in this case, you must move to the unfilled areas and press F to continue filling. This happens very rarely, however. Also, beware of trying to fill an area with an item with limited placements, such as a Robot. Alt+F - Sound Effects Press Alt+F to enter the sound effects editor. This editor affects all triggered sounds resulting from built-in actions, such as getting hit and shooting. First you must decide whether to use the default set of sound effects, or whether to edit your own. You can't edit the default set. If you edit your own, you will be in a series of editing screens. Use the Next and Previous buttons to move between screens. Sound effects, and the format used to represent them, are described in detail in another section. The format is the same as used for the Robotic command PLAY. (Like with PLAY, digitized sounds are allowed here.) Press F3 in the sound effects editor to rename the current sound slot. Slot names are limited to 9 characters in length. NOTE: Although this editor currently allows editing only the first 100 sound effects, a world can have as many as 256. Worlds can also have effects up to 255 characters long. Use the CHANGE SFX # "string" command to edit higher-numbered/longer custom sound effects. MegaZeux's Sound System Alt+G - Edit Global Robot Alt+G will start editing the Global Robot, starting at its name field. Ctrl+G - Goto Position Ctrl+G will pop up a window, displaying target x,y coordinates. Set the coordinates by either typing in or selecting the desired X and Y values, and select OK to go to those coordinates on the current board. Choosing Cancel or pressing Escape cancels. G - Global Info Press G to enter the global info dialog boxes. The global info options are covered in another section. Global Info Options Alt+H - Hotkey Toggle Press Alt+H to toggle display of the hotkeys and horizontal border. The default state of the hotkeys can be changed in the config file. The Config File I - Info (board) Press I to enter the board info dialog box. The board info options are covered in another section. Board Info Options Alt+I - Import Alt+I allows you to import a number of different file types into the current board or world. You can import a board file (.MZB) unique to MegaZeux. You can import a character set file (.CHR). You can import another world (.MZX), which is appended to the end of the list of boards. The global of the imported world will be ignored. (Unlike old versions of MegaZeux, all exits in an imported world will work.) You can import a palette (.PAL) file (including a palette indices (.PALIDX) file in SMZX mode 3) or a sound effects (.SFX) file, all unique to MegaZeux. Finally, you can import an MZM or ANSI/TXT file and place it at a given position. Importing boards or worlds will clear the board and overlay undo histories. L - Load L brings up a list of worlds in the current directory and allows you to select one to load. You will be warned if the current world as-is has not been saved yet. Alt+L - Test WAV Alt+L brings up a list of WAV/SAM/OGG files in the current directory. Selecting one will play it once at its natural frequency. This has no effect on the actual board or world. M - Move Board M moves the current board to the desired place on the board list. The title board cannot be moved, and other boards cannot be moved to the title board position. Alt+M - Modify Alt+M allows you to modify the settings of the thing under the cursor without changing the item in the buffer. Alt+N - Music Alt+N brings up a list of module files in the current directory. Selecting one will select it as the default music for the current board. If music is already playing, Alt+N will turn it off. Ctrl+N - Test Music Ctrl+N does the same as Alt+N, except it only plays the selected module. It does not set the board module to the selected module. It also remembers the last-used directory to maintain a current listening directory. A tested module will continue to play even if the current board is set to play music, and even if the current world file is changed. Alt+O - Edit Overlay Alt+O enters overlay editing mode. The overlay is on normal overlay mode by default. The overlay editing mode is similar to the normal editing mode, except that only certain keys are active, and the Enter and Alt+S keys have new purposes. The overlay is explained in further detail in another section. Editing and Using the Overlay P - Parameter P allows you to change the settings of the current object in the buffer. The object under the cursor is not affected. Alt+P - Size/Pos Alt+P allows you to change the size of the current board, the viewport size, and location. See the linked section for details. This action will clear the board and overlay undo histories. Board Sizes Alt+R - Restart Alt+R will clear the entire world. You will be asked for confirmation. All undo histories will also be cleared. S - Save S will prompt you for a filename, then save the current world as a MZX file. The save option will be highlighted if the world has changed since the last save or load. Alt+S - Status Info Alt+S will allow you to type in six different counters that can be shown on the default status screen within the game. This allows you to easily display your own items that the player can collect, and see how many are currently held. These counters can be up to 14 characters in length. Counters are discussed in further detail with Robots. Any status counter with a value of 0 will not be shown, and unseen counters will not change the position of the others. Alt+S - Show Level Alt+S while editing the overlay will toggle whether the level beneath the overlay is shown in overlay editing mode (defaults to YES). Editing and Using the Overlay Alt+T - Test Alt+T will allow you to test the current world, starting on the current board. Games CAN be loaded and saved in this mode, making it especially helpful for debugging. Test mode also enables several debugging tools and cheats that can be used during a test session. Quitting will return to the editor. Note that entering a test session will clear all editor undo histories. Debug Modes V - View V will allow you to see the current board as it would appear in the game. Use the arrows to Scroll the view, and ESC to return to the editor. X - Exits X will bring up a menu where you can select exits for each board direction. For example, selecting a destination board of "City" for north will cause the player to go to that board when pressing against the north edge of the current board. Boards are not automatically back-linked - to make "City" lead back here, you must go to that board and make a south exit back. Make sure the linked boards don't obstruct each other's exits, and that their linking boundaries are of the same size. Alt+X - Export Alt+X will allow you to export a number of different file types. You can export a board file (MZB) unique to MegaZeux, good for giving single boards to others. (The character set, palette, vlayer and global info aren't included!) You can export the character set (CHR) for later game use or to edit in Fontutil or another external app, or export a partial portion of the current set instead. You can export palettes (PAL) [regular mode or SMZX] and sound effect settings (SFX) for transportation. Both are file formats unique to MegaZeux. You can export the current world, but using the last version's world format, with the "Downver. world (MZX)" option. Finally, you can export a PNG-format image of the current board/overlay (when in board/overlay edit modes) or the vlayer (when in vlayer edit mode); this option will launch a progress bar, and can be aborted by pressing the Escape key while exporting. Files like MZMs and SAVs can be exported in-game by Robotic code. See their respective areas for details. Other file types such as character sets can be exported generically through file writing facilities and charset counters. SMZX indices (PALIDX) can be exported using the Export Palette (PAL) option in SMZX mode 3; its export dialogue will appear after the palette export dialogue. Alt+Y - Debug Window Alt+Y will toggle a red box in the lower corner of the screen. This box shows (on labeled lines) the current position of the cursor, the current Robot memory situation, and the presently playing module, and lists the MZX version of the current world at the top. This is the same as pressing F6 in-game, but removes the key_code and key_pressed info. Alt+Z - Clear (board) Alt+Z will clear the current board entirely. You will be asked for confirmation. Clearing the board will clear the board undo history as well. Ctrl+Z - Undo Ctrl+Y - Redo Ctrl+Z will undo an action; Ctrl+Y will redo any previously undone action. Action depth is determined by config file settings, with 100 as default. Ctrl+Number - Save Editor Position Alt+Number - Load Editor Position These save and load up to 10 cursor positions in the editor (0 through 9). These positions save both current board coordinates and active board, so one can save position on one board and load position from another board. These positions are saved for that world in its .editor.cnf file. Shift+8 OR Numpad * - Mod Wildcard This sets the board's current mod to play whatever played in the last-visited board. (i.e. The mod playing on that board differs if entering that board from a board using different music; it does not stick with the first such mod and play that from then on.) Shift+Arrow - Goto Linked Board This goes to the board linked in the given direction, if it exists. For example, pressing shift+up would go to the board linked to the North exit, provided there is a board linked to that exit. - - Goto Previous Board This moves the editor to the previous board in the board list, if it exists. + - Goto Next Board This moves the editor to the next board in the board list, if it exists. F1 - Help F1 will bring up context-relevant help. You can press F1 at almost any time. F2 - Text F2 will toggle text mode on and off. When text mode is on, Enter will go to the next line, and Backspace will delete the character under the cursor and move the cursor one position to the left. All printable characters will type in as text, including pressing the Spacebar. F3 - Terrain F4 - Item F5 - Creature F6 - Puzzle F7 - Transport F8 - Element F9 - Misc. (thing) F10 - Objects The above eight keys will bring up a menu of things to select from. Selecting one will ask you to enter settings (if appropriate) or choose a character for that thing. Then a copy of that thing will be placed at the cursor's location, and will also become the current object in the buffer. Scrolls, Signs, Sensors, Robots, and Pushable Robots (all in the Objects menu) will be discussed in another section. The current thing, color, and settings parameter (p##) is shown in the upper-right corner of the editor menu. Knowing the settings parameter isn't important except for certain Robotic programming situations. Signs and Scrolls in the Editor Sensors - What They Are and How to Use Them Robots - What They Are and How to Use Them Robotic Tutorial Robotic Reference Manual F11 - Select Screen Mode Pressing F11 will open a menu, allowing the user to select an MZX display mode (normal mode and Super MZX modes 1-3). This setting will persist in editor tests until overridden in-game; if editor tests are left while in a different SMZX mode, it will be reverted to the setting given here upon returning to the editor. Setting the screen mode is a prerequisite for editing Super MZX palettes and character sets. Super MZX Modes F12 - Take Screenshot Pressing F12 will make a 640x350 screenshot (in PNG format by default) in the working directory, using the software renderer. The file naming starts from "screen0". This may be disabled by changing the allow_screenshots setting in the config file. Alt+F11 - Robotic Debugger Alt plus F11 will launch the configuration screen for the Robotic Debugger. For more information on the Robotic Debugger, go to its relevant section. Debug Modes - The Robotic Debugger Shift+F1 - Show InvisWalls Shift+F2 - Show Robots Shift+F3 - Show Fakes Shift+F4 - Show Spaces These four keys will cause the given things onscreen to flash. Robots flash as the exclamation point character, char #33; fakes as the pound character; spaces flash between the O and * characters; inviswalls between the carpet/floor characters. They are good for locating "hidden" or camouflaged Robots, passages, and the like. Arrow - Move The arrow keys will move the cursor. The edit window will scroll when necessary. Alt+Arrow - Move 10 Alt plus the arrow keys will move the cursor ten spaces at a time, or up to the board's edge if under ten spaces away. These also jump numbers by 10 in dialog boxes. BackSpace - Delete (Main Layer Only) Del - Delete The Del key will delete everything under the cursor, while BackSpace will delete the object on the main layer and move any object on the under layer to the main layer. The current thing is not affected. End - L/R Corner End will jump the cursor to the lower-right corner of the entire board. Enter - Modify+Grab [Board Mode] Enter will modify the settings of the thing under the cursor, if applicable, then select that thing as the current thing. It is just like pressing Alt+M and then Ins. Enter - Character [Overlay Mode] Enter during Overlay editing mode will change the current character. Select it from a menu and then press Enter to confirm your choice. ESC - Exit/Cancel Mode ESC will exit the editor, asking for confirmation if your world has not been saved. If you are in block, overlay, text, or draw mode, ESC will instead cancel the current mode and return to normal editing. Home - U/L Corner Home will jump the cursor to the upper-left corner of the entire board. Ins - Grab Ins will select the thing under the cursor as the current thing. The thing under the cursor is not affected. Spacebar - Place Spacebar will copy the current thing to the location under the cursor. Trying to place something over a similar thing will instead replace the object under the cursor by default. (Robots and Pushable Robots are the exception; they will never be replaced.) Placing something over a floor type will actually place it OVER the floor, not replace the floor. Other things will be deleted if they are in the way. Spacebar can also replace similar objects under the cursor with a space; this can be set in the configuration file. The Config File Tab - Draw Tab will toggle the current draw mode. When drawing is on, you will place a copy of the current object in the buffer every time you move the cursor. PageDown - Next Menu PageUp - Previous Menu These two keys will cycle through the pages of the editor menu. The menu bar can wrap around. You do not have to be viewing the page listing a specific option before you can use that option - the menus are purely for reference. These keys also jump numbers by 100 in dialog boxes. The World Editor General Editing Tips Table of Contents

The Character Editor

The character editor is an important part of MegaZeux. With it, you can change the appearance of character sets. For example, one can make bricks, rockets, stones, and demons; using multiple characters, one can make much grander things. The default pixel resolution is fair - 8x14 per character for a total of 640x350 for the entire screen. Each character has a foreground color (for "on" pixels) and a background color (for "off" pixels). Other modes, known as Super MZX modes, increase color amount to four at a cost of lowering per-character resolution to 4x14, but the intricacies of character editing in those modes are best covered in that mode's section. To use the character editor, press Alt+C in the editor. You will be shown a zoomed version of the current character, a list of keyboard shortcuts, and a row of characters. The current character(s) being edited are displayed on the left edge of the character bar, and also highlighted and shown in relative position in the middle of the bar. To edit the character(s), move the cursor with the keys and use Spacebar to toggle pixels on and off (or left-click and right-click, respectively). Use + and - to move one character (or character block) up or down through the character set. Use Enter to select the current character (or block) from the entire set. When selecting from the entire set, one can move by one character using the arrows, or by one block using the -/+ keys. Use Del to clear the character. Use N to make a "negative", or inverse, of the character, turning all on pixels off and all off pixels on. Use Alt with the arrow keys to shift the entire character to one direction. Pixels shifted off of one edge wrap around to the other edge. Use M to mirror the character, flipping it left to right. Use F to flip the character top to bottom. Hold Shift to select multiple pixels at a time. The selection box will vanish once Shift is released. Alt+B will also create a similar selection box, but will not vanish until the Escape key is pressed. F2 will copy the current character to an internal buffer, while F3 will paste the buffer contents to the current character space. The buffer can contain a selection of pixels instead of a character by pressing F2 when selecting a group of pixels. When copying a single character and pasting to another single character, the new content simply replaces the old; in other circumstances, the new content is placed starting with the cursor position as its upper-left corner with no wraparound. The buffer is retained between uses of the character editor. Ctrl+Z will undo actions done in the editor (up to the limit defined in the config file). Keep in mind that the current frame is counted in the amount of undo actions. Ctrl+Y will redo any undone actions. C will allow selection of colors used in the char editor. This can be helpful in crafting characters for a specific palette. Use Alt+C to switch colors back to the default. Alt+F will flood fill any highlighted area. Tab will toggle mode (set) on and off. (set) mode will turn all pixels crossed to ON. Shift+Tab will toggle (clear) mode. (clear) mode will turn all pixels crossed OFF. F4 will revert the current character to its EGA ASCII (code page 437) appearance; F5 will revert the current character to its default MZX appearance. Multiple characters can be edited at one time. To select a group of characters, press Enter in the character editor, hold Shift on the upper-left corner of your desired block of characters to edit, and finally highlight your block of characters, release Shift, and press Enter. If more than one viable character space can be made from the selected characters, the user can choose the desired space size (e.g. six characters can be a 3x2, a 2x3 or a 6x1 space). The largest character space one can use for editing is 18 characters large (6x3, the max allowed sizes for the respective dimensions). The extra character sets accessible by unbound sprites can also be edited in the character editor. Press PgUp and PgDown to switch character sets, either on the main character edit screen or on the character selection menu. Alt+I will import character sets while in the character editor; Alt+X will export. This can be done with one full set, multiple sets, or groups of partials. For a full set, simply select the desired set and click OK. For saving multiple sets or a series of partials, first insert a hash sign in the set name then choose the Offset (starting character). Next, choose the First number of the series (e.g. char#.chr with a First value of 5 would start from char5.chr). Then, put the Size of each set (up to 256 chars, or a full set). Finally, choose the Count value to indicate how many sets will be saved. Loading is simpler: simply choose the starting character set, the Offset value and the Count value. If multiple characters are being worked on at once, importing and exporting partials can be set to tile (which will base export and import positions on the current character grouping) or linear (which will be based on sequential places in the char set). The character editor is a key element in creating decent games with MegaZeux. If you can't seem to draw well with it, that's okay, since it has some limitations. You can keep practicing at it, or you can get an MZXer friend to draw characters for you. The character editor changes somewhat in Super MZX modes - go to the Super MZX Modes section for more information on this. Super MZX Modes Editing Keys and Options Reference Table of Contents

The Palette Editor

MegaZeux is not limited to the colors it sets as default. The built-in palette editor can modify colors, which is very helpful in designing a game. It allows you to change the appearance of the currently-available colors, and is more user-friendly than having to change values through code. MegaZeux worlds can only have one active palette at a time, but can load different palettes as frequently as desired, so MegaZeux designers can create different palettes that fit different parts of their game. To use the palette editor, press Alt+E while in the MegaZeux editor. The palette editing screen will appear. The current palette will be shown to the left, with the current color marked. By default, the RGB values of the current color and the current color creation mode are shown to the right of the visible palette, and the menu is shown below. The color currently stored in the buffer is shown in the bottom-right corner. Some color theory is in order. Computer monitors display colors by projecting various amounts of Red, Green, and Blue light. Combined, these three colors can produce almost any shade and hue of color. This is one way colors are represented in MegaZeux as well. In the RGB color model (the default), each color has a Red, Green, and Blue value, each ranging from 0 to 63. 0 is "off" while 63 is "full intensity". To make colors other than red, green, and blue, you must mix them. Purple is red plus blue, cyan is green plus blue, and yellow is red plus green. (Really.) Whites and grays are made from equal amounts of all three. For example, Red at 42, Blue at 42 and Green at 0 would be a deep purple, and all as 20 would be a dark gray. Orange is made with full red, green set to 31 and blue zeroed out. To brighten a color, raise all the numbers, or lower them to darken it. For the RGB color model, use the arrow keys to select the current color. R, G, B, and A will respectively increase Red, Green, Blue, and All, while Alt+R, Alt+G,Alt+B and Alt+A will respectively decrease the values. Several functions are consistent across all color models. Alt+D will reset the palette to its default colors (you will NOT be asked for confirmation). 0 will blacken the current color. Alt+H will toggle the shortcut display. The PgUp and PgDn keys select the current color model. Alt+I will import a palette; Alt+X will export the current palette. Tab will switch to and from a scratchpad palette that will only exist for the editor session. Finally, F2 will store the current color to an internal buffer, while F3 will paste the buffered color to the current color. In addition to the keyboard shortcuts listed in the below menu, users can click colors in the palette to select them. Users can also use the mouse to change color values by clicking on the relevant areas, and hold down the mouse button to act as a slider. Color values can also be clicked on and then typed in directly. If one is more familiar with other color models, MegaZeux can create colors with two alternate models: HSL and CIELAB. HSL creates colors by setting hue (base color), saturation (color strength) and lightness (brightness relative to white). Hue can take values of 0-360; saturation and lightness take values of 0-100. The keyboard shortcuts in this mode are C, S and V for increasing Hue, Saturation, and Luminance, respectively, while alt key combinations of these keys reduce these values. CIELAB creates colors through a combination of lightness (L*) and color values represented by the opponent pair colors of red-green (a*) and yellow-blue (b*). L* values range from 0-100, and opponent color values can range from -128 (fully one color of the pair) to +128 (fully the other color). The keyboard shortcuts in this mode are V, A and B for increasing L*, a* and b*, respectively, while alt key combinations of these keys reduce these values.

The Palette Editor in Super MZX Modes

Super MZX Modes allow 256 colors at once, and have their own quirks; therefore, the palette editor changes considerably to accommodate them. The palette editor for each SMZX mode is noted below.

Super MZX Mode 1 Palette Editor

Super MZX Mode 1 does not require any changes, since it merely interpolates colors. Therefore, palette editing in this mode acts the exact same as it does in normal MZX mode.

Super MZX Mode 2 Palette Editor

Super MZX Mode 2's color selection is shown as a 16x16 set of colors. Each color also represents the four-color palette (also known as a subpalette) used when an item is assigned that color. The palette number, as well as its hex number and the four colors that comprise it, are shown in the upper-left corner. By default, the color selector shows the current color/palette highlighted by a white box, with red boxes showing the other colors of the palette. The buffer stores only subpalettes in this mode, cycling through each color of the subpalette. The base values of the current color and the current color creation mode are shown in the upper-right, and the help menu is shown below. On top of the functions allowed in the normal palette editor, SMZX Mode 2 adds these hotkeys: F5: Store Colors. Stores the currently-highlighted subpalette into the buffer. F6: Place Colors. Replaces the highlighted subpalette with the subpalette colors currently in the buffer. Insert: Cursors. Turns the display of the red boxes highlighting the component colors of the given subpalette on or off. Defaults to (on).

Super MZX Mode 3 Palette Editor

Super MZX Mode 3's color selection is shown as a 16x16 set of colors. The palette number, as well as its hex number and the four colors that comprise it, are shown in the upper-left corner. Since Mode 3 allows user-defined indices, the buffer display now also includes the currently-stored indices just to the left of the stored subpalette. The base values of the current color and the current color creation mode are shown in the upper-right, and the help menu is shown below. In this mode, the highlighted color only corresponds to a color, NOT to a subpalette; therefore, one can be editing a different color and subpalette at the same time, and changing highlighted color will NOT change the current subpalette. To change the current subpalette, press Space or click the middle mouse button, and then choose the subpalette to edit. Each color can be assigned to a color slot in the current subpalette; to place a color in a subpalette slot, press 1-4 to put the current color in the corresponding slot (for example, pressing 2 while on color #120 would make the second color of the current subpalette color #120). The Import and Export commands can also handle indices files in this mode. On top of the functions allowed in the SMZX Mode 2 palette editor, SMZX Mode 3 adds these hotkeys: F7: Store Indices. Puts the current indices into the buffer. F8: Place Indices. Assigns the current subpalette the indices currently in the buffer. With the exception of hiding the help, all functions available to the palette editor in normal MZX mode are available in the SMZX mode 3 editor. Editing Keys and Options Reference Super MZX Modes Table of Contents

Global Info Options

To edit the Global Info options, press G within the editor. Here you can edit options that affect the entire world. The first dialog you see has the following options:

First Board

Here is where you select which board will be the starting board for the game. The player will start on this board. This defaults to the second board in the list, or to the title board if a second board was not made when creating a new world.

Edging Color

This is the color of the area outside of the viewport. It defaults to dark gray on black (c08).

Starting/Maximum Lives

This is where you set the number of lives the player starts with, and how many lives the player can have at any one time.

Starting/Maximum Health

Same as above, but for health points.

Enemies' Bullets Hurt Other Enemies

If this is on, then bullets shot by enemies, such as tigers, will destroy other enemies that they hit. It basically turns all Enemy bullets fired into Neutral bullets (including ones shot by Robots).

Clear Messages and Projectiles on Exit

If this is on, the current message and all projectiles (stars, bullets, missiles, shooting fire) are cleared whenever the player leaves the screen.

Can Only Play World from a 'SWAP WORLD'

If this is on, then the current world is unplayable in a normal fashion. The only ways to play it are by swapping to it from another world with the Robotic command SWAP WORLD, or by testing it in the editor.

More

This button leads to another screen of settings.

Edit Chars

This button leads to a series of dialogs where you can edit the characters and colors used to represent various internal things. When editing chars, selecting char 255 for an object will make that object type act like a Custom object, which means the char displayed is based on the object's current parameter.

Edit Dmg

This button leads to a dialog where you can edit the amount of damage done by various internal things. Valid numbers range from 0 to 255.

Edit Global Robot

This button allows you to edit the global Robot, which is a very special Robot that is present at all times, although it is not physically on every board. It is a very important part of MegaZeux. See the section on The Global for more information. The Global Robotic Reference Manual The More page of settings for global info has the following options:

Death Board/Death X/Death Y/Mode

This tells MegaZeux what happens when the player dies. If the mode is Same Position, then the player will simply lose a life. If it is Restart Board, then the player will also teleport to the location on the board where the player entered. If it is Teleport, the player will instead teleport to the board and x,y coordinates stated in the above three settings.

Endgame Board/Endgame X/Endgame Y/Mode

This tells MegaZeux what happens when the player runs out of lives. If the mode is Game Over, then the game will simply end. If it is Teleport, the player will be given one life and one health, and then will be teleported to the board and x,y coordinates stated in the above three settings. This will continue to happen every time the player runs out of lives or when a Robot calls the ENDGAME command.

Play Game Over SFX

If this option is on, the game over sound effect will be looped when the game has ended and the Game Over message will flash along the bottom of the screen. The Game Over SFX will not play when the endgame teleport option is chosen.

Previous

This will go to the previous global settings dialog. The character editing dialogs (eight pages in total) are screens of characters and colors used to represent internal things. Select one to change the color or character used. Use Next and Previous to move between the screens, and Done when you are finished. Lit Bomb Anim 1 is special; setting it will set the other 6 frames of Lit Bomb Animation to the succeeding characters. Setting the char of any thing to 255 (always represented by a magenta question mark in the char select) will allow that object type to act like a Custom object. This means that the character it displays will correspond to the object's parameter (so, for instance, an object with this set and with a parameter of p0a will display character 10). This is best-suited for things that do not otherwise use the parameter field, but will work with objects that have meaningful parameters as well. Any object type with its char set to 255 that did not previously use the parameter field (such as Trees) will also prompt a character selection screen when initially placed in the editor, much like what happens when selecting a Custom object. Other objects are placed normally. The damage editing dialog allows you to change the amount of damage dealt by various things within the game. Select one and use the usual dialog keys to change the values, which can range from 0 to 255. 0 will leave the player invincible versus that thing, but pain sounds and messages will still be triggered. Editing the global Robot is covered in the Robot tutorials, as it is (mostly) the same as editing any other Robot. The actual use of a global Robot is covered in its own section. The Global Robotic Reference Manual Editing Keys and Options Reference Table of Contents

Board Info Options

To edit Board options, press I within the editor. This will bring up a dialog where you can edit options pertaining to the current board. The options are as follows:

Board Name

This is the name of the board. It is mainly for internal reference; however, the name of the first board (the title screen) is also used to represent the entire world on a file listing, and its value can be accessed through the BOARD_NAME string counter in Robotic. The special color codes ~ and @ can apply here, allowing colored text in board names.

Can Shoot/Bomb

These options determine whether or not the player can shoot or bomb normally. If off, then the player cannot perform the noted action. (Other ways of doing these actions in Robotic may replace the default ways of shooting/bombing and are unimpeded by this setting.)

Fire Burns Space/Fakes/Trees/Brown

These options determine what fire will and will not burn through. Space is empty space, NOT floors; Fakes include fakes, floors, carpets, and tiles. Trees is self-explanatory. Brown is anything other than the player or a Robot/sign/Scroll that is colored brown (that is, anything with a color of cX6).

Forest to Floor

If on, when the player moves through forest, it will become Floor. If off, the forest will simply be replaced by a space.

Collect Bombs

If on, the player will collect bombs normally. If off, bombs will be instantly lit when touched instead.

Fire Burns Forever

If on, fire will never burn out. If off, fire will eventually turn into ash, which is actually a dark gray (c08) Floor. Of course, if fire is set to burn fakes, the ash will probably re-light immediately.

Dragons Move Randomly

If on, dragons that move have a 1/8 chance of moving randomly each time they move instead of always seeking the player.

Restart if Hurt

When on, the player will be teleported to the place on the current board that it originally entered every time health is lost.

Reset Board on Entry

When on, every time the board is entered, the board will reset, acting as if the player is entering the board for the first time.

Player Locked N/S

When on, the player cannot directly move north or south until unlocked with the UNLOCKPLAYER command. (Other ways of moving the player in those directions, such as Robotic or the player being pushed, are unimpeded by this setting.)

Player Locked E/W

When on, the player cannot directly move east or west until unlocked with the UNLOCKPLAYER command. (Other ways of moving the player in those directions, such as Robotic or the player being pushed, are unimpeded by this setting.)

Player Attack Locked

When on, the player cannot shoot bullets or lay bombs until unlocked with the UNLOCKPLAYER command. (Other ways of doing these actions, in Robotic, are unimpeded by this setting.)

Time Limit

If greater than zero, the player has the noted amount of time to complete the board. The current time is shown in the lower left corner during gameplay. If time runs out, the player loses ten health and the time limit is reset. This option is most useful with the "Restart if Hurt" option. The countdown speed varies based on the MZX speed, ticking every other cycle; test the board to get a feel for the amount of time needed. The current time is reset if the player exits and re-enters the board.

Explosions to Space/Ash/Fire

This determines what explosions will leave in their wake: Empty space, ash (dark gray floors - in other words, floors colored c08), or burning fire.

Can Save/Can't Save/Can Save on Sensors

This determines when the player can save the game. The first two options are self-explanatory. Can Save on Sensors allows the player to only save if it is standing directly over a Sensor. Sensors are explained in another section. This only prevents or limits saving using the built-in save functions; saving done with Robotic is unaffected. Sensors - What They Are and How to Use Them

No/Normal/Static/Transparent Overlay

This sets the type of overlay for the current board. No Overlay means just that - overlay mode is completely off. Normal Overlay is an overlay that scrolls with the board. Static Overlay is an overlay that remains in a fixed position even when the board scrolls. A Transparent Overlay is similar to no overlay in that none is shown, but it allows you to edit it so that it may appear later. Overlays are discussed in full in another section. Editing and Using the Overlay

Load Charset on Entry

This can be set to load a specific charset every time the board is entered, or set to do nothing.

Load Palette on Entry

This can be set to load a specific palette every time the board is entered, or set to do nothing.

Reset/Load When Entering from the Same Board

If this option is set, all transitions from this board to itself will trigger charset/palette reloads. If "Reset board on entry" is concurrently set, all transitions from this board to itself will also reset the board. One can set the current board's settings as the default settings for all new boards made for this world file. Select the "Set as defaults" button at the bottom and click or press Space/Enter. This will save a .cnf file for the current world. There will be no confirmation. Since the .cnf is named after the current world, the current world must have been saved first. Editing Keys and Options Reference Table of Contents

MegaZeux's Sound System

MegaZeux has two types of sound: Digitized sound, played through a sound card, and sound effects, which are emulated PC Speaker effects. MegaZeux allows OGG, WAV, SAM (a legacy sound format), and module files (that is, music files) for digitized sound. MegaZeux's many sound options can be accessed through the config.txt file. Please see this section for details. The Config File

Music Files

Music files, referred to as MODULES, can be any one of the following formats: * OGG * MOD (or NST/WOW/OCT) * S3M * XM * IT * GDM * RAD * Other formats {STM, MTM, 669, ULT, FAR, MED, OKT, AMF} * Several other formats are in ModPlug or XMP, but are not supported in MZX. The default module engine is XMP. It is still possible to build using ModPlug, and possible to build using MikMod to support platforms that cannot handle anything else. OGGs, WAVs and RADs are handled outside of the module engines, while GDMs load natively in XMP/MikMod, but not in ModPlug. When a GDM is loaded with ModPlug as the music engine, it is converted to an S3M file. The S3M file is then loaded in all future incidences. Formats common to all engines are MOD, S3M, XM, IT, STM, MTM, 669, ULT, FAR, MED, OKT and AMF. All other formats (excluding WAV/OGG/SAM/GDM/RAD) are locked out of MZX by default. MED support is the most inconsistent between module engines, due to its multiple subversions and the engines' varying accuracy on dealing with them, so use of this format is not generally advised. MZX supports loop markers for OGG files. OGG loops are supported with the LOOPSTART, LOOPLENGTH and LOOPEND metadata tags. MZX can also control OGG looping dynamically with the MOD_LOOPSTART and MOD_LOOPEND counters.

Using Sound and Music in Your Own Games

There are three ways to utilize sound and music in your own games: 1- Select the default modules for each board (or mod *). 2- Edit the built-in speaker sfx tables. 3- Use Robots to play modules, SAMs/WAVs/OGGs, and speaker sfx.

Selecting Default Modules for Each Board

This is perhaps the easiest method to get music in your games. Simply make sure that the proper module files are in the current directory, or in a subdirectory of the current directory, and use Alt+N to select music for a board. Press Alt+N to turn it back off again. To set it to play the same music as the last board (mod *), press Shift+8 or the numpad's asterisk key. Details on Alt+N

Editing the Built-in Speaker SFX

To edit the built-in speaker sound effect tables, use Alt+F. The format for them is discussed later in this section. Details on Alt+F

Using Robots

Robotic has a large number of commands for playing modules, SAMs/WAVs/OGGs, and speaker sfx. A knowledge of Robotic basics is required, so see the following sections to learn about Robots. Robots - What They Are and How to Use Them Robotic Tutorial Robotic Reference Manual The following sections discuss individual commands relating to sound and music. CHANGE SFX # "string" END MOD END SAM END PLAY JUMP MOD ORDER # MOD "file" MOD FADE IN "file" MOD FADE OUT MOD FADE # # MOD SAM # # PLAY "string" PLAY SFX "string" SAM # "file" SFX # VOLUME # WAIT MOD FADE WAIT PLAY WAIT PLAY "string"

SAM File Support

SAM files, formerly the only format for playing sounds in MZX, are directly supported. However, using OGGs or WAVs as the original source, if possible, is preferred as SAMs are low quality (~8KHz mono) compared to typical WAV and OGG quality settings. SAM support is mostly kept in for supporting older games, not for current usage in designing games.

Format for Sound Effects

The sound effects editor and Robotic PLAY commands all use the same format for playing sound effects. The format consists of a single string of characters, each character representing one note or command. Spaces are ignored, and capitalization is not important. Some knowledge of music is required to use the format effectively. The commands are: A B C D E F G Plays the note stated, at the current octave and duration. The scale starts at C and continues DEFGAB before going up an octave. Use # and $ for sharps and flats, placing them after the note. # $ Sharps (#) or flats ($) the previous note. This does not affect any note other than the note directly before the sharp or flat. Constructs such as B# are allowed. 0 1 2 3 4 5 6 Sets the current octave. MZX octaves are shifted a number back resulting in octave 3 starting at middle C (aka c'). The lower the number, the lower the notes. + - Raises or lowers the current octave by 1, but only if possible. You cannot go below octave 0 or above octave 6. X Plays a rest of the current duration. A rest is a period of silence. Z T S I Q H W These letters change the current duration of notes and rests, I.E. the length of time each subsequent note is played. Each one is twice as long as the previous one, with Z being the fastest and W the slowest. Duration defaults to T. The counterparts to the durations follow: Z = sixty-fourth note T = T hirty-second note S = S ixteenth note I = eI ghth note Q = Q uarter note H = H alf note W = W hole note Duration (and octave) does not carry over from one string to the next. . A dot will change the current duration to 150% that of usual. This is a permanent duration change and will only affect subsequent notes. Its use is similar to that of a dot in regular music, except that this dot affects multiple notes. ! An exclamation point will change the current duration to 33% that of usual. This is a permanent duration change and will only affect subsequent notes. Its use is similar to that of triplets in regular music, except it affects ALL subsequent notes. & & is a very special command. It is used to play SAM/WAV/OGG files (digitized sounds) within an sfx string. It allows digitized sounds within the sound effects editor. The general format for & is as follows:

"&FILENAME.WAV&4C"

This will play FILENAME.WAV at a pitch of 4c, which corresponds to a sample rate of 8363Hz. Any given durations are irrelevant. If nothing follows the last &, the effect will play at the file's natural frequency. Multiple filenames can be used in the same PLAY command, but only the last one can have nothing following its last &. _ An underscore is usually used in conjunction with &. It turns off digitized sounds for the rest of the string, and ignores the rest of the string ONLY IF digitized music/sound is on. For example:

"&SHOT.WAV&6F#_+C-C"

The above will play SHOT.WAV at a sample rate of roughly 48KHz (F-sharp, 6th octave) if digitized sound is on, OTHERWISE it will play the normal shooting sound of "+C-C".

Sound Effect Numbers

The PLAY SFX command in Robotic plays one of the built-in sound effects. The numerical values corresponding to these sound effects are listed below. 0 - Gem 1 - Magic Gem 2 - Health 3 - Ammo 4 - Coin 5 - Life 6 - Lo Bomb 7 - Hi Bomb 8 - Key 9 - Full Keys 10 - Unlock 11 - Can't Unlock 12 - Invis. Wall 13 - Forest 14 - Gate Locked 15 - Open Gate 16 - Invinco Start 17 - Invinco Beat 18 - Invinco End 19 - Door Locked 20 - Open Door 21 - Hurt 22 - Hurt (Lava) 23 - Death 24 - Game Over 25 - Gate Closing 26 - Push 27 - Transport 28 - Shoot 29 - Break 30 - Out of Ammo 31 - Ricochet 32 - Out of Bombs 33 - Place Bomb (Lo) 34 - Place Bomb (Hi) 35 - Switch Bomb Type 36 - Explosion 37 - Entrance 38 - Pouch 39 - Ring/Potion 40 - Empty Chest 41 - Chest 42 - Out of Time 43 - Fire Ouch 44 - Stolen Gem 45 - Enemy HP Down 46 - Dragon Fire 47 - Scroll/Sign 48 - Goop 49 - Unused

SAM, OGG, MOD and WAV Frequencies

Sounds played using the SAM command in Robotic play at its "natural" frequency at value 0. If one wants to play the sound at a different pitch, a frequency value is needed. Frequencies corresponding to MOD file notes follow: -------------------------------------------- | | C | C#| D | D#| E | F | F#| G | G#| A | A#| B | -------------------------------------------- |Octave 1|856|808|762|720|678|640|604|570|538|508|480|453| -------------------------------------------- |Octave 2|428|404|381|360|339|320|302|285|269|254|240|226| -------------------------------------------- |Octave 3|214|202|190|180|170|160|151|143|135|127|120|113| -------------------------------------------- |Octave 4|107|101| 95| 90| 85| 80| 75| 71| 67| 63| 60| 56| -------------------------------------------- |Octave 5| 53| 50| 47| 45| 42| 40| 37| 35| 33| 31| 30| 28| -------------------------------------------- The following table lists frequencies corresponding to PLAY statement notes: ------------------------------------------------- |O|C |C# |D |D# |E |F |F# |G |G# |A |A# |B | ------------------------------------------------- |0|3424|3232|3048|2880|2712|2560|2416|2280|2152|2032|1920|1812| ------------------------------------------------- |1|1712|1616|1524|1440|1356|1280|1208|1140|1076|1016| 960| 906| ------------------------------------------------- |2| 856| 808| 762| 720| 678| 640| 604| 570| 538| 508| 480| 453| ------------------------------------------------- |3| 428| 404| 381| 360| 339| 320| 302| 285| 269| 254| 240| 226| ------------------------------------------------- |4| 214| 202| 190| 180| 170| 160| 151| 143| 135| 127| 120| 113| ------------------------------------------------- |5| 107| 101| 95| 90| 85| 80| 75| 71| 67| 63| 60| 56| ------------------------------------------------- |6| 53| 50| 47| 45| 42| 40| 37| 35| 33| 31| 30| 28| ------------------------------------------------- The following tables list how to play a Wave or OGG at its normal sound with PLAY statements: 48000Hz Wave/OGG --> 37 44100Hz Wave/OGG --> 41 32000Hz Wave/OGG --> 56 24000Hz Wave/OGG --> 75 22050Hz Wave/OGG --> 81 16000Hz Wave/OGG --> 112 12000Hz Wave/OGG --> 149 11025Hz Wave/OGG --> 162 08000Hz Wave/OGG --> 224 To convert frequencies from MZX to real, use these formulae: Actual frequency = 1789682 / MZX frequency MZX frequency = 1789682 / actual frequency SAMs and WAVs converted from SAMs by older versions of MZX play at a natural frequency of 8363Hz. Finally, tracked modules have a normal frequency of 44100 Hz; OGGs, on the other hand, have normal frequencies at their recording rate (for example, a OGG encoded at 22050 Hz will play normally at the 22050 Hz setting). The frequency of a module can be controlled with the "mod_frequency" counter. Changing the frequency mid-song can create a popping sound, especially while lowering frequency. The lowest allowed setting of mod_frequency is 16 Hz.

Where to Get Module and Sound Files

These questions are answered in the Frequently Asked Questions section of help. Frequently Asked Questions The Config File Table of Contents

Editing and Using the Overlay

The overlay is a simple but useful part of a board. If one looks at Floors and Fakes as a floor layer, and Walls as a central layer, the overlay is a ceiling layer. Basically, the overlay, when on, appears OVER anything on the board. The player, enemies, Robots, etc. all move underneath it; the only exceptions are sprites specifically set to go over it. The overlay is purely for show and graphical effects. For example, you could create archways that the player moves under, or have a score and lives display that is overlaid over the view at all times (by using Robotic). However, character 32 (empty space 99.99% of the time) is never part of the overlay. To emulate a space, use the wall character or make your own space character. This is very important to remember when using the overlay to display text. The overlay is set on "Normal Overlay" mode by default. The editor will prevent you from editing the overlay if it is Off, since it will not be saved if it is. These are the available overlay modes: Off - No overlay is saved, none is shown. Normal - The overlay is shown normally, scrolling along with the rest of the board. Default for boards. Static - The overlay is shown, but it does not scroll with the board. It always shows the top left position. Very useful for creating HUDs and status displays. Transparent - The overlay is saved and can hold info, but is currently not shown. If the overlay is on, press Alt+O in the editor to edit it. This brings you to the overlay editor. The menu at the bottom of the screen will change, and you will have access to the following keys and options: Alt+B - Block Press Alt+B to start block mode, then move the cursor to the opposite corner of a rectangular block and press Alt+B again. You can then select an action to perform upon the block. In all copy/move operations, the cursor marks the new UPPER LEFT corner. Copy block will allow you to duplicate the block by moving the cursor to a destination and pressing Enter. Copy block (repeated) is the same as Copy block but can allow copying of the same block to multiple places. Move block will allow you to move the block to a new location. Clear block will erase the contents of the block. Flip block will flip the block upside down. Mirror block will flip the block left to right. Paint block will change the entire block to the current color. Copy to board will copy the block to the given spot of the board. You can choose to place it as either Custom Block, Custom Floor, or Text. Copy to vlayer will copy the block to the given spot of the vlayer. Save as ANSi/TXT will save the block as an ANSi or TXT file. Save as MZM will save the block as a layer-type MZM file. Destinations for Move and Copy can overlap the original block safely. Ctrl+Dir is especially helpful when doing a repeated copy block; it moves the cursor the width or height of the block, ensuring no overlap when pasting. Like normal Block functions, one can copy between boards by selecting the board when the editor prompts the user for the block's destination. Use the B key to select the destination board. C - Color Press C to select a new current color from a menu. The thing under the cursor is not affected. One can jump to a color by typing its hex code in the color menu; for example, typing "0D" would jump to color 013 (background color 0, foreground color D). A quirk to keep in mind: any overlay tile with a background color of 0 will display the background color of anything beneath it. F - Fill Press F to fill in an enclosed area with the current character and color. The area must be completely surrounded by characters other than the character beneath the cursor. For example, you can fill over a solid square of As with something else. The current fill command may not work right for very large and complex areas- In this case, you must move to the unfilled areas and press F to continue filling. However, this happens very rarely. Alt+O - Edit Overlay Alt+O will exit overlay mode and return to editing the main board. Alt+S - Show Level Alt+S will toggle whether the level beneath the overlay is shown (defaults to yes). Without the level, only the overlay is shown, and no board bits or underlying colors are seen through any holes or c0x characters in the overlay. However, it can be a good idea to show the level to see how it looks beneath the overlay. F1 - Help F1 will bring up context-relevant help. You can press F1 at almost any time. F2 - Text F2 will toggle text mode on and off. When text mode is on, Enter will go to the next line, and Backspace will delete going backwards. All printable characters will type in as text. Arrow - Move The arrow keys will move the cursor. The edit window will scroll when necessary. Alt+Arrow - Move 10 Alt with the arrow keys will move the cursor ten spaces at a time (or to the edge if under 10 spaces away in that direction). Backspace - Delete Del - Delete These two keys will delete any overlay under the cursor. The current character is not affected. End - L/R Corner End will jump the cursor to the lower-right corner of the entire overlay. Enter - Character Enter will alter the current character on the overlay. Select it from a menu and then press Enter to confirm your choice. ESC - Exit/Cancel Mode ESC will exit overlay mode. If you are in block, text, or draw mode, ESC will instead cancel the current mode and return to normal overlay editing. Home - U/L Corner Home will jump the cursor to the upper-left corner of the entire overlay. Ins - Grab Ins will select the character and color under the cursor as the current. The actual character is not affected. Spacebar - Place Spacebar will copy the current character and color to the location under the cursor. Other overlay will be deleted if it is under the cursor. Tab - Draw Tab will toggle the current draw mode. When drawing is on, you will place a copy of the current character every time you move the cursor. P - Change Buffer Character P will act much like Enter, but only change the character in the buffer; no character on the overlay is changed with this action. Ctrl+Z - Undo Ctrl+Y - Redo Ctrl+Z will undo an action; Ctrl+Y will redo any previously undone action. Action depth is determined by config file settings, with 100 as default. The basic method of editing the overlay is to use C and Enter to select characters and colors, and use Space, arrows, and Tab to draw with them. Do not switch overlay mode to Off once you have drawn your overlay, or it may be permanently erased. The overlay and overlay mode can also be changed using Robotic; with Robotic, not only can one powerfully manipulate the overlay, but change the overlay's type, and also copy directly to the board or vlayer from the overlay (and vice versa). A knowledge of Robotic basics is required, so see the following sections to learn about Robots. Robots- What They Are and How to Use Them Robotic Tutorial Robotic Reference Manual The following sections discuss individual commands relating to overlays. CHANGE OVERLAY [color] [char] [color] [char] CHANGE OVERLAY [color] [color] COPY BLOCK # # # # # # COPY OVERLAY BLOCK # # # # # # COPY OVERLAY BLOCK # # # # "@filename" # COPY OVERLAY BLOCK "#x" "#y" # # "@filename" # COPY OVERLAY BLOCK # # # # "$string" # COPY OVERLAY BLOCK "#x" "#y" # # "$string" # COPY OVERLAY BLOCK # # # # "#x" "#y" COPY OVERLAY BLOCK "#x" "#y" # # # # COPY OVERLAY BLOCK "#x1" "#y1" # # "#x2" "#y2" OVERLAY ON OVERLAY STATIC OVERLAY TRANSPARENT PUT [color] [char] OVERLAY # # WRITE OVERLAY [color] "string" # # Table of Contents

Signs and Scrolls in the Editor

Signs and scrolls are a simple way to get messages across in the game. Signs can be read multiple times; scrolls can be read once, then disappear. To place them in the editor, press F10 and select Sign or Scroll from the list. You must then edit the text of the sign or scroll. The Scroll editor is very simple. You can move the cursor among the different lines and characters. Type to insert text anywhere. Press Ins to toggle between insert mode (default) and overwrite mode, where typed characters will overwrite any characters already there. Backspace and delete work as normal, as do PageDown, PageUp, End, and Home. Use Alt+C to insert a selected character from the current character set into the text. Press Alt+V to toggle between viewing the scroll elements with the current game charset/palette and the editor charset/palette. Finally, use Enter to start or insert new lines. Signs and scrolls allow the standard color codes in messages (described in the Strings section of the help). Default color coding for messages in scrolls is background color 8 and foreground color F. Press ESC when you are done editing your sign or scroll. It will be placed at the current cursor position and will become the current object in the buffer. Note that although you can now copy the scroll freely, there is a limit of 255 scrolls and signs per board, but this limit shouldn't ever be a problem. Strings, Special Formatting, and Their Place in Robotic Table of Contents

Debug Modes

The debug modes are powerful tools. MegaZeux contains two types of debug modes: the Counter Debug Mode and the Robotic Debugger.

Counter Debug Mode

The counter debug mode - accessed by pressing F11 while running a world during playtesting in the editor - not only can pause all current MZX world action and display all of the counters and strings the world has set, but also can manipulate these values and even add new ones. The left side of the counter debug mode shows the current selection of counters/strings. Built-in counters ending with an asterisk (*) are read-only. Highlighting a counter/string and either clicking it or pressing Enter/Space while on it will bring up a box, allowing the value of the counter/string to be changed. Type in the desired new value, and press Enter to set the counter/string to the new value. Press Escape to cancel setting a new value. (PLEASE NOTE: Strings can only show and set its first 68 characters when attempting to set a new value. If a string originally contained over 68 characters, none of the characters past the 68th will show in the value setting box, even when any of the first 68 characters are deleted. Simply choosing to set a value, while not doing anything else, will truncate the string down to its first 68 characters.) These counters and strings are organized into various lists, shown in the upper-right. Selecting one of these lists will display its contents in the left-side box. If a list has a plus sign next to it, it is a tree, and clicking on it or pressing Space or Enter will expand it to show any of that tree's sub-lists (if they exist). Click again to hide the sub-lists. The lists are as follows: Counters: Lists all user-defined counters, as well as status counters (things like AMMO, HEALTH, etc) and menu counters, followed by their values. Expanding this tree will allow selection of lists sorted by starting character - individual A through Z lists contain only counters starting with their respective characters, and # does the same for everything else. Only the first 45 characters of a counter name will be shown. Strings: Lists all user-defined strings, followed by their values. Expanding this tree will allow selection of lists sorted by starting character - individual A through Z lists for the respective characters, and # for everything else. Only the first 16 characters of a string name (including the $) and the first 40 characters of a string value will be shown. Sprites: Lists the global sprite counters and their values. Expanding this list will allow selection of lists sorted by relevant sprite - "spr1","spr2", and so on. Each spr# list shows all of each sprite's relevant counters. The number of currently-active sprites is given under the "Active sprites" entry. Universal: Lists counters which persist throughout an entire session of MegaZeux, as well as their values. World: Lists built-in world counters/strings and their values. Also displays the amount of RAM used by each component of the currently-running world under the "RAM" sub-list. Board: Lists the current board's built-in board counters/strings and their values. Also can expand to show lists of scrolls/signs (both under "Scrolls") and sensors, if any of these items exist on that board. For scrolls/signs, each list shows a "Scroll text" entry; if clicked or Enter is pressed while highlighted, it views that scroll's/sign's text as it would be if encountered in-game (i.e. in the currently-loaded charset, not the protected charset). For sensors, each list shows the sensor name and the Robot it messages. Robots: If directly highlighted, this option lists nothing. However, expanding this tree will allow selection of lists sorted by the robot_id of the current board's Robots - starting with "0: <name>" for the Global, and continuing on for each Robot on the board. Each list displays that Robot's local counters and their values (as well as their robot_name strings). In addition, certain special values can be accessed in this menu. -The number of commands that the given Robot has processed is listed under its commands_total value. -The number of commands that the given Robot has executed in the current cycle is listed under its commands_cycle value. This value is read-only. -Whether the given Robot is locked or unlocked is denoted by the value of lockself (0 for unlocked, 1 for locked). Outside of directly displaying and setting values of counters and strings, the counter debug mode has several other tools at its disposal. They are given buttons in the lower-right corner, and are as follows: Search: Locates names and values in any of the counters/strings listed in the counter debug mode. Type the desired search string and select from the given options, then press Enter. The search begins from the last highlighted line. This menu can be directly accessed with Ctrl+F, and an instant repeat of the last search can be done with Ctrl+R. Options: -Search names: Searches counter and string names. -Search values: Searches counter and string values. -Case sensitive: Returns results only if case matches. -Exact: Returns results only if the entire string or counter value matches (as opposed to if part of the string or counter value matches). -Reverse: Searches from bottom to top (as opposed to the default top to bottom). -Wrap search: If no results are found, starts from the opposite end and searches until a result is found or the original search location is reached. -Current list only: Only searches the current list. Child lists of the current list will not be searched. New: Creates a new counter or string with the given name. Its value will be 0 for a new counter, and blank for a new string. If any counter or string already exists with the given name, this will be ignored and the original counter/string will keep its original value. You will not be notified of any such conflicts. This menu can be directly accessed with Alt+N. Toggle Empties: Sets whether counters with values of 0 and blank strings are shown in the display lists. Defaults to Show (i.e. counters and strings with these values will be shown). Searching forces this setting to Show. This menu can be directly accessed with Alt+H. Export: Exports a text file list of SET commands that would set the current user-defined counters and strings, and the built-in counters in the Counters parent list, to their current values. If overwriting a current file is chosen, MZX will ask for confirmation. In addition to its own considerable power, accessing the counter debug mode can allow access to the character editor (via Alt+C) or the palette editor (via Alt+E) for further manipulation and testing.

The Robotic Debugger

Ever have problems with a Robot choking your game to a crawl? Can't figure out how someone else's code works from a simple lookthrough? Are your Robots just not interacting the way you'd planned? The Robotic Debugger might help. The Robotic Debugger can enable controlled line-by-line execution of Robots, or even halt Robot execution altogether. Since stepping through code line-by-line can be very, very tedious if unneeded, the debugger only starts allowing such control after meeting given conditions. The conditions that tell the debugger when to begin stepping through lines are called breakpoints. MegaZeux does not provide default breakpoints (with one notable exception explained later), so suitable breakpoints must be created. Pressing Alt+F11 while in the editor or during an editor testplay will load the config screen for the Robotic Debugger. Breakpoints can be added by using Alt+N or Alt+A, or by clicking the "(new)" text. Breakpoints will activate stepping when characters in a line of code match a given string, preventing the line triggering the breakpoint from executing. Additionally, the breakpoint can be set to trigger only for Robots whose names contain the characters in another given string, or only when the condition is met on a given line number. A blank string can be set as a breakpoint. In this case, all lines running in Robots matching the given Robot name string will trigger the debugger, and all line numbers matching a given line number will likewise always trigger. However, leaving all string fields blank and line number at 0 will have no notable effect. String matches for breakpoints, like MegaZeux string comparisons in general, do not have to match case. Also, as implied, the string comparisons are not for the whole line or Robot name; the lines or names must merely contain the given strings. Similar to breakpoints are watchpoints. Watchpoints activate stepping as well, but are based off of the values of counters and strings, and only activate stepping after a relevant value is changed, not right when one is seen. Unlike with breakpoints, the watchpoint Variable string has to exactly match the counter or string name to trigger (although this check is case insensitive). Local counters can be watched as well as global counters; to watch local counters, check for rN.<counter>, where N is the robot_id, and <counter> is the relevant local counter name (without the angle brackets). For watching the global Robot's local counters, just check for the relevant local counter name. When the Value field of a watchpoint is left blank, the watchpoint triggers every time the relevant counter or string is changed. Putting a value in the Value field has the watchpoint trigger only when the relevant counter or string changes to that specific value. When a counter watchpoint is triggered, the debugger will show the original value and the changed value. String watchpoints will only show that the watched string value has changed. Editing breakpoints/watchpoints is done by pressing Space. Deleting breakpoints/watchpoints is done by pressing Alt+D. The Robotic debugger defaults to off. Clicking the Enable Robotic Debugger button, or adding a breakpoint or watchpoint, activates the debugger from that point on. Once done editing breakpoints and watchpoints, click the Done button. In addition to user-defined breakpoints and watchpoints, MegaZeux also activates stepping through the debugger when Robot processing reaches very high amounts; if the debugger was currently off, hitting this condition forces it on. By default, this happens when a Robot executes over 2,000,000 commands in a single cycle, but this can be changed by changing the value of the COMMANDS_STOP counter. Once a breakpoint or watchpoint is hit, MegaZeux halts execution of all actions and opens up a menu. Actions, and the keys that activate them, are as follows: Continue: Stops stepping through code until the next breakpoint/watchpoint is hit. (C or Escape) Step: Steps through the current line, executing it, and prompts the user for further action at the next line. (S) Goto: Opens up a menu to send Robots to a given label. (G) All Robots that match the given Name string (or all Robots for blank) will be sent to the given label. The Goto option will send the relevant Robots to the given label regardless of locked status; the Send option will act as a normal label send; the Send All option will act as a normal label send to all Robots. Select the "Send/send all ignores locked status?" option to have these ignore locked states as well. The strings given here do not have to be constants: expression outputs and interpolated strings will also evaluate correctly for these values. Halt: Makes the Robot running the current line immediately stop processing commands. Note that this does not permanently stop the Robot from processing commands in the future (e.g. due to being sent to a label), but merely prevents it from running its currently planned commands. (H) Halt All: Immediately makes ALL Robots stop processing commands. (Alt+H) Counters: Opens up the Counter Debug Mode. (F11) Breakpoints: Opens up the Robotic Debugger config. (Alt+F11) The PgUp and PgDn keys can shift the debugger window to the top or bottom of the screen, respectively. Table of Contents

Error Messages

The following is a list of error messages in alphabetical order, which links to descriptions of the error and possible remedies. MegaZeux silently ignores many other possible errors. MegaZeux General Errors: Cannot decrypt write-protected world; check permissions Cannot overwrite the player- move it first Current renderer lacks advanced graphical features; features disabled Directory rename failed. Error exporting ANSi Error exporting SFX file Error exporting text Error saving; file/directory may be write protected Error swapping to next world (Filename) already exists. File rename failed. Limited/missing extended charset support; some features may not work Overlay mode is not on (see Board Info) Save would overwrite older world. Aborted. Windowing code bug You can only play this game via a swap from another game MegaZeux Validation Errors: Any extra scrolls/signs/robots were replaced Board @ (hex location) could not be found Board @ (hex location): found (#) robots; expected (#) Board @ (hex location): found (#) scrolls/signs; expected (#) Board @ (hex location): found (#) sensors; expected (#) Board @ (hex location) is irrecoverably truncated or corrupt Board @ (hex location) is truncated, but could be partially recovered Board file is from a future version (version) Bytecode file (filename) failed validation check Cannot load password protected world Error importing ANSi File doesn't exist File is invalid or is not an SFX file File is not a board file or is corrupt File is not an MZM or is corrupt File is not a valid .SAV file or is corrupt File is not a valid world file or is corrupt MZM contains runtime robots; dummying out MZM doesn't exist MZM from newer version (version); dummying out robots MZM is missing robots or contains corrupt robot Post validation IO error occurred Robot @ (hex location) could not be found Robot @ (hex location) is truncated or corrupt .SAV files from newer versions of MZX (version) are not supported .SAV files from older versions of MZX (version) are not supported Scroll @ (hex location) is truncated or corrupt Sensor @ (hex location) is truncated or corrupt This world may be password protected. Decrypt it? Unknown error reading from file Unknown error writing to file World is from a more recent version (version) MegaZeux Validation Errors (ZIP World Format): Board # (number) is corrupt Board # (number) is missing data: Robot # (number) contains duplicates on board # (number) Robot # (number) does not exist on board # (number) Robot # (number) exists on board # (number), but was not found Robot # (number) on board # (number) is corrupt Scroll # (number) on board # (number) is corrupt Sensor # (number) on board # (number) is corrupt MegaZeux Updater Errors: Attempt to invoke self failed! Failed to back up manifest. Check permissions. Failed to change back to user directory. Failed to change into install directory. Failed to compute update manifests Failed to create (filename). Check permissions. Failed to create directories (path too long) Failed to create TCP client socket. Failed to identify applicable update version. Failed to initialize network layer. Failed to remove (filename). Check permissions. Failed to roll back manifest. Check permissions. Failed to prune directories (path too long) Transferred more than expected uncompressed size. Unknown stat() error occurred MZX General Errors Cannot decrypt write-protected world; check permissions This can be caused by file errors or a hard disk space shortage. It can also result from an attempt to overwrite a read-only file. Cannot overwrite the player- move it first The user attempted to place an object over the player. The player must be moved from its current location if something else is desired at that location. Current renderer lacks advanced graphical features; features disabled Certain graphics renderers (overlay2,gp2x) and platforms (NDS) are unable to utilize some newer graphical features (i.e. layer rendering). If this error message is displayed, these features will not work. Directory rename failed. File rename failed. The user attempted to rename a directory or file, respectively, but failed. This could be due to trying to change a read-only file, trying to change a locked file, or due to some other error. Error exporting ANSi Error exporting SFX file Error exporting text The user attempted to export a file in the relevant format, but no file was created. This can be caused by file errors or a hard disk space shortage. It can also result from an attempt to overwrite a read-only file or write to a directory without write permissions. Error saving; file/directory may be write protected This can be caused by file errors or a hard disk space shortage. It can also result from an attempt to overwrite a read-only file or write to a directory without write permissions. Error swapping to next world A Robotic command, SWAP to WORLD, was issued, but the stated world could not be found or otherwise could not be swapped to, due to version conflicts, file errors, etc. (Filename) already exists. The user attempted to create a new file, but a file with that name already exists. Limited/missing extended charset support; some features may not work When this error message is displayed, the currently-running instance of MegaZeux cannot fully support extended character sets. Worlds that rely on this feature will still run in this case, but without this feature. Overlay mode is not on (see Board Info) You cannot edit or copy to the Overlay if it is Off; go to Board Info and turn it to Normal, Static, or Transparent. Save would overwrite older world. Aborted. A save was attempted in the debytecode version of MegaZeux that would overwrite a non-debytecode world file. Due to the present instability of debytecode, this is forcibly prevented. Windowing code bug This is a critical internal error. Try to isolate the reason for the problem and notify the maintainer(s), as this error signifies a severe bug in MegaZeux. You can only play this game via a swap from another game This error occurs when the user tries to play a game that has the option set to disallow normal gameplay. The world can only be played as a swap from another game or in the editor. For example, this may be the second half of another game, or a separate world for showing the introduction. MZX Validation Errors Board @ (hex location): found (#) robots; expected (#) Board @ (hex location): found (#) scrolls/signs; expected (#) Board @ (hex location): found (#) sensors; expected (#) Any extra robots/scrolls/signs were replaced MegaZeux found more instances of the given object than the world file indicated it had. All instances past the expected amount are tossed out. Board @ (hex location) could not be found The MegaZeux world is indicating that there should be a board at the given location, but it is not actually in the world file. Board @ (hex location) is irrecoverably truncated or corrupt The board at the given location is corrupt beyond repair and will be replaced with a blank board. Board @ (hex location) is truncated, but could be partially recovered Only part of the board was found, but what board info remained is placed at that location. Board file is from a future version (version) Load of a board file from a more recent version of MegaZeux was attempted. You must use the version of MegaZeux listed or higher in order to import this board file. Bytecode file failed validation check An attempt to load a bytecode file has failed validation checks and will not be loaded. Cannot load password protected world Since MegaZeux 2.80, worlds that are password protected have to be stripped of the password to run. This error is seen when the user refuses to decrypt the password-protected file. File doesn't exist An import of a file was attempted, but the file does not exist. Error importing ANSi File is invalid or is not an SFX file File is not a board file or is corrupt File is not an MZM or is corrupt File is not a valid .SAV file or is corrupt File is not a valid world file or is corrupt An import of the given type was halted due to being unrecognized as a valid file, or due to corruption. MZM contains runtime robots; dummying out Load of an MZM containing Robots and saved during a running game was attempted in the editor. The Robots will be replaced with CustomBlock facsimiles, as if the file were loaded as a layer-type MZM. MZM doesn't exist Loading an MZM file was attempted, but the given file does not exist. MZM from more recent version (version); dummying out robots Load of an MZM file with Robots from a more recent version of MZX was attempted. The Robots will be replaced with CustomBlock facsimiles, as if the file were loaded as a layer-type MZM. MZM is missing robots or contains corrupt robot The loaded MZM file indicates that a Robot should be at a certain location of the MZM, but found either no code or corrupt code. Post validation IO error occurred The given file passed validation, but some other problem is preventing it from loading. Robot @ (hex location) could not be found The board file indicates a Robot should be present at the given location, but no Robot exists there. Robot @ (hex location) is truncated or corrupt The Robot at the given location is unrecoverable, and will be replaced with an empty Robot at that location. .SAV files from newer versions of MZX (version) are not supported .SAV files from older versions of MZX (version) are not supported The .SAV file the user attempted to load is a different format than a supported .SAV version and cannot be loaded. This consists of all newer .SAV versions and all .SAV versions predating version 2.84. Scroll @ (hex location) is truncated or corrupt The Scroll at the given location is unrecoverable, and will be replaced with an empty Scroll at that location. Sensor @ (hex location) is truncated or corrupt The Sensor at the given location is unrecoverable, and will be replaced with a Sensor with default attributes at that location. This world may be password protected. Decrypt it? Worlds saved with password protection (some worlds made before MZX2.51s3.2) cannot natively run in MegaZeux. This prompt asks the user if they want to convert the world to a readable format. If Yes is chosen, by default MegaZeux will create and run a decrypted copy of the world in memory or as a temp file. The original MZX file will remain unchanged. If No is chosen, the world is left alone and MZX keeps any currently-running world as its active world. The decryption method can be changed via the config file. The Config File Unknown error reading from file A file read was attempted, but MZX failed for some undetermined reason. Unknown error writing to file MZX attempted to write to a file, but failed for some undertermined reason. World is from a more recent version (version) The .MZX file you tried to load or import is from a more current version of MegaZeux. You must upgrade MegaZeux to the given version or higher to play this worldfile. MegaZeux Validation Errors (ZIP World Format): Board # (number) is corrupt The board with the given number is corrupt beyond repair. Board # (number) is missing data: The given board lacks data that its structure indicates it should have. Robot # (number) contains duplicates on board # (number) A Robot is found in multiple places in the given board's data. Robot # (number) does not exist on board # (number) A Robot should exist on the given board, according to the board data, but does not. Robot # (number) exists on board # (number), but was not found A Robot exists on the given board, but the board data for that Robot is absent. Robot # (number) on board # (number) is corrupt The Robot on the board with the given number is corrupt beyond repair. Scroll # (number) on board # (number) is corrupt The Scroll on the board with the given number is corrupt beyond repair. Sensor # (number) on board # (number) is corrupt The Sensor on the board with the given number is corrupt beyond repair. MZX Updater Errors Attempt to invoke self failed! This error occurs when MZX fails to reload itself after an update. This signifies a major bug in MegaZeux; please contact the maintainer(s). Failed to back up manifest. Check permissions. Failed to create (filename). Check permissions. Failed to remove (filename). Check permissions. Failed to roll back manifest. Check permissions. MZX tried to write/delete a file from the working directory, but could not, likely due to the user's MZX working directory disallowing write access. Failed to change back to user directory. Failed to change into install directory. These errors occur when MZX fails to change active directories during the updating process. Failed to compute update manifests This error occurs when the hash check in a manifest file fails. This error can also appear if the download of the manifest file times out. Failed to create directories (path too long) Failed to prune directories (path too long) This error occurs when the pathnames of the subdirectories included in or deleted by the selected update are too long. Failed to create TCP client socket. MZX failed to create a socket. This may be because the last one created is still in use. This can signify a major bug in MegaZeux; please contact the maintainer(s). Failed to identify applicable update version. MZX could not find an update in the branch the user selected. Please check the update_branch_pin and update_host options in config.txt and make sure they are correct. Failed to initialize network layer. MZX's networking code is unable to load. This signifies a major bug in MegaZeux; please contact the maintainer(s). Transferred more than expected uncompressed size. The updater has sent the user more data than needed. The update may be corrupt. Unknown stat() error occurred A fatal error outside of the ones mentioned occurred. Please contact the developer(s) if you see this error. Table of Contents

Sensors - What They Are and How to Use Them

Sensors have two real purposes. The first is to act as save points. The second is to interact with Robots as a hybrid of floor and object. The first use is simple - just set the board to "Save only on Sensors", and then the player can only save when standing on a sensor. The second use is more complex, and requires knowledge of Robotic. Sensors are like controllable CustomFloors (albeit CustomFloors that can be pushed by non-player objects). When creating one, give it a name and a character, then enter the name of a Robot with which it will interact. This use of sensors is easily replicable through Robotic now, so this use of sensors is deprecated. However, if one wants to use sensors, this information will easily help. Sensors interact with Robots using labels (messages) and SEND commands, just like Robots interact with each other. Any Robot can SEND a message to a sensor, but the sensor will only SEND messages to the Robot stated in its settings. If you entered a Robot of ALL, then it will SEND messages to all Robots. Unlike Robots, sensors cannot send to a dynamic name; for instance, it cannot be set to send to "&fest&ive" (whereas a Robot would properly send to "1ive" when "fest" is 1 and to "5ive" when "fest" is 5).

Messages TO Sensors

The following messages can be sent to a sensor. A sensor can receive messages even when it is beneath the player. DIE This will cause the sensor to disappear forever. CHAR'X' This will cause the sensor to change its character to X. CHAR### This will cause the sensor to change its character to that represented by the number ###, from 0 to 255. COLORxx This will cause the sensor to change its color to the color represented by the code xx, a hexadecimal number from 00 to FF. The color coding is the same as used for Robotic commands, except without the "c" character. ?s are not allowed. N S E W This will cause the sensor to move north, south, east, or west, respectively. If the player is on top of the sensor, the player will move along with it. If the sensor tries to move towards the player, it will instead move beneath. If something pushable is in the direction of movement, the sensor will push it while moving if there is room.

Messages FROM Sensors

Sensors will send Robots the following messages. SENSORON This is sent when the player steps onto the sensor, when the sensor is told to move and it ends up beneath the player, or when something pushes the player onto the sensor. SENSORTHUD This is sent when the sensor is told to move, but it is blocked. SENSORPUSHED This is sent when something pushes the sensor.

Notes on Sensors

Only the player can step onto a sensor; other things will push it. The sensor, when moving, will move UNDER the player if in the way, or will take the player with it if the player is on the sensor. Laying a bomb while on a sensor will destroy the sensor. Table of Contents

Robotic Reference Manual

Use the following help links to see your desired topic(s).

1) The Basics

Robots - What They Are and How to Use Them Robotic Tutorial

2) Command List and Core Concepts

Command Reference Command Syntax Using the Editor The Global Directions Colors Built-in Labels Counters, Built-in Counters and Local Counters Strings, Special Formatting, and Their Place in Robotic Conditions Sound and Music Bullet Types Robotic Usages That Should be Avoided

3) Extended Concepts

Cycles and Board Scans - How MZX Processes Robots Sprites Expressions Subroutines The Vlayer Super MZX Modes File Access Using MZMs Trigonometric Functions Partial Character Sets CHANGE CHAR ID - The CHAR ID Table

4) Legacy Coding Tools

Prefixes Sensors Table of Contents

Command Syntax

Commands in Robotic must conform to a certain syntax: COMMAND [param] [param] ... COMMAND is the words or symbol that specifies exactly which command you are using. Params are the values used to supplement the command's function. "string" or "counter" or "label" or "Robot" or "file" Strings are a series of characters surrounded by quotes. Counters are strings representing the name of a counter. Labels are strings representing the name of a label, a point within a Robot. Robots are strings representing the name of a Robot. Files are strings representing a file or folder on disk, always including the extension in the case of files. (Some string examples: "Hi", "Gems", "Label5", "*1230 +725", "robott.txt", etc.) The quotes can be left off if the string contains no spaces and if the string is not the same as any word found in any command or parameter, i.e. is a word that the editor could not mistake for a part of a command. MegaZeux will add the quotes for you if the string meets these criteria. For example, "fifty" and "HONK" will be auto-completed by MZX, but "Ammo", "N", "Goto", and most notably "loop" have to have the quotes typed in manually. # Numbers are allowed to be integers within the range of -2147483648 to 2147484647. Numbers can be replaced with a string representing the name of a counter at any time. Examples of legal numbers: 3200, "Stuffs", -19043, "Ammo". They can also be represented in hexadecimal, using $xxxx format. In this case, xxxx can be any number from 0 to FFFF. Any arithmatic that causes a number to go out of its range will not cap the result at the limit, but will instead cause a number wraparound. Numbers can not directly be allowed to go past the 16-bit limits (-32768 to 32767) in Robotic commands, but this can be easily circumvented by using constant expressions. Constant expressions also allow larger hexadecimal numbers and octal numbers; please view the expressions section for more detail. Certain commands will limit numbers to the range of 0 to 255. Expressions [color] The format for colors is cXX, where X is 0-9, A-F, or ?. The first X represents the background color; the second X represents the foreground color. The numbers and symbols represent the following colors, by default: 0 Black (color #0) 1 Blue (color #1) 2 Green (color #2) 3 Cyan (color #3) 4 Red (color #4) 5 Purple (color #5) 6 Brown (color #6) 7 Lt. Gray (color #7) 8 Dk. Gray (color #8) 9 Lt. Blue (color #9) 10 Lt. Green (color #10) 11 Lt. Cyan (color #11) 12 Lt. Red (color #12) 13 Lt. Purple (color #13) 14 Yellow (color #14) 15 White (color #15) ? Any color/No change in color The UI uses its own set of protected colors, to prevent general color edits from harming usability. The use of ? is not always a logical option for some commands. When used, it signifies to replace it with the current color or ignore that part of the color for that command (or if used in IF statements, signifies to accept any value in that field). Colors may be selected from a menu within the Robot editor using F2. Colors can also be replaced with the name of a counter at any time. In this case, the value of the counter is BK*16+FG, where BK and FG are 0-15. To use ?, use the following values: 256+FG = c?X 272+BK = cX? 288 = c?? A color of c?? will be inserted into commands when you do not put down anything for the color. Examples of legal colors: cF9, c02, c?5, c??, "color_counter". While detecting colors of ?? is generally an accepted practice, it's extremely discouraged to put colors of ?? or change to them, with the notable exception of placing Sprites. Robotic Usages That Should be Avoided [char] Characters ("chars" for short) are single characters surrounded by apostrophes, e.g. 'X'. X can be any character in the main character set. A character can be selected from a menu in the Robot editor using F3. Numbers and counters can be used to represent characters as well. Number values range from 0 to 255 (other values will wrap around to be 0-255). Examples of legal characters - 'a', '', 20, "Count". Characters can also represent numbers, so typing in commands like INC "health" '5' will most likely yield _much_ different results than what was likely intended. However, for some usages this use of chars is vastly superior to any other method (such as when reading from the overlay onto strings). Certain characters must be inputted in specific ways to avoid problems with Robotic: \0 for character 0 \t for tab (character 9) \n for newline (character 10) \r for carriage return (character 13) \" for quotation mark \\ for backslash MZX handles these conversions for you when using F3 to select a character from the current character set. To access characters in extended character sets, use counters. [dir] Directions are used to denote a direction on the board. A direction is one of the following: NORTH (or N or UP) SOUTH (or S or DOWN) EAST (or E or RIGHT) WEST (or W or LEFT) IDLE NODIR ANYDIR RANDNS RANDEW RANDNE RANDNB RANDB SEEK FLOW RANDANY UNDER (or BENEATH) The four cardinal directions (N, S, E, W) are self-explanatory. Below are descriptions of the other directions. IDLE No direction, as in the absence of any direction. Used with: WALK [dir] NODIR For condition checks only. If no direction matches the condition, the condition is met. Conditions ANYDIR For condition checks only. If any direction matches the condition, the condition is met. Conditions RANDNS Randomly either NORTH or SOUTH. RANDEW Randomly either EAST or WEST. RANDNE Randomly either NORTH or EAST. RANDNB Randomly any direction where the Robot is not blocked by something. RANDB Randomly any direction where the Robot is blocked. SEEK The direction closest to the player. If the player is on a diagonal and is equally far away from the Robot vertically and horizontally, the direction will randomly be one of the two directions comprising the diagonal. FLOW The direction that the Robot is currently walking. RANDANY Randomly one of NORTH, SOUTH, EAST, or WEST. UNDER The direction signifying whatever is BENEATH something, such as floors. Often used with: LAYBOMB [dir] LAYBOMB HIGH [dir] Most directions can be used with the following modifying prefixes: OPP The opposite direction. NORTH becomes SOUTH, etc. CW The direction clockwise of the named direction. NORTH becomes EAST, etc. RANDP Randomly a direction perpendicular to the named direction. NORTH becomes EAST or WEST, etc. RANDNOT Randomly any direction OTHER than the given direction. [thing] The name of any object from the editor, other than the player. Use the name from the object list, minus any punctuation or spaces. Examples of legal things: Gem, CustomFloor, LitBomb, Robot. There are some special cases: * OpenGate will place an already-open gate. The parameter field determines how long it remains open (ranging from p00 for 1 cycle, up to pff for 256 cycles). * Lazer will place a single piece of lazer wall. The parameter field determines both initial lazer character and duration. * Sprite and Sprite_Colliding relate to sprites, while Image_File relates to MZMs. These are covered in their own sections. [param] A code representing the settings for a thing. (see above) The format is p# or p??. # is a hexadecimal code from 0 to FF. ?? represents settings that you don't care about or shouldn't change. To enter parameter codes easily, use F4 in the Robot editor after you have typed in an object name. p?? will be inserted automatically any time you have a thing without a parameter. Counters can also be used as parameters, as can decimal numbers; to insert decimal numbers, place the number in the proper location, but without the "p" before it. p?? in an IF command will allow that command to accept all params. [item] One of the following: TIME, SCORE, GEMS, AMMOS, LIVES, LOBOMBS, HIBOMBS, COINS, HEALTHS. Note the plural format; this distinguishes items from things. !<>= A conditional for comparing two numbers, counters or strings: = or == Equal to < Less than > Greater than <= or =< Less than or equal to >= or => Greater than or equal to != or <> or >< Not equal to [condition] A word, sometimes followed by a direction, signifying a certain condition. Use in IF [condition] and IF NOT [condition] commands to test whether a condition is currently present. WALKING [dir] Tests whether the Robot is currently walking in a given direction. IDLE, NODIR, and ANYDIR are allowed here. SWIMMING Tests whether the Robot is currently in water. FIREWALKING Tests whether the Robot is currently in either lava or fire. TOUCHING [dir] Tests whether the player is next to the Robot in the given direction. NODIR and ANYDIR are allowed here. BLOCKED [dir] Tests whether the Robot is blocked by something in the given direction. NODIR and ANYDIR are allowed here. This condition has a special mode: if the IF command has a REL PLAYER prefix before it, it will instead check next to the PLAYER for being blocked. If the IF command has a REL COUNTERS prefix before it, it will instead check next to the position pointed to by the counters XPOS and YPOS. REL COUNTERS REL PLAYER ALIGNED Tests whether the player is aligned with the Robot either horizontally or vertically. ALIGNEDNS ALIGNEDEW Tests whether the player is aligned with the Robot, but only tests on the horizontal (EW) or vertical (NS) axis, not both at once. LASTSHOT [dir] Tests whether the last direction the Robot was shot in was the given direction. For example, if the Robot had just been shot on the north side, then LASTSHOT NORTH would be true. All bullet types are valid for this condition. NODIR/ANYDIR are not valid for this condition. LASTTOUCH [dir] Similar to the above; tests whether the last direction the Robot was touched by the player is the given direction. NODIR/ANYDIR are not valid for this condition. RIGHTPRESSED LEFTPRESSED UPPRESSED DOWNPRESSED SPACEPRESSED DELPRESSED Tests whether the indicated key is currently being held down. MUSICON Tests whether digitized music and sound effects are currently on. PCSFXON Tests whether PC speaker sound effects are currently on. Miscellaneous When typing in a command, the following symbols and words, as well as spaces, can be used freely. They have no effect on the final command and are only used to clarify its meaning. , (comma) ; (semicolon) A AN AND AS AT BY ELSE FOR FROM INTO IS OF THE THEN THERE THROUGH THRU TO WITH These will disappear from the line if "disassemble_extras" is set to 0 in the config file. See the config file for further details. The Config File Table of Contents Robotic Reference Manual

Strings, Special Formatting, and Their Place in Robotic

Simple Strings

Generally, a string is a series of symbols within quotes, such as: "BUG", "Hi there!", and even "EA9 _" or "". There are two special aspects or features of strings that may be useful: color coding, and counter interpolation.

Color

Used in Robotic commands *, %, ?, and &, strings can contain color codes. There are two color symbols: ~ for changing foreground, and @ for changing background. These should be followed by one of these characters: 0 Black (color 0) 8 Dk. Gray (color 8) 1 Blue (color 1) 9 Lt. Blue (color 9) 2 Green (color 2) A Lt. Green (color 10) 3 Cyan (color 3) B Lt. Cyan (color 11) 4 Red (color 4) C Lt. Red (color 12) 5 Purple (color 5) D Lt. Purple (color 13) 6 Brown (color 6) E Yellow (color 14) 7 Lt. Gray (color 7) F White (color 15) To show a ~, use ~~. To show a @, use @@.

Counters

Strings can show the values of counters, using the counter name surrounded with &s. For example, if the player has 55 gems, "You have &GEMS& gems." will become "You have 55 gems." If you use &INPUT&, then the last inputted string will be shown. Use && to show a true '&'. The above features are available in nearly ALL Robotic commands that use strings, including in the name of OTHER counters. (The sole exception is in label names.) This can be used to simulate array-like constructs.

Robotic Usage of Strings

In Robotic, strings can be incredibly powerful. They primarily hold text information, such as names. (They can hold a single number like counters can, but counters are by far better-suited for number use). A Robotic string is any counter prefixed by a $ sign (e.g. "$string"). Certain characters must be inputted in specific ways to avoid problems with Robotic: \0 for character 0 (this won't be parsed correctly in strings) \t for tab (character 9) \n for newline (character 10) \r for carriage return (character 13) \" for quotation mark \\ for backslash

Robotic Usage - Setting Strings

SET "$string" to "text" Sets the contents of the given string to the given line of text. SET "$string" to "$string2" Sets the contents of the given string to the contents of another string. SET "$string" to # Sets the contents of the given string to an integer value.

Robotic Usage - Outputting Strings

Anywhere you can output a counter, you can output a string. Simply encase the string name in ampersands. E.G.: SET "$woohoo" to "My favorite song!" * "&$woohoo&" Would output "My favorite song!" in the message line. There are several special things you can set strings to for certain functions. These are listed in the Counters section. String Counters

Robotic Usage - Comparing Strings

String comparisons are case-insensitive unless stated otherwise. Allowed comparisons are to a line of text, to another string and to a number. However, the string is required to be the first item, and string counters such as "MOD_NAME", "BOARD_SCAN", etc. are not valid comparisons. Strings can be compared through these commands: IF "$string" = "value" then "label" (equality) IF "$string" != "value" then "label" (inequality) IF "$string" > "value" "label" (greater than) IF "$string" < "value" "label" (less than) IF "$string" >= "value" "label" (greater than or equal to) IF "$string" <= "value" "label" (less than or equal to) IF "$string" === "value" then "label" (case-sensitive equality) Strings can also be compared using wildcards. There are two special wildcard characters: the ? character in the value being compared against matches any one character, while the % character matches any number of any characters (including zero). The wildcard commands are: IF "$string" ?= "value" then "label" IF "$string" ?== "value" then "label" (case-sensitive) Due to their use as a token, actual ? and % characters must be escaped to be checked for in wildcard comparisons. Use \\? and \\% to have values that check for literal use of these characters.

Robotic Usage - Manipulating Strings

Firstly, strings can be offset and limited ("spliced"). $strname#X will cap the string to X characters in length. $strname+X will offset the start of the string by X characters. Using a negative number will offset the start of the string backwards from the end of the string by X characters, with -1 as the end character. (e.g. "$str+-2" would offset the string "str" at two characters from its end.) $strname+X#Y will offset the string by X characters and limit the string to Y characters in length. Normally string splicing is used to read a given selection of a string; however, it can also be used for writing to parts of strings. When you set an offset when setting a string, the length of the string will not decrease, so you'll only manipulate a portion of the string. For instance: set "$str" "hello" set "$str+1" "LOL" Will cause $str to have the value "hLOLo". Writing to parts of strings with an offset also changes how the string limit works; any length cap will limit how much of the spliced-in material is inserted instead of limiting the string length in total. For instance: set "$str" "Baby steps." set "$str+0#4" "Long journey." Will cause $str to have the value "Long steps." $strname.X will manipulate the Xth character in a string (starting from 0). When used for output, it will give the character value of the given character in a string. Any invalid numbers (past the terminator) are given a value of 0. This command works well with char immediates: E.G. SET "$string.0" 'S' . When setting the character in a string it will make the string length one larger than X, so be careful when using very large values. Using negative numbers will manipulate using the end of the string as its basis: -X will manipulate the Xth character from the end of the string, with -1 being the end character. $strname.X#Y will manipulate characters in the string from the Xth character (starting from 0), up to character (X+Y-1). Y can be a number from 1 to 4; all other values for Y are clamped to fit this range. The string given or output acts as a number 8*Y bits in length. $str.length will give the length of the given string. Secondly, strings can be clipped, appended or written to from the board or overlay. INC "$string" "$string2" INC "$string" "text" These two commands append another string's contents or text, respectively, to the end of a given string. DEC "$string" # This command clips the given number of characters from the end of a string. # is treated as unsigned so using negative numbers will probably cause the length to go down to zero. COPY BLOCK x y w h "$string" t COPY OVERLAY BLOCK x y w h "$string" t These commands copy information from the board or overlay, respectively, to a given string. X and Y are the coordinates of the upper-left corner of the block; W and H are its width and height; T is the terminating character. For T, one can put in a counter with the param value of the desired terminator character or a char immediate in the form 'c' (not just the character itself). If "t" is 0 there will be no terminator. The letters are added from left to right and up to down until the terminator character is reached, or until the end of the given block is reached. If x and y begin with a pound sign (#), the string will instead be read from the vlayer. Please use this method of scanning strings instead of BOARD_SCAN.

Robotic Usage - File Access

Finally, strings can be used for loading and saving several MZX file formats. The following formats can be loaded from a string: -Palettes with LOAD PALETTE "$string" -Charsets with LOAD CHAR SET "$string" -Robots with SET "$string" "LOAD_ROBOT" -MZMs with PUT "@$string" image_file pNN x y Robots can be saved into a string with this command: SET "$string" "SAVE_ROBOT" MZMs can be saved into a string via these methods: COPY BLOCK x y w h "@$string" p COPY OVERLAY BLOCK x y w h "@$string" p COPY (OVERLAY) BLOCK "#x" "#y" w h "@$string" m String splicing is valid for string file operations. Robotic Reference Manual Table of Contents

Command Reference

The following tables are lists of all Robotic commands in MegaZeux. The commands are listed as help links and will jump to that specific command. After the tables are the actual command descriptions. Note that because of its size, the command reference is split into two parts. Any command that (typically) ends a cycle will be marked by a [!] symbol. For more precise information, view cycles_and_commands.txt in the documentation. The command listing is arranged by alphabetical order and by command type. Click the respective links to jump to that arrangement. Type-Based Command Listing Alphabetical Command Listing

Type-Based Command Listing

Flow and Branching Commands General Color and Character Commands Item Color and Character Commands Counter and String Manipulation Commands Music and Sound Commands Textbox and Message Row Commands Board Placement and Copy Commands Overlay Commands View Commands Other Board Commands Player Control and Item Commands Self Movement and Attack Commands Other Self-Oriented Commands Miscellaneous Commands

Flow and Branching Commands

: "label" WAIT # [!] END [!] GOTO "label" GOTO "#return" GOTO "#top" SEND # # "label" SEND "Robot" "label" SEND [dir] "label" SEND [dir] PLAYER "label" IF "counter" !<>= # "label" IF [condition] "label" IF NOT [condition] "label" IF # # "label" IF PLAYER # # "label" IF ALIGNEDROBOT "Robot" "label" IF [color] [thing] [param] # # "label" IF [color] [thing] [param] [dir] "label" IF [dir] PLAYER [color] [thing] [param] "label" IF NOT [color] [thing] [param] [dir] "label" IF ANY [color] [thing] [param] "label" IF NO [color] [thing] [param] "label" IF "$string" (equality) # "label" IF "$string" (equality) "text" "label" IF "$string" (equality) "$string2" "label" IF c?? Sprite_Colliding pNN # # "label" IF c?? Sprite pNN # # "label" IF STRING "string" "label" IF STRING MATCHES "string" "label" IF STRING NOT "string" "label" IF FIRST STRING "string" "label" LOCKSELF UNLOCKSELF ZAP "label" # RESTORE "label" # | "label" LOOP # LOOP START ABORT LOOP ASK "string" CYCLE # [!] WAIT MOD FADE [!] WAIT PLAY [!]

General Color and Character Commands

LOAD PALETTE "file" LOAD CHAR SET "file" SET COLOR # # # # CHAR EDIT [char] # # # # # # # # # # # # # # COPY CHAR [char] [char] SCROLL CHAR [char] [dir] FLIP CHAR [char] [dir] COLOR INTENSITY # PERCENT COLOR INTENSITY # # PERCENT COLOR FADE OUT COLOR FADE IN

Item Color and Character Commands

PLAYER CHAR [char] PLAYER CHAR [dir] [char] PLAYERCOLOR [color] CHANGE CHAR ID # [char] BULLETCOLOR [color] BULLETE [char] BULLETN [char] BULLETS [char] BULLETW [char] PLAYER BULLETCOLOR [color] PLAYER BULLETE [char] PLAYER BULLETN [char] PLAYER BULLETS [char] PLAYER BULLETW [char] NEUTRAL BULLETCOLOR [color] NEUTRAL BULLETE [char] NEUTRAL BULLETN [char] NEUTRAL BULLETS [char] NEUTRAL BULLETW [char] ENEMY BULLETCOLOR [color] ENEMY BULLETE [char] ENEMY BULLETN [char] ENEMY BULLETS [char] ENEMY BULLETW [char] MISSILECOLOR [color] CHANGE THICK ARROW CHAR [dir] [char] CHANGE THIN ARROW CHAR [dir] [char]

Counter and String Manipulation Commands

SET "counter" # SET "counter" RANDOM # # INC "counter" # INC "counter" RANDOM # # DEC "counter" # DEC "counter" RANDOM # # MULTIPLY "counter" # DIVIDE "counter" # MODULO "counter" # DOUBLE "counter" HALF "counter" SET "$string" "text" SET "$string1" "$string2" SET "$string" # INC "$string" "text" INC "$string" "$string2" DEC "$string" # INPUT STRING "string" CLIP INPUT

Music and Sound Commands

MOD "file" MOD "*" VOLUME # MOD FADE # # MOD FADE IN "file" MOD FADE OUT JUMP MOD ORDER # SAM # "file" PLAY "string" PLAY SFX "string" WAIT PLAY "string" [!] SFX # CHANGE SFX # "string" END MOD END PLAY END SAM MOD SAM # #

Textbox and Message Row Commands

[ "string" % "string" & "string" ? "label" "string" ? "counter" "label" "string" * "string" MESSAGE ROW # SET MESG COLUMN # CENTER MESG CLEAR MESG ENABLE MESG EDGE DISABLE MESG EDGE SCROLLARROW COLOR [color] SCROLLBASE COLOR [color] SCROLLCORNER COLOR [color] SCROLLPOINTER COLOR [color] SCROLLTITLE COLOR [color] ASK "string" INPUT STRING "string"

Board Placement and Copy Commands

PUT [color] [thing] [param] # # PUT [color] [thing] [param] [dir] PUT [color] [thing] [param] [dir] PLAYER PUT "@FILENAME.XXX" Image_File [param] # # PUT [color] Sprite [param] # # COPY # # # # COPY [dir] [dir] COPY BLOCK # # # # # # COPY BLOCK # # # # "@filename" # COPY (OVERLAY) BLOCK "#x" "#y" # # "@filename" # COPY BLOCK # # # # "$string" # COPY (OVERLAY) BLOCK "#x" "#y" # # "$string" # COPY BLOCK # # # # "#x" "#y" COPY BLOCK "#x" "#y" # # # # COPY (OVERLAY) BLOCK "#x1" "#y1" # # "#x2" "#y2"

Overlay Commands

PUT [color] [char] OVERLAY # # WRITE OVERLAY [color] "string" # # COPY OVERLAY BLOCK # # # # # # COPY OVERLAY BLOCK # # # # "@filename" # COPY OVERLAY BLOCK # # # # "$string" # COPY OVERLAY BLOCK # # # # "#x" "#y" COPY OVERLAY BLOCK "#x" "#y" # # # # CHANGE OVERLAY [color] [color] CHANGE OVERLAY [color] [char] [color] [char] OVERLAY ON OVERLAY STATIC OVERLAY TRANSPARENT

View Commands

VIEWPORT # # VIEWPORT SIZE # # SCROLLVIEW [dir] # SCROLLVIEW POSITION # # RESETVIEW LOCKSCROLL UNLOCKSCROLL SET EDGE COLOR [color]

Other Board Commands

CHANGE [color] [thing] [param] [color] [thing] [param] MOVE ALL [color] [thing] [param] [dir] [!] BOARD [dir] "string" BOARD [dir] NONE AVALANCHE DISABLE SAVING ENABLE SAVING ENABLE SENSORONLY SAVING

Player Control and Item Commands

GIVE # [item] TAKE # [item] TAKE # [item] "label" GIVEKEY [color] GIVEKEY [color] "label" TAKEKEY [color] TAKEKEY [color] "label" TRADE # [item] # [item] "label" LOCKPLAYER LOCKPLAYER ATTACK LOCKPLAYER EW LOCKPLAYER NS UNLOCKPLAYER TELEPORT PLAYER "string" # # [!] MOVE PLAYER [dir] [!] MOVE PLAYER [dir] "label" [!] PUT PLAYER # # [!] PUT PLAYER [dir] [!] ENDLIFE ENDGAME FILLHEALTH SET MAXHEALTH # SAVE PLAYER POSITION SAVE PLAYER POSITION # RESTORE PLAYER POSITION [!] RESTORE PLAYER POSITION # [!] RESTORE PLAYER POSITION # DUPLICATE SELF [!] EXCHANGE PLAYER POSITION [!] EXCHANGE PLAYER POSITION # [!] EXCHANGE PLAYER POSITION # DUPLICATE SELF [!] BLIND # FIREWALKER # WIND #

Self Movement and Attack Commands

/ "string" [!] WALK [dir] GO [dir] # [!] GOTOXY # # [!] PERSISTENT GO "string" [!] TRY [dir] "label" [!] SHOOT [dir] SPITFIRE [dir] SHOOTMISSILE [dir] SHOOTSEEKER [dir] LAYBOMB [dir] LAYBOMB HIGH [dir] LAZERWALL [dir] #

Other Self-Oriented Commands

CHAR [char] COLOR [color] DIE DIE ITEM EXPLODE # DUPLICATE SELF # # DUPLICATE SELF [dir] COPYROBOT "Robot" [!] COPYROBOT # # [!] COPYROBOT [dir] [!] . "@string" PUSH [dir] ROTATECW ROTATECCW SWITCH [dir] [dir] OPEN [dir] BECOME NONLAVAWALKER BECOME NONPUSHABLE BECOME LAVAWALKER BECOME PUSHABLE BECOME [color] [thing] [param]

Miscellaneous Commands

. "string" SWAP WORLD "file" CHANGE CHAR ID # [char] STATUS COUNTER # "counter" FREEZETIME # SLOWTIME # REL COUNTERS REL PLAYER REL SELF REL COUNTERS FIRST REL PLAYER FIRST REL SELF FIRST REL COUNTERS LAST REL PLAYER LAST REL SELF LAST

Alphabetical Command Listing

% "string" & "string" * "string" . "string" . "@string" / "string" [!] : "label" ? "counter" "label" "string" ? "label" "string" [ "string" | "label" ABORT LOOP ASK "string" AVALANCHE BECOME [color] [thing] [param] BECOME NONLAVAWALKER BECOME NONPUSHABLE BECOME LAVAWALKER BECOME PUSHABLE BLIND # BOARD [dir] "string" BOARD [dir] NONE BULLETCOLOR [color] BULLETE [char] BULLETN [char] BULLETS [char] BULLETW [char] CENTER MESG CHANGE [color] [thing] [param] [color] [thing] [param] CHANGE CHAR ID # [char] CHANGE OVERLAY [color] [char] [color] [char] CHANGE OVERLAY [color] [color] CHANGE SFX # "string" CHANGE THICK ARROW CHAR [dir] [char] CHANGE THIN ARROW CHAR [dir] [char] CHAR [char] CHAR EDIT [char] # # # # # # # # # # # # # # CLEAR MESG CLIP INPUT COLOR [color] COLOR FADE OUT COLOR FADE IN COLOR INTENSITY # PERCENT COLOR INTENSITY # # PERCENT COPY # # # # COPY [dir] [dir] COPY BLOCK # # # # # # COPY CHAR [char] [char] COPY OVERLAY BLOCK # # # # # # COPY BLOCK # # # # "@filename" # COPY OVERLAY BLOCK # # # # "@filename" # COPY (OVERLAY) BLOCK "#x" "#y" # # "@filename" # COPY BLOCK # # # # "$string" # COPY OVERLAY BLOCK # # # # "$string" # COPY (OVERLAY) BLOCK "#x" "#y" # # "$string" # COPY BLOCK # # # # "#x" "#y" COPY OVERLAY BLOCK # # # # "#x" "#y" COPY BLOCK "#x" "#y" # # # # COPY OVERLAY BLOCK "#x" "#y" # # # # COPY (OVERLAY) BLOCK "#x1" "#y1" # # "#x2" "#y2" COPYROBOT "Robot" [!] COPYROBOT # # [!] COPYROBOT [dir] [!] CYCLE # [!] DEC "counter" # DEC "counter" RANDOM # # DEC "$string" # DIE DIE ITEM DISABLE MESG EDGE DISABLE SAVING DIVIDE "counter" # DOUBLE "counter" DUPLICATE SELF # # DUPLICATE SELF [dir] END [!] END MOD END PLAY END SAM ENDGAME ENDLIFE ENABLE MESG EDGE ENABLE SAVING ENABLE SENSORONLY SAVING ENEMY BULLETCOLOR [color] ENEMY BULLETE [char] ENEMY BULLETN [char] ENEMY BULLETS [char] ENEMY BULLETW [char] EXCHANGE PLAYER POSITION [!] EXCHANGE PLAYER POSITION # [!] EXCHANGE PLAYER POSITION # DUPLICATE SELF [!] EXPLODE # FIREWALKER # FILLHEALTH FLIP CHAR [char] [dir] FREEZETIME # GIVE # [item] GIVEKEY [color] GIVEKEY [color] "label" GO [dir] # [!] GOTO "label" GOTO "#return" GOTO "#top" GOTOXY # # [!] HALF "counter" IF "counter" !<>= # "label" IF [condition] "label" IF # # "label" IF [dir] PLAYER [color] [thing] [param] "label" IF [color] [thing] [param] # # "label" IF [color] [thing] [param] [dir] "label" IF ALIGNEDROBOT "Robot" "label" IF ANY [color] [thing] [param] "label" IF FIRST STRING "string" "label" IF NO [color] [thing] [param] "label" IF NOT [color] [thing] [param] [dir] "label" IF NOT [condition] "label" IF PLAYER # # "label" IF STRING "string" "label" IF STRING MATCHES "string" "label" IF STRING NOT "string" "label" IF "$string" (equality) # "label" IF "$string" (equality) "text" "label" IF "$string" (equality) "$string2" "label" IF c?? Sprite_Colliding pNN # # "label" IF c?? Sprite pNN # # "label" INC "$string" "text" INC "$string" "$string2" INC "counter" # INC "counter" RANDOM # # INPUT STRING "string" JUMP MOD ORDER # LAYBOMB [dir] LAYBOMB HIGH [dir] LAZERWALL [dir] # LOAD CHAR SET "file" LOAD PALETTE "file" LOCKPLAYER LOCKPLAYER ATTACK LOCKPLAYER EW LOCKPLAYER NS LOCKSCROLL LOCKSELF LOOP # LOOP START MESSAGE ROW # MISSILECOLOR [color] MOD "file" MOD FADE # # MOD FADE IN "file" MOD FADE OUT MOD SAM # # MOD "*" MODULO "counter" # MOVE ALL [color] [thing] [param] [dir] [!] MOVE PLAYER [dir] [!] MOVE PLAYER [dir] "label" [!] MULTIPLY "counter" # NEUTRAL BULLETCOLOR [color] NEUTRAL BULLETE [char] NEUTRAL BULLETN [char] NEUTRAL BULLETS [char] NEUTRAL BULLETW [char] OPEN [dir] OVERLAY ON OVERLAY STATIC OVERLAY TRANSPARENT PERSISTENT GO "string" [!] PLAY "string" PLAY SFX "string" PLAYER BULLETCOLOR [color] PLAYER BULLETE [char] PLAYER BULLETN [char] PLAYER BULLETS [char] PLAYER BULLETW [char] PLAYER CHAR [dir] [char] PLAYER CHAR [char] PLAYERCOLOR [color] PUSH [dir] PUT [color] [thing] [param] # # PUT [color] [thing] [param] [dir] PUT [color] [char] OVERLAY # # PUT [color] [thing] [param] [dir] PLAYER PUT PLAYER # # [!] PUT PLAYER [dir] [!] PUT "@FILENAME.XXX" Image_File [param] # # PUT [color] Sprite [param] # # REL COUNTERS REL PLAYER REL SELF REL COUNTERS FIRST REL PLAYER FIRST REL SELF FIRST REL COUNTERS LAST REL PLAYER LAST REL SELF LAST RESETVIEW RESTORE "label" # RESTORE PLAYER POSITION [!] RESTORE PLAYER POSITION # [!] RESTORE PLAYER POSITION # DUPLICATE SELF [!] ROTATECW ROTATECCW SAM # "file" SAVE PLAYER POSITION SAVE PLAYER POSITION # SCROLL CHAR [char] [dir] SCROLLARROW COLOR [color] SCROLLBASE COLOR [color] SCROLLCORNER COLOR [color] SCROLLPOINTER COLOR [color] SCROLLTITLE COLOR [color] SCROLLVIEW [dir] # SCROLLVIEW POSITION # # SEND # # "label" SEND "Robot" "label" SEND [dir] "label" SEND [dir] PLAYER "label" SET "counter" # SET "counter" RANDOM # # SET "$string" "text" SET "$string1" "$string2" SET "$string" # SET COLOR # # # # SET EDGE COLOR [color] SET MAXHEALTH # SET MESG COLUMN # SFX # SHOOT [dir] SHOOTMISSILE [dir] SHOOTSEEKER [dir] SLOWTIME # SPITFIRE [dir] STATUS COUNTER # "counter" SWAP WORLD "file" SWITCH [dir] [dir] TAKE # [item] TAKE # [item] "label" TAKEKEY [color] TAKEKEY [color] "label" TELEPORT PLAYER "string" # # [!] TRADE # [item] # [item] "label" TRY [dir] "label" [!] UNLOCKPLAYER UNLOCKSCROLL UNLOCKSELF VIEWPORT # # VIEWPORT SIZE # # VOLUME # WAIT # [!] WAIT MOD FADE [!] WAIT PLAY [!] WAIT PLAY "string" [!] WALK [dir] WIND # WRITE OVERLAY [color] "string" # # ZAP "label" #

Command Descriptions

* "string" This command displays the given string as a message on the message line, which by default is at the bottom of the screen and centered. This command will cycle the message in different colors by default, but will also accept ~ and @ color codes. Using the newline char (\n) in this string will cause the message line to span another line underneath, allowing multi-line messages. A * message will stay on screen on that board for either 160 cycles, or until replaced by another * message, or until a CLEAR MESG command is ran, whichever comes first. CLEAR MESG Strings, Special Formatting, and Their Place in Robotic / "string" [!] PERSISTENT GO "string" [!] GO [dir] # [!] Use / followed by a string to move the Robot around the board. The string must consist of a series of N, S, E, W, and I. NSEW will move the Robot in that direction, and I will wait for one cycle. One action is performed each cycle. Use PERSISTENT GO in the same way as /. However, if the Robot attempts to move in a given direction and it cannot, the Robot will wait until it can before moving on to the next symbol. Use GO to move in a single direction for a given number of spaces (limited to 255; higher numbers and negatives wrap). These commands can be used concurrently with WALK [dir], allowing Robots to move in double-speed steps. However, this can only happen when the commands are in the same cycle and if the given string/number for the moving command is small. WALK [dir] Directions : "label" A : is used to denote actual LABELS within a Robotic program. These labels are used as points within the program to branch to when a Robot receives a message from another Robot, goes to a label of its own, or otherwise receives an external message. Label names can be any length and consist of any characters. They are not case-sensitive, and they can not take interpreted counters (e.g. : "&label&"). A Robot can have multiple active labels with the same name. In these cases, the topmost of these labels in the Robot's code is the one that is triggered. There are several label names that are automatically jumped to under certain conditions. These are detailed in the Built-in Labels section. Labels starting with a pound sign/hash (#) are subroutines. See the Subroutine section for more information. Subroutines Built-in Labels GOTO "label" This will attempt to send the current Robot to the label given; if the label does not exist, this command does nothing. If the label begins with a # it will go to it as a subroutine. Several (but not all!) built-in labels also have subroutine versions. GOTO "#return" GOTO "#top" This will send the current Robot to the line after the next-highest subroutine call and to the line after the first subroutine call, respectively. Subroutines SEND "Robot" "label" SEND [dir] "label" SEND [dir] PLAYER "label" SEND # # "label" Use SEND to send another Robot to the label given. This is called "messaging" a Robot, and the label given is the "message". The target Robot can be given one of four ways, as listed above respectively: 1. State the target Robot's name. Use "ALL" in place of the Robot name to message all Robots (including the Robot doing the send). Set LOCKSELF beforehand to prevent sending to yourself when sending to "ALL". 2. State the direction of the target Robot, relative to the source Robot. 3. State the direction of the target Robot, relative to the player. 4. State the x,y coordinates of the target Robot. Directions LOCKSELF [ "string" & "string" % "string" ? "label" "string" ? "counter" "label" "string" Use these commands to bring up a message box during the game containing the given text. The message box will contain all consecutive lines using the commands [, &, %, or ?. Blank lines and labels will be skipped over. The box message commands are as follows: [ will simply display the given message. & will display the given message, centered within the box. % will display the given message, but will parse color codes. ? will display an option that will send the current Robot to the given label when selected. The counter is optional. If a counter is included, the option will only be shown if the counter is NOT zero. All box-message commands can use ~ and @ color codes, EXCEPT for [. The message box can show up to 64 characters per line; any characters past that will not be shown. NOTE: Take care when using any of these commands in a loop (and be especially vigilant of possible unintended loops). Looping these commands without any WAITs or similar cycle-breaking commands (or repeatedly jumping to a label with said command) can cause the dialogue box to re-appear as soon as it is closed, making it very hard to resume normal action. Counters, Built-in Counters and Local Counters Strings, Special Formatting, and Their Place in Robotic . "string" This command does nothing. It is used for comments and other notes you may wish to make within your Robots. There is one exception - If "string" begins with a @. (see next) You may comment or de-comment lines of code automatically with the Ctrl+C command (comment mark). Comments can nonetheless have an actual effect on code speed, as they must be interpreted when encountered. . "@string" If a comment's string begins with a @, then the rest of the string becomes the new name for the Robot. For example, "@Hiya" would name the Robot "Hiya". This clips at the first 14 characters of the string; for example, . "@Robothasanewname" would cut off and rename the Robot "Robothasanewna". END [!] This command ends the Robot's program. The Robot will not run any further commands until an external event affects it. DIE DIE ITEM These commands destroy the Robot forever. DIE ITEM will also put the player at the location the Robot previously occupied, which is useful for creating Robots that simulate collectible items. WAIT # [!] This command will cause the Robot to do absolutely nothing for a given number of cycles (limited to 255; values over this will wrap around). Robots will still respond to label sends when waiting, provided that the Robot is not locked. Cycles and Board Scans - How MZX Processes Robots CHAR [char] This command will change the Robot's character (appearance) to the character given. COLOR [color] This command will change the Robot's color to the color given. Colors SET "counter" # SET "counter" RANDOM # # These commands set a counter to a certain value. Counters are internal variables that can be changed through Robots. They are usually used for custom purposes, although there are many counters with pre-defined uses as well, such as "Gems". The RANDOM version will set the counter to a random number within the given range, inclusive (first number minimum, second maximum). SET "$string" "text" SET "$string" "$string2" SET "$string" number These commands set strings to a certain value: a line of text, another string or a number, respectively. Counters, Built-in Counters and Local Counters INC "counter" # DEC "counter" # INC "counter" RANDOM # # DEC "counter" RANDOM # # These commands will increase or decrease a given counter or string by a given amount. The RANDOM versions will increase or decrease by a random number within the given range, inclusive (first number minimum, second maximum). Counters, Built-in Counters and Local Counters IF "counter" !<>= # "label" This command tests to see if a given counter is equal to, less than, etc. another counter or value. If the conditional is met, the current Robot is sent to the given label. The following conditionals are allowed: = Equal, < Less than, > Greater than, <= Less than/equal, >= Greater than/equal, != (also <>) Not equal. Counters, Built-in Counters and Local Counters CYCLE # [!] This command changes the Robot's speed to one Robot cycle for every given number of update cycles. An update cycle is how often everything onscreen is updated, such as most enemies. Every time a given Robot gets to run commands is called a cycle in terms of that Robot; most commands can run several times in a single Robot cycle. (CYCLE # values are limited to 255; values over this will wrap around.) Cycles and Board Scans - How MZX Processes Robots ENDLIFE ENDGAME These commands will end the player's current life or the entire game, just as if the player died or lost all of its lives. WALK [dir] This will cause the Robot to attempt to move one space in the given direction every cycle. Use a direction of IDLE to turn walking off. This can be used concurrently with GO [dir] # and its relatives to make Robots move in double-speed steps. GO [dir] # / "string" PERSISTENT GO "string" Directions SHOOT [dir] SHOOTMISSILE [dir] SHOOTSEEKER [dir] SPITFIRE [dir] These four commands all shoot a weapon in the given direction: A bullet, a missile, a seeker, or shooting fire, respectively. Directions TRY [dir] "label" [!] This will have the Robot attempt to move in the given direction. If it can, it will. If it can't, it will jump to the given label. Directions BECOME [color] [thing] [param] The Robot will end its program permanently, and instead become a specified object with a given color and parameter. NOTE: Becoming another Robot type will not destroy the program, but there are far better commands for doing this: BECOME PUSHABLE and BECOME NONPUSHABLE. Colors BECOME NONPUSHABLE BECOME PUSHABLE CHANGE [color] [thing] [param] [color] [thing] [param] All on-board objects of the first given type will become objects of the second given type. Colors PUT [color] [thing] [param] # # PUT [color] [thing] [param] [dir] PUT [color] [thing] [param] [dir] PLAYER This will put a given object somewhere on the board. If anything else is in that spot and layer, it will be placed under the new object, if possible; otherwise, it will be replaced by this object. (The exception is if the object were to replace the player; in this case, nothing happens.) The target location can be given in one of three ways: 1. State the target x,y coordinates. 2. State the direction, relative to the Robot. 3. State the direction, relative to the player. Note that this command is not suitable for placing Robots. For moving a Robot, use GOTOXY # #; for placing a copy of a Robot, use DUPLICATE SELF # # or DUPLICATE SELF [dir]. Colors Directions MOD "file" This command loads the given module/OGG/SAM file as background music. These files also can be loaded from a subdirectory with the syntax of ""dir"\\"file"" or ""dir"/"file"" (without the inner quotes). MOD, unlike SAM, will loop audio, and is affected by related commands like VOLUME and MOD ORDER. NOTE: placing * at the end of the filename will set the current mod to the given filename, but institute MOD "*" (see below) for subsequent board visits. MOD "*" Sets the board's currently running music to "wildcard". This means that it will continue to play whatever was last playing. This setting does not "lock" the board's music to any one song; for instance, if 1.mod was playing on the last board, mod "*" will continue playing 1.mod, but if the player then goes to a board playing 2.mod and jumps back to the mod "*" board from there, 2.mod will continue playing, and 1.mod will not start. Sound and Music Strings, Special Formatting, and Their Place in Robotic SAM # "file" Plays the given SAM/WAV/OGG/module file at a given frequency. These files also can be loaded from a subdirectory with the syntax of ""dir"\\"file"" or ""dir"/"file"" (without the inner quotes). 0 plays the file at natural frequency. Music loaded with the SAM command will not loop. Sound and Music END MOD END SAM END PLAY Ends the playing of the current audio set by MOD "file", the current audio set by SAM # "file", or the currently playing PLAY statement (respectively). Sound and Music DOUBLE "counter" HALF "counter" Doubles or halves (rounding down) the value of the given counter, respectively. Counters, Built-in Counters and Local Counters MULTIPLY "counter" # DIVIDE "counter" # MODULO "counter" # Multiplies, divides, or performs a modulo on the value of the given counter by the given number (rounding down), and then sets the counter to the result. To modulo is to set to the remainder when dividing. Example: 7 modulo 3 is equal to 1, since 7 divided by 3 gives a remainder of 1. NOTE: The modulo command may output different numbers compared to the modulo expression function; they may act differently when negative numbers are involved. For the modulo command, the output will give results similar to when both numbers are positive, but will simply have the sign of the dividend (i.e. a truncated modulo). Counters, Built-in Counters and Local Counters PLAY "string" PLAY SFX "string" WAIT PLAY "string" [!] These all play sound effects, PC speaker notes, or a combination thereof. PLAY SFX will only play if there are no other notes currently playing, while PLAY will add its notes to the end of the current sound effects queue. WAIT PLAY will wait until the queue is almost empty before adding its notes. Sound and Music SFX # Plays the given built-in sound effect. Sound and Music EXPLODE # The Robot will explode, destroying it and its program forever. The radius of the explosion in characters is stated in the command, with a maximum of 16 characters. COLOR FADE OUT COLOR FADE IN Fades the palette out to black or in to full color. Fading in will not work if you haven't faded out, and fades affect neither the current palette nor current intensities. GOTOXY # # [!] The Robot will go to the given x,y coordinates on the current board, destroying anything there that cannot go on the under layer. If the player is at those coordinates, the Robot ignores the command. LOOP START LOOP # ABORT LOOP These three commands define a loop, which is a sequence of commands to be repeated. LOOP START marks the start of a loop. LOOP # will loop back to LOOP START the given number of times. ABORT LOOP will jump out of the loop, to the command after LOOP #. The loop count is kept in the local counter "loopcount". Make sure your number in LOOP # is one less than the amount for which you actually want to loop, as the initial iteration before first hitting LOOP # is not counted in the number. NOTE: Using ABORT LOOP outside of the loop (that is, outside of any block of code starting with LOOP START and ending in LOOP #) is very highly unadvised and will most likely cause unintended effects. Counters, Built-in Counters and Local Counters MOVE PLAYER [dir] [!] MOVE PLAYER [dir] "label" [!] This attempts to move the player in the given direction. If the player is blocked, and the command contains a label, the Robot will jump to that label. Directions PLAYER CHAR [char] PLAYER CHAR [dir] [char] Changes the character (appearance) of the player. The second form allows you to change the appearance of one of the four facing directions at a time, while the first form changes all four directions at once. Directions PLAYERCOLOR [color] Changes the color of the player. Colors PUT PLAYER # # [!] PUT PLAYER [dir] [!] The player will go to the given x,y coordinates or in the given direction immediately relative to the Robot, destroying anything there that cannot go on the under layer. If the x,y coordinates of the put command are out of bounds, the player is moved to the closest-matching coordinates, and if a directional put is out of bounds it is ignored. Directions PUT "@FILENAME.XXX" Image_File [param] # # Places an MZM of the given filename. These files also can be loaded from a subdirectory with the syntax of ""@dir"\\"file"" or ""@dir"/"file"" (without the inner quotes). The @ is REQUIRED. The numbers mark the destination x,y coordinates of the MZM's upper-left corner; the parameter determines the placement of the MZM (00 = board, 01 = overlay, 02 = vlayer). See the MZM section for further details. Using MZMs PUT [color] Sprite [param] # # Puts a sprite on the board. The param number is the number of the sprite in hex (auto-converted from decimal). If the color is c?? then the sprite is drawn with its reference's colors; otherwise, it's painted with the given colors. # # marks the x,y coordinates of the sprite's upper-left corner. See the Spites section for further details. Sprites LOCKSELF UNLOCKSELF Locks or unlocks, respectively, the current Robot. When a Robot is locked, no external messages will be acknowledged - Only internal GOTOs, etc. will be processed. (Built-in label calls to "thud" and "edge" are exceptions.) VOLUME # Changes the volume of the MOD playing, from 0 (silent) to 255. This change is specific to the current board. The default when music is loaded is 255. COPYROBOT "Robot" [!] COPYROBOT # # [!] COPYROBOT [dir] [!] The current Robot becomes an exact duplicate of the noted Robot, starting from the beginning of the noted Robot's code. Note that if the source Robot was previously ended with the END command, or was at the end of its program, the destination Robot will be in an ended state as well. The Robot to copy can be stated in one of three ways: 1. State the target Robot's name. If multiple Robots on the same board share the same name, the Robot chosen may vary, so using this command in that situation is not advised. 2. State the x,y coordinates of target Robot. 3. State the direction of target Robot relative to the source Robot. NOTE: Exact means just that, EXACT, down to its states and the values of local counters. The only thing that will differ will be the robot_id. If one requires a group of objects differing only in name, COPYROBOT is generally unsuitable for this purpose because even the Robot name is copied. Directions DUPLICATE SELF # # DUPLICATE SELF [dir] The current Robot creates an exact duplicate of itself (including local counter values!) and places it at the noted x,y coordinates or relative direction. That Robot then begins its program at the first command. Directions The remaining Robotic commands are covered in another section. Command Reference Part II Robotic Reference Manual Table of Contents

Command Reference Part II

Command Reference (Part I) BULLETCOLOR [color] Changes the color of all bullets. Colors PLAYER BULLETCOLOR [color] ENEMY BULLETCOLOR [color] NEUTRAL BULLETCOLOR [color] Changes the color of a specific type of bullet: Player, Enemy, or Neutral (ricocheted/Robot) bullets. Colors Bullet Types BULLETN [char] BULLETS [char] BULLETE [char] BULLETW [char] Changes the character (appearance) of one of the four directions of bullet, across all three types. PLAYER BULLETN [char] PLAYER BULLETS [char] PLAYER BULLETE [char] PLAYER BULLETW [char] ENEMY BULLETE [char] ENEMY BULLETN [char] ENEMY BULLETS [char] ENEMY BULLETW [char] NEUTRAL BULLETN [char] NEUTRAL BULLETS [char] NEUTRAL BULLETE [char] NEUTRAL BULLETW [char] Changes the character of one of the four directions of bullet, for one of the three types of bullet: Player, Enemy, or Neutral (ricocheted/Robot) bullets, respectively. Bullet Types BECOME PUSHABLE BECOME NONPUSHABLE The Robot becomes a pushable or nonpushable Robot, respectively. IF [condition] "label" IF NOT [condition] "label" These test whether a given condition is present or not, and if it is, the first will jump to the given label. If it isn't, the second will jump to the given label. Conditions are covered in another section. Conditions IF # # "label" Jumps to the given label if the current Robot is at the x,y coordinates given. IF [dir] PLAYER [color] [thing] [param] "label" Jumps to the given label if the given thing is the given direction relative to the player. Colors Directions IF [color] [thing] [param] # # "label" IF [color] [thing] [param] [dir] "label" IF NOT [color] [thing] [param] [dir] "label" Jumps to a label if a given thing is at the given x,y coordinates or to the immediate given direction of the current Robot. The third form jumps if the thing is NOT in the immediate given direction. Colors Directions IF ALIGNEDROBOT "Robot" "label" Jumps to the given label if the current Robot is aligned either vertically or horizontally with the named Robot. IF ANY [color] [thing] [param] "label" IF NO [color] [thing] [param] "label" If there are ANY of a given thing with the given color and parameter on the current board, jumps to the given label. The second form triggers on the absence of the given thing. Colors IF PLAYER # # "label" If the player is at the given x,y coordinates, jump to the given label. GIVEKEY [color] GIVEKEY [color] "label" TAKEKEY [color] TAKEKEY [color] "label" Attempts to give keys to or take keys from the player. The forms without labels will give or take the key if possible, otherwise they will do nothing. The forms with labels will jump to the labels if the Robot tries to give a key when the player has no room for keys, or if the Robot tries to take a key the player doesn't have. Colors GIVE # [item] TAKE # [item] TAKE # [item] "label" Gives or takes a number of a certain item. If the player does not have enough of this type of item to take, nothing is taken. The third form jumps to a given label if the player doesn't have enough of the stated item. TRADE # [item] # [item] "label" Gives the player a number of the first item and takes a number of the second item in exchange. If the player doesn't have enough of the second item, this command jumps to the given label and has no other effect. This command eases the writing of simple shops and vendors. Keep in mind that trades involving healths and lives can end up with either at 0, leading to potential deaths and endgames if the player has the exact amount of health/lives being traded away. LOCKPLAYER LOCKPLAYER NS LOCKPLAYER EW LOCKPLAYER ATTACK UNLOCKPLAYER The first four commands lock the player, preventing the player from doing any moving and attacking (i.e. default shooting and bombing), from moving north or south, from moving east or west, or from attacking, respectively. The fifth command will clear all locks on the player, allowing free movement and attacking. These have no relation to the Board Info options "Can Bomb" and "Can Shoot". Player locking is local, only affecting the current board. Locking the player will also prevent messages related to locked actions from showing (such as bomb switch messages or a "Can't {shoot/bomb} here!" message when the player is attack locked). Also, locking the player will not cause the relevant input to be ignored completely. MegaZeux will still detect that you are pressing keys, even if the player is forbidden from responding to them, and will act accordingly. In short, even if a player is locked, Robots that take directional and space/delete inputs will still act the same. BOARD [dir] "string" BOARD [dir] NONE Changes the board exit in the given direction to lead to the given board or to nowhere. Unlike with the Board Exits menu, linking exits to the title board with this command is allowed. Directions Strings, Special Formatting, and Their Place in Robotic ZAP "label" # RESTORE "label" # | "label" ZAP will scan the Robotic program from the top down, changing a given number of instances of the stated label to ZAPPED labels. A ZAPPED label is inactive - it cannot be jumped to or sent to under any circumstance. This has two uses: It will prevent interference from a certain outside event, and it allows multiple instances of the same label. For example, you could have four SHOT labels in a row, ZAP one each time the Robot was shot, and jump back to normal code, but have a fifth SHOT label lead to an explosion. RESTORE will scan the Robotic program from the bottom up, changing a given number of the stated ZAPPED labels back to a normal label. Essentially, this means that the most recently ZAPPED labels are restored first. Both ZAP and RESTORE can have a number larger than the number of instances of the stated label. The final command, |, is a pre-ZAPPED label, allowing you to have labels in your Robotic programs that are already ZAPPED and inactive. REL COUNTERS REL PLAYER REL SELF PLEASE NOTE: Judicious use of expressions and certain counters (THISX/THISY/PLAYERX/PLAYERY) is a less cumbersome alternative to using the REL set of commands, and is generally preferred. These are special types of commands, called PREFIXES. Prefixes don't do a thing by themselves, but when placed before another command that uses x,y coordinates, they change the origin of the x,y coordinate system for that ONE following command. REL COUNTERS moves the origin to the x,y location stated in the counters XPOS and YPOS. REL PLAYER moves the origin to the x,y of the player. REL SELF moves the origin to the x,y of the current Robot. The movement of the origin changes the (0,0) coordinates from the upper left of the board to somewhere else, effectively adding that x,y position to any coordinates entered. For example, if the Robot is at the (5,5) position and uses REL SELF on the coordinates (2,2), it will effectively act on coordinates (7,7). If the player is at the (7,2) position and a Robot uses REL PLAYER on coordinates (-3,6), the Robot will effectively act on coordinates (4,8). Let's look at some examples. PUT c0E GEM p?? 5 5 This places a gem at the x,y coordinates (5,5). REL PLAYER PUT c0E GEM p?? 5 5 This places a gem 5 spaces to the right and 5 spaces below where the player currently is, or at the board edge if it is under 5 spaces to the right/below the player. REL SELF PUT c0E GEM p?? -2 -3 This places a gem 2 spaces to the left and 3 spaces above where this Robot currently is, or at the board edge if it is under 2 spaces to the left or 3 spaces above the Robot. REL COUNTERS PUT c0E GEM p?? 1 -4 This places a gem at the coordinates (XPOS+1,YPOS-4), or on a board edge if either of these coordinates would extend past the board. XPOS and YPOS are counters with amounts defined by the user before using this command. Prefixes only have an effect on the very next command. This includes comments. Prefixes also affect two (and only two) other things. The built in counters THISX and THISY will be offset by a prefix, and the command IF [dir] (NOT) BLOCKED will check next to the player or next to the position noted by the counters if a prefix is present. See their relevant sections for details. REL COUNTERS FIRST REL PLAYER FIRST REL SELF FIRST REL COUNTERS LAST REL PLAYER LAST REL SELF LAST These prefixes are similar to the above prefixes, but they only affect the first or last x,y pair of coordinates in the next command. For example, COPY accepts two pairs of coordinates. If you precede it with the following: REL PLAYER FIRST REL SELF LAST Then the coordinates of the object being copied will be relative to the player, and the destination coordinates will be relative to the Robot. There is one other difference with these commands - REL COUNTERS FIRST works off of the counters FIRSTXPOS and FIRSTYPOS, and REL COUNTERS LAST works off of the counters LASTXPOS and LASTYPOS. JUMP MOD ORDER # The current module jumps to the stated module order, if applicable. For example, JUMP MOD ORDER 3 will begin playing the third order in the module, which is the fourth section of the module. Sometimes your music editor will refer to this as the 'Pattern' or 'Track'. With OGG music, this command makes a jump to the stated frame. Sound and Music LAYBOMB [dir] LAYBOMB HIGH [dir] Places a bomb (high strength for the second form) next to the Robot in the given direction. Use a direction of UNDER or BENEATH to place the bomb underneath the Robot. Directions LAZERWALL [dir] # The Robot shoots a lazer in the given direction, and the lazer has the color of the Robot and the duration given. The number of cycles the lazer is active is duration x 2. Directions COPY # # # # COPY [dir] [dir] SWITCH [dir] [dir] Copies the thing at one location to another, with the location stated through x,y coordinates or directions relative to the current Robot. The third command will swap the things in the two directions. COPY can copy between different layers by using the appropriate prefixes. Prefix coordinate numbers with "+" to indicate overlay coordinates, and with "#" to indicate vlayer coordinates. NOTE: DO NOT normally use COPY # # # # to copy Robots; use DUPLICATE SELF or COPYROBOT. It is useful for copying by Robot id, however; use COPY rN.thisx and rN.thisy as the first pair of coordinates. Using COPY # # # # on a Robot will no longer cause the Robot copy to start where the parent left off, and will have new Robots start at the first line. Rn.<counter> Robotic Usages That Should be Avoided Directions COPY BLOCK # # # # # # COPY OVERLAY BLOCK # # # # # # Copies a block of things from one location on the board or overlay to another section. The first two numbers state the upper-left corner of the block to be copied, the second two numbers state the size of the block, and the third two numbers state the destination block's upper-left corner. COPY BLOCK and COPY OVERLAY BLOCK can copy from board to overlay and from overlay to board (respectively). The last two numbers must be prefixed by plus signs, like so: COPY BLOCK # # # # "+#" "+#" COPY OVERLAY BLOCK # # # # "+#" "+#" Valid Robotic block copies from the overlay to the board are always CustomBlocks. Editing and Using the Overlay COPY BLOCK # # # # "#x" "#y" COPY OVERLAY BLOCK # # # # "#x" "#y" These commands copy from the board or overlay (respectively) to the vlayer. The first two numbers are the x,y coordinates of the upper-left corner of the block to be copied; the next two numbers are the respective width and height of the block; the "#x" and "#y" are the x,y coordinates of the destination block's upper-left corner. The pound sign in "#x" and "#y" MUST be included. COPY BLOCK "#x" "#y" # # # # COPY OVERLAY BLOCK "#x" "#y" # # # # These commands similarly copy from the vlayer to the board or overlay (respectively). Editing and Using the Overlay The Vlayer and Its Uses COPY (OVERLAY) BLOCK "#x1" "#y1" # # "#x2" "#y2" This command copies a block from the vlayer and copies it onto a different spot on the vlayer. "#x1" and "#y1" are the x,y coordinates of the upper-left corner of the copied block; the next two numbers are the respective width and height of the copied area; "#x2" and "#y2" are the x,y coordinates of the destination block's upper-left corner. The pound sign in #x1", "#y1", "#x2" and "#y2" MUST be included. The Vlayer and Its Uses COPY BLOCK # # # # "@filename" # COPY OVERLAY BLOCK # # # # "@filename" # These commands copy from the board or overlay (respectively) to an MZM. The first two numbers are the x,y coordinates of the block's upper-left corner; # # is the respective width and height of the block; filename is the name of the file - the @ is required. Finally, the last number determines the MZM type. 1 saves as layer; 0 saves as board. 0 is integral for copying non-graphical data (primarily Robots); 1 is proper for copying graphical data, as the block's appearance will stay as exactly as it was when saved. Using MZMs Editing and Using the Overlay COPY (OVERLAY) BLOCK "#x" "#y" # # "@filename" # These commands act much like the above two commands, but they copy from the vlayer to an MZM instead. Using MZMs The Vlayer and Its Uses COPY BLOCK # # # # "$string" # COPY OVERLAY BLOCK # # # # "$string" # COPY (OVERLAY) BLOCK "#x" "#y" # # "$string" # These commands copy information from the board, overlay, or vlayer (respectively) to a given string. The first two numbers are the x,y coordinates of the upper-left corner of the block; the third and fourth are its respective width and height; the last is the terminating character's char value (i.e. a number from 0-255). The operation will end before all characters in the given range are read if either the parameter matching the terminating character, or a parameter of p00, is found. For the vlayer command, the pound sign is REQUIRED. Strings, Special Formatting, and Their Place in Robotic Editing and Using the Overlay SAVE PLAYER POSITION SAVE PLAYER POSITION # Saves the player's coordinates and board in one of eight internal slots (1-8). If no number is given, slot one is used. RESTORE PLAYER POSITION [!] RESTORE PLAYER POSITION # [!] RESTORE PLAYER POSITION # DUPLICATE SELF [!] Relocates the player to the coordinates and board stored in the given slot, or slot number one if none is given. The third form also duplicates the current Robot where the player used to be; this Robot then starts its program at the first command. This command will do transition fades on activation, even if the destination is the same board. EXCHANGE PLAYER POSITION [!] EXCHANGE PLAYER POSITION # [!] EXCHANGE PLAYER POSITION # DUPLICATE SELF [!] Exchanges the player's current coordinates and board with the coordinates and board stored in the given slot, or slot number one if none is given. The third form also duplicates the current Robot where the player used to be; this Robot then starts its program at the first command. This command will do transition fades on activation, even if the destination is the same board. FILLHEALTH The player's health is filled to its maximum. CLEAR MESG The message line, if currently displayed, stops displaying its current message. MESSAGE ROW # The top row of the message line is moved to the stated row. The range is 0 to 24. SET MESG COLUMN # Changes the message line to display its messages starting from the given column. The range is 0 to 79 and the changes affect each row. (The actual message will start at this location, not the message edge.) CENTER MESG Changes the message line to center its messages on its rows. LOAD CHAR SET "file" LOAD PALETTE "file" Loads in the specified character set or palette, exported using Alt+X from the world editor. The new character set or palette is permanent and affects the entire world until a new one is loaded. These files also can be loaded from a subdirectory with the syntax of ""dir"\\"file"" or ""dir"/"file"" (without the inner quotes). Character sets can be loaded to the middle of the current charset by prefixing the "file" name with +offset, where offset is a hexadecimal number, or @offset where offset is a decimal number. Up to 14 additional charsets can be loaded for use with unbound sprites. To set and access these, set the decimal offset number to (256*extra charset number); hexadecimal offsetting cannot access additional charsets. Naturally, offsets within these charsets can be set as well by adding the desired offset value to these numbers. These commands can also take string inputs in place of hard-coded filenames. Partial Character Sets Strings, Special Formatting, and Their Place in Robotic TELEPORT PLAYER "string" # # [!] Teleports the player to the given board at the stated x,y coordinates. This happens instantaneously, even if this causes a move between boards. Same-board TELEPORT PLAYER will trigger any "justloaded" labels and reset board time limits and entry positions, but will not otherwise act as a new board entry. Strings, Special Formatting, and Their Place in Robotic CHANGE OVERLAY [color] [char] [color] [char] CHANGE OVERLAY [color] [color] All of the stated character and color on the overlay are changed to the new character and color. The second form doesn't care about the character, only the color. Colors Editing and Using the Overlay MOVE ALL [color] [thing] [param] [dir] [!] All instances of the stated thing with the color and parameter given are moved in the given direction. This can force objects onto lava that normally don't go onto lava, but cannot force any objects onto goop. Colors Directions OPEN [dir] If there is a gate or door in the given direction, it will be opened. If the door is going to open towards the Robot, the Robot will be pushed out of the way if necessary and possible. It is suggested to wait a couple cycles before then continuing on through the door. (Gates aren't a problem.) If the gate or door is locked, it will be treated as if the player attempted to open it. This means that whether the door is opened or not depends on the player's held keys, and if the Robot unlocks the door, the player will lose the relevant key. Directions MOD SAM # # Plays a sample (instrument) from the current module file. The first number states the frequency at which to play it; the second is the number of the sample, from 1 on. This command will not work in current versions. Support for older worlds using this command is implemented only for the XMP module engine (the engine used for most release builds). Sound and Music LOCKSCROLL UNLOCKSCROLL Locks or unlocks scrolling on the current board. When scrolling is locked, the view will remain showing the same thing, even if the player moves. The screen will not scroll. CHAR EDIT [char] # # # # # # # # # # # # # # Changes the appearance of the given character, using a 14-number code of 8-bit numbers derived from which pixels are set per horizontal line. To insert these codes easily, use F5 in the Robot editor, select the desired character, and press ESC. MOD FADE IN "file" Fades in the stated module/OGG music file, from 0 volume to 255 volume. These files also can be loaded from a subdirectory with the syntax of ""dir"\\"file"" or ""dir"/"file"" (without the inner quotes). Sound and Music Strings, Special Formatting, and Their Place in Robotic MOD FADE OUT Fades out the current module/OGG music file, from the current volume to 0 volume. Although the mod will be inaudible, it will still be the current music file after the fade out. Sound and Music MOD FADE # # Fades the current module/OGG music file to a given volume at the given rate. The first number is the target volume, the second number is the speed at which to fade. All negative numbers and numbers over 255 will wrap around. Sound and Music MISSILECOLOR [color] Changes the color of all missiles fired from that point on. Colors PUSH [dir] Pushes anything next to the Robot in the given direction one space forward, if the object in that direction is pushable. The Robot itself does not move. Directions SET EDGE COLOR [color] Changes the color of the edging shown around the viewport. Colors SET MAXHEALTH # Changes the player's health limit, or maximum health rating. WAIT MOD FADE [!] Waits for the module/OGG music to finish its fading. Does nothing if music is not fading. (see MOD FADE IN, MOD FADE OUT, and MOD FADE) Sound and Music MOD FADE IN "file" MOD FADE OUT MOD FADE # # WAIT PLAY [!] Waits for all queued sound effects, if any, to finish playing. Sound and Music ASK "string" Brings up a dialog box asking the player a question. The player can select YES or NO. The Robot is then sent to either the YES or NO label, depending on the choice. If the player presses ESC, the NO label is used. Strings, Special Formatting, and Their Place in Robotic AVALANCHE Enacts the Avalanche potion/ring effect, placing boulders randomly about the board. Often precedes the CHANGE c?? Boulder p?? to c?? Explosion p?? command. Potion and Ring Effects BECOME LAVAWALKER BECOME NONLAVAWALKER Sets whether the current Robot can or cannot move on lava. Robots can always move over fire. BLIND # FIREWALKER # FREEZETIME # SLOWTIME # WIND # The stated potion/ring effect activates for the given number of cycles. Potion/ring effects are global; that is, they affect the entire world. The only exception is with the global Robot, as FREEZETIME and SLOWTIME commands do not affect it. The Global Potion and Ring Effects CHANGE CHAR ID # [char] Changes the character/color/number at the stated (numeric) location within the CHAR ID table. The CHAR ID table is internal and is covered in another section. CHANGE CHAR ID - The CHAR ID Table CHANGE SFX # "string" The sound effect referenced by the given number is changed to the new string. The numbers refer to the sound events editable through ALT+F. Sound and Music CHANGE THIN ARROW CHAR [dir] [char] CHANGE THICK ARROW CHAR [dir] [char] Changes the character used to represent thin arrows (for guns) or thick arrows (for pushers and spikes) for the specified direction. Directions INPUT STRING "string" Asks the player to input a string, presenting the given string as a prompt. The inputted string is stored in memory. This string can be displayed within box messages or on the message row by using &INPUT& within a message. Inputted strings are local to the current board. Strings, Special Formatting, and Their Place in Robotic IF STRING "string" "label" IF STRING NOT "string" "label" Jumps to the given label if the inputted string is or is not equal to the given string. Case is ignored. IF STRING MATCHES "string" "label" If the string matches a given pattern, jump to the given label. (Case is ignored.) The pattern is a series of characters and symbols to match. Characters must match exactly. The following symbols apply: # matches any number from 0-9 _ matches any letter from A-Z or a-z ? matches any character * matches the remainder of the input string IF FIRST STRING "string" "label" If the first word in the inputted string (i.e. everything up to the first space (char 32) or end of input) matches the given string, jump to the given label. CLIP INPUT This command chops off the first word of the inputted string (everything before and including the first instance of a space, aka char 32). For example, "Hello there" will now read in memory as "there". INC "$string" "text" INC "$string" "$string2" This command appends the given text or string to the end of a given string. DEC "$string" # This command clips the given string by the amount of characters given. Decreasing by negative numbers will not add characters to the string. IF "$string" (equality) # "label" IF "$string" (equality) "text" "label" IF "$string" (equality) "$string2" "label" These commands jump to a given label if the string matches the given equality conditions (ONLY equal or not equal; others such as less than are automatically parsed as FALSE). These commands compare the given string to a number, a line of text, or another string respectively. IF c?? Sprite_Colliding pNN x y "label" This command determines whether the sprite numbered NN would collide if the sprite is moved by x horizontally and y vertically. If it would, the program goes to the given label and spr_clistN counters are set to the detected collisions. c values other than c?? check if the sprite would collide with anything currently at absolute x,y coordinates instead. If the sprite numbered NN is unbound, movement amounts and absolute coordinates will be in pixels. IF c?? Sprite pNN x y "label" This command checks if the sprite numbered NN is currently at the location x,y; if it is, the program goes to the given label. For multi-character sprites, the label is jumped to if any part of the sprite is at the given coordinates. Use p?? to check for any sprite. If p?? is used, SPR_NUM is also set to the lowest sprite number at that location (if any). For static sprites, this check is valid against the coordinates where they visually appear, not their actual locations. COLOR INTENSITY # PERCENT COLOR INTENSITY # # PERCENT The first command changes the intensity of the entire palette from 0 to 255 percent (100 percent is a palette's default). The second command only changes one color, with the first number being the chosen color and the second number the intensity. COPY CHAR [char] [char] The character picture of the first character is copied to the second character. This command can access extended character sets; use expressions or counters to access them. DISABLE MESG EDGE ENABLE MESG EDGE Disables or enables the edging on the message line. When enabled, all messages have a space (char 32) tacked onto each end for display clarity. This is enabled by default. DISABLE SAVING ENABLE SAVING ENABLE SENSORONLY SAVING Disables or enables manual saving on this board, or enables manual saving on sensors only. Sensors FLIP CHAR [char] [dir] The character picture of the stated character is flipped vertically if the direction is north/south, or horizontally if the direction is east/west. Directions OVERLAY ON OVERLAY STATIC OVERLAY TRANSPARENT Turns the overlay on (to normal mode), to static mode, or to transparent mode. Editing and Using the Overlay ROTATECW ROTATECCW Rotates all pushable items around the Robot in a clockwise or counter-clockwise direction, respectively. This is done in the same manner as a CW Rotate or CCW Rotate object, except that these commands rotate objects only one space. SCROLL CHAR [char] [dir] The character picture of the stated character is scrolled one pixel in the given direction, with wraparound in effect. This command will not work as expected in SMZX modes. Directions SCROLLARROW COLOR [color] SCROLLBASE COLOR [color] SCROLLCORNER COLOR [color] SCROLLPOINTER COLOR [color] SCROLLTITLE COLOR [color] Changes the color used to represent a specific element of the Scroll and box-message system: ARROW = The arrows used to denote options BASE = The overall box and text color CORNER = The color of the corners of the box, and of the options in the option box at the bottom POINTER = The color of the pointers on the left and right TITLE = The color of the scroll/box title Colors SCROLLVIEW [dir] # SCROLLVIEW POSITION # # RESETVIEW The first two commands jump the current view a number of spaces in one direction or until the given coordinates are in the upper-left corner. RESETVIEW resets the view to normal, showing the player in the center of the screen when possible. All of these change to the target view instantaneously. Directions SET COLOR # # # # The given color (stated by the first number) is changed to the RGB values of the next three numbers. The RGB values must range from 0 to 63. These are the same numbers shown in the palette editor. STATUS COUNTER # "counter" The status screen counter with the stated position # is changed to the given counter. Valid positions for status counters range from 1 (top slot) to 6 (bottom slot). Status counters have a name limit of 14 characters. If the given counter has a name over 14 characters long, this command will be ignored. Counters, Built-in Counters and Local Counters SWAP WORLD "file" Transfers play to the starting board of the stated world file, with the target world starting as freshly loaded. In contrast to a launch from the title screen, a SWAP WORLD will retain all counters, items, keys, strings, etc. from the current world. The target file can be the same world that is currently running; this is a simple way to "reset" the world while keeping progress in the form of items and counters. Strings, Special Formatting, and Their Place in Robotic PUT [color] [char] OVERLAY # # WRITE OVERLAY [color] "string" # # Puts the given color/character at the given coordinates on the overlay, or writes a message in the given color starting at the given coordinates on the overlay. Strings, Special Formatting, and Their Place in Robotic Editing and Using the Overlay Colors VIEWPORT # # Moves the viewport's upper-left corner to the given screen coordinates. X ranges from 0 to 79, and Y ranges from 0 to 24. VIEWPORT SIZE # # Changes the size of the viewport. X size must be from 1 to 80, and Y size must be from 1 to 25. Command Reference (Part I) Robotic Reference Manual Table of Contents

Bullet Types

There are three different types of bullets in MegaZeux: Player, Enemy, and Neutral. The player shoots Player bullets, enemies shoot Enemy bullets, and ricocheted bullets become Neutral bullets. A Robot can shoot any type of bullet, according to its BULLETTYPE counter, but it defaults to Neutral bullets. All fired Enemy bullets, even those shot from Robots, become Neutral bullets when the option "Enemies' bullets can hurt enemies" is set. Only pre-placed Enemy bullets will remain Enemy bullets in this case. Player bullets can only hurt enemies. Enemy bullets can only hurt the player. Neutral bullets can hurt either. Robots go to different labels when shot with each one, or to a generic SHOT label if there are none of the specific PLAYERSHOT, ENEMYSHOT, or NEUTRALSHOT labels. Robotic Reference Manual Table of Contents

CHANGE CHAR ID - The CHAR ID Table

The CHAR ID table has many uses. The first area of usage - the CHANGE CHAR ID # [char] command - basically changes the value (a character, color, or number) of a given type of item. These values correspond to the Global Chars or Damage tables from Global Info. The first number in the command states what is to change. (Note - if noted, the number corresponds to a color or damage. Otherwise, it is a character.) These numbers are also listed next to things in the Global Edit Chars menus. The second area - using the BOARD_ID, BIDx,y or UIDx,y counters - will change an actual item instead of that entry's value; i.e. these counters transform the actual item (and ONLY that item) at a specific pair of coordinates from one type to another. WARNING: Changing certain CHAR ID values will have decidedly special effects: *Changing the value of any Custom type will turn ALL of that type into the given character; same with text. *There is a special exception to this, though. If the value is (char) 255, then all items of that type act like Custom objects and assume a character based on their parameter (e.g. p01 objects will use character 1). This can allow built-ins of the same type that display different characters in-game at the same time. Some built-ins may show interesting effects if set to this, such as gaining animation frames. *Changing the CHAR IDs of objects with animations or four directional characters will fix ALL animations/chars of that object type to the given character. *It is inadvisable to use any UNUSED values. *Using CHAR ID to change between actual items only works with values <122. For example, changing something into Ice by setting BOARD_ID to 160 will not work, but setting BOARD_ID to 25 will. However, there is no such restriction with changing CHAR ID table values using CHANGE CHAR ID. *Damage values start at 327. Not all values are listed, because technically you can assign damage values for things that cannot give damage (i.e. pretty much everything not listed in the table). If you really want to manipulate damage values for such items, to find the CHAR ID damage number for an item, just add 327 to it. Number Changes ------ ------- 0 Space 1 Normal 2 Solid 3 Tree 4 Line 5 Custom Block 6 Breakaway 7 Custom Break 8 Boulder 9 Crate 10 Custom Push 11 Box 12 Custom Box 13 Fake 14 Carpet 15 Floor 16 Tiles 17 Custom Floor 18 Web 19 Thick Web 20 Still Water 21 N Water 22 S Water 23 E Water 24 W Water 25 Ice 26 Lava 27 Chest 28 Gem 29 Magic Gem 30 Health 31 Ring 32 Potion 33 Energizer 34 Goop 35 Ammo 36 Bomb 37 Lit Bomb 38 Explosion 39 Key 40 Lock 41 Door 42 Open Door 43 Stairs 44 Cave 45 CW Rotate 46 CCW Rotate 47 Gate 48 Open Gate 49 Transport 50 Coin 51 N Moving Wall 52 S Moving Wall 53 E Moving Wall 54 W Moving Wall 55 Pouch 56 Pusher 57 Slider NS 58 Slider EW 59 Lazer 60 Lazer Gun 61 Bullet 62 Missile 63 Fire 64 UNUSED 65 Forest 66 Life 67-70 Whirlpool Anim 1-4 71 Invis Wall 72 Ricochet Panel 73 Ricochet 74 Mine 75 Spike 76 Custom Hurt 77 Text 78 Shooting Fire 79 Seeker 80 Snake 81 Eye 82 Thief 83 Slimeblob 84 Runner 85 Ghost 86 Dragon 87 Fish 88 Shark 89 Spider 90 Goblin 91 Spitting Tiger 92 Bullet Gun 93 Spinning Gun 94 Bear 95 Bear Cub 96 UNUSED 97 Missile Gun 98 Sprite 99 Sprite Collision 100 Image File 101-121 UNUSED 122 Sensor 123 Pushable Robot 124 Robot 125 Sign 126 Scroll 127 Player 128-143 Thin Lines (Web) (see below) 144-159 Thick Lines (Thick Web, Lines) (see below) 160 Ice 161-163 Ice Anim 1-3 164-166 Lava Anim 1-3 167 Small Ammo (below 10) 168 Large Ammo (above or equal to 10) 169-175 Lit Bomb Anim 1-7 176-183 Energizer Color Anim 1-8 184-187 Explosion Colors 1-4 188 Horizontal Door 189 Vertical Door 190-193 CW Rotate Anim 1-4 194-197 CCW Rotate Anim 1-4 198-229 UNUSED 230-233 Transport N Anim 1-4 234-237 Transport S Anim 1-4 238-241 Transport E Anim 1-4 242-245 Transport W Anim 1-4 246-249 Transport All-Dir Anim 1-4 250 Thick Arrow N (Pusher/Spike) 251 Thick Arrow S (Pusher/Spike) 252 Thick Arrow E (Pusher/Spike) 253 Thick Arrow W (Pusher/Spike) 254 Thin Arrow N (Guns) 255 Thin Arrow S (Guns) 256 Thin Arrow E (Guns) 257 Thin Arrow W (Guns) 258-261 Horizontal Lazer Anim 1-4 262-265 Vertical Lazer Anim 1-4 266-271 Fire Anim 1-6 272-277 Fire Color Anim 1-6 278-281 Life Anim 1-4 282-285 Life Color Anim 1-4 286 Ricochet Panel \ 287 Ricochet Panel / 288-289 Mine Anim 1-2 290-291 Shooting Fire Anim 1-2 292-293 Shooting Fire Color Anim 1-2 294-297 Seeker Anim 1-4 298-301 Seeker Color Anim 1-4 302-305 Whirlpool Color Anim 1-4 306-309 Player Bullets, NSEW 310-313 Neutral Bullets, NSEW 314-317 Enemy Bullets, NSEW 318-321 Player, NSEW 322 Player Color 323 Missile Color 324 Player Bullet Color 325 Neutral Bullet Color 326 Enemy Bullet Color 353 Lava Damage 365 Explosion Damage 386 Lazer Damage 388 Bullet Damage 389 Missile Damage 390 Fire Damage 402 Spike Damage 403 Custom Hurt Damage 405 Shooting Fire Damage 406 Seeker Damage 407 Snake Damage 410 Slimeblob Damage 411 Runner Damage 412 Ghost Damage 413 Dragon Damage 414 Fish Damage 415 Shark Damage 416 Spider Damage 417 Goblin Damage 418 Spitting Tiger Damage 421 Bear Damage 422 Bear Cub Damage To change a character, use the following form: CHANGE CHAR ID # [char] # is the number corresponding to the character that you want to change, or a counter representing that number. [char] is the character (or counter representing the character) that you wish to change it to. To change a color, use the following form: CHANGE CHAR ID # [color] # is the same as above, but corresponding to a color. [color] is the color or a counter representing the color that you wish to change it to. To change damage values, use a number or counter in place of the [char] or [color]. After typing in a [color] or damage value, it may change to a character representation, but the value will still remain the same. To change line characters: Take the base number for the type of line you wish to change (128 for thin, 144 for thick) and add one of the following values to represent which sides are connected via other web or lines: 0 - 1 N 2 S 3 N S 4 E 5 E N 6 E S 7 E N S 8 W 9 W N 10 W S 11 W N S 12 W E 13 W E N 14 W E S 15 W E N S CHANGE CHAR ID # [char] Robotic Reference Manual Table of Contents

Built-in Labels

Robotic has many built-in labels (messages) that are activated on certain external events. Each label, and what triggers it, is listed below. Subroutine versions of most labels exist. If a built-in label has a subroutine version, [#] will be listed to the right of its name. If both forms exist, they will both be triggered, with the subroutine version being triggered first, and the normal version triggered as the subroutine is left. Special care is required when dealing with built-in subroutine labels. To prevent abuse of the stack, using LOCKPLAYER and/or ZAP to keep subroutine calls to an absolute minimum is highly advised. Subroutines themselves are explained in another section. Subroutines TOUCH [#] This is sent when the player touches the Robot, that is, when the player is next to it and tries moving into it. If the player is locked in that direction, this label is not sent. THUD [#] This is sent when the Robot is walking and it runs into a non-pushable obstacle. This label is not sent when the obstacle is hit during a GO [dir] # or the / "string" command. THUD ignores LOCKSELF. This label will be constantly triggered if the condition persists. WALK [dir] EDGE [#] This is sent when the Robot is walking and it runs into the edge of the board. If EDGE is not found, the Robot is sent to THUD. This label is not sent when the edge of the board is hit during the GO [dir] # or the / "string" commands. EDGE ignores LOCKSELF. This label will be constantly triggered if the condition persists. WALK [dir] BOMBED [#] This is sent when the Robot is hit with an explosion. KEY? [#] This is sent when the player presses the given key. ? should be replaced with the key to be scanned for. Characters a to z and 0 to 9 work as expected. Shifted alphabetic characters will NOT work, and will actually scan as their non-shifted counterparts. Any other character that can be outputted directly, such as ";" or "*" or "=", will work, and "key " will detect the space bar. Other characters can be entered by pressing F3 and selecting them from the grid, but they are usually not guaranteed to work. Special-case characters that can work with KEY? are character 8 (BackSpace), character 9 (Tab), character 27 (Esc), character 127 (Delete) and character 13 (Enter, though there's a better label just for this mentioned in the very next entry). There is another way to scan for key presses: using counters. Key-scanning counters such as KEY_PRESSED, KEY, and KEY_CODE are detailed in the Miscellaneous Counters section of the help file. Miscellaneous Counters KEYENTER [#] This is sent when the player presses the Enter key. INVINCO [#] This is sent when the player grabs an energizer. PUSHED [#] This is sent when a pushable Robot is pushed by something. If something tries to push the Robot and can't, this label is not sent. ENEMYSHOT [#] PLAYERSHOT [#] NEUTRALSHOT [#] One of these is sent when the Robot is shot, correlating to the type of bullet used. If the appropriate label is not found, the Robot is sent to SHOT instead. SHOT [#] This is sent when the Robot is shot by a bullet and the more specific label cannot be found. PLAYERHIT [#] This is sent when the player is shot with a bullet. If not found, the Robot is sent to PLAYERHURT instead. PLAYERHURT [#] This is sent when the player is hurt by anything other than a bullet. Bullets send the Robot to PLAYERHIT, and only send it to PLAYERHURT if PLAYERHIT cannot be found. PLAYERDIED [#] This is sent when the player dies, whether through health being lowered to/below 0 or through the ENDLIFE command. This will not trigger when the LIVES counter is decremented. NOTE: Unlike other built-in labels, this label is jumped to on the cycle after it is sent, not the same cycle. SPITFIRE [#] This is sent when the Robot is hit with shooting fire. JUSTLOADED This is sent when the world was just loaded or restored from a saved game. This is also sent upon swapping worlds; in that case, it will only trigger if no JUSTENTERED label is set. JUSTENTERED This is sent when the board was just entered or the world was just started on this board. This is also sent upon swapping worlds; in that case, if no JUSTENTERED label is set, JUSTLOADED is triggered instead. SENSORON This is sent by a Sensor when it is stepped upon by the player, or the Sensor moves beneath the player. Sensors SENSORTHUD This is sent by a Sensor when it tries to move and is blocked. Sensors SENSORPUSHED This is sent by a Sensor when it is pushed by something. Sensors LAZER [#] This is sent when the Robot is hit with a lazer. GOOPTOUCHED [#] This is sent when the player touches Goop. YES This is sent when the YES button is selected in an ASK box. NO This is sent when either the NO button is selected in an ASK box, or when ESC exits an ASK box. ASK "string" Robotic Reference Manual Sensors Table of Contents

Counters, Built-in Counters and Local Counters

Counters are built-in variables, or stored values with names. Each counter has a name, such as "Yellow" or "Apple Pies" or even "100". A counter can hold a value from -2147483648 to 2147483647, in most cases. A counter is "active" when it has a value other than 0. There can be a practically unlimited amount of active counters at any one time, in addition to the built-in counters. Counters retain values between different boards. Local counters, on the other hand, only hold their values for one Robot. These are useful because multiple Robots can set local counters with the exact same names without causing conflicts. There are several local counters explicitly reserved for use; these are the "local" & "local2" through "local32" counters. To display a counter's number, enclose the counter in ampersands. (e.g. &counter&). This displays the counter value in decimal. Sometimes hexadecimal is needed, like in certain MegaZeux commands. To output a counter number in hex, add a + to the front of the enclosed counter (e.g. &+hexcount&). Lastly, other MegaZeux commands might require a two-digit hex number; for these, add a # to the front of the enclosed counter (e.g. &#twodigithex&). Note that in this case, only the two most significant digits will be used (e.x. the number 'abcdef' becomes 'AB') and single-digit numbers will gain a leading zero (e.g. the number '8' will become '08'). Also, characters can be used as counters in commands. For example: SET "boom" to '0' would come out as SET "boom" to 48. It's quite a difference! Commands that check or modify counters will accept numbers ranging from -32768 to 32767. To use numbers outside of this range with these commands, one must put the number in parentheses. For example: SET "bonus" to "(1000000)". The following is a list of built-in counters, which all have special meanings. There are four types of built-in counters: Global, which affect everything; Local, which are different for each Robot and require special handling for other Robots to manipulate; Board, which are specific to the current board; and Universal, which persist for the entire time MegaZeux is running. Some built-in counters are read-only; a few are write-only. MegaZeux utilizes a large number of built-in counters to maximize flexibility. For this reference, they have been divided into distinct sections. Player Counters Robot Counters Board Counters Audio Counters Mathematical Counters File Access Counters Sprite Counters String Counters Super MZX Counters Character Edit Counters Mouse/Joystick Counters Defaults Counters Vlayer Counters Miscellaneous Counters

Player Counters

GEMS, AMMO, LOBOMBS, HIBOMBS, COINS, LIVES, HEALTH These contain the current number of the stated item that the player currently has. INVINCO The number of cycles of invincibility the player currently has. SCORE The player's current score. PLAYERLASTDIR The last direction the player moved: 0 for none, or 1 2 3 4 for N S E W. Used to determine ice slippage and certain other effects. PLAYERFACEDIR The direction the player is facing: 0 1 2 3 for N S E W. Used to determine which player character to display. PLAYERX (read-only) PLAYERY (read-only) The x or y coordinate of the player, respectively.

Robot Counters

PLAYERDIST (read-only, local) The distance from the Robot to the player, in spaces. The sum of HORIZPLD and VERTPLD. HORIZPLD (read-only, local) VERTPLD (read-only, local) The horizontal or vertical distance from the Robot to the player, in spaces. THISX (read-only, local) THISY (read-only, local) The current X or Y coordinate of the Robot. Affected by prefixes - If a command that uses THISX and THISY is prefaced with a REL PLAYER command, THISX and THISY will be generated based on the player's current position. For example, if the player is at (2,2) and the Robot is at (5,5), THISX and THISY will be 3. If the player is at (8,8), THISX and THISY will be -3. If a command that uses THISX and THISY is prefaced with a REL COUNTERS command, THISX and THISY will be generated based on XPOS and YPOS. Basically, THISX and THISY will be set to THISX-XPOS and THISY-YPOS. REL COUNTERS REL PLAYER BULLETTYPE (local) The current type of bullet shot by the Robot: 0 for Player, 1 for Neutral, and 2 for Enemy. Technically, this counter can hold any number from 0 to 255, but only 0, 1 and 2 have defined behavior. The others essentially set the Robot to shoot Enemy bullets, if actually used to affect shot bullets. Bullet Types COMMANDS The number of commands executed per Robot cycle (40 is default). This number is global. It can severely slow MegaZeux if set too high and coupled with poor coding (especially busy loops lacking cycle-ending commands). LOOPCOUNT (local) The counter used for looping commands in Robotic - LOOP START, LOOP #, and ABORT LOOP. LOOP START ROBOT_ID (read-only, local) The internal ID of the Robot. These numbers match the parameters of Robots on the board, but are in decimal. So, for example, if a Robot on the board has a parameter of p0a, its ROBOT_ID would be 10. RID<Robot name> (read-only) ROBOT_ID_<Robot name> (read-only) Both of these give the robot_id number of the given named Robot. In the case of multiple Robots with the same name, the ID number corresponds to only one of them. If no Robots have the name, or if the name in question only belongs to the global Robot, -1 is given. BEWARE: The existence of this counter makes it impossible to use words which start with "rid" as counters. The port will NOT fall through and give the values of any counter that starts with "rid"; instead, it ends at -1 (since the Robot the counter is trying to find, like "dles" (for "riddles"), will most likely not exist). Older games will allow counters with names like this, but only for compatibility reasons. Rn.<counter> Contains the value of the given counter (without the angle brackets) in the Robot with the robot_id number n. If no Robot exists with this robot_id, the counter will return -1. THIS_COLOR (read-only, local) THIS_CHAR (read-only, local) The current color and character of the Robot, respectively. LAVA_WALK (local) Controls whether the Robot can walk on lava or not. Setting this to 1 is the equivalent of using the BECOME LAVAWALKER command. Setting it to 0 is the same as BECOME NONLAVAWALKER. Like BULLETTYPE, this counter can hold any value from 0 to 255, but only 0 and 1 have defined behavior. This was a popular local counter before the local counters were plentiful, as most Robots didn't deal with lava. BECOME LAVAWALKER LOCAL (local) LOCAL2 (local) .. LOCAL32 (local) The non-special local counters each Robot can use. In effect, any number can be used, not just 2-32; the counter accessed by it would be N%32 (so, for example, any change to "local0" would have the same effect as changing "local32"). LOCAL is the same as LOCAL1. GOOP_WALK (local) Controls whether the Robot can walk on goop or not. A value of 0 prevents walking on goop; a non-zero value allows it. This counter has an effective range of 0 to 255.

Board Counters

BOARD_X BOARD_Y BOARD_X and BOARD_Y represent the x,y coordinates of a target location on the current board. Several other counters use the values of these counters to read or alter parts of the board. These counters default to 0. BOARD_COLOR (read-only, board) BOARD_CHAR (read-only, board) Reads the color and character, respectively, of the object located at "board_x" "board_y". If board_x or board_y is an invalid coordinate, BOARD_COLOR and BOARD_CHAR access the closest valid coordinate. For example, if board_y is 60 and the board is 50 characters tall, board_y is treated as if it were 49. One thing to note is that BOARD_COLOR will not take background color 0's transparency into account. For example, assuming default colors, if a white-on-black Robot walks onto a yellow-on-blue floor tile, the Robot appears as white-on-blue on the screen, but this counter will still report it as white-on-black instead of the displayed colors. BOARD_ID Reads or alters the CHAR ID value of the object located at "board_x" "board_y". If board_x or board_y is an invalid coordinate, BOARD_ID accesses the closest valid coordinate. For example, if board_x is 60 and the board is 50 characters wide, board_x is treated as if it were 49. CHANGE CHAR ID - The CHAR ID Table BOARD_PARAM Reads or alters the parameter of the object located at "board_x" "board_y". If board_x or board_y is an invalid coordinate, BOARD_PARAM accesses the closest valid coordinate. For example, if board_y is a negative number, board_y is treated as if it were 0. BOARD_W (read-only, board) BOARD_H (read-only, board) The current board's width and height, respectively. TIME (board) The current timer value, between 0 and the time limit for the current board. If there is no time limit set, setting this counter will cause the timer to tick down but turn off after it runs out. TIMERESET (board) The time limit for the current board. 0 for no time limit. NOTE: This timer was erroneously called "TIMERSET" in some versions. MZX will NOT use TIMERSET as a synonym for this counter in current versions. SCROLLEDX (read-only, board) SCROLLEDY (read-only, board) The top-left corner of the screen's x or y coordinates, respectively. BCHx,y (read-only, board) Allows the reading of single characters to the board with regards to coordinates x,y. The comma must be included. Returns -1 for invalid coordinates. BCOx,y (read-only, board) Allows the reading of single colors to the board with regards to coordinates x,y. The comma must be included. Returns -1 for invalid coordinates. Much like BOARD_COLOR, BCOx,y will not take transparency into account. BIDx,y (board) Allows reading and writing of the CHAR ID of an object on the board at the coordinates x,y. The comma must be included. Returns -1 for invalid coordinates. BPRx,y (board) Allows reading and writing parameter values of an object on the board at the coordinates x,y. The comma must be included. Returns -1 for invalid coordinates. UCHx,y (read-only, board) Allows the reading of single characters on the under layer at the coordinates x,y. The comma must be included. UCOx,y (read-only, board) Allows the reading of single colors on the under layer at the coordinates x,y. The comma must be included. UIDx,y (board) Allows reading and writing of the CHAR ID of an object on the under layer at the coordinates x,y. The comma must be included. UPRx,y (board) Allows reading and writing parameter values of an object on the under layer at the coordinates x,y. The comma must be included. All of the above four under layer counters will return -1 if nothing is on the under layer at that location, as well as for invalid coordinates. Floor-type objects by themselves (such as fake, floor, carpet, ice, lava, etc) count as being on the board layer if nothing is on them. OVERLAY_X (board) OVERLAY_Y (board) OVERLAY_CHAR (read-only, board) OVERLAY_COLOR (read-only, board) These work in the same way as the BOARD_xxx counters above, but deal with the overlay instead. OVERLAY_CHAR and OVERLAY_COLOR return -1 if the overlay is off or if the coordinates are invalid. OCHx,y (read-only, board) Allows the reading of single characters on the overlay at the coordinates x,y. The comma must be included. Returns -1 if the overlay is off or if the coordinates are invalid. OCOx,y (read-only, board) Allows the reading of single colors on the overlay at the coordinates x,y. The comma must be included. Returns -1 if the overlay is off or if the coordinates are invalid. OVERLAY_MODE (read-only, board) Shows the state of the overlay. 0 is off, 1 is normal, 2 is static and 3 is transparent. VIEWPORT_X (read-only, board) VIEWPORT_Y (read-only, board) Contains the x,y coordinates of the upper-left corner of the current board's viewport. VIEWPORT_WIDTH (read-only, board) VIEWPORT_HEIGHT (read-only, board) Contains the respective width and height of the current board's viewport.

Audio Counters

MOD_FREQUENCY (board) Controls the frequency (in Hz) of the currently playing module/ OGG music. Note that this value is NOT saved by save or counter files, so if necessary, it needs set again after a save gets loaded. SAM, OGG, MOD and WAV Frequencies MOD_ORDER (board) Controls the current mod order of the currently playing mod. MOD_POSITION (board) Controls the current row in tracked modules, or the current PCM sample in OGGs. MOD_LENGTH (read-only, board) Contains the length of the currently playing mod. This counter's value shows number of rows for module files and number of samples for OGG files. NOTE: This counter will not work if MegaZeux was built with the Mikmod engine. This is a minor concern due to Mikmod never being the default module engine for MegaZeux. MOD_LOOPSTART MOD_LOOPEND These counters control looping in the currently-playing music. MOD_LOOPSTART marks the beginning position of a loop; MOD_LOOPEND marks the end. If MOD_LOOPEND is 0, no looping will occur. Despite the counter names, they do not work on tracked modules, only OGG files.

Mathematical Counters

ABSn Gives the absolute value of the number n. SQRTn Gives the integer approximation of the square root of n. Results are truncated, not rounded. MINx,y Takes the numbers x and y and outputs the smaller number. The comma is required. MAXx,y Takes the numbers x and y and outputs the larger number. The comma is required. MULTIPLIER Multiplies values output by the normal trigonometric functions (sin, cos, tan) by the given number. Defaults to 10000. DIVIDER Divides the number given to the inverse trigonometric functions (asin, acos, atan) by the given number. Defaults to 10000. C_DIVISIONS Determines the number of divisions of the base circle in MegaZeux's trigonometric functions. Defaults to 360. SINn COSn TANn ASINn ACOSn ATANn ARCTANdy,dx Accesses MegaZeux's sine, cosine, tangent, inverse sine, inverse cosine, inverse tangent, and atan2 functions (respectively). Trigonometric Functions

File Access Counters

FREAD_OPEN (function) FWRITE_OPEN (function) Opens a file for reading from or writing to, respectively. The syntax is as such: set "file.ext" to "FREAD_OPEN" FREAD_OPEN will also read subdirectories with the given syntax: set "dir" to "FREAD_OPEN" FWRITE_MODIFY (function) This opens an existing file for reading without overwriting it, starting at the beginning of the file. FWRITE_APPEND (function) This opens a file for writing at the END of the file. Note that all FWRITE_POS functionality is ignored in this mode. FREAD_COUNTER (function) Reads four bytes from the open file. FWRITE_COUNTER (function) Writes four bytes to the open file. NOTE: The above two counters will have different functionality in worlds made before MZX 2.82 (in the old implementation, they use two bytes and are unsigned). This is purely for compatibility reasons. FREAD_POS FWRITE_POS The current reading or writing position of the accessed file. 0 is the beginning position; when no file is loaded, the relevant counter is -1. If set to -1, the position is set to the end of the file. FREAD_DELIMITER FWRITE_DELIMITER The character considered the terminator for fread and fwrite operations, respectively. FWRITE (function) FREAD (function) Respectively writes to and reads from the open file. With counters, these counters only write/read a single byte at a time; with strings, FWRITE will write a full string and tack the terminator character to the end, and FREAD will read a full string up to the terminator. FWRITEn (function) FREADn (function) Respectively writes to and reads from the open file, but will limit action to n number of characters. These counters only work with strings, not with counters, and will neither place nor respect terminator characters. FREAD_LENGTH Returns the length in characters of the open file in read mode. If this file does not exist, returns -1. If a directory is open, returns the number of items (files and subdirectories) in that directory. FWRITE_LENGTH Returns the length in characters of the open file in write mode. SAVE_ROBOT (function) LOAD_ROBOT (function) SAVE_ROBOTn (function) LOAD_ROBOTn (function) Saves or loads Robotic code to or from plaintext files, respectively. The first forms save/load the current Robot, while the second forms save/load the Robot with the Robot ID of the number n. One can also load a string as a Robot instead of a text file, or save a Robot into a given string. SAVE_BC (function) LOAD_BC (function) SAVE_BCn (function) LOAD_BCn (function) Saves or loads Robotic code to or from bytecode files, respectively. The first forms save/load the current Robot, while the second forms save/load the Robot with the Robot ID of the number n. Keep in mind that due to slated changes in MegaZeux, saving out Robots (in either text or bytecode form) is considered a deprecated function and may be removed entirely in the future. SAVE_GAME (function) LOAD_GAME (function) Saves or loads MZX savegames, respectively. SAVE_COUNTERS (function) LOAD_COUNTERS (function) Saves or loads MZX counter files, respectively. File Access Strings, Special Formatting, and Their Place in Robotic

Sprite Counters

SPRn_WIDTH SPRn_HEIGHT The dimensions of sprite n. (x and y dimensions, respectively.) SPRn_X SPRn_Y The current position of sprite n. These can be used to set the sprite outside the edges of the board, whereas PUT c?? Sprite p?? X Y disallows this. SPRn_REFX SPRn_REFY Where sprite n's appearance is stored - either on the board or the vlayer (see SPRn_VLAYER). REFX is the x-coordinate, REFY is the y-coordinate. Whatever this looks like at this position is what the sprite will look like when drawn, including the colors if c?? is used when placing the sprite. SPRn_CWIDTH SPRn_CHEIGHT The dimensions of the collision box around sprite n. (X and Y dimensions, respectively) SPRn_CX SPRn_CY The location, relative to sprite n's upper left corner, of the sprite's collision box (X and Y coordinates, respectively). These have default values of 0. SPR_CLISTn (read-only) A list of flagged collisions after a collision test was performed. Values of n from 0 to (SPR_COLLISIONS - 1) are valid. Each valid SPR_CLISTn value lists the number of a sprite involved in a collision with the checked sprite, arranged in ascending sprite order. If the foreground collided, SPR_CLIST0 is always set to -1 to indicate this. SPR_COLLISIONS (read-only) The number of sprite/foreground collisions reported by SPR_CLISTn counters. SPRn_CCHECK (write-only) If set to 1 for sprite n, overlapping char 32s will not cause a collision between that sprite and other sprites or the foreground. If set to 2, both char 32s and blank chars will not collide, and blank characters will not be drawn. If set to 3, the given unbound sprite will undergo pixel-precise collision checks, and transparent colors will not cause a collision. Setting to 0 will cancel any previously set ccheck modes for that given sprite. SPRn_CLIST (write-only) Setting this counter to any value will perform a collision test on sprite n against its current location. SPRn_VLAYER (write-only) If set to 1, sprite n is referenced from the vlayer instead of the board. SPRn_OFF Shows whether sprite n is inactive: a value of 1 means yes (the sprite is off), 0 means no (the sprite is on). Also, if set to any value, turns sprite n off if it is on. SPRn_OFFONEXIT If set to any non-zero value, turns the sprite off upon leaving the current board. The sprite will be turned off even if the destination board is also the current board. SPRn_OVERLAID (write-only) SPRn_OVERLAY (write-only) If either is set to 1, these draw sprite n over the overlay as opposed to underneath. Note that this has different behavior depending on whether unbound sprites are present. If there are any unbound sprites active, all overlaid sprites will be drawn above all non-overlaid sprites (as well as over the overlay). If unbound sprites are not in use, overlaid sprites will be drawn above the overlay, but will otherwise respect the standard sprite draw order. SPRn_SETVIEW (write-only) Setting this to 1 will cause the viewport to be centered around sprite n. This is not a permanent effect, but a one-time jump akin to the RESETVIEW command. This is useful for scrolling the screen for (e.g.) a sprite-based player object. SPRn_STATIC (write-only) If set to 1, makes sprite n act static (like a static overlay, a static sprite always stays in a given position on the screen); if this is 0, the sprite scrolls with the board. Of note: any collision with a static sprite happens based on its visually-apparent location, not its actual location. This means that when the board scrolls, the valid coordinates for absolute collision checks against a static sprite change even when the static sprite itself is not visually moved, and that relative collision checks like SPRn_CLIST against a static sprite work based on the static sprite's screen position. SPRn_Z These counters allow a user-defined sprite draw order. This method of determining draw order takes precedence over SPR_YORDER and sprite number. Higher SPRn_Z values are higher priority and will be drawn over sprites with lower SPRn_Z numbers. Matching SPRn_Z values will fall back to SPR_YORDER precedence if active, and sprite number precedence otherwise. SPR_NUM When using p?? for placing a sprite, this counter's value becomes the sprite's parameter. When IF c?? Sprite p?? X Y is used, SPR_NUM will be set to the number of the first sprite that makes the IF statement true (if there are any). The sprites are checked by sprite number in ascending order. SPR_YORDER (write-only) If set to 1, the sprites are drawn in order of lowest sum of SPRn_Y and SPRn_CY values to highest instead of in order of their sprite numbers. Any incidence of matching sums will have draw order determined by sprite number. If any SPRn_Z values are set, those take precedence. SPRn_SWAP (write-only) Swaps sprite n with the sprite number to which this function is set. SPRn_UNBOUND If set to 1, unbinds sprite n from the grid, making its coordinates refer to pixel positions instead of tile positions. Its dimensions (SPRn_HEIGHT, SPRn_WIDTH) and reference coordinates (SPRn_REFX, SPRn_REFY) will still be relative to tiles, but its current position (SPRn_X, SPRn_Y) and collision box counters (SPRn_CX, SPRn_CY, SPRn_CWIDTH, SPRn_CHEIGHT) will adhere to this change. See the Unbound Sprites section in the Sprites help for more information. SPRn_TCOL Sets which color provides transparency for unbound sprite n. Setting to -1 disables transparency for that sprite. Defaults to 0. SPRn_OFFSET Internally alters any number that refers to a character for sprite n by the counter's value. This only applies to unbound sprites. This number will often be a multiple of 256 in order to access an extra charset, but offset values within char sets may also be used. Sprites

String Counters

SET "$string" to "INPUT" Sets the given string to any input placed for the "input string" command. SET "$string" to "BOARD_NAME" Sets the given string to the name of the current board, or to a blank string when the board has no name. SET "$string" to "MOD_NAME" Sets the given string to the filename of the currently playing module, or to a blank string when no music is playing. If the current board mod is mod *, this will contain the actual filename of the currently-playing mod, not "*". SET "$string" to "ROBOT_NAME" Sets the given string to the name of the Robot this command is in, or to a blank string when the Robot has no name. Note: BOARD_NAME, MOD_NAME and ROBOT_NAME cannot be directly displayed, unlike &INPUT&. SET "$string" to "FREAD" SET "$string" to "FREADn" Sets the given string to the contents of the currently open file. FREAD stops at the terminator (*, or char 42, by default) or at the end of the file. FREADn reads the first n characters from the file. You can use FREAD with the #N string splicing format to read up to N characters while still terminating on the terminator. SET "$string" to "FWRITE" SET "$string" to "FWRITEn" Places the contents of the given string into the currently open file. FWRITE places the entire string, ending it with the terminator character (*, or char 42, by default), while FWRITEn only places the first n characters. If n goes over the string's length, the entire string (and nothing else like whitespace or garbage characters) will be placed. SET "$string" to "BOARD_SCAN" Sets the given string to a line of characters read directly from the board starting at "board_x" "board_y" and terminating at an asterisk (char 42), any instance of char 0, or after 63 characters (whichever comes first). This command is deprecated; please use copy block to strings instead.

Super MZX Counters

SMZX_MODE Determines whether Super MZX mode is off (0), 1, 2, or 3. All other values wrap around these four (so, for instance, trying to set SMZX_MODE to 4 would set it to 0, and trying to set SMZX_MODE to -1 would set it to 3). SMZX_Rn SMZX_Bn SMZX_Gn Changes or reads the value of color n's red/blue/green value, respectively. These counters range from 0-63; numbers outside these bounds wrap around. These counters also work outside of SMZX modes; in normal mode, using numbers 0-15 for n alters the current palette. SMZX_IDXx,y Reads or sets the color of a tile with a given color x's yth color. For example, SET "SMZX_IDX191,0" to 50 would set the color number of the base color (color 0 out of 0-3) of a c1a (color 191) tile to color 50. This applies to SMZX mode 3 only, and only to renderers that support unbound sprites. Keep in mind that all re-ordered indices will be set to normal values when SMZX_MODE is changed. SMZX_INDICES (function) Loads SMZX indices files. This only applies for SMZX Mode 3. SMZX_MESSAGE Controls whether messages in the message line are displayed with SMZX characters and colors in SMZX modes. 1 is yes, 0 is no (displays in normal mode); the default value is 1. SMZX_PALETTE (read-only) Loads a Super MZX palette. This counter is deprecated; please use load palette instead.

Character Edit Counters

CHAR_X CHAR_Y PIXEL Set CHAR_X and CHAR_Y to a pixel location in the char set. You can then set the PIXEL counter to one of the following to edit the pixel: 0 Turns the pixel OFF 1 Turns the pixel ON 2 Toggles the pixel You can also read the counter to see the current state of the chosen pixel. A value of 1 denotes that the pixel is set, and 0 if not. The pixel location system works on a 32 x 8 grid of characters, exactly like the 'Select Character' grid. Each character consists of fourteen rows of eight pixels, which gives us 256 pixels across by 112 pixels down. Since we start counting at 0, the top-left pixel of the top-left character (char 0) would be 0,0. The bottom-right pixel of the bottom-right character (char 255) would be 255,111. These counters become useless in SMZX modes. The Character Editor CHAR_BYTE CHAR BYTE Set CHAR to a character (0-255) and BYTE to one of the fourteen bytes within the char (0-13). You can then read or write that byte using the CHAR_BYTE counter. Char_byte values range from 0-255, and the meaning of each char_byte setting changes between normal mode and SMZX modes. Normal MZX graphics mode sets bytes in binary (base 2); SMZX modes use quaternary (base 4). These counters can also edit the extra character sets unbound sprites use by setting CHAR to the character numbers of the extra sets (e.g. 256 for the first char of the first extra set). It helps to write the number in binary/quaternary first, then convert to decimal. Writing the numbers this way helps demonstrate that whatever is desired to be set is set. The values per pixel decrease going left to right. Examples: (Normal MZX mode, setting the third, fifth and seventh pixel) Binary: 00101010 ------------- |128|64|32|16|8|4|2|1| ------------- | 0| 0| 1| 0|1|0|1|0| ------------- Decimal: ((128*0)+(64*0)+(32*1)+(16*0)+(8*1)+(4*0)+(2*1)+(1*0)) = 42 Notice that the binary number shows which pixels are on, in order. (Super MZX Mode, setting first and second pixel to color 2, third to color 4 and fourth to color 1) Quaternary: 1130 ------ |64|16|4|1| ------ | 1| 1|3|0| ------ Decimal: ((64*1)+(16*1)+(4*3)+(1*0)) = 92 Much like the binary numbers for normal MZX mode, the quaternary number shows what color each pixel is in order. Here, color values range from 0 to 3. The Character Editor

Mouse/Joystick Counters

MOUSEX MOUSEY Reads/sets the mouse cursor's x or y-coordinates (respectively) relative to the screen in characters. MOUSEPX MOUSEPY Reads/sets the mouse cursor's x or y-coordinates (respectively) relative to the screen in pixels. Always scales to terms of 640x350, regardless of the actual resolution or current SMZX mode. MBOARDX (read-only, board) MBOARDY (read-only, board) Reads the mouse cursor's x or y-coordinates (respectively) relative to the board. BUTTONS (read-only) Reads which mouse buttons are currently being pressed. The counter value is based as follows: 0 for no input pressed +1 for left button +2 for right button +4 for middle button +8 for wheel up +16 for wheel down +32 for wheel left +64 for wheel right +128 for extra button 1 +256 for extra button 2 E.G., left by itself would output 1, and left+middle would output 5 (1 + 4). CURSORSTATE Determines whether the default mouse cursor is on or off (0 is off, 1 (or any non-zero value) is on - defaults to off). JOY#ACTIVE (read-only) Determines the status of the given joystick numbered #. Returns 1 for active, 0 for inactive, and -1 for an invalid index. JOY#.[ACTION] (read-only) Determines the status of the given joystick action for the given joystick numbered #. The square brackets are not included. Digital actions return 1 for pressed/held and 0 for unpressed/unheld. Analog actions will return their current value. Invalid actions will return -1. Please read joystick.html for a full list of actions. JOY_SIMULATE_KEYS Allows MegaZeux to simulate key presses with joystick actions when enabled. 0 is off, 1 (or any non-zero value) is on. Defaults to on.

Defaults Counters

ENTER_MENU Determines whether the built-in status window is loaded when the enter key is pressed. 1 (or any non-zero value) is yes, 0 is no. The default is 1 (yes). If on the title screen, this counter is ignored unless in standalone mode. ESCAPE_MENU Determines whether the built-in game exit dialog is loaded when the escape key is pressed. 1 (or any non-zero value) is yes, 0 is no. The default is 1 (yes). If on the title screen, this counter is ignored unless in standalone mode. HELP_MENU Determines whether the built-in help window is loaded when the F1 key is pressed. 1 (or any non-zero value) is yes, 0 is no. The default is 1 (yes). The help menu is still accessible from other default dialogs (such as the file menus) unless in standalone mode. If on the title screen, this counter is ignored unless in standalone mode. F2_MENU Determines whether the built-in MegaZeux options window is loaded when the F2 key is pressed. 1 (or any non-zero value) is yes, 0 is no. The default is 1 (yes). If on the title screen, this counter is ignored unless in standalone mode. LOAD_MENU Determines whether the built-in MegaZeux loadgame window is loaded when the F4 key is pressed. 1 (or any non-zero value) is yes, 0 is no. The default is 1 (yes). If on the title screen, this counter is ignored unless in standalone mode. BIMESG (write-only) Controls built-in game messages (e.g. the message given when touching goop); 1 (or any non-zero value) is on while 0 is off. The default is 1 (on). SPACELOCK (write-only) Controls whether holding space locks player movement. If 1 (or any non-zero value), the player will be locked into place when space is held; if 0, the player can move freely when space is held, but will be unable to shoot bullets. The default is 1 (on).

Vlayer Counters

VLAYER_WIDTH VLAYER_HEIGHT Sets the width and height of the vlayer, respectively. The defaults are 256 for VLAYER_WIDTH and 128 for VLAYER_HEIGHT. Setting one will automatically set the other to the maximum possible for the current vlayer_size. VLAYER_SIZE Sets the maximum size of the vlayer. The default is 32768. Making this larger won't change the values of VLAYER_WIDTH or VLAYER_HEIGHT but shrinking it may shrink both - height first, then width. VCHx,y Allows reading and writing of single characters to the vlayer at the coordinates x,y. The comma must be included. Returns -1 for invalid coordinates. VCOx,y Allows reading and writing of single colors to the vlayer with at the coordinates x,y. The comma must be included. Returns -1 for invalid coordinates. The Vlayer and Its Uses

Miscellaneous Counters

MZX_SPEED The current game speed (1-16) of MegaZeux. MZX_SPEED 1 is processor-bound and executes as many cycles per second as possible. Other speeds execute cycles according to this formula: 62.5 / (MZX_SPEED - 1) = cycles per second Once the speed is set with this counter, the player cannot change the speed in the F2 menu until MZX_SPEED is set to 0. Setting MZX_SPEED to 0 will not affect the current speed. MZX_SPEED will revert back to the default value listed in the configuration file upon loading a different game. The Config File COMMANDS_STOP A special counter active only while playtesting in the editor. COMMANDS_STOP will activate stepping in the Robotic debugger, even if the debugger was currently disabled, once the number of commands any specific Robot executes in a single cycle exceeds COMMANDS_STOP's value. By default, COMMANDS_STOP holds a value of 2000000. EXIT_GAME If this counter is set to a non-zero value, the current MegaZeux world will exit to the title screen, or back to the editor if playing from the editor. This counter does nothing on the title screen unless in standalone mode, and if standalone mode is ran without a title screen, this counter will cause MegaZeux to exit entirely. PLAY_GAME If this counter is set to a non-zero value when MZXRun is in standalone mode and on the title screen, the game will be started. Instances outside of the title screen and outside of MZXRun will be ignored. CURRENT_COLOR RED_VALUE GREEN_VALUE BLUE_VALUE When CURRENT_COLOR is set between 0 and 15 (between 0 and 255 in Super MZX modes), the other three counters contain the red, green and blue values of that color. Super MegaZeux Modes The Palette Editor INPUT (board) The numerical value of the last string inputted in an INPUT STRING box. Strings that are solely numbers and strings leading with numbers (e.g. "86ed") set this counter to the relevant number. This counter returns 0 if the last string inputted did not lead with a number. INPUT STRING "string" INPUTSIZE (board) The size, in characters, of the last string inputted in an INPUT STRING box. INPUT STRING "string" DATE_DAY (read-only, universal) DATE_MONTH (read-only, universal) DATE_YEAR (read-only, universal) Contain the current day, month and year respectively, based on the system clock. TIME_HOURS (read-only, universal) TIME_MINUTES (read-only, universal) TIME_SECONDS (read-only, universal) TIME_MILLIS (read-only, universal) Contain the current hour, minute, second and millisecond respectively, based on the system clock, in 24-hour format. DATE_WEEKDAY (read-only, universal) Contains the current day of the week as a number 0 through 6, starting with Sunday (0) and ending with Saturday (6). INT BIT_PLACE INT2BIN Used to manipulate bits within a counter. Set INT to the number or counter you wish to edit. Set BIT_PLACE to a number between 0 and 15 (which correspond to the bits in a 16-bit signed counter), and then set INT2BIN to one of the following to edit the bit: 1 Sets the bit ON 2 Sets the bit OFF 3 Toggles the bit The edited value is placed into the INT counter. You can also read the INT2BIN counter to see the current state of the bit. This method of bit manipulation is heavily deprecated in favor of expressions (especially considering it only works on 16 bits instead of the current 32). Follow the link below to read more. Expressions KEY_PRESSED (read-only) KEY KEY_CODE (read-only) KEY_PRESSED lists whether any key (each referenced by a number) is currently being held down; for example, on a typical keyboard, if the spacebar is being pressed the value of key_pressed will be 32. If no key is currently held, its value is 0. Results are unsigned, so checking for negative numbers will not work. "Autorepeat stall" affects KEY_PRESSED, so if you hold down a key you will get the value, then get zeros for a period, then get the values again. This is useful for many applications. KEY acts like KEY_PRESSED, but lacks autorepeat stall, returns uppercase letter values, and retains its value until another key is pressed. KEY_CODE acts similar to KEY_PRESSED (has an autorepeat stall, is 0 when nothing is held) but uses different keycodes. Its keycode set is more limited, making KEY_PRESSED generally preferable. In the case of multiple keys being held down at once, these counters only report the value of the most recently-pressed key. KEYn (read-only) KEY_RELEASE (read-only) KEY_PRESSEDn (read-only) KEYn counters check whether the key with the keycode n is pressed; a counter value of 1 means yes, 0 means no. KEY_RELEASE contains the keycode of the last key released, or is 0 if a key is currently being held. These display/use the same keycodes as KEY_CODE, but do not cause an autorepeat stall. Results are unsigned, so checking for negative numbers will not work. KEY_PRESSEDn counters function like KEYn counters, but use KEY_PRESSED's keycodes. As multiple KEYn and KEY_PRESSEDn values can be 1 at the same time, these counters can be very useful for detecting key combinations. RANDOM_SEED0 (universal) RANDOM_SEED1 (universal) These counters allow reading and controlling MegaZeux's random seed. RANDOM_SEED0 controls the low 32 bits of the seed, while RANDOM_SEED1 controls the high 32 bits. The random seed is not retained by save files. MAX_SAMPLES Sets number of samples that can play at once. -1 sets no limit, 0 mutes all samples; -1 is the default setting. The actual sample limit will be the smaller of the limit set by this counter and the limit set by the max_simultaneous_samples config file setting. PC Speaker emulated sounds are unaffected. XPOS YPOS The X or Y-coordinates (respectively) used by the REL COUNTERS command. REL COUNTERS FIRSTXPOS FIRSTYPOS The X or Y-coordinates (respectively) used by the REL COUNTERS FIRST command. REL COUNTERS LAST LASTXPOS LASTYPOS The X or Y-coordinates (respectively) used by the REL COUNTERS LAST command. REL COUNTERS LAST Robotic Reference Manual Table of Contents

Using the Editor

The Robotic editor is quite simple to use. After selecting your Robot's character and name, you will enter the editor screen. There are three major sections to the editor screen: The top box, showing current statistics; the middle box, showing the Robot's program with the current line highlighted in the center; and the bottom box, showing helpful key shortcuts. To edit the Robot, you enter lines just as in editing scrolls. Use up and down or PageUp and PageDown to scroll between lines, and use Enter at the end of a line to insert new blank lines. Pressing Enter in the middle of a line will remove everything to the right of the cursor and place it onto a new, following line. Press Backspace at the beginning of a line to place its contents onto the preceding line (this be ignored if there is not enough space). After you enter a line, it will be checked for proper syntax. If it passes, it will be reformatted and redisplayed, and you can then enter another line; if it does not, it will be marked as ignored. The reformatting is unpreventable - Since MegaZeux tokenizes Robotic lines to conserve space, all irrelevant information such as extra spaces is lost. The editor attempts to print the lines in a visually pleasing manner. It is possible for MZX to reformat the line in a way you aren't intending, so double-check your line if MZX reformats it. All lines other than the current line will have the various elements such as strings and numbers highlighted in different colors. cXX-type color codes will be shown as their actual color. The current line is shown in a solid color and color codes are shown in the usual cXX format. The following keys are active within the Robotic editor: F1 - Help F2 - Color F3 - Character F4 - Parameter F5 - Char Edit F6-F10 - Macros F12 - Take Screenshot Alt+B OR Alt+Enter - Block Action Alt+E OR Alt+End - Mark Block End Alt+H - Hide Help / Borders Alt+I - Import Alt+M - Configure Macro Alt+O - Edit Single Line Macros Alt+S OR Alt+Home - Mark Block Top Alt+U - Unmark Block Alt+V - Verify Alt+X - Export Alt+BackSpace - Delete Entire Line Alt+Ins OR Alt+P - Paste Ctrl+F - Search Ctrl+H - Replace Ctrl+R - Repeat Search/Replace Ctrl+G - Goto Position Ctrl+Y - Redo Ctrl+Z - Undo Ctrl+I/D/C - Mark Line Ctrl+BackSpace - Delete Previous Word Ctrl+LeftArrow - Jump to Previous Word Ctrl+RightArrow - Jump to Next Word Ctrl+Home - Jump to Program Start Ctrl+End - Jump to Program End Esc - Exit Robotic Editor On Mac platforms, any command that uses the Alt key can take  (the command key) instead. F1 - Help Use F1 to bring up context-sensitive help at any time. F2 - Color F2 will bring up a menu of colors representing the current palette. Select a color and press Enter to insert a cXX color code into the current line corresponding to that color. F3 - Character F3 will bring up a menu of characters representing the current character set. Select one and press Enter to insert that character into the current line. No quotes or apostrophes are added. F4 - Parameter If you have just typed in the name of a thing, such as Ammo, F4 will allow you to select settings for it, placing a pXX parameter code for the chosen settings. This includes things that are turned into Custom things by setting their CHAR ID values to 255. If the thing is a valid MZX thing without meaningful parameter values, pressing F4 automatically outputs " p00". F5 - Char Edit Use F5 to edit and select a character for use with the Robotic CHAR EDIT command. This outputs the numbers needed for that command to visually match the character selected. F6-F10 - Macro F6 through F10 will insert short macros, customizable using Alt+O. If you have an extended macro set for these an input window for it will come up (see Configure Macro for more details). F12 - Take Screenshot Pressing F12 will make a 640x350 screenshot (in PNG format by default) in the working directory, using the software renderer. The file naming starts from "screen0". Alt+B OR Alt+Enter - Block Action Allows you to perform an action on the current block of lines. Possible actions are: Copy to the OS's clipboard, Cut to the OS's clipboard (copy it and then delete it), Clear from memory, or Export to a text file on disk. If no block is currently highlighted, the actions will take effect on the current line. Alt+Enter is the old and deprecated hotkey, left in to ease use for long-time users. Alt+S OR Alt+Home - Mark Block Top Alt+E OR Alt+End - Mark Block End Alt+S/E will mark the top or bottom of a block of lines. You can then perform various block actions on these lines. The marked lines are highlighted. Alt+Home and Alt+End are the old and deprecated hotkeys, left in to ease use for long-time users. Alt+H - Hide Help / Borders Alt+H toggles the horizontal borders and help key reference. Alt+I - Import Use Alt+I to import a text file or bytecode file into the current Robot. The new lines will be inserted into the current program, starting from the current line. Alt+M - Configure Macro Alt+M will load a box where you list the name of an extended macro to be configured (for example, type "1" to edit macro_1). After choosing a macro to edit, you will be able to set the various variables for the macro. Select OK to place the macro, Cancel to go back to the editor without placing the macro, and Default to change all values to their defaults. Alt+O - Edit Single Line Macros You can change the values of the five single-line macros here. Use ^ for Enter in the macros. If there is an extended macro in place of macros 1-5, it will override any single-line macro also set for that macro. The Config File Alt+U - Unmark Block The current block is unmarked. Alt+V - Verify Use Alt+V to determine if there are any invalid lines in the Robot, and if there are what their errors are. Each invalid line can be set to I (ignore), D (delete) or C (comment), which will be applied if the user selects OK. Only the first 256 errors will be listed. Alt+X - Export Use Alt+X to export either the current block or the entire Robot program to a text file or bytecode file on disk. If saved as text, one can then edit the program outside of MegaZeux or use the text file in other ways. Alt+BackSpace - Delete Entire Line The currently selected line is blanked. The empty line itself will remain. Alt+Ins OR Alt+P - Paste Alt+Ins or Alt+P will paste in the block last copied to the internal clipboard. The clipboard used is the OS clipboard, and as such is preserved between Robots and even between worlds. Ctrl+F - Search Use Ctrl+F to activate the Search menu. After inputting a string to find in the Search box and choosing options, the Robotic editor will search for the term starting from the current line and jump to the first string that matches. Wrap will ensure every line of the code is checked (otherwise all code above the current line will be ignored) and Case Sensitive will require the search string and the results match case exactly before giving results. Ctrl+H - Replace Use Ctrl+H to activate the Replace menu. The Search box takes the text to be changed, and the Replace box takes the text that replaces it. Replace only changes the first seen instance of the searched text, with the search starting from the current line. Replace All changes all of them at once. Once completed, the Robotic editor will jump to the last line changed by a replace action (if any). Wrap will ensure every line of the code is checked (otherwise all code above the current line will be ignored) and Case Sensitive will require any string matching the search string to also match case before being replaced. Ctrl+R - Repeat Search/Replace Use Ctrl+R after a Search or Replace action to repeat the action. Ctrl+G - Goto Position Use Ctrl+G to jump to the given Robotic line/column (if too high of a number is given, the editor will jump to the last possible line/column). Ctrl+Z - Undo Ctrl+Y - Redo Use Ctrl+Z to undo the most recent editor action(s). Ctrl+Y reverts an undo. Ctrl+I/D/C - Mark Line These commands mark the current invalid line as to be ignored, deleted, or commented out upon editor exit, respectively. If the line is valid Ctrl + C will turn it into a comment (truncating the end of the line if commenting would make the line exceed 241 characters). Note that comment-marking a comment will immediately strip the line. Ctrl+BackSpace - Delete Previous Word Use Ctrl+BackSpace to delete the word to the left of the cursor. Ctrl+LeftArrow - Jump to Previous Word Use Ctrl+LeftArrow to jump to the beginning of the previous word in the current line. Ctrl+RightArrow - Jump to Next Word Use Ctrl+RightArrow to jump to the beginning of the next word in the current line. If on the last word of the line, this command jumps to the end of the line. Ctrl+Home - Jump to Program Start Use Ctrl+Home to jump to the first line of the current program. Ctrl+End - Jump to Program End Use Ctrl+End to jump to the last line of the current program. Esc - Exit Robotic Editor This key will exit the Robotic Editor, unless any lines are marked as invalid. The statistics line across the top of the Robot editor shows the current line number, the current column within the line, the size of the Robot program versus the maximum size this Robot can reach, and the Robot's X/Y position. Use ESC to exit the Robot editor when you are done editing your Robot program. Robotic Reference Manual Table of Contents

Robots - What They Are and How to Use Them

Robots are the heart and soul of MegaZeux. Nearly anything you could want to do in MegaZeux - anything you see done in a MegaZeux game, many things you didn't know were possible - can be done with MegaZeux's Robots. Robots are programmed in their own programming language, called Robotic. Robotic is a fairly simple language to learn, but somewhat moderate to completely master. It is somewhere along the lines of BASIC, although more complex. If you've ever used Epic Megagame's ZZT, Robotic is vastly more complex than ZZT-OOP, although there are vague similiarities. There's a kludge or dozen to get really powerful things working, but you'll get used to them. To place a Robot in the editor, press F10 and select Robot. (You can also select Pushable Robot if you want things to be able to push the Robot.) Then name the Robot and select a character to represent it. You are then brought to the Robot editor, where you can program the Robot in Robotic. Robots are limited to the board, and there can be 255 of them on each board. They can be pretty large - 2MB in size, enough code space to create extraordinarily complex (or convoluted) programs. There is an exception: the Global Robot, which is outside of the board and runs at all times. Robotic Tutorial Table of Contents Robotic Reference Manual

Robotic Tutorial

Robotic has a few concepts that you must understand before you begin to program in it. You can skip this if you want, but it will help you learn Robotic much faster. A large portion of this will be obvious to anybody who has ever programmed in any language or used computers extensively.

Commands

You can have one command per line. A command is an instruction to MegaZeux or the Robot telling it to do something. A program is a series of commands that are ran right after another, from top to bottom (until told otherwise).

Parameters

A parameter is the part of the command that can change, such as numbers or colors. They specify how the command should be run or what it should affect. For example, in the command: WAIT 6 WAIT is the command, and 6 is the parameter. Many commands have multiple parameters. Parameters are often specified using #, "string", or [color] [char], etc.

Labels

A label is a point in a Robotic program that has been given a name. It is used as a reference point so the Robot can return to that point at any time, to allow actions like repeating sections of commands (looping) or reactions to certain events. Labels are written as follows - : "label"

Messages

A message is something one Robot sends to another, or an external event sends to a Robot, to tell it to do something. This involves jumping to the label corresponding to that message. For example, a Robot can tell another Robot to "Bounce"; That Robot will now be executing commands starting at the label : "Bounce" .

Coordinates

x,y coordinates are a pair of numbers representing a point on the current board. (0,0) is the upper-left corner of the board, and the first coordinate increases while going right, while the second increases while going down. You can find coordinates easily at the bottom of the screen when help is hidden, by pressing Alt+Y, or by pressing F6 in the game (only in editor playthroughs). x,y coordinates can be negative, but this is uncommon and used for special purposes only (e.g. using REL commands).

Strings

A string is a series of letters or characters, inside quotes. For example, "STRING", "Booga!", "-21_Trees-", or "[[]]".

Characters

A character is a single symbol, letter, number, punctuation mark, space, graphic, etc. All things are viewed as single characters. When using single characters in Robotic, they must be enclosed in apostrophes- e.g. 'X'. Certain characters must be inputted in specific ways to avoid problems with Robotic: \0 for character 0 (this won't work in strings, but will work for single chars) \t for tab (character 9) \n for newline (character 10) \r for carriage return (character 13) \" for quotation mark \\ for backslash

Colors

A color is a code representing a background/foreground color pair. They follow the format cXX, where X is 0-9, A-F or ? (which stands for any color). To enter color codes easily, use F2 in the Robot editor. The exact format of color codes is covered in another section. A quirk to keep in mind: any entity with a background color of 0 will display the background color of anything beneath it.

Directions

Directions represent one of the four cardinal directions of NORTH, SOUTH, EAST, or WEST. They can be abbreviated to N, S, E, and W. There are other directions, but these are the most commonly used. Hopefully you understood the above material, as knowledge of it is essential to program in Robotic. If you don't quite grasp it, you can return to it later, but you will need to understand it eventually.

Your First Robotic Program: HELLO WORLD!

First, open the Editor and create a Robot. Then open the Robot's programming box by pressing Enter twice while the Robot is highlighted. Now, type the following into the editor: * "HELLO WORLD!" end Here's what each line does. * "HELLO WORLD!" The * command puts whatever text is in the quotation marks on the bottom of the screen. (Actually, it's placed on the given message line row, which is the bottom by default.) All Robotic code starts immediately, so this particular statement happens right as the board with this Robot is loaded. end This ends the code. It is good practice to include the END command even when you don't think you need it; leaving the END command out can cause some problems such as text glitches or, worse, the running of any and all code after where you want your Robot to stop! That was really simple, wasn't it? Now let's step up to something a bit bigger.

Your Second Robotic Program

Create a Robot in the editor, and give it the following program: : "start" GO NORTH 2 GO SOUTH 2 GOTO "start" Now test the world. As you can see, this program makes the Robot move up and down. Let's analyze it line by line. : "start" As we know, this is a label. It marks the beginning of the program. GO NORTH 2 This quite plainly tells the Robot to move north two spaces. GO SOUTH 2 This tells the Robot to move south two spaces. GOTO "start" GOTO tells the Robot to jump to a label. In this case, the Robot returns to the label "start", effectively restarting its code. This particular Robot will be executing these lines of code for the entirety of the game, or until destroyed. Pretty easy so far, huh? You will probably find that Robotic's basics are easy to grasp. Let's try something a little more complex.

Your Third Robotic Program

Try the following Robot program: : "loop" / "NNEESSWW" GOTO "loop" : "touch" * "Hello!" CHAR 'X' END Testing will show you that this Robot runs around in a small square. Now try touching it. If you can catch it, the Robot will stop moving, change to an X and greet you! Let's look at this program. : "loop" A label. / "NNEESSWW" The / command tells the Robot to move along a given path. The path is represented with a string of the letters N, S, E, W, and I. NSEW represent the four cardinal directions, while I tells the Robot to wait for a bit before continuing. Our path tells the Robot to go north twice, east twice, south twice, and west twice, forming a square path. GOTO "loop" The Robot will now return to the "loop" label, continuing in a square path forever. Without an outside stimulus, the Robot will never do anything else. : "touch" Another label, but this one is special. When the player touches a Robot, by standing next to it and pressing against it, the Robot is sent to the label "touch". MegaZeux has several labels like this, called "built-in labels", that are triggered in specific ways. The following commands will be run when the player touches the Robot. CHAR 'X' This tells the Robot to assume the appearance of character X. Make sure that the X is in apostrophes ' and NOT quotes ".

Robot Interaction

Let's get some Robots to interact with each other. Put two Robots on a board, right next to each other. Name the left one Lefty, and give it this program: : "dance" / "WWWEEE" SEND "Righty" to "dance" END Name the right one Righty, and give it this program: END : "dance" / "EEEWWW" SEND "Lefty" to "dance" END Now test this board out. You will see a silly pair of dancing Robots, as they bump each other left and right. Let's examine their programs more closely. Since Righty has an END command as the first line, he isn't going to be doing anything until told; so, we look at Lefty. It's nothing we haven't seen, except for the SEND command. SEND "Robot" to "message" The SEND command allows one Robot to send messages to another, telling it what to do. In this case, Lefty will tell Righty to "dance", sending Righty to the label "dance". Knowing this, the behavior of the two Robots should be clear. Each one, in turn, moves away and back again, then it tells the other one to do this. This repeats ad infinitum. For a little practice, see if you can get them each to display a message at the start of their dance step. Make the messages different for each Robot.

Some New Commands

The following Robot will demonstrate some new commands and features. GIVE 6 AMMOS GIVE 5 HIBOMBS END : "shot" COLOR c2C [ "OKAY, I GET THE POINT. I NEED MORE IRON" [ "...and now a liver transplant :<" zap "shot" 1 END : "shot" IF "AMMO" = 0 "lecture" [ "...cut it out. =(" END : "bombed" . "Check this out..." . "(editor) I'm not impressed." * "ARRGHFRRAGGH I'M ALLERGIC TO BEING BOMBED" DIE END : "touch" * "Please leave me alone :/" WAIT 10 SHOOT SEEK END : "lecture" [ "Did you REALLY have to use all of your shots." END Test this Robot out, bombing, shooting, and touching it. The new commands and labels are explained below. GIVE 6 AMMOS Sensibly enough, this gives the player 6 units of ammo. GIVE 5 HIBOMBS This gives the player 5 high-strength bombs. : "shot" When the Robot is shot by a bullet, it jumps to this label. COLOR c2C This changes the Robot's color. The c2C represents Lt. Red on Red. To enter colors, press F2 in the Robot editor and select the color you want. The appropriate cXX code will be typed in for you. [ "OKAY, I GET THE POINT. I NEED MORE IRON" [ "...and now a liver transplant :<" The [ command is slick for a default. When encountered, all consecutive [ commands are put together to form one long message, which is then displayed in a Scroll-like window. It can be scrolled and viewed by the player. ZAP "shot" 1 The ZAP command tells the Robot to ignore a certain number of labels with the given name - in this case, the first "shot" label. The ZAP command always starts from the top. Using the ZAP command lets programmers give out different reactions for going to the same label. In this case, we get to go to the second "shot" label after we went to the first. IF "AMMO" = 0 "lecture" The IF command will jump to a label (in this case, one called "lecture") if the given condition is met, and will continue to the next line if not met. In this case, it will check to see if the AMMO counter is 0. The AMMO counter is a built-in counter MZX uses to represent how many units of ammo the player holds. : "bombed" When the Robot is bombed, or otherwise hit by an explosion, it is sent this message. . "Check this out..." . "(editor) I'm not impressed." Notice how this message was not shown in any way. The . command is used for comments, i.e. messages that are not to be shown. They are good for your own reference, so you know what you were trying to do with this Robot, or so you can keep notes of important things. DIE This command destroys the Robot forever. WAIT 10 WAIT causes the Robot to stop and sit for an amount of time. The time is in number of cycles (in this case, 10 cycles). A cycle is the amount of time it takes to update the board once, moving all the enemies and bullets, etc. Robots can run at different speeds; the default is cycle 1 (fastest, acts every cycle) unless a cycle command is placed inside the Robot. SHOOT SEEK The Robot will shoot a bullet in the indicated direction (in this case, the nearest direction the player is in).

Conclusion

You now should know enough Robotic for simple programs. Even more importantly, you should be able to scan the Robotic reference manual, including the command reference, and be able to learn many new commands. There are loads of important commands and concepts in the command reference that we have not yet mentioned, such as TELEPORT PLAYER, strings, file access, expressions, sprites, and the COPY class of statements. It is recommended that you at least skim each of the Robotic reference manual sections. Make sure you (eventually) read over every part of the reference manual, as there are many sections not covered in the tutorials. Especially of interest will be advanced topics like "The Vlayer and Its Uses", "Using MZMs", "Subroutines", "Debug Modes", and most newer help file additions. Robotic Reference Manual Table of Contents

The Global

The global Robot is a special-case Robot that is always present on every board of the game. It is immobile (technically off the board, but listed as at (-1,-1)), has a ROBOT_ID of 0, and cannot be destroyed or changed into another object, even through deliberate attempts to do so such as the EXPLODE command. All other traits of Robots, such as 2MB of Robot memory, reserved local counters and the ability to be copied, apply to the global. The global is accessed either through pressing G to access the Global Settings menu and then clicking Edit Global Robot, or by simply pressing Alt+G on the editor screen. The global is important because it not only exists on all boards, but also continues its state across boards. This allows for easy management of continuous global engines such as an inventory, status bars, and sidescrolling control, among other possibilities. If the global did not exist, a copy of the engine would be needed on every board, and the states of each such Robot would be separate (possibly leading to management problems). Certain commands (as hinted above) are worthless in the global. Obvious commands such as BECOME, EXPLODE, COLOR/CHAR and all command forms that take a relative direction (like LAYBOMB and DUPLICATE SELF [dir]) will be ignored. DIE, DIE ITEM and GOTOXY # # are completely ignored as well. Any checks at (-1,-1) will fail to detect the global. Finally, the global is the only Robot that ignores FREEZETIME and SLOWTIME states. This is extremely handy in creating the ability to pause and unpause a MegaZeux game, among other things. FREEZETIME # SLOWTIME # Robotic Reference Manual Table of Contents

Robotic Usages That Should be Avoided

There are several coding pitfalls in Robotic. While some are complex in nature, others can be easily avoided. In general, clean and efficient code is the least likely to cause unexpected errors as well as the easiest to repair. Listed here are several practices to avoid, as well as proper replacements. BAD: Creating anything with c?? or p?? Anything that has an undefined value will use a default that may be undesirable. The correct action would therefore be to define the object's color and parameter values. c?? and p?? generally exist for the sake of Robotic comparisons and conditional branching, not for being applied to actual objects. Sprites are an exception regarding color, since they refer to a set of placed characters with their own colors. GOOD: Putting in set values for colors and parameters when placing objects. BAD: Using global counters for temporary or localized work. There are several counters that are Robot-specific and don't eat up global counter space. local through local32 per Robot should be enough for almost everyone, and the local counters can be written to and read by other Robots as well (using the rN.local# counter form). If global temp counters are used in a Robot with several copies on the board, you will most likely run into problems. Unfortunately, using local counters can come at the cost of minor readability, since local counters cannot be given descriptive names. GOOD: Using local counters for temporary or localized work. BAD: Breaking a subroutine without returning or entering the middle of a subroutine. GOOD: Fully finishing and starting subroutines. This is especially important for built-in labels which can trigger very rapidly, such as #keyN. BAD: Using a high amount of if statements regarding one variable. GOOD: Using "label&number&" as the destination label in IF statements regarding one variable. BAD: Looping without using cycle-ending commands of any kind. Looping without CYCLE 1 or WAIT 1 in idle loops is more severe than one might think. Coupled with the "commands" counter set to a high number, loops without CYCLE 1 or WAIT 1 can absolutely choke a game's speed, especially idle loops, and potentially FREEZE YOUR GAME. GOOD: Including CYCLE 1 or WAIT 1 in every loop except loops that are designed to get a finite length task done as quickly as possible. You should add a CYCLE 1 or WAIT 1 for any loop that constantly checks for events (such as keypresses or board status). BAD: Setting the COMMANDS value to maximum. It's generally unneeded, and a loop without a cycle-ending command coupled with this change is a guaranteed way to cause freezes in MZX. MZX has safeguards for when this happens, but it is still very undesirable. GOOD: Setting the COMMANDS counter to a reasonably high value. Your code can utilize the extra processing speed higher commands-per-cycle allows, and if a loop without a cycle-ending command is accidentally created, it becomes apparent without requiring severe intervention. BAD: Ending Robots with a label. GOOD: Ending Robots with the END command. It's debatable whether putting END after commands that destroy the Robot (e.g. DIE, EXPLODE #) is necessary, but it is still recommended in order to prevent a habit of leaving it out in less redundant places. Robotic Reference Manual Table of Contents

Subroutines

Subroutines are returnable labels, in essence. After the subroutine actions finish, the Robotic goes to the line right after the subroutine call. Anywhere a label can be used, a subroutine can be called. Another way to think about it is a label with a place marker. Going to this label marks your previous place; when done, the program goes straight to the place marker and returns where it left off. Subroutines are accessed by using the # sign as the first letter. For example: goto "#example" would call the subroutine at the label "#example". To return to the next command after the call use goto "#return". In addition, one can go to the first subroutine's return position using goto "#top". A quick example of subroutines: * "YE SHALL NOT PASS UNLESS YOU GIVE ME SPACE." goto "#spacewait" * "THAT'S BETTER BUT YOU'RE STILL HERE. _CORRECT THIS_" goto "#spacewait" * "THANKS FOR YOUR COMPLIANCE!" wait 25 * "YOUR PASS WILL ARRIVE IN 6 TO 8 WEEKS! or now! byebyebye" set "PASS" to 1 die end : "#spacewait" : "spaceheld" cycle 1 . "If space is held down, progress no further." . "We want to force space to be pressed each time." if spacepressed "spaceheld" : "notspaceloop" cycle 1 if not spacepressed "notspaceloop" goto "#return" When sending other Robots to subroutines the behavior is slightly different. Because the Robot is pre-empted (interrupted) it will return to the same command it was at before going to the subroutine, not the instruction after. When using subroutines - especially with easily triggerable conditions - it is important to try to make sure that every subroutine send ends in a #return, or that every set of subroutine sends ends in a #top. The built-in labels can be especially problematic, as some can trigger rapidly in a short period of time. State management with LOCKSELF and/or ZAP is crucial. NOTE: Unlike older versions of MegaZeux, it is no longer needed to initialize the stack, so don't get confused looking at older examples of code and seeing odd statements like . "#*-1-2-3". These statements are now treated as comments, and you should mentally treat them the same way. Robotic Reference Manual Table of Contents

Expressions

Expressions in MegaZeux allow users to set counters or a displayed number to a mathematical expression. The possible inputs are: counters, constants, or a combination. Any expression in MegaZeux is bound in quotation marks and parentheses. For example, an expression adding 5 and 3 would be done in MegaZeux by inputting "(5 + 3)". Counters can be used inside expressions using single quotes or ampersands like so: "('five' + &three&)". Using single quotes is preferred to prevent confusion with the normal usage of ampersands to interpolate counters. Unlike in many other programming languages, MegaZeux does not follow a strict order of operations. Items in parentheses take precedence, then unary ops; ternary is evaluated last, with all other operator precedence solely determined by their positions. Unary ops are handled right-to-left; everything else is handled left-to-right. For example, "(5 - 4 * 20 / (21 - 16))" would evaulate to 4. 5 - 4 evaluates to 1; 1 * 20 evaluates to 20; 20 / (21 - 16) first evaluates to 20 / 5, which becomes 4. Whitespace between operators is not necessary. (5+3) is as valid as (5 + 3). MegaZeux cannot decipher directly nested ampersands or single quotes; such will cause MegaZeux to misinterpret your expression in different ways, depending on which you used. Therefore, using expressions for nesting is another benefit. Example: We set "r" to 1, "in" to 8 and "out18" to 11. We want to output the value of "out18". "(&out&r&&in&&)" would output (0r&in&). "('out'r''in'')" would output ('out'r''in'') "('out('r')('in')')" would output the desired result - 11. Nesting is limited only to the amount one can put in a single editor line - 241 characters. In expressions, the following operators may be used: Binary operators (value-argument-value): + Addition - Subtraction * Multiplication / Division % Modulo ^ Exponent (A^B is A to the Bth order/power) >> Bitshift Right (logical, not arithmetic) << Bitshift Left (logical, not arithmetic) >>> Signed Shift Right (arithmetic) > Greater Than < Less Than >= Greater Than or Equal To <= Less Than or Equal To = Equal To != Not Equal To a Bitwise AND (not logical AND) o Bitwise OR (not logical OR) x Bitwise XOR (not logical XOR) + Addition: Outputs the sum of the two given values. (3+2) would return 5. - Subtraction: Outputs the difference of the two given values. (3-2) would return 1. * Multiplication: Outputs the product of the two given values. (3*2) would return 6. / Division: Outputs the quotient of the two given values. (3/2) would return 1. Note that any fractional values will be truncated, i.e. have the decimal part of the number thrown out. % Modulo: Outputs the remainder of the two given values, when both values are positive. (5%3) would return 2. The modulo expression function and the modulo command may output different results if any number involved is negative; unlike the command, the modulo expression function uses a floored modulo. To explain, if the dividend is negative, than the result will be the divisor minus the remainder (e.g. (-5%3) would return 1); if the divisor is negative, than the result will be the additive inverse of the difference of the divisor and the remainder (e.g. (5%-3) would return -1); if BOTH are negative, the result will be the additive inverse of the remainder (e.g. (-5%-3) would return -2). ^ Exponent: Outputs the result of taking the first number to the power of the second number. (3^2) would return 9. >> Bitshift Right: Shifts the first number rightward by [second number] of bits. Info shifted off of the boundaries will NOT wrap around. Using an 8-bit counter for clarity's sake, (5>>2) would turn 5 [00000101] into 1 [00000001] by shifting two bits rightward. << Bitshift Left: Shifts the first number leftward by [second number] of bits. Info shifted off of the boundaries will NOT wrap around. Using an 8-bit counter for clarity's sake, (5<<2) would turn 5 [00000101] into 20 [00010100] by shifting two bits leftward. >>> Signed Shift Right: Also known as Arithmetic Right Shift. Shifts the first number rightward by [second number] of bits, but unlike normal bitshift right, shifts in whatever number was in the leftmost bit instead of always shifting in 0s. Info shifted off of the boundaries still will not wrap around. Using an 8-bit counter for clarity's sake, (5>>>2) would turn 5 [00000101] into 1 [00000001], while (-5>>>2) would turn -5 [11111011] into -2 [11111110]. > Greater Than: If the first number is greater than the second number, outputs 1 (TRUE); otherwise, outputs 0 (FALSE). (3>2) would return 1, (2>2) would return 0. < Less Than: If the first number is less than the second number, outputs 1 (TRUE); otherwise, outputs 0 (FALSE). (3<2) would return 0, as would (2<2). >= Greater Than or Equal To: If the first number is either greater than or equal to the second number, outputs 1 (TRUE); otherwise, outputs 0 (FALSE). (3>=2) would return 1, as would (2>=2). <= Less Than or Equal To: If the first number is either less than or equal to the second number, outputs 1 (TRUE); otherwise, outputs 0 (FALSE). (3<=2) would return 0, (2<=2) would return 1. = Equal To: If the first number is the same value as the second number, outputs 1 (TRUE); otherwise, outputs 0 (FALSE). (3=2) would return 0, (2=2) would return 1. != Not Equal To: If the first number is a different value compared to the second number, outputs 1 (TRUE); otherwise, outputs 0 (FALSE). (3!=2) would return 1, (2!=2) would return 0. a = Bitwise AND: Performs a bitwise AND operation on the two given values; i.e. compares the bits of each value and sets to 1 each bit that is 1 in both numbers. Using an 8-bit counter for clarity's sake, (5a3) would return 1, as 5 [00000101] and 3 [00000011] has only the bit in the ones place set in both numbers, leaving 1 [00000001]. o = Bitwise OR: Performs a bitwise OR operation on the two given values; i.e. compares the bits of each value and sets to 1 each bit that is 1 in either number. Using an 8-bit counter for clarity's sake, (5o3) would return 7, as 5 [00000101] and 3 [00000011] have bits set in the fours, twos, and ones places among them, leaving 7 [00000111]. x = Bitwise XOR: Performs a bitwise XOR operation on the two given values; i.e. compares the bits of each value and sets to 1 each bit that is different between numbers. Using an 8-bit counter for clarity's sake, (5x3) would return 6, as 5 [00000101] and 3 [00000011] have different bits set in the fours and the twos places, leaving 6 [00000110]. Unary operators (operator followed by value): - Unary Negation: returns the negative value of the operand (two's complement); i.e. reverses the sign of a number. (-10) would return -10. ~ Bitwise Negation: returns the bitwise NOT value of the operand (one's complement); i.e. changes each bit in a number. Using an 8-bit counter for clarity's sake, (~10) [00001010] would return -11. [11110101] Ternary operators (value - operator token - value - operator token - value): ?: Conditional Operator: Evaluates expressions based on the value of the first given expression. This operator is often simply called the ternary operator. If the expression to the left of the question mark is non-zero, the expression between the question mark and colon is evaluated; otherwise, the expression to the right of the colon is evaluated. For example, If "local" is 35, SET "local" ('local'<60?'local'+2:'local'+1) would set the value of "local" to 37, as the first expression evaluates to 1 and the second expression ('local'+2) is then evaluated. Special usages: -Using a constant expression "(n)" is the only way to directly use numbers over 32767 or under -32768. This can not be changed due to the way the world file format is coded. This is also the only way to use octal (base 8) and full-sized hexadecimal numbers; octal numbers always begin with a 0 (ex: 01745) and hex numbers begin with 0x (ex: 0xDEAF). Robotic Reference Manual Table of Contents

File Access

MegaZeux allows somewhat unwieldy but powerful file access abilities. File access can do things that no other tools of MegaZeux can do, such as create high score tables or preserve and unlock game options without needing a save. An MZX world can access any file in its own directory or deeper, including for charset, palette, sound and MZM loading commands. To do this, give MZX the subdirectory name as well as the file name. Both slashes and backslashes are accepted, regardless of OS. Examples: "subdir/subsubdir/file.txt", "subdir\\file.txt". Access of folders outside of this range is forbidden. MegaZeux has some ways of accessing standard formats in-game: SET "file.txt" to "SAVE_ROBOT" SET "file.txt" to "LOAD_ROBOT" SET "file.txt" to "SAVE_ROBOTn" SET "file.txt" to "LOAD_ROBOTn" These commands can save Robotic code to text files and import text files into a Robot. The first forms use the current Robot, while the second forms use the Robot with the given Robot ID n. String inputs are also accepted in place of hard-coded file names. SET "file.bc" to "SAVE_BC" SET "file.bc" to "LOAD_BC" SET "file.bc" to "SAVE_BCn" SET "file.bc" to "LOAD_BCn" These commands can save Robotic code to files in bytecode format and import bytecode files into a Robot. The first forms use the current Robot, while the second forms use the Robot with the given Robot ID n. Bytecode is much more compact than plain text, but cannot be easily read by the human eye. Note that for loading Robotic code via LOAD_ROBOT(n) or LOAD_BC(n), any and all local counters previously set in the Robot will retain their value. SET "file.sav" to "SAVE_GAME" SET "file.sav" to "LOAD_GAME" These commands save or load MZX savegames, respectively. SET "file.sav" to "SAVE_COUNTERS" SET "file.sav" to "LOAD_COUNTERS" These commands respectively save or load a counters file. Counter files only contain counter and string data (to be specific, only global and current board counters/strings). Unlike save files, they do not require version checks. Saving will dump the current contents of the current world's counters and strings; loading will set the current world's counter and string values to the values given in the file. SET "file.palidx" to "SMZX_INDICES" This command loads an SMZX indices file. SMZX indices are essentially miniature palettes and will only load in SMZX Mode 3. MegaZeux can manipulate any type of file with certain Robotic commands. Here are some basic things to remember when using file access. -A file can only be read or written to at one time, never both. This means you can't select the same file to be the current "FREAD_OPEN" and "FWRITE_OPEN" targets. -Only one file can be read to and one can be written to at the same time. -Writing and reading operations change the current fwrite and fread positions. -The writing and reading position is set to 0 (the beginning position of a file) when a file is loaded, unless the FWRITE_APPEND command is chosen. -There is a special character called the terminator (char #42, '*', by default) placed at the end of a write when a string is written to a file with FWRITE. This character ends an FREAD to a string when encountered (the terminator character itself will not be in the string output). However, using FWRITEn will not place a terminator, and FREADn will ignore any terminator characters encountered. -To find the length of a file, use the FREAD_LENGTH and FWRITE_LENGTH counters. They will report the length of the file (in characters) currently open in the respective mode. If a directory is open for reading, the counter will be the number of files and subdirectories in that directory. If there is no file or directory open, these counters will return -1. -Lastly, files need to be closed when the current task is finished. Otherwise, the file remains open and causes problems. To close a file, use SET "" to "FREAD_OPEN" to close a file for reading and SET "" to "FWRITE_OPEN" to close a file for writing. Here are the file writing commands at your disposal. SET "file.xxx" to "FREAD_OPEN" This command loads a file for reading. SET "file.xxx" to "FWRITE_OPEN" This command creates a new file for writing. If a file by this name already exists, it is overwritten. SET "file.xxx" to "FWRITE_MODIFY" This command opens an existing file for reading without overwriting it, starting at the beginning of the file. SET "file.xxx" to "FWRITE_APPEND" This command opens a file for writing at the END of the file. Please note that FWRITE_POS settings will not work in this mode. SET "FREAD_POS" to # SET "FWRITE_POS" to # These commands change the current reading or writing position of the accessed files. The position is in DECIMAL, not hexadecimal, and the first position is 0; when no file is loaded, the relevant counter is -1. Setting "FREAD_POS" or "FWRITE_POS" to -1 is called "file end seeking" and will set the relevant counter to the final position in the file (or -1 if the file does not exist). This is very helpful for placing stuff at the end of a file. SET "dir" to "FREAD_OPEN" This command opens subdirectories for reading (by using the name of the subdirectory by itself, e.g. SET "directory" to "FREAD_OPEN"). FREAD will then list the names of files in the directory, with each read position being a different filename. To read the directory the current world is in, SET "." to "FREAD_OPEN". Note that the files are not guaranteed to be read in any specific order. SET "FREAD_DELIMITER" to # SET "FWRITE_DELIMITER" to # These commands change the character considered the terminator. The FREAD command changes which character is detected as the terminator, and the FWRITE command changes which character is written as the terminator. SET "FWRITE" to "counter" SET "$string" to "FWRITE" SET "$string" to "FWRITEn" SET "counter" to "FREAD" SET "$string" to "FREAD" SET "$string" to "FREADn" These commands write values to and read values from, respectively, the open file relative to the FWRITE_POS or FREAD_POS counters. FWRITE and FREAD, when used with counters, only write one byte at a time (from 0-255). The SET "$string" to "FWRITEn" and "FREADn" commands will write the first n characters (relative to FREAD_POS or FWRITE_POS) from the file to the given string or read the first n characters from the string into the open file, respectively. Using SET "$string.N" to "FWRITE(n)" will ensure that the string will be at least N characters long when written. FWRITE and FREAD, when used with counters, can be substituted by FWRITE_COUNTER and FREAD_COUNTER to read in longer values at a time (four bytes as opposed to one). SET "counter" to "FREAD_COUNTER" Reads from the open file to a counter. This will grab four bytes instead of one (treated as signed, so the range is from -2147483648 to 2147483647). SET "FWRITE_COUNTER" to "counter" Writes from a counter to the open file. This will write all four bytes of the counter instead of just the first byte (treated as signed, so the range is -2147483648 to 2147483647). Here's a quick example of file access. SET "example.txt" to "FWRITE_OPEN" SET "$zoosound" to "ROAAAAR" SET "$zoosound" to "FWRITE" DEC "FWRITE_POS" by 1 . "This line backs us up one space so that the terminator . "character will be overwritten, allowing us to display the" . "whole contents of the file." SET "$ender" to " (click)" SET "$ender" to "FWRITE" SET "" to "FWRITE_OPEN" . "We're closing the file because we're going to read from it." SET "example.txt" to "FREAD_OPEN" ASK "Want to play your animal sounds tape?" END : "yes" SET "$tape" to "FREAD" * "&$tape&" WAIT for 30 ZAP "yes" 1 ASK "Want to play it again?" END : "yes" SET "" to "FREAD_OPEN" . "Switching tasks for the same file again." SET "example.txt" to "FWRITE_OPEN" . "We're wiping the file clean." SET "$winder" to "bzz-bz-zipfwip--(clik) " SET "$winder" to "FWRITE" DEC "FWRITE_POS" by 1 SET "$tape" to "FWRITE" SET "" to "FWRITE_OPEN" SET "example.txt" to "FREAD_OPEN" ZAP "yes" 1 : "yes" SET "FREAD_POS" to 0 . "We're forcing the beginning position because we want to" . "read all of the file every possible time, not just the" . "first time." SET "$tape" to "FREAD" * "&$tape&" WAIT for 30 ASK "Want to play it again?" END : "no" SET "" to "FREAD_OPEN" END This Robot will display first a roar and the sound of a tape player clicking off before it asks if you want to play the tape again. If no, the file is closed and the program ended. If yes, rewinding tape sounds are stuck on the front of the text. The player can then choose to re-view this text until "No" is chosen. Here is another example, for a basic and very common use of file access: using and updating a high score list. SET "game.hi" "FREAD_OPEN" SET "NAME_LENGTH" 3 SET "SCORE_LENGTH" 4 SET "ENTRY_LENGTH" 7 SET "ENTRY_NUMBER" 10 . "We will allow 3 characters maximum for listed names here." . "File structure: initials (3 chars) and score (4 chars)." . "Ten 7-char entries total, no chars between them, in order." . "This assumes a fully-populated default highscore list." . "However, it should be relatively simple to create your own." SET "FREAD_POS" "('FREAD_LENGTH'-'SCORE_LENGTH')" . "First, we read the lowest high score value to compare." . "If our score is below it, no new high score." SET "local" "FREAD_COUNTER" IF "SCORE" >= "local" "newscore" SET "" "FREAD_OPEN" END : "newscore" . "Let's find out where it needs to go first." SET "FREAD_POS" 0 : "placecheck" INC "FREAD_POS" "NAME_LENGTH" SET "local" "FREAD_COUNTER" INC "local2" 1 IF "SCORE" >= "local" "placement" IF "local2" < "ENTRY_NUMBER" "placecheck" [ "WTF" . "We should never, ever, get here, but it's nice to check :)" SET "" "FREAD_OPEN" END : "placement" DEC "FREAD_POS" "ENTRY_LENGTH" SET "$temp" "FREAD('FREAD_LENGTH'-('local2'*'ENTRY_LENGTH'))" . "This places the lower, still-ranked entries into a string." . "We will write these scores to their new places later." . "We skip reading entry #10, as it no longer qualifies." SET "" "FREAD_OPEN" SET "game.hi" "FWRITE_MODIFY" . "This write mode keeps the previous contents intact." SET "FWRITE_POS" "('local2'-1*'ENTRY_LENGTH')" . "Setting to write in the correct place." INPUT STRING "Hooray! You're #&local2&! Enter your initials." SET "$temp2" "INPUT" . "The next line checks input length, as that needs to be 3+" IF "$temp2.length" < "NAME_LENGTH" "#correct" SET "$temp2" "FWRITE&NAME_LENGTH&" . "We only write the first 3 chars; ignore any extra." SET "FWRITE_COUNTER" to "SCORE" SET "$temp" "FWRITE('$temp.length')" . "The whole dang string goes into the rest of the file." . "Last example used FWRITE instead of FWRITEn for this." . "That leaves a terminator, though, which we don't want." . "This is another way to write it all with no terminator." SET "" "FWRITE_OPEN" . "Closing the file doesn't require the same write type." END : "#correct" IF "$temp2.length" = 0 "#default" : "add" . "Input was under three chars long, and we need three." INC "$temp2" " " IF "$temp2.length" < "NAME_LENGTH" "add" GOTO "#return" : "#default" SET "$temp2" "???" . "If the user doesn't put in anything, this makes initials ???" GOTO "#top" Code to properly display the scores will be an exercise left to the reader. File Access Counters Strings, Special Formatting, and Their Place in Robotic Robotic Reference Manual Table of Contents

Sprites

Sprites allow the designer to have interactive entities on the board composed of several characters. A sprite is a block of characters displayed on the board, either beneath or above the overlay. The biggest benefit of sprites is that they are cohesive: unlike use of several Robots, there is absolutely no chance of the sprite falling apart. Sprites also have the benefit of a well-defined draw order. This means that if sprites overlap, it is easy to determine which sprite gets shown in the overlap. By default, sprites determine this by sprite number. The sprites are drawn in order of sprite number, which means that parts of higher-numbered sprites will be displayed over lower-numbered ones whenever they overlap. There are up to 256 available sprites (globally, not per board), and sprites are controlled in the following ways: -Through sprite-specific counters named SPRn_value ("n" being the sprite number, e.g. SPR10_value modifies sprite number 10); -Through control counters for all of the sprites; -Through commands for placing sprites and testing for collision. A sprite's appearance is determined by a set of reference characters. These are characters on the board or the vlayer that make up what the sprite will look like. By default, sprites look for these characters on the board. As with the overlay, any instance of char 32 in the sprite will not be shown, instead displaying the next underlying layer. Also, if the reference characters change, the sprite's characters will change to match, as will colors of a c?? sprite. To set up a sprite you must set its SPRn_REFX / REFY / WIDTH / HEIGHT counters to define where the sprite's reference characters are and the sprite's size. (SPRn_REFX and SPRn_REFY are the x,y coordinates for the upper-left corner of the reference characters.) Then you use: PUT cXX sprite pNN x y where NN is the number of the sprite in hexadecimal (if you write NN without the p in decimal it will be automatically converted). If cXX is c?? then the sprite is drawn with the colors of the reference characters, otherwise it's painted with the given colors. Once a sprite is placed, it can be easily removed by setting its SPRn_OFF counter to any value. So, for example, to make a 2x2 sprite, you could base its reference characters on the board from the position (10, 10), assign it to sprite number 15, then have it drawn at position (40, 5). The Robotic for this is as follows: SET "spr15_refx" 10 SET "spr15_refy" 10 SET "spr15_width" 2 SET "spr15_height" 2 PUT c?? sprite p0f 40 5 You can then move the sprite around by changing spr15_x and spr15_y. For example, using: INC "spr15_x" 1 DEC "spr15_y" 1 will move the sprite to the northeast by 1. Outside of simple sprite motion such as this, you can do collision tests. These check if moving sprites will cause collision (i.e. overlapping) with either the foreground (customblocks) or with other sprites. This way, you can do things such as prevent sprites from moving into walls or other characters, or allow a sprite to damage another one when striking. For these, sprite collision boxes must be set, as sprites will not have one set by default. Use the SPRn_CX and SPRn_CY counters to set the respective x,y coordinates of the upper-left corner of the collision box, and use SPRn_CWIDTH and SPRn_CHEIGHT to set its respective width and height (in tiles). Once collision boxes are established, collision tests have to be triggered. This is done by using the following command: IF c?? sprite_colliding pNN x y "collision" This will go to the label "collision" if moving sprite NN x by y from its current position would cause it to collide with something. If anything besides c?? is used then it tests whether it would collide with whatever is at absolute board coordinates x,y instead. If collisions are detected, then the spr_clistN counters will be set to what sprite numbers it collided with - one counter set for each other sprite in the collision, starting with spr_clist0 - and spr_collisions will be set to the number of things that the sprite collided with. If the sprite collided with the foreground, spr_clist0 will be set to -1. So for instance, if the sprite collided with the foreground and sprites 2 and 3, spr_collisions will be set to 3, spr_clist0 will be -1, spr_clist1 will be 2, and spr_clist2 will be 3. If the sprite collided only with sprites 2 and 3, spr_collisions will be set to 2, spr_clist0 will be 2, and spr_clist1 will be 3. The values of spr_clistN with values of N greater than (spr_collisions - 1) are undefined. Alternatively, a collision check for a sprite can be done by setting that sprite n's "SPRn_CLIST" counter to anything. This checks that sprite against its current location and does not force a label jump on collision. Sprites can be set to ignore certain types of blocks in collision checks by setting the sprN_ccheck value of a given sprite N. In addition, setting a sprite's ccheck value to 2 will prevent blank characters in a sprite from being shown, much like char 32. Since sprites are global, they will persist upon changing boards. (They can, however, be turned off on leaving a board by setting the SPRn_OFFONEXIT counter to 1). Since the vlayer is global as well, using the vlayer to reference characters (by setting the SPRn_VLAYER counter to 1) will keep sprite characters consistent between boards.

Unbound Sprites

Unbound sprites are sprites with special implementations, allowing significantly greater precision and access to extra character sets. They have their own setup, their own quirks, and their own unique restrictions. A sprite can be set as unbound by setting the SPRn_UNBOUND counter to 1 for a given sprite number n. Once this is done, the sprite becomes "unbound" from the tile grid and immediately starts using pixels as reference for the collision box (SPRn_CX, SPRn_CY, SPRn_CWIDTH, SPRn_CHEIGHT), for sprite location (SPRn_X, SPRn_Y), and for values in Sprite_Colliding checks. Other attributes, such as reference location and sprite dimensions, are left in terms of tiles. Essentially, this means that sprite control and collision checks can now be easily pixel-based. (If, for whatever reason, a sprite is given tile-based x/y parameters and placed before setting as an unbound sprite, the sprite will not adjust its x/y location in pixels to match and will keep the literal x/y values, adjusting them to be in terms of pixels instead of tiles once the unbound status is set.) On top of pixel-based manipulation, unbound sprites have extended display options at their disposal. Unlike other sprites, unbound sprites are allowed access to up to 14 "extra" character sets. First, one must place characters in the extra locations. This can be done in two ways: with the LOAD CHAR SET command or the CHAR EDIT command. With LOAD CHAR SET, extra character sets can be loaded into their proper places by using the @ prefix to load it into proper positions. The first extra character set begins at position 256, the second at 512, the third at 768, and so on. (One could also load a character set file that is much larger than normal to fill these positions.) CHAR EDIT can manipulate individual characters of an extra charset by being given similar numbers, but the command cannot take them directly; one must feed it a counter with the desired number instead. Second, the sprite must be set to access these charsets. This is done by setting an offset for that sprite using the SPRn_OFFSET counter. For example, setting SPR0_OFFSET to 256 will change all character references done by sprite 0 to the first extra character set. As this process implies, each unbound sprite is still limited to one character set's worth of characters - 256 - simultaneously. However, different unbound sprites can accept different offsets and display their sets of characters at the same time, resulting in up to 3840 different characters loaded at once (not counting the system set). In addition to access to larger numbers of characters, unbound sprites can provide transparency effects on a per-sprite basis, instead of merely treating certain characters as transparent. Each unbound sprite has its own transparent color, which is set with the SPRn_TCOL counter. All pixels of that color in that unbound sprite will not display, and instead show the next underlying layer. When assigned a ccheck value with SPRn_CCHECK, an unbound sprite will only apply its personal ccheck value in collision tests instead of the value of the sprite that initiated the check. In addition, unbound sprites can use a special ccheck value (3) to ignore transparent colors in collision checks. Finally, SMZX modes do not affect unbound sprite movement and manipulation. This fact can be exploited to overlap SMZX sprites and potentially raise detail to normal MZX mode levels while retaining much of SMZX's palette benefits. See the Sprite Counters and Robotic sections for other features of sprites not noted here. Sprite Counters Robotic Reference Manual Table of Contents

Super MegaZeux Modes

Super MZX modes (a.k.a. SMZX) allow richer color options at the expense of halved horizontal resolution per character. The number of colors per character doubles to four, while the number of total max colors on-screen at one time squares to 256. However, each mode works differently and has different limitations and uses. In the editor, F11 switches display modes. To set Super MZX modes in a game, use the set "smzx_mode" # Robotic command, where # is the SMZX mode (0 to revert to normal mode). Super MZX mode 1 is the simplest mode and the easiest mode to use. SMZX mode 1 simply blends the foreground and background colors to get the third and fourth character colors. It is obviously limited, as this mode only allows editing of the 16 base colors, but is useful for anti-aliasing and shading effects. Super MZX mode 2 is the most difficult mode to use, although it has its benefits. It allows considerable control over the palette and allows for some overlay and sprite translucency effects. All 256 colors can be individually manipulated, and each color also represents a subpalette of four colors that is used by a character when an object is assigned that color. The four colors (values in hex) are determined as such: -Color I is the background color number as the first and second digits. (For example, if background color is 5, the hex number of color I is 55.) -Color II is the foreground color number as the first digit and the background color number as the second. (For example, if foreground color is 10 and background color is 5, the hex number of color II is A5.) -Color III is the background color number as the first digit and the foreground color number as the second. (For example, if background color is 5 and foreground color is 10, the hex number of color III is 5A.) -Color IV is the foreground color number as the first and second digit. (For example, if foreground color is 10, the hex number of color IV is AA.) Super MZX mode 3 is the best for dynamic usage of the palette, and the easiest to edit in general. By default, its four colors are determined around a base value in hex (background color number as first digit, foreground color number as second). Color I's number is the base, II's is base+1, III's is base+2, and IV's is base+3. The numbers wrap around (so if your base is, for example, FF, color II would be 00). However, one can also directly change each value in this mode, disregarding these limitations. This essentially allows 256 user-defined subpalettes of four colors each. These overrides, called SMZX indices, are loaded and saved out separately from the normal palette. These changes can only apply for renderers that can show unbound sprites (which is the vast majority of renderers). Character editing in Super MZX modes is noticeably different. While the character set can be edited in MegaZeux's internal character editor, certain changes occur. 1-4 selects the desired color; space no longer toggles between colors (it always sets here); right click no longer clears; clear mode is gone. Palette editing for SMZX modes is also accommodated by MZX's palette editor. However, the user needs to be in the relevant SMZX mode before loading the palette editor. On top of direct editing through the editor, SMZX palettes can be changed on the fly with Robotic. The counters for SMZX palettes are: SMZX_Rn SMZX_Bn SMZX_Gn Manipulation of these counters can change or read the value of color n's red/blue/green value, respectively. n ranges from 0 to 255, and counter values range from 0 to 63. The SMZX indices can also be directly read or changed with the SMZX_IDXx,y counter. x is the palette color ranging from 0 to 255; y is one of the given color's indices ranging from 0 to 3. Lastly, SMZX palettes and character sets can be loaded and saved like any other palette or character set. SMZX indices must be loaded in a special manner in Robotic: SET "filename" "SMZX_INDICES". There is a deprecated way to load an SMZX palette in Robotic (SET "filename" "smzx_palette") due to constraints DOS imposed, but it is no longer necessary. Super MZX Counters The Palette Editor Robotic Reference Manual The Character Editor Table of Contents

The Vlayer and Its Uses

The vlayer is an extra global graphical layer, but it is never directly seen in a game. It can only hold character and color info. The vlayer acts like a workspace allowing copying from/to overlay, copying from/to MZMs, copying between places in the vlayer, reading/writing individual graphical data to/from the vlayer, and reading strings from the vlayer. Another important aspect of the vlayer is the ability to reference a sprite to the vlayer. This allows indirect display of the vlayer through display of sprites. This can be exploited to create the semblance of extra overlay layers. The vlayer defaults to 32768 characters large (256x128); its size can be as large as roughly 16.7 million characters (2^24). It cannot be removed altogether. While in the editor, press Alt+V to enter the Vlayer Editor. The vlayer editor accepts the following commands: Alt+B - Block Press Alt+B to start block mode, then move the cursor to the opposite corner of a rectangular block and press Alt+B again. You can then select an action to perform upon the block. In all copy/move operations, the cursor marks the new UPPER LEFT corner. Copy block will allow you to duplicate the block by moving the cursor to a destination and pressing Enter. Copy block (repeated) is the same as Copy block but can allow copying of the same block to multiple places. Move block will allow you to move the block to a new location. Clear block will erase the contents of the block. Flip block will flip the block upside down. Mirror block will flip the block left to right. Paint block will change the entire block to the current color. Copy to board will copy the block to the given spot of the board. You can choose to place it as either Custom Block, Custom Floor, or Text. Copy to overlay will copy the block to the given spot of the overlay. Save as ANSi/TXT will save the block as an ANSi or TXT file. Save as MZM will save the block as a layer-type MZM file. Destinations for Move and Copy can overlap the original block safely. Ctrl+Dir is especially helpful when doing a repeated copy block; it moves the cursor the width or height of the block, ensuring no overlap when pasting. Like normal Block functions, one can copy between boards by selecting the board when the editor prompts the user for the block's destination. Use the B key to select the destination board. C - Color Press C to select a new current color from a menu. The thing under the cursor is not affected. One can jump to a color by typing its hex code in the color menu; for example, typing "0D" would jump to color 013 (background color 0, foreground color D). F - Fill Press F to fill in an enclosed area with the current character and color. The area must be completely surrounded by characters other than the character beneath the cursor. For example, you can fill over a solid square of As with something else. The current fill command may not work correctly for very large and complex areas - in this case, you must move to the unfilled areas and press F to continue filling. However, this happens very rarely. Alt+V - Exit Vlayer Editor Alt+V will exit vlayer mode and return to editing the main board. Alt+P - Size Alt+P will open the vlayer size menu. From here, one can change the dimensions of the vlayer; if the vlayer is shrank in one or both dimensions, the user will be asked for confirmation. Any characters removed by shrinking vlayer dimensions are lost, and any dimension settings that would cause the vlayer to go over its maximum size will be limited to the largest size possible by reducing the smallest given dimension until the vlayer is within size limits (if both given dimensions are the same size, width is reduced). Changing the size of the vlayer will clear the undo history of the vlayer. F1 - Help F1 will bring up context-relevant help. You can press F1 at almost any time. F2 - Text F2 will toggle text mode on and off. When text mode is on, Enter will go to the next line, and Backspace will delete going backwards. All printable characters will type in as text. Arrow - Move The arrow keys will move the cursor. The edit window will scroll when necessary. Alt+Arrow - Move 10 Alt with the arrow keys will move the cursor ten spaces at a time (or to a vlayer edge if it is under 10 spaces away in that direction). Backspace - Delete Del - Delete These two keys will delete everything under the cursor. The current character is not affected. End - L/R Corner End will jump the cursor to the lower-right corner of the entire vlayer. Enter - Character Enter will alter the current character on the vlayer. Select it from a menu and then press Enter to confirm your choice. ESC - Exit/Cancel Mode ESC will exit vlayer mode. If you are in block, text, or draw mode, ESC will instead cancel the current mode and return to normal vlayer editing. Home - U/L Corner Home will jump the cursor to the upper-left corner of the entire vlayer. Ins - Grab Ins will select the character and color under the cursor as the current. The actual character is not affected. Spacebar - Place Spacebar will copy the current character and color to the location under the cursor. Other characters will be deleted if they are under the cursor. Tab - Draw Tab will toggle the current draw mode. When drawing is on, you will place a copy of the current character every time you move the cursor. Ctrl+G - Goto Position Ctrl+G will pop up a window, displaying target x,y coordinates. Set the coordinates by either typing in or selecting the desired X and Y values, and select OK to go to those coordinates on the vlayer. Choosing Cancel or pressing Escape cancels. P - Change Buffer Character P will act much like Enter, but only change the character in the buffer. No character on the vlayer is changed with this action. Alt+Z - Clear (Vlayer) Alt+Z will clear the vlayer entirely. You will be asked for confirmation. Clearing the vlayer will clear the vlayer undo history as well. Ctrl+Z - Undo Ctrl+Y - Redo Ctrl+Z will undo an action; Ctrl+Y will redo any previously undone action. Action depth is determined by config file settings, with 100 as default. Ctrl+Number - Save Editor Position Alt+Number - Load Editor Position These save and load up to 10 cursor positions in the vlayer (0 through 9). These positions save the current coordinates in the vlayer. These positions are saved for that world in its .editor.cnf file. --- On top of being modifiable in the editor, the vlayer can be changed in a running MZX world with Robotic. To manipulate the vlayer in Robotic, "#n" is used instead of pure numbers in copy commands. For example, if copying a 2x2 block from (6,6) of the board to (0,0) of the vlayer is wanted, the command would be: COPY BLOCK 6 6 2 2 "#0" "#0" Here are the vlayer copy functions: Board to vlayer: COPY BLOCK x1 y1 w h "#x2" "#y2" Overlay to vlayer: COPY OVERLAY BLOCK x1 y1 w h "#x2" "#y2" Vlayer to board: COPY BLOCK "#x1" "#y1" w h x2 y2 Vlayer to overlay: COPY OVERLAY BLOCK "#x1" "#y1" w h x2 y2 Valid Robotic copies from vlayer to board are always CustomBlocks. In the commands below, COPY BLOCK and COPY OVERLAY BLOCK are interchangeable. Vlayer to MZM: COPY (OVERLAY) BLOCK "#x1" "#y1" w h "@name.mzm" m Vlayer to string: COPY (OVERLAY) BLOCK "#x1" "#y1" w h "$stringN" c Vlayer to itself: COPY (OVERLAY) BLOCK "#x1" "#y1" w h "#x2" "#y2" "m" and "c" can be any value but must exist. There are several ways to give the vlayer working coordinates: Pure numbers - "#xxx" Counter value - "#&counter&" Expressions - "#('counter' + x)" MZMs can be placed on the vlayer by using p02. Example: PUT "@visuals.mzm" image_file p02 x y Reading and writing single characters or colors from the vlayer requires the vch and vco counters. For reading and writing characters use "vchX,Y". For reading and writing colors use "vcoX,Y". For example: SET "vch10,10" '+' sets the vlayer char at (10,10) to a plus sign. SET "vco10,10" 15 sets the vlayer color at (10,10) to white on black. SET "temp" "vch10,10" sets temp to whatever the character at (10,10) of the vlayer is. Vlayer size can be changed by setting the counter "vlayer_size" to the desired length of the vlayer. Doing this only sets the maximum size; the actual vlayer will not be this large unless the vlayer's dimensions are changed. All attempts to set the vlayer's size above the maximum will be ignored. To change the vlayer's dimensions in Robotic, use the counters "vlayer_width" and "vlayer_height". When one dimension is given, the other becomes as large as possible to fill the given vlayer. For example, if one has a vlayer 50000 characters large and sets vlayer_height to 499, the vlayer's width will become 100 characters wide (for a total vlayer size of 49900 characters). All bad values of vlayer_size, vlayer_height and vlayer_width (0 and below) will be changed to 1. Remember that the vlayer is global. If many vlayers are wanted, liberal usage of MZM saving and loading can help get around this problem. Vlayer Counters Strings, Special Formatting, and Their Place in Robotic Using MZMs Robotic Reference Manual Table of Contents

Using MZMs

MZM files are rough equivalents of the ANSI files used in older MZX versions. MZMs, however, are much more powerful and can store much more information. MZMs can be up to 65535 x 65535 tiles in size. MZMs are useful for easy access of reused graphics and reused, multi-Robot entities. MZMs come in two modes: "board" and "layer". * Board mode saves color, param, ID, and under information. However, it cannot save the player, scrolls or sensors. Board mode can save most built-ins. As for Robots, MZMs saved in the editor will save fresh Robots, while MZMs saved in-game keep the Robots' current states. * Layer mode saves only color and char information. Any information not saveable will be replaced by a customblock facsimile. While in the editor, MZMs can be placed by using the import function (Alt+I) and choosing MZM. Layer MZMs can be placed on the board layer as CustomBlock, CustomFloor, or Text. When loading a board MZM file to the overlay or vlayer, the character used is the parameter stored. Outside of customblocks and related, different characters could appear due to different param settings (especially built-ins and Robots). One can save MZMs in the editor; use the block action function (Alt+B). MZMs saved in the editor from the board are saved as board; from the overlay and vlayer, MZMs are always saved as layer. Robotic methods of saving MZMs are: COPY BLOCK x y w h "@filename" p COPY OVERLAY BLOCK x y w h "@filename" p COPY (OVERLAY) BLOCK "#x" "#y" w h "@filename" m X/Y are the coordinates of the block's upper-left corner; w/h are the width and height of the block; filename is the name of the file (the @ is required); finally, p determines the MZM type. 1 saves as layer; 0 saves as board. 0 is integral for copying non-graphical data (especially Robots); 1 is proper for copying graphical data, as the block's appearance will stay as exactly as it was when saved. The last case is for saving from the vlayer to MZM. The x,y coordinates MUST be in "#x" "#y" format, and the m can be any value but MUST exist. Any valid MZX string can take the place of a filename, but the @ prefix is still required. Unlike with board MZMs containing Robots saved in the editor, loading board MZMs containing runtime Robots in the editor is unsupported. Any such Robot will be replaced with a customblock fascimilie. If you want any such MZMs to be fully loaded, they must also be loaded at runtime. The Robotic method of loading MZMs is: PUT "@filename" image_file pNN x y filename is the name of the MZM file (after the required @), x and y are the upper-left corner's coordinates, and NN is 00 for board, 01 for overlay, 02 for vlayer. Again, any valid string can take the place of a filename if preceded by the required @ prefix. Finally, MZMs will neither be saved nor loaded if at the edge of a board. Alt+B OR Alt+Enter - Block action Robotic Reference Manual Table of Contents

Trigonometric Functions

Trigonometry can simplify some complex engines, and MegaZeux can access several trigonometric functions with fair precision. However, accessing trigonometric functions in MegaZeux requires some setup. Because MegaZeux works solely with integers, you need to set the counter "multiplier" to determine how the non-integer working value is converted. For example, if your function has a value of .86602 and "multiplier" is set to 10000, the resulting value would be 8660. Results are always truncated (that is, have everything to the right of the decimal removed). The default value for the "multiplier" counter is 10000. The counter "c_divisions" determines the precision of the trig functions by determining how many times the circle is divided. Sensible values for this include 360 (degree precision), 21600 (arc-minute precision) and 1296000 (arc-second precision). The default value for the "c_divisions" counter is 360. The "divider" counter works solely on inverse trigonometric functions. Its effect is to divide the number passed to an inverse function before it is calculated. For example, if you have "divider" set to 100 and try to calculate "acos50", MZX will calculate the arccosine of .50 (50 divided by 100), outputting 60 degrees. The default value for the "divider" counter is 10000. These are the trig functions MegaZeux can directly utilize. SIN - sine COS - cosine TAN - tangent ASIN - arcsine (inverse sine) ACOS - arccosine (inverse cosine) ATAN - arctangent (inverse tangent, takes signs into account) ARCTAN - atan2 (special form of arctangent, takes two values in the form of ARCTANdy,dx ("dy" is the first input, "dx" the second)) NOTE: The inverse functions output degrees, not radians. To use the counters you put the unit number after the counter name. Here's an example. To display the cosine of 30 degrees with degree-based precision, the needed line would be: * "&cos30&" Trig functions can also take expressions and counters. However, counters can only be inserted through expressions; a construct like "&sinlocal&" will not work, but "&sin('local')&" will. Mathematical Counters Robotic Reference Manual Table of Contents

Cycles and Board Scans - How MZX Processes Robots

Knowing MZX's commands is important for coding, obviously, but knowing how and when they get executed can be just as paramount. After executing code in the global Robot, MegaZeux executes Robotic code by scanning the board from the top-leftmost Robot first, then proceeding from left-to-right, jumping down to the beginning of the next line when at the end of its current line, and ending at the Robot in the bottom-right corner. This action is called a BOARD SCAN. MegaZeux then does a clean-up scan in reverse to catch certain actions. This complete act of scanning a board and executing any Robotic commands is called a CYCLE, and when a Robot completes all of its commands for that cycle, it's called ENDING A CYCLE for that Robot. After a cycle is executed, the display is updated, so MegaZeux's internal frame rate is essentially the same rate as the number of cycles executed per second. By default, MegaZeux will run up to 40 commands per Robot in a cycle. Setting the COMMANDS counter can set the number of commands processed per Robot per cycle to be lower or (significantly) higher. Some commands, however, have the ability to end processing prematurely; these are called cycle-ending commands. When the COMMANDS value is very high, MegaZeux can end up consuming large amounts of processing power in a single cycle. Cycle-ending commands can limit the number of commands processed in a cycle to only what is necessary. Otherwise, very high COMMANDS values can potentially slow down MegaZeux or even cause MegaZeux to trigger safeguards that prevent it from freezing. The two commands that are best suited for ending the cycle are WAIT 1 and CYCLE 1, because of their very low amounts of side effects. While WAIT 1 is preferred in most cases, mostly due to being far more intuitive, there is a subtle difference between processing the two due to its quirk with reverse scan detailed later in this section. As a simple rule of thumb, commands that move anything on the board generally end a cycle, especially moving the player, though this is not always the case. The amount of cycles MegaZeux processes per second is set by the MZX_SPEED value. Speed 1 is completely processor-bound and will execute as many cycles per second as possible. Other speeds process cycles according to this formula: 62.5 / (MZX_SPEED - 1) = cycles per second Simplified, this means that MegaZeux can be set to consistent rates ranging from 62 & 1/2 cycles per second (speed 2) all the way down to 4 & 1/6 cycles per second (speed 16). The CYCLE command dictates how often a Robot is active. By default, Robots will execute commands on every cycle, but the CYCLE command can cause a Robot to spend a certain number of cycles idling before executing commands. Robots can go from executing 1 out of every 1 cycles (i.e. every cycle) to 1 out of every 255. Special care should be given to the scan that happens in reverse to clean up certain actions. This scan ensures that if a Robot sends a Robot that has already executed its commands to a label, then the target Robot can actually be sent to the proper label. Certain commands in the target Robot - specifically, the cycle-ending commands that can act across multiple cycles - can cause that Robot to execute the new label commands in the very same cycle. The global Robot is exempt from this process. Commands that can prompt this behavior are: / "string" END GO [dir] # TRY [dir] "label" WAIT # Anything besides solely one of these commands ran in the target Robot's cycle (even blank lines!) will prevent the target Robot from executing in the same cycle. There is an exception for Robots using CYCLE # values over 1: being in such a Robot's idle cycles will trigger a same-cycle execution. For more detailed information about what commands end cycles and when, read cycles_and_commands.txt in the additional documentation. Table of Contents

Partial Character Sets

Partial character sets are smaller than full sets, as the name definitely implies, but they only overwrite the characters they are told to when loaded. This leaves the rest of the characters intact. Heavy animations and changes that keep part of the character set intact (such as the alphanumeric characters) are two issues best tackled with partial character sets. One can save a partial character set in the editor by selecting a starting character value (aka "offset") and a length value. These fields show up when you export a character set, under the filename input. To load partial character sets into your current set, you have two options. You can firstly load it as you would a normal character set; this replaces all characters from the start of the target character set until the end of the partial set. Secondly, you can load the partial set into a non-0 position of the target character set. In the editor, this can be done by setting the offset field in the import character dialog, under the filename input. The @xxxx prefix allows this in Robotic; xxxx is the number (in decimal) of the first character to replace in the target character set. Robotic Reference Manual Table of Contents

The MegaZeux Updater

Modern MegaZeux versions on supported platforms, such as Windows, have the ability to update MegaZeux from MegaZeux itself. The updater can be set to run by pressing either F7 or U on any title screen. It can also be configured to check for updates every launch in config.txt settings, or disabled altogether. MegaZeux checks the sites listed under the config.txt settings, in order. By default, the updater checks the Stable branch of MegaZeux, but can be set in config.txt to other branches (such as Unstable or Debytecode). If a host reports back that your version of MegaZeux is current, the next host can be checked to see if they differ. If a new version of MegaZeux is detected, MegaZeux offers the user these choices: -Upgrading to the new version using the "Upgrade" button. -Updating the current version to whatever minor "refreshed" version may exist (where the version number remains the same, but a small issue or two not caught before release is fixed) using the "Update Old" button. -Cancelling out of the update process with the "Cancel" button. No changes are made. Once the option is chosen, MegaZeux lists what files will be added, changed, or deleted by the pending update. At this point, the user can still cancel out of updating with the Escape key. Pressing Enter at this point begins the updating process. The updater will then attempt to download the necessary files for the update. The download indicator lists the current file being downloaded, its size in bytes, and current file number out of total files to be downloaded. If all files are properly downloaded, MegaZeux will apply the update and notify the user of a restart. Click "OK" and MegaZeux will restart, fully updated. Table of Contents

NEW in MegaZeux!

September 10th, 2024 - MZX 2.93b This is mostly a big bugfix release, but there are a few new features of note. First and probably of most interest, there is a new feature to export a full screenshot of an entire board or the entire vlayer from the editor. Renderers based on the software layer renderer should see some performance improvement. The Darwin multiarchitecture .app port has also been massively overhauled, and now targets up to 5 architectures (ARM still pending). libxmp now plays stereo samples correctly. DOS port users should be happy to hear that Sound Blaster Pro support has been restored, and support for even more sound cards is coming. Additionally, some Ogg Vorbis-related crashes have been fixed, and the SVGA renderer should work better than prior. Screenshots have been enabled for this port, and the TIME/DATE counters should now work properly. Finally, as usual, there are a large number of bugfixes, which includes several crash fixes, scroll fixes, and FREAD fixes. No compatibility checks have been added for the string splice FREAD/FREADn bugfixes, as the old behavior was unusably buggy. USERS + Added board and vlayer image export to the editor (Alt+X). This feature will render the entire board (with overlay, if applicable) or vlayer as it appears in the editor. This may take a long time with large boards/vlayers. + Builds without libpng (Android, DOS) now use a simple fallback PNG exporter for screenshots instead of falling back to BMP. + The DOS port now supports Sound Blaster Pro in stereo mode. The driver should also support all other Sound Blasters with DSP >=2.00 and the mono/8-bit modes of the Sound Blaster 16, but these are disabled for now (no software mixer support for mono output). IRQs higher than 7 are also supported now. + The DOS port now uses stb_vorbis for Ogg Vorbis playback, which should fix most audio-related crash bugs. Related crash bugs caused by stream management have also been fixed. + All "gamecontroller[...]" config.txt options have been renamed to "gamepad[...]". The old names are still supported. + Windows UNC paths are now supported in the file manager. + Paths with colons (:) are now explicitly supported in Linux and macOS and always rejected in path strings used by worlds. + Fixed blank screen bugs that occur with the glslscale renderer in conjunction with Intel HD Graphics 2500 graphics drivers and possibly some other old drivers. + The softscale renderer now respects disable_screensaver. + HTML5: fixed the poor performance of FREADn and other features that rely on calculating the length of an open file. + Clear world (Alt+R) now resets the world version. + Fixed a crash bug and a false positive match bug in the command IF ALIGNEDROBOT. The false positive bug has been version locked to 2.80 through 2.92X (just in case). + Software layer rendering performance for transparent sprites has been improved, significantly in some cases. + Fixed a software layer renderer bug where a buffer with a pixel alignment that varies between lines would cause the frame to render incorrectly. + Fixed a software layer renderer bug in 32-bit builds where SMZX sprites would sometimes render incorrectly when clipping off the left side of the screen. + Setting a string offset, limit, or splice to FREADn now respects the provided limit. If n is larger than the limit, n total bytes will still be read (up to the maximum string size); any bytes read past the limit are discarded. + Setting a string offset, limit, or splice to FREAD now respects the provided limit and no longer pads the string with spaces in some cases. Setting any string to FREAD now reads the file until a terminator or the end of the file is found instead of stopping when the maximum string size is reached; any bytes read past the limit or maximum size are discarded. + Setting a string splice to FREAD or FREADn with invalid offset or size values no longer causes a crash. + Setting a string splice to FREAD with a valid offset that would write past the current length no longer causes a crash. + Fixed a rare networking bug where fetching a compressed file over HTTP could fail for particular compressed file sizes. + The About MegaZeux dialog now shows both the compiled and linked versions of libpng if they are different. + Fixed flash thing layer draw order bug that would cause it to display over editor elements using the game UI layer. + Licenses are now properly loaded in the About MegaZeux dialog for Darwin builds. + Fixed potential heap overflows in mfread and mfwrite when the current position is past the end. This should never actually happen, but it's safer and shuts up _FORTIFY_SOURCE and ASan compilation warnings. + Fixed platform-dependent out-of-memory errors when loading robots from <=2.84 save files with corrupt stack sizes. + Fixed hangs in the robot editor caused by trying to use Replace All to replace quotes or extra words with nothing. + Fixed the handling of lines over 64 characters long during scroll editing. Scroll editing now previews colors and allows lines up to 255 bytes in length. Like robot message boxes, any characters past the first 64 will clip. + Clicking a line in the scroll display and editor now jumps to that line (same as the help file). + You can now toggle between editing scrolls with the protected palette/charset and the game palette/charset with Alt+V. + Games for versions 2.80X through 2.90X now display scrolls using the protected palette instead of the game palette (fixes a scroll in Welkin). + Fixed possible robot stack and scroll message memory leaks. + Fixed a 2.93 regression where color strings with escapes like "~x", where x is not a hex digit, would also print the ~ or @. + Fixed clipping of the board message when it contains color codes and when the message column is set to something besides centered or 0. The next row will also use the correct color code from the previous row (as if there had been no clipping) instead of whatever the last color code displayed was. The old behavior is version locked to <=2.93, so this fix won't take effect until 2.94. + Added compatibility for MegaZeux 1.x's reverse send behavior which allows robots to execute twice per cycle in some cases. + Fixed COPY when used with REL COUNTERS for 1.x worlds. + Added support for MegaZeux 1.x entrance precedence (color match, then thing match only). This fixes an entrance bug in MegaZeux Tutorial. + Added support for MegaZeux 1.x entrances linking to other entrances on the same board. This fixes the whirlpools in the Aqua Cavern board in Caverns of Zeux. + Added support for MegaZeux 1.x entrances not triggering when the player is pushed onto them. + Added support for MegaZeux 1.x TELEPORT interrupting the current board scan and partial support for the same behavior in RESTORE PLAYER POSITION/EXCHANGE PLAYER POSITION. + The DJGPP port now locks all of its memory. This prevents paging crashes related to audio, but increases memory usage. + Fixed the TIME and DATE counters in the DOS port when the environment variable TZ is not set. + The SDL audio driver will now initialize the software mixer frequency with the value returned by SDL_OpenAudioDevice. + Fixed audible pops when setting MOD_FREQUENCY. + ccv and png2smzx now return slightly more useful error messages when an image fails to load. + ccv and png2smzx now support BMPs that use BI_BITFIELDS and BI_ALPHABITFIELDS. + ccv and png2smzx now support Truevision TGA images. + Fixed YUV subsample averaging for UYVY (little endian) and YUY2/YVYU (big endian). + ANSi file import/export options are now identified as both ANSi and TXT, and the extension of the selected format is now forced during export. + Fixed taking screenshots when in the board editor text mode. + The SVGA renderer now uses vsync palette/display page flips, which improves performance and fixes display bugs. (asie) + Fixed libxmp stereo samples not playing correctly. + Fixed libxmp music not playing at high audio sample rates. DEVELOPERS + Renamed "compat_sdl.h" to "SDLmzx.h". This header is now used to abstract ALL trivial includes of SDL headers. This makes supporting the future release of SDL 3 cleaner. + The version of SDL to build with is now determined by the config.sh options: --enable-sdl (enables the default SDL version, usually 2); --enable-sdl2 (enables SDL 2.x); --enable-sdl1 (enables SDL 1.2.x); --disable-sdl (disables SDL). For compatibility, "--disable-libsdl2" is still recognized. + Added SDL 2 support to the Wii port. + Added SDL 2 and SDL 1.2 support to the 3DS port. (asie) + Updated the "sdlaccel" renderer, which can now be enabled with --enable-sdlaccel in config.sh. This renderer uses the SDL renderer API for hardware rendering and has an experimental threaded charset texture update routine. SMZX isn't currently implemented and it's slow, so it's disabled by default. + Moved SDL renderer window creation to render_sdl.c so both of the SDL renderer-based renderers can benefit from it. + Removed floating point division usage in render_gl2.c. + Added --enable-lto to enable link-time optimizations. + The sanitizer config.sh options can now be used with release builds e.g. --enable-release --enable-asan. + Simplified the configuration of system directories for ports in config.sh, which now prints more information about them. + Fixed config.sh output of "/usr/bin/git" and the Git HEAD. + Fixed testworlds process running check edge cases. + Fixed config.sh and platform_endian.h detection for IBM Z and System/390 architecture. + Software mixer configuration (rate, buffer, channels) is now done using the function audio_mixer_init instead of each driver handling it manually. + The software mixer render function now takes the number of frames and channels to render and the output format instead of the number of bytes. Supported output formats are 16-bit signed, 8-bit signed, and 8-bit unsigned. + Audio streams with a null mix_data function are now supported. These streams will be ignored by the software mixer. + sampled_mix_data now properly handles output requests smaller than the size of the audio buffer. + Added software renderer regression tests. + Removed PPAL compile time render_layer variants. These did not help performance and increased the render_layer size by 50%. + Added dependency builder makefile system in scripts/deps to help with regenerating MinGW, DJGPP, darwin-dist, and Linux w/ MemorySanitizer dependencies. + Overhauled the darwin-dist build system to allow for more modern XcodeLegacy-based compilation, including code signing and shared library support (via dylibbundler). The following architectures are now supported: i386, x86_64, x86_64h, ppc, ppc64, and arm64/arm64e (untested). + Updated libxmp to 4.6.0+6cb48a4a+sample rate patch. + Added more PowerPC64 GCC defines to platform_endian.h. Table of Contents December 31st, 2023 - MZX 2.93 This is the first MegaZeux release in about 3 years, so there are a lot of changes, including a large number of crash fixes. Brief summaries of each section: General: worlds are decrypted in memory now, MegaZeux 1.x worlds are now supported, you can have more custom sound effects, the 1/8th random movement chance of dragons has been readded, and static sprites now collide at their apparent position. Robotic: new label PLAYERDIED, new counter KEY_PRESSEDn, new counter DATE_WEEKDAY, new counter SPRn_OFFONEXIT, new viewport counters, and setting MOD_LOOPSTART after MOD_LOOPEND now works. Editor: the robot editor now has undo/redo, layer MZM block type can now be selected, reimplemented ANSi/TXT import/export, watchpoint improvements, a new variable debugger RAM menu, and vlayer saved positions. Video/audio: most GLSL performance and graphical issues have been addressed and libxmp has received a massive bugfix update. Portability: new PS Vita, DOS, Wii U, and Dreamcast ports. Numerous NDS and 3DS improvements. The extra memory system from the NDS port has been generalized to several ports and now supports memory compression. Virtual filesystem support. Utilities: vastly expanded image file support for ccv/png2smzx and a new video conversion utility called y4m2smzx. GENERAL + Added an "About MegaZeux" dialog, accessible from the main menu. This menu contains extended version information, and displays license information for MegaZeux and the 3rd party software it uses. + Protected worlds are now decrypted to RAM or a temporary file when 'auto_decrypt_worlds' is enabled and the original file is left unmodified. This setting is now enabled by default. + Added experimental support for loading MZX 1.x worlds. Support is not fully implemented yet, but all currently known 1.x worlds are playable. + Up to 256 custom sound effects are now supported instead of 50, and custom sound effects can be up to 255 chars in length. Currently, the sound effects editor is restricted to 100 SFX of length 68; the CHANGE SFX # to "" command may be used as a temporary workaround. + Custom sound effects can now be given custom names in the sound effects editor. Currently names are limited to 9 chars and are only useful when editing. + Fixed dragon 1/8th chance of random movement, which has been broken since 2.80. The original DOS behavior (random movement) or the 2.80 behavior (no random movement) can be selected via the new board setting "Dragons randomly move". + Reset Board on Entry and load charset/palette on entry now optionally will be performed even if re-entering a board from itself (enabled by default). + Fixed a Reset Board on Entry bug where a temporary board would not be generated when loading the title screen or if the starting board is the title board. + Fixed bug where the second cycle of a board when entering from a board edge or entrance would be shortened due to incorrect gameplay framerate timing introduced in 2.91g. + Fixed a bug where, if a world's title screen music is set but fails to load when the world is loaded, the music from another world could continue to play. + Fixed a bug where boards wouldn't be pulled from extra memory before saving, potentially causing save corruption on the NDS. + Fixed a standalone mode crash on exit that occurred when using Alt+F4 or the window close button. + Fixed a crash that could occur when loading a save file with the temporary board flag set but no temporary board data. + Fixed a bug in the random number generation function that could cause it to rarely return a number outside of the expected range. This unfortunately breaks compatibility for the RANDOM_SEED# counter. + Static sprites now collide as if they are at the position on the board where they are currently being drawn i.e. relative to the viewport instead of at their actual X/Y position. This behavior has also been added to the IF SPRITE AT # # command. + Optimized ccheck 3 sprite collision performance by generating visibility masks for characters directly instead of using an intermediate render and skipping pixel checks for blank chars. + Fixed a bug where worlds with SMZX mode selected would display the previous world's palette after switching back to MZX mode. + World and save files now save the MZX mode palette when in SMZX modes 2 or 3. Save files now save the MZX mode palette intensities when in SMZX modes 2 or 3. The palette and palette intensities for SMZX modes 2 and 3 are now saved as "palsmzx" and "palints" when one of these modes is active. + Save files now save palette intensities for all modes as a raw array of little endian DWORDs instead of bytes. The 2.92 and 2.93 intensities file formats are mutually incompatible. + Scrolls can now display standard message ~@ color codes. + Fixed warning messages caused by SDL controller CRCs. + Fixed hangs that could be caused by malformed counters files. + Fixed world/save/counters file corruption in rare edge cases where the aforementioned files could break the zip format's internal field bounds. + Fixed loading of world/save/counters files over 4 GB. + Fixed crashes when loading world or save files that contain invalid current board IDs (both loaders), saved position board IDs (both), start/death/game over board IDs (zip), board exit board IDs (zip), robot program positions (both), robot stack pointers (both), or robot stack sizes (legacy). + The output file mode (FWRITE_OPEN, FWRITE_MODIFY, or FWRITE_APPEND) is now stored in save files. This fixes a bug where the output file would be reopened in the wrong mode (ab) when reloading a saved game. + Added a second Robotic command listing to the help file that lists commands categorized by command type. (Terryn) + Links in the help file table of contents and Robotic Reference Manual are now grouped into categories. (Terryn) + Other misc. help file corrections and maintenance. (Terryn) ROBOTIC + New built-in label: PLAYERDIED (and the subroutine equivalent #PLAYERDIED). When the built-in player dies, this label is sent on the board the player died on. Because player death occurs at the end of the cycle, this is received during the following cycle. + New counter: KEY_PRESSEDn, to read internal keycode statuses. This is like KEYn, but KEY_PRESSEDn accepts internal keycodes instead of PC XT keycodes. KEY_PRESSEDn will return 1 if the key is currently pressed, or 0 if it is not pressed. + New counter: DATE_WEEKDAY, which returns the number of the current day of the week. Values are 0=Sunday, 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday. + New counters: VIEWPORT_X, VIEWPORT_Y, VIEWPORT_WIDTH, and VIEWPORT_HEIGHT to read the current board's viewport settings. (Sparkette) + New counter: SPRn_OFFONEXIT. When enabled for a sprite, that sprite will be automatically turned off when exiting the board (same as setting SPRn_OFF). This occurs even if the new board and the previous board are the same. (Sparkette) + Fixed crash bugs caused by using CHANGE SFX # to "" with an invalid sound effect number. + Fixed loop detection for Ogg Vorbis files when MOD_LOOPSTART is set to a value greater than MOD_LOOPEND. + Fixed a crash bug when attempting to save MZMs over 4MB to an existing string. + Fixed a buffer overflow crash that could occur when using LOAD CHAR SET with both a large input file and a large offset. + Reading from and writing to extended character sets should no longer display an "advanced graphical features" error message when a renderer without layer rendering support is active. This will, however, display a (new) error message specific to the Nintendo DS port. + Fixed CLIP INPUT and IF FIRST STRING "" "" bug where INPUTSIZE would be used as the bound on the input string without also checking for null chars, potentially allowing heap corruption. + Fixed a hack where the TELEPORT command would temporarily store the current board to extra memory, causing the game update loop to potentially cause memory corruption with stale board pointers on the NDS. + Fixed string wildcard matching bug that could cause patterns ending with ? to sometimes fail. + Dividing the value -2147483648 by -1, either by the commands DIVIDE and MODULO or through expression operators / and %, no longer crashes MegaZeux. + When the right operand to a bitshift operator in an expression is less than 0 or greater than 31, << and >> will return 0, and >>> will return 0 if the left operand is positive or -1 if the left operand is negative. The old behavior of the bitshift operators for these shift values was architecture dependent. + The date and time for the Robotic date and time counters is now sampled once per command maximum. When multiple date/time counters are read in the same command, they are guaranteed to represent the same time. + The Robotic message box commands now properly display char 10. + The Robotic command ? now correctly accounts for color codes in its length bounding. + Fixed crashes in the & Robotic command caused by bad color string length calculations. + Fixed PrintScreen/SysRq and Menu/"Right Click" keycodes. + Unsupported keys no longer return a KEY_PRESSED value of 1 for SDL 2 builds. + Fixed crashes when executing the GIVE, TAKE, TAKE ELSE, and TRADE commands with an invalid item type. + Fixed crashes when disassembling a Robotic command with an invalid condition. EDITOR + Added robot editor undo (Ctrl+Z) and redo (Ctrl+Y). Like with board/vlayer/charset editing, the size of the undo stack is defined by the config setting "undo_history_size". Note that extended macro expansion can sometimes clobber undo or redo frames (this is not easily fixable, and prevents worse bugs). + When loading a layer MZM to the board in the editor, instead of always loading the MZM as CustomBlocks the conversion type can now be selected from CustomBlock, CustomFloor, and Text. Canceling the object type dialog no longer cancels the current block or MZM placement. + Reimplemented ANSi import/export support for the editor. ANSi and TXT files can be imported in the editor with Alt+I and can be exported by selecting a block (Alt+B). + Creating a new world using N from the title screen or Alt+R in the editor now clears the extended character sets. + Improved the performance of Robotic debugger watchpoints, especially for non-built-in counters and non-spliced strings. + Robotic debugger watchpoints can now watch for particular counter or string values. Leaving the value field blank will still check for any value. + Added a list of variables related to RAM usage to the counter debug window. This list can be found in the "World" list. + Added vlayer saved positions to the editor. Like regular saved positions, these can be configured with the config file option "vlayer_position#", and they work identically to board saved positions. + Fixed bugs caused by missing validation in the Import SFX feature in the editor. + Fixed a bug where multichar char tile movement could still sometimes jump to the -/+/= chars in the main charset. + Fixed another bug that would cause string searching in the robot editor to sometimes skip matches. + Replace all (Ctrl+H) in the robot editor should no longer skip adjacent instances of the search string. + Opening the block action menu in the robot editor (either with Alt+B or Alt+Enter) now updates the current line, fixing bugs where it could copy old line contents to the buffer. + Fixed a robot editor crash that could occur when combining two lines with backspace or delete if one of the lines contained the start or end block mark. + Fixed a bug in the robot editor where Ctrl+Home and Ctrl+End would only set the current line (and not the current column). + Fixed a robot editor extended macro crash that would occur: when pasting a line containing a macro from the clipboard; when importing a Robotic source file that invokes macros; when invoking nested extended macros. + Invoking an extended macro with enter/return no longer inserts an extra blank line. + Pressing enter at the start of a line with an extended macro now invokes the macro instead of just inserting a line. + Fixed editor extra memory crashes when importing and deleting boards. + editor_show_thing_toggles is now enabled by default. - board_editor_hide_help and robot_editor_hide_help are no longer enabled by default for accessibility. VIDEO/AUDIO + Added the "glslscale" renderer. This is the same as the GLSL renderer, but uses software rendering with scaling shaders instead of hardware rendering. This is faster on low end PCs and embedded devices and is the new default renderer selected by auto_glsl. (Hardware rendered GLSL is still available for users with graphics cards by selecting the "glsl" renderer.) + The software fallback renderer functions now support SMZX mode 3 indices, fixing graphical bugs in situations where the fallback would be used and display the wrong colors in games using custom indices. + Added an "auto" mode for the force_bpp config option. Modern SDL automatically selects a native window pixel format and a fixed value can make the software renderer slower. Detecting the BPP from the created window is more in line with reality. + Fixed color inaccuracies in the softscale renderer on Mac OS caused by using full-swing YUV values instead of the expected studio-swing values for GL_YCBCR_422_APPLE textures. + Simplified GLSL renderer texture data packing to improve support for OpenGL ES and older OpenGL implementations. + The GLSL tilemap fragment shaders will now use highp floats if provided by the OpenGL ES driver. If highp is unavailable and mediump has inadequate precision, MZX will print a warning. + Fixed software renderer display issues caused by relying on SDL_PixelFormat::BitsPerPixel instead of BytesPerPixel on platforms with native 15 BPP display modes. + Added disable_screensaver configuration option. MegaZeux now leaves the screensaver enabled by default (fixes regression caused by SDL 2.0.2+). + Added an "sdl_render_driver" config setting. This setting can be used to specify the underlying SDL renderer driver used by the softscale renderer. This setting does not affect any other renderers. + libxmp playback improvements for GDM, AMF, and OctaMED modules as well as general stability improvements. + Updated libxmp to 4.6.0+ceb2d025. + Fixed crashes in the RAD player that could be caused by references to uninitialized instruments. + Applied various Opal fixes from OpenMPT. - Removed GL4ES from the GLSL blacklist. PORTABILITY + Added an experimental PlayStation Vita port. (Spectere) + Added an experimental Wii U port. (asie) + Added an experimental Dreamcast port. (asie, Lachesis) + Added an experimental MS-DOS 32-bit port based on DJGPP. (Mr_Alert, asie, Lachesis) + Added support for BlocksDS to the NDS port. (asie) + Added support for 800x240 mode to the 3DS port. This mode can be toggled with the 3DS keyboard. (asie) + Added support for using 352kB of previously unused NDS VRAM as board storage. This area can be used for board storage even when a slot 2 expansion cartridge is not present. (asie) + Reduced RAM usage by 50k by removing variants of *printf and *scanf with floating point support on the NDS. (asie) + The MOD_ORDER counter is now readable on the NDS. (asie) + save_slots is now enabled by default for consoles. (Spectere) + Inactive boards and some robots are now compressed on the NDS, which (combined with asie's VRAM patch) should vastly increase the number of games that can be played on the original DS and DS Lite without a slot 2 expansion cartridge. This is also enabled for the PSP and DOS ports. + The NDS, PSP, and DOS ports now write zip archives with the fastest zlib compression level. This makes saved files that use compression (worlds, saves, etc.) slightly larger. + Added virtual filesystem support to MegaZeux. Currently, this is only used for caching files, and is only enabled by default on platforms with slow or buggy file IO (3DS, Vita). This feature may be optionally configured with the config options vfs_enable, vfs_enable_auto_cache, vfs_max_cache_size, and vfs_max_cache_file_size. + Fixed a bug where the 3DS and Switch ports would display .. in the file manager when selecting a board module, board charset, or board palette. + Fixed a bug where, when a faulty dirent implementation returns .. when listing the contents of a root directory, .. would be displayed despite being meaningless. + Fixed a bug where some checks in the file manager could fail when getcwd returns different slashes than expected. + Fixed a bug where stdio redirect could generate corrupted log files on the Nintendo DS due to poor freopen support. + Enabled the GLSL renderer for the Android port. The Android port now uses the GLSL scaled software renderer by default. - Removed 3DS CIA support. (asie) UTILITIES + ccv and png2smzx now both support the following image formats: PNG (libpng builds only), GIF, BMP (uncompressed, RLE8, RLE4), NetPBM (PBM, PGM, PPM, PNM, PAM), farbfeld. png2smzx will now build when libpng support is disabled, though it won't support loading PNGs with this configuration. + ccv and png2smzx now both support streaming image data from stdin using the input filename "-". + Added y4m2smzx, a video converter frontend for the same image converter that png2smzx uses. This is a rewrite of Mr_Alert's original frontend from 2010. This uses a custom y4m loader rather than MJPEG Tools for now, so it may be buggy. Usage: ffmpeg -i input -f yuv4mpegpipe pipe:1 | y4m2smzx - out.mzv + The downver utility now supports save files. + Fixed a bug where checkres would not check the current dir for files when provided with a MZX filename with no path component. + checkres now attempts to scan every board in <=2.84 worlds where a corrupt board/robot is found. Due to old world format limitations, robots after a corrupt robot can not be scanned. + checkres now supports scanning protected worlds. + Added experimental checkres support for MZX 1.x worlds. DEVELOPERS + Added --enable-extram config.sh flag to enable extra memory hacks on arbitrary platforms. This is enabled by default in CONFIG.NDS, CONFIG.PSP, and CONFIG.DJGPP. When enabled, non- active boards are compressed in RAM. Certain platforms can use platform-specific storage, like the NDS. + Board input strings, charset paths, and palette paths are now heap allocated on-demand to save RAM for low-memory systems. + Status counters are now saved as a nested properties file. + Refactored the 3DS renderer to use templates. (asie) + intake2() now supports custom handling of intake events, i.e. it can now be used without providing a fixed size buffer. + The draw and click handlers have been removed from intake2(). This should provide more flexibility to the parent context for displaying the string that is being edited. + Added "mzxout" and "mzxerr" streams for printing console messages. In most places these should be used instead of "stdout" and "stderr" to allow debug and warning messages print to the correct log files when stdio redirect is enabled. + Fixed broken MIPS big endian detection inherited from SDL 1.2. + Added architecture width detection for RISC-V RV32 and MIPS64. + Replaced the macro-based mixers in sampled_stream.c with more maintainable template-based mixers. + Fixed the DSO -Wstrict-aliasing warnings in Socket.cpp and the OpenGL renderers for GCC versions using -Wstrict-aliasing=2. + Added --host config.sh option to manually specify a cross compiler prefix. This is ignored or overriden by most ports and is mainly just for Linux. + Relicensed ccv from GPL 3 to GPL 2+ to match the rest of MZX. (Lancer-X) + If available, GetSystemTimePreciseAsFileTime and clock_gettime are now used to calculate the system clock time. + If available, SDL_GetTicks64 is now used by get_ticks(). + Minor performance improvements for run_robot, is_string, and find_function_counter. + _FILE_OFFSET_BITS=64 is now used for 64-bit fseeko, ftello, readdir, and stat/fstat support for 32-bit Linux builds. + Updated Android SDL to 2.28.2. (asie) + Updated Android NDK to r23c. (asie) + Fixed Android build system handling of missing libraries. + Improved fileform.html, joystick.html, keycodes.html, and platform_matrix.html readability on small/mobile displays. - String values are now allocated separately from the string struct and name. This may make strings very slightly slower, but means string pointers are now stable through an entire gameplay session. New in Versions 2.92 to 2.92f New in Versions 2.90 to 2.91j New in Versions 2.84 to 2.84c New in Versions 2.82 to 2.83 New in Versions 2.81 to 2.81h New in Versions 2.80 to 2.80h New in Versions 2.60 to 2.70 New in Versions 2.01 to 2.60 New in Version 2.00 New in Versions Through 1.03 Table of Contents

New in Versions 2.92 to 2.92f November 22nd, 2020 - MZX 2.92f Here's another bugfix release. Highlights of this release are crash fixes (including the 3DS OGG crash bugs), numerous SAM/WAV playback bugfixes, some edge case compatibility fixes, world decryption improvements, networking improvements (including experimental Wii, 3DS, and Switch support), bugfixes for the file manager in Nintendo Switch builds, and too many libxmp fixes/improvements to list. Since libxmp development is active again, the number of MegaZeux hack patches is down to just two! The editor is now enabled for 3DS builds, and some rudimentary joystick support has been added to the editor so it will (maybe) be (almost) usable. Of special note are asie's improvements to the NDS port. New features include protected character set and palette support, improved touchscreen focus, reduced memory consumption, and *audio support*. Currently NDS audio requires preconversion of music files to .MAS and sample files to .SAM, but that it works at all is amazing by itself. Pre-converted .MAS files are included with the packed-in copy of Caverns of Zeux. USERS + Added audio support to the NDS port. PC speaker effects and .SAM files will work out of the box, but .MOD/.S3M/.XM/.IT files require preconversion to .MAS using mmutil. All other audio formats are unsupported. (asie) Example: mmutil -d -m CV_TECH.MOD + Added protected character set and palette support to the NDS port and reduced overall RAM usage for the NDS port. (asie) + Fixed a bug in the NDS port where MZX would immediately focus the player after a touchscreen press event, preventing the touchscreen from being used to scroll the upper screen. (asie) + Fixed a crash that could occur sometimes when duplicating robots on a board with Reset Board on Entry enabled. + Added SET RANDOM, INC RANDOM, DEC RANDOM, and TAKE "label" commands to the list of commands that should allow "infinite" loops in pre-2.80 versions. + Fixed SET RANDOM # TO # for large ranges on certain platforms (example: Linux) confused by the 32-bit math used to calculate the random range. + Fixed crashes that could occur when attempting to run MegaZeux without help.fil. + Fixed graphics corruption when using the glsl and opengl2 renderers on big endian platforms. + Fixed a bug that would cause string searches to sometimes skip certain matches. + Improved performance of saving ZIP worlds/save files/etc. for some platforms. + Platforms without a protected palette and the meter enabled should now fade out properly before loading a world. + Rewrote decrypt() to work better on low-memory platforms. + Improved GLSL layer renderer performance slightly by sending the palette and indices to the GPU fewer times per frame. + Fixed a bug where the GLSL renderer could attempt to load the framebuffer symbols from a driver that doesn't support them when resizing the window. + Fixed a bug where checkres wouldn't correctly detect "LOAD_ROBOT#" when used to load to a specific robot. + Fixed a memory leak when printing network error messages in Windows builds. + Fixed a potential crash bug in the netcode where socket IDs could be reused after close() when attempting to connect. + Fixed a crash bug affecting the compatibility implementation of getaddrinfo() that would occur if NULL was returned by gethostbyname() during DNS resolution. + Fixed a potential crash in the compatibility implementation of getaddrinfo() caused by gethostbyname() being thread-unsafe. + Fixed a bug where the updater would hang for up to 10 seconds due to connections timing out during the confirmation UI. + Fixed a bug where the local manifest.txt would be overwritten by the remote manifest, potentially causing bugs. The local manifest will now be replaced only after a successful update. + Fixed bugs where the HTTP layer would filter header names, content/transfer coding values, and content type values too strictly. + Fixed a bug where INPUT STRING would display newlines from an interpolated string. + MZX now validates the world version of encrypted worlds before offering to decrypt them. This should reduce the chance of accidentally "decrypting" a corrupted file and prevents MZX from attempting to decrypt MZX 1.x files (which store the password differently). + Added config settings "editor_show_thing_blink_speed" and "editor_show_thing_toggles". The former controls the blinking speed of the show thing (Shift+F2 et al.) editor keys and the latter allows these keys to be treated as a toggle instead of blocking input. + Added SOCKS5 IPv6 and username/password support. + Added "network_address_family" config setting to allow users to force either IPv4 or IPv6 connections/name resolution. By default, MZX will now request either or both depending on the system IP address configuration (previously, it was hardcoded to only allow IPv4 despite IPv6 support being implemented). + The config setting "updater_enabled" has been added to turn off the updater system entirely without disabling networking. + The updater now allows update checks to be performed even when a full update wouldn't be possible, and should be more helpful about printing warnings to the console when this situation occurs. + Enabled rewinddir hack and .. file manager hacks for Nintendo Switch builds to fix the file manager and directory seeking. + Fixed a bug where importing a board over the title board would not update the world title. + Fixed a crash that could be caused by selecting a block on the overlay/vlayer, changing boards, then pressing enter. + Fixed a bug where the currently playing PC speaker note would play for the rest of its duration after turning off PC speaker sound effects, after "end play", after exiting gameplay, etc. + Fixed a regression where turning off music in the settings menu and then turning music back on would not start playing the music file for the current board. + Fixed multiple libvorbis and tremor crashes related to the 3DS platform_mutex_lock implementation not blocking. + Fixed audio frequency bugs in .SAM file playback. + Certain .WAV subtypes handled by SDL_LoadWav should now load properly on big endian machines. + Signed 16-bit samples should now work correctly with MOD SAM on big endian machines. + Fixed the white border present when using the GLSL renderer in HTML5 builds. + Added joystick input handlers for most editor interfaces. Only very basic things are supported like navigating boards and robots. This is intended for things like handheld consoles without a keyboard. + Fixed a bug where turning off the listening mod would load the mod that was playing when the listening mod was loaded instead of the current board's mod. + Fixed a bug where setting a board mod to a partiular mod, then setting the board mod to *, then changing to a different board with the same mod would not restart the board mod. + Fixed a bug where libxmp would not ignore zero volume samples in STM files. + Restored libxmp support for Soundtracker 2.6/IceTracker .MODs. Currently only libxmp supports this .MOD variant. + Fixed a bug where MZX would fail to load Noisetracker, Octalyser, and Mod's Grave .MOD files if they were named using the extensions .NST, .OCT, and .WOW (respectively). These can now be selected with Alt+N/Ctrl+N in the editor. + Enabled loading .XM and .AMF files with MikMod. Whatever the issue was with these in 2007 seems to have since been fixed. + Fixed loading Soundtracker 15-instrument .MODs with MikMod. + Fixed MOD_POSITION and MOD_LENGTH counters for MikMod. + MikMod now uses interpolation if module_resample_mode is set. - Disabled playing modules using the SAM command with MikMod to avoid crashes due to MikMod using a global player state. DEVELOPERS + The test worlds now run correctly when AddressSanitizer is enabled. + The SUPPRESS_BUILD Makefile flag has been split into several flags, allowing more granularity for disabling default rules. The Android and Darwin "dist" meta targets use these flags to to disable the default "all" target, so "make" can now be used in place of "make dist" for these platforms. + Using "make build" will now remove the build/${SUBPLATFORM} directory if it exists before preparing a build. Before, using "make build" when the platform build directory already exists would not copy any updated binaries/assets/etc., potentially causing confusion. + The check_alloc series of functions should now be thread safe. The main thread will display a fatal error as usual when allocation fails; others threads will print a warning and return NULL. + Added implementations of new/delete/__cxa_pure_virtual that can be linked to avoid linking libstdc++/libc++ on platforms and configurations that otherwise don't need those libraries. + Refactored the netcode to use C++ instead of/in addition to C, allowing some cleanup that otherwise wouldn't have worked. Host::bind, Host::listen, Host::accept, and Host::poll are no longer disabled. Other network deadcode functions have been updated but are still disabled. + Fixed FD_ISSET in the Windows netcode. + Added a EAI_AGAIN define for the getaddrinfo() fallback. + Fixed leak of updates.txt file pointers in the updater that could occur when updates.txt fails to download. The updater now downloads updates.txt to a buffer instead of to disk. + Added graphics.renderer.hardware_cursor for platforms with hardware cursors that may need to be updated during any frame regardless of the current cursor state/blinking (i.e. DJGPP). + Fixed "make build" error after using "make debuglink" with png support disabled. + Added const and restrict to the software render_graph and render_layer implementations for a small performance boost. + Added --disable-getaddrinfo and --disable-ipv6 config.sh flags to allow disabling these for old platforms and consoles SDKs. Amiga, Wii, and PSP network builds force-disable these. Switch and 3DS builds currently force-disable IPv6. + Added experimental network support for Wii, Switch, and 3DS. + Updated libxmp to git-ab70ec9f, refactored libxmp patches. + Removed unused libxmp Paula simulator code to save RAM. (asie) + SDL is no longer required to build MZX with MikMod enabled. + Fixed MikMod static linking on Windows. + Added --disable-stack-protector config.sh option. Platforms that previously disabled the stack protector in the Makefile now force disable this config option. These force disable hacks will probably be removed in the near future. Table of Contents July 20th, 2020 - MZX 2.92e This bugfix release includes miscellaneous audio fixes and fixes for bugs in the configuration system. Other things of note are a fix for a graphical bug in the robot editor, a freeze bugfix in the updater when updating from older MZX releases, and the title of the Alt+A ("Select Char Set") dialog has been reverted back to roughly what it was in DOS versions. A second default SMZX character set with a different font has been added as well. USERS + Fixed Windows file handle leaks in audio_xmp.c caused by MinGW's non-compliant fdopen. + Fixed a bug where the title screen's intro message wouldn't cycle the scroll color while no world was loaded. + Added the missing "ccode_chars" config setting. + Fixed a bug where the "ccode_extras" config setting would change the strings color code instead. + Fixed a bug where "macro_#" where # is 0 or between 6-9 would corrupt various parts of the editor configuration. Notably, "macro_6" would corrupt the extended macros and cause crashes. + Fixed division-by-zero crashes and GL errors when using invalid fullscreen_resolution or window_resolution values. + Fixed a bug where files included by the config file include directive would ignore editor settings. Also added a recursion limit for includes and fixed a bug where the "include=file" format would not work on some platforms. + Fixed a libxmp bug where pattern jump/break could take effect after using JUMP MOD ORDER or setting MOD_ORDER/MOD_POSITION. This fixes a bug at the end of the Inmaportal scene in Cans 3. + Zip files with the language encoding flag set no longer print unsupported flag errors. + Fixed a bug where recursive directory deletion in the updater could get stuck in an infinite loop due to not checking the return value of rmdir and path_get_directory not behaving the same as get_path used to. + Fixed a bug where the cursor could display over the color selector and char editor when opened from the robot editor. + Fixed a bug where the default character set selection menu was inconsistently labeled "Object type". + Added a second SMZX default character set with a more legible font. The original is still available for those who prefer it. DEVELOPERS + Fixed memcasecmp test alignment checks for the Motorola 68000. + Improved validation of config setting inputs and added a unit test for config file and command line parsing. + Added buffered zip compression/decompression support. + Added unit tests for the zip functions and (de)compressors. Table of Contents May 8th, 2020 - MZX 2.92d This release includes minor new features, an overhaul to the way MZX handles text input from SDL 2.0 which should fix various text bugs (particularly with non-US keyboards), fixes required to get the Android port working, and a new file format document. Other things of note are two libxmp patches fixing issues with S3Ms saved by the original Modplug Tracker and with GDMs relying on fine effect continue, checkres updates, and misc. fixes for the Windows and HTML5 ports. Fixed compatibility issues in this release are a string compare bug that prevented Mines of Madness from working and MODs with extended filenames working when referenced by their truncated DOS SFN in the MZX file. The latter fix only works when there is a single unambiguous match, which turned out to be essentially every affected game. It is worth noting that the Android port is EXPERIMENTAL and is likely to have compatibility issues on many devices. A USB OTG or Bluetooth keyboard or game controller is required at minimum. Many devices have key press issues that are likely caused by drivers or SDL. SDL text input events are disabled as they cause even more keyboard bugs, and as a result non-US keyboard layouts probably won't work with this port right now. Other problems with this port that have been reported include graphical bugs and crashes when focusing/unfocusing MegaZeux. USERS + Added robot editor shortcuts CTRL+Home and CTRL+End to jump to the start and the end of the current program. + Char selector tile movement is now disabled outside of the char editor and for 1x1 char selections. This allows typing -/_/=/+ in other char selectors to jump to those characters. + Added docs/fileform.html, a document describing all currently supported MZX file formats in excessive detail. + When startup_file is provided with both a directory and a filename and no startup_path has been set, the directory will now be used as startup_path. If startup_path is set, the directory portion of startup_file will still be ignored. + The flash thing editor functions (Show Robots, etc.) now use the protected charset and will display with the protected palette in SMZX mode and in regular mode situations where the normal flashing would be difficult/impossible to see. + Fixed a bug where input text with no corresponding internal key would be ignored by the robot editor. + Fixed a bug where some AltGr key combinations would not work in the robot editor (note: SDL doesn't distinguish Alt from AltGr, so any Alt key combos with a special meaning in the robot editor will still be intercepted by MZX). + Windows Alt+numpad sequences corresponding to ASCII characters 32-126 should now be recognized. + Fixed an out-of-memory error in the save slot UI and improved its mouse functionality. + Added optional CRC-32 output to checkres. Currently this flag only works for files in ZIP archives and no CRC-32 validation is performed. + Fixed checkres parsing for LOAD CHAR SET "+&+var&file.chr". + Fixed checkres crash that could occur on some platforms when attempting to checkres a directory. + Fixed wrong robot board positions reported by checkres for some files when run with -vv. + Repurposed the old checkres -A flag to display everything but unused files, which should be much more useful than the older behavior (particularly with loose files in directory dumps). + Fixed memory leaks in legacy_assemble_line. + Fixed potential null termination issues in both world loaders that could be triggered with invalid board name, robot name, scroll, sensor, sfx, and status counter strings. Also improved loaded robot stack bounds checks. + Decreased the sizes of the counter and string structs and fixed a crash that would occur when attempting to expand the counters or strings lists beyond 1 billion. Checks have been added to prevent them from expanding beyond 2^31 (please don't actually use this many counters/strings). + Fixed string comparison for pre-2.81 games that relied on null-terminated string compares. This fixes Mines of Madness. + Fixed hlp2html bug where certain chars wouldn't be escaped and decreased the size of the output HTML files somewhat. + Fixed libxmp playback for S3Ms containing ADPCM4 samples. This fixes mm2flash.s3m in ZeuxDrop. + Fixed libxmp playback for GDMs where 100/200/A00 should continue the fine portamento and fine volume slide commands. This fixes LB2_7.GDM from Kikan. + fsafetranslate now attempts to detect matches for truncated DOS SFNs on non-Windows platforms. If an unambiguous match for a truncated SFN is found, the SFN will be expanded to the match. This fixes numerous games relying on truncated SFNs with unambiguous matches. + Reimplemented COPY # # # # for layer-to-layer copies. + Fixed a collision bug affecting unbound sprites with ccheck 3 set in SMZX mode where wrong colors could be treated as the transparent color for the purposes of collision. + Fixed softscale bug on some platforms where the screen border wouldn't be cleared. + The GLSL renderer will now attempt to use a framebuffer when available. This fixes GL_INVALID_OPERATION bugs with certain OpenGL ES 2.0 implementations. + Directory navigation in the file manager now checks directory access permissions before allowing navigation and displays an error when navigation fails. + Fixed windowing code bug in extended macro editor that would occur after selecting "Default" multiple times. + Fixed a bug where long extended macros could sometimes break. + Fixed extended macros not working when the params line is indented by more than one space or tab. + Windows builds now attempt to load and call SetProcessDPIAware on startup. This should fix undesirable DPI-related scaling and fullscreen bugs. + Fixed Emscripten crashes on startup when built with Emscripten 1.39.5 and up caused by usage of deprecated canvas behavior. + Fixed a COPY BLOCK $string bug where the buffer could be allocated at the empty destination string's value on some platforms and a faulty bounds check would result in the string being expanded but otherwise blank. DEVELOPERS + Added a set of C++-based unit tests for portions of MZX that can't be reached/tested easily by MZX worlds. These tests will be built and run when "make test" is used prior to running the test worlds. + Decoupled SDL 2 text input handling from regular key handling and added a text input buffer. Text keys can now be requested multiple times and either as ASCII or unicode; the next key in the buffer is returned on subsequent calls. intake and editor text entry can now accept multiple text chars per frame. + Added SDL 1.2 implementation for __peek_exit_input. + Contributed sound engines (libxmp, libmodplug) should now properly rebuild after config.sh is run. + Fixed a bug where khash tables couldn't expand beyond 2^31, added hash caching, made the MZX copy of khash use MZX style, and better documented the changes made to it. + Added fast sprintf replacements for Robotic counter to string conversion (counter interpolation, string/counter compares). + Fixed alignment issues in memcasecmp. + Fixed alignment issues in get_cursor_color. + Added a config.sh flag for UndefinedBehaviorSanitizer. + Categorized config.sh flags list. + Added a trace logging level that is disabled by default and changed most dns.c, fsafeopen.c, and checkres.c debug logging to use it. Use the --enable-trace config.sh flag to enable trace logging for debug builds. + Added a config.sh flag to build using GCC's -fanalyzer flag (disabled by default). + Refactored path functions out of util.c. + Replaced the Android build scripts with an improved Makefile system. The Android Makefile now uses the NDK toolchains directly. Also added support for APK signing and fixed several Android port bugs. + MZX will now exit on startup if no world could be loaded and the SDL dummy video driver is active. - Removed -fpermissive from CXXFLAGS (pointless). - Removed -fbounds-check from debug builds (pointless; MegaZeux doesn't use GCC to build any Fortran or Java code). Table of Contents March 8th, 2020 - MZX 2.92c Here's another bugfix release, this time mostly oriented towards fixing bugs in the Emscripten/HTML5 port and checkres. Other fixes of note are the module_resample_mode (formerly 'modplug') config setting has been fixed, numerous optimizations have been made to the software layer renderer, and yet another ternary operator bug has been fixed. Finally, Spectere has added an experimental save slots UI that can be enabled with the config setting "save_slots". This feature is intended primarily for consoles and will likely be enabled by default for consoles in the future. USERS + Added an optional save slots interface to complement the file manager. This can be enabled by setting the "save_slots" config setting to 1, and is disabled by default. (Spectere) + Board list typing now allows non-alphanumeric keys like spaces and periods. Typing a space first will match zero or more prefixed spaces while seeking. + Added the config setting "auto_decrypt_worlds". When set to 1, this allows MegaZeux to automatically attempt to decrypt protected worlds. For most platforms this option is disabled by default. + MegaZeux now silently ignores robots in older worlds with corrupt programs that are marked unused. This fixes an error message that would display when loading Wes. + Renamed "modplug_resample_mode" to "module_resample_mode". Fixed a bug where the xmp interpolation mode wouldn't be set correctly from this setting and instead would always reset to "linear". The default for this setting in config.txt has been corrected (the default has been "cubic" since 2.82b). + Fixed a ternary operator bug where the expression could break with certain counter names in the second and third terms. + Added a comment to the Emscripten frontend for how to disable the "Click to Play" splash. + Fixed Emscripten frontend issues when MegaZeux is embedded in an iframe making it difficult to regain focus after losing it. + Fixed an Emscripten frontend bug where certain filenames could cause false positives when checking for a directory name, preventing fsafetranslate from detecting the correct path. This fixes various things in Eternal Eclipse Taoyarin. + The Emscripten frontend should now fall back to memory storage if IndexedDB or local storage fails to initialize. This fixes an error when using MZX in a private browser window. + Fixed a robot editor regression where certain numpad symbols could not be typed. + Added "GL4ES wrapper" to the auto_glsl blacklist. + Added "Software Rasterizer" to the auto_glsl blacklist. + checkres no longer requires zip archive filenames to end with the .ZIP extension. + Added optional CSV output to checkres. + Added error to checkres for 1.xx worlds. + Fix checkres errors when encountering VER1TO2 empty robots. + ZIP support now ignores __MACOSX/, .DS_Store, and Thumbs.db. + Added decompression support for various legacy ZIP compression methods and deflate64. + The Emscripten frontend now falls back to a wrapper for MZX's internal ZIP support when UZIP fails to extract an archive. + Fixed IndexedDB support for legacy Edge versions. (asie) + Fixed an 8bpp software layer renderer bug where transparent UI colors would not be transparent in SMZX mode. + General software layer renderer (software, softscale, opengl1) performance improvements. + Fixed out-of-bounds CHAR_BYTE access with BYTE values over 14, added compatibility check for games relying on this. (asie) + Fixed faulty bounding on CHAR_X/CHAR_Y/PIXEL. - Removed the options "overlay1" and "overlay2" from the list of selectable renderer options except when SDL 1.2 is enabled. DEVELOPERS + Refactored render_layer_code to use C++ templates. + render_layer now disables the (unused) 64-aligned renderers for 32-bit platforms and Emscripten builds. + Fixed buggy render_layer clipping that required clipping renderers to unconditionally use a suboptimal alignment. + Switched from xmp_load_module to xmp_load_module_from_file. + Fixed various clang unused argument compiler warnings. + Updated MSVC dirent.h implementation to latest version. + Moved dir_* functions from util.c to dir.c. + Added Windows UTF-8 compatibility layer to vfs.c and dir.c. UTF-8 support for Windows is still limited. + Moved Makefile compiler version checks to arch/compat.inc. + Added cycles_and_commands.txt to build and install targets. Table of Contents September 23rd, 2019 - MZX 2.92b This release fixes several bugs, notably 3DS and Wii rendering issues and a bug where the wrong palette would be saved while COLOR FADE OUT was active. Also in this release are performance and usability improvements for the NDS and 3DS ports and a new frontend for HTML5/Emscripten builds (special thanks to asie). USERS + Fixed a bug where mouse warping both mouse coordinates would not actually warp both coordinates. + Fixed a port regression where save files would be saved with the wrong color intensities while COLOR FADE OUT was active (or during the first cycle of a board for <2.90 worlds). This fixes fading bugs in Ruin Diver 3. + Added compatibility for a bug where the robot message box would disable COLOR FADE OUT in versions 2.83 through 2.90X. This fixes several BKZX games. + Fixed checkres bugs separately preventing detection of global robots in both world formats. + Fixed 3DS renderer bug where the UI wouldn't properly display char foregrounds with extended graphics enabled. + Fixed 3DS renderer bug where sprites containing chars with transparent foregrounds wouldn't draw any char backgrounds. + Fixed 3DS renderer crashes that would occur when large numbers of sprites were active. + Improved file manager directory read times for 3DS/NDS/Wii. + File IO for world saving/loading is now buffered, which should improve save/load times on the 3DS and Switch. + Enabled writing zip data descriptors for the Switch. + Added classic/stretch video ratio support for the 3DS and NDS lower screens. (asie) + "classic" is now the default ratio for the 3DS, NDS, and Wii. + Fixed GX renderer bug where chars with both colors transparent could cause various graphical bugs in normal MZX mode. + Fixed bug where board exits could be cleared when deleting a board or after loading a world containing null boards. + Fixed bugs when playing STARDSTM.GDM with the libxmp engine. + Fixed a crash that could occur when importing a world in the editor containing a null board. + Fixed a bug where null boards wouldn't be properly refactored on the NDS while using a memory cart, causing entrances to point to the wrong boards and possibly other problems. + Fixed a bug that could corrupt the ends of robot programs when using an NDS memory cart. + Improved world loading times when using an NDS memory cart. + Improved NDS memory cart transfer speed. (asie) + Disabled NDS logging hacks when stdio redirect is enabled. + Exiting MZX on the NDS should now power off the NDS. + Added Emscripten frontend. (asie) + Fixed bug where errors in the title screen Load World window could clear the rest of the screen. + Fixed crash that could occur when attempting to load an invalid zip world. + Non-recursive directory deletion in the file manager now tries to delete the directory itself instead of its contents. Added error messages for failed file and directory deletes. DEVELOPERS + Added initial support for the dirent d_type field to help avoid stat calls when reading directories. + Replaced most fseek calls in the legacy world loader. + Refactored move_current_board to be more readable. + Corrected some of the editor's bad extram handling and added warnings to debug builds to help debug it (no platforms at the present support both the editor and extram). + Replaced error wait_event() with update_event_status_delay(). + Added preliminary VFS code to replace function pointer casting in zip.c. + Fixed Wayland/X11 detection for setups that don't allow X or Xorg to be run normally. + Unix builds should now attempt to load the icon from the installed path instead of from a hardcoded path. Builds with no sharedir set will use "contrib/icons/quantump.png" instead. Table of Contents July 22nd, 2019 - MZX 2.92 Here's another inexcusably big minor version release. First off, there are two new ports (Switch and Emscripten) and the Android port has been updated to be actually usable. Second, joystick support has been significantly overhauled (and depending on the controller/joystick you plug in, it may work with no config settings required!). Game joystick settings should no longer override the new UI joystick behavior. Also, controllers can now be used directly via Robotic. Read docs/joystick.html for more information on the new features. Other changes of note include RAD music support (v1 and v2), palette editor improvements, and some new counters. There's a new SDL 2 exclusive renderer to replace overlay1/overlay2 called "softscale" that performs much better than either did and with fewer crashes. Also of note are the massive number of fixed bugs and compatibility improvements, fixing regressions and error messages that affected around 20 different games (or more). A major bug was fixed that caused the updater to not initialize in Windows has been fixed too, so basically, update already. FEATURES + Added numerous improvements to MZX's joystick handling: + Joystick inputs can now be bound to generic actions. These actions correspond to XInput buttons and can interact with MegaZeux's various windows in a context-specific manner. They can be used directly in Robotic with the new counter "joy#.[action]" or can be bound to keycodes in the config file to allow them to be used with older games. The NDS, 3DS, Wii, PSP, and GP2X pad.config files have been updated to use actions. See the help file or config file for more info on the config options and available actions. + Added automatic joystick mapping for Windows/Mac/Linux/etc. Joysticks recognized as SDL game controllers are assigned joystick actions when detected. This behavior can be altered or disabled via config options. + New counter: "joy#active" will return 1 if a given joystick is availabled, 0 if not, and -1 if the index is invalid. + New counter: "joy_simulate_keys". When set to 1 (default), joysticks can produce simulated key presses, as in older MZX versions. When set to 0, this behavior is disabled. + Joystick settings in game.cnf files are now loaded as game- specific joystick bindings. These bindings will no longer override global/UI bindings defined by the config file or pad.config. The default bindings are restored when any world is loaded from the title screen; they are not restored when a save is loaded, between world swaps, or in the editor. + Joystick config options can be assigned to key names in the format of "key_X" (without quotes), where X is the key name. + Joystick config options for a particular controller now work with ranges of controllers e.g. "joy[1,16].lshoulder = 13". + Added the config setting "joy_axis_threshold". This setting allows the threshold for joystick axis mapped presses to be configured. + The NDS directional pad is now considered a joystick hat. + The 3DS directional pad is now considered a joystick hat. The circle pad is now mappable as axes 1 and 2. + The Wii Classic Controller triggers are now recognized as axes 7 and 8. The Guitar Hero axes have been shifted to 9, 10, and 11, and a likely bug with the whammy bar axis has been fixed. The Gamecube controller triggers are recognized as axes 5 and 6, and all 8 controllers now have default bindings in pad.config. + Added/updated Android port. (asie) + Added Emscripten port. (asie) + Added Nintendo Switch port. (Lachesis, asie) + The main menu and game menu are now usable with keyboard, mouse, or joystick. Pressing a navigation key/joystick button or clicking an option in these menus will enable a cursor to select one of the options. Most listed options are selectable unless disabled by the current game, in which case they will be hidden from the menu entirely. However, the settings and exit options appear regardless of their respective counters. + MegaZeux now supports Reality Adlib Tracker (RAD) music files. Both 1.x and 2.x variants are fully supported. + New counter: TIME_MILLIS. Returns the milliseconds of the current system time. + New counters: MOD_LOOPSTART and MOD_LOOPEND. These counters return the start and end of the loop for the current playing music and can be set to change the loop while the music is playing. Setting MOD_LOOPEND to 0 disables the loop. These counters only work for Ogg Vorbis and WAV audio (not modules). + Added support for the LOOPEND tag for Ogg Vorbis files. This tag can be used to define the end of the loop directly, which may be more convenient for some users. This tag takes lower precedence than LOOPLENGTH if both are present, and will be ignored if its value is less than LOOPSTART. + The SPR#_OFF counter is now readable through Robotic. + New sprite counter: SPR#_Z. Sprites are displayed in order of their z value. Sprites with a higher z value will appear in front of sprites with a lower z value. This ordering takes precedence over both Y ordering (if SPR_YORDER is enabled) and sprite number. Removes the need to use SPR#_SWAP for managing sprite draw order. (Lancer-X) + New counters: FREAD_LENGTH and FWRITE_LENGTH. These counters return the length of the FREAD file/directory (if open) or the current length of the FWRITE file (if open). + New counter: SET "$string" "SAVE_ROBOT". This does the same thing as SET "filename" "SAVE_ROBOT", except it saves the robot to the specified string. + The default boot.dol for Wii builds with the editor enabled is now MegaZeux instead of MZXRun. + New GLSL scaling shader: "sai". This shader implements the "Scale 2xSaI" algorithm by Kreed with a modified interpolation function to produce sharper edges. This shader can scale up to any size larger than 640x350 and is comparable to hqscale (though it should look and perform a little better). + Fullscreen mode will now attempt to match a supported screen resolution if no "fullscreen_resolution" setting is specified. For scaling renderers, this favors the current desktop resolution. For "software", this favors smaller resolutions. + Added the config setting "fullscreen_windowed". When set to 1, MZX will create a borderless window with the current desktop resolution instead of regular fullscreen. Disabled by default. + Added the config setting "grab_mouse". When set to 1, MZX will trap the mouse cursor within the window while the window is active. Disabled by default. + The current renderer can now be set from the settings menu. + Added the 'softscale' renderer. This renderer is a generalized rewrite of the former SDL 2 overlay renderer implementation. It should perform significantly better and be more portable. + Added several palette editor usability improvements: + The current color stored with F2 is now displayed in the bottom-right corner of the palette editor help menu. + In SMZX mode 2 or 3 editing, the four colors of the current subpalette can be stored with F5. Stored subpalette colors can be placed at the current subpalette with F6. These are stored independently of the stored current color. The help menu color display will cycle through the stored colors. + In SMZX mode 3 editing, the current subpalette's indices can be stored with F7 and placed at the current subpalette with F8. The stored indices are displayed in the help menu next to the stored color display. + The shortcut for toggling the subpalette cursors has been changed to Insert. The subpalette cursors are now displayed in SMZX mode 3 editing and are enabled by default. + Palettes (and/or indices) can be imported into and exported from the palette editor with Alt+I and Alt+X, respectively. + Added a secondary editor-only palette which can be switched to with Tab. This palette is not saved with any world, but can be edited and imported to/exported from and can be used to copy colors/subpalettes between different sources. + checkres now displays the board, sfx, and robot (with line and position on the board) each file was referenced in. + checkres can now be used with a directory as the base file. Like a ZIP archive, checkres will recursively search the directory for .MZX/.MZB files and display information for all of them. + checkres has more display options: only display missing (-M) (default), only display created (-C), only display found (-F), also display missing (-m), also display created (-c), and also display found (-f). + checkres can now wildcard match resources from commands that use expressions or interpolation in filenames. This can be enabled with -w or enabled exclusively with -W. + checkres can now display unused resources in a path/zip after the other resources are listed (-u), or display only unused resources (-U). + checkres can now display every reference to a particular resource in a world instead of just the first with varying levels of information (-v, -vv). Added the option -s, which is the default and equivalent to older versions of checkres, and -1 as an alternate flag for -q. + checkres can now sort its output either by the name of the expected resource file (-N) (default) or by the location in the world the file was referenced (-L). + checkres option flags can now be combined (e.g. -aL). This does not apply to the "-extra" and "-in" flags. + New config options: "test_mode" and "test_mode_start_board". If "test_mode" is set to 1, MegaZeux will start the given file in testing mode, exactly as if the user used Alt+T on the first board from the editor. Setting "test_mode_start_board" to a valid board number in the world will start instead from that board. Exiting testing will exit MegaZeux entirely. - SDL 2 support for the overlay renderers has been removed. When specified for video_output, softscale will be enabled instead. - Removed WAV from the list of board mod extensions. FIXES + SET "$string" TO "fwrite" will now always write the delimiter regardless of the length of $string. Previously, this command would only write a delimiter if $string was a length greater than zero, requiring extra checks by the user to account for this special case. Compatibility checks have been added for for worlds made in older versions. + Fixed bug where robots attempting to copy the player over themselves with COPY x y x y or COPY dir dir would get stuck in an infinite loop instead of executing the next command. + SPR_YORDER and the sprite collision list are properly saved and loaded from saves again. + The SPR_NUM counter now has the full range of a regular counter and is saved. Out-of-range values are ignored for the purposes of its legacy IF and PUT uses. This only affects 2.92+ worlds. Additionally, 2.65 through 2.69c worlds treat its range as -128 through 127, fixing a bug in Sprite Catcher. + The active sprites count is properly updated when SPR#_OFF is set and is properly loaded from saves again. This value can be viewed from the variable debug screen now, though it may be inaccurate for older saves. + Fixed various bugs related to the robot position not being internally tracked correctly. This could be caused by WALK, SWITCH dir dir, OPEN, MOVE ALL, moving through a transport, pushing, and rotation. This fixes issues with IF ALIGNEDROBOT, THISX, THISY, THIS_COLOR, PLAYERDIST, HORIZPLD, VERTPLD, RID#, ROBOT_ID_#, the robot's coordinates displayed in the counter and robot debuggers, and MZM saving. Due to the number of features affected by these bugs, the fix only affects worlds saved in 2.92 or later. + Fixed a regression where rotating could sometimes fail to rotate the player, sensors, pushable robots, or transports. + When a robot uses the OPEN command and is pushed through a transport, MZX no longer crashes or creates invalid robots. + Fixed crash that could sometimes occur when pressing Alt+Up while drawing near the top of a board in the editor. + Fixed bug where canceling 'Alt+C' char selection in the robot editor would comment the current line. + Fixed a bug where F5 in the robot editor would not print data for extended chars. + Clicking through board name windows and other interfaces with the mouse should no longer place the current buffer. + Fixed a bug where the updater could fail to initialize due to a relative argv[0] in Windows. MegaZeux attempts to get the executable path from Win32 first now. + Improved warning message when no HTTP response is received. + The software renderer no longer tries to use an SDL_Renderer to draw the surface returned by SDL_GetWindowSurface. This fixes a crash when switching to fullscreen with the software renderer on some platforms. + Fixed a software renderer mouse crash bug caused by moving the cursor off the screen with a window bigger than the screen. + Fixed a bug where setting SMZX_MESSAGE to 0 wouldn't always draw the message correctly. + If a referenced SAM or GDM file isn't present, MegaZeux will attempt to load a corresponding WAV or S3M (respectively) with the same filename minus the extension. This should fix some music/sounds in older games that referenced SAM/GDM files but were packed with the post-conversion WAV/S3M files only. + The behavior for reseting the player movement repeat timers has been reverted to requiring all four movement keys released (as in 2.80 to 2.91i). The related player locking fix has not been modified. + IF "&$string&" and COPY BLOCK # # # # "&$string&" now properly resolve &$string& before checking if the first operand or the copy destination are a string (respectively), bringing their behavior more in line with SET/INC/DEC and other commands. + Fixed a regression where the COLOR INTENSITY commands would update the screen if used the same cycle as TELEPORT PLAYER. This fixes a graphical issue in Thanatos Insignia. + Improved string wildcard comparison performance. + Changed the debug window to display "2.65/2.68" for worlds from MZX 2.65 and MZX 2.68. Features from 2.68 still check for the intended MZX 2.68 magic; the very few existing 2.68 worlds that use these features need to be resaved in 2.69. + MegaZeux now attempts to fix Robotic that fails bytecode validation. This resolves error messages and bugs in Eternal Eclipse Taoyarin v1.0, Loco, Manuel the Manx, SaintZZT 7th, Slave Pit, and Ep+Arp World MZX. + The MOD SAM command has been restored for compatibility and is version locked to <2.80 worlds. This fixes missing sound effects in Crisis in Stuffyou City (original), Sprite Catcher, and Talon's Tale. This only works for libxmp builds. + Fixed a sprite collision bounding bug where the collision height bounding for the reference checked using the collision width instead. This fixes Manuel the Manx. + Fixed several memory leaks in the editor related to editing, placing, grab, and undo/redo operations on robots and scrolls. + Fixed vlayer memory leak when loading 2.84 saves. + Fixed a regression where the 'if c?? Sprite' legacy fix wasn't locked to 2.69c and up. This fixes Depravity (2003 DoZ #666). + PUT Sprite now works unconditionally for <2.80 games, fixing bugs where games relied on placing 0-height sprites or placing sprites before initializing their dimensions: Hackers Can Turn Your Computer Into a Bomb!, Lethal Recurse (2003 DoZ #215), Serum (2003 DoZ #404), Trashman Dan (Summer 2004 DoZ #18349). + The LOCAL and LOCAL# counters are now versioned separately, fixing bugs in Freedom Bound (Summer 2000 DoZ #4096) and Impact (2001 DoZ #027). + SHOOT now properly updates the blocked array. This fixes a bug in Captain Proton and the Reality Rippers (1999 WEoZ #173). + Fixed a bug where the custom SFX flag and max samples wouldn't be reset when creating a new world in the editor. DEVELOPERS + Fixed -Wunused-result warnings for Linux builds. + Added "Intel EMGD" to auto_glsl blacklist (questionable OpenGL 2.0 support). + Added platform-independent joystick event functions and updated the SDL, NDS, 3DS, and Wii event handlers for them. + MinGW builds now use -Wl,-Bstatic and -Wl,-Bdynamic to enforce the preferred linking when both static and dynamic builds of libraries are present. + For MSYS2 shells, config.sh now chooses the prefix /mingw32 or /mingw64 by default if $MSYSTEM is "MINGW32" or "MINGW64" and either the "win32" or "win64" arch is selected. + MegaZeux now uses the renderer free_video function on exit. + GL_LoadLibrary no longer fails if the library is already loaded in SDL 1.2. (Lancer-X) + GL renderers free textures and revert to fixed function pipeline where appropriate. (Lancer-X) + OpenGL ES support can now be enabled for SDL builds with the --enable-gles option. This option is force-enabled for platforms that only support OpenGL ES. + opengl1 renderer now always uses power of 2 textures, same as opengl2 and glsl. This provides a tiny performance improvement on most cards and a massive performance improvement on some other cards. (Lancer-X) + Added debug build sanitizer options for AddressSanitizer, MemorySanitizer, and ThreadSanitizer. MemorySanitizer requires clang and all currently require Linux/BSD/Mac OS X/similar. Support for all three is very experimental; they may require disabling options like modular builds or may not work at all. + Moved several param functions from robot.c to run_robot.c. Aside from a few exceptions, these functions are largely used in run_robot.c only. This should improve Robotic performance in release builds. + Updated MSVC project for Visual Studio 2019. (elig, Spectere) + Added experimental pledge(2) and unveil(2) support for OpenBSD builds. By default, this is enabled for the utils but not for MZX. Additionally, config.sh now detects OpenBSD properly and several warnings have been fixed. + Fixed faulty '!' rule logic in match_function_counter and changed 'key?' to 'key!' to prevent potential false matches. - Removed uthash as a build option. NEW in MegaZeux! New in Versions 2.90 to 2.91j New in Versions 2.84 to 2.84c New in Versions 2.82 to 2.83 New in Versions 2.81 to 2.81h New in Versions 2.80 to 2.80h New in Versions 2.60 to 2.70 New in Versions 2.01 to 2.60 New in Version 2.00 New in Versions Through 1.03 Table of Contents

New in Versions 2.90 to 2.91j

February 20th, 2019 - MZX 2.91j Here's a huge collection of bugfixes and a couple of features that needed to be split off from 2.92. Features: every release has an HTML copy of the help file now, the editor keeps separate board/overlay/vlayer buffers now, and anyone who still uses scrolls/sensors can view their info in the counter debugger. The global volume settings use an exponential curve now, range from 0 to 10, and have updated UI elements. Fixes in this release include: the updater won't complain about mzx_help.fil anymore, the NDS and 3DS ports have keyboards that work again, several bugs that would lead to worlds/saves with "Robot # does not exist on board #" errors have been fixed, and several crashes have been fixed. USERS + A complete HTML copy of the MegaZeux help file is now packaged with releases for all platforms. It can be found in the docs/ folder. + Nvidia and AMD switchable graphics drivers should now detect MegaZeux and MZXRun properly on Windows. + The editor now remembers the contents of the buffer when switching between board, overlay, and vlayer editing. For example, if a robot is selected on the board before switching to overlay mode, the robot will still be in the buffer when the user switches back to board mode. + The editor now remembers the last filename for importing and exporting MZM, MZB, CHR, PAL, and PALIDX files. + Scrolls and sensors can now be viewed in the counter debugger. They can be found by expanding the Board list (when present). + Readded "#version 110" directives to all GLSL shaders, fixing warnings on some Intel HD drivers. OpenGL ES builds should now comment out these directives. + Fixed bug where using Modify+Grab on built-ins could clear the floor under the built-in. + Fixed bug where key repeat wouldn't work for any text field in the NDS/3DS/Wii ports. This also affected the robot editor in Wii builds. + Fixed NDS touch screen support. Touching the screen no longer acts like escape and the keyboard properly works again. + Fixed a bug where the NDS keyboard would drop keypresses on games not running at speed 2. + The counter debugger now correctly displays the value of local0. + Fixed a bug where the counter debugger would not reopen to the correct robot local# value. + MZX now attempts to retry removal of an old file when updating if deletion fails initially. Error messages related to the failed deletion of "mzx_help.fil" or "assets/help.fil" are now suppressed as they are caused by a bug in older MZX versions. + The help file is now closed before the updater restarts MZX. + Fixed crash bug that could occur when removing old files after an update. + Improved manifest validity checks. + Fixed board editor crash caused by invalid thing IDs. + Player movement key repeat no longer resets when the player is locked. It will reset for a direction only when the arrow key corresponding to that direction is released. This fixes a bug in Brotherhood where the player would move at a fraction of the speed they were supposed to while swimming. + Added version checking for legacy IF c?? Sprite behavior. In versions 2.82b and prior, c?? would make this command ignore the provided param and use SPR_NUM instead. This fixes Project MoveZig. + Fixed spelling error in missile param dialog. + Switching boards in the editor now properly translates the new board's mod name, fixing cases where board mods would restart sometimes. + Fixed a bug where the current board mod wouldn't play after starting a listening mod, testing, returning to the editor, and then disabling the listening mod. + Replaced the linear volume setting curve with an exponential curve to make lower volumes less loud. The volume settings can now be set from 0 to 10 instead of from 1 to 8. + The config file setting pc_speaker_on=0 no longer prevents turning on PC speaker SFX at runtime. + Added temporary workaround for numpad 5 key detection when numlock is disabled. + "Forest to floor" and "Collect bombs" are properly enabled again for new boards by default. This fix doesn't alter config settings or saved .editor.cnf defaults. + The "Downver. world (MZX)" option in the "Export as" dialog is now completely highlighted when selected. (Lancer-X) + Starting MegaZeux with "startup_editor=1" no longer loads the default palette over the startup world's palette. + The move block action and undo/redo operations should now preserve the element beneath the player. + Fixed crashes caused by using block actions or COPY BLOCK on the player while the player is standing on a sensor. + Fixed several bugs where editor block actions and the commands COPY/COPY BLOCK would not check for the player or clean up robots/scrolls/sensors. Worlds/saves saved after these bugs occured could display "Robot # does not exist on board" errors when loaded. + The DUPLICATE SELF x y and DUPLICATE SELF dir commands now properly check for the player before attempting to duplicate a robot. This fixes a bug where MZX could create saves with "Robot # does not exist on board" errors. + Fixed a crash that could occur when importing a new board. + Fixed a bug where the 3DS onscreen keyboard would send key releases instead of key presses. + The 3DS onscreen keyboard now returns shifted chars when shift is active. + Fixed a bug where the libxmp implementation of MOD_ORDER and JUMP MOD ORDER could not restart the current order. + Fixed a crash with the libxmp implementation of MOD_POSITION when providing an out-of-bounds value. + Fixed a bug where Ctrl+[key] shortcuts would not work while a dialog list element was active on the Wii. + Fixed a bug where setting the board mod/charset/palette could truncate the first letter of the path on the Wii. + "mask_midchars" no longer masks the non-text char 127. + The message box title and the command [ now properly display the graphic for char 9 instead of a tab. + Added newline escaping to robot, counter, and string names in the counter debugger to work around formatting bugs. DEVELOPERS + Added the hlp2html utility, which can be used to convert WIPHelp.txt into web and printable HTML files. + Updated to latest NDS ARM7 template. + Updated SDL2 for Windows release builds to SDL 2.0.9. Table of Contents December 9th, 2018 - MZX 2.91i A small release with a bunch of fixes for bugs introduced mostly within the past few versions. Other highlights: joysticks should be hot pluggable now and Alt shortcuts now also work with the command key in Mac builds. USERS + MZX now properly detects when joysticks are connected and disconnected at runtime for platforms using SDL 2. + Fixed bug where the robot editor would open with the cursor at the end of the line instead of the start of the line. + Fixed a bug where the robot box could display using MZX mode but SMZX colors if opened on the first frame SMZX was enabled. + The built-in text box title should display correctly again in SMZX modes. + Fixed regression where keys could trigger wrong "keyN" labels. + Alt+F2 can now be used to open the settings dialog. + Mac users can now optionally use command in place of alt. + Improved editor cursor color selection for SMZX modes 2 and 3. DEVELOPERS + Fixed make test for SDL 1.2 builds. Table of Contents November 14th, 2018 - MZX 2.91h A minor release primarily focused on improving counter/string lookups and fixing bugs in the robot editor and counter debug menu. USERS + auto_glsl correctly switches to glsl on startup now. + Fix bug where "(editor)" wouldn't always display in the caption when editing. + The single line macro dialog now allows the full size of the single line macros to be edited. This fixes a crash caused by having a macro configured to be longer than the edit box could display. + Setting a counter to a string no longer duplicates the entire string in memory. + Fixed faulty BOARD_X and BOARD_Y bounding for values greater than the board width or height. Fixes potential crashes with BOARD_CHAR, BOARD_COLOR, BOARD_ID, and BOARD_PARAM. + The value of SPR_YORDER is now correctly displayed in the counter debug menu. + Improved the performance of the counter debug search. + Fixed cosmetic counter debug menu issue where the the "String" tree appeared to be expandable/collapsable when empty. + Fixed faulty substring searching algorithm used in the counter debug menu search and for breakpoints. + Added "Search" and "Cancel" buttons to the counter debug menu search so it can be used with the mouse. + When testing from the editor, if "__test.mzx" exists MegaZeux will now choose a numbered name for this world backup (e.g. "__test2.mzx") instead of potentially overwriting work. + Fixed bug where six-digit line numbers would display in the robot editor incorrectly. + Inserting text in the robot editor using the F2/F3/F4/F5 shortcuts can no longer exceed the line length limit, fixing related crashes. + Using F5 in the robot editor generates decimal numbers instead of hex numbers now. + Fixed robot editor bug where pressing delete at the end of a line wouldn't join lines unless the current line was empty. + Restored the ability to use the F7/F8 cheats outside of the editor. This feature was broken in 2.91g. To enable cheats outside of the editor, the config option "allow_cheats" must now be set to "mzxrun" or 1. The former will enable them for MZXRun only (same as from 2.82b to 2.91f) and the latter will enable them for both executables (same as the -t flag in DOS versions). + Fixed bounding bug on the "board_default_width" and "board_default_height" config file options. + Separated robot editor "Search and Replace" dialog into a "Search" dialog and a "Replace" dialog. Both dialogs are smaller in size than the original. The order of the elements in these dialogs has also been altered to be more user- friendly. The hotkey for the new replace dialog is Ctrl+H. + Fixed Ctrl+R repeating for the "Replace All" robot editor search operation. Previously, it would act like "Replace". + Canceling the robot editor search/replace menus no longer disables the repeat feature. + Searching in the robot editor now properly preserves the case of the search string if case sensitive search is disabled. + Fixed bug where toggling the robot debugger position wouldn't take effect immediately. + Exiting the editor with the "startup_editor" config setting enabled should no longer inappropriately close MZX. + Selecting "tile" for the char editor import mode works again. + The bounds for the main editor charset import/export offsets and size have been increased to allow for extended charset values. + Fixed the "KEY?" labels for keys that no longer have a unicode representation in SDL2. + Fixed SET "$string" "FWRITE#" bug where, if # exceeded the length of $string, the output would be clipped to the wrong length. + The missile color ID char is now correctly set back to its default value when a new world is created from the editor. DEVELOPERS + Cleaned up the counter debug menu code. + Switched from uthash to a modified version of khash for counter and string lookups. Counters/strings now consume less memory and counter/string lookups should perform slightly better on most platforms. + Replaced toupper/tolower in memcasecmp and substring searching with a lookup table-based implementation of tolower. + Refactored the following contexts to use the main loop: robot editor, intake, thing menu. For compatibility purposes the old intake still exists, but all robot editor hacks have been removed from it. Table of Contents October 7th, 2018 - MZX 2.91g This bugfix release fixes various minor-to-moderate bugs in various areas of MegaZeux. The title/game update code has gone through a fairly major overhaul and several parts of MegaZeux have been combined to use the same loop. The conversion of MegaZeux's interfaces to be compatible with this loop is an ongoing process expected to occur over several versions. USERS + Added "allow_screenshots" config file option. Setting this option to 0 will disable the built-in screenshot feature. + The F12 key can now be detected by Robotic. + Loading saves from the title screen no longer resets TIME. + Loading saves from the title screen no longer erroneously changes the player restart position. + Swapping worlds now sets the correct TIME and player restart position values. + Fixed a bug where the fade out effect from COLOR FADE OUT would be reset after any Robotic dialog. + Undo for overlay and vlayer mouse drawing now works properly. + Mouse drawing in the editor now draws smooth lines instead of lines with gaps. + Fixed move block bug when the source and destination both overlapped the player. + Palette editor component entry now accepts most of the same inputs as dialog number boxes. + The board name in the caption now updates to reflect the current board while testing. + Fixed bug where TIME would either decrement normally or not decrement at all while the slow time effect was active. + Added compatibility for pre-port endgame teleport behavior. In DOS versions of MZX, the endgame teleport would disable itself after being triggered for the first time and any following endgame would instead trigger a game over. + Reduced stutter in NDS and 3DS main screen scrolling. + Fixed a bug where creating a string MZM would not correctly set the string's length for preexisting strings. + Fixed a bug where loading robot source code from a string wouldn't work correctly with the robot debugger. + The help system is now accessible from the main menu and game menu. + The settings screen is now accessible from the main menu, game menu, editor, and palette editor. + The shortcut Ctrl+F2 can be used to open the settings screen from anywhere the settings screen is accessible. This shortcut works even if F2 is used for a different feature and will also ignore the value of the F2_MENU counter. + Fix a crash that would occur decrypting a world with a password exactly 15 chars long. + The label for the INPUT STRING command should no longer be able to overflow outside of the window. + Fix a crash that would occur attempting to open the help file from the world decryption confirm dialog. + Fix bug where saved layer MZMs and board MZMs without robots would have useless extra data at the end of the file. + Scroll contents properly display game colors during gameplay. + An error message is now displayed for failed board exports. + Enabled writing zip data descriptors on the 3DS to decrease saving time. - The "password protected" error message has been removed as it was redundant with the confirmation dialog following it. - The "disassemble_extras" and "disassemble_base" options no longer affect Robotic output during gameplay. SAVE_ROBOT will always output extra words and base 10 numbers regardless of user configuration. DEVELOPERS + Implemented a main event loop to replace the various separate event loops scattered around MegaZeux. See core.h and core.c for more info. + Refactored the following contexts to use the main loop: titlescreen, gameplay, main menu, game menu, editor, palette editor. + When enabled, the debug FPS display will now update from any interface using the main loop. If fullscreen mode is active, the FPS display will now appear in the top-left corner of the screen for any main loop interface aside from the editor. + The --disable-screenshots config.sh option can be used to disable screenshot support. This allows platforms that don't use render_layer.c to stop building and linking it. + Cleaned up m_show()/m_hide() overuse. + Replaced all uses of "bool" with "boolean" to avoid potential C/C++ compatibility issues. - Removed most old/unused source code in contrib/unzip, src/old, and src/vfs. Table of Contents September 17th, 2018 - MZX 2.91f A bugfix release focusing primarily on renderers, the 3DS and Wii ports, and the Makefile build system. Highlights: the 3DS port should perform better now, the Wii port's GX renderer has been restored, the 'darwin' platform has more Unix-like options now, and several crashes have been fixed. USERS + The config setting 'audio_buffer' can also be specified with 'audio_buffer_samples' now. The default value for this setting is now 1024 (instead of 4096). + Fixed a crash that could occur in the counter debugger. + Fixed a crash that occurs when attempting to add a watchpoint for robot local counters, loopcount, etc. Using these counters as watchpoints will watch the global robot's instances of these variables (for other robots, use e.g. r#.local1). + Using SMZX_INDICES or LOAD_ROBOT on an unset string no longer causes a crash. + png2smzx is now properly bundled with Linux builds. + Improved the performance of loading partial charsets for the glsl, opengl2, and 3DS renderers. Other renderers were not affected by this issue. + Fix opengl2 unbound sprite regression introduced in 2.91e. + The opengl2 renderer now correctly draws unbound sprites containing chars with a transparent foreground color. + 3DS renderer optimizations. (asie) + 3DS screen focusing now mimics the NDS port's behavior. (asie) + Fixed bug where games could fail to open files on some platforms if the paths contained duplicate slashes. (asie) + Added a Wii software layer renderer. This renderer can be selected with "video_output = xfb" in the config file. + Wii GX renderer optimizations. + Added layer rendering support to the GX renderer. + The Wii GX renderer now uses the gl_vsync config option to toggle vsync. For the Wii, this feature is on by default. Disabling it may increase the framerate of some games but may also cause other problems. + The loading bar on console platforms now redraws the screen less often. DEVELOPERS + GAMESDIR/BINDIR/SHAREDIR now properly apply PREFIX when they are not explicitly set by config.sh. + LIBDIR is now user-definable like BINDIR et al. Variations such as "lib64" currently must be explicitly provided for platforms that still use them. + Remove src folder from CFLAGS to fix a bug where system includes could be mistaken for MegaZeux headers. All includes of MegaZeux headers must be done using relative paths now. + Fixed include bugs for X11 and Carbon clipboard handlers. + Makefile now attempts to respect the prefix when running sdl-config, sdl2-config, and libpng-config. + Renamed the "darwin" config.sh platform to "darwin-dist". + Added "darwin" and "darwin-devel" config.sh platforms. These act like Mac OS X versions of the "unix" and "unix-devel" options. + The darwin-dist build system and instructions are now somewhat more clear and robust. + Fixed a bug where zlib wouldn't necessarily be linked to png2smzx. + Renderers will now use render_layer to draw the text_video fallback if no render_graph function is present. Table of Contents September 3rd, 2018 - MZX 2.91e Bugfix release fixing some crashes, port bugs, and some other significant issues affecting a variety of things. USERS + Fixed bug where loading a board charset would also clear all of the extended charsets. + Fixed bug where loading a default charset in the editor would also clear all of the extended charsets. + Loading a 2.91 world when a renderer with no layer support is active no longer triggers an error message. + Fixed a memory corruption bug in the non-SDL Wii port caused by faulty threading code. + Fixed crash that could occur when updating a board undo frame. + Fixed crash when changing to a board with overlay disabled in overlay editing mode. + Fixed a bug where the protected charset could get cleared for renderers without layer rendering support. + Enabled C99-compliant stdio functions for mingw, fixing at least one crash bug and possibly improving performance. + The NDS port now attempts to detect argv[0]. + The 3DS port now attempts to detect argv[0] and otherwise will start in /3ds/megazeux instead of /. + The 3DS port .3dsx file is now located in /3ds/megazeux. + The MOVE PLAYER [dir] and MOVE PLAYER [dir] [label] commands now update the commands cycle and commands total values. + Fixed a bug where MZX and checkres wouldn't accept some DEFLATE-related ZIP flags. + checkres no longer crashes on failing to open a resource zip. + The window caption now updates correctly when using either of the overlay renderers. + Update checking will now display an error instead of silently hiding the updater when the updater fails to initialize. + Fixed an issue where UIs would execute redundant frames. + Fixed a bug where string comparison would not order strings of different lengths correctly. (GreaseMonkey) DEVELOPERS + Code style has been cleaned up in numerous files. + Moved GLSL shaders from assets/shaders/ to assets/glsl/. + Added missing GPL headers to GLSL shaders and added slightly better documentation to them. Table of Contents July 12th, 2018 - MZX 2.91d This is a minor bugfix release to get a handful of fixes out primarily concerning the updater. The NDS/3DS/PSP/Wii ports now include a copy of Caverns of Zeux. USERS + Added timeouts to updater network operations. + Fixed bug where the updater would retry downloads without regard to the status code. + The updater is now force-disabled for all non-Windows platforms in config.sh. + Fixed bug where breakpoints could trigger on the wrong line. + Amended VOLUME/MOD FADE # # bounding to clamp values in port versions. DOS versions will still wrap between 0 and 255. + Added DOS compatibility fix for sprN_off. + Window caption is now properly updated when loading a world from an unedited world in the editor. + Fixed bug where ".." would change to the current directory if the current path ended in a path separator. - Removed undocumented support for "title.cnf", "game.cnf", and "editor.cnf" config files, which would have been loaded from the same directory as the main config (not to be confused with world-specific config files, which are still supported). DEVELOPERS + The MSYS2 buildscripts have been overhauled to work with the new devkitPro pacman repositories. + Added config options to select vorbis, tremor, tremor-lowmem, or to disable ogg vorbis file support. The 3DS and Wii ports now use tremor instead of tremor-lowmem. Table of Contents March 4th, 2018 - MZX 2.91c This release contains an assortment of bugfixes ranging from player clone fixes to obscure compatibility patches. A handful of updater issues have been fixed (or at least addressed). MegaZeux can now automatically check for updates on startup on Windows platforms. This behavior can be configured, and by default will simply leave a message in the window caption. USERS + MegaZeux can now automatically run the updater on startup on applicable platforms. This can be configured with the 'update_auto_check' config file option. + Fixed a bug where several .MOD variants stopped working with libxmp enabled. + Sound effects in subdirectories can now be used in the SFX editor. + Fixed a bug where checkres would fail on legacy worlds with very long custom SFX. + Checkres no longer ignores the SFX tables of 2.90+ worlds. + Fixed a bug where interpolated expressions containing ternary operators could terminate counter names early. + Fixed faulty IF ANY compatibility behavior. + Fixed a bug where FWRITE functions could change the case of user-defined filenames when creating new files on non-Windows platforms. + SMZX mode 1 palettes are now exported correctly as 16 colors instead of as 256 colors. + Fixed subtly inconsistent timing in certain built-ins. + Fixed bug where wind and transporters could clone the player. + MegaZeux now restarts correctly in paths containing spaces when the updater is run. + Subroutines in pre-port MZX worlds now always return to the command after the subroutine was sent. + Typed color components now wrap from the maximum value to zero like dialog number inputs, and pressing minus will now negate the input number. + Copying chars in the char editor between regular and SMZX screen modes now works properly. + Fixed a crash that could occur when placing things on a vlayer larger than the current board. + Sharks and SpittingTigers with firing rates greater than 4 now retain their firing rate when edited. + Fixed a bug where world decryption could crash. (Revvy) + If the glsl renderer is selected by default, the detection of a software opengl driver will result in falling back to software. (Lancer-X) + Fixed a bug in the GLSL renderer where an additional window is created if the OpenGL version is low enough to cause a fallback to software. (Lancer-X) DEVELOPERS + Added .MZX-based unit testing system. Run with "make test". See testworlds/README.md for more information. + The default renderer is now auto_glsl, which turns into glsl if not using a blacklisted opengl driver. (Lancer-X) Table of Contents January 6, 2018 - MZX 2.91b Here's a fairly significant update for MegaZeux 2.91, fixing several major Robotic, audio, and editor related bugs, as well as issues that mostly affected Linux platforms. Also of note is the updated MSVC and Xcode support by Spectere. USERS + Added the config file option "editor_thing_menu_places". When set to 0, selecting an object from the thing menus (F3-F10) will place the object in the buffer but not on the board. Defaults to 1. + Fixed a bug where MZMs could sometimes fail to load in the editor. + MZMs loaded in the editor now behave correctly when undone. + Fixed bug where GOOP_WALK wouldn't always be 0 when loading old worlds. + Values of GOOP_WALK greater than 1 no longer cause issues. + Board time limits greater than 255 are no longer truncated when saving worlds/saves. + Fixed bug where "robot not found" errors could result from using backspace on robots in the editor. + Fixed backwards string inequality evaluation. + String inequality compares are now endian-safe. + Fixed a bug where certain mods (e.g. FR_TOWER.MOD, Neve.s3m) could repeat to the wrong order after reaching the end. + Fixed a bug where certain .it channels could partially ignore the volume command. + Setting mod_position in libxmp now works for positions in the middle of orders (NoSuck). DEVELOPERS + Updated MSVC for Visual Studio 2017. (Spectere) + Added xcode support. (Spectere) + "make clean" now deletes ccv. (pgimeno) + Fixed creeping CRLF usage. (Lachesis, pgimeno, Spectere) + Fixed a bug where the MSYS2 build scripts could inadvertently include non-portable SDL2 binaries in Windows builds. Table of Contents November 22, 2017 - MZX 2.91 This release introduces mostly new editor features, but also a a few Robotic features to note. It also fixes over 30 bugs. MegaZeux now features a palette editor for SMZX modes 2 and 3, and worlds can be saved and loaded in SMZX mode. The char editor has been changed to allow preview palettes (mostly to aid with SMZX editing), and can now access the extended character sets. The new vlayer editor allows the vlayer to be edited directly. On the Robotic side of things, LOAD_COUNTERS actually works now, SMZX mode 3 indices can be loaded from a file, the message line can be configured to use normal MZX mode in SMZX modes, and new string features such as simple wildcard matching and negative offsets have been added. String support has been improved to disallow invalid or nonsense string splices that previously had undefined behavior. Additionally, asie's new Nintendo 3DS port has been merged into MZX, and optional SDL support has been added for the Wii. FEATURES + Added SMZX_INDICES special counter to load SMZX indices. This counter works with either a filename or a string, e.g. set "file.palidx" "SMZX_INDICES", and will do nothing outside of mode 3. + Added MOD_LENGTH counter. The value of this counter is length of the current playing music in rows for modules, or in samples for PCM audio. + Added MAX_SAMPLES counter. When set, MegaZeux will limit the maximum number of samples that will play simultaneously. Set to -1 to disable the sample limit. + Added 'max_simultaneous_samples' config file option. This behaves the same as the MAX_SAMPLES counter, but applies globally. + Added SMZX_MESSAGE counter. When set to 0 with SMZX active, messages will display in normal MZX mode instead of SMZX using the first 16 colors of the SMZX palette. + Added 'random_seed#' counters to read and write the random seed, 32 bits at a time (random_seed0 controls the low 32 bits and random_seed1 controls the high 32 bits. (Lancer-X) + Added a case-sensitive string equality operator: IF "$string" === "ABC" then "label". + Added wildcard-matching string equality operators: IF "$string" ?= "a?%" then "label" IF "$string" ?== "a?%" then "label" (case-sensitive). The character '?' will match exactly one of any character in $string, and '%' will match any number of any character in $string (including no characters). + Added negative indexing for strings, e.g. SET "$string.-X" 32. This manipulates the string at the Xth character starting from the end of the string (with -1 for the final character). + Added negative offsets for strings, e.g. SET "$string+-X" "a". + Added multiple character indexing for strings. When a length is provided with a string index, e.g. SET "$string.X#Y" 12345, the characters at positions X, X+1, ..., X+Y-1 will be treated as a single 8*Y bit number. This works for values of Y between 1 and 4, with 4 characters providing the same functionality as a counter. + The palette editor and character editor are now accessible while testing. Press Alt+E or Alt+C respectively to access them from the counter debugger. + Extended the palette editor to SMZX modes 2 and 3. The updated palette editor allows the editing of all 256 SMZX mode 2/3 colors and editing color indices for SMZX 3. + Component numbers can now be typed in the palette editor by clicking the component name or its number, e.g. clicking "Red" allows you to type a red value. + SMZX indices can now be imported/exported while editing in mode 3 using import/export palette. + Added a new vlayer editor. In the world editor, press Alt+V to switch to the vlayer editor. The vlayer is something like an invisible global overlay that can be used to store and retrieve graphical data through Robotic. See the editor help and the Robotic reference manual for more details. + Added color selection to the character editor. Press C to choose a color to preview and edit chars with, and press Alt+C to revert back to the default grey. + Added extended charset support to the char editor. Extended charsets can be selected during char selection. Note that in gameplay these chars can be accessed only by unbound sprites. + Selected blocks of chars with a height greater than one (before selecting a subdivision) are now properly supported. Using -/+ with these selections will move in a tiled manner, with no overlap between chars in "tiles". Charsets can also be exported/imported using this tiling behavior. + The -/+ keys now behave the same in the char selection screen as they do in the char editor. + The character editor help now covers several shortcuts that were previously missing (Alt+B, Shift+Arrows, etc...). + The undo/redo shortcuts in the character editor are now Ctrl+Z for undo and Ctrl+Y for redo. + Added undo/redo functionality to the world editor. Use Ctrl+Z to undo changes to the board/overlay/vlayer and Ctrl+Y to redo. + The default editor undo history stack size has been extended to 100 levels. + The editor will now prompt the user to create a new starting board when opened. If a new board is created, the global first board will be set to the new board and the title board will be renamed. + Saved positions now have confirmation dialogs. Saved positions are saved to/loaded from the editor.cnf file for each world. + Pressing Enter/Return on the overlay (and vlayer) now acts the same as on the board, changing both the buffer and the current layer being edited. + Pressing P on the overlay (and vlayer) now acts the same as on the board, changing the character in the buffer but NOT on the current layer. This is equivalent to the original overlay behavior for Enter. + Block tiling movement (Ctrl+Arrows) now works with most block actions, and does not require an initial block placement to activate. + Restoring its DOS functionality, Alt+D now toggles the default colors of built-in types in the editor. When disabled, built-ins placed from thing menus will use the buffer color instead of their default colors, and a red dot will appear on the right side of the status bar. + Color selection now supports typing in the hex value of a color/subpalette to select the given color/subpalette. For example, typing "4c" will select background color 4 and foreground color 12. + Readded the downver utility. - Removed the undocumented Shift+F7 shortcut in the editor. This shortcut was redundant with F11. FIXES + Fixed a bug that would cause Linux binaries to fail to find most resources. + Fixed a bug where loading a save from the titlescreen, exiting gameplay to a world that doesn't exist, and then loading a second save would corrupt the counter and string hash tables. + Fixed crash that would occur when loading a saved position on the same board referring to out-of-bounds coordinates. + Fixed a freeze that could occur opening the counter debugger to an empty list or searching for a counter in an empty list. + LOAD_COUNTERS now works as intended. + Fixed a bug where key repeat would be prematurely terminated when releasing a key while holding another key. + Attempting to open the robot validator with no errors will no longer crash MegaZeux. + Backspace now mirrors delete in overlay mode instead of affecting the board. + Moving an overlay block partially out of bounds in the editor will now correctly clear the block's original position. + The color selector will now correctly display SMZX palettes in SMZX mode instead of the default char 254. + Fixed bug where the mouse cursor would vanish after using the robot debugger configuration dialog in the editor. + Fixed a bug where the counter debugger could sometimes display behind the robot debugger after exiting the counter debugger. + Undo in the char editor now works correctly with the mouse. + The char editor no longer forces the screen to SMZX mode 1 when editing in SMZX modes 2 or 3. + Fixed screen corruption bug when resizing the char editor in SMZX modes. + Fixed a bug where multichar editing wouldn't correctly wrap to the start of the charset. + The editing area outside of the current board is now correctly drawn when SMZX is enabled. + The viewport is now correctly drawn when SMZX is enabled and the UI or unbound sprites are active. + The editor bar no longer appears while SMZX is enabled in view mode. + Messages are now drawn correctly in SMZX mode. + Fixed bug where centering the viewport could change the width and height of the viewport. + Unbound sprites are now clipped correctly against the viewport when the viewport origin is not 0,0. (Lancer-X) + The VLAYER_SIZE counter now clears new vlayer area added when it is increased. This applies only to 2.91+ worlds. + The VLAYER_WIDTH and VLAYER_HEIGHT counters now preserve data on the vlayer when set. This applies only to 2.91+ worlds. + Fixed several bugs with string length and offset parsing that would allow invalid string accesses to work in certain cases. + COPY BLOCK $string now works correctly with string splices. + Fixed a bug where saving and loading 2.90X files wouldn't work on the Nintendo DS. + Fixed a bug where mouse clicks would carry through from the UI into games. + Invalid gl_scaling_shader values should no longer appear as the current loaded scaler. + MegaZeux now falls back to the default scaling shader when a selected scaling shader fails to compile. + Blank sprite chars are now drawn when ccheck is 3. (Lancer-X) + The sprite color is used with ccheck 3 collisions. (Lancer-X) + When spr_yorder is enabled, sprites with the same (sprN_y + sprN_cy) value are now consistently ordered by their sprite numbers. + The collision rectangles of ccheck 3 sprites now constrained to the sprite dimensions (Lancer-X). + MZX no longer crashes when a line of length 512 characters or longer is pasted into the robot editor. + Fixed a crash bug when trying to swap a sprite with an invalid sprite index. DEVELOPERS + Added Nintendo 3DS port. (asiekierka) + Added "make uninstall" option to the Linux makefile. + Added devkitPro portlibs paths to the NDS and Wii Makefiles. - Removed the depackers and non-MegaZeux formats from libxmp. Table of Contents September 4, 2017 - MZX 2.90d Here's another bugfix release. This is mostly assorted small fixes, but there are also a couple of major fixes here: first, the ternary operator now works correctly when nested both with and without expressions, and second, sprN_setview does not break in conjunction with certain unbound sprites. Additionally, SAMs will not be converted to WAV files anymore (and are now natively supported) and the robot debugger config is accessible from the editor. FEATURES + The current MegaZeux version is now visible from the enter menu on the title screen. This is to assist identifying the version on platforms that don't respect window title changes or have no window border. + Updated checkres.bat and checkres documentation. + The robot debugger configuration screen is now accessible from the editor via Alt+F11. + Removed SAM to WAV converter. MegaZeux now has native SAM support. (asiekierka) + Added crt-wave.frag, updated crt.frag. (astral) FIXES + Fixed a bug where MegaZeux would crash when editing a robot with an invalid IF command operator. + Fixed a bug where the ternary operator would fail to find the correct colon when the middle term contained a second ternary operator in a nested expression. + Nested ternary operators should now behave as expected. + Fixed a bug where the built-in cursor would disappear after exiting testing with EXIT_GAME. + Fixed a bug where the listening mod would not restart after exiting testing. + Fixed a bug where the robot debugger would not wrap long lines of Robotic code correctly. + Attempting to save a world in a write-protected location correctly displays an error message again. + Fixed a bug where key repeat would not work when scrolling through the counter debugger tree list. + checkres will no longer report empty filenames as dependencies e.g. SET "" TO "FWRITE_OPEN". + The -q flag in checkres will now correctly output filenames instead of nothing. + Fixed a bug where sprN_setview would scroll the viewport to the wrong side of the screen if the sprite is unbound and is close to the top or left edge of the board. (Lancer-X) DEVELOPERS + Fixed PSP and NDS ports. (asiekierka) Table of Contents July 25, 2017 - MZX 2.90c This is a small fix release mostly cleaning up issues from the previous release. Notable fixes include a crash on certain instances of string interpolation into counters/labels/text. Playing mods as sound effects works again, and the audio_sample_rate config file option now works correctly. This release also includes support for loading save files from MegaZeux 2.84X and experimental editor behavior for handling board charsets and palettes. FEATURES + Save files from 2.84X worlds can now be loaded. + The editor can be configured to automatically load board charsets and palettes now. Use the 'editor_load_board_assets' config file option to enable this behavior. This behavior is disabled by default. Note that this will OVERWRITE THE CURRENT WORLD CHARSET AND PALETTE and your changes will NOT be saved automatically. + GLSL is now the default renderer. (Lancer-X) FIXES + Fixed bug where --disable-modular builds would fail to link. + Fixed bug with libxmp integration where mods could not be played as sound effects. + Fixed bug with libxmp integration where MZX would assume audio_sample_rate was 44100, causing mods to play at incorrect pitches with other rates. + Fixed bug where editor config file options would be ignored at the command line. + Fixed bug where string interpolation into a label/counter name could cause MZX to crash with very long strings. Table of Contents July 16, 2017 - MZX 2.90b It's been two weeks, so here's a bugfix release for MZX 2.90. There isn't a whole lot that's new to talk about. Firstly, the palette editor has gone through an overhaul. This is mostly internal preparation for an eventual SMZX palette editor, but the new features include the partial restoration of mouse input (which was removed in 2.80X), the addition of color sliders, the ability to hide the palette editor help, and two new colorspaces (HSL and CIELAB) to aid in the selection of palette colors. Next, the robot debugger introduced in 2.90 has new features. You can now set "watchpoints" to watch the status of particular variables, and you can send labels/goto from the robot debugger. The robot debugger config screen has been visually improved, and line number breakpoints can be defined. Another notable feature is that KEY_PRESSED and KEY_CODE values are now displayed in the debug window during gameplay. libxmp is now the default sound engine for modules, fixing a longstanding bug where certain S3Ms would have muted channels. GDM modules are now supported by MZX again. If you notice any inaccuracies with mod files, please report them to the tracker. Fixed bugs include a major overhaul of the glsl shaders for compatibility with almost any system, various sprite, text box, and input bugs, a crash fix when MZMs were saved from out of bounds board locations, and a bug where opening worlds or testing from the editor could cause MegaZeux to exit. FEATURES + The "shaders/extra" folder is now "shaders/scalers". The default vertex shader is still located in the shaders folder. + The default scaling shader can now be set in the config file using the gl_scaling_shader option. If not defined, MegaZeux will load assets/shaders/scalers/semisoft.frag. + The robot debugger now supports monitoring the values of counters and strings. Use the config menu/breakpoint editor to add watchpoints; when the debugger detects a change in a watchpoint counter/string AFTER a command has been executed, the robot debugger will open. + The robot debugger can now send robots labels. Use 'G' or select 'Goto' in the robot debugger to use this feature. The name and label inputs support expression parsing and string/ counter interpolation. + The robot debugger can now use line numbers in breakpoints. + The palette editor help can now be hidden with Alt+H. The default behavior for this can be set in the config file. The palette editor help is visible by default. + The palette editor's mouse functionality has been improved. Behavior when clicking the palette has been restored, and component sliders have been added. + The palette editor now supports alternate color spaces. + The debug window now displays the last key_code (green) and key_pressed (magenta) values detected during gameplay. These values are located in the bottom right corner of the window. + The default fullscreen resolution for scalable renderers is now 1280,720. The default fullscreen resolution for 'software' is still 640,480. The default aspect ratio is now 'modern'. + The checkres utility has been updated to support 2.90X worlds, worlds in subdirectories of zip archives, multiple input files to test, and the ability to specify secondary directories and zips to search (e.g. for games with separate music zips). BUGFIXES + Fixed a bug where certain "keyN" labels, such as "key$", would not work correctly. + Integer comparisons between numbers greater than 2^31-1 apart now work correctly. (Lancer-X) + The palette editor now displays the SMZX mode 1 palette correctly. + Sprite collisions now correctly ignore the sprite's visual width and height. + Blank lines are no longer skipped when copy-pasting text into the robot editor. (Lancer-X) + Fixed a bug where key presses in dialogs could be detected in games, and keypresses could still carry between other dialogs. + [ message boxes now use the same screen mode as everything else. Same with scrolls. (Lancer-X) + spr#_setview now works with unbound sprites. It's pretty nasty as the viewport can't scroll with pixel precision, but the new behavior should still be better than the old. (Lancer-X) + Fixed a bug affecting certain Intel HD Graphics cards and the GLSL renderer that appears to have been around since that renderer was first introduced. (Lancer-X) + Fixed a bug where the numeric numpad keys were inappropriately translated to regular keys based on numlock when they were read from KEY_PRESSED. This behavior is now locked to worlds from 2.82X through 2.84X. + Fixed a bug where warping the mouse on one axis would snap the mouse to the nearest pixel on the other axis, causing problems for upscaled windows. + Fixed a bug where mouse control would not respect video_ratio settings aside from "stretch". * Fixed a bug where MZX would attempt to load certain invalid worlds that should have been caught by validation. + Copy block to MZM no longer crashes when the MZM is partially overlapping the board edge. (Lancer-X) + Fixed bug where MegaZeux would sometimes exit immediately on loading a game or would immediately exit testing. DEVELOPERS + libxmp is now the default module sound engine. Use "make xmp" to make and install libxmp if it is not available on your platform. + Mac OS X portability improved. (Spectere and Why-Fi) Table of Contents June 29, 2017 - MZX 2.90 Hey, it's been a while! Didn't mean to keep everyone waiting. To make up for it as much as possible, we've prepared an extra special release of MegaZeux here for you. Yeah, you! I don't even know where to start with this release, as there's simply a lot to talk about. MZX's world formats and rendering architecture have gone through major overhauls, and a multitude of bugs have been fixed (60+). Particularly the MZX UI graphical glitch that occurred when an SMZX mode was enabled. Some notable new features are unbound sprites (MZX's new native pixel precision support), loading character sets/palettes/source code/MZMs from strings, saving MZMs to strings, a new Robotic debugger, the SAVE_COUNTERS and LOAD_COUNTERS function counters, options to help create standalone game releases, the ability to assign character sets/palettes to a board to load on entry, and resetting boards on entry. The size limit of Robotic bytecode has been increased to 2MB. Other important mentions: MegaZeux has been updated to use SDL 2.0 and libmodplug 0.8.9.0. The SAVE_WORLD function counter has been permanently removed. The downver utility has been temporarily discontinued, as adapting it to this release would have been a considerable amount of work. Instead, there is a new option in the Export menu in the editor to export a 2.84 world. Enjoy, and try not to get overwhelmed by all of the new stuff! FEATURES + Added a built-in robot debugger. See the Debug Mode section of the help file for details. + Added the COMMANDS_STOP special counter to MegaZeux. When a robot executes a number of commands exceeding this value while testing, the robot debugger will be enabled automatically and will open. During regular gameplay, it will be ignored. The default value of COMMANDS_STOP is 2000000. + The counter debugger now remembers its previous position after being reopened. + Added commands_cycle and commands_total variables to the Robot section of the counter debugger. See the Debug Mode section of the help file for details. + Certain types specified as 255 on the char ID table are now treated as Custom* types when placed and selected in the editor. If you switched a type to char ID 255 in a game that already had that type, the parameters will not be changed (and the types will still be char 0 if they were already placed in the world). When making a type a Custom* type from the global chars dialog, it will appear visually different in the list and in the character selection window, and also ask for confirmation. + The enter menu can be closed with escape now. + In the editor, the Backspace key now removes the top layer and brings the under layer to the top, as a compliment to Del. This does not affect the text entry behavior. + Seeking in the String section of the counter debugger will now ignore the $ prefix. + Tentative joypad POV hat support added: joyNhat = U, D, L, R + The BUTTONS counter has been extended to support the mouse wheel and X1/X2 buttons. + Strings can now be used in the LOAD PALETTE "file" command in place of a file name, i.e. LOAD PALETTE "$string+10". + Strings can now be used in the LOAD CHAR SET "file" command in place of a file name, i.e. LOAD CHAR SET "@240$chars". + Strings can now be used for the special counter LOAD_ROBOT in place of a file name, i.e. set "$str" "LOAD_ROBOT". + Strings can now be used for saving and loading MZMs in place of a file name, i.e. put "@$str" image_file... (Lancer-X) + Added ESCAPE_MENU counter. When set to 0, this counter will prevent pressing escape from opening the exit gameplay menu. This will not affect any other escape menus in MZX, and the exit gameplay menu can still be opened by other means, such as ALT+F4, CTRL+C, the window close button, etc. + Added EXIT_GAME function counter. When set to anything but 0, this will cause MegaZeux to exit to the title screen. This has no effect on the title screen. + Added the ternary operator (?:) to expressions. If the value to the left of ? is not equal to zero, the expression between the ? and the : will be evaluated. If the value to the left of ? is equal to zero, the expression to the right of : will be evaluated. + Added SAVE_COUNTERS and LOAD_COUNTERS special counters. These will save and load files containing every counter and string from the world they're used in, respectively. These files are not version checked, and may be used like save files. + Robots now keep their robot IDs after reloading saves. + Added standalone mode. The config parameters standalone_mode and no_titlescreen can now be used (from MZXRun only) to create standalone versions of MZX with the ability to fully customise the player's experience. See config.txt for details. (Lancer-X) + The minimal help bar now displays robot memory and the current board mod when contextually appropriate. + The minimal help options for the board and robot editors are now enabled by default. + Shaders can now be changed from the F2 menu when using the GLSL renderer. The user can select a fragment shader from the assets/shaders/extra/ directory. If a matching vertex shader exists, it will be loaded alongside the fragment shader. Otherwise, MZX will fall back to the default vertex shader. + On Linux and Mac OS X the configuration file will be copied into the user's home directory and given the name .megazeux-config if it is not already present. This config file will then be used instead of the global one. (Lancer-X) + Added unbound sprites. Sprites can be unbound from the grid by setting spr#_unbound to 1. Their coordinates will now refer to the sprite's location in pixels, not tiles. spr#_width, height, refx and refy still refer to chars; however, spr#_x, y, cx, cy, cwidth and cheight are all in pixels. Unbound sprites do not work with all renderers; currently, out of the renderers available on the PC platforms, the overlay2 renderer lacks this functionality. (Lancer-X) + Unbound sprites do not let char 32 or blank characters (when in ccheck 2) through like regular sprites do. Instead, set spr#_tcol to a color that will be transparent when the unbound sprite is drawn. (Lancer-X) + Unbound sprites can make use of additional hidden charsets. There are an additional 14 charsets beyond the default that can be modified through using load char set or char edit. (e.g. load char set "@256charset.chr") A sprite can be set to refer to these later chars with the spr#_offset counter. The offset value is then added to each char in the sprite. You can use this to refer to higher char sets. (e.g. set "spr0_offset" 256) Offset values can also be set to locations within a char set. (Lancer-X) + To allow you to access the extended charsets, the @ option to load char set now takes up to 4 digits, rather than merely 3. The + option still only allows 2 hex digits. (Lancer-X) + The colors used by tiles of a given color # in SMZX mode 3 can now be rebound using the "smzx_idx#,#" counters. (e.g. set "smzx_idx7,0" 32) Now if you put down a c07 tile, all 00 pixels will refer to color 32 (as opposed to color 0 in SMZX mode 2 or color 7 in SMZX mode 1). These values are reset whenever the SMZX mode is changed. Once again, this is only available to renderers that support unbound sprites. (Lancer-X) + Edited worlds now retain their world version until resaved. Before, they would lose their world version after testing. + Added world version display to the debug window. + Added GOOP_WALK counter for robots. + Added "Reset board on entry" parameter for boards. When set, the board will reset to its original state when the board is entered during gameplay. This setting can be saved as a board default. + Added "Load charset on entry" parameter for boards. When set, MegaZeux will load the selected charset file when the board is entered during gameplay. This setting can be saved as a board default. + Added "Load palette on entry" parameter for boards. When set, MegaZeux will load the selected palette file when the board is entered during gameplay. This setting can be saved as a board default. + Maximum robot size has been increased from 64kb to 2mb. (Lancer-X) + Debytecode: the LOAD_SOURCE_FILE special counter can now be used to load and compile a robot program from source code. This can be used with either a file or a string as input. + Debytecode: the robot editor's import robot menu now supports loading legacy source code. BUGFIXES + Fixed crash bug when using ALT+Z (Clear Board). + Fixed crash bug when attempting to view the help file in the updater. + Fixed crash bug when attempting to use SMZX_R/G/B with out-of- range indexes. + Fixed crash on exit when the config file did not explicitly specify update hosts. + Fixed memory leak involving bounds-breaking FREADn calls. + Fixed counter debugger issue where counters and strings starting with chars over 'Z' would cause everything in their section to be placed into the '#' list. + Dialog window labels can not be put into focus by clicking them with the mouse anymore. + Dialog windows closed by pressing escape will now close only on a new press instead of whenever the key is held. + Load (F4)/quickload (F10) on invalid save files in-game leaves the current game running instead of exiting to the titlescreen or editor. + Fixed issue where counter debugger would display wrong values for the robot LOCAL counters. + Fixed robot editor issue where global robot coords would be reloaded as 65535. + Fixed issue where board defaults would be reset after leaving testing until the world was manually reloaded. + Fixed issue where the Board Info dialog would not close when 'Cancel' was selected. + Fixed bug where chars 254 and 255 would not be reverted back to their defaults via F4/F5. + Fixed bug where player would move onto goop when walking into enemys on top of goop. + Fixed bug where 'enter' would be detected in loaded save files when loading from a title screen. + Fixed issue where MZX was using the world file version instead of the internal MZX version when saving MZMs and determining whether it could load MZMs both within the editor and in game. + Changed the caption behavior in the world editor as to refresh only when board values are synchronized. + Fixed bug where, when exiting gameplay, the world would keep running on the title screen if MegaZeux lost read access to the world file. + Fixed minor bug where trying to load a nonexistant mod would change MOD_NAME's output while the previous mod still played. + Fixed a Windows-only bug, where attempting to load a Robotic file in the Robot Editor or with LOAD_ROBOT would not load the entire file if the file contained 0x1A (char 26). + Fixed a bug where the lazer animation would fail to complete. + Fixed bug where the VOLUME # and MOD FADE # # inputs could go out of range, resulting in ear-piercing white noise. Inputs now wrap between 0 and 255 for compatibility reasons. + Fixed bug where certain unicode values could crash MZX in the character selection dialog. + Fixed bug where : "keyN" would not work on the Pandora. + Fixed a bug where FREAD could create a string larger than the maximum string size. + In the sprite section of the counter debugger, the spr_clistN values were incorrectly labelled as "spr_collisionN". Fixed. + Fixed counter debugger crash when selecting certain strings containing escaped values. + Added compatibility for the cycle-ending SHOOT, SHOOTMISSILE, SHOOTSEEKER, and SPITFIRE commands from MegaZeux 2.83. + Fixed crash bug when attempting to use file counters with paths equal to or longer than 512 chars in length. MegaZeux will now ignore such paths. + Fixed bug where MZX would crash with out-of-bounds joystick key mappings. + Fixed a bug where robots could not push the SliderNS type to the south. + Fixed a bug where a robot using #return or #top multiple times within a single command could cause a crash. + Fixed a port regression where IF ANY would continue to iterate over the board after finding a match, potentially triggering multiple subroutines, #return, or #top labels. + Fixed a bug where MZM error messages could repeat indefinitely and lock up MZX. + Fixed a bug where the (#)PUSHED label would not be sent to the first object in a row of pushed objects if that object was a robot. + Fixed support for PPC Linux builds. (Insidious) + Fixed a bug where a robot sent a subroutine would restart the command it was executing upon #return if the command was a multi-cycle command. This fix applies to worlds saved in 2.90 and later only. + Fixed a bug where ALT+F4 would cause menus to open instead of/ in addition to triggering an exit event. + Fixed a bug where subdirectory mods with different types of slashes in their names would fail to be recognized as the same mod. + Fixed a bug where SMZX palette intensities were not saved. + Made the opengl2 and glsl renderers endian-correct. (Lancer-X) + Fixed a bug where keystrokes were getting lost during event processing. (Lancer-X) + The UI now uses the regular MZX mode and the protected palette when playing SMZX games. This is only available to renderers that support unbound sprites. (Lancer-X) + Changing from SMZX mode 1 to 0 correctly restores the palette. (Lancer-X) + Fixed a bug where the tree list in the counter debugger would rapidly scroll through elements when clicked. + Fixed a bug where the updater, on failing to receive data from the server, would consume large amounts of CPU before timing out. (Lancer-X) + Fixed various bugs related to the pushing of sensors. (Lancer-X) + Fixed a bug where MZX would crash in some cases when testing after adding/importing new boards into a world. + Made KEY a board counter <=2.70. Also added masking <=2.62 to make Oath Demo work again. (Lancer-X) + Bullet types shot by robots clamped to 0-2. (Lancer-X) + SAVE_GAME and SAVE_WORLD now happen at the end of a cycle, not immediately. (Lancer-X) + SAVE_WORLD no longer exists. (Lancer-X) + Labels at the end of a program no longer get randomly sorted first and stop the actual first instance of that label being called. This fixes a bug in the Dark Corner 'Zane' demo. (Lancer-X) + Copy and copy block in pre-port MZX games now preserves the state of any robots copied. (Lancer-X) + Copying and pasting robot code with LF line endings on Windows now works. (Lancer-X) + MegaZeux can now be exited during an infinite loop. (Lancer-X) + Fixed a bug where SAVE_GAME on the first cycle of a board would cause the game to be faded out on load. This still affects legacy worlds. (Lancer-X) + Fixed a bug where trying to create new counters called "fread" or "fread_counter" in the counter debugger would cause the file being read to advance. + Fixed a bug where the numpad was unable to be used to control the player, despite being identical to the cursor keys for every other situation. (Lancer-X) + Fixed a bug where pre-port worlds could play any number of concurrent samples. This makes portions of Bernard the Bard quite cacophonous. (Lancer-X) + Fixed a bug where per-game config files could set options they weren't supposed to be able to. DEVELOPERS + Fixed linking bug when attempting to make a modular build of MegaZeux in Debian/armhf. -fPIC is now enabled for modular builds on all platforms. (Insidious, ajs) + Added SDL 2.0 support. At the moment, the overlay renderers are not accelerated by SDL 2.0 and may be slower than their SDL 1.2 counterparts. Other minor inconsistencies may exist between the two versions. (ajs) + Keycode help diagram replaced with an HTML file (from the older PNG file). This will make future updates much easier. + Updated NDS, Wii and PSP ports to latest devkitpro toolchains. + Updated libmodplug to version 0.8.9.0. (asiekierka) + Added experimental libxmp support. (asiekierka) + Added experimental libopenmpt support. (asiekierka) + New rendering architecture that mostly sits alongside the old rendering architecture. There is a new function implemented by supporting renderers: render_layer(). This provides a layer in a similar form to the text_video array in graphics and expects that to be drawn on the screen. This is called once for each layer that is drawn- this means the board, overlay, UI and sprites. Each layer can have a different SMZX mode, although at the moment this is only used to allow the UI to remain in regular MZX mode while the game or editor is in SMZX mode. The render_layer() function is only called if it is implemented by the renderer and if there is something on the screen that can only be drawn by the renderer (e.g. unbound sprites, or UI elements in an SMZX game) (Lancer-X) + LibSDL2 support is now the default. It can still be disabled by passing --disable-libsdl2 to config.sh. (Lancer-X) NEW in MegaZeux! New in Versions 2.92 to 2.92f New in Versions 2.84 to 2.84c New in Versions 2.82 to 2.83 New in Versions 2.81 to 2.81h New in Versions 2.80 to 2.80h New in Versions 2.60 to 2.70 New in Versions 2.01 to 2.60 New in Version 2.00 New in Versions Through 1.03 Table of Contents

New in Versions 2.84 to 2.84c

December 24, 2012 - MZX 2.84c Hey all, new version of MegaZeux here! And hopefully without any crashes this time around! Haha yeah right. The most notable thing this release (besides fixed crash bugs, as usual) is the new counter debugger! Give it a try and tell us what you think! Counter binary search has been replaced with a hash table in versions of MegaZeux for most platforms. This has resulted in slightly faster counter lookups, and MUCH faster creation of counters, since MegaZeux doesn't have to keep the list ordered. The hash table is turned off for NDS builds for now due to tight memory constraints. Otherwise, most of the new features are editor enhancements and modifications. Notable mentions are reordering the board list with 'M' and a custom undo history size. FEATURES + The functionality of the F11 counter/string debugger has been expanded to include sprites, robots, and miscellaneous world and board variables. The ability to modify many of these vars is limited and a large portion are read-only. In addition, you may add new counters and strings, hide empty counters/strings (does not affect built-in variables), and search by name and contents. Export is still limited to counters and strings. + Max string length has been increased from 1MiB (1048576 bytes) to 4MiB (4194304 bytes). + Board mods may now be selected from subdirectories of the game folder in the ALT+N dialog. + The title bar now displays the world and editing board/robot names based on context. + Fire Burns Space and Fire Burns Forever are off by default. + You may now specify the size of the undo history in the char editor, and the history affects the entire char set. Undo is still ALT+U, redo is now ALT+R. + You may now use the -/+ keys in the world editor to move to the previous/next boards in the board list, and Shift+Arrows to change to the boards linked by board edge. + You may now move the current board anywhere in the board list with M. You may not move the title screen board. + View mode in the board editor (V) will start from the current location of the screen now rather than at the top-left corner. + Config file options for default board settings added, as well as the ability to save these per-world from the editor. + Ctrl+G - Goto board position at X,Y. + png2smzx now requires less arguments and has an option to skip a char (generally char 32 will be useful to skip). + Debytecode: The robotic editor now asks for a confirmation to save the program on exit. BUGFIXES + Fixed a bug in the 'glsl' renderer that caused the cursor color to be ignored (always white). This caused the cursor to not be visible if shown on a white background. (ajs) + Setting $string.length will not cause memory corruption now. In addition, its pre-2.84 behavior of intentionally allocating the string past the set length has been restored, but the length itself will still be set to the correct value. + Added bounds check to INC "$string" "value". Attempts to increase a string past its maximum length (4 MiB, or 4194304 bytes) will now fail. + Fixed MegaZeux crash that could sometimes occur when a string was increased by itself. + Fixed MegaZeux crash that could occur when exiting the editor to a world file that failed validation. + Rolled string->storage_space into string->name to prevent buffer overflow errors and crashes. (Mr_Alert) + Fixed crash that would occur when attempting to type in a dir in the ALT+N dialog. + Fixed a bug where copy block $string would apply REL twice. + Thanatos Insignia (DoZ Q1 2011, 98485) will now play without freezing both normally AND after loading a save. Robots will not be incorrectly versioned with the save format magic now. + Fixed bug where ALT+M wouldn't always edit non-stored types. + Fixed bug where ! could not be used as a substitute for ~. + Fixed a bug where tab-draw and block actions would carry between board and overlay editing. ALT+O now sets the drawing mode back to normal on a switch. + ALT+M now edits the overlay instead of the board while editing the overlay. + Quick-load (F10 during gameplay) will not work if the load menu (F4) has been disabled with the LOAD_MENU counter. + Fixed a bug where the listening mod directory would stay the same as the directory the editor was opened in. + The listening mod now continues to play after world and board changes, and also after the board mod has been changed by ALT+N or Shift+8/*. + LOAD_GAME will not incorrectly trigger JUSTENTERED anymore. + Palette/intensity changes made on the same cycle as a teleport player command are now properly taken into account. This fixes a game-stopping regression in Sponkgo's Legendary Journey where leaving the second stage's bonus area would leave the color intensity at 0. + SMZX mode is now disabled when leaving the editor if it was enabled in the editor via F11. + Fixed potential crash bug where robot bytecode files were not being validated before being loaded with LOAD_BC. + Fixed minor message box bug dating back to DOS where a message box starting with an unavailable option would begin with the cursor on a blank line. + Fixed crash that happened when typing over bounds while renaming a file in a file manager dialog. File and directory renaming now use a popup dialog akin to ALT+N. + Files with names longer than 55 chars may now be selected in file managers. The limit for typing in a file name is still 55 chars. You may not enter a blank line as a file name anymore. + Fixed segfault when attempting to read THIS_COLOR for the global robot. It will now always return -1. DEVELOPERS + Overhauled txt2hlp. Error messages now differentiate between hyperlinks and labels and will take the display chars ~ and & into account. Eventually, the goal should be to get rid of txt2hlp altogether and have MZX load straight from the .txt file. + Added compile option to use uthash for counter/string lookups as opposed to binary search. Ideally, this will vastly improve lookup speeds for large numbers of counters/strings, but will consume more memory. (thanks to Lancer-X for the modified uthash header file) Table of Contents June 20, 2012 - MZX 2.84b Less than three weeks after the last one, MegaZeux 2.84b is here a few weeks early to fix a key regression regarding the use of REL commands with the COPY x y dx dy command. While several new features have been added, this release was mostly about rooting out as many crash bugs from MegaZeux as possible. An official public beta release of debytecode has been pushed off once again due to time constraints. Most notable as far as new features go, pressing 'E' while a game's title screen is running will now take you directly to that world in the editor. A blank new world may still be created with 'F8', and now with the 'N' key. The function key corresponding to the new 'E' functionality is 'F9'. A major new aspect of this version, which could be seen as a bugfix or as a new feature, is MegaZeux's ability to validate the MZX, MZB, MZM, and SAV file formats. Validation has been rigorously tested and refined, and a comprehensive list of most world files that fail any check is available on the MZX Wiki. File load crashes and force-quit "Out of memory" errors in these instances are nearly a thing of the past. One final major change regards the file manager dialogs (Load / Save Game, etc). These dialogs have been internally overhauled to avoid permanent directory changes unless a valid world or save file has been loaded. If any bugs are experienced using these, they should be reported to the MZX Bug Tracker. FEATURES + Pressing 'E' or 'F9' on a title screen will now open the current world for editing. Press 'N' or 'F8' to create a new world. + Multiple hosts may now be defined in config.txt. Update attempts will be carried out in the order they are defined. + A startup path may be defined in config.txt ("startup_path"). + Specifying the backup filename with a directory, ex. "backup/file", will now silently attempt to create the directory if it does not exist. + MZM3 is now forward compatible (robots will be dummied out). BUGFIXES + World validation has been strengthened, preventing disasterous loads of most non-world files. Mostly intact/valid worlds, such as HUNTDRAK.MZX, can be loaded -- corrupt/missing boards will be replaced with blank boards, corrupt robots will be replaced by robots with empty programs, and so on. If more robots/scrolls/signs are found on a board than their data suggests there should be, the extras will be replaced with customblocks. Back up the version of the world with errors in this instance, as the robots' code or scroll text may still be salvageable from the world data. + Fixed a long-standing memory corruption bug in the shoot command introduced by the port. + Mac OS X: MegaZeux now uses /Users/[username] as the default starting directory. Apps previously would always start at the filesystem root. (ajs) + Fixed dangerous crash-causing bug where the editor would not chdir back to the correct directory after testing. + MegaZeux, after saving a world to a new directory, now chdirs to the new current world file's directory. + Changed behavior where a failed save file load would fade the still-running world out of focus. MegaZeux now leaves the world in focus. + All failed world/save loads leave the current world running and in the same working directory. + When startup_file is defined as a directory at the command line, MZX chdirs to the directory instead of attempting to open it as a world file. In the config file, the directory is pruned off since there's a new config option for the startup path. + Fixed regression where the rel commands would be ignored for board to board copy x y dx dy. + Updated MZX_SPEED in the counter debugger, where it was still getting clamped from 1 to 9. + COLOR FADE IN and COLOR FADE OUT (and all built-in uses of them) now correctly respect any COLOR INTENSITY changes made before they are used. + In file selection dialogs, when attempting to make a directory that already exists with ALT+N, MZX now shows the correct file name and does not force the user to quit MegaZeux. + In file selection dialogs, when pressing ALT+D with a directory selected, MZX now correctly prompts to delete the selected directory instead of a file. + The option to import world files in the board editor now correctly takes the world version into account. + Savegame MZMs loaded into the editor now have their robots dummied out for safety purposes. + Fixed bug where INPUT STRING would not terminate lines longer than 71 chars after clipping them. + INPUT STRING and ASK do not allow either tabs (INPUT only) or line breaks (both) anymore. + Fixed bug where putting a scroll/sign in the editor buffer and then selecting something else could cause a crash on leaving the editor. + Temporary fix for MSVC bug where all window dialogs would freeze. (MZXGiant) + Temporary fix: board block actions will not corrupt robot source code in DBC anymore. (MZXGiant) DEVELOPERS + Switched debian prereq. and darwin libpng12 to libpng, switched darwin and default ldflags to use '--ldflags' instead of '--libs'. + Darwin CC/CXX compiler can now be specified on the command line. (ajs) + Cleaned up broken ifeq structure in darwin Makefile.in so ARCHes other than i686 can be built. + Updated MSVC dirent.h to the latest version (MZXGiant) + Added updated MSVC dependencies. (MZXGiant) Table of Contents June 01, 2012 - MZX 2.84 The first version of MegaZeux to be released in two and a half years, this time with a vast number of bugfixes, several new features, and hopefully no new bugs. There's a new port to the Pandora platform from Exophase. There are no binaries for this platform yet, as ajs has not had time to set up the cross-compiler. Same goes for Android. Another major (internal) change this time around is that Exophase's experimental "debytecode" language modification has been merged. This still has some major bugs open against it, and missing features, so I won't be doing official releases yet. You can add support for this feature by passing "--enable-debytecode" to config.sh on all platforms. Thanks to Terryn, Exophase and MZXGiant for their contributions and to Lancer-X, Old-Sckool and Lachesis who reported and tracked the majority of bugs this time round. FEATURES + Added experimental port to Pandora. See arch/pandora/README for more information. (Exophase) + Directories may now be opened with FREAD_OPEN. This functionality can be used in conjunction with FREAD_POS and SET "$str" FREAD. FREAD will set the string to "" when it has reached the end of the file listing. + MZX_SPEED can now be set up to 16 by a robot or from the F2 dialog menu. (Lachesis) + Numbers can now be temporarily backspaced past their minimum value to make typing a new number more intuitive in dialogs. (Lachesis) + Chars 0 and 255 can now be selected from the Edit Chars submenu of the Global Info menu. Using char 255 on a kind that would have previously denied it now gives a warning dialog. (Lachesis) + New Counter: SPACELOCK represents the default space functionality for the built-in player. Setting this counter to 0 disables it, allowing the player to move as normal when space is pressed. Setting it back to 1 enables it again. Defaults to 1. (Lachesis) + New Counter: FREAD_DELIMITER allows you to change the terminating char for the string FREAD function. The terminating char still defaults to '*'. A complementary FWRITE_DELIMITER function has been added as well. (Lachesis) + New Counter: ARCTANdy,dx takes two values and returns the angle with corrected quadrants as an alternative to using ATANdy with DIVIDER as dx, which was less intuitive and never documented properly. (Lachesis) + New Counters: MINv1,v2 and MAXv1,v2 return the minimum or maximum value between two inputs, respectively. Chain several of these in an expression or a loop for more arguments. (Lachesis) + New Counters: bchX,Y; bcoX,Y; bidX,Y; and bprX,Y are new shorthand access counters for BOARD_CHAR, BOARD_COLOR, BOARD_ID, and BOARD_PARAM. The same limitations to those counters apply to the new ones. (Lachesis) + New Counters: uchX,Y; ucoX,Y; uidX,Y; and uprX,Y are new shorthand access counters for the board's under layer. The same limitations apply to these as to their board counterparts. Additionally, these counters will fail if the same spot on the normal board is occupied by a floor-type (space, [dir]water, lava, fake, etc...). (Lachesis) + New Counters: ochX,Y and ocoX,Y are new shorthand access counters for the overlay. Like OVERLAY_CHAR and OVERLAY_COLOR, these are read-only to discourage the user from writing to these instead of using the much faster PUT [color] [char] OVERLAY [x] [y]. (Lachesis) + Pressing ALT+G from the world editor now goes directly to the Global Robot without having to skip through the Global Info menu. (Lachesis) + MZM3 has been enabled for 2.84 and all following versions. The difference between MZM3 and MZM2 is that MZM3 stores a copy of the world version, allowing the robot format to change. (Lachesis) + COPY can now take + and # prefixes to its arguments. COPY BLOCK and COPY OVERLAY BLOCK can now take + prefixes to their first set of coordinates. (Lachesis) + Subroutine versions of TOUCH, BOMBED, INVINCO, PUSHED, PLAYERSHOT, NEUTRALSHOT, ENEMYSHOT, SHOT, PLAYERHIT, LAZER, SPITFIRE, GOOPTOUCHED, PLAYERHURT, KEY[char], KEYENTER, THUD, and EDGE have been added. These should ALWAYS be used in conjunction with LOCKSELF/ZAP and #RETURN or #TOP to keep the robot stack under control. Please remember that THUD and EDGE ignore LOCKSELF and their subroutine versions must be ZAPped. JUSTENTERED, JUSTLOADED, and the sensor labels have been excluded from this due to various reasons. (Lachesis) BUGFIXES + Fixed a bug where LOAD_ROBOT or LOAD_BC would not reset the stack pointer for newly loaded programs. This could cause crashes if a robot popped the stack in the new program. + Fixed a bug where range checking of BOARD_X and BOARD_Y would sometimes not be done correctly, leading to crashes. + Strings in the debug menu list no longer interpret any color codes they may contain. + Fixed a bug where a string would not be interpreted correctly if it used a '.' character in a splice parameter expression. Expressions such as IF "$str#('$str2.length'-4)" = "blah" THEN "label" will now work correctly. + Fixed negative sprN_cheight et al from crashing. (Exophase) + Placement of objects on the player will be blocked with an error dialog like DOS versions, instead of silently failing after setup. (MZXGiant) + Fixed a bug where LOAD_ROBOT would not properly parse lines of imported code that had leading whitespace. (MZXGiant) + Fixed an integer wrapping bug in debytecode, disallowed numeric literals outside of the bounds of a signed short. (MZXGiant) + Fixed a bug that would corrupt the UI palette if "set color" was run against a color index over 15. (MZXGiant) + If either board dimension is less than the editor viewport, the character and colors used to indicate space outside of the board are taken from protected sets. In game, they are taken from the game's sets. + Increase limit on difference for RANDOM "A" TO "B" to UINT_MAX rather than INT_MAX - 1 as it was previously. Since the entire range represented by a counter is now usable, there are no cases where RANDOM will "break". + Fixed avalanche rings and potions to limit boulder placement to 1/18, matching the AVALANCHE command. + Fixed corruption and possible crashes when using VIEWPORT SIZE to set the viewport to a size less than 80x25 but greater than the current board dimensions. The viewport will now always be clamped to board size. + Fixed incorrectly changing horizontal mouse position on setting MOUSEY. (Mr_Alert) + Fixed overflow into protected character set when "Revert to..." is selected in the character editing dialog. (MZXGiant) + Music and SFX now mute when the updater launches and are restored when it is complete. (MZXGiant) + Fixed odd string behaviour when copying between strings that happen to be stored close to each other in memory. This fixes a regression introduced by the "crash when pasting to and from the same string" fix in 2.82b. + The size/offset parameters for strings can now be specified in either order (#+ vs +#) and will behave correctly. + Reverted bogus cycle-ending behaviour for SHOOT, SHOOTMISSILE, SHOOTSEEKER and SPITFIRE. + Improved cycle-ending compatibility with MZX versions prior to 2.80. Fixes games such as Kya's Sword and Stones & Roks II. + Restored shark's ability to move in goop. + MZX now clears SPR_YORDER upon loading a new world. + When transitioning between boards, MZX now compares the module filenames of the source and destination boards case-insensitively. A difference in case will no longer cause the board module to be incorrectly restarted. + Fixed rare rendering corruption in the load game dialog. + Fixed a bug where SEND "robot" TO "#return" could corrupt the program counter of the target robot if it had a stack pointer of zero. + Fixed some security issues with SMZX_PALETTE and LOAD_BC counters. + MZX now only lists/opens regular files or symlinks to regular files in file dialogs. Special files are now ignored. + Opening directories with FWRITE_OPEN is now rejected properly on all platforms. + Fixed a bug where a file would be re-opened for read/write, even if the file was missing or an I/O error occurred before saving. + Fixed a bug where MZX could occasionally crash due to label list corruption when copying robots from heap locations greater than 2^32 bytes apart (only affected 64bit builds). + Stopped SET "var" <command> from assembling. Some invalid uses of command tokens were already being ignored, but this was just luck. + Sprites with color c?? (inherited "natural" colors) will correctly inherit the colors of special characters such as the player and other self-colored built-ins. + Debytecode's legacy expression converter should use is_string() instead of its own (buggy) hand-rolled version. Fixes crash when converting CoAZ. + The editor no longer incorrectly clamps the intelligence of sharks, spitting tigers and spiders to <=4, and no longer clamps the HP of dragons to <=4. (Lancer-X) + MZX now accepts SET EDGE COLOR "string" in addition to SET EDGE COLOR c??. + Fixed NDS port initialization on DSi devices. (asiekierka) + Fixed a bug in the joystick code where centering an axis clears the previous axis button. (iamgreaser) + Fixed a bug that allowed vlayer->board COPY BLOCK to overwrite the player. Blocks that would overwrite the player are now ignored. + Fixed a 2.81e regression that allowed SENDs to self to ignore LOCKSELF. + Setting $str.length now makes $str the length specified. (Lachesis) + Caps Lock no longer interferes with dialog box text input. (Lachesis) + Increasing the size of a string with $str.length, $str.N, or with a splice now wipes old string data with char 32s. + Dialogs (especially "Exit gameplay - Are you sure?") now require the user to have actually hit ESC to close, making escaping busyloops and message loops much easier. (Lachesis) + Added a compatibility fix for different label caching in 2.80 through 2.83 that allowed constructs such as : "LABEL" / SEND "ALL" "LABEL" on an unlocked robot to continue instead of getting caught in a loop. The altered label caching caused #98485 Thanatos Insignia to lock up in an unescapable busyloop in GIT versions. (Lachesis) + MOD "[lead-in file]*" now works properly. In previous versions of the port, this construct would result in the lead-in file failing to play and the wildcard mod restarting when the player re-entered and re-exited the board. (Lachesis) + Fixed a bug where mod "*" would cause the mod to restart when entering another board with the same playing mod. (Lachesis) + ALT+D (Default palette) now requires a confirmation. (Lachesis) + The COMMANDS counter is now saved as a 32-bit variable. (Lachesis) + The LOOPCOUNT counter has been moved to save-only data and is now saved as a 32-bit variable. (Lachesis) + Fixed a bug where not all whirlpools were being considered as such, notably during the transport board scan. (Lachesis) + The abilities of PLAY "&file&" to play at multiple frequencies and to parse multiple files have been restored. (Lachesis) + As of MZX 2.84, BOARD_COLOR will now ignore the under color of any object with a BG color of 0 that is on top of something. Worlds that relied on this between 2.80 and 2.83 are unaffected. (Lachesis) + Setting BIMESG to 0 will now disable Game Over's auto-centering of the message row. (Lachesis) + The DIVIDER counter's documentation has been updated to explain its true purpose. + Fixed an editor bug where canceling a world load could cause MZX to forget the filename of the current world. (Lachesis) + Pressing ALT+M in the world editor now edits anything with parameters, not just Robots, Signs/Scrolls, and Sensors. DEVELOPERS + Source tarballs are now generated in XZ (LZMA2) format. + Make hlp2txt utility work correctly on Windows platforms. + Updated and repaired MSVC project for Visual Studio 2010. (MZXGiant) + Win32 binaries are built ASLR-capable (via pefix). + Version control was changed from SVN to Git; the repo is at: http://github.com/ajs1984/megazeux + The EGL backend now supports Mesa's EGL implementation on X11. + Imported libmodplug 0.8.8.4 and rebased all patches. + Introduced SOCKS4/4a/5 support transparently into the network layer. (MZXGiant) NEW in MegaZeux! New in Versions 2.92 to 2.92f New in Versions 2.90 to 2.91j New in Versions 2.82 to 2.83 New in Versions 2.81 to 2.81h New in Versions 2.80 to 2.80h New in Versions 2.60 to 2.70 New in Versions 2.01 to 2.60 New in Version 2.00 New in Versions Through 1.03 Table of Contents

New in Versions 2.82 to 2.83

December 29, 2009 - MZX 2.83 It's been a year since the last release, due in part to my reduced free time, and less contribution from other developers in 2009. I'd also like to believe that 2.82b was such a good release, there was no need to rush. There's over 30 bugs fixed this time. A few features I had to withhold for 2.82b have been added; sample loop markers and some changes to the board file format necessitated the bump to 2.83. Logicow's GLSL renderer has finally made it in (various bits had to be re-written to extend portability to other platforms). There's a new (semi-complete) Android port this time; I hope to complete it, and provide binaries for Android 2.0 phones, in 2.83b. Thanks go out to the usual suspects -- Terryn, Mr_Alert, Logicow, kvance, Lancer-X, revvy and Exophase -- for supporting development this year. USERS + Added support for loop markers in WAV and OGG files. The WAV loop support uses the "smpl" chunk used by ModPlug Tracker and Wavosaur among others. Only the first loop is used, and only forward looping is supported. The OGG loop support uses the "LOOPSTART" and "LOOPLENGTH" tags as used by RPG Maker VX. (Mr_Alert) + Added OpenGL Shader Language (glsl) renderer which uses shaders to render and scale the video. This renderer is compatible with Open GL >=2.0 and Open GL-ES 2.0 video cards only. A variety of shader programs have been provided and these can be customized. Performance of all MZX modes (including SMZX) is excellent. (Logicow, ajs) + Files will no longer be silently overwritten by save dialogs if the user enters an existing filename without the default extension. (revvy) + The string editor in the counter debug menu (F11) now escapes newlines and backslashes to prevent UI corruption. + Fixed a bug where the LOAD_GAME counter handler could continue to use the old board state after load, causing crashes. (Lancer-X) + Fixed a bug where status counters containing numbers >6 characters would cause MegaZeux to crash or behave strangely. + Fixed a bug in the robot editor's find/replace function that caused crashes when replacing a string with another longer string, with a replacement at the end of a line. + Programmatically writing to a read-only "built-in" counter will no longer allocate it general heap space. This prevents writes from showing up in the F11 counter debugger that are inaccessible from robotic. + Fixed a bug that caused the SMZX mode 3 palette to become corrupted upon entering the char editor (the editor would re-write colours 2-4 and not restore them from backup correctly). + Fixed a bug where a robot program would never progress if the subroutine stack was popped more times than it was pushed (via return or top). + On UNIX platforms a desktop/menu entry is now installed by default, using the existing icon. (Sci-freak) + Clamp score to >= 0 if world <= 2.70. Fixes "Gates: The Puzzles" and possibly other old titles depending on this behavior. (Exophase) + Fullscreen modes will now automatically use your current desktop resolution if using any hardware renderer (i.e. not the default software renderer). To get the old behaviour back you must set fullscreen_resolution explicitly. + Fixed a bug where web and thick web would be treated the same. + Fixed a bug in the updater where modified/replaced files would be considered for deletion. + Fixed a bug on case-sensitive filesystems where saving a game, world or MZM could fail to overwrite any existing file by the same name (if matched case insensitively). + MZX no longer applies masking to chars 32-127 in signs or scrolls when playing a world. Previously, even the mask_midchars option would have no effect on the display of signs or scrolls. This has been broken since 2.80g. + Re-worked board editor's Alt+H option to provide minimal editor (one row) status info, rather than completely hiding the help. + The checkres utility now checks the global robot for missing resources too. + Chests can be added with Hi Bombs (omission noted by zzo38). + Fix IF c?? Sprite p?? # # "label" so that a non-wildcard parameter is respected (previously it would always just check sprite 0). + NDS port updated from dsmzx2 release. (kvance, ajs) + Updated SDL to 1.2.14 in Windows x86, Windows x64 and Mac OS X builds. + Security checks are no longer applied to filenames in module or sample playback in "listening only" modes in the editor. + Module volume is applied immediately before playback upon switching boards. This prevents one cycle of audio "leaking" at the wrong volume. + Prevent crash with negative string clip where clip + offset = 0. Clip is now correctly limited to total string length. + Help file is now optional for MZXRun, even with CONFIG_HELPSYS=1 builds. + Fixed crash when robot editor macros expanded other macros. + The lock icon is no longer missing from the Items THING menu (F4). + A world to start up with can now be passed to MegaZeux without the startup_file= prefix. This makes megazeux consistent with other applications. + SHOOT, SHOOTMISSILE, SHOOTSEEKER and SPITFIRE now end the cycle, to restore compatibility with pre-port MZX and fix games such as Kya's Sword and Stones & Roks II. + Have IF [dir] PLAYER [color] [thing] [param] "label" interpret SEEK direction wrt robot coordinates, rather than player coordinates. Other directions are not affected. + Zapping a label at the end of a robot program will no longer corrupt the robot list (which usually caused crashes). + Entering lines in the robot editor with leading or trailing spaces will be trimmed before the line is compiled. + The single quote characters encasing S_CHARACTER parameters in the robot editor will now use the protected (GUI) charset rather than the game one. + Added a "system_mouse" config.txt option that allows the mouse cursor to be replaced with the system mouse cursor, rather than being drawn by MegaZeux. + Disallowed placing player clones with SET "board_id" 127. + Relaxed file name limit on board MOD file. The board MOD can now be as long as the limit imposed by file dialog's input box (previously limited to 12 characters). + Truncation of currently open input/output file names will now only occur at MAX_PATH bytes (typically 512 characters). The previous limit was 13 characters. + Relaxed limit of INPUT string and bottom ("*") messages from 80 characters to ROBOT_MAX_TR (512) characters. In the case of bottom messages this can be usefully exploited to ~200 characters. + Progress meter will be shown for world decrypt on console platforms. + Fixed a bug where a malformatted BMP header would be written (length too short, didn't include dummy channel in BMP palette). (Mr_Alert) + Optimized audio locking; do file I/O outside of critical sections to decrease stalling, particularly on platforms with slow I/O. (Mr_Alert) + Added support for MacOS 10.6 (Snow Leopard) and removed support for 10.3. + Loading a save game from robotic will now correctly restore intensities to their saved values. + Copy/pasting a block either with COPY BLOCK or the editor, where the copy would exceed the limit on robots/signs/scrolls /sensors, will no longer place junk at the target co-ordinates. Instead, the object's background will be copied in isolation. + Pasting from the clipboard, expanding a macro, or importing .txt or .bc files that would cause a robot to exceed the 64k limit now has the operation ignored at the point it exceeds the limit, rather than adding an unlimited number of unrecognized lines. DEVELOPERS + MZXRun compilation can now be disabled. Compilation of pre-2.82b style non-modular builds requires `--disable-modular --disable-mzxrun'. + Disabling SDL can now be done with --disable-sdl and the resulting configuration will automatically disable any SDL-dependent components. This is useless to anybody except developers doing new ports. + Game directory, utility directory and resource directories can now be specified and will be respected on "make install". (Sci-freak, ajs) + Added experimental port to Android. See arch/android/README for more information. + Ported opengl1 and opengl2 renderers to OpenGL ES 1.x and glsl renderer to OpenGL ES 2.0, used increasingly by mobile devices. + Removed SDL dependency from NDS port. It only used it for timing and stuffed events. + On Windows platforms, binaries are processed with the `pefix' in-tree tool to eliminate data section differences in programs with identical texts. This minimizes the amount of content required to be sent for updates. + Updated Wii port: improved audio and video support, added USB mouse support, numerous optimizations and improved file selector. (Mr_Alert) Table of Contents December 29, 2008 - MZX 2.82b This release contains plenty of important bug fixes, ranging from regressions such as the broken command-line editor macro expansion to third party bugs like the Windows "directx" SDL video driver breakage. There are also some new ports and features. MegaZeux now runs on the Wii (port by Mr_Alert) and AmigaOS 4.x (port by myself and Spot from os4depot). The Windows x64 port has matured immensely and can now be considered stable. MacOS X builds now have clipboard support. The hardware stretching renderers now have a couple of fixed aspect ratio modes. The biggest feature of this release is the introduction of a portable network layer, which is currently being tested by the new built-in updater (F7/U). Internally, MegaZeux is now modularized and builds as several DLL and EXE files, which should make redesigning parts like the help system and editor a little easier, as well as allowing us to ship a "mzxrun" executable for the first time since 2.69c. This "mzxrun" executable is now used by a majority of the console ports. Contributions from Revvy, Mr_Alert, Terryn and Exophase have helped make this another solid release. USERS + Writing to $str.length (which previously did undefined things) will now truncate or enlarge the string to the size specified. + Removed filename size limit for FWRITE_MODIFY and FWRITE_APPEND. (Revvy) + Added support to the checkres tool to check worlds in non-local directories. (Revvy) + Fixed an old bug with saving games and worlds from Robotic where a board could be prematurely "optimized", renumbering robot IDs within the same cycle. For commands like DIE this could cause unpredictable behaviour or simply crashes (if invoked in the same cycle). As a special case, end the cycle if either of these SET specials are used. + Mistaken or malicious file I/O such as set "$test" to "fread(-1>>1)" will no longer crash MegaZeux. The read size will be truncated to a contextual maximum for the current file. + Fixed a crash using "fwrite0" in conjunction with an empty string. + Fixed a bug where checking sprite_collisions on a disabled target sprite would unconditionally trigger (regardless of whether a collision was present or not). + Un-grouped the handling of the KEY and KEYn counters so that different compatibility checks can be applied to either counter. Fixes "Bocco Chronicles 1" and probably several other titles. + Fixed a crash when using RIDn or ROBOT_ID_n in the same cycle as DIE for another robot positioned earlier in the board scan. + Fixed poor sanity checks on BOARD_ID counter writes. Illegal character IDs such as -1 can no longer be used to bypass the check (causing subsequent crashes). + Windows builds now use a patched version of SDL 1.2.13 containing a fix for the directx+F10 issue. + Fixed a bug where one robot could send another robot to "#return", with an address outside its program. In such cases, the robot will now terminate. + An "mzxrun" binary is now shipped alongside the editor-capable MZX binary. + Fixed TIME/TIMERESET overflows with very large values. Board timeout is now programmatically limited to 32767, which is consistent with the Board Info control. + Clamped CHAR_X/CHAR_Y properly so that negative numbers can no longer be used to corrupt the editor charset and potentially other process memory. + Fixed recent breakage of SHIFT+F{1,2,3,4} so that the percentage of time spent displaying the original character and the '!' are equal. + Removed some bogus handling of lines containing "only" ';', ',' or ' '. + Honor user's robot character selection if they are holding shift when pressing return or space (would previously always return char 247). + Backspacing a line and then expanding a macro no longer restores the original line contents immediately after the expansion. + MacOS 10.x clipboard support (via Cocoa Pasteboard). Alt+Ins can be entered with Fn+Alt+Numpad0 on a Macbook or Powerbook keyboard. + Robot editor S_CHARACTER fields no longer bogusly escape characters such as ". In addition, rendering glitches are no longer encountered when using the ' S_CHARACTER (which is completely reasonable). + Fixed robot editor glitches where the game charset SPACE would be used in places where the protected UI charset should be used instead. + The introductory help message is displayed if the load dialog is cancelled prior to loading a game. Hopefully the screen is now never totally blank. + The F7/F8 cheats can now be used freely in MZXRun (in MegaZeux proper they remain usable only in editor tests). + Saving to a directory above the MegaZeux startup directory, then attempting to save to this location again, will no longer crash MegaZeux. Instead, the parent directory will be changed into before the dialog is displayed. + Fixed numerous crash bugs with the scroll editor; it should be relatively usable now. + Writing to $str+0 is no longer interpreted in the same way as a plain write to $str. Instead, it behaves like writes to non-zero offsets (as more of a paste than a replace). + Display of current X,Y position of robot in the robot editor status bar. + Fixed directory rename so that it no longer displays garbage and/or crashes MegaZeux (Alt+R to rename a directory in any file picker). + In the robot editor, lines can now be split at a midpoint with enter and two consecutive lines merged together with backspace. (Exophase) + Fixed use of status counter 6 and display of status counters in general, which has been broken since 2.80. + Fixed swapping to encrypted worlds if initially the user decides to not decrypt the world. Previously, this would either crash, or loop forever. + When using the OpenGL or overlay renderers, in either windowed or fullscreen mode, the aspect ratio can now be preserved as either 4:3 (most similar to DOS) or 64:35 (most similar to the port). The display will be letterboxed or margins applied as appropriate. See the "video_ratio" configuration option for more information. + Fixed a bug on some systems where numlock could not be used as a key, only as a flag. The numlock "key" is now masked out of "key_code" and similar; hopefully this won't break any games. + Restored the meter widget from the old DOS MZX for use with the world loader and saver routines. This reassures users, especially on consoles, where loading a world can take a long time. (Mr_Alert) + On Windows, directx.bat now passes %cd% through to `start' so that features such as the updater continue to work. (MZXGiant) + Pasting into a string with set "$str+N" with an N > str.length will no longer crash MZX. + "Exit to DOS" is now "Exit MegaZeux" to reflect the multi-platform nature of the program. + Setting a substring size to zero with $string#0 will no longer return the whole string; it will instead return the empty string. + Accessing a substring with an offset >= $string.length will no longer return the last character from the string; it will instead return the empty string. + Writing beyond MAX_STRING_LEN (1MB) or using negative offsets (which has the same effect) no longer crashes. Instead, the write is ignored. + Fixed crash when pasting to and from the same string, specifically in conjunction with $str+offset. - Removed the legacy "force_resolution" option which was replaced long ago by the more accurate "fullscreen_resolution" option. DEVELOPERS + Ported to OpenSolaris. You need to install `SUNWxorg-headers' if you want X11 clipboard support. + Removed dependency on SDL_image on non-win32 platforms when enabling the icon branding feature (see pngops.c). + Ported to AmigaOS. You need to install the clib2 version of libSDL and miniGL, and the build system assumes you are using a cross compiler. + Added experimental port to the Wii. See arch/wii/README for more information. (Mr_Alert) + get_path() in util.c now returns <0 for failure, or the length of the path for the given file. (Revvy) + Added the make time WHOLE_PROGRAM=1 flag which enables compilation of the core binary in GCC's "-fwhole-program --combine" mode. This makes all symbols static and improves optimization, somewhat like MSVC's LTO does. + Added a valgrind.supp file to suppress bugs in third party libraries when valgrinding MegaZeux. + Cleaned up all the ports and documented making new ports. The platforms "linux", "solaris" and "obsd" are now called "unix", and the "linux-static" platform is now "unix-devel" and available on all UNIX derivatives/clones. + Added a special hack to enable linking with --as-needed for DT_NEEDED link optimization for GNU ld platforms. + Updated MSVC projects. Fixed all warnings emitted by MSVC 2008, and implemented icon support with existing mingw resource files. + Now uses the GNU ld "debuglink" feature on all platforms to enable shipping of a side-by-side symbol package. Optimized release builds can now be debugged with minimal user effort. + MegaZeux now provides the option for "modular" linkage, factoring out the "core", "editor" and "network" features to shared objects that other binaries can link against. This feature works on the unix, mingw, amiga and darwin ports. + Added RPM .spec file. Capable of building (at least) Fedora 10 RPMs. - Removed HOST_CC feature for cross compilation; since the utilities now intimately depend on the MZX runtime, they must be built with the same compiler. Table of Contents June 10, 2008 - MZX 2.82 Despite the increase in minor version, this release mostly targets bug and regression fixes. However, there ARE some additional new features, such as the introduction of the LOAD_MENU and mouse pixel counters, and refinement of the {FREAD,FWRITE}_COUNTER counters. (There are several other smaller features that are documented in the changelog.) SAVs from older worlds (requiring compatibility hacks) no longer fail to play (Darkness, etc. are affected). We've also done a good bit to fix compatibility with 2.70 and older. A new tool, "checkres", is now routinely packaged, allowing you to check your games for missing resource files (PALs, CHRs, etc.) before passing them on to other people. This should be especially handy for DoZ game submissions. The Nintendo DS port (Kevin Vance's "DsMZX") has been merged into this release. I'll provide binaries for GP2X, PSP and NDS this time, but I can't guarantee they'll work. Both of the snags from the last DoZ have been addressed -- the help system should no longer crash and the Block Action crashes should be reduced in frequency. However, there are still issues with pasting in the robot editor that remain unfixed (they're just really hard to reproduce). With your bug reports, I look forward to fixing this. As usual, thanks go out to Revvy and Mr_Alert for their contributions to the bug-fixing effort, and to Terryn for his unwavering dedication to creating and organising bug reports, and for testing our bug fixes. USERS + Fixed and improved quality of the half-width renderer for the GP2X port (Mr_Alert). + The numpad now works correctly when numlock is disabled. Keys are no longer ignored by the MZX editor, and games should recognize them as before. + Added a tool, "checkres", which extracts all resources from a MegaZeux world or board file and lists them (or lists only those which are not found in the game directory). ZIP files are also supported (to a more limited extent). (ajs & Revvy, ideas from Exophase & Terryn). + Removed the bogus "F1 for Help" option from error dialogs, and finally got rid of the "** BETA **" banner on title boards in play mode. + Obsoleted support for the AMS, DBM, DMF, MDL, MT2, PSM, PTM and UMX module formats. As noted for several versions in the help file, these are not loadable by MikMod. It is extremely unlikely any game uses these obscure formats, but denying their use is now enforced (at a robotic level). + Fixed crash when writing to an MZX string at an illegal offset (< 0). + Fixed returning from a subroutine invoked by a jump from a MZX text box class command so that it no longer skips the next impending line (after the text box). + Assembled single non-alphanum/punctuation characters as bytecode CHARACTER instead of bytecode STRING. Fixes bogus auto-quoting for commands like SCROLL CHAR (Revvy). + Switched the Win32 package back to using the "windib" SDL video driver, instead of the "directx" SDL video driver. The windib.bat file has been replaced with directx.bat, which has opposing semantics. + SAM/GDMs with converted WAV/S3M counterparts of zero length will be automatically re-converted. This hack can be used to procedurally regenerate WAV files from SAMs, or transparently work around on-disk corruption. + Strings are now limited to a maximum length of 1M. I'm open to suggestions over a better limit, but there must be a limit (set "$string.X" notation grows a string arbitrarily, so robotic can crash MZX when a string is resized beyond a reasonable limit). + Strings, when grown, will fill gaps with ' ' instead of garbage. This can be useful when the string grows after using the set "$string.X" notation; the rest of the string is no longer garbage, allowing the debugger to be used. + A robot that does a "put c?? Thing p?? [dir] player" and overwrites itself will no longer leak commands. Instead, if the robot overwrites itself, its program will end. + Fixed message edges always showing up black, instead of whatever color 0 is. (Revvy) + Changed starting/max health and lives minimum to 1 instead of 0. (Revvy) + Some help system (F1) bugs have been fixed, hopefully mitigating some of the crashes people have been seeing. + Fixed a bug on Linux where fclose() on a robot-opened file could, on world reload, occassionally crash (due to a stale handle). Fixes loading Taoyarin saves multiple times in a row. + The new option "gl_vsync" has been added to allow the SDL "flip on vsync" in the OpenGL renderers to be forcibly enabled or disabled. This fixes a problem where speed 1 would only be as fast as the video refresh rate. + Setting the music volume to 0 (when using the ModPlug engine) now ensures that no music is audible. Previously, setting the volume to 0 would be equivalent to setting the volume to 1, which was still audible. + Upon exiting the initial load screen, and not entering the editor, the screen is now updated. This fixes rendering glitches in the MZX game window when overlapping the window with another, at the slight expense of CPU time. + If loading a save game from the title screen (or when no world has been loaded) MZX no longer sends JUSTENTERED to all robots. This restores compatibility with MZX 2.70 and is consistent with loading a save from another board. + Counters with 10 digits and a negative sign are no longer truncated in the debug menu. + Correctly clamped (rather than truncating) the value passed through to a SET COLOR. Restores compatibility with 2.70, and fixes Xenogenesis. + Improved clipboard copy behaviour on Linux. Some actions are still mysteriously broken. + Fixed replacing with a blank string in conjunction with the replace all Ctrl+F action in the robot editor. The cursor can now no longer become negative, fixing numerous possible crashes on search/replace. + Fixed loading the intrinsic SMZX palette when switching to SMZX modes from a game not in the same directory as the "smzx.pal" file. + Reloading a world that requires switching between SMZX and non-SMZX modes will now respect the world's intrinsic palette on the title screen. Fixes problems loading non-SMZX games after having an SMZX game loaded. + Clamped array offsets on boards. Some older MZX worlds are corrupted and have the endgame_{x,y} coordinates outside of the limits of the endgame board. Fixes "Fourth Power". + Where possible, versioned all counters that the port understands. This ensures that in the unlikely case that a game made with an older version of MZX (actually, with an older world magic) uses a counter that did not exist in that game's era, the port will no longer try to interpret it. Previously, only rid? and key? were versioned. + SAV files will now be stamped with the world magic of the world they were loaded from. This allows compatibility hacks to apply to SAV files as they would to worlds (ajs, Terryn, Mr_Alert). + Added LOAD_MENU counter like ENTER_MENU, F2_MENU et al. to allow control (from Robotic) over whether the LOAD_MENU can be brought up. + Made FREAD_COUNTER and FWRITE_COUNTER read in a DOS dword (32bit) instead of a DOS word (16bit). This allows modern post-port MZX counters to be fully represented in files. Compatibility with older worlds is preserved. + Added a new config option "board_editor_hide_help" which changes the default hide setting of the help text on the primary board editor. + Numerous fixes for bugs found by valgrind. (Nightwatch) + Icon support is now fixed and works on all platforms. On Windows, the icon cannot currently be changed (it is loaded from the EXE's resource section). Use ResHacker if you really want to change it. + Fixed a bug where either LOAD_ROBOTn or LOAD_BCn (where n was equal to ROBOT_ID) would alter the robot's line number rather than completely restart it. Due to complexities in robot context, this lead to the first line being skipped. + Added a new tool "downver" which supports drag-and-drop downgrading of a world or board from the version of MZX it is packaged with to the previous version of MZX. This tool may be unsafe to use -- be careful. + Fixed a bug in the robotic assembler which would occassionally emit corrupt programs with SAVE_ROBOT. These programs, if loaded by LOAD_ROBOT, could cause a crash. + Added a config.txt (or command line) option "startup_editor" which, if set to a non-zero value, will start MegaZeux in the editor with a blank world. + Fixed a bug where a robot's WALK processing, on entering a transporter, could allow subsequent commands (such as GO) to corrupt the board. WALK now ends the cycle in the special case that a robot goes through a transporter. + You can now directly import bytecode into the robot editor via the Alt+I menu. The extension for the bytecode file must be .bc for it to be loaded. + A game loading SAVs via the LOAD_GAME counter will no longer crash MZX if the SAV attempted is from an incompatible version of MZX, or in any way corrupted. + Fixed a crash when auto-completing lines that were greater than 241 characters in length after completion. + Added mouse pixel counters MOUSEPX and MOUSEPY. (Mr_Alert) + Commenting a line of maximum length (241 characters) can no longer grow the length of the line beyond this limit. + Fixed a bug causing the software renderer to fail to center when using a boxed fullscreen resolution. Also fixes a bug where the PSP platform would ignore an override of the force_bpp option. (Mr_Alert) + Fixed a bug causing macros loaded from config.txt to be expanded incorrectly. Relatedly, fixed a bug where #<string> in the robot exitor would "disappear" on entry, if there was no correspondingly named macro. DEVELOPERS + Builds no longer initialize the SDL audio subsystem if audio is permanently disabled with --disable-audio. + Added fixes for OpenBSD to allow PNG screenshots and X11 clipboard support to work. Tested with OpenBSD 4.2 and GCC 3.3.5. + Updated Win32 builds with SDL 1.2.13. + Build and package two utilities, txt2hlp (for helpfile generation) and checkres, on Win32. + Dependencies are now correctly tracked in the build system. Modifying a header will automatically regenerate the minimal set of object files that depend on this header. + Out of the box MSVC support. The file "msvc.zip" in the root of the source package now provides a Visual Studio 2005 project and pre-compiled dependencies. There may be stability issues with the resulting binary. See also the documentation in arch/msvc/README.txt. + The Nintendo DS port (a.k.a. 'dsmzx') has been merged. This is the most exotic port thus far, and adds features such as player focus (on the second display). Sound isn't working yet, and large games still won't play (due to lack of memory). See docs/nds.txt for more information. (kvance) + Many stack-heavy functions have been de-bloated and allocate large storage on the heap (if performance is not critical). This helps out platforms with a small, fixed stack size (such as NDS). + The built-in help system can now be disabled for embedded platforms. The startup check for the help file will not be performed if the help system is disabled, and so this file can be omitted from distributions. + The package.sh script now supports OS X, PSP, GP2X and NDS packaging. + The OS X port no longer requires Xcode. The new build system and package.sh can create a universal Application and corresponding DMG file. The new infrastructure deprecates the old macosx.zip method. + Most of the internal dependency on SDL has been removed. Therefore, MZX can be built (but not yet work) without SDL present. The only remaining component to convert is MikMod, but this can be disabled, so port authors can start using the feature right away (see config.sh). (Mr_Alert) NEW in MegaZeux! New in Versions 2.92 to 2.92f New in Versions 2.90 to 2.91j New in Versions 2.84 to 2.84c New in Versions 2.81 to 2.81h New in Versions 2.80 to 2.80h New in Versions 2.60 to 2.70 New in Versions 2.01 to 2.60 New in Version 2.00 New in Versions Through 1.03 Table of Contents

New in Versions 2.81 to 2.81h

December 8, 2007 - MZX 2.81h Another bugfix release with a couple of new features, in time for the Winter 2007 Dualstream Day of Zeux. The major new features of this release are automatic module renaming in the editor, PNG screenshots and many improvements to MZX on embedded platforms (like PSP and DS). MegaZeux can now be compiled in MZXRun mode (like the old DOS implementation) and by disabling features such as unnecessary renderers and audio support, can be made approximately 70% smaller. Thanks again to Terryn for relentlessly tracking down many serious bugs; we've tried to fix all the issues that have crept up in the last 5 months. Thanks too to Exophase, Mr_Alert and Wervyn for contributing to this release; your time and help is invaluable. Happy Holidays! USERS + Added a more lenient WAV file loader so that ModPlug isn't relied on as much to play malformed WAV files (mostly old SAM conversions) (Mr_Alert). + Added SCORE and mzx_speed to the counter debugger (Mr_Alert, ajs). + Added a 16-bit software renderer and a half-width renderer for the GP2X port (Mr_Alert). + Made the mouse cursor in the "opengl2" renderer look more like the mouse cursor in the other renderers (Mr_Alert). + Setting vlayer_size, vlayer_width or vlayer_height to values less than or equal to zero would crash MegaZeux. Limited the smallest vlayer size to 1x1. + Setting vlayer_width or vlayer_height to a value larger than vlayer_size would crash MegaZeux. Limited the largest size of either dimension to a maximum of vlayer_size. + If selecting a module with a non 8.3 filename, MZX will now ask you if you want to rename it to 8.3, and do so in an intelligent way. This means that music can be selected in the editor and correctly saved (Wervyn). + The OpenBSD compiler detected some serious string bugs in MegaZeux. These have now been fixed and should eliminate some more potential crashes. + Fixed a bug where an ENERGIZER item or use of the INVINCO counter would cause the original player color to be corrupted at the end of the colour blitz. + Fixed a long-standing bug where set "$string" to "FWRITEn" would be cheerfully ignored. + Fixed a bug where a corrupt robot list could crash MegaZeux (e.g. the list from Star Quest from DoZ'02). + FEATURE: Screenshots are now saved in a palettized PNG file format. For platforms without libpng, PNG support can be compiled out, and BMP will be used instead. + Fixed a bug where changing boards in the editor could sometimes corrupt memory, later causing a crash (either testing or coming out of testing a board). + Fixed a sensor bug that happens when a sensor can't go anywhere it is told to, and the player is on it (Exophase). + Fixed using ABORT LOOP in some situations. Using it outside of a loop still has undefined semantics and this has been documented in the help file (Exophase). + Setting a board option below its numeric limit is no longer possible (Exophase). + Fixed problems with going over Robot name character limits using the .@ command (Exophase). + Fixed problems with LOAD_ROBOT freezing on a robot with no newline at the end of the file. + Fixed a problem with "Replace All" in the robotic editor that could sometimes cause a line to exceed 240 characters and crash the editor. + Fixed a problem with "Replace" in the robotic editor which could cause a line to temporarily become 241 characters and then truncate silently to 240 characters. + Fixed a bug that caused the original game palette to be lost when testing a game in the editor that switched between Regular/SMZX1 and SMZX2/3 modes. MegaZeux should now try much harder to preserve the user palette, regardless of game edits. + Fixed a bug causing board switching to not correctly alter the x,y viewport scroll leading to the display of raw memory and potential crashes, with differently sized boards. + Fixed stack corruption caused by SCROLL CHAR SOUTH, detected by Ubuntu's SSP (Stack Smashing Protection) enabled binary. DEVELOPERS + Made the build system less verbose by default (like Linux). This should help make warnings (due to coding errors) easier to identify. If you don't like the new syntax, or need the command debug, you can build with "make V=1". + Updated Win32 builds with SDL 1.2.12. + Rewrote the build system to not use recursive Makefiles. Variable propagation was starting to be a problem, and recursive designs are generally discouraged. + Refactored the graphics rendering code to modularize the renderers and reduce code duplication (Mr_Alert). + GDM2S3M switched over to use inttypes.h instead of home-brew types. + MegaZeux now compiles on OpenBSD (and probably other BSDs). + Made all unnecessary global symbols static. This should improve compiler optimisations and correctness (Mr_Alert, ajs). + Fixed compilation of MegaZeux against SDL 1.3 SVN. However, this SDL version is still in development, and MegaZeux does not work correctly when compiled against it. + MegaZeux now builds with the experimental MINGW-x64 branch, enabling x64 binaries for Windows. + MegaZeux now builds with MSVC if you apply the patch from contrib/,megazeux-r326-replace-c99-variable-arrays-with- malloc-free.diff . This patch is required for MSVC because it makes non-compiler-specific changes (which involve converting from C99 variable length arrays to malloc/free) which are slower and should not be used with competent C99 compilers like GCC. Microsoft Visual C++ Express Edition 2005 was used to build libogg, libvorbis, libsdl and MegaZeux itself. Only 32bit builds were tested. + MegaZeux now has size optimisations which can reduce binary size when features are disabled. For example, all renderers can now be disabled, and when module engines are disabled, audio will not export any symbols. + The entire audio subsystem can now be disabled. This further reduces binary size on embedded platforms. However, SFX editing still remains enabled (though useless) until editor modularity is implemented. + The PSP port is now officially supported, and compiles out of the box. See docs/psp.txt. + Renamed macos platform "darwin", to reflect its true nature (use Xcode to build as a real Application, instead of just a UNIX binary). Also fixed some bogosities with robo_ed's X11 includes on OS 10.5. + The editor can now be disabled, a la MZXRUN from the old DOS versions. Configure with --disable-editor to shrink MZX by about 150k. + MegaZeux can now be compiled with size optimisations (--optimize-size to config.sh) for a 20% space saving. + MegaZeux's core now builds with -W (basically all GCC warnings) plus some additional warnings that aren't switched on by this flag. All warnings have been fixed. Table of Contents July 4, 2007 - MZX 2.81g Again, no significant new features have been introduced in this release. However, there have been many essential bugfixes, including improved compatibility with games made in older versions of MegaZeux. Additionally, improvements have been made to the opengl2 and overlay2 renderers, improving performance for most users. A port of MegaZeux to the GP2X console has been added. MegaZeux has been backported to C (rather than C++) and can operate correctly on a CPU without a floating-point unit. Particular thanks go out to Mr_Alert (for his valuable bug fixes), Lancer-X (for fixing what I was too lazy to) and Terryn (for finding many annoying bugs that nobody else could). USERS + Fixed a bug in the audio code. The linear resampler was not taking volume into account, which broke changing the volume of samples (WAV and Vorbis) which cannot natively alter their volumes. + Fixed a regression in the overlay editor caused by the new editor space semantics. + Screenshots are now rendered to a separate texture using the 8bit software renderer. This means that the hardware scalers will not affect the quality of the screenshot. It also fixes a bug when using opengl2, which would dump only a white screen. + Temporarily reverted a bugfix that broke Zeux IV - Forest of Ruin. I'm not dropping the bugfix, I just can't immediately see what's wrong. + Fixed a bug where setting the viewport to negative coordinates would crash MegaZeux. There was code to handle this, but it was wrong. + Fixed a bug that permitted the mouse y coordinate to be warped to row 25, which does not exist. This bug caused some of the renderers to crash, and the software renderer to draw in memory it did not possess. + Fixed a bug where games made before 2.68 could have available the "key?" counters, unsupported in that version. This caused collisions with counters with the key? name used with inc/dec/mul/div/mod. Fixes "Doom Keep". + Imported libmodplug 0.8.4, which adds MIDI/PAT and ABC format support, fixes some bugs in the mixer, and should build on more platforms. NOTE: MID files currently cannot be selected in the editor, because they do not play correctly. + Improved the performance of the "opengl2" renderer, by removing the convoluted 3D drawing commands and replacing them with 2D ones. Reduced the quad count by using an intermediary 80x25 texture. MegaZeux now depends on fewer GL features. [LogiCow] + Introduced an "fsafegets" to work around problems where robots exported by a Windows version of MegaZeux would not load on other platforms. This was due to differing EOL style and broke at least one game (Termination). + Renamed "force_resolution" to "fullscreen_resolution" to better match its semantics with the scaling renderers. The new name is less accurate for software render modes, but most people using software will not want to change it from the default anyway. + Fixed a bug where the variable-length string allocator would prematurely bail out when reading a string (of indeterminate length) from a file with the set "$var" to "FREAD" syntax. + Fixed a bug where more than 256 errors would crash the robotic checker. + Improved performance of the overlay2 (faster) renderer (Mr_Alert). + Made the transparent overlay "really" transparent when used in conjunction with sprites (Mr_Alert). + Fixed a bug reported by Mr_Alert where MZX would not handle short, non-looping mods in the editor. The editor would try to destroy the mod again, even after the callback had destroyed it (premature termination). + Fixed a bug with SWAP WORLD where file translation would occur but the result would mistakenly not be used. This broke some uses of SWAP WORLD on non-Windows platforms (Mr_Alert). + Fixed a bug where using JUMP to MOD ORDER right after switching boards would fail due to the board music not having been loaded yet (Mr_Alert). + Fixed a bug where games made before 2.80 would inadvertently trigger "PLAYERHURT" due to using the SET command to reduce the amount of health (Mr_Alert). + Fixed a bug where player clones were generated when entering transports during FREEZETIME (Lancer-X). + Debug menu is now eradicated on leaving the editor (Lancer-X). + Debug menu is now properly painted over when the board size is < the editor viewport. Fixes various graphical glitches (Lancer-X). + Fixed a crash bug when playing older MZX games from read-only media (such as a CD) or where file-system permissions prohibited creating SAM conversions (Lancer-X). + Fixed bug where certain file formats would not be automatically converted if their extensions were mixed or upper case (e.g. OGG/SAM/GDM). + Restored functionality of "if lasttouch DIR" which has been broken since MZX 2.02. + Fixed a bug where attempting to decrypt a read-only world file would result in a crash (Mr_Alert). + Fixed several bugs where an error loading a world file would result in crashes in several different situations (Mr_Alert). + Fixed a bug where a robot using the BECOME command to change into a PushableRobot or vice versa would freeze (Mr_Alert). + Fixed memory leaks in the file selection dialog, the counter debugger, the collision list and the global robot (Mr_Alert). + Updated counter list (see docs/counter_list.txt in the source) (Terryn). + Fixed a bug where pressing escape when editing the effect of a ring or potion would result in an invalid parameter which would later cause a crash if edited again (Mr_Alert). + Fixed a bug in which robot-driven text boxes using option commands (the ? command) could overflow by two characters and spill over the side (Lancer-X). + Fixed the list box searching mechanism (used in the file manager and F11 counter list) and made the existing function more understandable. (Lancer-X). + Fixed a bug in which the message string given to the 'ask' command could spill over. Now, the 'ask' dialog resizes if possible, and clips when no further resizing can be performed (Lancer-X). + Clipped the 'input string' message properly, to prevent similar overflow. + Fixed a bug with the EXPLODE, DIE, DIE ITEM and BECOME commands when used with the global robot (would clear the global robot, eventually corrupting memory when in the editor). Presumably, these commands are bogus for the global robot, and have been disabled. DEVELOPERS + Rewrote config.sh to use POSIX sh compatible functions, so that there is no dependency on the BASH interpreter. Surprisingly, some distributions still don't enable BASH by default (using csh, ash or zsh instead). + Ported most of MegaZeux back to C. Many more changes were required than I anticipated; MZX was using more C++ features than I expected. The only exception is audio.cpp, which cannot be ported back to C because it uses ModPlug's C++ classes directly (but I plan to split this file up shortly). NOTE: The changes required were enormous, so I might have introduced some weird bugs! Please test! + Enabled GCC's -W flag for even more warnings, switching off unused parameter warnings (useful for delegates). Mostly typing fixes, but it found a bug in string handling. + No longer suppresses char-subscript warnings, and fixed up any remaining abuses in the tree. + Added manpages for 'megazeux' and other binaries for the Debian packages. Complied with the Debian packaging guidelines by providing a copyright note, listing significant contributors to MegaZeux. + Added support to the build system for supporting icons modularly. See contrib/icons/README for more information. + The debug build (make DEBUG=1) now enables GCC 4.x's stack protector. This breaks compatibility with GCC 3.x, but you can just remove the flag if you don't want to use it (the stack protector will improve stack corruption detection and provide more usable debug traces). + Custom Random() implementation to provide a more uniform number distribution. Factored out for future (better) implementations. + The audio backend (audio.cpp) has been modularised to support the use of mikmod instead of modplug. This should enable ports of MZX to platforms without an FPU, and improve performance on platforms with weak FPUs. + Added GP2X port to config.sh, based on work done by Simon Parzer. Table of Contents January 30, 2007 - MZX 2.81f This release is mostly about the new renderers, the first of which was introduced in the previous version. There's also a few important bugfixes, and a lot of internal tidy-up work. I'd like to thank Mr_Alert, Quantum P. and LogiCow for contributing to this release. Thanks guys. USERS + Renamed the force_32bpp config option to force_bpp, in preparation for 16bit OpenGL render modes. This option now takes 8, 16 or 32. 16 is reportedly broken on Windows, so stick to 32 for now. + Added infrastructure for "pluggable" renderers. This code isn't perfect, but it's far better than the mess in 'e'. Defaults to the 'software' render mode. + Added Logicow's alternative OpenGL renderer. For more information about this renderer, see config.txt. NOTE: This code may be buggy! Please test! + Added Mr Alert's YUV overlay renderers. One does full YUV macropixel approximation, the other (faster) render does chroma supersampling. See config.txt for more information. NOTE: This code may be buggy! Please test! + Simplified Exophase's OpenGL renderer present in 'e', and fixed a few bugs that caused it to not work for some people. + Really made MegaZeux use 'directx' by default on Windows. The code in 'e' was non-functional. Use 'windib.bat' to run MegaZeux with the SDL windib driver. + The OpenGL renderers now have a 'filter' option that allows you to choose linear (where pixels are interpolated, looks "blurred") or nearest (where nearest-neighbour approximation occurs, looks "sharp"). + Mouse warping was broken when using any of the hardware renderers. There should be code in there now to take account of this (thanks Mr_Alert). + Added an option 'editor_spaces_replace' which allows you to revert MZX's space overwrite behavior to the semantics of 'd' (the feature was removed in 'e'). By default, the behavior is unchanged (the same as 'e'). + F6 (the debug menu) can now no longer be enabled anywhere but in the editor Alt-T test mode. In 'e', it was possible to enable on the title screen, but could not be enabled in a game. Like the cheats, this option is now visible only in test mode. + Fixed a bug where the global robot could be exited via some legal commands, in an abnormal fashion. The bug resulted in all the code up to the offending command being executed over and over. + Fixed a bug in the audio code. The linear resampler was not taking volume into account, which broke changing the volume of samples (WAV and Vorbis) which cannot natively alter their volumes. + Fixed a regression in the overlay editor caused by the new editor space semantics. + Temporarily reverted a bugfix that broke Zeux IV - Forest of Ruin. I'm not dropping the bugfix, I just can't immediately see what's wrong. + Screenshots are now rendered to a separate texture using the 8bit software renderer. This means that the hardware scalers will not affect the quality of the screenshot. It also fixes a bug when using opengl2, which would dump only a white screen. - The force_height_multiplier option has been removed. A lot of code wasn't properly designed to handle it, there have been mouse warp bugs with it for years, and nobody seems to use it. If people want stretching, they can choose one of the four hardware renderers to achieve this. - Removed the 'lame/1337' menu feature. DEVELOPERS + OpenGL can now be disabled via config.sh. This allows MegaZeux ebuilds to be constructed on systems that do not have any form of OpenGL support. (Although MZX runtime loads the OpenGL library, 'e' required the headers to build correctly. This is now no longer the case.) + On Windows, due to an ATi driver bug, I have provided a means of linking directly to opengl32.dll, instead of relying on the dynamic loader. This reduces binary portability, but fixes many bug reports of being unable to fullscreen on ATi video cards. See OPENGL_LINKING for more information. + Improved support for cross compiling with mingw32 on Linux, combined the win32 Makefile with this new support. + Rewrote the config.sh script. All of the options have changed, and the broken platform auto-detection has been removed. See ./config.sh for more information. + Rejigged MegaZeux's headers so that they can be used in both C and C++ mode. Renamed fsafeopen.cpp to fsafeopen.c. Hopefully by 'g' most of MegaZeux should be ported back to C, instead of the "C++" it is now. + Fixed up the 'txt2hlp' utility which Terryn has been using a version of to build the internal MZX help system. This binary is built in the source distribution, but it is not distributed with the MegaZeux binaries. + Moved some antiquated Greg code out into 'old'. No attempt has been made to make it compile, it is provided purely for reference. + For the windows binaries, "windib.bat" is now generated by package.sh and auto-generated for the name of the MegaZeux executable. + Updated Xcode package from Quantum P. (see macosx.zip). + Fixed an invalid assumption in config.sh where /bin/sh was chosen as the shell script interpreter. This should have been /bin/bash, as 'sh' is not required to support functions, which config.sh uses. Table of Contents January 19, 2007 - MZX 2.81e + Made grabbing in the editor not combine background color - only uses "special" in game colors for player. tell me if anything ends up being weird because of this. + Possibly fixed an obscure bug where moving something happened immediately if it was sent to a label by a robot further east/south than it and it moved north or west (has to do with the way robots are reverse scanned). Tell me if this changed any behavior for the worse and I'll change it back or try to work out something new. + Added GDMs to ctrl + n; this will, of course, auto convert and play the s3m. + Added ability to preset player locked status from board settings. + Instead added ability to debug variables (counters and strings) ingame with F11. There's also an option to export the current variables to Robotic program that sets them. + Fixed bug where moving a block with the player into an overlapping region leaves a space where the player was. + Fixed bug with a robot indirectly sending itself to a subroutine via send all or send name causing it to loop the send. + Added compatability hacks for key# prior to MZX 2.69 worlds and ridNAME falling through in MZX 2.70 and earlier worlds. + F6, F7, F8, and F11 debug/cheat keys only work in editing mode now (as things were prior to the port) You can still save/load in the editor so if you want all of these things you can play the game from the start there. + Space in the editor no longer deletes something of similar type that is beneath; not sure what the point of this was anyway. + Fixed bug causing cursor to clipped be out of bounds in SMZX char editor if changing to smaller multichar edit region. + Accidentally messed up screen centering in fullscreen for 32bpp mode, fixed. + Added hardware scaling option. You can now supply a window resolution besides 640x350 and allow for window resizing if hardware scaling is on; this will also scale fullscreen output to fill the entire screen. This can slow down rendering somewhat. + Fixed bug causing flip block to crash in the editor. + Made blocked directions relative to the player for put dir player. + Fixed bug where putting something to a direction relative the player overwriting the robot could crash MZX. + Fixed ability to input in input boxes by clicking on their question string. + Removed the bogus patch to Modplug and correctly fixed it in the build system. + Added 'debian' subdirectory for building Debian and Ubuntu upstream packages. Hopefully MegaZeux will be in the primary pool in a few months. + Added OS X xcode project files (see 'macosx.zip'). Fixed many bugs relating to endian that caused MegaZeux to be buggy on big-endian architectures (like PPC). Credit goes to Quantum P for finding these bugs and engineering high quality solutions. + Made 'directx' the default video render again on Windows. NOTE: This overrides the default SDL behaviour, but will not be applied if you set SDL_VIDEODRIVER yourself. + Repaired the 'linux-static' target so that it no longer includes a system C++ library, which caused unpredictable results on distros without a static version. + Fixed a locking bug with the audio code that caused hangs at startup on OS X. Also provided a mutex implementation using GNU pthreads as a temporary workaround for an SDL bug on the Linux platform. + Added PlayStation Portable (PSP) port. This code was written by Exophase and is highly experimental. It may not work at all for you. Please see docs/build.txt for more information regarding this port. + Fixed mouse movement from being affected by height_multiplier when not in fullscreen mode. + Fixed height_multiplier config.txt option allowing you to enter really stupid values (like negatives, 0, and values too large for the resolution). + Added in an extra video mode check to stop MZX from crashing on video modes that the video card can not reproduce. + Fixed Avalanche to a constant placement rate of 1/18 (this caused MZX to deliver an uneven number of boulders, and to crash with certain board sizes). + Fixed sprite collision box to stop MZX from crashing when stupid values are entered. + Fixed setting the viewport size to weird values like some old MZX games do. + Default fullscreen resolution is now 640x480; this can be changed in config.txt . + The config.txt option force_32bpp is now enabled by default. + Seeking with mod_position when using a .WAV file as background music fixed (thanks Mr_Alert). - Removed ability to change SMZX mode ingame (F11). Table of Contents December 10, 2006 - MZX 2.81d NOTE: This release was made by Alistair Strachan (ajs) and not by Exophase. As such, any problems present in this release that were not present in 2.81c should be reported directly to ajs. + Fixed a compilation failure on Linux, due to SDL no longer depending on libX11. Now we manually link X11 into MZX if necessary. + Various build system improvements, fixing bugs in the prefixing of dependencies. + New libmodplug 0.8 imported, fixing many endian problems on big-endian machines, integrating all of our local patches to 0.7. + Fixed bug causing MZX to freeze when starting up on Win9x machines. + Fixed a warning generated by GCC 4.1. + Updated the GPL boilerplates project-wide to the newest FSF address. + Fixed a string range check causing an obscure crash in certain games. + Updated the build.txt documentation. Table of Contents December 14, 2005 - MZX 2.81c + Oops, accidentally broke shift + F2. Fixed that. + Also accidentally broke &+counter& for full hex representation. Fixed. + Fixed memory leak problem with playing certain WAVs in a loop. + Fixed inconsistency of bad viewport sizes behaving differently on current versions from old DOS versions. + Accidentally broke joystick stuff in config.txt (has to do with way configure options were being read), fixed. + Fixed bug causing crash when loading MZBs larger than the current board size. + Made cursor hidden in alt + V in editor. + String comparison failed with nulls in the strings, fixed. Also should be slightly more optimal. + Fixed bug when using negative numbers for if sprite_colliding "counter". + Fixed math operations (inc, dec, etc) not working on string indeces. + Added ability to force screen to 32bpp. Fixes some slight rendering issues, and if you have problems with fullscreen let me know if this helps (try it without first though). See force_32bpp in config.txt. + Fixed sprite clipping bug with respect to overlay. + Fixed bug where pressing enter on things besides robots, scrolls/signs, or sensors in the editor would clear whatever was underneath it. + Accidentally broke SFX with optional PC speaker chains (played both, should only play PC speaker when digital music is off, fixes Bernard the Bard). + Made last character in char selection for F3 and alt + C remembered (note that they're remembered in two different places for both). + Accidentally broke life animations, fixed. Table of Contents November 26, 2005 - MZX 2.81b + Fixed inability to make proper .savs of worlds with strings. (they'd crash when loaded..) + Fixed PC speaker audio bug causing a constant high pitched noise to be played instead of PC speaker audio sometimes. + Fixed some issues with long pathnames. + Fixed a bug causing Caverns to crash in recent versions (long story, it was most likely due to an error in ver1to2). + Now when you set mzx_speed in a game you can no longer change the speed from the F2 menu. Setting mzx_speed to 0 reallows this (and doesn't set the speed). + When loading a game its speed is now set to the speed MZX started with (whatever's in config.txt, or the default of 4). + Added backup_ext config.txt option to specify the extension of backup files (default is .mzx). + Fixed backup_interval for config.txt possibly being broken. + Fixed a bug messing up the death board on some old MZX games (like Nick Brick 2) + Escaped more things and made displays always in escaped form for certain character sequences. It should be impossible to type non-escaped forms. The following should be used: \0 for 0 (this probably won't work in strings, but in chars should) \t for tab (character 9) \n for newline (character 10) \r for carriage return (character 13) \" for double quote \\ for slash + Copy + paste on escaped character won't unescape them anymore. + Fixed error message for invalid lines in Robotic. + Fixed inability to import text files from other directories. + Huge overhaul of the source (proper types for things, directions, equalities, conditions, chest items, and potions), if anything is suddenly broken now let me know. + Made scrolls/signs only display text (letters, numbers, etc). in the default char set. That should be enough for now. + Added mousewheel support for robot editor and robot box display. + Fixed inability to load MZMs from other directories in the editor. + Wrapped audio stuff in proper mutex, hopefully this fixes some issues (like crashing when changing mod_frequency a lot). + Long current directory paths no longer write out too much in the file loader (instead the last bit is shown with a ... prefixing the beginning) + Decided to be nice and make board_scan not crash. Don't use it. It's only there to make one legacy game work. If you use it I will personally scold you. And don't tell other people to use it (that means you CJA). Use copy block x y w h "$str" t instead. If you don't know what that means read the help file, it explains everything. + Removed ability to copy + paste after changing board dimensions of the source under any circumstances (alt + R, alt + Z, import world, import board). + Fixed appearance of ghosts in F10 menu. + Prevented char editor from counting moving the cursor as an undo step if nothing was actually drawn. + Made pressing escape on initial char selection/board selection/param selection for things cause it to cancel placing anything. + Made it impossible to set board width/height to 0 again (oops). + Made starting lives and starting health take effect immediately for the first alt + t. + Added ability to play OGG from alt + l (but not the other mods, don't want to clutter that up). + Made it so if no note follows an embedded SAM in a play string it's played at native frequency. + Accidentally made loading worlds in the editor not change the current directory, fixed that. Table of Contents November 20, 2005 - MZX 2.81 + Fixed a bug where MZX world/save names > 12 chars could cause weird things to happen (like doors breaking). + Fixed problems with help file/charsets loading when loading MZX outside of the directory MZX is in. This should fix file associations on Windows as well. + Changed board selector so when board 0 is "(no board)" it doesn't actually refer to the title but to no board. + Made import world not overwrite the title string. + Fixed bug that causes crash when trying to flood fill an area with the color it already is in the SMZX char editor. + Redid audio engine. Everything is unified now, meaning that anything you can use as a mod you can use as a sam and vice-versa. + The new audio engine uses its own master resampler that has three interpolation modes - see config.txt for more information. + sam 0 filename will play a file at its native frequency (note that SAMs that have been converted from WAVs are set to be played at 8363Hz). + Added support for OGG vorbis audio files. + Fixed bug causing SFX volume control in F2 menu to not work. + Removed limitation on number of SAMs that can be played simultaneously. + Fixed bug where the mouse got "stuck" in the black border edges of non 640x350 fullscreen resolutions. + Fixed issues with message boxes being part default palette part current palette, they now always use the current palette. + Added mod_position counter. What these actually set/return is dependant on the type of file loaded. Modules use the current row, OGGs use the current PCM sample. + Added mod_frequency counter. There are a few things to note here: Modules have a "nominal" frequency of 44.1KHz. Other data types have their own nominal frequency to prevent output from sounding differently depending on the audio_sample_rate in config.txt. For OGGs and WAVs the nominal frequency is the one the file is encoded at. Changing the frequency can cause a noticeable one time popping sound, so it might not be desirable to slide it. This is much more prominent with lowering the frequency than raising it. This value is capped so it can't reach below 16. + Changed alt + L to play back at natural frequency instead of 8363Hz. + Fixed bug causing sensor deletion while the player is on top to destroy the player. + Fixed bug causing imported boards to possibly crash after being tested. + Fixed bug causing save_game and save_world to not work if a file with the given name isn't already present. + Changed function counter matching removing restriction on number of digits for parameters. 10+ digit inputs should no longer fail (for instance, abs-123456789) + Made counter/string names internally variable length instead of a fixed 14 chars. There is now no longer a name length limitation. + Changed alt+8 for mod * to just * in the hotkey listing. + Fixed crash when referencing (by param) sprites > 256. + The string system has been redone. Strings are now dynamically sized and don't have an artificial maximum length. Writing to string.N will guarantee that the size of the string becomes at least N, while reading in this way will return 0 if out of bounds to maintain the illusion of null termination. Be careful when using this. + $str.length returns the length of string $str (this is faster than iterating through it to find when chars hit 0). + Vlayer is dynamically sized. The vlayer_width/vlayer_height counters still work as per usual, but the vlayer_size counter has been added to adjust the maximum size. The default is 32768. + Fixed bug not allowing things to move over goop. + Fixed bugs causing current directory to be changed when importing things from other directories. + Properly implemented support for volume "string". + Fixed a few commands not working when they should from the global robot (such as put to dir of player). + Fixed a bug where going to a label at the end of a robot would treat it as if it's the first of its name in a sequence of labels. + Fixed a bug involving moving the a block with the player not moving what was underneath the player. + New help file, thanks MUCHLY to Terryn for pulling off this enormous effort! (This is what you're reading from.) - Save files from 2.80 are not compatible due to several changes in the save format. NEW in MegaZeux! New in Versions 2.92 to 2.92f New in Versions 2.90 to 2.91j New in Versions 2.84 to 2.84c New in Versions 2.82 to 2.83 New in Versions 2.80 to 2.80h New in Versions 2.60 to 2.70 New in Versions 2.01 to 2.60 New in Version 2.00 New in Versions Through 1.03 Table of Contents

New in Versions 2.80 to 2.80h

June 6, 2005 - MZX 2.80h + Fixed a bug which could cause crashes when quitting the game. + Fixed some bugs when changing boards and other things that can cause duplicate players.. I think. + Fixed a bug that could cause crashes when adding boards. + Improved response time in editor for slower computers/high load situations. + Fixed some endian issues with the GUI. + Fixed some crash when moving the mouse cursor around in the editor. + Fixed bug where you if you had a robot whose name is the same as the global robot it wouldn't get messages (fixes yoyo in Weirdness). + Fixed debug box not moving with text input. + Fixed bug with duplicate player appearing when killed and a new one can't be put at 0, 0. + Added copy/paste for outside of MZX to/from the robot editor. It only works in Windows and X11, and functionality may be limited in X11 right now (currently seems to work in native X11 apps and GTK 2.6 apps but not earlier GTK or QT, also try shift + insert to paste). + Fixed bug in resizing involving overlay blanking. + Fixed clear messages/projectiles not working (and damaging the game instead). + Fixed behavior of P key in editor for wildweasel. + Fixed random in Robotic not correctly swapping the range if they're given in the wrong order. + Fixed clip length in [ messages. + Fixed crash when changing volume without a game loaded. + Redid internal GUI system, fixes some minor things. + New file loading/saving window - press del to delete a file/dir, alt + n to create a new directory, alt + r to rename a file/dir. + Added PC speaker volume control to F2 settings and config.txt. + Fixed yet another crash bug with resizing boards. + Fixed inability to type * in text placement in the editor (although this adds inability to turn on mod * while F2 is on...). + Added ctrl + n in the editor to load a module for listening only (won't set the current board's module, and will let you choose ones from different directories). + Fixed crash on macros with more variables than can be displayed in their configuration. + Fixed bug that causes char selection cursor to reset to 0 on unhandled keys (and continuously do so for lock keys). + Tweaked ctrl + dir in text entry boxes. + Added gdm2s3m in-tree to the contrib/ directory. gdm2s3m no longer needs to be installed on the system before compiling mzx. + Improved the build system to automatically build .c and .cpp files with compound system CFLAGS/CXXFLAGS, respectively. + Made package.sh automatically ship the source package with a Makefile.dist to warn the user that they need to run config.sh before 'make'. + Rectified inconsistency in source copyrights. + Added multi-character editor. Select multiple keys in the character selection with shift. The char editor also now has the ability to perform operations (delete, copy, scroll, etc) on subblocks. Hold down shift or press alt + b to highlight a region (press escape to remove the latter). Blocks copied like this will be pasted to where the cursor is at. Other small things in chareditor tweaked/changed... No longer press tab to toggle through set/clear/toggle draw modes, instead tab for set mode and shift + tab for clear (no more toggle). Mouse behavior is modified as well. In non-SMZX left click sets, right click clears. Shift + F2 will cut a block (clear + copy). alt + x/alt + i can now be used to import/export partial charsets while in the char editor. You can do so for several in series: put a # in the name of the charset then set the First for the first number # will be replaced with and the Count value to indicate how many in series to work with. For instance, saving s#.chr with first = 0, count = 3, starting at offset 100, with a 2x2 char selection will save charsets s0.chr from 100, s1.chr from 104, s2.chr from 108, and s3.chr from 112. *** NOTE *** Series import/export will only work correctly with char selections that are one in height (they can still be split up another way in the editor itself). If you want to use partial charsets on your edits, it's important that you select all the chars in a row. + Made characters for the editor/GUI use another charset that's protected. Please notify me if any characters are incorrect. Modify mzx_edit.chr to change this charset. The same thing goes for colors. It doesn't work for SMZX, which also might look a bit different in the editor... + Added option (defaults on) to protect chars 32-127 in input boxes and strings in the robot editor. + Mouse warping goes to middle instead of top corner now, so there isn't a bias towards moving up. + Hopefully fixed another bug with the cursor and changing boards... + Fixed module looping problem in modplug... + Added libmodplug 0.7 with both patches (see contrib/) in-tree. Removes system dependency on libmodplug. + Made auto-backup on by default. (3 count) + Made if touching idle, beneath always false instead of like nodir. + Fixed bug that caused bad things to happen if you pressed too many different keys too rapidly. + Made mouse wheel emulate up/down in dialog boxes and list menu. + Added ctrl + backspace to intake (delete previous word). + Made modulo operator use floored instead of truncated mod (uses positive remainder instead of negative). + Fixed crash when testing after using ctrl + z to clear a board. + Fixed bug where sending other robots to subroutines caused the return address to be to the next instruction like local subroutine calling works. + Fixed bug where going to a label on the last line of the robot could screw the game up. + Fixed a bug where the editor froze if you tried to fill the board with players. (eheh...) + Fixed a bug that could cause crashes when sending all sensors something. + Fixed some crashes when exporting/saving fails. + Fixed import world's ability to go over the board limit and cause crashes. + Allowed input of decimal numbers for params. Table of Contents April 1, 2005 - MZX 2.80g + Fixed crash on alt + x in robot editor. + Fixed missing line on alt + h in robot editor. + Introduced incorrect enter action in robot editor (didn't reset to beginning of the line), fixed. + Fixed garbage appearing when moving from a larger to smaller board and being outside of that board's scroll region. + Fixed bug that could cause glitches/crashing when resizing the board. + Fixed error with global next option not retaining the three checkmark options correctly. + Added work around so that move block moves the player (won't move it on inter-board moves). + Fixed bad palette loading for Linux introduced in 2.80e or f or something + Made it so block highlighting doesn't highlight the debug window. + Made the debug window move if necessary when home/end is pressed. + Added autorepeat buffering so previous keys can be resumed. + Fixed bug with swap world possibly not working (crashing??) off Windows. + Fixed more problems with garbage/crashes when resizing with the cursor in a position causing the scroll to go off the edge. + Fixed incorrect text cursor offset with force_height_multiplier on. + Redid way directories are loaded internally so you can load dirs with over 4096 entries now. Might be faster (unsure) + Chest contents list menu looked funny, fixed. + Changed default.spl to smzx.pal so you can load it more sanely. + Export block wasn't getting the last selected line. Fixed. + Hacked scroll editor so it wouldn't crash when removing lines. Scroll code either needs to be 100% overhauled or replaced by robots somehow... + Fixed config files not being closed. + Added include file option for config files. Use it like this: include "config file"; e.g., "include subconfig.cnf" will load subconfig.cnf's options. + Fixed freadN not terminating strings. + Fixed graphical glitch when using the mouse in the char selector. + Fixed save games crashing when they can't load fopened files. + Fixed some other problems with save games and fopened files. + Accidentally had title screen running a bit slow... + Value strings starting with ( not parsed as an expression if they don't end with the ). + Fixed problem with key_code being triggered for keys that aren't in-game. + Added extended macros. This allows for parameter based macros to be entered in the robot editor via a window or by command. See macro.txt for more information. + Fixed player cloning after flip/mirror and player placing. + Added random seeding that was mysteriously missing... + Finally added drive changing for Windows builds. + Fixed mousex/mousey for resolutions other than 640x350 (only applies to fullscreen). + Fixed crash on weird invalid death/endgame boards... + % and & messages clip correctly now. + Fixed potential crash on double closing the files. + Fixed crash bugs with placing sensors and maybe scrolls. + Fixed sending sensors when you have robots of the same name (fixes Weirdness chapter 1). - Removed the unimplemented if player dir and if not player dir commands from RASM. Table of Contents December 26, 2004 - MZX 2.80f + Fixed a bug that could cause crashes when auto-quoting params in the robot editor (eg, set x 1 -> set "x" to 1). + Fixed a bug that could crash the robot editor if you added a new line prior to the first line of a marked block, then did an action on it. + Fixed a bug where clearing the first and only line could cause it to appear as if it hadn't been cleared at all. + Unified global and global next parameter setting so that nothing is lost between first/next but information can be cancelled without application. + Fixed E/S block markers appearing in the robot editor when they should be off the screen. + Left click position in robot editor mysteriously disappeared after having been added somewhere after 2.80d. Re-added. + Added option to hide the hotkeys help and horizontal border in the robot editor with alt + h. Also added a config.txt option to have it default this way. + Search/replace in the robot editor. ctrl + f to find or replace/replace all, ctrl + r to repeat either search or replace (depending the last one you did, if you cancelled this does nothing). + The load_game counter sequence was broken; fixed. + Hopefully fixed all means of overrunning the current line max length in the robot editor... + Fixed robot editor validation not showing every 13th line. + Fixed aesthetic problem with validation report... + Fixed crash with setting message column less than 0. + A couple things added for 2.80e mysteriously disappeared in source handling. Re-added. + Changed max board size prevention to auto resize the lower dimension to the max that can be handled with the higher (ex, 30000x25000 becomes 30000x559). + Added flood fill to char editors (alt + f). + Added single depth undo to char editors (alt + u). Table of Contents December 19, 2004 - MZX 2.80e + Fixed a bug causing problems with static overlay if a non-overlaid sprite is displayed so it's clipped off the edge of the screen. + Fixed a bug in the display of c?x color boxes in the F2 menu in the robot editor. + Fixed a bug that caused incorrect thisx/thisy for one cycle after copyblock. + Fixed a bug preventing calls to nonexistent subroutines from passing that point in the robot. + Fixed crash on sam 0 "file". + Fixed a bug where loading new SFX may not correctly overwrite previous ones. + Fixed a bug where you could only load/unload so many mods before MZX couldn't load anymore.. same bug as the SAMs but went unnoticed! + Fixed a bug that caused you to be infinitely stuck in the global settings dialog box when you press previous on the next page. + Fixed a bug where going to next then exiting would not save the changes from the previous page. + Fixed a bug that could cause crashes while ending modules. + Fixed a bug that could do the same kind of thing with sams. + Fixed an allocation bug when loading MZX worlds that could lead to crashes. + Fixed a bug that caused MZX to crash if you interpolated an expression with a value equal to or greater than 1 billion. + Fixed a bug where mixing ccheck1/2 with sprites from board and vlayer could cause problems (that's the short version of the explanation, I'll spare you the long one). + Fixed a bug that could cause certain old MZX games to crash after the title screen + Somewhere broke missiles between 2.80c and 2.80d. Fixed. + Fixed error in lit bomb anim sequence setup in char ID editor. + Reworked a lot of robot editor code; adding/deleting lines while marked areas are active should work more naturally now and it's hopefully no longer possible to crash it in the same ways it was previously. + Fixed crash when setting mesg row to less than 0. + Fixed mouse presses not working in the robot editor. + Made MZX ignore alt + tab so you can safely switch in your WM without it triggering... + Added numerical key entry for number boxes. Use 0-9 to add to the most significant digit and backspace to take it away. + Added config.txt option to make MZX pause when key focus is lost (when clicking on another window, perhaps) or when it's minimized. Music will still continue. + Added save/load position to the editor. Works for loads in between boards as well. Press ctrl + num to save to slots 0 through 9 and alt + num to load from that slot. Please press shift + 8 or the numpad * key instead of alt + 8 to set mod wildcard. + Fixed a further bug that could cause playing samples to crash. + Added config file option to revert the robot editor to the default palette when loaded. + Fixed bug in shoot command. + Fixed error when making save name in editor but cancelling. + Auto-backup - see config.txt for details. + Joystick key mapping - see config.txt for details. + You can now load game-specific config files by creating game.cnf for the corresponding game.cnf (for instance, caverns.cnf). This is mainly useful for joystick key mapping. Note that these settings will NOT go away if another game is loaded that doesn't have a .cnf. + Alt+enter finally works as block action in the robot editor. + Loading a .mzx/.sav from another directory indirectly (via command-line or robotic) will now actually change the current working directory. + Fixed bug that crashed MZX with ctrl + i in the robot editor. - Fixed maximum board size to about 16.7 million tiles (128MB) for now. - MZX now ignores the mouse scroll wheel instead of interpreting it as a click. Table of Contents October 9, 2004 - MZX 2.80d + Fixed cursor going invisible when escaping from import in the editor. + Fixed robot editor entry when pressing OK on global info. + Fixed lack of name for MZB import/export (any MZB's exported in prior beta versions still won't have a name). + Fixed some problems with setting the mouse position. + Fixed problem with exits not bringing you all the way to the edge if width over 400 or height over 200. + Fixed bug that cleared too much when increasing both width and height while resizing the board. + Fixed problem with 1 char shortcut commands with spaces immediately after them. + Fixed problems with load_robot and load_bc (caused crashes and infinite loops). + Optimized RASM heavily (this should be most noticeable when doing a lot of external robot loading from text files). + Fixed inability to use absolute paths in loading a game from command line. + Fixed lastshot/lasttouch conditions with directions not working. + Fixed char editor in robots not going into SMZX mode when proper. + Cleaned up source code so it passes -Wall without complaint and in the process corrected some glaring code errors that may have corrected random problems. + File opening broken in 2.80c, fixed. + Implemented MZM2 saving and loading and rewrote mzm.cpp (if anything is changed or fixed regarding MZMs, attribute it to this). MZM2s can be of larger dimensions, smaller filesize for same amount of data, and can store robots. + Fixed bug that could cause MZX to crash when making new strings. + Block operations to overlay when overlay was off caused crashes - fixed. + Fixed a problem with sprite ccheck2 against other sprites. + Optimized function counter lookups a bit; speed gain for all counter accesses (especially ones that begin with certain characters such as _). + Fixed disassembly error with ' ' character. + Fixed assembly error where condition extended dir (such as blocked opp seek) was not getting compiled with the dir extension. + Fixed editor bug where the param was not being cleared when overwriting things by double placement. + Fixed inability to use counters with playercolor/bulletcolor/missilecolor. + Added ability to use counters in place of p?? in the robot editor. Note - even though this expands functionality of the editor this does not require a version number change because the worlds will still be playable in older MZX versions (and will display correctly in the robot editor - you simply won't be able to correctly edit the commands). + Mouse correctly limited to screen edges now. + Fixed inability to overwrite robots with pushable robots and vice-versa, as well as scrolls with signs and vice-versa. + Possibly fixed problem with windowing error when editing global robot (?). + Fixed disappearing cursor after color selection box with mouse (and other places?). + Fixed bug in sprite clipping that caused some to be clipped off inappropriately. + Made board_id/board_param counters readable. + Added bound checks for all counters using board_x/board_y/overlay_x/overlay_y. + Fixed potential direction corruption bug causing directions not to work sometimes even if they display correctly in the robot editor. + Fixed copy overlay to MZM copying to overlay too. + Fixed a bug where debug window could display the wrong amount of robot mem and potentially even crash MZX. + Fixed help_menu counter not doing anything (durr). + Changed sprite draw order so they're drawn underneath the message bar, debug box, and time remaining display. + Changed put p?? in Robotic so it will put default params if available. + Fixed a bug that could cause copies from overlay to vlayer to not end up at the correct destination. + Fixed a bug where c?x and cx? would not display correctly in the robot editor. + Optimized copy blocks a bit using variable length arrays instead of malloc. - Removed ability to put robots, scrolls/signs, and sensors (with the put command in Robotic). Table of Contents August 16, 2004 - MZX 2.80c + Fixed issues with the commands counter not being reset. + Color intensity now gets reset when you enter the editor + SAMs got cut off sometimes now.. fixed. + Fixed bug where loading a world with empty boards could change the starting, endgame, and death boards. + Fixed bug where you could text enter off the bottom of the board, causing problems. + Fixed bug involving cutting/clearing the entire robot in the robot editor while not at the first line. + Fixed robot name entry for global robot not disappearing on small boards. + Fixed bug where you could duplicate the player by holding down a direction as a saved game loads. + Fixed bug where you could go to line 0 in the robot editor. + Saving an MZM now auto-adds the .mzm extension... + Fixed black screen on quicksave. + Fixed bug where opening a file didn't close the old one if one was open (so it'd eventually crash MZX). + Changed Alt+backspace behavior in intake so it doesn't exit. + Added clipping for refx/refy/width/height for sprites (less than 0 at initialization, greater than board width/height at draw). + Fixed direction parsing for move all. + Fixed bug where creating things on top of the player would use a slot for robots/scrolls/signs/sensors instead of just copy to the buffer. + Added ability to use chars as immediates in Robotic commands (ie, set "$str.0" 'a'). + Added options to enable oversampling and specify resampling mode in the config file (higher quality audio). + Building with patched modplug that fixes loading 2-channel mods outputted by FT2. If you're building yourself, see build.txt. + Fixed inability to mouse click in alt + h mode. + Fixed ability to mouse click outside of board range. + Should work better for Linux users; case insensitivity for file opens has been added. + Fixed close bug that was affecting Linux builds (may affect more). + Keypad enter works where normal enter works now. + Fixed disappearing cursor when cancelling out of abandon changes box when loading a new world in the editor. + Fixed problems when loading/saving robots outside of ID range (do not hardcode ID's people). + Fixed problem with NO BOARD exits being set to something else when empty boards were being stripped or when worlds were being imported. + Fixed bug where auto-decrypting worlds didn't work if the XOR value was negative. + Fixed problem with rid not working the first cycle. + Fixed inability to interpolate (with &&'s) counter names larger than 14. + Added new robot mem counter in debug box (only kb precise, rounds up). + Fixed ability to clone the player on non-title board after testing. + Lengthened size of mod name buffers. + Fixed bug where send x y doesn't work from the global robot. + Fixed a few bugs that could cause MZX to crash. Table of Contents August 11, 2004 - MZX 2.80b + Made it possible for robots to move through teleporters. + Fixed bug with pressing shift in text entry boxes. + Made it so alt + tab does not switch draw modes in editor. + Fixed a disassembly error for color intensity N percent command. + Fixed problem with looping on mods that do not loop explicitly. + Fixed alt + dir scrolling in the char editor. + Fixed not being able to click the rightmost char in the char editor. + Re-added unmark (alt + u) to robot editor (mysteriously disappeared??). + Fixed key label so it returns proper unicode values. + The player and pushable robots can now be pushed by the push command. + Fixed bug where you could clone the player by switching boards. + Fixed bug where you could either turn off overlay or switch to boards that don't have it while in overlay edit mode... + Fixed bug where remains of debug window would not be cleared in editor if the board width is too small. + Fixed bug where turning off the menu with a board too small would mess things up. + Fixed bug where run lengths were saved one too large... this could fix stability problems in at least occasional cases (with saved worlds or save games, at least). + Fixed placing solid things beneath robots (like bombs). + Added support for a keyboard plus in the char editors. + Fixed previous button in SFX editor. + Made robot name box disappear when robot char box comes up... + Fixed bug where mods restart after pressing P if they're the same mod as what was playing before. + Fixed problem with changing params (with P) in the editor. + Fixed bug where null boards were not being pruned from old worlds upon load. + Made file name saving box larger (for saving games and worlds). + Fixed bug where default (100%) palette intensity values would not be applied to the palette a game loads with. + Fixed bug where exporting char sets that are full size caused a 0 byte charset to be exported (8bit wraparound). + Added support for forms such as :line. + Fixed sporadic incompletion of strings without trailing quotes at the end of the line. + Fixed bug where clearing/cutting the last line of a robot crashed MZX. + F4 in robot editor now works more generally. + Made line numbers in robot editor error report start at 1. + Added ctrl + G to go to a line in the robot editor (ala nano). + Made it possible to change a robot's color in the editor + Fixed bug where spitfire, seekers, and missiles didn't hurt something immediate adjacent to whatever shot it. + Fixed editing of spitfires. + Made default speed 4 again (5, bleh). + Re-added quicksave/quickload. + Re-added F8 clear (always works - be careful). + Fixed autorepeat problems for spacepressed/delpressed. + Wrapped around sprite values so LogiCow's bad code would work (HTMCIAB). + Cleared block commands in between board changing and other things like that. + Fixed bug where MZX would crash if put dir player overwrote the robot doing it. + Fixed bug where playing SAMs would eventually crash MZX + Fixed some mod * problems (hopefully?). + Fixed bug where pasting blocks over the edge of the board in the editor would cause MZX to crash. + Uses new GDM2S3M source that fixes some bugs. If your converted GDM's have problems, delete the S3Ms it generated. - Removed export text in the board editor. Don't think anyone wanted it... Table of Contents August 9, 2004 - First release, MZX 2.80 BETA + All ASM files have been rewritten to ANSI C compliant C++; this mainly involves the mammoth game2.asm. + Everything graphics related has been replaced with an SDL driven engine, including text mode rendering (also capable of rendering SMZX modes). + All keyboard and mouse events are now also handled by an SDL driven engine. All internal keyboard/mouse routines use SDL keycodes; no attempt was made to convert to MZX's old format at this level. + All world/board/robot loading and saving code has been entirely rewritten and is more modular now. + All robot handling code has been rewritten from scratch, and is more sane/efficient now (allocation, message sending, sensors, etc.) + All counter handling code has also been rewritten from scratch. This includes the functionality of builtin and "function" counters. It also includes a new string framework. + The robot interpreter has been almost entirely rewritten. + The main game playing code (game.cpp) has been almost entirely rewritten. + All module/sample playing code has been rewritten to use modplug and SDL. PC speaker effects are emulated. + The main part of the editor (edit.cpp) has been almost entirely rewritten. + The robot editor has been entirely rewritten, utilizing a modified (fixed) version of RASM (released by me over a year ago) + All other source files (for instance, window handling code, scroll displaying, char editor, etc.) have been largely overhauled, some to more of a degree than others. At the very least, everything has been reformatted and made to work with the new systems. + key_pressed and key_code now return unsigned chars instead of signed, so if the game checks for negative values, it won't work. The same goes for reading back characters for strings. + Boards may now be as large as 32767x32767. Please do not make boards this large. :) + You may now have up to 250 boards. + Boards may have up to 255 robots, 255 scrolls, and 255 sensors. + There is no robot memory per board limit. However, individual robots may only be up to 64k large. If you include the global robot, this means that you effectively can have up to 16MB of robot memory per board. + The same applies to scrolls, which have separate memory spaces and may only be up to 64k in length each (so you could have almost 16MB of scroll text per board, but who would want that??). + The robot stack need not be initialized, and will be dynamically resized as necessary (useful for recursion). This refers to lines such as . "#*-1-2-3-4-5-6-7-8" at the beginning of robots. They're no longer necessary or useful (they will be ignored, like any other comment). + You may have a virtually unlimited number of counters active. The theoretical limit is some 4 billion. The effective limit depends on memory available. + The same goes for strings, which may now have any name, so long as it begins with a dollar sign ($). The same conventions regarding strings in 2.68+ still apply (see 268_info.txt for more information). + Local2 and local3 no longer have dangerous side-effects. Local4 through local32 are also available per-robot now. + The following are now natively supported: XM, S3M, MOD, MED, MTM, STM, IT, 669, ULT, WAV, DSM, FAR, AMS, MDL, OKT, DMF, PTM, DBM, AMF, MT2, PSM, J2B, and UMX. + You can now perform repeated copies by selecting "Copy (repeated)" from the block command window. This will cause you to repeat the copy indefinitely until you press escape. Also, after the first paste is made, you may press ctrl + direction to move in steps that are the size of the copy (you really have to try it to get a good idea of what I mean). + Press alt + H to hide/unhide the menu/information occupying the bottom 6 lines of the screen. + Right click is similar to pressing insert (grabs whatever's under the cursor). + Exporting char sets now gives direct options to set the size/offset for partial charsets. The old format (prefixing the name) will not work. + For saving files, you may make filenames larger and use mixed case (as opposed to all caps). + Now when you import worlds their exits will actually work. + Loading worlds results in all empty boards and empty robots/scrolls/sensors within the boards being removed. When you delete a board, you won't be presented with a gap in the board list anymore. + You may once again select ASCII as a default charset and revert to it in the char editor. You may also select a default SMZX charset. + Anywhere you can enter a line of text you can now press ctrl + left and ctrl + right to go to the previous/next word. + This isn't totally limited to the editor, but now everywhere a selection box shows up (such as for files, boards, items) you can press multiple keys to seek to a specific entry. Furthermore, in file selection boxes you can press backspace to go up a directory. + The SMZX char editor has been changed quite a bit. First, to use, you must be in SMZX modes 1-3 (toggle using F11). Within the editor, press keys 1 through 4 to change the "current color." You can place this color with space, and you can toggle repeated placement on/off using tab (sorry, no clear/toggle in this mode, they got in the way far more than they helped). You now move in increments of 1 char naturally instead of "half chars." Right click grabs the current "color" underneath the cursor. + You are now able to type invalid code within a robotic line. You will see that it's invalid due to the way the line is color coded. If you try to escape while any lines are invalid or if you press alt + V, a window will be brought up describing the nature of all erroneous lines. It will also let you mark each line to be deleted or commented out on exit. If all invalid lines are marked with anything besides ignore, you can exit safely. You may also mark invalid lines using ctrl + I, D, and C (to mark as ignore, delete, and comment respectively). ctrl + C may also be used to comment out a normal line, and then uncomment. + alt + O is still available, but you may only change macros here (see the config file for the other rarely used options). This does give you more room to modify macros, though. They may be up to 64 characters in length, and you may set up to around 45 or so in this window. (To get larger, you'll have to use the config file.). + Command line params have changed. + MegaZeux configuration information is now stored in a file called config.txt. - There are some slight discrepancies in robot size; if you highlight the last line then leave it, it will register as a compilation of that line. Yet, when you exit, the line will be discarded, so this addition is not permanent. This shouldn't be problematic. - alt + enter and alt + escape no longer work; use the alternatives (alt + b and alt + u). - You cannot click on help options to make it happen (for instance, you can't click on L:Load and expect it to bring up the load window). - You cannot import or export ANS files. Use MZM instead. - Some things that worked in the DOS version only worked due to chance, such as there being default (but valid) values for sprite widths or heights and thus sprites could be displayed before new values were set. They will not work here. NEW in MegaZeux! New in Versions 2.92 to 2.92f New in Versions 2.90 to 2.91j New in Versions 2.84 to 2.84c New in Versions 2.82 to 2.83 New in Versions 2.81 to 2.81h New in Versions 2.60 to 2.70 New in Versions 2.01 to 2.60 New in Version 2.00 New in Versions Through 1.03 Table of Contents

New in Versions 2.60 to 2.70

**NEW in 2.70*** + Robotic code now loadable and savable to files, either to text files or compact but human-unreadable bytecode files. Other robots' code can be written to or read as well. + Defaults changed to more accepted values. + The swap world bug should be fixed. You should now be able to swap worlds back and forth with no trouble. + "atan" now works with any input/output value. + The "load_game" command now should work without any problems. + It should now be easier to compile MZX from the source. + It's not really a bug fix, but the palette is now returned to its original colors. + Robots can now 'put' things underneath themselves: eg. put c04 carpet p?? under. + The title screen menu now works: e.g. the menu you get when pressing 'Enter' on the title screen. + "key_pressed" now returns the twos-complement of the key value, i.e. the one used for :key? + The mouse can scroll across the whole screen after a screen refresh / transition to/from SMZX mode. Table of Contents **NEW in 2.69c*** + Sprite limit expanded from 64 to 256. + New sprite flag added: sprN_ccheck mode 2. + Vlayer added. This is a virtual, unseen layer 32767 in size used to store graphical data. + World loading and saving through Robotic now possible. + Special class fwrite_modify; this allows editing of a file as opposed to overwriting. + File end seeking added. + Char file offsetting added. + File seeking added to editor. Table of Contents ***NEW in 2.69b*** + Fixed the fwrite_append problem RoSS mentioned. + Fixed the string problem Nanobot mentioned. + Added ridNAME as an alternative to robot_id_NAME. + Added mouse_mx and mouse_my to determine mouse motion in "mickey" units. + Added two local counters "local2" and "local3", local2 uses walk_dir and is_locked (so walking and locking will affect it), local3 uses last_shot_dir and last_touch_dir (so shooting and being touched will affect it). + Added the builtin string "robot_name" to determine the name of the robot invoking it. + Reverted back to BWSB 1.20a again, in the hopes that it will alleviate swap world crashing a bit. Table of Contents ***NEW in 2.69*** + if "$stringN" = "literal" should now work. + Embedding && or () in names for save/load files for MZM saving and the like should work now. + Expressions won't be activated in pre-2.68 games, meaning if they used the constructs which would be valid expressions they should be okay. + More minutiae. + key_code, a more useful key_pressed alternative, added. + SMZX mode 1 returns. + SMZX mode 2 added. Table of Contents ***NEW in 2.68*** + Expressions added. + Trigonometric capabilities added. + MZM file capabilities added. + Board and overlay can now copy block to each other. + Saving and loading of SAV files through Robotic added. + String commands totally redone. + Now, instead of using value/sqrt_value/abs_value you may use a value with the counter directly as such: * sqrtN * absN + fread_pos/fwrite_pos and page should work correctly now; when you increase the pos it should bump up the page too. + pixel_x, pixel_y, char were broken in 2.65; fixed in 2.68 + strings had some bugs in 2.62b+, should be fixed now because of a separate implementation. + MZX Robot files are now saved to save files, so if you have a read and/or write file open and the game is saved, if the game is loaded the file will be restored at the position it was at. Table of Contents ***NEW in 2.65*** + Shows current mod playing in debug window + Misc new counters: (ro = read only, wo = write only) * fread_counter (ro), fwrite_counter (wo): reads/writes a full counter from file * board_w (ro), board_h (ro): returns current board width/height * robot_id_(name) (ro): returns the ID number of robot "name" * r(number).(counter) (ro): returns the value of the local counter for the robot with the given ID. Note that you cannot write to another robot's counter. + You can now save partial charsets in the editor. + Sprites added; limit set at 64 global. + Counters now representable in hex. + Subroutines added. Table of Contents ***NEW in 2.62*** + Strings added; limited to ten strings. + "mod_order" counter: reports the current order (that is, pattern) the playing module is at. Used in conjunction with the jump mod order command it can be used to save/restore a mod position between boards... - MZX 2.62 files are no longer forward compatible. That means that a file made in MZX 2.62 will NOT work in any previous versions (but it WILL work in future versions, so long as they set the version string correctly). - The string reading from files may not work correctly on the first read (that is, it might truncate the first character of the string). For this reason put a junk string in the first part of the file and read it first. Table of Contents ***NEW in 2.61*** + Game speeds have been normalized. + Original startup color scheme implemented! + Redocumentation of a few features left undocumented. - Password protection has been fully removed.

***

NEW in MegaZeux! New in Versions 2.92 to 2.92f New in Versions 2.90 to 2.91j New in Versions 2.84 to 2.84c New in Versions 2.82 to 2.83 New in Versions 2.81 to 2.81h New in Versions 2.80 to 2.80h New in Versions 2.01 to 2.60 New in Version 2.00 New in Versions Through 1.03 Table of Contents

New in Versions 2.01 to 2.60

2.60 release: + File access + Menu activation/deactivation + Current key pressed detection + Easy access to all 16 bits of a counter + Pixel editing of a char set + Single Byte editing of a char. + Real player distance + :key# added: gives twos-compliment of key value. - SMZX removed. - inter robot targeting removed. - Random color startup removed. Table of Contents 2.51ak1.0 release: + Added Numerous new Counters + Added new inter robot targeting system + Added new SMZX mode, dynamic resolution setting + Fixed fatal crash when taking a picture, also increased the number of picture you can take to 99 + Removed Built-in ASCII charset + Added Random color start up Table of Contents 2.51s3.2 release: + Removed password protection + Added new counter BIMesg to turn off built-in messages Table of Contents 2.51s3.1 release: + Fixed damage table, now works correctly + Fixed unworking Alt+s + Fixed screenshot name + Fixed strange missile color when firing Table of Contents 2.51s3 release: + Fixed bug involving savegame name being overwritten by mod name + Fixed overlay transparency weirdness. Now, background of lower layer will ALWAYS show through if background of overlay is 0 + Added in kev's refresh screen support. Press Alt+w on the title screen or editor screen, and = in the game(don't ask, has to do with mzx's keyboard handler). Use this if your charset gets corrupted in windows. + Screen shot saving rotates file name(starts with screen0.pcx) + Fixed bug involving incorrect loading of mzx health etc. Table of Contents 2.51s3final release: + Fixed bug involving mod * settings being lost when loading + Should have fixed ems problems some were reporting, if not, just try to get more conventional memory. Enclosed document (convmem.txt) should help you. + Fixed a bug involving direction checking. + Pressing ']' at most any time will now save a screenshot to screen.pcx + Pressing Alt+8 in the editor will set the current mod to *. Table of Contents 2.5.1s2beta release: + Added MOD "*", which allows a board to use whatever module the previous board was using; this necessitated a change in the .SAV file format (still need changes in the editor UI to access this feature outside of Robotic) + inmate's semantics for MOD "SOMETHIN.MOD*" aren't immediately possible, although a rough hack is in already + char edits are now not displayed until the beginning of the next cycle; the deferred display should eliminate a lot of flickering + an (at least partial) fix for the infamous UNDER bug + MOUSEX, MOUSEY and BUTTONS are now buffered. + more sane magic handling + can load MZX 2.51 and 2.51S1 worlds, but will only save 2.5.1spider2 format Table of Contents 2.51s1beta release: + Increased counters to 1000. + Added following counters: (ro) is read only, (r&w) is read + write * (r&w) MOUSEX, MOUSEY - Location of mouse cursor over the screen. * (ro) BUTTONS - Status of the buttons (none=0,left=1, right=2,both=3) * (ro) MBOARDX, MBOARDy - Location of mouse cursor over the board. * (ro) SCROLLEDX, SCROLLEDY - Length the screen has been scrolled in each direction. * (ro) PLAYERX, PLAYERY - Location of the player * (r&w) CURSORSTATE - Turns on & off the hardware cursor (0= off, 1= on, 0 default) + Added new independent counter like LOOPCOUNT, named LOCAL, it's now possible for a robot to search the screen or something without wasting a counter. + New .MZX and .SAV formats for MZX2.51S1. + .SAV files from 2.51S1 are incompatible with 2.51, and vice-versa + 2.51S1 is capable of loading 2.51 .MZX world files. - 2.51 is not capable of loading .MZX files created or opened & saved in 2.51S1 Table of Contents

NEW in version 2.51: ALL NEW music/sound code! 32-channels;

bug-free; support for stereo, 16-bit, GUS, and PAS-16;

support for many formats and effects; up to four

simultaneous sound effects!

Note that the new music support requires that you CONVERT all non-MOD files using the included program, 2GDM. See 'MegaZeux's Sound System' for details on the NEW music system. MegaZeux's Sound System Note- This is a direct translation from the file WHATSNEW.251, included with MegaZeux. If you haven't used version 1.03 or before, you probably won't understand much of this list. New in version 2.51: (quick fix before I do 3.00!) * Bug where moving north or west towards a board that is larger than 100 tiles in a dimension may not work properly fixed. * Bugs in 2GDM.EXE preventing proper conversion of some S3Ms fixed. * A rare bug preventing internal MOD conversion fixed. * "Error opening MOD" will no longer appear during normal gameplay. * Exporting ANSis now adds a color to the end returning text to normal grey. Table of Contents New in version 2.50: * FOR ALL YOU 2.07 USERS- THE MAJOR UPGRADE is the new sound code! Support for stereo, 16-bit, more cards, 4 sound effects channels, 32 music channels, higher quality, and faster sound code! Less bugs! More formats supported! All non-MOD files MUST be converted to GDM using the included 2GDM.EXE program. Formats supported- MOD (up to 32 channels), WOW/OCT/NST, S3M, 669, and MTM. * Volume controls (overall and SAM) added to F2-Settings (saved in .CFG file) * SAMs play at 2x volume. * MTM support added to 2GDM.EXE. Other formats aren't added because they aren't needed (not used often enough) or in the case of XM, because they support too many advanced features that MZX does not support. Partial XM support MAY be added later. * Many minor bug fixes in 2GDM.EXE's conversion routines. * Internal MOD conversion (in MegaZeux) sped up considerably. * For all those that upgraded from 2.07, see 2.49g and 2.48b WHATS-NEW for more stuff, including a couple interesting new Robotic features Table of Contents New in version 2.49g: * New Import function added- You can import an ANSi to any position on the board. * Full SAM sound effect support as in the original 2.07 version (but using the new MOD code for up to 4 simultaneous channels) * The OPEN Robotic command will now push the Robot out of the way if the door would be blocked by the robot. * REL PLAYER and REL COUNTERS now affects the THISX/THISY counters (giving the distance FROM the player/counters TO the Robot) and the prefixes also affect the IF [dir] BLOCKED command, allowing you to check for blocked status next to the player or an arbitrary position. * [ box message statements now clip their message to 64 characters (the maximum) on display. Note that all other box-message statements are NOT clipped! * Color codes are allowed in ? and & box message statements * Invalid sound card settings no longer cause a lock-up * You can hold down the mouse button to cycle through RGB values in the palette editor * Changing something to an explosion no longer can cause weird colors * What's New section of help sorted by version * Placing a robot over the player is prevented with a warning * The "Alt+N- Music" lights up properly in the editor now * When changing from a larger board to a smaller board, you can no longer accidentally have the cursor outside of the board size. * GUS owners don't need to enter # of SFX channels, since MegaZeux cannot support GUS sound effects anyways. * File boxes (loading MODs, worlds, etc.) can now hold as many filenames as memory allows. * GUS setup shown properly on configuration screen * 2GDM.EXE rewritten- In THIS release, it can only convert MOD, NST, WOW, OCT, 669, and S3M files! The final (2.50) release will have support for the remaining file formats. It is being rewritten to fix many small bugs and make it smaller and faster, as well as possibly add more file formats. * 2GDM.EXE- F00 effect in MODs deleted during conversion * 2GDM.EXE- Bad effects S8x, S0x, and Xxx deleted during S3M conversion * 2GDM.EXE now works properly from other directories * INTERNAL MOD loading support. You can now load MODs, NSTs, WOWs, and OCTs from within the game without having to convert them to GDM first. The only exception is 15- instrument MODs- they must first be converted. Note that all other formats, such as S3M, 669, etc. must still be converted. NST/WOW/OCT support was only added because they are extremely similar to MODs, and MODs were required for backward compatibility. * Insert doesn't display those "Lo bomb selected" messages, etc. if the player is Attack Locked or settings say he cannot bomb. * Minor bugs in ANSi import corrected. (problem fixed- caused errors on import of ANSis with more or the same number of lines as the current board size maximum) * "Ammo <10" and "Ammo >9" entries in Global Chars changed to "Small Ammo" and "Large Ammo" to prevent confusion. Table of Contents New in version 2.48b: * ALL NEW music code! Features include faster, NO BUGs, 32 channels, more formats supported (sorry, no MID or XM) etc. * Bug where selecting "(no board)" to add a board caused an error if that wasn't the first "(no board)" on the list. * Bug where if a robot line entered consisted of only semicolons, spaces, and commas, it would screw up that robot's program, fixed. * Command line options (-port,-dma,-irq) added for setting sound card parameters. Only needed if auto-detection fails. * Minor help corrections. * Save/load during testing in editor disabled. * Pressing \ no longer causes problems during gameplay. * Bug where "Restart board" for death option in global options didn't function properly on first board, nor did restart-if-zapped. (fixed) * Filling in the overlay no longer locks up if you fill over something of the same color and picture. * Overlay no longer messed up when resizing board. * Lock up on Import World removed. * Setting the counter "INVINCO" to 0 works properly. * Hopefully fixed rare lockups after robot box messages. * Added confirmation for board deletion in editor. * All included worlds are NO LONGER password protected. (The old password was "megahertz".) * Minor bugs in passage search algorithms corrected. * Obscure bug involving REL prefixes if used in "infinite- loop" type constructs (fixed) * In editor- Alt+Dir to move 10 spaces now works as expected with draw mode on. (IE it will draw in ALL 10 spaces) * Bug where passages on screens wider than 256 spaces didn't work properly. (fixed) * Bug where fire-to-player's-right would lock up and kill him FIXED. * Counters can be used in ALL strings in &COUNTER& notation. For example, SEND "ROBOT" "LABEL&COUNTER&" will replace &COUNTER& with a number. This works for ALL strings - counter names, labels, robots, etc. See Robotic help for details. Table of Contents New in version 2.07: * Labels and NON-valid counter-regulated options in robot box messages are not blank lines; Instead they are just removed from the message. * Passage (stairs/caves/whirlpools) search algorithm corrected. * Digitized sample SFX works properly with the note B now. * Bug where getting multiple energizers in a row screwed up player's color is fixed. * Bug where chests with invinco potions will die when taken is fixed. * Filling in editor, with a robot/scroll/sensor over itself, is now handled properly. * Whee!! More minor help typos fixed. Table of Contents New in version 2.06: * Yet more cursor safeguards inserted. (Where do you GET these problems!? :) * Saving a game no longer asks for overwrite confirmation if the file doesn't really exist. * Help and tutorial- Minor textual errors fixed * Save dialog boxes only allow entry of 12 characters now, instead of 13. * Help file can be accessed from any directory. * -l cmd line option will no longer cause a loading error with an oversized filename. (it will instead be ignored) Table of Contents New in version 2.05: * Cursor bug fixed. (If it isn't, then get a new BIOS! :p) * MegaZeux now utilizes overlaid code, for almost 50k core memory savings. * LOCKSCROLL cmd fixed * Moving into the lower-right corner of full-size boards no longer warps you to the upper-left corner. * SET COLOR and COLOR INTENSITY don't blow up if the color is not from 0 to 16. * Code for activating 16 background colors is now shorter and uses BIOS calls for compatibility. Table of Contents New in version 2.04: * Slight modifications to Robotic Tutorial (help file) * Sending a robot a message, when it hadn't done anything yet that turn, activates it immediately. This helps with synchronized activities, such as large, multi-robot creatures. * Alt+Numerics feature of BIOS keyboard routine DISABLED (IE Alt+3 will no longer break to DOS) * Counters' code optimized. * The temp file DITRSZ.TMP created when resizing a board is now deleted when finished. * a KEYBOARD CODE kink was worked out (hopefully got 'em all...) * Made printer code more general (should work on any printer in text mode) * PALETTE BUG on some SVGA cards FIXED. (black now looks like black) If it still isn't, please notify me. * HOME and END will jump to the top/bottom of a box message/help/scroll. * PgUp/PgDn/Mouse navigation work properly in box messages/help/scrolls * HOME and END in dialogs works properly now- Unless you are editing a number, they will jump to the FIRST item and the NEXT or OK button, respectively. In a string, they will still jump to the start/end unless you are already there, then they will jump to the proper dialog location. * Robots (especially when there are lots of them) sped up. * DUPLICATE SELF and COPY ROBOT cmds sped up some, except when used by global robot. * Palette intensities reset when going into editor after the title screen changes them. * MODULO "str" # will no longer crash if # is 0. * Extreme palette activity no longer causes snow or (on EGA) screen breakup. Palette activity also sped up. * Bug fixed- If a SAM/MOD command had to free up board memory (showing the little "freeing up board memory..." meter) then that robot stopped running. * Bug fixed- If the robot changed it's surroundings (IE Putting a SPACE to it's NORTH) and then did a RANDNB or RANDB, the new surroundings weren't always taken into consideration. * DIVIDE ERROR crash/bug fixed. (It was related to usage of RANDNB and RANDB) * CHAR "A" vs. CHAR 'A' question added to F.A.Q. * README.TXT changed- Boot disk/support info added. * Help on cmd ."@string" corrected. * SPEED defaults to 4 (settings) and is saved in MEGAZEUX.CFG. Table of Contents New in version 2.03: * Intensity of palette (and other stuff?) now resets after a test game. * Messed-up black color on certain graphics cards- Attempted to fix. * Minor bug in VER1TO2.EXE fixed * Robot section of Tutorial corrected (the descriptor scrolls) * Speeds based on real time (IE speed 3 will be the same on ANY computer, unless the computer itself is so slow that it forces a slower speed.) * CAVERNS has game over screen fixed * MOVE PLAYER [dir] "label" command now works properly. (Before, the label was almost always ignored) Table of Contents New in version 2.02: * Bugs with Enter in text mode on small boards fixed * Bugs with slime fixed * If you have screen faded out (COLOR FADE OUT) and go to another screen, it no longer fades it in for you automatically. * HELP.DOC- CHANGE CHAR ID section fixed * Fill really does now fill properly on boards larger than 127x127. :) * Sped up sensor interactions somewhat * Fixed problems with boards not scrolling with the player, in the game on over-sized boards. Run FIX.EXE in all directories containing version 2.01 or 2.00 .MZX/.MZB files. * Nothing can give you negative coins, gems, etc. (such as thieves) * Minor robot speed improvements * Turning Music Off (Settings in Game) really keeps it off... :) Table of Contents New in version 2.01: * Sensor command CHAR'X' fixed * TAKEing health now counts as hurting the player for the :playerhurt label * Can load help from any drive/directory * Copy block in editor now properly clips the block's destination * Move block in editor now properly clips the block's destination * ."@new_robot_name" command added * If the player runs up against a player bullet, it won't hurt him * JUSTENTERED, JUSTLOADED, and GOOPTOUCHED labels fixed * UNLOCKSCROLL and locked scrolling in general fixed * Global info now properly sets endgame/death boards * Robot ASK command works properly now * Help- internet address/address validity date corrected * Help- CHANGE CHAR ID help section- added note about how the numbers are also listed in the Global Edit Chars menus * ENTER can now exit robot box messages/scrolls * Message line (bottom) shows color correctly * EXCHANGE/RESTORE w/DUPLICATE SELF fixed * Attempted to fix cursor problems in editor. If it doesn't work now, then I have no solution, as I use documented BIOS routines with many safegaurds. * Minor speed improvements * Minor size reduction * Fill in editor now works with board sizes over 127x127 NEW in MegaZeux! New in Versions 2.92 to 2.92f New in Versions 2.90 to 2.91j New in Versions 2.84 to 2.84c New in Versions 2.82 to 2.83 New in Versions 2.81 to 2.81h New in Versions 2.80 to 2.80h New in Versions 2.60 to 2.70 New in Version 2.00 New in Versions Through 1.03 Table of Contents

New in Version 2.00:

* All code has been rewritten or at least stepped through line by line, except for the music code. * New user interface style and startup screen. Lots of neat little items like shadows, nicer colors, etc. Mostly aesthetic but nice. Mouse support also improved. * Keyboard code rewritten (again) All Alt+lock, shift-lock, and ctrl+lock problems, as well as most other keyboard problems, should not be a problem anymore. You may have to use the -keyb2 command line option. If a key locks, tap it a couple times. * No flicker- The game engine now page flips. * Better string input- ANYWHERE you can enter a string, you can now move with the cursors and insert in the middle... * Better character selection box- Shows all the characters. * New default character set- Much nicer, more general use characters. * Now detects processor to avoid lock ups on an old 8086/8088. If an invalid graphics card is found, DOS services are used for printing. * Different command line options. (use -? to get info on them) * Context sensitive help. * Bombs and Sensors under the player no longer mess up floors, etc. * CHANGEing something to lava, fire, etc. now works correctly. * Transporting onto a Sensor works properly. * New conditions- MUSICON and PCSFXON * Changing things to spaces CLEARS them, to avoid screwing up floors. * Restart position not changed during a save/load * Label- :playerhurt for when player is hurt, not sent on invincible hurts * Maximum Robot commands per cycle is 40, not 25 * Global Robot runs normally in freeze/slow time * Choice of 100x100, 200x50, 400x25, 80x125, or 60x166 for each board. * Character editor remembers character you were editing. * Robo-P renamed to Robotic * Scrolls now allow proper use of mouse, pgup, and pgdn. * Scrollborder became Scrollcorner. * :gooptouched auto label added, for when the player touches Goop. * Messages like "You got a red key" are now "You got a key" so palette fiddling won't make strange words. :) * Within Robotic messages (box/line) a &INPUT& will be replaced by the exact text of the currently inputted string * Notes in play of same freq. won't run together * Explosions won't destroy entrances, lava, water, ice, or goop * Robots are stopped from firing if there is already a bullet of the same dir/type in that dir. * Other things will push the player ONTO a Sensor. * The above will trigger the SENSORON label. * If player is on an entrance without having been there before the update, use it. (I.E. can now be pushed onto entrances) * Teleporting or walking onto a screen and starting on a Sensor will trigger the SENSORON label * Non-players/puzzle pieces now transport properly. * PLAYERLASTDIR (0-4) and PLAYERFACEDIR (0-3) as counters. * Points for killing enemies (3) and points for rings/potions (5) * Way to disable edging spaces on message row- ENABLE MESG EDGE, DISABLE MESG EDGE. * Cmds- LOOP START, LOOP # TIMES, ABORT LOOP, uses Robot counter LOOPCOUNT * Counter limit increased to 50 plus built-in. * New passage search order- 1) Same type, same color 2) Same color 3) Same type, same foreground 4) Same foreground 5) Same type 6) Default player position * Palette import/export * If the starting board is deleted, change starting board to title. * "Sets of five" numerical input actually increase by fives * Holding the mouse button on a numeric arrow button cycles the num. * Removed the "." Directory from file menus * Six (not four) status counters. * CHANGE blah p?? blah p?? (notice the p?? added for the first thing) * Doors, if can't move, don't advance in anim. I.E., doors won't get "stuck" if they are blocked. * PERSISTENT GO command, like /"nsew" but WAITS to move if blocked. * No chest message on empty. * Startup "help" screen on first use. * Explosions Leave Empty doesn't mess up ANY floors, etc. * Much better fill routine. * Entering a non-cmd with the first character as a [, ., :, etc. automatically formats it. Leading and trailing spaces and quotes are cleared first. * Save/Load game/etc. are accessed through F-keys in the game. * Removed special menu for Alt+M (modify) in editor * In editor, keeps track of whether world has been modified. * Ceiling layer - non-interactive, but overlays things and looks neat. Included in editor- Edit, display toggle. Robots - changing it by character, copying areas of it, and filling an area of it by cmd or string (I.E. set area to "A string") Char of 32 is see-thru. Layer during game can be on, off, or static (I.E. not Scrolling, just showing upper left portion). * Robot commands to change the mode of saving. * Limit any one Robot/Scroll to 31k. * Allow placing shooting fire in editor. * Make all enemies without speed arguments move 1/2 their speed. * Player CANNOT be overwritten, you must place him anew to move him. * First line of Robot now shows if it is a box mesg. * Speed 1 in game does NOT page flip, for speed. * Inputted strings allow input of spaces. * Time limits- Out of time zaps to entrance automatically, THEN RESETS TIMER. Counter TIMERESET holds reset value for timer, and the TIME counter holds the current time. * MOD code has only an error on no memory. Errors for loading MODs and SAMs (I.E. not enough memory) are active if the debug menu (F6) is shown. SAMs have errors for file errors/ out of memory. These errors are always in the editor/testing games. * First test of a game doesn't give GAME OVER. * Sound effects aren't cut off across screens. * Placing a bomb while upon a passage no longed warps to title. * Sensors are pushable by things other than the player. * New Sensor-activated label- SENSORPUSHED, when the Sensor is pushed, with or without the player on it. * Label- JUSTENTERED when the player just entered the screen or the game is started. (NOT restored) * Command- Can lock/unlock board Scrolling temporarily- LOCKSCROLL, UNLOCKSCROLL. * IF ALIGNEDROBOT "Robot" "label" * Damage editing- Changing the amount of damage things inflict. * Load title screen directly when loading game for title. Prevents music on first board from playing, and saves time. * New Robot-specific auto-counters- (read only) THISX, THISY. * Anywhere a number can go in a Robotic command, a counter can too. Wherever there is a number, character, or color, you can use a counter name in quotes instead. * Cmd line- load MZX file. (-lxxxxxxxx.MZX) * Config file for options, ask "OK?" on startup. Removed all config cmd line options. * Cmd- SCROLLVIEW X Y. (upper left hand corner is specified) Based off of current player position. * Cmd- SWAP TO WORLD "world.mzx" as if starting the world up. Skips any title screen. (you could put a message there) The other world can have a "Only play from swap" option set. * Quicksave key in game- Saves without asking for filename and confirmation. * Quickload key in game- Same idea. * Option (default off) on world to clear messages, bullets, and spitfires from a screen when exited. * Label JUSTLOADED sent to as soon as the game is started or restored. (including the title screen and actual playing) * Shows character number on char edit and char selection. * Shows color number on color selection. * Multiple spots to SAVE/RESTORE/EXCHANGE PLAYER POSITION. (8) * RESTORE/EXCHANGE PLAYER POSITION with the option to duplicate the Robot to take his place. When the player moves back, the Robot is, of course, deleted. * Remove RANDOM POS/SIZE options. * Allow labels to interrupt in a Robot's box-message code and have the message still show uninterrupted. * Show a pic of the item next to it in the THINGS menus. * Different bullet pics/colors for player, neutral, and enemy bullets. * Status shown counters won't show if the value is 0. * Prefixes that affect only the first or last x y pair of a command. (REL COUNTERS LAST, REL SELF FIRST, etc.) * Mod fading commands (background) * Allow lives/health to max out at 65535. * Score as a counter. * Maximum of 150 boards. (not 127) * Cmd- COPY BLOCK x y x y x y. * Label for SpitFire hitting a Robot- "spitfire" * Label for Lazer hitting a Robot- "lazer" * Cmd- CLIP INPUT (chops first word + spaces off of input) * Cmd- IF FIRST INPUT "str" "label" * KEY1 through KEY9 labels. (like KEYA thru KEYZ) * Allow viewport sizes down to 1x1. * PUSH Robot command- push things to dir without moving there. * ONE global Robot. (No ID) Stored separate from a board, and is active on ALL boards. * Robots- Allow importing of a character into a CHAR EDIT command. * Robots- Have SCROLL CHAR, FLIP CHAR, and COPY CHAR commands. * Full backward compatibility w/old MegaZeux via a conversion program. (VER1TO2.EXE) * Editable built-in sfx. (including to digitized) * Elements- Goop, which is like Water from ZZT. * EGA/VGA palette editor, with easy fading. Commands- COLOR INTENSITY # PERCENT, COLOR INTENSITY "counter" PERCENT, COLOR FADE IN, COLOR FADE OUT, SET COLOR # TO r g b, SET COLOR # TO INTENSITY # PERCENT, SET COLOR "counter" TO INTENSITY "counter" PERCENT. (note- the FADE OUT/IN cmds are "quick" fades, IE not in the bk, but they actually stall the game a bit. They also end the current cycle.) * Display counters within strings, IE. * "You have &GEMS& gems." (use && for &) * Robot command- LOAD CHAR SET "file.chr" * New default characters for global chars and char set. * When adding another board, copy most of the options (can attack, etc.) from the current board, including MOD file. * Edit ANY character/color from Global Chars. * Char editor- Revert to ASCII, Revert to MegaZeux, changed REVERSE to NEGATIVE. * Alt+Y Debug info LABELs each line. * Block command- Paint (w/color). * Board editor- Scroll when cursor is five spaces from the edge. * Fade in/out between screens and program areas. * Ice does NOT keep pushing you against something. If you are blocked, cease movement. * Make sound test available in editor as an option, from the sound effects editing screen. * Can't test a save-locked game w/o pw, and it no longer locks up from this. * REMOVED Scroll coloring on line by line. (using ! codes) * Export .ANS file. * Energizer will return player color to old color. * Capture and throw away ctrl+C, PrintScreen, SysRq, and Pause. * Return in editor at end of program can now add a blank line. * Allow marking of a section of Robot, in lines. You can now Copy, Cut, Clear, or Paste blocks. * Remove useless "pro" mode. * Robot commands- DIVIDE, MULTIPLY, MODULO. * Different player pics per direction. NEW in MegaZeux! New in Versions 2.92 to 2.92f New in Versions 2.90 to 2.91j New in Versions 2.84 to 2.84c New in Versions 2.82 to 2.83 New in Versions 2.81 to 2.81h New in Versions 2.80 to 2.80h New in Versions 2.60 to 2.70 New in Versions 2.01 to 2.60 New in Versions Through 1.03 Table of Contents

New in Versions Through 1.03

1.03 release: QUICK FIXES, LIMITED DISTRIBUTION * TELEPORT command fixed * Gives error on attempt to test pw-protected world * "Explosions leave Empty" won't screw up floors, etc. (except web) * Placing a bomb over an entrance no longer warps to the title screen * INPUT STRING allows input of spaces Table of Contents 1.02 release: NEW: * Miscellaneous help errors fixed * Miscellaneous errors in Caverns fixed * Miscellaneous speed/efficiency code updated * AVALANCHE fully fixed, now can be entered into a robot * Timing code fixed (may fix some problems) * Slight modification to keyboard code (may fix some problems) * Added -keyboard2 option Table of Contents 1.01 release: FIRST "NON-BETA" RELEASE: * JUMP MOD ORDER 'num' has now been documented. * AVALANCE corrected to AVALANCHE. * Robot command GO DIR "LABEL" fixed. * Some minor help errors fixed. * Fixed bug where a BECOME THING command, if becoming a space, fake, or other "under"-type object, would not erase anything already under the robot. * REL TO PLAYER and REL TO SELF now work with the TELEPORT command. * If a robot (from WALKing) is sent to the EDGE label and none exists, it then attempts to find a THUD label as well. Table of Contents 1.00g release: FIRST PUBLIC RELEASE: * Removed ALL joystick support- Didn't work, couldn't get it to. * PW protect- lot simpler, faster, and easier to hack. :) * GLOBAL INFO- Toggleable game over music (you should correct this in all your pre-1.00g games) * Fixed misc. bugs in games. SOMEONE NEEDS TO TEST THEM ALL AGAIN FROM START TO FINISH. * Strings w/o quotes that begin with C or P are not capitilized funny. * Settings box no longer turns off music. * Alt-A in editor (param) gives error if there is not a legal "thing". * ALLIGNED fixed to ALIGNED (spelling error inherited from ZZT) * Fixed bug where if slow time or freeze time was active when player touched a door, player was copied. * Help- fixed slight bugs * Fixed minor problems in Caverns, Forest, and Chronos * MOD not required for SAM * Level not speeded up if MOD not playing * MOD not require a speed command (speed properly done) * Help uses Alt-P to print * Speed defaults to 3 not 4 Table of Contents 6th beta release: NEW: * Fixed bug where slow/stop effects didn't work on title. * Fixed bug in command MOVE PLAYER where it would occasionally create junk. * Fixed bug in robot editor where if "Show Colors" option (Alt-O) was off, any color with a ? for the second digit showed an incorrect first digit- cV? for cF?, etc. * The direction UNDER now works with the PUT thing dir PLAYER command. * Dir/drive support added to loading MZX fileboxes. * HELP IS IN ONE FILE- MZX_HELP.PKG (note- memory minimum is still maintained.) * Fixed bug where fire could hurt you indirectly even if lavawalker was in effect. * Fixed bug where nothing (except player) could push a pushable robot head on. (only if it was in a string of things to push) * Fixed bug where shooting fire would destroy entrances. * Fixed bug in Put commands that would erase before placing, so putting things over a fake or floor erased the fake/floor. (etc) * Change command- Didn't change params properly if you were changing between like objects (IE text to text) Also made more robust against attempts to change things to robots/scrolls/signs/sensors/players. * Put commands- Made more robust against attempts to put robots/scrolls/signs/sensors/players. * Fixed bug where no player on a board would really mean no player! * With Shift-F1 through Shift-F4 in editor, the key used to stop the flashing is not interpreted but ignored. * Sensor/Robot interactions! (See help) * PageUp will change menus in the editor now. (along with PageDown) * Removed all refrences (except in file format) to double speed robots and projectiles. Code increase is not worth it. * RANDB, RANDNB directions added! * Misc. help corrections and bug fixes, finished help. (except for minor changes) * Alt-O (options) no longer clears the command line at the bottom * Character insert in robot editor now inserts the characters corresponding to 10 and 13. * If you select base 16 in Alt-O options (robot editor) then ALL numbers are shown in hex, including when editing the line. (previously, the current line was shown in base 10 at all times.) * Chronos-Stasis finished. (not tested outside of myself) * Forest of Ruin finished except for ending. (see above) * Repeat (F4) and Delete line (Alt-D) added to robot editor * Copy, Cut, and Paste line (Alt-C/T/P) added to robot editor (note- paste REPLACES current line) * Export robot (Alt-X) added to editor. Exporting from current line or top of program both supported. * Import robot (Alt-I) added to editor. Importing only looks for *.TXT in the filebox. Import always REPLACES the current robot program. Table of Contents 5th beta release: NEW: * Fixed bug in teleport command where screen was not updated if player ended up in the same position. * Fixed bug where mouse didn't select right item on game menu * Fixed bug where adding a new robot/scroll/sensor when the current item was a robot/scroll/sensor would reset the color to lt.grey * Caverns all finished (hope I got all the bugs) * The DEF.COLORS option doesn't reset when changing/adding boards now * SAM now works right... * In fact, added new code for MOD and VOC- a LOT less "out of mem" or "error loading" errors. * Fixed bug with locked doors (not locks, but real doors) * Saving games and files is MUCH faster in almost all circumstances. Save meter more accurate as well. * Board import/export fixed- robots/scrolls/sensors were messed up * Pgdn, Pgup, Ctrl/Alt Home, Ctrl/Alt End added to robot editor. * Ctrl/Alt Left + Right used to jump 10 chars in character selection boxes. * Save area in character editor (F-2 and F-3) stays the same between calls to the character editor, including when loading games. * Character editor shows not only current char pic, but those of the three chars before and three chars after as well. * Fixed bug where a robot with no program would majorly mess up things. * Misc. bug fixes, help typos, and optimizations. !ADDED 14 COMMANDS (all commands finished) !ADDED 2 DIRECTIONS (randp, randnot) * Help brings up Robot Table of Contents within robot editor * Quotes not required around strings of one word not matching any reserved word, IE a word used for ANYTHING else, anywhere. They are added automaticaly, though. * EDITOR OPTIONS in robot editor (Alt-O) Choose number base, upper case or lower case, and whether to display colors. * Bug fixed in editor- Now colors like c7? (with ? at end) work right. * Calibrate Joystick button added to Game options (F2) Tony- See if this helps. * Speeded up certain file operations. This MAY fix the "lockup" bug when accessing Help during a MOD- I think that the lockup may of been just a really slow file access. * Added X position indicator to bottom left of robot window, to facilate creating box messages that aren't too long. * Fixed bug that allowed entering ANY character at the mixing rate prompt. * INPUT STRING, IF STRING "str" "label", IF STRING NOT "str" "label" robot commands added. * UNDER/BENEATH direction added to IF dir PLAYER thing "label" command. * Clarified options at startup- Music device became Device for Digitized Music and Sound. * Added four more mixing rates. Choose from 7500 up to 25000 in jumps of 2500. (eight rates total) Table of Contents 4th beta release: NEW: * Note- SAVE GAME FORMAT CHANGED. Delete all your .SAV files. .MZX file format NOT changed- compatibility still maintained. * Scroll border/etc. colors changable using robot commands- SCROLLBASE COLOR, SCROLLBORDER COLOR, etc. (see help) * Removed Alt-Minus and Alt-Plus keys in editor- Useless and dangerous. (they were only for testing purposes.) * Various bug fixes * Joystick support- UNTESTED! Tony- I need feedback! * Mixing rate options at startup. * A warning is given and verification is necessary if you try to save a .MZX file over an already existing file. * You can now choose from some additional music output devices. * Help is in seperate files, MZX*.HLP, to save memory. (lots!) * I FINALLY THINK THE MEMORY AND FILE CODE WORKS PERFECT! Except for speed. Something to work on... * Char editor shows values of bytes along left side, for use with robot command CHAR EDIT. * Yet more help * Robot editor! See the top box for keys to use (Import/eXport not implemented yet) * Robots as well! See Help, Robo-P Reference, Command Reference, and look at commands for help using them. Some are not done yet. * Video mode returns to default VGA mode (text 16x9) on exit * File lists sorted * Directory support and DRIVE support in file boxes WAS added, but was taken out due to problems since changing the current directory makes it almost impossible to find the current .MZX file to read boards from. * Custom Critical Error Handler (no dos grey messages if the drive is invalid or something like that) * Password displayed as *'s when inputting, except on protection menu. (Do YOU think it should be *'s on protection menu? 'T'? CP?) * Enemys-hurt-enemys option added (GLOBAL info, SPEC. button) * "Show Robots" option added (Shift F2) * More help added * Fixed sensor bug (The player couldn't move onto it in most cases) * Fixed a bug where if you tried to Grab something via the Modify menu and the current thing was a scroll, sign, or robot that had no copy anywhere else on the current board, then the memory allocated to that object was not freed. (whew!) * A few more optimizations * Mouse disapears after a certain period of time of non-use * Boulders from the AVALANCHE potion, and explosions from the BLAST potion can't appear over an entrance anymore * Fixed some bugs in Text Export * Removed .BIN import- Waste of program space * Made ALL options (protection, ANSi import) available in unregistered- now registration is only for the games * Removed "suicide key" from game. Think about how it could screw up carefully planned cinemas, story sequences, etc. * Mouse support in character editor * Test function added * Speeded up saves and board switches * Slowed down all file access (okay, so it's not a feature, but it's more reliable, as is memory management as well) * Made save meter more accurate * BLOCK COMMANDS! (in editor) * ZZT board import (not perfectly accurate, but...) * Bug fixed where games with the title screen title at maximum length would mess up the file list box * MOD (SB & speaker) support! (& SAM) * Explosion-meets-player bug fixed Table of Contents 3rd beta release: NEW: * Full mouse support (except in character editing) * No "pointer" mouse... * Scrolls and sensors * Robot code (memory management) mostly transparent to user * GLOBAL Info- Death & endgame options * GLOBAL Info- Removed "Health Only/Lives Only" options * CW/CCW support * Sound always the same speed * Bug fixes and optimizations * Status Info added Table of Contents 2nd beta release: NEW: * Cmd line options * Mouse support (not finished) * -Bios option * Hopefully fixed Tony's graphics bugs (try it with and without -bios) * Bug fixes * Tutorial.mzx has creatures/guns sections * Fixed/better/changed keyboard routines * Optimized code NEW in MegaZeux! New in Versions 2.92 to 2.92f New in Versions 2.90 to 2.91j New in Versions 2.84 to 2.84c New in Versions 2.82 to 2.83 New in Versions 2.81 to 2.81h New in Versions 2.80 to 2.80h New in versions 2.60 to 2.70 New in versions 2.01 to 2.60 New in version 2.00 Table of Contents