------------------------------- Readme for ZZT Ultra deployment ------------------------------- Prepared by Christopher Allen -------- Contents -------- . Can I really deploy this anywhere? . File list . Customizing ZZT Ultra page design . Type/object code definition file . GUI definition file . Deployment Options o Deployment Option #1: Basic content path o Deployment Option #2: Static index o Deployment Option #3: Dynamic index resource . High score options . Auto-run options . Configuration property options . Deployment visible in configuration . Modifying ZZT Ultra configuration via GET variables . How ZZT Ultra accesses game files o ZZT o SZT o WAD o ZIP o HLP o TXT ---------------------------------- Can I really deploy this anywhere? ---------------------------------- Yes! Well, usually. ZZT Ultra is Freeware and released under a Creative Commons BY-NC license (see license link below). You can deploy this to a website or keep it local on your own computer, but you are subject to the rules of CC. http://creativecommons.org/licenses/by-nc/4.0/legalcode Modifications to configuration and HTML page template are pretty much guaranteed, and really the whole point of this release. You can modify the files to your heart's content, as long as you stay within the attribution and non-commercial requirements. --------- File list --------- README.txt : This file ZZTUltra.swf : Flash program file ZZTUltra.html : HTML page template for Flash program file eval_dir.php : Directory-evaluation PHP script file eval_hs.php : High-score-evaluation PHP script file guis/zzt_objs.txt : Default type/object code definition file guis/zzt_guis.txt : Built-in GUI definition file guis/zzt_ini.txt : Deployment initialization file DEMO.WAD : Demo world file CHARDEMO.WAD : Character/Palette demo world file SMASHZZT.WAD : Smash ZZT world file BQDELTA.WAD : Patch file for Banana Quest PBF0.WAD : Patch file for POINTBLANKFIRING=0 (ZZT files) PBF0_SZT.WAD : Patch file for POINTBLANKFIRING=0 (SZT files) To deploy ZZT Ultra, copy the files to the target location. When "ZZTUltra.html" is shown in a web browser, it loads "ZZTUltra.swf", initializes the configuration components, and starts up. It is not necessary to copy the PHP files or WAD files to the deployment location. The required files include ZZTUltra.swf, this file, and all the configuration components within the guis folder. --------------------------------- Customizing ZZT Ultra page design --------------------------------- The file "ZZTUltra.html" is provided as a "bare bones" template for how the application can appear on the page. In practice, only two components need to be present on the page: . The "" portion within the HTML HEAD portion . The "" portion within the HTML BODY portion To modify the resolution of the Flash application, tweak the 'width' and 'height' attributes within AC_FL_RunContent. Please remember that the default resolution of 640x400 is a reproduction of the original text mode resolution in DOS; expanding the size will not enhance the detail. -------------------------------- Type/object code definition file -------------------------------- The default type/object code definition file, "guis/zzt_objs.txt", is loaded by ZZT Ultra on startup. This contains all the ZZT and Super ZZT type information used for those games, plus the message-dispatch routines for the GUIs. You can edit this file to change the default behavior of the types and objects. However, do so at your own risk. If a type is modified and stops working, ZZT Ultra will need to be stopped and restarted after the offending object code is fixed. To learn more about the language ZZT-OOP, use this reference: http://www.chriskallen.com/zzt/zztoop.php ------------------- GUI definition file ------------------- The built-in GUIs for ZZT Ultra are stored in "guis/zzt_guis.txt". This is loaded by ZZT Ultra on startup. GUIs are used in conjunction with the type/object code. The GUI editor is built into ZZT Ultra, and can be used to create custom GUIs. To learn more about GUIs, use this reference: http://www.chriskallen.com/zzt/editors.html#guieditor Although you can modify the built-in GUI definition file, this is not advisable. A better solution would be to add a new GUI or override an existing GUI with a PWAD. ------------------ Deployment Options ------------------ The deployment INI file is used to configure ZZT Ultra at the hosted location. ZZT Ultra loads "guis/zzt_ini.txt" at startup and behaves according to these settings. The main purpose of the INI file is to control how ZZT Ultra discovers game files within the same web-hosted location. There are three different ways to deploy the ZZT Ultra configuration: Basic content path, static index, or dynamic index resource. The default INI file contains samples of all three configurations, but with only the dynamic index resource configuration active. The other configurations are "commented out." If you want to see a valid sample configuration, visit http://www.chriskallen.com/zzt/guis/zzt_ini.txt. ------------------------------------------ Deployment Option #1: Basic content path ------------------------------------------ The simplest deployment option is to set a path where various file types can be located. This deployment option is contingent on the condition that no "index" file be defined at the specified folder. Web servers commonly enumerate a list of files when given a folder, but a file such as "index.html" is typically loaded instead, if it is defined within the same folder. Therefore, the use of basic content paths to enumerate content is not guaranteed to work unless both the web server and file system support them. Note that the other deployment options are not limited in this fashion. Paths are always evaluated relative to the launch folder; you cannot use ".." or "/" to navigate upwards or to the web root. For example, this works: "DEP_INDEXPATH" : "files/zzt" These do not work: "DEP_INDEXPATH" : "/root/files/zzt" "DEP_INDEXPATH" : "../zzt" Loading from other domains also does not work: "DEP_INDEXPATH" : "http://www/mysite.com/files/zzt" If a path option is not set, or is set to "", the path variable will not be used to evaluate content. You can choose to recursively evaluate subfolders if desired. The default recursion level is 0, indicating that no evaluation of subfolders occurs. If one sets the level to 2, as follows... "DEP_RECURSIVELEVEL" : 2 Deployment paths would run down to two levels deep. For example: "DEP_INDEXPATH" : "files/zzt" ...evaluates files in files/zzt, files/zzt/a, files/zzt/b, files/zzt/b/b2, etc. ZZT Ultra attempts to identify the files resembling extensions .ZZT, .SZT, .WAD, .ZIP, .HLP, and .TXT. ZZT Ultra requires these files to be quoted within the text of an A HREF hyperlink. Subfolder evaluation is not guaranteed to be 100% accurate, because there is no standard for how the file list needs to be organized upon fetch. Subfolders may or may not have an obvious demarkation. ZZT Ultra will evaluate text as a subfolder if: 1) It is within the text of an A HREF hyperlink 2) It ends with a slash "/" 3) It does not start with a period "." ----------------------------------- Deployment Option #2: Static index ----------------------------------- The most secure deployment option is to define the index within the INI file. The deployed paths are limited to just the files within DEP_INDEX. An example: "DEP_INDEX" : [ "www/content/town.zzt", "www/content/demo.zzt", "www/content/monster.szt", "www/content/bananaq.zip" ], The paths are evaluated relative to the launch folder, and wildcards are not allowed. Note that file links (HLP files) also need to be defined in the index if they must be referenced. Content that happens to exist casually within the same folder as a file in the index is not "visible" to ZZT Ultra unless it also appears within the index. --------------------------------------------- Deployment Option #3: Dynamic index resource --------------------------------------------- The most versatile deployment option is a resource fetched over HTTP. If the resource is a server-side script, it can report just about anything to ZZT Ultra. For example, this index resource evaluates the "content" subfolder for all files with ZZT extension, and with a recursion level of zero: "DEP_INDEXRESOURCE" : "eval_dir.php?path=content/*.zzt&level=0" The "eval_dir.php" script file is provided as a matter of convenience. The "path" GET variable acts as a folder and optional wildcard search argument, while the "level" serves the same purpose as DEP_RECURSIVELEVEL. Of course, you can have DEP_INDEXRESOURCE point to your own customized server-side script, which does not need to be PHP (it can even be a static text file). ZZT Ultra fetches the index over HTTP, and it will honor the list of files as long as it conforms to a list pattern. This list must be newline-delimited (\n). Blank lines are ignored. ".." and "/" path components are not honored, although "./file" is honored, working the same way as "file". In the interest of human readability/testing, it is acceptable for the index to have an HTML tag structure, but the list is ONLY read as the portion inside a

