Information Topics

General Information

• History of ZZT
• The Making of ZZT Ultra
• ZZT Ultra Component Summary
• Fall of ZZT: The Curse of Production Quality

ZZT World Support

• List of Supported Worlds

Reference

• ZZT Ultra Editors
• ZZT-OOP Reference
• ZZT Objects and Behaviors
• File Formats
• Program States and Modes
• Downloading and Deploying ZZT Ultra

Miscellaneous

• Other Links
• Contact Info

ZZT Ultra Program States and Modes

When programming the ZZT Ultra environment, a designer normally only needs to be concerned with type, grid, and code definitions. The underlying architecture of the engine that makes all this possible is not, under most circumstances, very important to this end.

However, it can be useful to understand what states and modes ZZT Ultra supports as part of its internal operation. The following "main modes" are handled by ZZT Ultra as it runs.

Initialization Modes

This is the initial startup mode as ZZT Ultra is loading. It transitions soon to MODE_LOADMAIN.

This is when ZZT Ultra loads guis/zzt_guis.txt. Upon successful load, the "DEBUGMENU" GUI is established, and the mode transitions to MODE_LOADDEFAULTOOP.

This is when ZZT Ultra loads guis/zzt_objs.txt. Upon successful load and parse, the mode transitions to MODE_LOADINI.

This is when ZZT Ultra loads guis/zzt_ini.txt. Upon successful load and parse, the mode transitions to MODE_AUTOSTART if no more deployment searching is needed. If additional deployment searching is needed, the mode transitions to MODE_LOADINDEXPATHS.

One or more files must be loaded as part of a deployment configuration that specifies a basic content path or a dynamic index resource. This mode will be launched as many times as necessary until all files are loaded, after which control moves to MODE_AUTOSTART.

Immediately transition to MODE_NORM and wait for the next user input if no DEP_STARTFILE is set. If a DEP_STARTFILE is set, the auto-loaded file is automatically loaded from the deployed (site) files.

When ZZT launches a generic deployed (site) file, the file extension determines how it must be processed:

• ZZT: MODE_LOADZZT
• SZT: MODE_LOADSZT
• WAD: MODE_LOADWAD
• ZIP: MODE_LOADZIP
• HLP: MODE_LOADFILELINK
• All others: MODE_LOADFILEBROWSER

Loading/Saving Modes

This is when ZZT Ultra loads a file of .ZZT extension. Upon successful load and parse, the "ZZTTITLE" GUI is established, the board is switched to board number 0, and $ONWORLDLOAD is dispatched to the main type code. Regardless of whether or not the load succeeds, the mode transitions to MODE_NORM, and in an unpaused state.

This is when ZZT Ultra loads a file of .SZT extension. Upon successful load and parse, the GUI established will depend on the world name. This will be "PROVING", "FOREST", or "MONSTER" for the official Super ZZT worlds, or "CUSTOMSZT" for all other Super ZZT worlds. The board is switched to board number 0, and $ONWORLDLOAD is dispatched to the main type code. Regardless of whether or not the load succeeds, the mode transitions to MODE_NORM, and in a paused state.

This is when ZZT Ultra loads a file of .WAD extension. Upon successful load and parse, the board is switched to board number 0, and $ONWORLDLOAD is dispatched to the main type code. Regardless of whether or not the load succeeds, the mode transitions to MODE_NORM. It is assumed that the built-for-ZZT Ultra worlds will take control of other details, such as the paused state and GUI, as part of the $ONWORLDLOAD handler.

This is when ZZT Ultra loads a file of .ZIP extension. Upon successful load and parse, the behavior will vary depending on the content of the archive and the auto-run configuration setting. If the archive contains only a single file, that file is launched immediately. If the archive contains a single game file and other non-game files, the game file is launched only if DEP_AUTORUNZIP is set to 1. In all other circumstances, the contents of the archive are displayed as button links on a scroll, which are individually selectable for opening/activation. The action taken is the same as what would normally be taken for a deployed (site) file. If no choice is made, the mode transitions back to MODE_NORM.

This is when ZZT Ultra is loading a WAD file intended to act as a savegame. The last loaded GUI is re-instated, the last active board is switched to, and $ONRESTOREGAME is dispatched to the main type code. Regardless of whether or not the load succeeds, the mode transitions to MODE_NORM.

This is when ZZT Ultra is loading a HLP file from a button link. The next action will depend on what the HLP file code actually does. By default, the mode will go to MODE_NORM until scroll text is displayed (it is a near certainty that text will be displayed).

When PWADs are present in the configuration, these states represent a small side-loading process while the patch file is loaded and applied to the main world file. After successful patch, the mode transitions to the corresponding MODE_LOADZZT, MODE_LOADSZT, etc.

