RuBBS

rubbs is our Ruby gem for building telnet bulletin boards: a login dialogue in ten lines, a full-screen board with windows, menus and mouse in a few hundred, and the same board on a Commodore 64 on the same port. All eleven boards of our BBS network run on it. This manual describes rubbs 1.0.0. Every class and method is documented in the source: the API reference (RDoc) is rebuilt from it on every release tag.

What you get

• Three layers in one call — Flow for line dialogues (login, wizards), Application for a desktop with windows, menus and widgets, and the PETSCII Screen with its Selector cursor menus for a line-by-line board on a Commodore 64 or a modern terminal; a call moves between them freely.
• Turbo Vision on a telnet line — windows that move, size, zoom and switch, a menubar with hotkeys, a statusbar, forms, master-detail browsers, chat streams, five colour themes and a Markdown renderer, all clickable with the mouse.
• A Commodore 64 face — session.petscii! turns the line into 40×25 PETSCII while the code keeps writing UTF-8 and ANSI; BBS::Terminal asks each caller which terminal is calling and starts the modern or the C64 face.
• Doors and gateways — simulated machines (FakeOS), flows and any program as doors, telnet gateways that hand the line on to another board (a C64 can even call an ASCII board), ZMODEM and XMODEM downloads.
• AI characters — a persona in a YAML file talking through any OpenAI-compatible model, streamed word by word, with canned replies when the model is away.
• The blocks of a content board — an SQLite file with migrations, bounded HTTP, a cache, rate limits, a paced Wikipedia client, one log format and background work with retry.
• Made for the real line — telnet negotiation, window size, SGR mouse, idle, session and per-address limits, control-free input, a gateway that calls only public addresses, and a door's crash never ends the call.

The manual

A first board

The gem is called bbs. It listens on a TCP port, negotiates telnet with every caller, gives each one a Session, and runs the flow you configure:

require 'bbs'

BBS.configure do |c|
  c.log_tag = 'my-bbs'
  c.flow = BBS::Flow.define do
    big_banner 'My BBS'
    ask :name, prompt: 'Your name'
    say 'Welcome!', style: :success
  end
end

BBS.start

ruby bbs.rb, then telnet localhost 2323. From there, Getting started builds it into a board with windows and a C64 face.

The three layers

A call usually starts in a flow (the terminal question, the login) and continues in an application or on a PETSCII screen; doors and gateways step out of it and come back. Until 1.0 there was a fourth layer, BBS::TUI, for single full-screen pages; no board used it, and 1.0 removed it (see the Changelog).

flowchart LR
  S[TCP server] --> SE[Session: telnet, window size]
  SE --> F[Flow]
  F --> A[Application]
  F --> P[PETSCII Screen + Selector]
  A <--> D[Door: FakeOS, Flow, program]
  A <--> G[Gateway: another board]
  P <--> G
  F --> F2[Sub-flow]

Who uses it

Building blocks of a line-by-line board

Since 0.29.0 rubbs carries what every line-by-line board of ours used to write for itself. All of them are in the API reference; the Commodore 64 page shows them at work.

module UI
  module Petscii
    BBS::Petscii::Colors.install(self)

    class Screen < BBS::Petscii::Screen
    end

    LOGO = BBS::BlockFont.petscii('WARP', colors: [LB, LB, CY, CY, WH], indent: 10)
  end
end

screen = UI::Petscii::Screen.new(runner.session)
book   = screen.pick('the shelves', books, &:title)
screen.say('Downloading…', color: YE)
BBS::Goodbye.petscii(screen, title: 'warpengine bbs', color: LB)

Upgrading from 0.x

1.0 is the cleanup release: one way to do each thing. What a board usually has to change:

• screen.say(text, GN) → screen.say(text, color: GN), screen.rule(DG) → screen.rule(color: DG);
• screen.editor(max, title) → screen.edit(title: title, max: max).to_s;
• Petscii::Screen::MENU → BBS::Selector::COLORS (or nothing: it is the default);
• a gateway to a neighbour board on a private address → public_only: false;
• BBS::TUI, BBS::Color, ProgressBar, Spinner, HBox, VBox, Panel, AnsiArt, most Flow steps beside call and the colour-named Flow styles are gone.

The Changelog has the list in short; UPGRADING.md in the repository lists every removed or renamed API with its replacement and a grep that finds it.

Installation

gem 'bbs', git: 'https://git.teletypegames.org/engines/rubbs.git', tag: 'v1.0.0'

Ruby 3.2 or newer (the socket timeouts need IO#timeout=), with the sqlite3 gem. Boards pin rubbs by tag or by git revision in their Gemfile.lock.

Source layout

Repository

engines/rubbs — MIT licensed. Its README.md is the developer reference in one file, UPGRADING.md the way from 0.x to 1.0; this manual is the guided version.