đź“Ś Narwhal Bot Overview
Narwhal Bot is a custom Discord bot that pulls random images from subreddit caches and lets you interact with them in fun ways.
đź“‹ Cache System
The bot doesn’t hit Reddit directly every time — instead, it builds a local cache of posts from each subreddit.
A subreddit can only be used once it has been “ran against” (meaning the cache has been filled at least once).
Until then, commands will return “No cache file found.”
Once cached, images can be pulled instantly and repeatedly.
🔄 Feed Rotation & Resets
The bot rotates through feeds: top day, top month, top year, hot, new.
Daily feeds (day, hot, new) reset every new day.
Monthly feed (month) resets when the calendar month changes.
Yearly feed (year) resets when the year changes.
This ensures caches stay fresh without losing long‑term pagination progress.
🎲 Commands
/start_cache <subreddit>
Initializes the cache for a subreddit by pulling fresh posts from Reddit’s JSON feed. You must run this before using any image‑pulling commands. For best results, run it 4–5 times the first time you cache a subreddit. Returning on later days will add new trending posts. Sometimes, it may take 60+ seconds for the /start_cache command to complete. This is because of Reddit’s limits on how often the API can be hit. Just be patient and the caching will complete :)
/random_url <subreddit>
Returns one random cached image from the chosen subreddit.
/faceoff <subreddit>
Shows two random cached images side‑by‑side so users can vote on their favorite.
/count <subreddit>
Displays how many images are currently cached for the subreddit.
/get_cached_subreddits
Lists all subreddits that currently have cached images.
/news
Returns trending news links from a supported news‑based subreddit. Works only with:
nba, mlb, nfl, sports, news, worldnews, goodnews, nottheonion, technology, technews, science, pcgaming, gamingnews, television, entertainment.
/plinko
Starts a Plinko mini‑game. Earn points that can be used to bet in other games like /slot and /emoji_race.
/slot <bet>
Starts the slot machine mini‑game.
/emoji_race
Starts an emoji racing game where multiple players can place bets and watch the race together.
/support
Opens a support ticket with the bot’s admins.
/suggest
Sends a suggestion to the bot’s admins.
/help
Shows the help menu.
đź“ť Notes
Commands only work if the subreddit has been cached. use /start_cache <subreddit> to begin a first run of the cache. Recommend running it 2-3 times + to get a sizable amount of images. Only works well with image based subreddits.
The bot is designed for fun, voting, and sharing images — please keep interactions respectful.
