# adskdev/godot-photon-plugin architecture

> Architecture diagram of the GitHub repository adskdev/godot-photon-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adskdev/godot-photon-plugin
- Repository: https://github.com/adskdev/godot-photon-plugin

## Overview

#### 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/`.

Main entry points: [`src/register_types.cpp`](https://github.com/adskdev/godot-photon-plugin/blob/master/src/register_types.cpp) (Type registration), [`src/PhotonView.cpp`](https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonView.cpp) (PhotonView), [`src/PhotonClient.cpp`](https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonClient.cpp) (PhotonClient), [`CMakeLists.txt`](https://github.com/adskdev/godot-photon-plugin/blob/master/CMakeLists.txt) (CMake build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & Packaging"]
  node_cmake{{"CMake build<br/>build entry point<br/>[CMakeLists.txt]"}}
  node_manifest["Extension manifest"]
  node_native_library["Native extension library<br/>compiled GDExtension"]
end

subgraph group_extension["Godot Extension"]
  node_registration["Type registration<br/>GDExtension initialization<br/>[register_types.cpp]"]
  node_photon_client["PhotonClient<br/>Godot-facing session client<br/>[PhotonClient.cpp]"]
  node_game_scripts["Game scripts &amp; scenes<br/>Godot project consumers"]
end

subgraph group_replication["Network Replication"]
  node_photon_view["PhotonView<br/>network object base<br/>[PhotonView.cpp]"]
  node_transform_view["PhotonTransformView<br/>transform replication"]
  node_rigidbody_view["PhotonRigidbodyView<br/>physics replication"]
  node_animator_view["PhotonAnimatorView<br/>animation replication"]
end

subgraph group_external["External Runtime"]
  node_godot_bindings["Godot C++ bindings<br/>external dependency"]
  node_photon_sdk["Photon Realtime SDK<br/>external dependency"]
  node_godot_engine["Godot engine<br/>host runtime"]
  node_photon_cloud["Photon cloud<br/>external multiplayer service"]
end

subgraph group_docs["Documentation"]
  node_api_docs["API documentation<br/>Read the Docs source<br/>[index.rst]"]
end

node_cmake -->|"links"| node_godot_bindings
node_cmake -->|"links"| node_photon_sdk
node_cmake -->|"builds"| node_native_library
node_manifest -->|"loads"| node_native_library
node_godot_engine -->|"reads"| node_manifest
node_godot_engine -->|"initializes"| node_registration
node_registration -->|"registers"| node_photon_client
node_registration -->|"registers"| node_photon_view
node_registration -->|"registers"| node_transform_view
node_registration -->|"registers"| node_rigidbody_view
node_registration -->|"registers"| node_animator_view
node_game_scripts -->|"drives sessions"| node_photon_client
node_photon_client -->|"uses LoadBalancing"| node_photon_sdk
node_photon_sdk -->|"connects to"| node_photon_cloud
node_photon_client -->|"routes events and RPCs"| node_photon_view
node_photon_view -->|"base class"| node_transform_view
node_photon_view -->|"base class"| node_rigidbody_view
node_photon_view -->|"base class"| node_animator_view
node_transform_view -->|"serializes state"| node_photon_sdk
node_rigidbody_view -->|"serializes state"| node_photon_sdk
node_animator_view -->|"serializes state"| node_photon_sdk

click node_cmake "https://github.com/adskdev/godot-photon-plugin/blob/master/CMakeLists.txt"
click node_manifest "https://github.com/adskdev/godot-photon-plugin/blob/master/addons/photon/photon_ext.gdextension"
click node_registration "https://github.com/adskdev/godot-photon-plugin/blob/master/src/register_types.cpp"
click node_photon_client "https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonClient.cpp"
click node_photon_view "https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonView.cpp"
click node_transform_view "https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonTransformView.cpp"
click node_rigidbody_view "https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonRigidbodyView.cpp"
click node_animator_view "https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonAnimatorView.cpp"
click node_api_docs "https://github.com/adskdev/godot-photon-plugin/blob/master/docs/source/index.rst"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmake,node_manifest,node_native_library toneBlue
class node_registration,node_photon_client,node_game_scripts toneAmber
class node_photon_view,node_transform_view,node_rigidbody_view,node_animator_view toneMint
class node_godot_bindings,node_photon_sdk,node_godot_engine,node_photon_cloud toneRose
class node_api_docs toneIndigo
```

## Components

### Build & Packaging

- [CMake build](https://github.com/adskdev/godot-photon-plugin/blob/master/CMakeLists.txt): build entry point · Builds the native extension for Windows and Linux. · `CMakeLists.txt`
- [Extension manifest](https://github.com/adskdev/godot-photon-plugin/blob/master/addons/photon/photon_ext.gdextension): GDExtension manifest · Selects the platform-specific native library. · `addons/photon/photon_ext.gdextension`
- **Native extension library**: compiled GDExtension

### Godot Extension

- [Type registration](https://github.com/adskdev/godot-photon-plugin/blob/master/src/register_types.cpp): GDExtension initialization · Registers exposed C++ classes with Godot ClassDB. · `src/register_types.cpp`
- [PhotonClient](https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonClient.cpp): Godot-facing session client · Controls connection, matchmaking, rooms, properties, scenes, and Photon callbacks. · `src/PhotonClient.cpp`
- **Game scripts & scenes**: Godot project consumers

### Network Replication

- [PhotonView](https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonView.cpp): network object base · Manages Photon identity, ownership, instantiation, destruction, and RPC dispatch. · `src/PhotonView.cpp`
- [PhotonTransformView](https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonTransformView.cpp): transform replication · Synchronizes transforms with smoothing and dead reckoning. · `src/PhotonTransformView.cpp`
- [PhotonRigidbodyView](https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonRigidbodyView.cpp): physics replication · Synchronizes body state and motion prediction. · `src/PhotonRigidbodyView.cpp`
- [PhotonAnimatorView](https://github.com/adskdev/godot-photon-plugin/blob/master/src/PhotonAnimatorView.cpp): animation replication · Synchronizes animation-related state. · `src/PhotonAnimatorView.cpp`

### External Runtime

- **Godot C++ bindings**: external dependency
- **Photon Realtime SDK**: external dependency · Common, Photon, and LoadBalancing libraries.
- **Godot engine**: host runtime · Loads and invokes the extension in process.
- **Photon cloud**: external multiplayer service · Master Server, lobby, and room infrastructure.

### Documentation

- [API documentation](https://github.com/adskdev/godot-photon-plugin/blob/master/docs/source/index.rst): Read the Docs source · `docs/source/index.rst`

## Connections

- CMake build → Godot C++ bindings: links
- CMake build → Photon Realtime SDK: links
- CMake build → Native extension library: builds
- Extension manifest → Native extension library: loads
- Godot engine → Extension manifest: reads
- Godot engine → Type registration: initializes
- Type registration → PhotonClient: registers
- Type registration → PhotonView: registers
- Type registration → PhotonTransformView: registers
- Type registration → PhotonRigidbodyView: registers
- Type registration → PhotonAnimatorView: registers
- Game scripts & scenes → PhotonClient: drives sessions
- PhotonClient → Photon Realtime SDK: uses LoadBalancing
- Photon Realtime SDK → Photon cloud: connects to
- PhotonClient → PhotonView: routes events and RPCs
- PhotonView → PhotonTransformView: base class
- PhotonView → PhotonRigidbodyView: base class
- PhotonView → PhotonAnimatorView: base class
- PhotonTransformView → Photon Realtime SDK: serializes state
- PhotonRigidbodyView → Photon Realtime SDK: serializes state
- PhotonAnimatorView → Photon Realtime SDK: serializes state