This is when ZZT Ultra is requesting high scores from the server. If the high scores are successfully loaded, $ONGETHS is dispatched to the main type code. If no high scores were loaded $ONFAILGETHS is dispatched instead. The mode always transitions back to the original state after the message is dispatched (usually MODE_NORM).

This is when ZZT Ultra is posting a new high score to a server and fetching an acknowledgement (the resulting list). This works similar to MODE_GET_HIGHSCORES, except $ONPOSTHS is dispatched on success, and $ONFAILPOSTHS is dispatched on failure. The mode always transitions back to the original state after the message is dispatched (usually MODE_NORM).

Special User Interface Modes

This is a "waiting" mode while ZZT Ultra has a dialog open for selecting a file for loading or saving. After the dialog closes, the mode transitions to MODE_NORM if no file was selected, or MODE_NORM if it was a save dialog and save was successful, or MODE_RESTOREWADFILE if the file selected for loading was a savegame.

This is when ZZT Ultra is waiting on user input for a confirmation message. Once the user enters "Y" for yes or "N" for no, the GUI label that displays the text is erased, the mode is changed back to MODE_NORM, and the appropriate message is dispatched to the main type code (depending on the user choice).

This is when ZZT Ultra is handling a one-line text input box. The user's keystrokes enter text character in the box. Backspace and left arrow take back characters from the box. If the user presses the Enter key, the $TEXTRESULT global variable is set to the text the user had just entered, and the appropriate "positive" message is dispatched to the main type code. If the user presses the Escape key, the other "negative" message is dispatched to the main type code. Regardless of the result, the GUI label that displays the text is erased, and the mode is changed back to MODE_NORM.

This is when ZZT Ultra is handling a pen-selection interface from the #SELECTPEN command. The left and right arrows move the pen. If the user presses the Enter or Escape keys, the $PENRESULT global variable is set to the resulting pen quantity. The end-signifying message is dispatched to the main type code, the GUI label that displays the pen is drawn again with default coloration, and the mode is changed back to MODE_NORM.

This is when ZZT Ultra is handling a large scroll interface. The user can move the scroll position using Up Arrow, Down Arrow, Page Up, Page Down, Home, and End. The Escape key transitions to MODE_SCROLLCLOSE. The Enter key transitions to MODE_SCROLLCLOSE, and it will also follow a button link if such a position is aligned with the center pointer.

This is when ZZT Ultra is preparing the integrated text file browser for the display of a text file. Will transition to MODE_FILEBROWSER immediately.

This is when ZZT Ultra is handling the integrated text file browser. User interaction will scroll the browser. When the user closes the browser, the mode to go to next will depend on the context just prior to opening the browser. If the file browser had been invoked on a file from a ZIP archive, the ZIP archive is re-opened and displayed again as a scroll interface. Otherwise, control goes back to MODE_NORM.

Effect Transition Modes

This is when ZZT Ultra is opening a large scroll interface. After the scroll is completely open, it transitions to MODE_SCROLLINTERACT.

A small variation on MODE_SCROLLOPEN is MODE_SCROLLCHAIN. Some "perpetual navigation" contexts, like HLP files, keep the scroll interface open as long as the user continues to navigate to button links within the same file.

This is when ZZT Ultra is closing a large scroll interface. After the scroll is completely closed, it transitions to MODE_MAIN and sets the $SCROLLMSG global variable to 0. However, if the scroll had been invoked on a file from a ZIP archive, the ZIP archive is re-opened and displayed again.

This is when ZZT Ultra is processing a square dissolve effect. After the dissolve is finished, the mode transitions to whichever effect had been defined to be handled next. Usually, this is MODE_NORM.

This is when ZZT Ultra is processing a scrolling-board effect. After the scrolling is finished, the mode transitions to whichever effect had been defined to be handled next. Usually, this is MODE_NORM.

This is when ZZT Ultra is processing a palette-fade effect. After the fade is finished, the mode transitions to whichever effect had been defined to be handled next. Usually, this is MODE_NORM.

Main Game and Menu Mode

This is the "primary" mode of ZZT Ultra. GUI-oriented key inputs are processed and dispatched upon receipt. The behavior of this mode splits into two general sub-modes, based on whether or not ZZT Ultra is in a paused state:

• Unpaused State: Objects are iterated in real-time at the rate set by the configuration property GAMESPEED. Additionally, the $SECONDINTERVAL message is dispatched to the main type code every second.
• Paused State: Objects are not iterated in real-time. The $PAUSED message is dispatched to the main type code every frame.

All editor contexts operate in a paused state.