The Sysop's Manual

#Welcome

ATDT is a complete bulletin board system that runs on ordinary shared web hosting. Callers get an authentic CP437 terminal in the browser: ANSI art, hotkey menus, message bases, live chat, and door games. You get a modern web console to run all of it.

Everything lives in one folder. The board is the atdt/ directory you uploaded; all of its data (database, configuration, custom themes, door saves) lives in data/ inside it. There is no daemon, no build step, and nothing to install on the server beyond PHP itself.

Vocabulary

#Installing the board

Requirements

The installer checks all of this for you on its first screen and explains anything that is missing.

The install wizard

• Step 1. Upload the contents of the atdt/ folder to your web space. The web root and a subdirectory (for example /bbs/) both work.
• Step 2. Visit https://your-site.example/install.php. The environment check runs.
• Step 3. Pick the database. SQLite needs nothing and is right for almost everyone; the database file gets a randomized name inside data/. MySQL asks for host, port, database name, user and password, with a test button.
• Step 4. Board identity. Board name (up to 60 characters), sysop handle (3 to 20 characters: letters, digits, space, period, underscore, hyphen), sysop password (minimum 8 characters, typed twice), board timezone (US zones listed first; this is the clock callers see), and the base URL (auto-detected; correct it if your board lives behind a different public address).
• Step 5. Done. The installer prints your cron line and links to the board and the console.

The cron job

The board does housekeeping on a schedule: the daily tick at board midnight, session sweeps, and each door game's own daily work. The installer prints a line like this for cPanel's Cron Jobs page:

The key is a long random string that guards the endpoint. If you cannot add cron jobs, skip it: pseudo-cron runs the same housekeeping piggybacked on caller traffic. A real cron entry is only better because it fires even when the board is quiet.

Reinstalling

To wipe the board and start over, delete data/config.php (or the whole data/ folder) and visit install.php again. To upgrade in place instead, see chapter 19.

#Your first hour as sysop

The console lives at /admin/. Log in with the sysop handle and password from the wizard. Only level 255 accounts may enter, wrong passwords are throttled (five tries per 15 minutes, lockouts are logged), and every session rides a CSRF-protected cookie.

A sensible first hour:

• Open the board itself in another tab and look around as a caller. The seeded board has two message areas on a "Main Boards" shelf, a welcome bulletin, and two doors.
• Settings: confirm the board name, timezone and base URL. Decide your new-user policy (chapter 6).
• Community: rewrite the welcome bulletin in your own voice.
• Areas: rename the starter areas or build your own layout with categories (chapter 9).
• Themes and the ANSI editor: draw or import a logon screen (chapters 11 and 12).
• Leave the first oneliner. Boards feel alive when the walls have writing on them.

#What callers see

The terminal page is an 80×25 CP437 screen rendered with a real IBM VGA font. Callers type; the board answers. Menus respond to single hotkeys, prompts take a line of input, and the full-screen editor opens for message writing.

The matrix and new users

Before login a caller can press L to log in, A to apply for an account, or G to log off. Applications ask for a handle, password, location, and your custom question. What happens next depends on your new-user policy: with approve the account waits for you (the dashboard shows pending callers), with auto it activates immediately, with closed no applications are taken.

The post-login sequence

After a successful login the caller rides the classic ceremony: connect banner, logon art, board news, a fresh bulletin if one changed since their last call, the auto-message wall, a random rumor, mail check, and last callers, then lands at the MAIN menu. Each step advances on any key.

The default menu map

Every menu, item and hotkey is yours to change in the menu designer.

Caller-side settings

The "Your settings" screen gives each caller a terminal bell toggle, a nostalgic connection-speed throttle (300, 1200, 2400, 9600 baud, or off; keypresses drain the buffer instantly), and a password change.

#The dashboard

The console home page is the pulse of the board. Everything urgent surfaces here.

The stat cards

• Calls today and total calls for the board.
• Messages posted today.
• Pending callers: applications waiting when your policy is approve. Approve or reject inline.
• Cron health: minutes since the last tick. It stays green under pseudo-cron too; -- means cron has never run.

Who is online

Every live node with handle, node number, what they are doing, and idle time. Two buttons per caller:

• Join chat: drops you into the public room the callers see.
• Break in: opens a private line to that caller. See chapter 14.

The chat panel

The console chat panel mirrors the room without you being a node. The target selector aims your words: everyone in the public room, or a private line to one node. A loud banner above the box always shows where the next line goes, and when a caller pages you the form arrives pre-aimed at them.

The broadcast banner

Type a message, pick the minutes, and every connected caller sees it as a banner above their screen no matter what they are doing. Good for "board restarts in 10 minutes." It is separate from chat: a broadcast never lands in the room history.

