Version 1.0.0

SHARDS Hub

Complete Toolkit for Visual Novel Development
Ren'Py Framework Modular Architecture Achievements Gallery Music Player Favorites
Click a module card to view its documentation
itch.io Studio
Modules
▓

HUB Core

The foundation module that makes everything work together seamlessly, handling all the technical details so you can focus on creating your story.

  • Universal Font Fallback System
  • Automatic Module Detection
  • Unified Dashboard Interface
  • Cross-Module Compatibility
★

Achievements Core

Reward players with achievements that celebrate their journey through your story, featuring Steam integration and custom icons.

  • Steam Auto Integration
  • Custom Achievement Icons
  • Hidden Achievements
  • Progress Tracking
▪

Gallery Core

Create a gallery where players can revisit scenes, organized by chapters with advanced filtering and search capabilities.

  • Multi-Chapter Organization
  • Category Tag Filtering
  • Intelligent Layout System
  • Favorites Integration
♪

Music Player

Professional music player with interactive controls, category organization, favorites system, and clickable progress bars.

  • MusicRoom Integration
  • Category Organization
  • Favorites System
  • Play Statistics
◊

Favorites Plus

Smart system that captures scenes automatically and lets players organize them with custom tags and categories.

  • Universal Screen Capture
  • Intelligent Content Detection
  • Smart Tagging System
  • View Counter Tracking
•

TBA

Exciting new module coming soon to expand your visual novel development toolkit.

  • Advanced Features Coming
  • Enhanced Integration
  • Developer-Friendly Design
  • Stay Tuned for Updates
▴

TBA

Another innovative module in development to further enhance your visual novel projects.

  • Powerful New Capabilities
  • Seamless SHARDS Integration
  • Professional Quality Features
  • Coming Soon

HUB Core

Overview

HUB Core is the foundation module that makes everything work together seamlessly. It handles technical details like font management and module detection, allowing you to focus on creating your visual novel.

Features

  • Universal Font System - Works with any gui.rpy setup with intelligent fallbacks
  • Smart Module Detection - Automatically finds and organizes SHARDS modules
  • Unified Dashboard - Single interface that shows all modules
  • Icon Management - Consistent icons across all modules
  • Easy Integration - Add to your main menu with one line of code

The module is designed to be self-contained with minimal configuration required.

Basic Usage

Main Menu Integration

Add these to your main menu screen:

# Single module launchers textbutton "Gallery" action Function(shards_launch_gallery) textbutton "Music Player" action Function(shards_launch_music) textbutton "Achievements" action Function(shards_launch_achievements) textbutton "Favorites" action Function(shards_launch_favorites) # Unified interface (shows all modules, installed and uninstalled) textbutton "SHARDS Hub" action Function(shards_launch_unified_hub)

Module Detection

# Check what's installed modules = shards_hub_detect_modules() if modules["gallery"]["enabled"]: # Gallery is available pass # Quick check for complete bundle if shards_hub_is_full_bundle(): # All modules installed pass

Enhanced Font System

The font system intelligently finds and uses the best available fonts with multiple fallback options, including specialized font functions for different use cases:

