PluralKit WebSocket Server for Resonite

A WebSocket server that integrates with PluralKit API to enable front switching in Resonite using ProtoFlux.

Features

• 🔄 Real-time front switching via WebSocket
• 📡 PluralKit API integration
• 🎮 ProtoFlux-compatible client
• ⚙️ Easy configuration via JSON file
• 🔌 Multiple client support
• 📊 Real-time member information
• 🎨 Member color support
• 📝 Name-based member switching

Setup

1. Install Dependencies

npm install

2. Configure PluralKit

1. Get your PluralKit token from PluralKit.me
2. Get your system ID from your PluralKit dashboard
3. Copy the example config and fill in your details:

cp config.example.json config.json

4. Edit config.json with your actual token and system ID:

{
  "pluralkit": {
    "token": "your_actual_pluralkit_token_here",
    "systemId": "your_system_id_here"
  },
  "websocket": {
    "port": 8080,
    "host": "localhost"
  }
}

3. Start the Server

npm start

For development with auto-restart:

npm run dev

Usage

WebSocket API

The server accepts the following message types:

Switch Front

{
  "type": "switch_front",
  "data": {
    "memberId": "member_id_here"
  }
}

Get Current Front

{
  "type": "get_current_front",
  "data": {}
}

Get All Members

{
  "type": "get_members",
  "data": {}
}

Ping

{
  "type": "ping",
  "data": {}
}

Server Responses

Connected

{
  "type": "connected",
  "data": {
    "clientId": "unique_client_id",
    "currentFront": {
      "id": "member_id",
      "name": "Member Name",
      "displayName": "Display Name",
      "pronouns": "they/them"
    },
    "availableMembers": [...]
  }
}

Front Switched

{
  "type": "front_switched",
  "data": {
    "member": {
      "id": "member_id",
      "name": "Member Name",
      "displayName": "Display Name",
      "pronouns": "they/them"
    },
    "timestamp": 1234567890
  }
}

Error

{
  "type": "error",
  "data": {
    "message": "Error description"
  }
}

ProtoFlux Integration

Basic WebSocket Connection

In ProtoFlux, you can connect to the WebSocket server using:

1. WebSocket Connect Node: Set URL to ws://localhost:8080
2. WebSocket Send Node: Send JSON messages as strings
3. WebSocket Receive Node: Parse incoming JSON messages

Example ProtoFlux Flow

1. Connect: Use WebSocket Connect node
2. Send Switch Command:
   • Create a JSON string: {"type":"switch_front","data":{"memberId":"your_member_id"}}
   • Send via WebSocket Send node
3. Handle Response:
   • Receive via WebSocket Receive node
   • Parse JSON and check message type
   • Update UI or trigger other actions

JavaScript Client Example

For testing or advanced usage, you can use the provided JavaScript client:

const PluralKitWebSocketClient = require('./protoflux-client');

const client = new PluralKitWebSocketClient('ws://localhost:8080');

// Connect
await client.connect();

// Switch front by member ID
client.switchFront('member_id_here');

// Switch front by name
client.switchFrontByName('Member Name');

// Get current front
client.getCurrentFront();

// Get all members
client.getMembers();

Configuration Options

config.json

{
  "pluralkit": {
    "token": "your_pluralkit_token",
    "systemId": "your_system_id"
  },
  "websocket": {
    "port": 8080,
    "host": "localhost"
  },
  "logging": {
    "level": "info",
    "logToFile": true
  }
}

Troubleshooting

Common Issues

1. "Please set your PluralKit token"

   • Make sure you've updated config.json with your actual token

2. "Member not found"

   • Verify the member ID exists in your system
   • Check that the member is active

3. WebSocket connection failed

   • Ensure the server is running
   • Check the port isn't blocked by firewall
   • Verify the URL is correct

4. API errors

   • Check your PluralKit token is valid
   • Ensure your system ID is correct
   • Verify you have permission to switch fronts

Logs

The server logs all important events to the console. For production use, consider setting up proper logging.

Security Notes

• Keep your PluralKit token secure
• Don't commit config.json with real tokens to version control
• The .gitignore file prevents config.json from being committed
• Consider using environment variables for production
• The WebSocket server has no authentication - add it if needed for production

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - feel free to modify and use as needed.

Support

If you encounter any issues or have questions:

1. Check the commands.txt file for available commands
2. Review the server logs for error messages
3. Ensure your PluralKit token and system ID are correct
4. Verify the WebSocket connection is working properly