romeopavoni / petscii-bbs

A Java framework for building highly customizable PETSCII-enabled BBS, accessible from Commodore 64/128

PETSCII BBS Builder

A Java framework for building highly customizable PETSCII (and ASCII) enabled BBSes, accessible from 8-bit Commodore computers

Patreon support page

https://www.patreon.com/FrancescoSblendorio

Purpose

This framework provides base classes for build your own BBS in PETSCII mode, accessibile through:

• a Commodore 64 with a RR-NET compatible card, running KipperTerm
• a Commodore 64 with a WiFi modem card, running CCGMS
• a Commodore 64/128 with a 1541Ultimate, running UltimateTerm
• an Ultimate 64, running UltimateTerm
• a Commodore 64 with an Easy Flash 3 (with CCGMS-EF) + a PC running EF3USB
• a common PC/Mac running SyncTerm (ConnectionType=Telnet, ScreenMode=C64)
• C64 Forever, running CCGMS (included)

System requirements

• Java Development Kit (JDK) and JRE version 1.8+
• A machine that will act as server

Required skills

• Knowledge of Java language (compiler version 1.8+)
• BASIC TCP/IP concepts
• Knowledge of PETSCII encoding

Getting started

Let's suppose to build a very simple BBS that asks your name and welcomes you. The basic operation is to extend PetsciiThread class (or AsciiThread for ASCII BBS) implementing doLoop() method, such as:

public class WelcomeBBS extends PetsciiThread {
    
    // NEVER forget default (empty) constructor
    public WelcomeBBS() {
        super(); // Recommended
    }
    
    @Override
    public void doLoop() throws Exception {
    
        // clear screen
        cls();
        
        println("This is your brand-new BBS");
        println();
        print("Enter your name: ");

        // flush output 
        flush();
        
        // clear input buffer
        resetInput();
        
        String name = readLine();
        println();
        println("Welcome, " + name + "!");
        println("Press a key to exit");
        flush();
        readKey();

    }
}

this piece of code is enough to create a fully-functional but pretty simple BBS. The result will look like this:

All you have to do now is to build and run the BBS on your server, ready to be called by a PETSCII-enabled terminal client. Let's see how to do it in the following sections.

Building the server

Once you have written your own BBS as an extension of PetsciiThread class, simply build the fat jar with this command:

mvn clean package

The build process will result in the file petscii-bbs.jar, it will be found in the target directory. So you can run it with:

java -jar target/petscii-bbs.jar

Running the BBS Server

Running the server with no parameters, a help screen will be displayed:

usage: target/petscii-bbs.jar
    --bbs <bbsName:port>   Run specific BBSes (mandatory - see list below)
                           in the form <name1>:<port1> <name2>:<port2> ...
 -h,--help                 Displays help
 -s,--serviceport <arg>    TCP port used by service process, 0 for
                           no-service (default 0)
 -t,--timeout <arg>        Socket timeout in millis (default 60 minutes)
List of available BBS:
 * ...
 * WelcomeBBS

So we can rename the -jar file in bbs.jar, and the basic syntax for running our sample BBS is:

java -jar bbs.jar --bbs WelcomeBBS:6510

the port where the service will run is 6510 and the timeout is 3600000 milliseconds by default (1 hour). We can change the timeout parameter with -t switch:

java -jar bbs.jar --bbs WelcomeBBS:8088 -t 7200000

It's possible to run multiple BBSes, each one on a different port:

java -jar bbs.jar --bbs WelcomeBBS:6510 NewsBBS:8400 SportsBBS:9100 -t 7200000

(so the port will be 8088 with a timeout of 2 hours)

It's possibile to specify a "Service Port", which makes accessible (via web browser) the inspection of JVM running BBSes:

java -jar bbs.jar --bbs WelcomeBBS:6510 NewsBBS:8400 SportsBBS:9100 -s 8080

Keep it running

This .jar is intended to be a server process: it has to run all time. So, it's a good thing to run it in background if you use a UNIX shell using nohup command with bash "&" operator:

nohup java -jar bbs.jar --bbs WelcomeBBS:6510 &

It's VERY important not to forget the final & symbol to keep it running. After launching that, you can logoff from your server.

Stopping it

It's a plain process, so use plain ps and kill commands. If this jar is the only one running on your server, this command will do the work:

killall java

Sample BBSes in the package

You can study the sample BBSes (all classes that extend PetsciiThread) in the package eu.sblendorio.bbs.tenants as example of complete task. The package includes some proxies for accessing WordPress sites through Commodore 64 and a two classic strategy games (tic-tac-toe and connect-4)

Sample online BBSes

• bbs.sblendorio.eu - port 6510
• bbs.retrocampus.com - port 6510 (included in C64 Forever version of CCGMS)

Credits

Thanks to:

• Antonino Porcino for his browser-based PETSCII BBS Client emulator
• Brian W. Howell for the tic-tac-toe AI
• Felice Pagano for code optimizations
• Henrik Wetterström for droid64 project, used to read and open D64 files
• Jatin Thakur for the connect-4 AI
• Matteo Baccan for code optimizations
• Piero Corasaniti for the SD2IEC version of CSDB tenant
• Richard Bettridge for "Internet Browser" tenant
• Roberto Manicardi for adapting ZMPP to BBS engine
• Wei-ju Wu for ZMPP, a Java implementation of Z-Machine (Infocom text adventures)

Sample screenshot of the demo pack