F-List Java WebSocket Bot

A modular Java bot for the F-List chat WebSocket API with a clean separation between:

• Transport layer (WebSocket connection, queues, reconnect logic)
• Application layer (command handling, persistence, bot behavior)

This README gives a developer everything needed to run, understand, and extend the bot.

---

Architecture Overview

The project is structured around three main components:

Main → BotTransport → BotApplication
                  ↘
             FListWebSocketClient

1. Main

Bootstraps the application and transport.

• Loads account settings
• Starts the bot application
• Starts the transport layer
• Keeps JVM alive

2. BotTransport

Handles all networking and runtime orchestration.

Responsibilities:

• WebSocket connection lifecycle
• Reconnect logic
• Message queues (inbound/outbound)
• Message pump
• Watchdog monitoring
• Sending outbound messages

Does not contain bot logic.

3. BotApplication

Contains all bot logic and persistence.

Responsibilities:

• Command parsing (!help, !ping, etc.)
• Saving / backup
• Autosave timer
• Data storage

Does not know about WebSockets.

4. FListWebSocketClient

Low-level WebSocket adapter.

Responsibilities:

• Connect to F-List WebSocket
• Send raw protocol frames
• Parse incoming frames into Message
• Notify BotTransport

No command logic here.

---

Message Flow

||       InQueue      ||   ||Processing||   ||      OutQueue      ||
WebSocket → BotTransport → BotApplication → BotTransport → WebSocket

1. Server sends MSG or PRI depending on message type
2. WebSocket client parses → Message
3. Transport enqueues inbound
4. Pump calls BotApplication.handle()
5. BotApplication returns response message
6. Transport enqueues outbound
7. Transport sends frame to server

---

Requirements

• Java 17+
• Gradle 7.3+ (wrapper included)

Dependencies:

• OkHttp (WebSocket)
• org.json
• SLF4J + Logback

---

Setup

1. Configure account settings

Create file:

LocalVariables/accountSettings.txt

Format:

AccountName:yourAccount;
AccountPassword:yourPassword;
CharacterName:Your Character;
CName:Your Character;
Channel:adh-xxxxxxxxxxxxxxxx

⚠️ Do NOT commit this file to version control. You get the "Channel Code" by typing /code in a channel.

---

2. Run the bot

From project root:

./gradlew runMain

or Windows:

.\gradlew.bat runMain

---

Commands

Default prefix: !

Example Commands Implemented

Command	Description
!help	Show command list
!ping	Test response
!save	Save character data
!backup	Create backup

Add commands in BotApplication.handleCommand().

---

Extending the Bot

Adding a new command

In BotApplication:

case "roll" -> {
    incoming.setOutputMessage("You rolled a 4");
    return incoming;
}

Sending multiple messages

Return multiple messages or queue them manually in BotTransport.

Ignoring self messages (recommended)

In BotTransport.onIncomingMessage():

if (message.characterName.equalsIgnoreCase(settings.characterName())) {
    return;
}

Prevents bot responding to its own messages.

---

Ticket / Login Handling

The bot uses F-List API ticket authentication.

Tickets are cached and refreshed automatically.

If you see:

Login Failed. Too many failed attempts. Requests throttled.

Wait before retrying. The bot will back off automatically.

---

Logging

Logs are printed to console with timestamps.

Adjust logging in BotApplication.log() or configure Logback.

---

Common Issues

No response to commands

Check:

• Prefix is correct
• Bot joined correct channel
• MessageQueue is thread-safe
• handle() returns a message

WebSocket connects but no messages

Check:

• Channel ID correct
• Character logged in
• Server echo disabled
• Watchdog logs

Ticket errors

Check:

• Credentials
• Throttling
• Network connectivity

---

Development Tips

• All networking is isolated in BotTransport
• All logic belongs in BotApplication
• Never put bot logic in WebSocket client
• Never put network logic in BotApplication

---

Project Structure

org.example
 ├─ Main.java
 └─ Websocket
     ├─ BotApplication.java
     ├─ BotTransport.java
     ├─ FListWebSocketClient.java
     ├─ FListAuthService.java
     ├─ Message.java
     └─ MessageQueue.java

---

Contributing

When modifying code:

1. Keep transport and application separate
2. Add logs for new flows
3. Test commands locally
4. Avoid blocking inside handle()

---

License

Internal / personal use unless otherwise specified.