openttd-client/GEMINI.md

Development and Debugging Mandates

To ensure technical integrity and accurate implementation of the OpenTTD network protocol (especially JGRPP-specific modifications), the following mandates must be followed by all agents.

1. Upstream Source Code Access

The JGRPP upstream repository MUST be available in the workspace for direct source code analysis. This is critical because the OpenTTD protocol is complex, version-specific, and often requires verifying C++ logic for packet structures, KDF (Key Derivation Function) ordering, and state machine transitions.

Requirement

If the folder OpenTTD-patches is missing, you MUST clone it immediately before performing any protocol-related tasks:

git clone --depth 1 -b jgrpp https://github.com/JGRennison/OpenTTD-patches OpenTTD-patches

2. Debugging Workflow

Before implementing or modifying networking code:

1. Verify Packet IDs: Search OpenTTD-patches/src/network/core/tcp_game.h for the PacketGameType enum.
2. Verify Encryption Logic: Check OpenTTD-patches/src/network/network_crypto.cpp for any changes to AEAD or PAKE handling.
3. Verify State Transitions: Analyze OpenTTD-patches/src/network/network_server.cpp and network_client.cpp to understand the expected sequence of packets (e.g., when to send ClientMapOk or ClientAck).

3. Engineering Standards

• Binary Accuracy: Never guess packet structures. Always cross-reference with the Recv_ and Send_ calls in the C++ source.
• Protocol Documentation: If a new protocol detail is discovered, document it in docs/PROTOCOL.md.