From fd5f3e5aae5ad2e710c1e2682ad5fc573d3ce1ab Mon Sep 17 00:00:00 2001 From: Houmgaor Date: Sun, 9 Nov 2025 16:23:55 +0100 Subject: [PATCH] doc: expanding main documentation. --- CONTRIBUTING.md | 241 +++++++++++++++++++++++++++++++++++++++- README.md | 288 +++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 498 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8f2964736..2e6ed8115 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 `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 4d84283c3..7fc58a38c 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,76 @@ # Erupe Community Edition -Erupe is a community-built server for Monster Hunter Frontier - All versions. -It is a complete reverse engineered solution to self-host a Monter Hunter Frontier server. +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. -> ![IMPORTANT] +> [!IMPORTANT] > The purpose of this branch is to have a clean transition from a functional 9.2.0 release, to a future 9.3.0 version. > Over the last 2 years after the release of 9.2.0, many commits introduced broken features. -## Setup +## Features -If you are only looking to install Erupe, please use a [pre-compiled binary](https://github.com/ZeruLight/Erupe/releases/latest). +- **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 -If you want to modify or compile Erupe yourself, please read on. +## Architecture -### Requirements +Erupe consists of three main server components: -Install is simple, you need: +- **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 -- [Go 1.25+](https://go.dev/dl/): programming language for the server logic -- [PostgreSQL](https://www.postgresql.org/download/): server database +Multiple channel servers can run simultaneously, organized by world types: -### Installation +- **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 + +- **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! + +## Requirements + +- [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 + +### Quick Start (Pre-compiled Binary) + +If you only want to run Erupe, download a [pre-compiled binary](https://github.com/ZeruLight/Erupe/releases/latest): + +- `erupe-ce` for Linux +- `erupe.exe` for Windows + +Then proceed to [Configuration](#configuration). + +### Building from Source #### First-time Setup @@ -31,7 +81,7 @@ Install is simple, you need: cd Erupe ``` -2. Create a new PostgreSQL database and install the schema: +2. Create a PostgreSQL database and install the base schema: ```bash # Download and apply the base schema @@ -39,34 +89,39 @@ Install is simple, you need: psql -U your_user -d your_database -f SCHEMA.sql ``` -3. Run each script under [patch-schema](./patch-schema) to apply schema updates: +3. Apply schema patches in order: ```bash psql -U your_user -d your_database -f patch-schema/01_patch.sql - # Repeat for each patch file in order + # Repeat for each patch file in numerical order ``` -4. Copy [config.example.json](./config.example.json) to `config.json` and edit it: +4. Copy and configure the config file: ```bash cp config.example.json config.json - # Edit config.json with your database credentials + # Edit config.json with your settings (see Configuration section) ``` -5. Install dependencies and run: +5. Install dependencies and build: ```bash go mod download - go run . + go build ``` - Or build a binary: +6. Run the server: ```bash - go build ./erupe-ce ``` + Or run directly without building: + + ```bash + go run . + ``` + #### Updating an Existing Installation 1. Pull the latest changes: @@ -81,7 +136,7 @@ Install is simple, you need: go mod tidy ``` -3. Apply any new schema patches from [patch-schema](./patch-schema) +3. Apply any new schema patches from [patch-schema](./patch-schema) that you haven't run yet 4. Rebuild and restart: @@ -90,14 +145,191 @@ Install is simple, you need: ./erupe-ce ``` -### Note +### Docker Installation -You will need to acquire and install the client files and quest binaries separately. -See the [resources](#resources) for details. +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 +{ + "DevMode": true, + "DevModeOptions": { + "AutoCreateAccount": true, // Auto-create accounts on first login + "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": 120, // Login boost duration (minutes) + "BonusQuestAllowance": 3, // Daily bonus quests + "DailyQuestAllowance": 1 // Daily quest limit + } +} +``` + +### In-game Commands + +Configure available commands and their prefixes: + +```json +{ + "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 +{ + "DevModeOptions": { + "LogInboundMessages": true, + "LogOutboundMessages": true + } +} +``` ## Resources -- [Quest and Scenario Binary Files](https://files.catbox.moe/xf0l7w.7z) -- [PewPewDojo Discord](https://discord.gg/CFnzbhQ): community for discussion. -- [Mogapedia's Discord](https://discord.gg/f77VwBX5w7): Discord community responsible for this branch. -- [Community FAQ Pastebin](https://pastebin.com/QqAwZSTC) +- **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) - Maintainers of this branch + - [PewPewDojo Discord](https://discord.gg/CFnzbhQ) - General community +- **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 contributors can be found at AUTHORS.md (if available) or in the git commit history.