block. ------------------------------ PWADs: Patch files for worlds ------------------------------ "PWADS" : { "BQUE.ZZT" : "www/content/pwads/BQDELTA.WAD", "BQUEST.ZZT" : "www/content/pwads/BQDELTA.WAD", "BQUEST-B.ZZT" : "www/content/pwads/BQDELTA.WAD", "BQUEST-C.ZZT" : "www/content/pwads/BQDELTA.WAD" }, ZZT Ultra takes a page from the IWAD/PWAD relationship of the WAD file format and allows any ZZT, SZT, or WAD file to be patched with a "delta" specification. When the key filename within the "PWADS" dictionary is loaded, the value associated with that key is applied as a PWAD patch as part of the load process. One can use the PWADdler tool to create PWADs for ZZT Ultra. The PWADs shown in the above example are critical in patching the Banana Quest world files, which had relied upon external modifications to the ZZT executable and run environment. As a matter of convenience, BQDELTA.WAD is provided in this package, which patches the original Banana Quest world files upon load. The package also contains PWADs for setting POINTBLANKFIRING to zero for those worlds found to be problematic with point-blank firing active. ------------------ High score options ------------------ An optional deployment feature of ZZT Ultra is server-side high score deployment. The client-side implementation of high scores (loaded locally) is in the form of shared objects, which are supported automatically. The server-side implementation, on the other hand, requires a bit of work to set up correctly. High scores are read and written in a server-side context for any world loaded from the deployed configuration. The file "eval_hs.php" is invoked by ZZT Ultra to conduct two different operations: posting a new high score (from #POSTHS command) and fetching the high score list (from #GETHS command). The PHP script has its own configuration settings that the webmaster can fine-tune. The default "eval_hs.php" settings are permissive (any deployed game file on the site can have a high score list of up to 500 names). A subfolder of "hiscores" is assumed to act as the storage location for high score files, as well as an optional comma-delimited file for filtering objectionable words that users might post. ---------------- Auto-run options ---------------- "DEP_AUTORUNZIP" : 0 Default behavior when opening a ZIP file is to browse the contents within ZZT Ultra, whereupon text files can be read and game files can be launched. If you want to have ZZT Ultra immediately launch a single game file within a ZIP file, without a browsing option, set DEP_AUTORUNZIP to 1. Note that ZZT Ultra will always auto-run a ZIP file that has only a single game file and nothing else. Conversely, ZZT Ultra will always browse the contents of the ZIP file if multiple game files are found, since the user must be given a choice when loading a multi-world adventure. Therefore, auto-run occurs when... . Exactly one file in archive, which is ZZT, SZT, or WAD. . Only one game file in archive (ZZT, SZT, or WAD), and DEP_AUTORUNZIP=1. "DEP_STARTUPFILE" : "TOWN.ZZT" Default behavior when ZZT Ultra starts up is to show the startup GUI, but let the user decide what to do next. If DEP_STARTUPFILE is set, you can load a game file immediately. Note that this has the same effect as the old BIX.FLG file. A startup file will only work if it is already visible in the deployed configuration; it will not work otherwise. "DEP_STARTUPGUI" : "DEBUGMENU" Default behavior when ZZT Ultra starts up is to load the "DEBUGMENU" GUI. You can change this GUI to something else, provided you know what you are doing. The alternate startup GUI must exist within zzt_guis.txt, or else it will not work. ------------------------------ Configuration property options ------------------------------ Most of the configuration properties (i.e. world properties that configure ZZT Ultra) can be initialized in the INI file, overridding the defaults. This allows the deployed copy of ZZT Ultra to have a unique, tailored configuration. An example: "DEP_STARTUPFILE" : "UNREAL-A.ZZT", "GAMESPEED" : 1, ...or... "DEP_STARTUPFILE" : "SMILEY.ZZT", "POINTBLANKFIRING" : 0, ----------------------------------- Deployment visible in configuration ----------------------------------- While ZZT Ultra is running, the deployment properties are visible as world properties. Settings such as "DEP_STARTUPGUI", "DEP_INDEXPATH", etc. can be read from and written to. However, ZZT Ultra does NOT change the deployment if these deployment properties are changed using #SETPROPERTY or other property-changing mechanisms. Once the INI file is loaded, the deployment remains in its original state while ZZT Ultra is running. This rigidity is designed with security in mind. --------------------------------------------------- Modifying ZZT Ultra configuration via GET variables --------------------------------------------------- When ZZT Ultra is embedded within a web page, HTTP GET variables can alter the configuration from that specified in zzt_ini.txt. DEP_STARTUPFILE=tour.zzt This GET variable implicitly modifies DEP_STARTUPFILE. In this example, tour.zzt is selected as the startup file. DEP_AUTORUNZIP=1 This GET variable implicitly modifies DEP_AUTORUNZIP. In this example, ZIP files are set to auto-run. DEP_EXTRAFILTER=*.szt This GET variable limits the deployment configuration to a pattern. Note that the configuration can be reduced in terms of total number of searchable items, but it cannot be expanded. This example only shows Super ZZT files if the configuration would otherwise evaluate mixed content. POINTBLANKFIRING=0 Configuration properties can be tweaked by matching the GET variable to the property name. In this example, point-blank firing against OBJECT types is turned off. However, the "DEP_*" properties are NOT modifiable unless they are listed in this section. The configuration is secure because external modification cannot expand the fundamental directory structure. --------------------------------- How ZZT Ultra accesses game files --------------------------------- When ZZT Ultra loads a game file, the configuration properties and deployment influence how the game will play, as well as what other files are accessible. The following summarizes how each file is handled when loaded. ZZT The world file is loaded and run immediately. The default configuration shows the title screen in an unpaused state. If there are file links associated with this world, they must be present in the deployed configuration for them to be visible. Otherwise, file links will not work. If an external (uploaded) ZZT world is loaded, the world is effectively its own sandbox, and no file links are visible. SZT The world file is loaded and run immediately. The default configuration shows the intro GUI in an paused state. If there are file links associated with this world, they must be present in the deployed configuration for them to be visible. Otherwise, file links will not work. If an external (uploaded) SZT world is loaded, the world is effectively its own sandbox, and no file links are visible. WAD The world file is loaded and run immediately, with the $ONWORLDLOAD message dispatched to the main type code. This code is responsible for setting up the world. Any file links associated with this world must be embedded within the WAD file itself. A WAD lump named "FILE " counts as an embedded file. If an external (uploaded) WAD world is loaded, file links can still be seen (as they are embedded within the WAD). ZIP The archive is loaded and opened. If auto-run behavior is set (or the archive contains only a single ZZT, SZT, or WAD file), the world is loaded and run immediately per the behavior identified for the formats above. If auto-run behavior is not set, a file browser is shown containing all files within the ZIP. If the user selects a ZZT, SZT, or WAD file, the world is loaded and run per the behavior identified for the formats above. If the user selects any other file, ZZT Ultra attempts to view the file as text, with behavior identified for the formats below. Any file links associated with this world must be embedded within the ZIP file itself. If an external (uploaded) ZIP file is loaded, file links can still be seen (as they are embedded within the ZIP). HLP The file is loaded in a scroll interface with links pointing to various other locations within the same file. Essentially, a HLP file acts as an object that isn't placed in a board physically, and only exists to offer a text interface to the user. When the user closes the scroll without selecting a link, the game state returns to the state before the file was shown (either paused or unpaused). TXT The file is loaded in a large, full-page text browser. When the user closes the text browser, the game state returns to the state before the file was shown (either paused or unpaused). ------------------------------- My name is Christopher Allen and I approve this message. http://www.chriskallen.com/zzt