Erupe/README.md

Erupe

Erupe is a community-maintained server emulator for Monster Hunter Frontier written in Go. It is a complete reverse-engineered solution to self-host a Monster Hunter Frontier server, using no code from Capcom.

Quick Start

Pick one of two installation methods, then continue to Quest & Scenario Files.

Option A: Pre-compiled Binary

1. Download the latest release for your platform from GitHub Releases:

   • erupe-ce for Linux
   • erupe.exe for Windows

2. Set up PostgreSQL and create a database:

   createdb -U postgres erupe
   

   The server will automatically apply all schema migrations on first startup.

3. Copy and edit the config:

   cp config.example.json config.json
   # Edit config.json with your database credentials
   

4. Download quest/scenario files and extract them to bin/

5. Run: ./erupe-ce

Option B: From Source

Requires Go 1.25+ and PostgreSQL.

1. Clone and build:

   git clone https://github.com/Mezeporta/Erupe.git
   cd Erupe
   go mod download
   go build -o erupe-ce
   

2. Set up the database (same as Option A, steps 2–3)

3. Copy and edit the config:

   cp config.example.json config.json
   

4. Download quest/scenario files and extract them to bin/

5. Run: ./erupe-ce

Quest & Scenario Files

Download: Quest and Scenario Binary Files

These files contain quest definitions and scenario data that the server sends to clients during gameplay. Extract the archive into your bin/ directory (or docker/bin/ for Docker installs). The path must match the BinPath setting in your config (default: "bin").

Without these files, quests will not load and the client will crash.

JSON Format Support

As an alternative to opaque .bin files, Erupe supports human-readable .json files for quests, scenarios, and Hunting Road config. The server always tries .bin first and falls back to .json automatically — existing binary files work unchanged.

File type	Location	Documentation
Quest	bin/quests/<name>.json	Erupe wiki
Scenario	bin/scenarios/<name>.json	docs/scenario-format.md
Hunting Road	bin/rengoku_data.json	Erupe wiki

JSON quests and scenarios use UTF-8 text (converted to Shift-JIS on the wire), making them diff-friendly and editable without binary tools.

Client Setup

1. Obtain a Monster Hunter Frontier client (version G10 or later recommended)
2. Point the client to your server by editing host.txt or using a launcher to redirect to your server's IP
3. Launch mhf.exe, select your server, and create an account

If you have an installed copy of Monster Hunter Frontier on an old hard drive, please get in contact so we can archive it!

Updating

git pull origin main
go mod tidy
go build -o erupe-ce

Database schema migrations are applied automatically when the server starts — no manual SQL steps needed.

For Docker users, see docker/README.md.

Configuration

Edit config.json before starting the server. The essential settings are:

{
  "Host": "127.0.0.1",
  "BinPath": "bin",
  "Language": "en",
  "ClientMode": "ZZ",
  "Database": {
    "Host": "localhost",
    "Port": 5432,
    "User": "postgres",
    "Password": "your_password",
    "Database": "erupe"
  }
}

Setting	Description
Host	IP advertised to clients. Use 127.0.0.1 for local play, your LAN/WAN IP for remote. Leave blank in config to auto-detect
ClientMode	Target client version (ZZ, G10, Forward4, etc.)
BinPath	Path to quest/scenario files
Language	"en" or "jp"

config.example.json is intentionally minimal — all other settings have sane defaults built into the server. For the full configuration reference (gameplay multipliers, debug options, Discord integration, in-game commands, entrance/channel definitions), see config.reference.json and the Erupe Wiki.

Save Transfers

To move a character from one Erupe instance to another, use the saveutil admin tool.

Build saveutil

go build -o saveutil ./cmd/saveutil/

Method 1: Direct admin import (recommended)

This method does not require the server to be running.

On the source server, export the character:

./saveutil export --config config.json --char-id <SOURCE_ID> --output my_character.json

On the destination server, find the target character ID (use pgAdmin or psql), then import:

./saveutil import --config config.json --char-id <DEST_ID> --file my_character.json

Method 2: Player self-service via API

This method lets players import their own save without admin DB access, but requires the admin to grant a one-time token first.

Admin step — grant a token (valid for 24 hours by default):

./saveutil grant-import --config config.json --char-id <DEST_ID> [--ttl 48h]
# → Import token for character 42: abc123...