# Original font functions title_font = get_actsname_fonts() body_font = get_chartagline_fonts() # New specialized font functions cinzel_font = get_cinzel_font() calsans_font = get_calsans_font() readex_font = get_readexpro_font() interface_font = get_interface_font() dialogue_font = get_dialogue_font() # System information font_info = get_shards_hub_font_info() available_fonts = shards_hub_list_available_fonts()
Enhanced Fallback System:
  1. gui.interface_text_font - Your existing GUI setup
  2. gui.text_font - Alternative GUI font
  3. New! /Fonts/ folder - Your main fonts directory
  4. /fonts/ folder - Original fallback location
  5. /SHARDS_Hub/Fonts/ - Module-specific fonts
  6. /font/ and /Font/ - Additional fallback folders
  7. None (uses Ren'Py default)
Specialized Font Collection:

The system now includes specific fonts with intelligent fallbacks:

  • Cinzel-Regular.ttf - Elegant serif for titles and headings
  • CalSans-Regular.ttf - Modern geometric display font
  • ReadexPro-ExtraLight.ttf - Clean, readable font for body text
  • Inter-Regular.ttf - Priority interface font
  • Roboto-Regular.ttf - Secondary priority font
  • OpenSans-Regular.ttf - Clean web-safe option
  • NunitoSans-Regular.ttf - Friendly sans-serif alternative
  • SourceSansPro-Regular.ttf - Professional coding font
Google Material Design Icons:

The system integrates Google Material Design icons for modern, consistent UI elements throughout all modules, providing a professional and cohesive visual experience.

Supported Formats:

TTF, OTF, WOFF, WOFF2 - all the modern font formats you need!

Universal Notification System

New in this version! HUB Core includes a centralized notification overlay system that provides consistent, beautiful notifications across all SHARDS modules. This system replaces individual module notification systems with a unified approach.

Notification Types:
  • Achievement - Gold color (#FFD700) for achievement unlocks
  • Scene Unlock - Purple color (#9B59B6) for gallery scene unlocks
  • Favorite - Teal color (#4ECDC4) for favorite additions
  • General - White color for custom notifications

Notification Functions

# Universal notification function $ shards_show_notification("Title", "notification_type", duration=3.5) # Specific notification types $ shards_show_achievement_notification("achievement_id") $ shards_show_scene_unlock_notification("Scene Title") $ shards_show_favorite_notification("Item Name") # Examples $ shards_show_notification("Achievement Unlocked!", "achievement") $ shards_show_notification("Scene Unlocked!", "scene_unlock") $ shards_show_notification("Added to Favorites", "favorite") $ shards_show_notification("Custom Message", "general")
Visual Design:
  • Elegant Animation - Smooth slide-in from top with fade
  • Color-Coded - Each notification type has distinct colors
  • Consistent Styling - Uses SHARDS Hub font system
  • Customizable Duration - Control how long notifications display
  • Background Support - Custom background images supported

Module Integration

All SHARDS modules automatically use this notification system when available:

# Achievements Module # Automatically shows gold notifications when achievements unlock # Gallery Module # Shows purple notifications when scenes unlock (NEW!) $ shards_gallery_unlock_scene("chapter1", "scene_id") # Shows notification # Disable notifications for bulk operations $ shards_gallery_unlock_scene("chapter1", "scene_id", show_notification=False) # Favorites Module # Shows teal notifications when items are favorited via F-key
Developer Notes:

The notification system provides backwards compatibility - modules will fall back to simple renpy.notify() if the notification system isn't available, making it safe to use in any configuration.

API Reference

Core Functions

# Module Detection modules = shards_hub_detect_modules() # Detect all Installed Modules is_full = shards_hub_is_full_bundle() # Check if All Modules Installed enabled = shards_hub_get_enabled_modules() # Get List of Enabled Modules count = shards_hub_get_module_count() # Get Total Module Count # Statistics stats = shards_hub_get_statistics() # Get Aggregated Statistics # Module Launchers shards_launch_gallery() # Launch Gallery Core shards_launch_music() # Launch Music Player shards_launch_favorites() # Launch Favorites Plus shards_launch_achievements() # Launch Achievements Core shards_launch_unified_hub() # Launch Unified Interface # Font System title_font = get_actsname_fonts() # Get Title Font body_font = get_chartagline_fonts() # Get Body Font # Specialized Font Functions cinzel_font = get_cinzel_font() # Elegant Serif Font calsans_font = get_calsans_font() # Modern Display Font readex_font = get_readexpro_font() # Clean Reading Font interface_font = get_interface_font() # UI Elements Font dialogue_font = get_dialogue_font() # Character Dialogue Font # Font Information font_info = get_shards_hub_font_info() # Get Font Source Information available_fonts = shards_hub_list_available_fonts() # List all Available Fonts

Advanced Usage

Custom Module Detection

If you're building your own modules, you can extend the detection system:

# Check for your custom functions if hasattr(store, 'your_function_name'): # Your module is loaded pass

Statistics Integration

Hub Core can aggregate statistics from all modules:

stats = shards_hub_get_statistics() # Returns: # { # "gallery_unlocked": 15, # "music_tracks": 8, # "favorites_count": 23, # "achievements_unlocked": 12, # "total_content": 58 # }

Customization

Backgrounds and Frames

The module uses these image definitions that you can replace:

define SHARDSFrameOverlay = ("SHARDS_Hub/UI/SHARDS_FrameOverlay.png") define SHARDSHubBackground = ("SHARDS_Hub/UI/SHARDS_Hub_Background.jpg")

Button Graphics

Unified hub uses custom button backgrounds:

define SHARDS_BTN_Gallery = ("SHARDS_Hub/UI/SHARDS_BTN_Gallery.png") define SHARDS_BTN_Music = ("SHARDS_Hub/UI/SHARDS_BTN_Music.png") # etc...

Troubleshooting

"Module not found" Notifications

This usually means:

  • The module file isn't in the game/ folder
  • There's a syntax error preventing the module from loading
  • Required functions aren't defined

Check the Ren'Py console for error messages.

Font Issues

The enhanced font system is super robust, but if you need to troubleshoot:

Quick Font Check
# Debug your font setup font_info = get_shards_hub_font_info() print("Current font:", font_info["font_path"]) print("Font source:", font_info["source"]) print("Available locations:", font_info["available_locations"]) # See all available fonts available_fonts = shards_hub_list_available_fonts() for font in available_fonts: print(f"Found: {font['file']} in {font['location']}")
Font Folder Priority
  1. game/Fonts/ - Your main fonts (recommended!)
  2. game/fonts/ - Original location (still works!)
  3. game/SHARDS_Hub/Fonts/ - Module-specific fonts
  4. game/font/ or game/Font/ - Alternative locations
Tips
  • Put your main fonts in the new /Fonts/ folder for best results
  • Priority fonts (Inter, Roboto, etc.) are automatically detected first
  • The system supports TTF, OTF, WOFF, and WOFF2 formats
  • If no fonts are found, Ren'Py defaults will be used gracefully

Integration Guide

Main Menu Integration

The easiest way to integrate SHARDS Hub into your main menu:

screen main_menu(): tag menu # Your existing menu code... add gui.main_menu_background # SHARDS Hub integration $ modules = shards_hub_get_enabled_modules() $ is_bundle = shards_hub_is_full_bundle() vbox: xalign 0.5 yalign 0.7 spacing 20 # Unified interface (shows all modules) textbutton "SHARDS HUB": xsize 300 ysize 60 text_size 24 text_xalign 0.5 text_color "#4ECDC4" text_hover_color "#FFFFFF" background "#ffffff15" hover_background "#ffffff25" action Function(shards_launch_unified_hub) # Individual module buttons (optional) if "gallery" in modules: textbutton "Gallery" action Function(shards_launch_gallery) if "music" in modules: textbutton "Music Player" action Function(shards_launch_music) if "favorites" in modules: textbutton "Favorites" action Function(shards_launch_favorites) if "achievements" in modules: textbutton "Achievements" action Function(shards_launch_achievements) # Conditional Features Demo Button (only shows if modules are installed) python: modules = shards_hub_detect_modules() achievements_enabled = "achievements" in modules and modules.get("achievements", {}).get("enabled", False) gallery_enabled = "gallery" in modules and modules.get("gallery", {}).get("enabled", False) if achievements_enabled or gallery_enabled: textbutton "DEMO": text_size 20 xalign 0.5 yalign 0.5 action Start("shards_hub_features_showcase")

Scene Integration

Integrate with your story flow for automatic gallery unlocks:

label romantic_scene: scene beach_sunset "A beautiful sunset scene plays out..." # Unlock in gallery when scene completes $ shards_gallery_unlock_scene("chapter1", "romantic_scene") # Track achievement progress $ shards_achievements_increment_progress("scenes_viewed", 1) return label after_load: # Keep gallery updated after loading saves $ shards_gallery_update_unlocked_status() return

Dynamic Menu Generation

For advanced menu integration with dynamic generation:

init python: def get_shards_menu_items(): modules = shards_hub_get_enabled_modules() items = [] if "gallery" in modules: items.append(("Gallery", Show("shards_gallery_main"))) if "music" in modules: items.append(("Music", Show("harmony_hub_music_player"))) if "favorites" in modules: items.append(("Favorites", Show("shards_favorites_manager_main"))) if "achievements" in modules: items.append(("Achievements", Show("shards_achievements_main"))) return items

Achievements Core

Features

  • Steam Workshop Integration with local fallback
  • Progress Tracking for milestone achievements
  • Custom Achievement Icons
  • Hidden Achievements for secrets and spoilers
  • Category Filtering to organize large achievement lists
  • Overlay Notifications with custom backgrounds
  • Statistics Dashboard showing completion rates
  • Developer-Friendly with clear integration points

Installation

  1. Copy the contents of SHARDS_Achievements_Module.zip into your game/ folder
  2. Configure your achievements in the data structure
  3. Integrate with main menu

Quick Start

Basic Achievement Setup

There are three types of achievements you can create:

shards_achievements_data = { # Simple Achievement - Just unlock when condition is met "first_choice": { "title": "Decision Maker", "description": "Made your first choice in the story", "category": "Story Progress", "hidden": False, "progress_type": "simple", "icon_unlocked": None, # Uses default trophy emoji "icon_locked": None # Uses default lock emoji }, # Progress/Counter Achievement - Track incremental progress "bad_endings": { "title": "Completionist", "description": "Discovered all bad endings", "category": "Exploration", "hidden": False, "progress_type": "counter", "progress_max": 5, "progress_current": 0, "icon_unlocked": "images/achievements/completionist.png", "icon_locked": "images/achievements/completionist_locked.png" }, # Hidden Achievement - Keeps spoilers secret until unlocked "secret_ending": { "title": "Truth Seeker", "description": "Discovered the true ending", "category": "Hidden", "hidden": True, "progress_type": "simple", "icon_unlocked": None, "icon_locked": None } }

Unlocking Achievements

# Simple unlock $ shards_achievements_unlock("first_choice") # Progress tracking $ shards_achievements_increment_progress("bad_endings") # Silent unlock (no notification) $ shards_achievements_unlock("secret_achievement", show_notification=False)

Main Menu Integration

textbutton "Achievements" action Function(shards_launch_achievements)

Using Achievements in Your Game

Simple Unlock Example

label chapter_end: # Unlock achievement when chapter completes $ shards_achievements_unlock("story_complete") return

Progress Tracking Example

label dialogue_choice: # Increment progress each time player makes a choice $ shards_achievements_increment_progress("dialogue_master", 1) return

Hidden Achievement Example

label secret_route: # Unlock hidden achievement without spoiling it $ shards_achievements_unlock("true_ending") return

Custom Icons

Custom icons can significantly enhance the visual appeal of achievements, providing a more polished and professional appearance compared to default emojis.

Setting Up Icons

"achievement_id": { "icon_unlocked": "images/achievements/trophy_gold.png", "icon_locked": "images/achievements/trophy_gray.png" }
Icon Requirements
  • Size: Icons are displayed in 80x80px frames
  • Format: Any Ren'Py-supported format (PNG recommended)
  • Scaling: Uses fit "contain" so aspect ratio is preserved
  • Fallback: Set to None to use default emojis

Steam Integration

Important: Steam achievements require setup on BOTH Steam's side AND your code side. The IDs must match exactly!

Simple Setup Guide

Step 1: Plan Your Achievement IDs

Choose simple, consistent IDs that work for both Steam and your code:

# Good IDs (use these exact same IDs in both Steam and your code): "first_steps" "route_explorer" "music_collector" "completionist"
Step 2: Create Achievements in Steam

In your Steamworks Partner dashboard:

  1. Go to your app's Achievement section
  2. Create a new achievement
  3. Set the Achievement ID (e.g., "first_steps")
  4. Set Display Name (e.g., "First Steps")
  5. Set Description (e.g., "Started your journey")
  6. Upload achievement icons (unlocked/locked)
  7. Repeat for each achievement
Step 3: Use Same IDs in Your Code
shards_achievements_data = { "first_steps": { # This MUST match Steam's Achievement ID exactly "title": "First Steps", "description": "Started your journey in our world", "category": "Story Progress", "progress_type": "simple" }, "route_explorer": { # Same ID as in Steam "title": "Route Explorer", "description": "Completed 3 different character routes", "category": "Exploration", "progress_type": "counter", "progress_max": 3 } }
Critical: IDs Must Match Exactly

If your Steam Achievement ID is "first_steps", your code must use "first_steps" too. Even small differences like "first-steps" or "firststeps" will break Steam integration!

How It Works When You Unlock

# When you call this: $ shards_achievements_unlock("first_steps") # What happens automatically: # 1. Grants achievement in Steam (if Steam is running) # 2. Saves progress locally (always works, even without Steam) # 3. Shows notification overlay # 4. Updates in-game achievement screen

What Players See

  • Steam Notification: Uses the name/description from your Steamworks dashboard
  • Steam Profile: Shows in their Steam achievement list
  • In-Game Screen: Uses the title/description from your SHARDS code
  • Non-Steam Players: Only see the in-game screen (works perfectly!)

Complete Example

Steam Dashboard Setup:
  • Achievement ID: route_explorer
  • Display Name: Route Explorer
  • Description: Completed 3 character routes
  • Icon: route_explorer.jpg
Your SHARDS Code:
# Use the exact same ID from Steam "route_explorer": { "title": "Route Explorer", "description": "Completed 3 different character routes - try Emma, Michael, and Sarah!", "category": "Exploration", "progress_type": "counter", "progress_max": 3, "progress_current": 0 }
In Your Game:
label emma_route_complete: $ shards_achievements_increment_progress("route_explorer", 1) # This updates both Steam AND your in-game progress! return

Testing

Without Steam (Development)
# This works perfectly for testing: $ shards_achievements_unlock("first_steps") # Shows in-game notification and updates local progress
With Steam (Production)

When Steam is running, the same code will:

  1. Show Steam's achievement popup
  2. Add to player's Steam profile
  3. Show your in-game notification
  4. Update local progress as backup

Common Mistakes

These Will Break Steam Integration:
  • Mismatched IDs: Steam: "first_steps", Code: "first-steps" X
  • Typos: Steam: "route_explorer", Code: "route_explrer" X
  • Case differences: Steam: "FirstSteps", Code: "first_steps" X
  • Missing Steam setup: Code has achievement, Steam doesn't X

Pro Tips

  • Test locally first: Make sure your SHARDS achievements work before adding Steam
  • Use simple IDs: stick to lowercase letters and underscores
  • Keep a list: Write down your IDs to ensure consistency
  • Different descriptions OK: Steam can have short descriptions, SHARDS can have longer ones

Hidden Achievements

Hidden achievements provide true discovery mechanics while still being visible in the achievement list.

Implementation

"secret_route": { "title": "Off the Beaten Path", "description": "Found the secret character route", "hidden": True }

Player Experience

  • Before unlock: Shows as "Hidden Achievement" with description "This achievement is hidden until unlocked."
  • After unlock: Shows actual title and description like any other achievement
  • Hidden filter: Shows all hidden achievements with their placeholder text
  • Category filtering: Hidden achievements are excluded from category buttons and normal category browsing

Notifications

Default Notification

shards_achievements_unlock("achievement_id") # Shows default overlay

Custom Notification

# Legacy function - use new notification system instead shards_show_achievement_overlay("achievement_id", custom_bg="path/to/bg.png") # Recommended: Use new universal notification system $ shards_show_notification("Custom Title", "achievement", duration=3.5)

API Reference

Core Achievement Functions

# Achievement Management shards_achievements_unlock(achievement_id, show_notification=True) shards_achievements_is_unlocked(achievement_id) # Progress Tracking shards_achievements_update_progress(achievement_id, new_value) shards_achievements_get_progress(achievement_id) shards_achievements_increment_progress(achievement_id, increment=1) # Data Retrieval filtered_list = shards_achievements_get_filtered_list(filter_type="all") categories = shards_achievements_get_categories() stats = shards_achievements_get_statistics() # Demo/Testing Functions shards_achievements_check_demo_master() # Check demo completion

Statistics and Analytics

Player Stats

stats = shards_achievements_get_statistics() # Returns: # { # "total": 25, # "unlocked": 18, # "percentage": 72.0 # }

Troubleshooting

Achievement Not Unlocking

  1. Check the achievement ID spelling
  2. Verify the achievement exists in shards_achievements_data
  3. Look for Python errors in the console
  4. Test with shards_achievements_unlock("id") in console

Icons Not Showing

  1. Check file paths (relative to game folder)
  2. Verify image files exist and are accessible
  3. Test with None values to confirm emoji fallback works

Music Player

Features

  • Perfect Ren'Py Integration: Works seamlessly with your existing audio setup - no conflicts!
  • Smart Categories: Organize tracks by mood, genre, or whatever makes sense for your game
  • Smooth Navigation: Horizontal scrolling through categories feels buttery smooth
  • Player Favorites: Let your players bookmark tracks they absolutely love
  • Play Analytics: See which tracks are hitting with your audience
  • Premium Controls: Shuffle, repeat, skip - all with satisfying visual feedback
  • Interactive Progress Bar: Click anywhere to jump to that part of the song - so intuitive!
  • Live Progress Display: Real-time position and duration updates
  • Auto-Detection: Categories appear automatically from your track data - no extra work!
  • Beautiful Interface: Spotify-inspired design with clean, professional appearance
  • Volume Control: Integrated slider with percentage display for perfect audio levels
  • Auto-Advance: Seamlessly flows from one track to the next

Getting Started

  1. Extract SHARDS_Music_Module.zip into your game/ folder
  2. Set up your music collection (see configuration below)
  3. Add one line to your main menu - that's it!

Quick Setup

Basic Configuration

shards_hub_music_collection = { "track_id": { "title": "Track Title", "artist": "Artist Name", "category": "Ambient", # Auto-generates category buttons "file": "audio/music/track.mp3", "cover_art": "SHARDS_Hub/Audio/Covers/track_cover.jpg", # Optional album cover "unlocked": True, "duration": "3:45" } }

Main Menu Integration

textbutton "Music Player" action Function(shards_launch_music)

That's it! The system handles all the technical MusicRoom setup automatically, so you can focus on the fun stuff.

Building Your Soundtrack Collection

Set up your soundtrack collection with optional cover art support:

shards_hub_music_collection = { "menu_theme": { "title": "Ethereal Dawn", "artist": "Your Composer", "category": "Menu Music", "file": "audio/music/menu_theme.ogg", "cover_art": "SHARDS_Hub/Audio/Covers/menu_theme_cover.jpg", # NEW! "unlocked": True, "duration": "2:30" }, "battle_theme": { "title": "Clash of Fates", "artist": "Your Composer", "category": "Action", "file": "audio/music/battle.mp3", "cover_art": "SHARDS_Hub/Audio/Covers/battle_cover.png", # NEW! "unlocked": False, # Unlock during gameplay "duration": "4:15" }, "love_theme": { "title": "Heart's Promise", "artist": "Your Composer", "category": "Romance", "file": "audio/music/romance.ogg", "cover_art": "SHARDS_Hub/Audio/Covers/romance_cover.jpg", # NEW! "unlocked": True, "duration": "3:22" } }
New Cover Art Support!
  • Individual Cover Art: Each song can have its own unique album cover
  • Smart Fallback: Automatically uses default music icon if cover art is missing
  • File Safety: System checks if cover art exists to prevent errors
  • Supported Formats: JPG, PNG, and other image formats
  • Perfect Size: 300x300px display area for beautiful cover art

Smart Category System

Auto-Detection

Categories appear automatically based on your tracks - no manual setup required:

# These tracks automatically create "Ambient", "Dark", "Epic" categories "track1": {"category": "Ambient"}, "track2": {"category": "Dark"}, "track3": {"category": "Epic"}
Creative Category Ideas
  • By Mood: Ambient, Dark, Epic, Peaceful, Intense
  • By Scene: Menu, Battle, Romance, Sad, Victory
  • By Character: Emma's Theme, Michael's Theme, etc.
  • By Chapter: Chapter 1, Chapter 2, Finale
  • By Genre: Classical, Electronic, Orchestral, Piano
Performance Recommendation

Maximum 8-10 categories recommended for optimal performance. While the system can handle 20+ categories, each category creates an interactive button that affects viewport scrolling performance, especially when using drag scrolling. Horizontal mousewheel scrolling remains smooth regardless of category count.

Unlock System

Manual Unlocking

# During gameplay $ shards_hub_music_collection["track_id"]["unlocked"] = True

Story Integration

label after_boss_battle: # Unlock the boss battle theme $ shards_hub_music_collection["boss_theme"]["unlocked"] = True "You can now listen to 'Epic Confrontation' in the music player!" return

Progressive Unlocks

label check_music_unlocks: python: # Unlock tracks based on story progress if persistent.chapter >= 2: shards_hub_music_collection["chapter2_theme"]["unlocked"] = True if persistent.route == "emma": shards_hub_music_collection["emma_theme"]["unlocked"] = True return

Premium Player Features

Professional Playback Controls

Beautiful Material Design icons with smooth hover animations:

  • Play/Pause: Large central control with professional icons and instant feedback
  • Previous/Next Track: Navigate through current playlist with smooth transitions
  • Shuffle Mode: Randomize playlist order (icon changes to red when active)
  • Repeat Modes: Off → Track → Playlist → Off cycling
  • Volume Control: Integrated slider with real-time percentage display
  • Auto-Advance: Automatically plays next track when current ends
Enhanced Visual Design
  • Material Design Icons: Professional Google Material icons replace emoji
  • Smooth Hover Effects: Buttons glow and respond to interaction
  • Visual State Feedback: Active modes clearly show with color changes
  • Consistent Styling: All controls follow the same design language

Visual Experience

  • Dynamic Cover Art: Each song displays its own unique album cover
  • Interactive Progress Bar: Click anywhere to jump to that position
  • Real-time Progress: Shows current position and total duration
  • Track Highlighting: Active track has distinct background in list
  • Smart Fonts: CalSans for titles, ReadexPro for artists with automatic fallbacks

Favorites System

Players can favorite tracks they love:

# Check if favorited if shards_music_is_favorite("track_id"): # Show golden heart icon # Toggle favorite status $ shards_music_toggle_favorite("track_id")

Play Statistics

Track listening habits automatically:

# Get play count plays = shards_music_get_play_count("track_id") # Display: "Played: 15 times" in track list

Advanced Usage

Interactive Progress Bar

Players can click anywhere on the progress bar to instantly jump to that part of the song, like having a professional music app in your visual novel:

# The progress bar is automatically added to the player interface # Users can click anywhere on the bar to jump to that position # # Technical implementation uses custom AudioBar class for seamless audio seeking # # The bar shows: # - Current playback position (left side) # - Total track duration (right side) # - Visual progress indicator # - Click-to-seek functionality
Progress Bar Features
  • Click-to-Seek: Jump to any position instantly
  • Smooth Updates: Refreshes 10 times per second
  • Visual Feedback: Color changes on hover
  • Accurate Positioning: Precise seeking control

Premium Player Functions

# Premium playback with playlist support $ shards_music_premium_play_track("track_id") # Playlist navigation $ shards_music_next_track() $ shards_music_previous_track() # Player modes $ shards_music_toggle_shuffle() $ shards_music_toggle_repeat() # Volume control $ shards_music_set_volume(0.7) # 70% volume # Track position and timing position = shards_music_get_position() duration = shards_music_get_track_duration_seconds("track_id") formatted_time = shards_music_format_time(position) # Interactive progress bar (automatically included in UI) progress_bar = shards_music_progress_bar(channel="music", update_interval=0.1) # Stop current track $ shards_music_stop() # Check what's playing if music_current_track == "boss_theme": # Do something

Integration with Gameplay

# Change music and unlock simultaneously label romantic_scene: play music "audio/music/romance.ogg" $ shards_hub_music_collection["romance_theme"]["unlocked"] = True emma "This moment is perfect..." return

MusicRoom Integration

How It Works

The system automatically registers your tracks with Ren'Py's MusicRoom:

# This happens automatically when the module loads music_room = MusicRoom(fadeout=1.0) for track_id, track_data in shards_hub_music_collection.items(): file_path = track_data.get("file") if file_path: music_room.add(file_path, always_unlocked=track_data.get("unlocked", True))
Benefits
  • Seamless audio: Uses Ren'Py's audio channel system
  • Interactive seeking: Progress bar allows precise position control
  • Fade transitions: Smooth crossfades between tracks
  • Memory efficient: Streams audio instead of loading everything
  • Format support: Whatever Ren'Py supports (MP3, OGG, WAV, etc.)

Audio File Management

Supported Formats

  • OGG: Best choice for Ren'Py (smaller files, good quality)
  • MP3: Universal compatibility
  • WAV: Highest quality but large files

Duration Formatting

# Recommended format: "M:SS" "duration": "3:45" # 3 minutes 45 seconds "duration": "12:30" # 12 minutes 30 seconds "duration": "1:05" # 1 minute 5 seconds

Troubleshooting

Tracks Not Playing

This is usually something simple - try these steps:

  1. Check file paths: Make sure your audio files actually exist in the specified locations
  2. Try different formats: OGG works best with Ren'Py - consider converting if needed
  3. Check for errors: Look at the Ren'Py console for any helpful error messages
  4. Volume check: Ensure music volume isn't set to zero in preferences

Categories Not Showing

Categories are shy - they only appear when they have something to show!

  1. Unlock some tracks first: Categories only appear when they have unlocked tracks
  2. Check spelling: Make sure category names are consistent across tracks
  3. Empty categories hide: This is by design - keeps the interface clean!

Category Scrolling Tips

Got lots of categories? Here's how to navigate smoothly:

  1. Use mousewheel: Horizontal mousewheel scrolling is much smoother than dragging
  2. Some categories off-screen?: Totally normal! Just scroll to see more
  3. Feeling laggy?: Try keeping to 8-10 categories for best performance
  4. Keep names simple: Single words work best (like "SciFi" instead of "Sci-Fi")

Favorites Plus

What It Does

  • Universal Screen Capture: Works with any scene, background, or UI state
  • Intelligent Content Detection: Prioritizes actual content over backgrounds
  • Smart Tagging System: Organize favorites with custom categories
  • View Counter: Track engagement and popular content
  • Fullscreen Viewer: Immersive viewing experience with navigation
  • Cross-Module Integration: Works seamlessly with Gallery Core
  • Background Detection: Automatically filters out common background patterns

Installation

  1. Copy the contents of SHARDS_Favorites_Module.zip into your game/ folder
  2. Configure capture key bindings (optional)
  3. Integrate with main menu

Basic Usage

Main Menu Integration

textbutton "Favorites" action Function(shards_launch_favorites)

In-Game Capture

# Add to your main game screen or as a global key key "f" action Function(shards_favorites_favorite_current_screen)

Advanced Viewer Features

The favorites system includes an advanced image viewer with comprehensive viewing capabilities:

Slideshow Mode

  • Auto-Advance: Click "Slideshow" to automatically advance through images
  • Timing: 3 seconds per image with smooth transitions
  • Controls: Pause/resume functionality with visual feedback

Zoom and Pan System

  • Zoom Range: 1.0x to 3.0x magnification
  • Mouse Wheel: Scroll up to zoom in, scroll down to zoom out
  • Pan Support: Click and drag to pan when zoomed in
  • Zoom Reset: Spacebar to reset to original size
  • Visual Feedback: Shows current zoom level when active

Navigation Controls

# Keyboard Controls Left/Right Arrow Keys: Navigate between images Mouse Wheel Up: Zoom in Mouse Wheel Down: Zoom out Spacebar: Reset zoom to original ESC/Click: Close viewer # Visual Elements Position Indicator: Shows "2 of 5" current position Zoom Display: Shows "2.3x" when zoomed Navigation Buttons: On-screen arrow controls

Manual Item Management

# Add specific item (by ID) $ shards_favorites_add_item("scene_sunset") # Add with tags $ shards_favorites_add_item("scene_sunset") $ persistent.shards_favorites_tags["scene_sunset"] = ["Sunset", "Beautiful"] # Remove item $ shards_favorites_remove_item("scene_sunset") # Check if item is favorited if shards_favorites_is_favorited("scene_sunset"): # Do something # Toggle favorite status $ shards_favorites_toggle_item("scene_sunset")

Core Features

Screen Capture System

The heart of the system is intelligent screen detection:

def shards_favorites_get_current_background(): """Gets the current scene content, prioritizing actual content over backgrounds""" try: scene_images = renpy.scene_lists() if 'master' in scene_images: tags_list = scene_images['master'] # Process in reverse order to get topmost content for tag in reversed(tags_list): if hasattr(tag, 'displayable') and tag.displayable: if hasattr(tag, 'name') and tag.name: tag_name = tag.name[0] # Filter out common background patterns if "black" not in tag_name.lower(): return tag_name except Exception as e: # Fallback handling pass return None
Why This Works
  • Reverse processing: Gets the topmost displayed content
  • Background filtering: Skips common backgrounds like "black" screens
  • Universal compatibility: Works with any naming scheme
  • Graceful fallbacks: Handles edge cases and errors

Tagging System

Players can organize favorites with custom tags:

# Add tags to items $ shards_favorites_add_tag("scene_id", "romance") $ shards_favorites_add_tag("scene_id", "emma") $ shards_favorites_add_tag("scene_id", "sunset") # Filter by tags tagged_items = shards_favorites_get_by_tag("romance")

Built-in Tag Categories

The system includes common tag categories:

  • Characters: Emma, Michael, Sarah, etc.
  • Scenes: Romance, Drama, Comedy, Action
  • Locations: Beach, School, Home, City
  • Moods: Happy, Sad, Romantic, Mysterious
  • Custom: Whatever players want to add

Advanced Features

View Counter System

Track which favorites are most popular:

# Increment view count (automatic when viewing) $ shards_favorites_increment_view_count("item_id") # Get view count views = shards_favorites_get_view_count("item_id") # Get most viewed items popular = shards_favorites_get_most_viewed(limit=10)

Content Detection Intelligence

The system automatically detects different content types:

def shards_favorites_favorite_current_screen(): """Captures current screen with intelligent content detection""" current_bg = shards_favorites_get_current_background() if current_bg: # Generate unique ID timestamp = int(time.time()) item_id = f"fav_{timestamp}" # Create favorite item item_data = { "image": current_bg, "timestamp": timestamp, "tags": [], "title": current_bg # Auto-generated title } # Add to collection persistent.shards_favorites_list[item_id] = item_data # Show feedback # Use new universal notification system instead shards_show_notification(f"Added {current_bg}", "favorite") else: renpy.notify("No content to favorite right now!")

Integration Features

Gallery Core Integration

Seamless compatibility with the gallery system:

# Gallery favorites appear in Favorites Plus # Correct function names: def shards_gallery_add_favorite(act, scene_id): scene_key = f"{act}_{scene_id}" if scene_key not in persistent.shards_gallery_favorites: persistent.shards_gallery_favorites.append(scene_key) # Get favorited gallery scenes def shards_gallery_get_favorited_image_scenes(): return persistent.shards_gallery_favorited_images

Cross-Module Notifications

Uses the achievement system for consistent notifications:

# Reuses achievement overlay system shards_show_achievement_overlay( title="Favorite Added!", notification_type="favorite" # Teal accent color )

Customization

Visual Styling

# Thumbnail frames background Frame(SHARDSFavFrameSmall) # Custom frame graphic # Color scheme text_color "#ffffff" hover_color "#4ECDC4" # Teal accent background "#ffffff15" # Semi-transparent backgrounds

Layout Options

# Grid configuration thumbnails_per_row = 4 thumbnail_size = (320, 180) thumbnail_spacing = 20 # Viewer settings fullscreen_fit = "contain" # or "cover", "fill" show_navigation = True auto_hide_ui = False

Troubleshooting

Content Not Capturing

  1. No displayables: Scene might not have content to capture
  2. Background detection: Common backgrounds are filtered out (intended)
  3. Timing issues: Try capturing after scene transitions complete
  4. Error handling: Check console for Python errors

Tags Not Working

  1. Data structure: Verify tags are stored as lists
  2. Case sensitivity: Tag matching is case-sensitive
  3. Persistence: Make sure tag data is being saved
  4. UI updates: Tags might not show until screen refresh

Advanced Use Cases

Custom Capture Points

# Capture specific moments during scenes label romantic_sunset: scene bg sunset_beach show emma happy # Manually add specific item to favorites $ shards_favorites_add_item("sunset_beach") # Add tags separately $ persistent.shards_favorites_tags["sunset_beach"] = ["Emma", "Sunset", "Beautiful"] emma "This is perfect..." return

Developer Analytics

# Basic analytics using available data def get_favorites_analytics(): """Get insights into what players favorite most""" analytics = { "total_favorites": len(persistent.shards_favorites_list), "total_tags": len(persistent.shards_favorites_tags), "view_count_data": persistent.shards_favorites_view_count } # Calculate most common tags manually all_tags = [] for item_tags in persistent.shards_favorites_tags.values(): all_tags.extend(item_tags) # Count tag frequency tag_counts = {} for tag in all_tags: tag_counts[tag] = tag_counts.get(tag, 0) + 1 analytics["most_common_tags"] = sorted(tag_counts.items(), key=lambda x: x[1], reverse=True) return analytics