feat: Add coinflip command with optional prediction

.dockerignore

@@ -1 +1,2 @@
 data/
+.venv/

locales/strings.en-US.json

@@ -78,6 +78,19 @@
   "case_type_field": "Type:",
   "case_type_field_value": "`{0}`",
   "case_type_field_value_with_duration": "`{0} ({1})`",
+  "coinflip_correct_prediction_author": "Correct Prediction!",
+  "coinflip_correct_prediction_description": "The coin landed on **{0}**. You predicted correctly!",
+  "coinflip_flipping_animation_1": "\ud83e\ude79 Flipping...",
+  "coinflip_flipping_animation_2": "\ud83e\ude79 Flipping..",
+  "coinflip_flipping_animation_3": "\ud83e\ude79 Flipping.",
+  "coinflip_flipping_author": "Flipping a Coin",
+  "coinflip_flipping_description": "The coin is in the air...",
+  "coinflip_invalid_prediction_author": "Invalid Prediction",
+  "coinflip_invalid_prediction_description": "Please enter a valid prediction ('heads'/'h' or 'tails'/'t').",
+  "coinflip_result_author": "Coin Flip Result",
+  "coinflip_result_description": "The coin landed on **{0}**.",
+  "coinflip_wrong_prediction_author": "Wrong Prediction",
+  "coinflip_wrong_prediction_description": "The coin landed on **{0}**. Your prediction was incorrect.",
   "config_author": "Server Configuration",
   "config_birthday_channel_set": "birthday announcements will be sent in {0}.",
   "config_birthday_module_already_disabled": "the birthday module was already disabled.",

modules/economy/coinflip.py

@@ -0,0 +1,102 @@
+import asyncio
+import random
+
+from discord.ext import commands
+
+import lib.format
+from lib.client import Luminara
+from lib.const import CONST
+from ui.embeds import Builder
+
+
+class Coinflip(commands.Cog):
+    def __init__(self, bot: Luminara) -> None:
+        self.bot: Luminara = bot
+        self.coinflip.usage = lib.format.generate_usage(self.coinflip)
+
+    @commands.hybrid_command(
+        name="coinflip",
+        aliases=["cf"],
+    )
+    @commands.guild_only()
+    async def coinflip(
+        self,
+        ctx: commands.Context[Luminara],
+        prediction: str | None = None,
+    ) -> None:
+        """
+        Flip a coin. Optionally predict the outcome.
+
+        Parameters
+        ----------
+        ctx : commands.Context[Luminara]
+            The context of the command.
+        prediction : str, optional
+            The predicted outcome ('heads'/'h' or 'tails'/'t').
+        """
+        result = random.choice(["heads", "tails"])
+
+        flip_embed = Builder.create_embed(
+            Builder.INFO,
+            user_name=ctx.author.name,
+            author_text=CONST.STRINGS["coinflip_flipping_author"],
+            description=CONST.STRINGS["coinflip_flipping_description"],
+        )
+        flip_message = await ctx.send(embed=flip_embed)
+
+        await asyncio.sleep(1)
+
+        for animation in (
+            CONST.STRINGS["coinflip_flipping_animation_1"],
+            CONST.STRINGS["coinflip_flipping_animation_2"],
+            CONST.STRINGS["coinflip_flipping_animation_3"],
+        ):
+            flip_embed = Builder.create_embed(
+                Builder.INFO,
+                user_name=ctx.author.name,
+                author_text=CONST.STRINGS["coinflip_flipping_author"],
+                description=animation,
+            )
+            await flip_message.edit(embed=flip_embed)
+            await asyncio.sleep(0.5)
+
+        if prediction:
+            prediction = prediction.lower()
+            if prediction in ["heads", "h", "tails", "t"]:
+                predicted_correctly = (prediction.startswith("h") and result == "heads") or (
+                    prediction.startswith("t") and result == "tails"
+                )
+                if predicted_correctly:
+                    embed = Builder.create_embed(
+                        Builder.SUCCESS,
+                        user_name=ctx.author.name,
+                        author_text=CONST.STRINGS["coinflip_correct_prediction_author"],
+                        description=CONST.STRINGS["coinflip_correct_prediction_description"].format(result),
+                    )
+                else:
+                    embed = Builder.create_embed(
+                        Builder.ERROR,
+                        user_name=ctx.author.name,
+                        author_text=CONST.STRINGS["coinflip_wrong_prediction_author"],
+                        description=CONST.STRINGS["coinflip_wrong_prediction_description"].format(result),
+                    )
+            else:
+                embed = Builder.create_embed(
+                    Builder.ERROR,
+                    user_name=ctx.author.name,
+                    author_text=CONST.STRINGS["coinflip_invalid_prediction_author"],
+                    description=CONST.STRINGS["coinflip_invalid_prediction_description"],
+                )
+        else:
+            embed = Builder.create_embed(
+                Builder.INFO,
+                user_name=ctx.author.name,
+                author_text=CONST.STRINGS["coinflip_result_author"],
+                description=CONST.STRINGS["coinflip_result_description"].format(result),
+            )
+
+        await flip_message.edit(embed=embed)
+
+
+async def setup(bot: Luminara) -> None:
+    await bot.add_cog(Coinflip(bot))