¶ Overview
When a cat is caught, the bot randomly picks a new time according to the channel's timing settings. The bot then saves this target time to the database and creates a task which waits until that time hits to spawn another cat.
When the time comes, the bot randomly picks a cat type (based on the spawn chances) and sends it to the channel. If it fails due to missing permissions or deleted channel it will unsetup the channel to prevent further errors.
It will choose the default if there is no custom spawn message.
¶ Spawn and Caught Messages
The default spawn message looks like this:
{emoji} {type} cat has appeared! Type '"cat" to catch it!
The default catch message looks like this for most cats:
{username} cought {emoji} {type} cat!!!!1!
You now have {number} cats of dat type!!!
this fella was cought in {time}!!!!
For special catch messages (by default), please refer to Cat Types.
¶ Rains
Starting a rain pauses the normal spawn cycle and forcibly spawns cats randomly every 2.5-3 seconds. Unlike normal spawning, the timer starts ticking right after a spawn is done, so if a cat is not caught within the ~2.5 seconds the next one will be lost.
There is a set amount of cats spawned in each rain, calculated as rain duration in seconds / 2.75.
¶ Restarts
When Cat Bot finishes starting up, it goes through every channel in which the target time is in and spawns a cat in them. This covers spawns which should have occurred during the restart. Additionally, every 5 minutes, a loop is run to check for any channels which are past due, either due to their tasks getting killed by the restart or something going wrong somewhere in the process. Cat Bot also keeps track of active channels to ensure that no duplicate spawns occur, maintaining a smooth and balanced spawning cycle across servers. If a cat remains uncaught for too long, Cat Bot automatically despawns it and resets the timer for that channel. The bot also logs spawn and catch events to improve performance tracking and help identify any bugs or timing issues. Over time, Cat Bot’s system adapts based on user activity, ensuring that more active servers experience more frequent cat appearances, while less active ones maintain a slower and more stable spawn rate.
This loop also handles saving cookies, updating status, posting stats to Top.gg, sending vote, quest, and timed reminders, as well as database backups.
¶ Commands
/setup, as well as setting up the bot, spawns the first cat to bootstrap the above infinite loop. /forget also makes the bot forget about any spawned cats as well as marks the channel as deleted to prevent any ongoing spawn tasks.
/forcespawn forces a cat to spawn, overriding any ongoing spawn tasks.
Due to how spawning works, /changetimings will only take effect after the next catch.
Spawn and catching messages can be modified with the /changemessage command.
¶ Spawning Troubleshooting
- Make sure you ran
/setupin the channel where you want cats to appear. - Try saying "cat". There might just be a cat in the channel, even if there is no appear message.
- Try using
/forcespawnto force the cat to spawn. - Do
/forgetand then/setupagain in the channel where you want cats to spawn. - If everything fails, create a post in the Cat Bot #support channel in our support server and we will help you.
¶ Catching
Here is a brief overview of what happens when you send cat:
- Check if there isn't a cat and user is in
/preventcatchmode.- If that's the case, react with :pointlaugh:.
- Complete belated quests, if needed
- Pick next spawn time
- This is done early so if something goes wrong during the catch, the spawn shouldn't be affected.
- Calculate catch time
- This is taken from message ID.
- Discord provides time in unix millis, so the time is accurate up to 3 digits after the floating point, but we only show 2 unless the time is under 1 second.
- Determine cat type (for cats which spawned before February 11, 2025 and weren't caught yet).
- This is done by scanning for emoji name (e.g. :finecat:) inside the message. This is the reason these are blacklisted from
/changemessage. - For example if failed, if the user deleted the spawn message, say "oopsie poopsie, i cant access the original message but [user] did catch a cat rn" and end early.
- Cat types after Feb 11, 2025 are stored in the database to remove the need of fetching original spawn message.
- This is done by scanning for emoji name (e.g. :finecat:) inside the message. This is the reason these are blacklisted from
- Calculate the prism boost chance.
- This includes extending the rain by 10 minutes or starting a new one if the eGirl cat got boosted.
- Handle powerups such as blessings and catnip.
- Randomly advertise Cat Rains (1/8) with "☔ get tons of cats and have fun:
/rain" (changes during sales) - Randomly show a fun fact/hint about itself (1/20). For example, it may say "View all cats and rarities with /catalogue".
- Choose either the channel's custom catch message or a cat themed one (if any). Note: custom catch messages take priority.
- Choose a button to attach.
- 1/11 chance with 20 or more Fine cats in inventory with the Dark Market not activated - You see a shadow...
- Didn't vote - Vote button, which show any one of 19 different (usually silly) messages linking to cat bot's top.gg page. It can say:
- You havent voted today!
- I know you haven't voted
- If vote cat will you friend
- Vote cat for president
- vote = 0.01% to escape basement
- vote vote vote vote vote
- mrrp mrrow go and vote now
- if you vote you'll be free (no)
- vote. btw, i have a pipebomb
- No votes? :megamind:
- Cat says you should vote
- cat will be happy if you vote
- VOTE NOW!!!!!
- I voted and got 1000000$
- I voted and found a gf
- lebron james forgot to vote
- vote if you like cats
- vote if cats > dogs
- you should vote for cat NOW!
- I'd vote if I were you
- 1/21 - Join our Discord!
- 1/501 - John Discord 🤠
- 1/50001 - DAVE DISCORD 😀💀⚠️🥺
- 1/5000001 - JOHN AND DAVE HAD A SON 💀🤠😀⚠️🥺
- Otherwise: don't attach a button.
- Add the cats to the user.
- In parallel: send the catch result message and delete the spawn message
- Set fastest and slowest personal bests if needed.
- Give out achievements, if needed.
- Complete quests, if needed
- Complete mafia bounties, if needed
- Detect if a rain ended unexpectedly (it might take a couple catches as the check is only run a bit after the rain should have normally ended).
- If so, restart it and add 3 cats to it as compensation.
- Sleep until the next decided spawn time.
- Spawn a cat
¶ Trivia
-
There was a special message added on April 29th 2025 for a 0 second catch: "this fella was cought in 0.000 seconds (woah)".
-
The new rain system was added on August 11th 2025.
-
The "should end" formula is calculated like this:
floor(rain time + 600 * 1.3)fromfloor(rain time + 600 * 1.2)since August 24th 2025. -
Catching was optimized on October 27th 2025
- Cat Bot should now react to catches at least ~65ms faster on average, but it could be longer depending on whether the catch was blessed/prism boosted.