> ## Documentation Index
> Fetch the complete documentation index at: https://summer-18f03259-codex-native-multiplayer-entry.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SummerPlayer Contract

> Scaffolded player interface for peer identity, synced state, and server-read input, plus an optional SummerCharacter3D template.

## What Is `SummerPlayer`?

`SummerPlayer` is the scaffolded platform contract for a future connected-player record.
The production gameplay runtime and transport are not live, so the signatures below are
authoring targets rather than deployed connection behavior. See
[platform capability status](/knowledge-base/source-status#platform-capability-status).

It is intentionally game-agnostic:

* no required 3D movement model,
* no required health model,
* no required scene structure.

The contract is intended to support card games, RTS, 2D games, and 3D action games without
forcing one movement model.

## Core Contract (Signatures)

```gdscript theme={null}
# identity
peer_id: int
player_id: String
display_name: String
avatar: Dictionary

# custom synced vars (server writes, clients read)
set_synced(key: String, value: Variant) -> void
get_synced(key: String) -> Variant
```

## Identity

The future runtime contract assigns identity fields during connection:

```gdscript theme={null}
var peer = player.peer_id
var id = player.player_id
var name = player.display_name
var avatar = player.avatar
```

* `peer_id: int`
* `player_id: String`
* `display_name: String`
* `avatar: Dictionary`

## Custom Synced Variables

`set_synced` and `get_synced` are the core data sync mechanism.

Use them for any gameplay data your clients need:

* card hand summaries,
* turn state,
* unit stats,
* score,
* custom RPG state.

```gdscript theme={null}
player.set_synced("score", 10)          # server path
player.set_synced("hand_count", 5)      # server path
player.set_synced("turn_active", true)  # server path

var score = player.get_synced("score")  # client or server
```

* `set_synced(key: String, value: Variant) -> void`
* `get_synced(key: String) -> Variant`

<Warning>
  Keep authoritative game logic on server paths (`Summer.is_server()`). Clients should render synced state, not decide outcomes.
</Warning>

## Input (Read On Server)

The future runtime contract gives a connected player an input proxy for server-side reads:

```gdscript theme={null}
var move = player.input.movement
var look = player.input.look_direction
if player.input.is_action_just_pressed("interact"):
    handle_interact(player)
```

* `player.input.movement -> Vector2`
* `player.input.look_direction -> Vector2`
* `player.input.is_action_pressed(action: String) -> bool`
* `player.input.is_action_just_pressed(action: String) -> bool`

## `SummerCharacter3D` (Optional 3D Template)

For 3D action games, use `SummerCharacter3D` in your `player.tscn`.

The template contract includes:

* `CharacterBody3D` movement-compatible node type,
* health fields (`health`, `max_health`, `is_alive`),
* helpers (`respawn`, `damage`, `heal`, `kill`, `teleport`),
* same synced API (`set_synced` / `get_synced`).

Example:

```gdscript theme={null}
func _player_joined(player) -> void:
    if player.has_method("respawn"):
        player.respawn(get_random_spawn_point())
```

## Practical Rule

If your game needs built-in 3D character behavior, use `SummerCharacter3D`.

If your game is not a 3D character game, extend `SummerPlayer` directly and sync your own state model.