From 33d42362c0d87942b1d02100456af535744b3343 Mon Sep 17 00:00:00 2001 From: Houmgaor Date: Mon, 16 Feb 2026 12:25:13 +0100 Subject: [PATCH] doc: rewrite README, add CONTRIBUTING.md and SECURITY.md Rewrite README with comprehensive documentation covering architecture, configuration, features, troubleshooting, and development. Update all links to Mezeporta/Erupe. Add contributing guidelines and security policy (supported: main, stable/v9.2.x). --- CONTRIBUTING.md | 241 ++++++++++++++++++++++++++++++++++ README.md | 337 ++++++++++++++++++++++++++++++++++++++++++++---- SECURITY.md | 19 +++ 3 files changed, 570 insertions(+), 27 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..c67b44054 --- /dev/null +++ b/CONTRIBUTING.md @@ -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! diff --git a/README.md b/README.md index 1d39678c8..77fd08e56 100644 --- a/README.md +++ b/README.md @@ -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) -- [Mezeporta Square Discord](https://discord.gg/DnwcpXM488) +- **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). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..dd2dd37fb --- /dev/null +++ b/SECURITY.md @@ -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.