¶ 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.
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. The bot also logs spawn and catch events to improve performance tracking and help identify any bugs or timing issues.
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 makes the bot forget about any spawned cats as well as marks the channel as unsetup to prevent any ongoing spawns.
/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 the
/setupcommand in the channel where you want cats to appear. - Do
/forgetand then/setupagain in the channel where you want cats to spawn. - Try using
/forcespawnto force the cat to spawn. - Try saying "cat". There might just be a cat in the channel, even if there is no appear message.
- If everything fails, join our support server and open a ticket, the moderation team 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 or user attempted to double catch with anti-double catch setting enabled.- If that's the case, react with :pointlaugh:.
- Complete belated quests, if needed
- Pick next spawn time
- If there are more than 5 normal spawns in that second and it is a normal spawn, shift the time -11 to 11 seconds to prevent hitting global ratelimits.
- 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 doesn't mean they now aren't blacklisted though.
- 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 50 or more cats in the inventory - a "You see a shadow..." button appears.
- 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 💀🤠😀⚠️🥺"
The four buttons above all link to Cat Stand, the support server.
- Otherwise: don't attach a button.
- Add the cats to the user and 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.
- Do event objective, 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 rain check 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