#Settings, every field

Identity

Access

Display

The cron key

The Settings page shows the exact cron line to paste into cPanel and a button to mint a new key. Minting a new key immediately invalidates the old one; update your cron entry to match.

#Users and access

The list

Search by handle, filter by status, sort by any column. The list caps at 200 rows and tells you to narrow the search past that. Pending applications float to the top with one-click approve.

The edit drawer, field by field

The level ladder

#Access strings (ACS)

One tiny grammar controls visibility everywhere: message areas (read and write separately), menu items, bulletins, voting questions, doors, and menu backdrops. Blank always means everyone. You, at level 255, pass everything.

Recipes

#Message areas and categories

Areas are the message bases. Categories are named shelves that group them: callers see each category as a header with its areas beneath, and the message reader labels the area as "Category / Area."

Categories

• Add: name up to 30 characters. New categories land at the end of the order.
• Rename inline, reorder with the arrows. The caller list follows this order exactly.
• Delete: the category goes away, the areas inside it stay, loose. Nothing else is touched.
• Areas without a category gather under "Other Boards" at the end of the list. A board with no categories at all shows the plain flat list.

Areas, field by field

• The arrows reorder an area within its own category, which is the order callers see.
• Delete refuses while the area still holds messages; empty it first.
• The private mail spool is plumbing, not an area; the console will not let you edit or delete it.

#The menu designer

Menus are the caller-facing skeleton. Each menu has items; each item is a hotkey with an action. The designer edits everything live, with a real preview rendered by the same engine callers use, filtered by your access, since callers see their own filtered view.

Menus

• Add a menu by name. Names are short uppercase words: MAIN, MSGS, DOORS.
• MAIN cannot be deleted; it is where callers land.

Items, field by field

Actions

Every MODULE key

Per-level backdrops

Any menu can wear full-screen ANSI art behind its items, and different callers can get different art: each backdrop row pairs an art slot with an ACS, and the first row the caller passes wins. Draw the art in the ANSI editor, then attach it on the menu's page. Sysops can get one screen, regulars another, and a backdrop plus a hidden item makes a proper secret door.

#Themes

A theme is the board's wardrobe: every caller-visible string plus the art files. The shipped default theme is read-only; the console duplicates it into data/themes/<name> and you edit the copy. You can never break the board permanently: anything missing in your copy falls back to the shipped look.

The Themes page

• Duplicate: copy any theme into an editable one under data/themes/.
• Strings: every caller-facing string, grouped, with a live pipe-code preview as you type. Save writes your strings.ini overlay.
• Art: the theme's .ans slots. Upload rules: .ans files only, 256 KB cap, always served through the board's CP437 loader.
• Delete: blocked while any caller still wears the theme. Reassign them on the Users page first. Deleting a copy of a shipped theme lets the shipped version show through again.

Assigning themes

Themes are per caller: the Theme field in each user's edit drawer. New accounts get default.

Well-known art slots

#The ANSI editor

A full drawing program at Console › Editor: an 80×25 CP437 canvas rendered with the same engine callers see, so what you draw is exactly what ships. It saves straight into a theme's art slots.

Tools

Color, glyphs and the keyboard

• Palette: 16 foreground colors, 8 backgrounds. With iCE colors on, backgrounds get all 16.
• The glyph row holds the full CP437 set: box drawing, shades, blocks, symbols. Click to arm the pencil with any of them.
• Undo is Ctrl+Z, redo is Ctrl+Y. Zoom and a grid overlay are on the toolbar.
• The canvas autosaves to your browser while you work, so an accidental tab close loses nothing.

Files: save, import, export

• Save to slot: writes the drawing into the chosen theme's art slot as a real .ans file with a SAUCE record. Anything wired to that slot updates instantly.
• Import: upload any .ans (256 KB cap), including classic scene art with iCE backgrounds; it lands on the canvas for editing.
• Round trips are pixel-identical: import, edit, save, and the render matches byte for byte where you did not touch it.

Wiring art into the board

• Logon and connect screens: save to those slots in the caller's theme.
• Menu backdrops: attach the slot on the menu designer page, with an ACS per variant.
• ANSI bulletins: pick the slot on the bulletin form; callers get the art full-screen.
• ART menu items: point the item's argument at the slot.

#The community desk

One page, five tabs: everything callers write that you curate.

Bulletins

• Title up to 60 characters. Body text renders pipe colors and word-wraps at the full 80 columns, so classic-width text pastes cleanly.
• Or attach an ANSI art slot instead: callers get the art full-screen.
• ACS gates who sees each bulletin; sort orders the list.
• A freshly saved bulletin greets every caller once at their next logon.

