Quick Start

Setup

hypkg is designed to be run with npx inside a Hyperfy repository:

# Navigate to your Hyperfy repository
cd path/to/your/hyperfy/repository

# Run interactive installation of mods
npx hypkg apply

Basic Usage

Managing Mods

# List installed mods
npx hypkg list

# Search available mods
npx hypkg search

# Install specific mods
npx hypkg apply repository/mod-name

# Remove installed mods
npx hypkg remove repository/mod-name

# Reset to base state (remove all mods)
npx hypkg reset

Syncing Mods

npx hypkg sync

This will:

1. Check for updates to all installed mods
2. Ensure all mods are compatible with the current Hyperfy version
3. Re-apply mods in the correct order
4. Handle any conflicts between mods

Run this command periodically to ensure your mods stay up-to-date.

Caution

if you make your own commits ontop of mods, you will need to track upstream yourself and can no longer pull hypkg updates

Repository Management

# List available mod repositories
npx hypkg repo list

# Add a new mod repository
npx hypkg repo add name url

# Remove a mod repository
npx hypkg repo remove name

For Developers

Important: When developing mods, your branch should have the latest commit of the Hyperfy canonical branch as a base. When updating your development branch, always use:

git rebase dev

# Release a new version of your mod
npx hypkg release

Do NOT use git merge dev as this will not work correctly with the mod system.

Troubleshooting

If you encounter issues:

1. Make sure you’re running the command in a valid Hyperfy repository
2. Try resetting your mod state: npx hypkg reset
3. Check for updates: npx hypkg sync
4. Reach out on the hypkg channel on Hyperfy discord server