Fun & Social Commands

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/fun/facts.ts
• src/commands/fun/love.ts
• src/commands/fun/react.ts
• src/commands/fun/tod.ts
• src/commands/fun/generators.ts
• src/data/respFun.json
• types/third-party.d.ts
• package.json

The Fun & Social commands in Amina are a suite of features designed to increase user engagement and provide entertainment within a Discord server. These commands range from simple social calculations and party games to interactive commands that fetch content from external APIs. They are a core part of Amina's "multipurpose" nature, offering a lighter, more interactive experience alongside the bot's utility and moderation capabilities.

A key architectural aspect of these commands is their integration with the mina response helper and the structured JSON response files, such as respFun.json. This allows for consistent, personality-driven text and embeds across all fun commands, reinforcing the bot's character. Many commands also leverage external APIs for dynamic content or use third-party libraries for game mechanics.

Command Overview

The following table summarizes the primary commands within the Fun & Social category.

Command	Category	Description
/facts	FUN	Get random facts and images about various animals.
/love	FUN	Calculate a "totally scientific" love percentage between two users.
/react	ANIME	Send anime-style reaction GIFs like hug, pat, or slap.
/tod	FUN	Play party games like Truth or Dare, Would You Rather, etc.
/generator	IMAGE	Create meme images using various templates and a user's avatar.
/hangman	FUN	A classic game of Hangman. (Uses discord-gamecord library)

Sources: src/commands/fun/facts.ts:1-29, src/commands/fun/love.ts:1-24, src/commands/fun/react.ts:1-32, src/commands/fun/tod.ts:1-45, src/commands/fun/generators.ts:1-55, src/data/respFun.json:2-10

API-Driven Content Commands

Several fun commands rely on external APIs to fetch dynamic images and text, providing fresh content for users.

/facts Command

This command fetches a random fact and an accompanying image for a specified animal from the some-random-api.com API.

The command execution flow is as follows:

1. The user selects an animal from a predefined list.
2. The bot constructs a URL to the API endpoint (e.g., https://some-random-api.com/animal/cat).
3. A GET request is made to the API.
4. If successful, the bot parses the JSON response to extract the fact and image URL.
5. A random introductory phrase is selected from respFun.json.
6. An embed is constructed with the title, fact, image, and a footer crediting the user.

Sources: src/commands/fun/facts.ts:31-80, src/data/respFun.json:89-99

The following sequence diagram illustrates the /facts command flow.

The available animals are hardcoded in the command file.

Animal Choices for /facts
cat
dog
panda
fox
red_panda
koala
bird
raccoon
kangaroo

Sources: src/commands/fun/facts.ts:20-29

/react Command

The /react command sends an anime-style reaction GIF. It can be directed at another user, and it attempts to use correct pronouns in the response message.

The logic involves these steps:

1. Fetch a reaction GIF from the api.waifu.pics SFW endpoint.
2. If a target user is specified, attempt to fetch their pronouns.
   1. First, check Amina's internal user database (User schema).
   2. If not found, query the external pronoundb.org API.
3. Generate a descriptive message using the author, target, and fetched pronouns.
4. Construct and send an embed containing the message and the GIF.

Sources: src/commands/fun/react.ts:34-162

This diagram shows the data flow for the /react command, including the pronoun lookup.

/generator Command

This command creates a meme by overlaying a user's avatar (or a provided image link) onto a template using an external image generation API.

• API Endpoint: The base URL is configured in src/config.ts under IMAGE.BASE_API.
• Authentication: The request includes an authorization header with an API key from secret.STRANGE_API_KEY.
• Image Source: The command prioritizes the avatar of a mentioned user, then a provided image link, and finally defaults to the command author's avatar.

Sources: src/commands/fun/generators.ts:57-108

Party & Social Games

/tod (Truth or Dare & More)

This is a comprehensive party game command with multiple modes and a content rating system.

Subcommands & Modes

The /tod command is structured with several subcommands, each representing a different game mode.

Subcommand	Description
truth	Asks a "truth" question.
dare	Gives a "dare" challenge.
paranoia	Asks a "paranoia" question.
nhie	"Never Have I Ever..."
wyr	"Would You Rather..."
hye	"Have You Ever..."
wwyd	"What Would You Do..."
random	A random question from any category.

Sources: src/commands/fun/tod.ts:30-44

Content Rating & Safety

The command implements a robust rating and safety system to ensure content is appropriate.

1. Ratings: PG (default), PG-16, and R (18+ NSFW).
2. User Preference: A user can set a preferred rating, which is stored in the User schema (todRating field). The command will use a requested rating for a single command over the user's preference.
3. Age Verification: For PG-16 and R ratings, the system checks the user's age from their profile (user.profile.age). If the user is underage, the rating is automatically downgraded to PG.
4. NSFW Channel Check: R-rated content can only be used in channels marked as NSFW in Discord.

Sources: src/commands/fun/tod.ts:58-96

This flowchart illustrates the logic for handling a /tod command request.

/hangman

The Hangman game is implemented using the discord-gamecord third-party library. The command options and game messages are configured within Amina to match the bot's personality.

• Dependency: discord-gamecord is listed as a dependency in package.json.
• Type Definitions: The options for the Hangman class from this library are defined in types/third-party.d.ts. This includes game messages, theme, and hangman parts.
• Game Logic: The core game loop (tracking guesses, checking letters, determining win/loss) is handled by the external library. Amina is responsible for initiating the game and displaying the results.

Sources: package.json:34, types/third-party.d.ts:74-86, src/data/respFun.json:101-105

Social Calculation Commands

/love Command

This command calculates a "love percentage" between two users. The logic is intentionally simple for fun.

1. Two users are provided as input.
2. A random number between 1 and 100 is generated.
3. Based on the resulting percentage, a "love status" (perfect, good, decent, low) and a corresponding random response message are selected from respFun.json.
4. An embed is created with the result, status, and a relevant GIF.

Sources: src/commands/fun/love.ts:26-90, src/data/respFun.json:28-59

This diagram shows the simple logic flow for the /love command.