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

doc: expamding documentation.

Browse Source
This commit is contained in:
Houmgaor
2025-11-09 16:47:18 +01:00
parent 42fa7a34b6
commit 68b9cf48d1
2 changed files with 541 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

241
CONTRIBUTING.md
View File

@@ -1,6 +1,241 @@
# Contributing to Erupe
Before submitting a new version:
Thank you for your interest in contributing to Erupe! This guide will help you get started.
- Document your changes in [CHANGELOG.md](CHANGELOG.md).
- Run tests: `go test -v ./...` and check for race conditions: `go test -v -race ./...`
## 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!

338
README.md
View File

@@ -1,7 +1,45 @@
# Erupe
Erupe is a community-maintained server for Monster Hunter Frontier Z.
It is written in Go, and uses no code from Capcom.
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.
## About This Fork
This fork is maintained by the Mogapedia community, focusing on stability, documentation, and quality improvements to Erupe. Our goal is to provide a reliable, well-documented server platform for Monster Hunter Frontier enthusiasts.
### Branch Strategy
- **main**: Active development branch with the latest features and improvements
- **9.2.0-clean**: Stable release branch providing a clean, functional 9.2.0 baseline for those seeking stability over cutting-edge features
The 9.2.0-clean branch was created to address stability concerns after the 9.2.0 release, providing a solid foundation for future development while the main branch continues to evolve.
## 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
@@ -12,61 +50,291 @@ It is written in Go, and uses no code from Capcom.
- PlayStation Vita
- Wii U (Up to Z2)
### Versions (ClientMode)
### Versions
- 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.
- **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. Copy [config.example.json](./config.example.json) to `config.json`, and edit it. Change the "Database" field 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/ZeruLight/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:
### Building from Source
- 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.
#### First-time Setup
Note: Patch schemas are subject to change! You should only be using them if you are following along with development.
1. Clone the repository:
```bash
git clone https://github.com/ZeruLight/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/ZeruLight/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)
- [Mezeporta Square Discord](https://discord.gg/DnwcpXM488)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution guidelines.
- **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)
View [CHANGELOG.md](CHANGELOG.md) for version history and changes.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## Authors