Customization Overview

Passage is designed to be highly customizable while maintaining simplicity. This page provides an overview of customization options and helps you understand which customizations are right for your network.

Philosophy: Start Simple, Scale Complexity

Passage follows a progressive enhancement philosophy:

Start with fixed adapters - Get running quickly with static configuration
Add dynamic elements - Introduce HTTP or Agones adapters as needed
Implement custom logic - Use gRPC adapters for complex requirements
Monitor and optimize - Add observability and fine-tune performance

You don’t need to use all features at once. Many successful networks run with just fixed adapters.

What Can Be Customized?

Core Settings

Network binding: Which address and port to listen on
Timeouts: Connection timeout durations
Rate limiting: Connection flood protection
PROXY protocol: Support for load balancers

→ Configuration Reference

Status Information

Control what players see in their server list:

Server name (MOTD)
Player counts
Favicon
Version compatibility

Available options:

Static configuration
Dynamic HTTP endpoint
Custom gRPC service

→ Status Adapters Guide

Server Discovery

Determine which backend servers are available:

Static server list
Dynamic from external service
Auto-discovery from Kubernetes/Agones

Available options:

Fixed configuration
gRPC service
Agones GameServer discovery

→ Target Discovery Guide

Routing Strategy

Choose how players are distributed across servers:

First available
Fill servers sequentially
Custom logic (region-based, skill-based, etc.)

Available options:

Fixed (first server)
Player Fill (consolidate players)
gRPC (custom logic)

→ Target Strategy Guide

Observability

Monitor Passage’s performance and health:

OpenTelemetry metrics and traces
Sentry error tracking
Structured logging

→ Monitoring Guide

Localization

Customize disconnect messages in multiple languages:

Default locale selection
Per-locale message customization
Parameter substitution support

→ Localization Guide

Common Customization Scenarios

Scenario 1: Small Static Network

Need: 2-3 fixed servers, simple routing

Solution:

[status]
adapter = "fixed"

[target_discovery]
adapter = "fixed"
[[target_discovery.fixed.targets]]
identifier = "lobby"
address = "10.0.0.10:25565"

[target_strategy]
adapter = "fixed"

Complexity: None - pure configuration

Scenario 2: Multiple Lobbies with Fill Strategy

Need: 5 lobby servers, consolidate players for better experience

Solution:

[status]
adapter = "fixed"

[target_discovery]
adapter = "fixed"
# ... list all 5 lobbies with player counts in metadata

[target_strategy]
adapter = "player_fill"
[target_strategy.player_fill]
field = "players"
max_players = 50

Complexity: Low - requires updating player counts in metadata

Scenario 3: Kubernetes with Auto-Scaling

Need: Cloud deployment with dynamic game servers

Solution:

[status]
adapter = "http"
[status.http]
address = "http://status-service/status"
cache_duration = 5

[target_discovery]
adapter = "agones"
[target_discovery.agones]
namespace = "minecraft"

[target_strategy]
adapter = "player_fill"
[target_strategy.player_fill]
field = "players"
max_players = 50

Complexity: Medium - requires Kubernetes and Agones setup

Scenario 4: Multi-Region Routing

Need: Route players to nearest regional server based on IP

Solution:

[status]
adapter = "grpc"

[target_discovery]
adapter = "grpc"

[target_strategy]
adapter = "grpc"
# Custom gRPC service implements geo-IP lookup

Complexity: High - requires custom gRPC services

→ Custom gRPC Adapters Guide

Customization Roadmap

Phase 1: Getting Started

Install Passage with default configuration
Configure one backend server
Test connection flow
Enable rate limiting

Phase 2: Basic Customization

Customize status (MOTD, favicon)
Add multiple backend servers
Configure player fill strategy
Set up basic monitoring

Phase 3: Dynamic Elements

Switch to HTTP status adapter (if needed)
Integrate with Kubernetes/Agones (if applicable)
Implement custom target filters
Add localization for your languages

Phase 4: Advanced Features

Implement custom gRPC adapters
Add complex routing logic
Integrate with existing infrastructure
Optimize for high-scale deployment

Best Practices

Configuration Management

✅ Do:

Use version control for config files (except secrets)
Start with minimal config and add as needed
Document your customizations
Test configuration changes in staging first

❌ Don’t:

Commit secrets to version control
Over-configure before understanding needs
Change too many things at once
Skip testing after config changes

Adapter Selection

✅ Do:

Choose the simplest adapter that meets your needs
Keep adapters fast (<50ms response time)
Monitor adapter performance
Implement fallback behavior

❌ Don’t:

Use gRPC adapters unless you need custom logic
Make slow API calls in adapter implementations
Forget to cache expensive operations
Block on I/O in adapter code

Performance Optimization

✅ Do:

Enable rate limiting in production
Use appropriate cache durations
Monitor connection latency
Scale horizontally when needed

❌ Don’t:

Run without rate limiting
Cache status for too long (>30 seconds)
Ignore performance metrics
Add unnecessary complexity

Customization Checklist

Before deploying your customized Passage:

Getting Help

Documentation Resources

Configuration Reference - All config options
Adapter Overview - Understanding adapters
Advanced Topics - Complex customizations

Community Support

GitHub Discussions - Ask questions
Discord Server - Real-time help
GitHub Issues - Report bugs

Professional Support

For enterprise deployments or custom development:

Contact the maintainers via GitHub
Consider sponsoring the project for priority support