Reborn Protocol Reference Documentation

Welcome to the comprehensive reference documentation for the Reborn protocol. This documentation provides detailed packet structure specifications, encoding formats, and implementation guidelines for developers working with Reborn servers and clients.

Note

New to the protocol? Start with Protocol Overview to understand why everything adds 32, why there are three string types, and other architectural decisions from the late 1990s.

Protocol Specification:

• Protocol Overview
  • Before You Begin: The Philosophy
  • Protocol Architecture
  • Encryption Generations
  • Data Encoding
  • Coordinate System
  • Quick Start: Minimal Client
  • Documentation Structure
  • Common Pitfalls
  • Acknowledgments
• Data Types Reference
  • The +32 Obsession: Why Everything Adds 32
  • Primitive Types (The Normal Ones)
  • G-Types: The Reborn-Encoded Types
  • Coordinates: A Field Guide
  • Player Property Data Types
  • Time Types
  • Implementation Guidelines
• String Types: A Tragedy in Three Acts
  • The Three Types at a Glance
  • Type 1: Regular String (Read Until You Can’t)
  • Type 2: GSTRING (The Polite One)
  • Type 3: Newline-Terminated (The Impostor)
  • The PLO_LEVELLINK Trap 🪤
  • The Naming Confusion
  • Quick Reference by Packet
  • Character Encoding
  • Common Pitfalls Summary
• Encryption and Packet Processing
  • The Packet Lifecycle
  • Encryption Generations
  • ENCRYPT_GEN_5: The Details
  • The Magic Constants
  • Implementation Examples
  • Security Considerations
  • Common Implementation Errors
  • Full Bundle Processing Example
• Reborn Protocol v2 - Packet Structure Reference
  • Overview
  • Protocol Architecture
  • Data Encoding Types
  • Client-to-Server Packets (PLI_*)
  • Player Properties (PLI_PLAYERPROPS Data)
  • Remote Control Packets (PLI_RC_*)
  • NPC Control Packets (PLI_NC_*)
  • Special Packets
  • Encryption Details (ENCRYPT_GEN_5)
  • Data Type Reference
  • Implementation Notes
  • Server-to-Client Packets (PLO_*)
  • Encryption Implementation Details
• GServer Behavior Reference
  • String Encoding
  • Critical Packet Implementations
  • Common Patterns
  • Coordinate Systems
  • Property Encoding
  • Error Handling
  • Important Notes
  • Quick Reference Table
• Level Link Implementation Guide
  • Overview
  • Packet Structure
  • Special Coordinate Values
  • GMAP Implementation
  • Complete Implementation Example
  • Sending Warp Request
  • Common Implementation Pitfalls
  • Testing Recommendations
  • Visual Debugging
• Server-Side Behavior and Level Links
  • The serverside Setting
  • How It Affects Level Links
  • Client Implementation Requirements
  • GMAP Considerations
  • GServer Source Code References
  • PyReborn Implementation
  • Recommendations

Implementation:

• PyReborn Protocol Conformance Analysis
  • Overview
  • Overall Conformance: GOOD (85%)
  • ✅ Correctly Implemented Areas
  • ⚠️ Deviations from Specification
  • 🚫 Missing Features
  • 🔧 Implementation Quality Issues
  • 📊 Detailed Conformance By Area
  • 🛠 Priority Fixes Needed
  • 🎯 Recommendations
  • 📝 Summary
  • 📋 Recent Discoveries and Fixes
• Protocol Conformance Guidelines
  • Conformance Levels
  • Critical Requirements
  • Testing Requirements
  • Validation Checklist
  • Performance Guidelines
  • Security Considerations
  • Documentation Requirements
  • Certification Process
• Usage Examples
  • Basic Client Connection
  • G-Type Encoding Examples
  • Player Property Handling
  • File Transfer Example

About This Documentation

This documentation is derived from deep analysis of the GServer-v2 codebase and provides:

• Complete packet structure specifications (100+ packets documented)

• Primitive-level encoding details for cross-language implementation

• The infamous G-type encoding explained with visual diagrams

• The three string types (yes, three) and their gotchas

• ENCRYPT_GEN_5 protocol implementation with flow diagrams

• PyReborn library conformance analysis

• Implementation examples in Python, JavaScript, and C++

The documentation is maintained as part of the OpenGraal2 project and is designed to enable developers to create compatible Graal clients and servers in any programming language.

Reading Order

For newcomers to the Reborn protocol:

1. Protocol Overview - The big picture and common pitfalls

2. Data Types Reference - G-type encoding (the +32 obsession)

3. String Types: A Tragedy in Three Acts - The three string types and the PLO_LEVELLINK trap

4. Encryption and Packet Processing - Packet bundling, compression, and “encryption”

5. Reborn Protocol v2 - Packet Structure Reference - Individual packet formats

For existing developers:

• GServer Behavior Reference - How GServer-v2 actually implements things

• PyReborn Protocol Conformance Analysis - Conformance issues and fixes

Contributing

This documentation is open source and contributions are welcome. The source is available on GitHub as part of the OpenGraal2 project.

Indices and tables

• Index

• Module Index

• Search Page