README.md

GenTogether - CS153 Example Discord Activity Project

This is an example of a final project that integrates with Discord as a Discord Activity.

GenTogether, powered by Black Forest Labs' image generation models, allows Discord users to generate images together, seeing each others' prompts and generated images in real time.

In the example below, we have two different users on each side generating images together:

CleanShot.2025-01-26.at.18.26.32.mp4

Discord Activities

Discord Activities are a type of Discord App that allows you to embed an iFrame of often a game or app into the Discord client. Users can launch activities in voice calls or text channels, and other users can join to participate in real time.

Activities are inherently more complex than bots, as they involve not only a web app, but implementation of a realtime server to facilitate communication of the state between users. However, they allow you to create incredible projects, as you're building the entire UX.

Tutorials

We've put together a few useful tutorials to help you get started.

Cursor Tutorial

Here's a short tutorial on how to use the Cursor IDE for building your projects. Run Cmd(ctrl)-I to open the composer if it doesn't show up for you!

Project Structure

In this example, the activity is split into two parts:

1. Activity web app: A (serverless) NextJS app that contains the game, Discord authentication, and image generation APIs. Maintains no state.
2. Realtime server: A Socket.IO server that maintains the state of the game and user connections.

This separation is important, as the NextJS app can't maintain state between serverless function calls. Our websocket server is just separated out.

To start the project, you'll need to run each of these separately at the same time.

Project Setup

Install cloudflared, a CLI for Cloudflare Tunnels, allowing you to create HTTPS tunnels for locally developed projects on your device.

Activity Web App Setup

1. Open a new terminal and cd into the activity folder, and install npm packages.

2. Go to https://discord.com/developers and click “New Application” in the top right corner.

3. Pick a cool name for your new app!

4. Create a .env file and put in these credentials from the Discord Developer Portal and Black Forest Labs.

   NEXT_PUBLIC_DISCORD_CLIENT_ID= DISCORD_CLIENT_SECRET= BFL_API_KEY=

5. Click the Activity Settings tab and turn on "Enable Activities"

Start the Web App

1. Run npm run dev to start the next app

2. Open a new terminal, and run npm run tunnel to start the Cloudflare tunnel. Make sure you installed the cloudflared CLI earlier up.

This URL is only valid while the terminal session is open. You will need to run this again and update this on the developer portal if you close the terminal or turn off your computer.

3. Copy the tunnel URL printed in the terminal into the "Root Mapping" field under "URL Mappings"

[image of that]

Start the Realtime Server

1. Open a new terminal and CD into the realtime-server folder, and install npm packages.

2. Run the server with npm run dev

3. Open a new terminal and start another cloudflare tunnel with npm run tunnel.

4. Tap the "Add Another URL Mapping" button and set it to /ws pointed to your URL.

BFL API Route

To allow images generated by BFL to display in the Discord app, we also need to add a URL mapping to their CDN. Discord proxies all requests via these URL Mappings.

Add another URL mapping with /gen set to delivery-us1.bfl.ai.

Run the activity

To start the activity in Discord, join a voice call and tap the shapes icon. Find your activity in the list and click the "Launch" button.

Authorizing other users

To allow other users to use your activity, they'll have to add it to their account with an OAuth link. Check out the Discord docs for more information on how to do this.