Oneliners and rumors

Callers write them; you hold the eraser. Oneliners are the graffiti wall, one per caller per board day. One random rumor greets every caller at logon, so prune the duds.

The voting booth

• A question takes up to 100 characters and 2 to 10 options, one per line, with an optional ACS.
• One ballot per caller per question; results draw as bar graphs.
• Questions cannot be edited once ballots exist. Close them (callers see results only) or delete them (ballots and options go too).

The BBS list

The other-boards directory. Callers add entries, gated by the Settings-page ACS; you edit or delete anything. Addresses must be https://, telnet://, or host:port.

The auto-message

One board-wide wall message, shown in the post-login sequence. Callers who pass its ACS rewrite it from the caller side; the previous message is simply replaced.

#Chat, paging and the broadcast banner

The room

One public chat room, every node together. Callers page through history with PgUp and PgDn (or the arrow keys), and a half-typed line survives paging. Timestamps show the board clock, with dates when history crosses midnight.

Page sysop and the private line

• A caller pages you with a reason; the console chat panel rings and arrives pre-aimed at their node.
• Break in, on the dashboard next to any caller, opens the private line yourself. The caller gets a banner naming you; everything either of you types rides caller-to-sysop only, invisible to the room.
• Callers answer from wherever they are; they do not need to be in the chat room. ESC ends their side.

Broadcast

The dashboard broadcast form puts a timed banner above every connected caller's screen for the minutes you choose. It never lands in chat history. Use it for maintenance warnings and event calls.

#Door games in the console

The registry

• Scan finds new doors in doors/ (shipped) and data/doors/ (yours) and registers them.
• Per door: enable or disable, display title, ACS, and sort order. Disabled doors vanish from caller menus instantly.
• A door whose folder went missing is marked so you can re-upload or remove it.

HILO

The shipped number-guessing classic. No settings; its scoreboard feeds the Stats screen. Its source is deliberately small: it doubles as the Door API example.

Star Merchant

The flagship: an original space-trading game in a persistent galaxy. The universe generates itself the first time anyone opens the door.

The console panel

What the day-tick does to the game

• Port stocks drift 15 percent back toward full, so gluts clear and famines refill.
• Colonized planets produce by class, per thousand colonists.
• Bank balances earn half a percent; every merchant's turns refill.
• Fresh derelicts scatter for scavengers; pirate crews drift one warp and replenish to roughly one per 50 sectors.
• Weekly, the net-worth ladder snapshots into the hall of fame.

#The Door API

A door is one folder with a manifest and a PHP class. The board gives it a screen, input, storage and player identity; the door gives back frames. Nothing a door does can take the board down: every crash is caught, logged, and turned into a polite apology while the caller returns to the menu.

#Cron and the daily tick

The cron endpoint runs housekeeping. With a real cron entry it fires every five minutes; without one, pseudo-cron performs the same work piggybacked on caller traffic. Either way the work is the same and runs at most once per due moment:

• Sweep dead sessions so nodes free up.
• At board midnight, in your timezone: the daily tick. Board-day counters roll; each enabled door's cron.php runs in its own try/catch.
• Log every run; the dashboard cron card shows minutes since the last tick.

The endpoint requires the key: cron.php key=YOURKEY from the command line, or cron.php?key=YOURKEY over HTTP. A wrong key is refused and logged.

#Logs and events

#Backups, upgrades and recovery

Backups

Everything that is yours lives in data/: the configuration, the SQLite database, theme overlays and door storage. Back up that one folder and you have the whole board. On MySQL, dump the database too. Restoring is copying it back.

Upgrading in place

• Upload the new release's files over the old ones. The zip contains no data/ folder, so an overwrite upload cannot touch your data.
• The first page hit after the overlay migrates the database automatically if the new version needs it.
• install.php coming back with the upload is harmless: it sees the existing board and locks itself.

Recovering a lost sysop password

• If another level 255 account exists, reset the password from its console, on the Users page.
• If not: upload a one-line PHP file, visit it once, then delete it.

Any database tool works too; the only rule is that the stored value must come from PHP's password_hash().

Troubleshooting

#Pipe color codes

Pipe codes color text anywhere the board renders them: theme strings, bulletins, menus, and, when Allow user color is on, caller text. || prints a literal pipe. Codes 00 to 15 set the foreground, 16 to 23 the background.

#MCI variables

Theme strings substitute these live values wherever %XX appears. Caller-typed text never expands them.

#Settings quick reference

#What lives where

Back up data/. Everything else is replaceable from the release zip.

↑ Back to the top