사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-multiplayer시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Godot Multiplayer (4.x high-level)
Connect peers, call functions remotely with @rpc, assign authority, and replicate state with MultiplayerSpawner/MultiplayerSynchronizer. Targets Godot 4.7 with ENet (see Version notes). Treat all client input as untrusted; keep the server authoritative.
When to use
- Hosting/joining over ENet, writing RPCs, assigning per-node authority, or
auto-spawning/syncing nodes across peers.
When not to use:* local split-screen (no networking); raw TCP/UDP/WebSocket protocol work (PacketPeer); HTTP requests; Roblox → roblox-networking; persistence → save-systems.
Core workflow
- Create a peer (
ENetMultiplayerPeer), callcreate_server(port, max_clients)or
create_client(address, port), check the returned Error, and assign it to multiplayer.multiplayer_peer. The server's id is always 1; clients get random positive ids.
- Handle connection signals on
multiplayer:peer_connected(id),
peer_disconnected(id), connected_to_server, connection_failed, server_disconnected. Print each one; the smoke test (step 8) reads those lines.
- Define RPCs with
@rpc(...)and call them on the method'sCallablewithrpc()
(all peers) or rpc_id(peer_id) (one peer). Inside, multiplayer.get_remote_sender_id() says who sent it.
- Keep the RPC set identical on every build that runs the script: Godot checksums all
@rpc methods of a script, and a mismatch prints errors that can name an unrelated RPC.
- Assign authority per node with
set_multiplayer_authority(id); gate input and
movement on is_multiplayer_authority().
- Replicate state with
MultiplayerSpawner(instances scenes on clients) and
MultiplayerSynchronizer (syncs chosen properties). Both can be configured in code (Pattern 4), so no Replication-dock clicks are needed.
- Validate on the server. Clients send intent; the server checks it and broadcasts
results.
- Check with two headless instances before you finish. Make the game host or join
from command-line user args (Pattern 5), then:
timeout 20 godot --headless --path . -- --host > server.log 2>&1 &
sleep 2
timeout 15 godot --headless --path . -- --join 127.0.0.1 > client.log 2>&1
wait
grep -nE "^ *(SCRIPT ERROR|ERROR):" server.log client.log # no output = pass
grep -n "connected" server.log client.log # your step-2 printsPass means both logs show the handshake prints and no error lines (RPC "not allowed", checksum and "Node not found" errors all print as ERROR:). With no Godot binary (godot, godot4 or $GODOT_BIN), ask the user to run these lines and paste both logs. Gameplay feel still needs a human: ask the user to start two or more windows (editor menu Debug > Customize Run Instances...) and report what desyncs.
Patterns
1. Host or join (ENet)
const PORT := 7000
const MAX_PLAYERS := 8
func host() -> void:
var peer := ENetMultiplayerPeer.new()
var err := peer.create_server(PORT, MAX_PLAYERS)
if err != OK:
push_error("Cannot host: %s" % error_string(err)); return
multiplayer.multiplayer_peer = peer
multiplayer.peer_connected.connect(func(id: int): print("peer_connected ", id))
func join(address := "127.0.0.1") -> void:
var peer := ENetMultiplayerPeer.new()
var err := peer.create_client(address, PORT)
if err != OK:
push_error("Cannot join: %s" % error_string(err)); return
multiplayer.multiplayer_peer = peer
multiplayer.connected_to_server.connect(func(): print("connected_to_server"))
func leave() -> void:
multiplayer.multiplayer_peer = OfflineMultiplayerPeer.new()2. RPCs: client sends input to the server (anypeer, calllocal)
This script sits on a player avatar whose authority is the owning client (Pattern 3), so the server is not the node's authority. A server→clients RPC on such a node must be "any_peer" and check that the sender is the server.
func _unhandled_input(event: InputEvent) -> void:
if event.is_action_pressed("fire") and is_multiplayer_authority():
request_fire.rpc_id(1) # send only to the server (id 1)
# Clients may call this; it runs on the server (and locally if server is a player).
@rpc("any_peer", "call_local", "reliable")
func request_fire() -> void:
if not multiplayer.is_server(): # ignore copies relayed to other clients
return
var sender := multiplayer.get_remote_sender_id()
if not _can_fire(sender): # server-side validation
return
spawn_projectile.rpc(sender) # tell everyone to spawn it
# "authority" here would make clients reject the server's call (the client is the
# authority), so accept any peer and keep only calls that come from the server.
@rpc("any_peer", "call_local", "reliable")
func spawn_projectile(owner_id: int) -> void:
if multiplayer.get_remote_sender_id() != 1:
return
_do_spawn(owner_id)3. Per-node authority (each player controls their own avatar)
extends CharacterBody2D
func _ready() -> void:
# The node name is the owning peer's id; that peer is the authority.
set_multiplayer_authority(name.to_int())
func _physics_process(delta: float) -> void:
if not is_multiplayer_authority():
return # only the owner reads input & moves
velocity = Input.get_vector("left", "right", "up", "down") * 200.0
move_and_slide()4. MultiplayerSynchronizer configured from code
@onready var sync: MultiplayerSynchronizer = $MultiplayerSynchronizer
func _ready() -> void:
# Paths are relative to sync.root_path (default "..", the synchronizer's parent).
var config := SceneReplicationConfig.new()
config.add_property(^".:position")
config.property_set_replication_mode(^".:position",
SceneReplicationConfig.REPLICATION_MODE_ALWAYS) # unreliable, every interval
config.add_property(^".:health")
config.property_set_replication_mode(^".:health",
SceneReplicationConfig.REPLICATION_MODE_ON_CHANGE) # reliable, only when changed
sync.replication_config = configPer-peer visibility (public_visibility, set_visibility_for) is in the reference.
5. Host or join from the command line (for the smoke test)
func _ready() -> void:
var args := OS.get_cmdline_user_args() # only the arguments after `--`
if "--host" in args:
host()
elif "--join" in args:
var i := args.find("--join")
join(args[i + 1] if i + 1 < args.size() else "127.0.0.1")Gotchas
- RPC checksum. Every
@rpcmethod in a script must exist with the same annotation on
client and server builds, even unused ones. Argument names and counts are not part of the check; the set of RPCs and their annotations are.
- Default `@rpc` is `"authority"`. Calls from other peers are dropped unless the mode
is "any_peer". Add "call_local" when the host is also a player.
- `RPC 'x' is not allowed on node ... from: 1. Mode is "authority"` → the server called
an "authority" RPC on a node a client owns. "Authority" means the node's authority, not the server. Use "any_peer" plus a get_remote_sender_id() == 1 check, or move server-driven RPCs to a server-owned node (e.g. a game manager).
- NodePaths must match across peers. RPC routing uses the node path; spawn with
identical names everywhere (MultiplayerSpawner, or add_child(node, true) after setting name).
- Trusting the client. Never let clients set authoritative state (health, position,
hits) directly. Send intent, validate on the server, then broadcast.
- RPCs live on Nodes and carry plain data.
@rpcworks only onNode-derived
classes, not Resource/RefCounted, and Objects and Callables do not serialize. Send ints, strings, arrays, dictionaries and packed arrays.
- Disconnect by resetting the peer: `multiplayer.multiplayer_peer =
OfflineMultiplayerPeer.new()`.
- Port already in use in the smoke test → a previous server is still running; the
timeout wrapper ends it, or pick another port.
- Android exports need the INTERNET permission in the export preset, or all
networking is blocked.
References
- Read
references/replication-and-rpc.mdwhen you need the full@rpcargument rules,
MultiplayerSpawner with a custom spawn_function, synchronizer visibility filters, SceneMultiplayer authentication, transfer-mode choices, or a lobby skeleton.
Related skills
godot-nodes-scenesfor instancing the scenes that get spawned and synced.godot-signals-groupsfor connection signals and event flow.godot-exportfor a headless dedicated-server build.godot-gdscript-headless-testingto keep server-logic tests in CI.
Version notes
Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).
SceneReplicationConfig.property_set_sync/property_set_watchare deprecated; use
property_set_replication_mode().
MultiplayerSynchronizer.public_visibilitydefaults totrue;MultiplayerSpawner.spawn()
errors without a spawn_function.
Sources: SceneReplicationConfig @ 4.7.2-stable, ENetMultiplayerPeer @ 4.7.2-stable, OS.get_cmdline_user_args @ 4.7.2-stable, High-level multiplayer.