====== Mystic BBS Terminal Screen Design (ANSI + MCI) ======

This page documents how to create a **terminal-style interface inside Mystic BBS**, similar to **MRC (Multi Relay Chat)**.

The goal is to create a reusable **ANSI template + MPL script system** that can be used for:

* Chat clients (MRC style)
* External messaging systems
* Terminal dashboards
* Chickadee integration
* Node monitoring tools
* Live data feeds

Mystic does **not use GUI widgets**. Instead it uses:

* **ANSI art** for the screen layout
* **MCI codes** for dynamic fields
* **MPL scripts** to control logic and user input

---

===== Architecture Overview =====

Typical layout used by Mystic terminal programs:

<code>
+-------------------------------------------------------------+
| Title Bar                                                   |
+-------------------------------------------------------------+
| Status / Info Line (Room, Topic, Users, etc.)               |
+-------------------------------------------------------------+
|                                                             |
|                                                             |
| Chat / Message Area                                        |
|                                                             |
|                                                             |
|                                                             |
+-------------------------------------------------------------+
| Input Line                                                  |
+-------------------------------------------------------------+
| Help / Command Line                                         |
+-------------------------------------------------------------+
</code>

Example usage:

* **MRC Chat**
* **IRC client**
* **Packet BBS console**
* **Real-time BBS tools**

---

===== Components of a Mystic Terminal Screen =====

Mystic terminal programs typically use **three parts**:

^ Component ^ Purpose ^
| ANSI screen file | Draws the interface layout |
| MPL script | Handles input/output logic |
| External program | Network / background processing |

Example (MRC architecture):

<code>
User Terminal
     ↓
ANSI screen (layout)
     ↓
MPL script
     ↓
Temp message files
     ↓
Python client
     ↓
Network server
</code>

---

===== ANSI Screen Files =====

Mystic loads **ANSI screens** to draw the interface frame.

Example files from MRC:

* `mrcmain.ans` → main chat screen
* `mrcscrl.ans` → scrollback screen

These files contain:

* box drawing characters
* color codes
* Mystic MCI variables
* cursor positioning

Example ANSI layout:

<code>
|CL
|19╔══════════════════════════════════════════════════════════╗
|19║ |15Multi Relay Chat                                      |19║
|19╚══════════════════════════════════════════════════════════╝
</code>

`|CL` clears the screen.

---

===== Important Mystic MCI Codes =====

Mystic uses **MCI codes** to control colors and screen behavior.

Common ones used for terminal screens:

^ Code ^ Meaning ^
| `|CL` | Clear screen |
| `|XY` | Move cursor |
| `|XX` | Set foreground color |
| `|[X##` | Set X cursor position |
| `|[Y##` | Set Y cursor position |
| `|CR` | Carriage return |

Example:

<code>
|[X01|[Y01|15Mystic Terminal
</code>

This moves the cursor to **column 1 row 1**.

---

===== Designing the Chat / Output Area =====

The main message area is usually **left blank in the ANSI file**.

Example:

<code>
|19║                                                          ║
|19║                                                          ║
|19║                                                          ║
|19║                                                          ║
</code>

The MPL script later writes messages into this region.

Typical chat area:

* rows **5–20**
* width **70–78 characters**

---

===== Input Line =====

A typical input prompt appears near the bottom.

Example:

<code>
|[X01|[Y23|10Say > |07
</code>

User input is captured by the MPL script.

---

===== Status Line =====

Many terminal programs include a **live status bar**.

Example fields:

* room name
* topic
* latency
* users online

Example:

<code>
Room >>> General
Topic >>> BBS Chat
Users >>> 12
Latency >>> 32ms
</code>

These are updated dynamically by MPL.

---

===== Scrollback Screen =====

Many Mystic terminal tools include a **secondary screen**.

Example:

`mrcscrl.ans`

Purpose:

* browse old chat lines
* page up/down
* search logs

Typical commands:

^ Key ^ Action ^
| ↑ ↓ | scroll |
| PgUp | page up |
| PgDn | page down |
| ESC | return |

---

===== MPL Script Responsibilities =====

The MPL script handles:

* keyboard input
* message display
* command parsing
* updating MCI variables
* launching external programs

Typical tasks:

<code>
load ansi screen
position cursor
read keyboard input
write message to temp file
refresh message area
</code>

---

===== Example Terminal Workflow =====

Example message flow:

<code>
User types message
      ↓
MPL script writes temp packet file
      ↓
External program sends packet
      ↓
Server replies
      ↓
External program writes new message file
      ↓
MPL reads file and displays text
</code>

This allows **real-time chat inside the BBS**.

---

===== Applying This to Chickadee =====

Chickadee could use the same architecture.

Example layout:

<code>
Chickadee Terminal
────────────────────────────────────────

Channel >>> #general
Users   >>> 8
Server  >>> amigaz.org

---

(chat messages here)

---

> type message here
>
> </code>

Possible features:

* cross-BBS chat
* private messaging
* file sharing
* bot commands
* status notifications

---

===== Recommended File Layout =====

<code>
mystic/
 ├─ ansi/
 │   ├─ chickadee_main.ans
 │   └─ chickadee_scroll.ans
 │
 ├─ mpl/
 │   └─ chickadee_terminal.mpl
 │
 ├─ data/
 │   └─ chickadee/
 │
 └─ scripts/
     └─ chickadee_client.py
</code>

---

===== Tips for Terminal Screen Design =====

* Design ANSI art using **80x25**
* Keep the chat area fixed
* Avoid writing over the frame
* Use consistent colors
* Reserve bottom rows for input

Useful ANSI tools:

* PabloDraw
* Moebius
* Mystic built-in editor

---

===== References =====

Mystic documentation:

* https://wiki.mysticbbs.com

Relevant sections:

* MCI Codes
* ANSI Screens
* MPL Scripting
* External Programs

---

===== Notes =====

Terminal-style screens are ideal for:

* chat systems
* live dashboards
* message relays
* sysop monitoring tools

The **MRC client** is a good reference implementation for this architecture.