ZCode: The ZZT World Editor for VS Code

Welcome to ZCode, a VS Code extension designed to help you create and modify ZZT worlds directly within your IDE. This editor provides a visual interface for designing boards, placing elements, and managing game logic.

Getting Started

To begin using ZCode:

1. Open a ZZT World File: Open a .zzt file in VS Code. The editor will automatically launch in a custom editor tab.

Editor Overview

The editor interface consists of the main board view and a sidebar with various tools and palettes.

Tools

Located in the sidebar, these tools control your primary interaction mode with the board:

• Select Tool: Use this tool to select areas on the board. You can then copy, cut, or paste selections. You can also move selected areas as a "floating layer" on the board.
• Draw Tool: This is your primary drawing tool. Select an element from the palette and click or drag on the board to place it.
• Text Tool: For placing text characters directly on the board. Each character placed is a separate ZZT text element.
• Fill Tool: Use this to flood-fill contiguous areas with the currently selected element.

Element Palette

The sidebar provides various categories of ZZT elements you can use:

• Terrain: Basic board elements like walls, water, forest, and empty space.
• Items: Collectible items such as ammo, gems, keys, and energizers.
• Creatures: Various ZZT creatures like bears, ruffians, sharks, and lions.
• Puzzle: Interactive elements including boulders, sliders, ricochets, and bombs.
• Transport: Elements for board navigation, such as passages and transporters.
• Text: Pre-defined colored text elements.
• Objects & Other: Special elements like objects, the player, scrolls, and board edges.

Current Brush & History

The editor displays your currently selected element (the "brush"). You can also see a history of recently used brushes for quick access.

Object/Stat Editor

When you select an object or certain interactive elements on the board (e.g., passages), an Object/Stat Editor will appear. Here you can:

• View and modify the element's properties.
• Write and edit ZZT-OOP (ZZT's scripting language) code associated with objects.

Keyboard Shortcuts

Many common actions have keyboard shortcuts for efficiency:

• Arrow Keys: Navigate the cursor on the board. When a floating layer is active (in Select mode), these move the floating layer.
• Ctrl/Cmd + Arrow Keys (Select mode): Jump to adjacent boards using the board's exits (West/East/North/South).
• Ctrl/Cmd + Shift + Arrow Keys (Select mode): Open the passage link selector for the indicated direction (West/East/North/South).
• Enter:
  • In Select mode: If over an object or text/colored tile, opens the character/character-color selector. Otherwise, picks up the tile under the cursor as the current brush.
  • In Text mode: Moves the cursor to the beginning of the next line (paragraph-aligned).
• Ctrl/Cmd + Enter (on a Passage): Navigate to the passage's linked board. Attempts to position the cursor on the matching-colored passage.
• Spacebar: In Select mode, places the current brush/selection onto the board. Also applies a floating layer.
• Backspace / Delete: In Text mode, deletes the character to the left; may move to the previous line when appropriate.
• Ctrl/Cmd + C: Copy the current selection to the clipboard.
• Ctrl/Cmd + X: Cut the current selection to the clipboard.
• Ctrl/Cmd + V: Paste from the clipboard.
• Ctrl/Cmd + H: Shuffle the current selection.
• C: In Select mode, opens the color selector for the tile under the cursor.
• B: Opens the board selector for quick navigation between boards.
• P: Runs the current ZZT world in a ZZT emulator.
• O: Toggle display mode between default and highlight.
• F: Flood fill from the current cursor position using the current brush (Select/Draw modes).
• Tab: Toggle between Select and Draw tools. When switching to Draw, places the current brush at the cursor.
• T: Switch to Text tool. Escape returns to Select.
• E:
  • If over a passage, opens the passage editor.
  • If over an object, focuses the object's code editor. (Note: Escape returns you from this editor.)
• Escape: Clears the current selection or floating layer.
• Ctrl/Cmd + 1..7: Open element category popups directly:
  • 1: Terrain
  • 2: Items
  • 3: Creatures
  • 4: Puzzle
  • 5: Transport
  • 6: Text
  • 7: Objects & Other

Brush History Hotkeys

• Ctrl/Cmd + Shift + 1..0: Select brush from history at that index (1 is most recent, 0 selects the 10th).
• Ctrl/Cmd + ``` (backtick): Quick-select the previous brush.

Mouse Interactions

• Left Click (and Drag):
  • Select Tool: Starts or extends a selection (hold Shift to extend from the current anchor). Dragging a floating layer moves it.
  • Draw Tool: Draws with the current brush. Hold Shift to draw a straight line between two shift-clicks.
  • Text Tool: Moves the cursor.
  • Fill Tool: Performs a flood fill.
• Right Click:
  • Draw Tool: Picks up the tile under the cursor and sets it as the current brush (eyedropper).
  • Fill Tool: Picks up the tile under the cursor and sets it as the current brush (eyedropper).
• Ctrl/Cmd + Click (Select Tool): Lift the current selection into a floating layer for repositioning.

Floating Layer Tips

• Move: Arrow keys.
• Apply/Drop: Press Enter, Space, or Q.
• Cancel: Escape. Clicking outside also clears the floating layer.

Display Modes

Toggle between different display modes (e.g., showing object highlights) to assist with editing.