adskdev/godot-photon-plugin

Purpose and Runtime

This repository builds a native C++ GDExtension for Godot 4.3+ that exposes Photon Realtime/LoadBalancing multiplayer capabilities to Godot projects. The compiled extension is declared by addons/photon/photon_ext.gdextension and runs in-process within the Godot engine.

Build and Native Dependency Boundary

CMake is the build entry point: CMakeLists.txt. It links the Godot C++ bindings and the externally supplied Photon C++ Realtime SDK (Common, Photon, and LoadBalancing libraries). The repository targets Windows and Linux; SDK binaries and Godot bindings are expected as external/submodule dependencies rather than represented in this tree.

GDExtension Registration

src/register_types.cpp and src/register_types.h are the extension initialization boundary. They register the C++ classes with Godot’s ClassDB during GDExtension startup, making Photon client and network-view types available to Godot scripts/scenes. addons/photon/photon_ext.gdextension directs Godot to load the platform-specific native library.

Photon Client and Session Control

src/PhotonClient.h and src/PhotonClient.cpp provide the central Godot-facing Photon Realtime client. This component owns the integration with Photon LoadBalancing: connection to the Master Server, lobby and room lifecycle, matchmaking, player/room properties, scene loading, RPC routing, and network object ownership. It forms the primary boundary between Godot APIs and Photon callbacks/events.

Network Object Identity and RPC Layer

src/PhotonView.h and src/PhotonView.cpp define the base networked-object abstraction. Photon views associate Godot objects with Photon identities, coordinate instantiation/destruction, track ownership, and dispatch RPCs with Photon target policies such as all clients, other clients, master client, and buffered recipients.

State Replication Views

Specialized views implement replication for common Godot node state:

• src/PhotonTransformView.h / src/PhotonTransformView.cpp synchronize transforms with smoothing/dead reckoning.

• src/PhotonRigidbodyView.h / src/PhotonRigidbodyView.cpp synchronize physics-body state and motion prediction.

• src/PhotonAnimatorView.h / src/PhotonAnimatorView.cpp synchronize animation-related state.

These classes sit between local Godot scene nodes and Photon event serialization, applying received state to local objects while publishing authoritative/local changes.

Primary Control Flow

At engine startup, Godot loads the extension manifest, invokes registration, and exposes the registered classes. Game scripts configure and drive PhotonClient, which calls Photon Realtime for connection, matchmaking, and room operations. Network instantiation creates or resolves PhotonView instances; their specialized child views serialize local state outbound and consume incoming Photon events/RPCs inbound. Photon’s cloud Master Server, lobby, and room infrastructure remain external services.

Documentation Distribution

The public API documentation is generated for Read the Docs from docs/source/index.rst and docs/source/conf.py. The installable Godot-facing artifact is organized under addons/photon/, allowing consumers to copy that directory into a project’s res://addons/.