Give the printed token to the player. They then call the import endpoint:

curl -X POST http://<server>:8080/v2/characters/<DEST_ID>/import \
  -H "Authorization: Bearer <player_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "import_token": "<admin_token>",
    "character": <paste contents of my_character.json .character field here>
  }'

The token is consumed on success and cannot be reused. To cancel a pending grant:

./saveutil revoke-import --config config.json --char-id <DEST_ID>

Troubleshooting

"savedata integrity check failed" — the character was imported directly into the DB without going through saveutil. Fix by clearing the stored hash:

UPDATE characters SET savedata_hash = NULL WHERE id = <char_id>;

The correct hash will be recomputed on the next save.

Features

• Multi-version Support: Compatible with all Monster Hunter Frontier versions from Season 6.0 to ZZ
• Multi-platform: Supports PC, PlayStation 3, PlayStation Vita, and Wii U (up to Z2)
• Complete Server Emulation: Entry/Sign server, Channel server, and Launcher server
• Gameplay Customization: Configurable multipliers for experience, currency, and materials
• Event Systems: Support for Raviente, MezFes, Diva, Festa, and Tournament events
• Discord Integration: Optional real-time Discord bot integration
• In-game Commands: Extensible command system with configurable prefixes
• Developer Tools: Comprehensive logging, packet debugging, and save data dumps

Architecture

Erupe consists of three main server components:

• Sign Server (Port 53312): Handles authentication and account management
• Entrance Server (Port 53310): Manages world/server selection
• Channel Servers (Ports 54001+): Handle game sessions, quests, and player interactions

Multiple channel servers can run simultaneously, organized by world types: Newbie, Normal, Cities, Tavern, Return, and MezFes.

Client Compatibility

Platforms

• PC
• PlayStation 3
• PlayStation Vita
• Wii U (Up to Z2)

Versions

• G10-ZZ (ClientMode): Extensively tested with great functionality
• G3-Z2 (Wii U): Tested with good functionality
• Forward.4: Basic functionality
• Season 6.0: Limited functionality (oldest supported version)

Database Schemas

Erupe uses an embedded auto-migrating schema system. Migrations in server/migrations/sql/ are applied automatically on startup — no manual SQL steps needed.

• Migrations: Numbered SQL files (0001_init.sql, 0002_*.sql, ...) tracked in a schema_version table
• Seed Data: Demo templates for shops, distributions, events, and gacha in server/migrations/seed/ — applied automatically on fresh databases

Development

Branch Strategy

• main: Active development branch with the latest features and improvements
• stable/v9.2.x: Stable release branch for those seeking stability over cutting-edge features

Running Tests

go test -v ./...           # Run all tests
go test -v -race ./...     # Check for race conditions (mandatory before merging)

Troubleshooting

Server won't start

• Verify PostgreSQL is running: systemctl status postgresql (Linux) or pg_ctl status (Windows)
• Check database credentials in config.json
• Ensure all required ports are available and not blocked by firewall

Client can't connect

• Verify server is listening: netstat -an | grep 53310
• Check firewall rules allow traffic on ports 53310, 53312, and 54001+
• Ensure client's host.txt points to correct server IP
• For remote connections, set "Host" in config.json to 0.0.0.0 or your server's IP

Database schema errors

• Schema migrations run automatically on startup — check the server logs for migration errors
• Check PostgreSQL logs for detailed error messages
• Verify database user has sufficient privileges

Quest files not loading

• Confirm BinPath in config.json points to extracted quest/scenario files
• Verify binary files match your ClientMode setting
• Check file permissions

Debug Logging

Enable detailed logging in config.json:

{
  "DebugOptions": {
    "LogInboundMessages": true,
    "LogOutboundMessages": true
  }
}

Resources

• Quest/Scenario Files: Download (catbox)
• Documentation: Erupe Wiki
• Discord Communities:
  • Mezeporta Square
  • Mogapedia (French Monster Hunter community, current Erupe maintainers)
  • PewPewDojo
• Community Tools:
  • Ferias — Material and item database
  • Damage Calculator — Online damage calculator
  • Armor Set Searcher — Armor set search application

Changelog

View CHANGELOG.md for version history and changes.

Contributing

See CONTRIBUTING.md for guidelines.

Authors

A list of authors can be found at HISTORY.md.