Here are some notes and code snippets for ZZT which may be useful to you, or future me, if I do anything further with the engine.

One of the unique aspects of ZZT is its capacity to be used as a medium for publishing about ZZT itself. Various company magazines, best-practice guides, and reference encyclopedias (collections of cool things you can do) were created throughout the years. However, the drawback of publishing information in this way is that you can't get to it easily without loading the world files in ZZT and actually playing them. The Museum of ZZT File Viewer helps greatly with this visibility problem, but the content is still spread across several publications.

This page will start out as a few random notes, but I hope to eventually map out the encyclopedias and attribute sources where possible.

ZZT-OOP

Counters

Set the player's health to a specific value

ZZT infamously only provides addition and subtraction to a handful of pre-defined counters. The Health counter can be directly set to a specific value by abusing the endgame command:

@setHealth
#end
:touch
#endgame
#give health 100
#end

Endgame normally sets the player's health to zero and triggers a Game Over state, but if you immediately give the player health afterwards, ZZT will not catch that the game should have ended, and will continue on as if nothing happened.

Detect when the player enters a board

Super ZZT provides a new label for making objects do things whenever the player enters a board. In ZZT, under certain circumstances, it is possible to do this by monitoring the Time counter:

@timeCheck
#cycle 1
:a
#take time 1 enteredboard
#give time 1
/i#b

:enteredboard
#give time 1
enteredboard label tripped.
/i
#all:enter
#a

Caveats: The board should not have a time limit specified, and if the player takes built-in damage (hit by a bullet or creature), this will also reset the Time counter to zero and cause the loop to trigger. ZZT-OOP #give / #take commands do not have this side effect.

The Time counter is always available to mess around with in ZZT-OOP, even when a time limit is not specified on a given board, and it is always set to zero upon entering a board or upon taking built-in damage. Its value will be preserved when restoring from a save file.

Display an external text file

An undocumented menu option (!-FILENAME;) will display the contents of a specified text file. These files may include additional menu links, but the text will not be executed as ZZT-OOP.

@readDoc
#end
:touch
What do you want to read?

!-HELLO.TXT;Read HELLO.TXT!
!x;Never mind.
:x
Okay.
#end

If the file doesn't exist, nothing happens. Paths may be specified as well. For example, you could display Z:\AUTOEXEC.BAT when running within DOSBox.

This may be useful for conserving limited memory in a large world file, or to allow blocks of text to be viewed on multiple boards without duplicating the text everywhere.

Entities that are visible in the dark

Dark boards in ZZT mask the entire screen in a grey fog, showing only the player, passages and torches. The player can light torches to view a small radius of the surrounding area. Abuse of these entities can allow you to fill in negative space and create animations that otherwise wouldn't be visible.

Also known as the Kangaroo effect, the namesake of this wiki.

The following entities are visible on dark boards, and can be used to display a limited set of patterns or solid colors on an otherwise grey screen:

Torches. The safest thing to use.
Passages, both with stats and statless. This can cause undesired warping to other boards, particularly the title screen with statless passages.
Player Clones, both with stats and statless.
Kryptonite Text -- Entity ID 54, which shows up as blinking white text. This is an undefined entity and its presence on a board is capable of crashing ZZT!

Torches and passages cannot be pushed by anything, but player clones and Kryptonite text may be moved by non-player entities such as objects and boulders. Player clones carry some potential side effects, particularly with board edge linking if those clones are up against an edge. (TODO expand on this.) These entities in general can be set as the "under" terrain for entities with stats, so that when the upper object moves, the entity underneath shows through the fog mask.

Attribution

Kryptonite Text, presented and coined by Ellypses, 27 Oct 2018, Discord of ZZT

Linking Boards Together

Board Edges

ZZT boards are 60x25, but the internal playfield incorporates a perimeter of "Edge" terrain which is used for determining when the player is attempting to travel to another screen. Edge cells were designed for internal engine use, but it is possible to place them within the visible playfield using STK, an external editor, or even in-game using a bug in ZZT-OOP:

@makeEdgeCell
#end
:touch
#put opp seek

For some reason, putting no 'kind' identifier after the direction causes an edge cell to be made. (TODO attribution.)

If the player touches an edge cell within the visible playfield, it will attempt to transport the player to the linked board in the direction that it was touched. If there is no link, or if the edge on the other side is blocked, then the cell will behave like an obstacle.

Passages

Passages transport the player to a destination board which is chosen in the editor. Passages made with the internal editor cannot link to the title screen. However, passages made with ZZT-OOP in-game can 'only' link to the title.

When a player is warped by a passage, ZZT will search for a passage on the destination board with matching foreground and background colors. If a match is found, the player is positioned on top of that passage. If no match is found, then the player remains wherever they are currently located on the destination board.

When looking for a matching passage, ZZT starts at the bottom-right, and goes bottom-to-top, right-to-left. Only the first match is used.

Back-To-Back Passage Routing

While passage links normally can't be changed in-game, it is possible to use an intermediate linking board with an array of passages to route the player from one source to different destinations. Additionally, on this linking board, one can use ZZT-OOP to modify which egress passage the player is routed through. If you make the title screen a linking board, then you now have the ability to place and destroy passages in-game with ZZT-OOP at will.

Attribution:

Pepper Bolette by Ellypses uses a static linking board to warp the player to an inventory screen, and back to most boards in the game.

ZZT Notes

Contents