Documentation Index
Fetch the complete documentation index at: https://mintlify.com/developer51709/Noxie/llms.txt
Use this file to discover all available pages before exploring further.
Mood banners are the visual personality layer of every Noxie response. They are JPEG images of Noxie’s face in different emotional states — sleepy during cooldowns, love-struck after a legendary pull, full evil for a mythic catch. Banners live in the mood_banners/ directory, and the entire selection pipeline is handled by utils/face_manager.py, which maps events, rarities, and creature moods to the correct file path.
How Banners Work
Every CV2 container that carries a mood banner uses the same render pattern: a discord.ui.MediaGallery component placed at the bottom of the discord.ui.Container, after a hidden separator. The image is sent as a discord.File attachment, and the gallery references it via attachment://filename.
The low-level helper in utils/cv2_helpers.py:
def _media(attachment_name: str) -> discord.ui.MediaGallery:
return discord.ui.MediaGallery(
discord.MediaGalleryItem(media=f"attachment://{attachment_name}")
)
if banner_path:
banner_filename = f"banner_{rarity}.jpeg"
container.add_item(_sep(visible=False))
container.add_item(_media(banner_filename))
files.append(_make_file(banner_path, banner_filename))
Banners are always sent as Discord File attachments. The attachment://filename URI in the MediaGallery must exactly match the filename argument passed to discord.File. Mismatches silently result in a broken image in the container.
All 14 Banners
| File Name | Mood Key | Used For |
|---|
neutral.jpeg | neutral | Default state, common hunts |
happy.jpeg | happy | Pull success |
evil.jpeg | evil | Mythic hunts, chaos reactions |
dizzy.jpeg | dizzy | Errors, donation failure |
deadpan.jpeg | deadpan | Sarcastic personality, pull failure |
cozy.jpeg | cozy | Uncommon hunts, cozy tone |
chaotic.jpeg | chaotic | Chaotic personality |
sarcastic.jpeg | sarcastic | Sarcastic responses |
carinha.jpeg | carinha | Soft reactions |
melancholy.jpeg | melancholy | Hunt failures, sad events, guild leave |
sleepy.jpeg | sleepy | Hunt cooldowns |
excited.jpeg | excited | Epic hunts, donation start |
love.jpeg | love | Legendary hunts, donation confirmed, guild join |
rare.jpeg | rare | Rare hunts |
mood_banner_path() function in utils/helpers.py holds the authoritative filename mapping and checks that the file actually exists on disk before returning a path:
def mood_banner_path(mood: str) -> str | None:
banner_dir = ROOT / "mood_banners"
mapping = {
"neutral": "neutral.jpeg", "happy": "happy.jpeg",
"evil": "evil.jpeg", "dizzy": "dizzy.jpeg",
"deadpan": "deadpan.jpeg", "cozy": "cozy.jpeg",
"chaotic": "chaotic.jpeg", "sarcastic": "sarcastic.jpeg",
"carinha": "carinha.jpeg", "melancholy": "melancholy.jpeg",
"sleepy": "sleepy.jpeg", "excited": "excited.jpeg",
"love": "love.jpeg", "rare": "rare.jpeg",
}
filename = mapping.get(mood)
if filename:
full = banner_dir / filename
if full.exists():
return str(full)
return None
Rarity → Banner Mapping
When a hunt result is ready, face_manager.get_face_for_rarity(rarity) selects the default banner based on the rarity rolled. This mapping is defined in utils/helpers.py as RARITY_MOOD:
| Rarity | Mood Key | Banner File |
|---|
common | neutral | neutral.jpeg |
uncommon | cozy | cozy.jpeg |
rare | rare | rare.jpeg |
epic | excited | excited.jpeg |
legendary | love | love.jpeg |
mythic | evil | evil.jpeg |
RARITY_MOOD = {
"common": "neutral",
"uncommon": "cozy",
"rare": "rare",
"epic": "excited",
"legendary": "love",
"mythic": "evil",
}
Event → Banner Mapping
For non-hunt contexts, face_manager.get_face_for_event(event) resolves the banner through the EVENT_MOOD dict in utils/face_manager.py:
| Event Key | Mood Key | Banner File |
|---|
cooldown | sleepy | sleepy.jpeg |
error | dizzy | dizzy.jpeg |
guild_join | love | love.jpeg |
guild_leave | melancholy | melancholy.jpeg |
donate_start | excited | excited.jpeg |
donate_done | love | love.jpeg |
donate_fail | dizzy | dizzy.jpeg |
pull_success | happy | happy.jpeg |
pull_fail | deadpan | deadpan.jpeg |
hunt_fail | melancholy | melancholy.jpeg |
reaction_uwu | love | love.jpeg |
reaction_evil | evil | evil.jpeg |
reaction_cozy | cozy | cozy.jpeg |
get_face_for_event() falls back to neutral:
def get_face_for_event(event: str) -> str | None:
mood = EVENT_MOOD.get(event, "neutral")
return mood_banner_path(mood)
Creature Mood Override
During a hunt, the caught creature’s own mood can override the rarity-based banner. face_manager.get_face_for_creature_mood() maps creature moods through the mood_* event family:
| Creature Mood | Event Key | Banner File |
|---|
melancholy | mood_melancholy | melancholy.jpeg |
chaotic | mood_chaotic | chaotic.jpeg |
cozy | mood_cozy | cozy.jpeg |
neutral | mood_neutral | neutral.jpeg |
sarcastic | mood_sarcastic | sarcastic.jpeg |
cogs/hunt.py ensures the creature’s mood always takes priority:
banner_path = face_manager.get_face_for_rarity(rarity)
creature_mood_banner = face_manager.get_face_for_creature_mood(creature.get("mood", "neutral"))
final_banner = creature_mood_banner or banner_path
melancholy Gloomfox always shows the melancholy.jpeg banner — even though Gloomfox is common and the rarity default would be neutral.jpeg.
Adding a New Banner
- Drop the
.jpeg file into mood_banners/.
- Add the mood key → filename entry to the
mapping dict in utils/helpers.py::mood_banner_path().
- Add the event key → mood key entry to
EVENT_MOOD in utils/face_manager.py (if the new mood will be triggered by an event).
- Call
face_manager.get_face_for_event("your_event") wherever you want the banner to appear.
No schema changes or bot restarts beyond a normal reload are required.
The mood_banner_path() function checks that the file exists on disk and returns None if it doesn’t. A None banner path is safe — the container will render without a banner — but the missing file will go silently unnoticed. Verify filenames carefully when adding new assets.
