Hyperfy Game Installer #2726
Open
Hyperfy Game Installer #2726
+432
−2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 22 commits
October 20, 2025 07:18
- Add TUI installer (omarchy-install-hyperfy) that: - Clones Hyperfy dev branch from GitHub - Uses Docker with Node 22.11+ (containerized, no host Node required) - Provides port selection and conflict detection - Creates compose stack with persistent volumes - Generates webapp desktop entry - Add launcher (omarchy-launch-hyperfy) for container management - Add lightning bolt SVG icon for desktop integration - Add Docker Compose template for standardized deployment - Integrate into Games menu with auto install/launch logic Hyperfy is an open-source 3D virtual world framework with real-time collaboration, physics simulation, and WebXR support. Perfect for metaverse development.
- Add TUI prompts for all Hyperfy environment variables: - World name, JWT secret, admin code, save interval - Player collision, max upload size, cleanup settings - Create proper .env file inside the Hyperfy repository - Fix port mapping (3000 instead of 5173) - Use npm start instead of npm run dev - Generate complete Hyperfy configuration with proper URLs
- Fix Docker command sequence: npm install → npm run build → npm start - Resolve dotenv-flow dependency and build process errors - Ensure proper Hyperfy application startup sequence - Container now starts successfully and serves on port 5173
- Add TUI prompts for all Hyperfy environment options:
- Basic: world name, JWT secret, admin code, save interval
- Player settings: collision, max upload size
- Asset storage: local vs S3 with URI configuration
- Database: local SQLite vs PostgreSQL with URI/schema
- System: cleanup on startup setting
- AI integration: provider selection (Anthropic, OpenAI, XAI, Google)
with model-specific options and API key (password input)
- LiveKit voice chat: WebSocket URL, API credentials
- Generate complete .env file with proper comments matching official format
- Conditional prompts based on user choices (S3, Postgres, AI, LiveKit)
- Password-protected inputs for sensitive data (API keys, secrets)
- Smart model selection based on AI provider choice
- Remove SVG icon dependency, use text ⚡ lightning bolt in menus - Simplify installer to create standard desktop entry instead of complex webapp - Use system applications-games icon for desktop integration - Create proper .desktop file with Game/Network/WebBrowser categories - Integrate with Omarchy's app launcher system via desktop entry - Simplify omarchy-launch-hyperfy to just open URL (no complex focus logic) - Remove icon file copying and asset dependencies Now Hyperfy appears as a standard webapp in the app launcher after installation!
- Update omarchy-launch-hyperfy to use omarchy-launch-webapp for proper app windows - Use omarchy-webapp-install with working icon URL (placehold.co) - Creates proper webapp window instead of browser tab - Maintains Docker container startup before launching webapp - Now opens like other Omarchy webapps with --app flag for dedicated window
- Switch from building from source to using ghcr.io/hyperfy-xyz/hyperfy:dev - Replace placeholder lightning bolt icon with official Hyperfy icon URL - Use official port 3000 mapping to container's port 3000 - Add persistent volume for world data storage - Remove unnecessary Node.js version verification - Update config directory structure for pre-built image usage - Maintain full integration with Omarchy webapp system and menu
- Change from lightning bolt ⚡ to world/globe 🌍 icon - Better represents Hyperfy as a virtual world platform - Maintains consistency with gaming menu visual style
- Use script location to find template relative to installer binary - Add fallback to git repo detection for development environments - Provide better error messages showing both attempted paths - Resolves template not found error when running from different directories
- Remove lightning bolt from webapp display name (now just 'Hyperfy') - Change ICON_GLYPH from ⚡ to 🌍 for consistency with menu - Webapp now uses official Hyperfy icon from https://hyperfy.xyz/static/logo-icon-echo.svg - Desktop entry created correctly with proper icon conversion
- Add templates/icons/hyperfy.png with the official Hyperfy logo - Update installer to use local icon file instead of downloading - Fallback hierarchy: template icon → existing icon → download from URL - Ensure consistent Hyperfy branding across all installations - Desktop entries now use the proper Hyperfy logo PNG file
- Replace grayscale 107x128 icon with full-color 153x183 version - Better quality and proper Hyperfy branding colors - Updated template and current webapp icon - Icon now displays properly in application menus with full colors
- Remove accidentally created applications/ directory with desktop/icon files - These files belong in ~/.local/share/applications/ not in the repo - Keep only the template icon in templates/icons/hyperfy.png
This reverts commit 0dd1e33.
- Restore applications/ directory and its desktop/icon files - Ensure files remain in the repo for proper application integration
- Embed Docker Compose YAML directly in installer script using heredoc - Remove dependency on external templates/compose/hyperfy.yaml file - Installer now works standalone without any external template files - Simplifies deployment and reduces file dependencies - Same functionality, more portable and reliable
- templates/compose/hyperfy.yaml is no longer needed - Docker Compose YAML is now embedded directly in the installer - Reduces file count and dependencies - Installer is now completely self-contained
- Remove templates/icons/hyperfy.png dependency - Embed high-quality full-color Hyperfy logo as base64 in installer - Installer now completely self-contained with no external file dependencies - Uses applications/icons/hyperfy.png (153x183, 8-bit colormap) as source - Maintains same functionality with zero external template files needed
- Change ICON_GLYPH from 🌍 to in the installer script - Update Hyperfy menu to reflect the new icon glyph - Ensures consistent branding across installation and menu options
- Change icon handling to use a provided PNG file instead of embedded base64 data - Implement fallback icon creation if the provided icon is not found - Enhance the webapp removal script to include Docker cleanup for Hyperfy - Ensure consistent handling of Hyperfy application data during installation and uninstallation
…ser experience - Update file permissions for installation scripts - Simplify header function and enhance user prompts for Docker image selection - Streamline configuration gathering for Hyperfy, including world and admin settings - Improve handling of Docker Compose and environment files for better clarity - Add detailed user feedback during installation and configuration processes
|
|
|
This can be seen in action here |
…ipt to reference icon from data root directory.
…removing unnecessary flags
|
Changed base to dev for pulling and testing |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds a complete installer for Hyperfy that makes it super easy to get up and running with just one command. The installer lets users choose between DEV (latest features) or MAIN (stable) versions, or use their own custom Docker image, then walks them through configuration with helpful descriptions for ports, player collision, and other settings. After installation, Hyperfy automatically launches and shows up in the app menu with a proper icon like any other webapp. When users want to remove it, they can do so through the webapp menu and it properly cleans up all Docker containers and data.