Mirror/Erupe
1
0
Fork 0
mirror of https://github.com/Mezeporta/Erupe.git synced 2026-03-21 23:22:34 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #153 from Mezeporta/doc/update-readme

Browse Source 
doc: rewrite README, add CONTRIBUTING.md and SECURITY.md
This commit is contained in:
Houmgaor
2026-02-16 12:27:19 +01:00
committed by GitHub
parent e9bd0b2ddb 33d42362c0
commit 4028de27ce
3 changed files with 570 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

241
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,241 @@
# Contributing to Erupe
Thank you for your interest in contributing to Erupe! This guide will help you get started.
## Getting Started
### Prerequisites
- [Go 1.25+](https://go.dev/dl/)
- [PostgreSQL](https://www.postgresql.org/download/)
- Git
### Setting Up Your Development Environment
1. Fork the repository on GitHub
2. Clone your fork:
```bash
git clone https://github.com/YOUR_USERNAME/Erupe.git
cd Erupe
```
3. Set up the database following the [Installation guide](README.md#installation)
4. Copy `config.example.json` to `config.json` and configure it
5. Install dependencies:
```bash
go mod download
```
6. Build and run:
```bash
go build
./erupe-ce
```
## Code Contribution Workflow
1. **Create a branch** for your changes:
```bash
git checkout -b feature/your-feature-name
```
Use descriptive branch names:
- `feature/` for new features
- `fix/` for bug fixes
- `refactor/` for code refactoring
- `docs/` for documentation changes
2. **Make your changes** and commit them with clear, descriptive messages:
```bash
git commit -m "feat: add new quest loading system"
git commit -m "fix: resolve database connection timeout"
git commit -m "docs: update configuration examples"
```
3. **Test your changes** (see [Testing Requirements](#testing-requirements))
4. **Push to your fork**:
```bash
git push origin feature/your-feature-name
```
5. **Create a Pull Request** on GitHub with:
- Clear description of what changes you made
- Why the changes are needed
- Any related issue numbers
6. **Respond to code review feedback** promptly
## Coding Standards
### Go Style
- Run `gofmt` before committing:
```bash
gofmt -w .
```
- Use `golangci-lint` for linting:
```bash
golangci-lint run ./...
```
- Follow standard Go naming conventions
- Keep functions focused and reasonably sized
- Add comments for exported functions and complex logic
- Handle errors explicitly (don't ignore them)
### Code Organization
- Place new handlers in appropriate files under `server/channelserver/`
- Keep database queries in structured locations
- Use the existing pattern for message handlers
## Testing Requirements
Before submitting a pull request:
1. **Run all tests**:
```bash
go test -v ./...
```
2. **Check for race conditions**:
```bash
go test -v -race ./...
```
3. **Ensure your code has adequate test coverage**:
```bash
go test -v -cover ./...
```
### Writing Tests
- Add tests for new features in `*_test.go` files
- Test edge cases and error conditions
- Use table-driven tests for multiple scenarios
- Mock external dependencies where appropriate
Example:
```go
func TestYourFunction(t *testing.T) {
tests := []struct {
name string
input int
want int
}{
{"basic case", 1, 2},
{"edge case", 0, 0},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := YourFunction(tt.input)
if got != tt.want {
t.Errorf("got %v, want %v", got, tt.want)
}
})
}
}
```
## Database Schema Changes
### Patch Schemas (Development)
When actively developing new features that require schema changes:
1. Create a new file in `schemas/patch-schema/` with format: `NN_description.sql`
2. Increment the number from the last patch
3. Test the migration on a clean database
4. Document what the patch does in comments
**Important**: Patch schemas are temporary and may change during development.
### Update Schemas (Production)
For release-ready schema changes:
1. Consolidate patch schemas into update schemas
2. Create a new file in appropriate schema directory
3. Update schema version tracking
4. Test migration paths from previous versions
## Documentation Requirements
### Always Update
- **[CHANGELOG.md](CHANGELOG.md)**: Document your changes under "Unreleased" section
- Use categories: Added, Changed, Fixed, Removed, Security
- Be specific about what changed and why
### When Applicable
- **[README.md](README.md)**: Update if you change:
- Installation steps
- Configuration options
- Requirements
- Usage instructions
- **Code Comments**: Add or update comments for:
- Exported functions and types
- Complex algorithms
- Non-obvious business logic
- Packet structures and handling
## Getting Help
### Questions and Discussion
- **[Mogapedia's Discord](https://discord.gg/f77VwBX5w7)**: Active development discussions
- **[Mezeporta Square Discord](https://discord.gg/DnwcpXM488)**: Community support
- **GitHub Issues**: For bug reports and feature requests
### Reporting Bugs
When filing a bug report, include:
1. **Erupe version** (git commit hash or release version)
2. **Client version** (ClientMode setting)
3. **Go version**: `go version`
4. **PostgreSQL version**: `psql --version`
5. **Steps to reproduce** the issue
6. **Expected behavior** vs actual behavior
7. **Relevant logs** (enable debug logging if needed)
8. **Configuration** (sanitize passwords!)
### Requesting Features
For feature requests:
1. Check existing issues first
2. Describe the feature and its use case
3. Explain why it would benefit the project
4. Be open to discussion about implementation
## Code of Conduct
- Be respectful and constructive
- Welcome newcomers and help them learn
- Focus on the code, not the person
- Assume good intentions
## License
By contributing to Erupe, you agree that your contributions will be licensed under the same license as the project.
---
Thank you for contributing to Erupe!

335
README.md
View File

@@ -1,52 +1,335 @@
# 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.
## 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
## 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**: For new players
- **Normal**: Standard gameplay
- **Cities**: City-focused instances
- **Tavern**: Special tavern area
- **Return**: For returning players
- **MezFes**: Festival events
## Client Compatibility
### Platforms
- PC
- PlayStation 3
- PlayStation Vita
- Wii U (Up to Z2)
### Versions (ClientMode)
- All versions after HR compression (G10-ZZ) have been tested extensively and have great functionality.
- All versions available on Wii U (G3-Z2) have been tested and should have good functionality.
- The second oldest found version is Forward.4 (FW.4), this version has basic functionality.
- The oldest found version is Season 6.0 (S6.0), however functionality is very limited.
### 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)
If you have an **installed** copy of Monster Hunter Frontier on an old hard drive, **please** get in contact so we can archive it!
## Setup
If you are only looking to install Erupe, please use [a pre-compiled binary](https://github.com/ZeruLight/Erupe/releases/latest).
If you want to modify or compile Erupe yourself, please read on.
## Requirements
- [Go](https://go.dev/dl/)
- [Go 1.25+](https://go.dev/dl/)
- [PostgreSQL](https://www.postgresql.org/download/)
- Monster Hunter Frontier client (see [Client Setup](#client-setup))
- Quest and scenario binary files (see [Resources](#resources))
## Installation
1. Bring up a fresh database by using the [backup file attached with the latest release](https://github.com/ZeruLight/Erupe/releases/latest/download/SCHEMA.sql).
2. Run each script under [patch-schema](./schemas/patch-schema) as they introduce newer schema.
3. Edit [config.json](./config.json) such that the database password matches your PostgreSQL setup.
4. Run `go build` or `go run .` to compile Erupe.
### Quick Start (Pre-compiled Binary)
## Docker
If you only want to run Erupe, download a [pre-compiled binary](https://github.com/Mezeporta/Erupe/releases/latest):
Please see [docker/README.md](./docker/README.md). This is intended for quick installs and development, not for production.
- `erupe-ce` for Linux
- `erupe.exe` for Windows
## Schemas
Then proceed to [Configuration](#configuration).
We source control the following schemas:
- Initialization Schema: This initializes the application database to a specific version (9.1.0).
- Update Schemas: These are update files that should be ran on top of the initialization schema.
- Patch Schemas: These are for development and should be run after running all initialization and update schema. These get condensed into `Update Schemas` and deleted when updated to a new release.
- Bundled Schemas: These are demo reference files to give servers standard set-ups.
### Building from Source
Note: Patch schemas are subject to change! You should only be using them if you are following along with development.
#### First-time Setup
1. Clone the repository:
```bash
git clone https://github.com/Mezeporta/Erupe.git
cd Erupe
```
2. Create a PostgreSQL database and install the base schema:
```bash
# Download and apply the base schema
wget https://github.com/Mezeporta/Erupe/releases/latest/download/SCHEMA.sql
psql -U your_user -d your_database -f SCHEMA.sql
```
3. Apply schema patches in order:
```bash
psql -U your_user -d your_database -f schemas/patch-schema/01_patch.sql
# Repeat for each patch file in numerical order
```
4. Copy and configure the config file:
```bash
cp config.example.json config.json
# Edit config.json with your settings (see Configuration section)
```
5. Install dependencies and build:
```bash
go mod download
go build
```
6. Run the server:
```bash
./erupe-ce
```
Or run directly without building:
```bash
go run .
```
#### Updating an Existing Installation
1. Pull the latest changes:
```bash
git pull origin main
```
2. Update dependencies:
```bash
go mod tidy
```
3. Apply any new schema patches from [schemas/patch-schema](./schemas/patch-schema) that you haven't run yet
4. Rebuild and restart:
```bash
go build
./erupe-ce
```
### Docker Installation
For quick setup and development (not recommended for production), see [docker/README.md](./docker/README.md).
## Configuration
Edit `config.json` to configure your server. Key settings include:
### Core Settings
```json
{
"Host": "127.0.0.1", // Server binding address
"BinPath": "bin", // Path to quest/scenario binaries
"Language": "en", // "en" or "jp"
"ClientMode": "ZZ" // Target client version
}
```
### Database
```json
{
"Database": {
"Host": "localhost",
"Port": 5432,
"User": "postgres",
"Password": "your_password",
"Database": "erupe"
}
}
```
### Server Ports
```json
{
"Sign": {
"Enabled": true,
"Port": 53312 // Authentication server
},
"Entrance": {
"Enabled": true,
"Port": 53310 // World selection server
}
}
```
Channel servers are configured under `Entrance.Entries[].Channels[]` with individual ports (default: 54001+).
### Development Options
```json
{
"DebugOptions": {
"LogInboundMessages": false, // Log incoming packets
"LogOutboundMessages": false, // Log outgoing packets
"MaxHexdumpLength": 256 // Max bytes for hexdump logs
}
}
```
### Gameplay Options
```json
{
"GameplayOptions": {
"MaximumNP": 100000, // Max Netcafe Points
"MaximumRP": 50000, // Max Road Points
"BoostTimeDuration": 7200, // Login boost duration (seconds)
"BonusQuestAllowance": 3, // Daily bonus quests
"DailyQuestAllowance": 1 // Daily quest limit
}
}
```
### In-game Commands
Configure available commands and their prefixes:
```json
{
"CommandPrefix": "!",
"Commands": [
{"Name": "Raviente", "Enabled": true, "Prefix": "ravi"},
{"Name": "Reload", "Enabled": true, "Prefix": "reload"},
{"Name": "Course", "Enabled": true, "Prefix": "course"}
]
}
```
For a complete configuration example, see [config.example.json](./config.example.json).
## Client Setup
1. Download and install a Monster Hunter Frontier client (version G10 or later recommended)
2. Download [Quest and Scenario Binary Files](https://files.catbox.moe/xf0l7w.7z)
3. Extract the binary files to the `bin` directory in your Erupe installation
4. Configure your client to point to your Erupe server IP/hostname
5. Modify the client's `host.txt` or use a launcher to redirect to your server
## Database Schemas
Erupe uses a structured schema system:
- **Initialization Schema**: Bootstraps database to version 9.1.0
- **Update Schemas**: Production-ready updates for new releases
- **Patch Schemas**: Development updates (subject to change)
- **Bundled Schemas**: Demo templates for shops, distributions, events, and gacha in [schemas/bundled-schema/](./schemas/bundled-schema/)
**Note**: Only use patch schemas if you're following active development. They get consolidated into update schemas on release.
## Development
### Running Tests
```bash
# Run all tests
go test -v ./...
# Check for race conditions
go test -v -race ./...
```
## Troubleshooting
### Common Issues
#### 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
- Ensure all patch files are applied in order
- 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`:
```json
{
"DebugOptions": {
"LogInboundMessages": true,
"LogOutboundMessages": true
}
}
```
## Resources
- [Quest and Scenario Binary Files](https://files.catbox.moe/xf0l7w.7z)
- **Binary Files**: [Quest and Scenario Binary Files](https://files.catbox.moe/xf0l7w.7z)
- **Discord Communities**:
- [Mezeporta Square Discord](https://discord.gg/DnwcpXM488)
- [Mogapedia's Discord](https://discord.gg/f77VwBX5w7)
- [PewPewDojo Discord](https://discord.gg/CFnzbhQ)
- **Documentation**: [Erupe Wiki](https://github.com/Mezeporta/Erupe/wiki)
- **FAQ**: [Community FAQ Pastebin](https://pastebin.com/QqAwZSTC)
## Changelog
View [CHANGELOG.md](CHANGELOG.md) for version history and changes.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## Authors
A list of authors can be found at [AUTHORS.md](AUTHORS.md).

19
SECURITY.md Normal file
View File

@@ -0,0 +1,19 @@
# Security Policy
## Supported Versions
| Version | Supported |
|---------|-----------|
| main | Yes |
| stable/v9.2.x | Yes |
| All other branches | No |
## Reporting a Vulnerability
If you discover a security vulnerability, please report it responsibly:
1. **Do not** open a public GitHub issue
2. Contact us privately via [Mogapedia's Discord](https://discord.gg/f77VwBX5w7) or [Mezeporta Square Discord](https://discord.gg/DnwcpXM488)
3. Include a description of the vulnerability, steps to reproduce, and any potential impact
We will acknowledge your report within 72 hours and work with you to address the issue before any public disclosure.