> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/ko/docs/sample-projects/godot/godotsteam-server.md).

# Edgegap의 GodotSteam 서버

Edgegap의 GodotSteam 전용 서버: 헤드리스 Linux 내보내기, Steam 로그인 및 인증 티켓, Docker, 배포 및 Steam 클라이언트.

[GodotSteam Server](https://codeberg.org/godotsteam/godotsteam-server) 는 GodotSteam의 전용 서버 버전입니다. Steam의 게임 서버 API(`SteamGameServer`)를 Godot에서 사용할 수 있도록 래핑하므로, 헤드리스 서버가 Steam에 로그인하고 자체 Steam ID를 받으며, 접속하는 모든 플레이어가 게임을 소유한 실제 Steam 사용자인지 확인할 수 있습니다.

이 가이드에서는 Godot 4 프로젝트를 처음부터 만들어 Edgegap에서 실행되는 GodotSteam Server 전용 서버로 구성하고, Steam 클라이언트가 접속해 Steam 인증 티켓 검사를 통과하도록 합니다. 플레이어는 Godot 내장 ENet(UDP)으로 접속하며, Steam은 신원, 소유권 및 부정 행위 방지 검증에 사용됩니다.

이 가이드의 전체 프로젝트는 GitHub에서 확인할 수 있습니다: [edgegap/server-sample-godotsteam-dedicated-server](https://github.com/edgegap/server-sample-godotsteam-dedicated-server). 저장소를 복제하고 `./tools/fetch-godotsteam.sh` 를 실행해 GodotSteam 애드온을 다운로드한 다음, README의 안내에 따라 몇 가지 명령어로 서버를 실행하세요.

{% hint style="success" %}
**2026-11-09 테스트 완료** Godot 4.7.2, GodotSteam Server 4.12.1(GDExtension), GodotSteam 4.24(GDExtension), Steamworks SDK 1.65에서 테스트했습니다. 서버는 Edgegap에서 익명으로 Steam에 로그인했고, Windows 클라이언트가 ENet을 통해 접속했으며, Steam에서 해당 클라이언트의 인증 티켓을 검증했습니다. 클라이언트가 나가자 배포 환경은 자동으로 종료되었습니다.
{% endhint %}

## ✔️ 준비

시작하기 전에 다음을 확인하세요. [Edgegap 무료 계정 만들기](https://app.edgegap.com/auth/register) (신용카드가 필요하지 않습니다).

**개발 컴퓨터에서 몇 가지 필수 항목을 설정하세요.**

* [Godot 4.4 이상](https://godotengine.org/download) 및 **Linux** 내보내기 템플릿(Editor / Manage Export Templates). GodotSteam Server의 GDExtension을 사용하려면 Godot 4.4 이상이 필요합니다.
* [Docker Desktop(또는 Docker CLI)](https://www.docker.com/products/docker-desktop/).
* 게임 클라이언트를 테스트하려면 Steam 클라이언트를 설치하고 로그인하세요.
* Steam 앱 ID. 이 가이드에서는 `480` (Spacewar)를 사용합니다. 모든 Steam 계정에서 사용할 수 있는 Valve 테스트 앱입니다. 게임을 출시하기 전에 본인의 앱 ID로 바꾸세요.

{% hint style="info" %}
Godot 전용 서버를 처음 사용하시나요? 먼저 [Godot - 시작하기](https://docs.edgegap.com/ko/godot.md) 를 참고해 Edgegap 플러그인을 사용한 내보내기, Docker 및 배포 방법을 익힌 다음, 돌아와 Steam을 추가하세요.
{% endhint %}

## 🧩 1. GodotSteam 설치

GodotSteam에는 두 가지 버전이 있으며, 클라이언트/서버 게임에는 둘 다 필요합니다.

| 애드온                   | 싱글턴           | 용도       | 다운로드                                                                                                                                                                                           |
| --------------------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GodotSteam Server** | `SteamServer` | 전용 서버    | [Codeberg 릴리스](https://codeberg.org/godotsteam/godotsteam-server/releases) (`godotsteam-server-<version>-gdextension-plugin-4.4.zip`) 또는 Godot 에셋 라이브러리에서 "GodotSteam Server GDExtension 4.4+" |
| **GodotSteam**        | `Steam`       | 게임 클라이언트 | [Codeberg 릴리스](https://codeberg.org/godotsteam/godotsteam/releases) (`godotsteam-<version>-gdextension-plugin-4.4.zip`) 또는 Godot 에셋 라이브러리나 에셋 스토어에서 "GodotSteam GDExtension 4.4+"              |

☑️ 두 파일의 압축을 풀어 프로젝트에 넣으면 다음 경로가 생깁니다. `addons/godotsteam_server/` 및 `addons/godotsteam/`. Steamworks API 라이브러리(`libsteam_api.so`, `steam_api64.dll` 등)는 각 애드온에 이미 포함되어 있습니다.

{% hint style="info" %}
**GDExtension과 모듈 중 무엇을 선택해야 하나요?** 이 가이드에서는 GDExtension 빌드를 사용합니다. 표준 Godot 편집기 및 표준 내보내기 템플릿과 함께 작동합니다. 모듈 빌드(`godotsteam-server` 템플릿과 편집기)는 사용자 지정 Godot 빌드입니다. 이를 사용하는 경우 GodotSteam Server 템플릿으로 서버를 내보내고 애드온 폴더는 건너뛰세요. 한 프로젝트에서 GDExtension 빌드와 모듈 빌드를 절대 함께 사용하지 마세요.
{% endhint %}

{% hint style="warning" %}
두 애드온을 한 프로젝트에 넣으면 편집기에 다음과 같은 오류가 표시됩니다. `Attempt to register extension class 'SteamProjectSettings', which appears to be already registered`. 두 애드온 모두 해당 설정 클래스를 선언합니다. 테스트에서는 서버나 클라이언트에 영향을 주지 않았으며, 이 가이드의 각 내보내기에는 두 애드온 중 하나만 포함되므로 내보낸 빌드에서는 이 오류가 발생하지 않습니다.
{% endhint %}

✅ 이제 다음 단계로 진행할 수 있습니다.

## 🔧 2. 서버 및 클라이언트 스크립트 추가

아래 스크립트는 하나의 자동 로드 스크립트로, 서버 내보내기에서는 전용 서버로 실행되고 그 외의 경우에는 클라이언트로 실행됩니다. 이 스크립트는 `Engine.get_singleton()` 을 사용하므로 두 애드온 중 하나만 포함된 내보내기에서도 구문 분석이 가능합니다.

**서버의 동작:**

1. `serverInitEx()` 는 게임 포트, 쿼리 포트, 인증 모드 및 버전 문자열을 사용해 Steam 게임 서버 API를 시작합니다.
2. 서버의 제품, 설명, 모드 디렉터리, 이름 및 플레이어 수를 설정합니다. Steam은 이러한 값을 로그인하기 **전에만** 허용합니다.
3. `logOnAnonymous()` 는 임시 Steam ID로 Steam에 로그인하거나, `logOn(token)` 은 다음과 같은 경우 게임 서버 로그인 토큰으로 로그인합니다. `STEAM_GSLT` 가 설정되어 있으면(참조: [#steam-account-and-game-server-login-token](#steam-account-and-game-server-login-token "mention")).
4. 포트에서 ENet 서버를 엽니다. `7777`. 피어가 연결되면 해당 피어에 서버의 Steam ID를 보내고 Steam 인증 티켓을 최대 15초 동안 기다립니다.
5. `beginAuthSession()` 은 티켓을 Steam에 전달합니다.  `validate_auth_ticket_response` 시그널은 플레이어의 접속 허용 여부를 알려 줍니다. 인증에 실패하거나 티켓을 보내지 않은 플레이어는 연결이 끊깁니다.
6. 모든 플레이어가 나가거나(또는 2분 내에 아무도 참가하지 않으면) Steam에서 로그아웃하고 자체 Edgegap 배포를 삭제하여, 비어 있는 서버에 대한 비용이 계속 발생하지 않도록 합니다.

**클라이언트의 동작:** App ID로 Steam을 초기화하고, ENet으로 연결한 뒤 서버의 Steam ID에 연결된 인증 세션 티켓을 Steam에 요청합니다. Steam이 티켓을 확인할 때까지 기다린 다음 서버로 전송합니다.

{% hint style="warning" %}
Steam 시그널은 `run_callbacks()`을 호출할 때만 발생합니다. 스크립트는 매 프레임 `SteamServer.run_callbacks()` (그리고 `클라이언트에서는 Steam.run_callbacks()` )를 `_process`에서 호출합니다. GodotSteam의 "embed callbacks" 프로젝트 설정은 대신 렌더링 프레임에 연결되지만, 헤드리스 서버는 렌더링하지 않습니다.
{% endhint %}

☑️ 스크립트를 다음 경로로 저장합니다: `res://net/session.gd`.

{% code title="net/session.gd" lineNumbers="true" expandable="true" %}

```gdscript
extends Node
## 연결 양쪽에서 사용하는 단일 자동 로드입니다.
## 서버(dedicated_server 내보내기 또는 `-- --server`): GAME_PORT에서 ENet을 사용하고 Steam에 로그인합니다
## GodotSteam Server를 사용하며, 모든 플레이어는 Steam 인증 티켓 검사를 통과해야 합니다.
## 클라이언트(GodotSteam): ENet으로 연결한 다음 Steam 인증 티켓을 서버로 보냅니다.
## Engine.get_singleton()을 사용하므로 두 애드온 중 하나만 포함된 내보내기에서도 스크립트를 파싱할 수 있습니다.

const STEAM_APP_ID := 480            # Spacewar, Valve의 테스트 앱입니다. 자체 App ID를 사용하세요.
const SERVER_VERSION := "1.0.0.0"    # x.x.x.x 형식입니다. Steam에는 최신 버전의 서버만 표시됩니다.
const GAME_PORT := 7777              # ENet, UDP. Edgegap 포트 "gameport".
const QUERY_PORT := 27015            # Steam 쿼리, UDP. Edgegap 포트 "queryport".
const MAX_PLAYERS := 8
const AUTH_TIMEOUT_SEC := 15.0       # 제한 시간 안에 유효한 티켓을 보내지 않는 피어를 추방합니다.
const NO_PLAYER_TIMEOUT_SEC := 120.0 # 아무도 접속하지 않으면 배포를 중지합니다.

# 확인할 SteamServer.ServerMode 및 BeginAuthSession / AuthSession 결과입니다.
const SERVER_MODE_AUTHENTICATION := 2
const BEGIN_AUTH_RESULT_OK := 0
const AUTH_SESSION_RESPONSE_OK := 0

var steam_server: Object  # SteamServer 싱글톤, 서버 전용
var steam: Object         # Steam 싱글톤, 클라이언트 전용
var server_steam_id := 0
var players := {}         # peer_id -> steam_id, 인증된 플레이어
var pending := {}         # peer_id -> {"steam_id": int, "deadline": float}
var had_players := false
var stopping := false


func _ready() -> void:
	if is_server_launch():
		_start_server()
	else:
		_start_client()


func _process(_delta: float) -> void:
	# Steam 콜백(시그널)은 이 함수를 호출해야만 실행됩니다.
	if steam_server:
		steam_server.run_callbacks()
	if steam:
		steam.run_callbacks()
	if multiplayer.is_server() and steam_server:
		_check_timeouts()


static func is_server_launch() -> bool:
	return OS.has_feature("dedicated_server") or "--server" in OS.get_cmdline_user_args()


# ---------------------------------------------------------------- 서버

func _start_server() -> void:
	steam_server = Engine.get_singleton("SteamServer")
	if steam_server == null:
		_fail("GodotSteam Server add-on not loaded")
		return

	# Edgegap은 내부 포트를 임의의 외부 포트에 연결합니다. Steam에는 여기서 전달하는 게임 포트가
	# 광고되므로 플레이어가 실제로 접속하는 외부 포트를 지정합니다.
	var advertised_port := int(_env("ARBITRIUM_PORT_GAMEPORT_EXTERNAL", str(GAME_PORT)))
	var init: Dictionary = steam_server.serverInitEx("0.0.0.0", advertised_port, QUERY_PORT,
			SERVER_MODE_AUTHENTICATION, SERVER_VERSION)
	if init.get("status", -1) != 0:
		_fail("serverInitEx failed: %s" % init)
		return
	print("STEAM init ok game_port=%d query_port=%d" % [advertised_port, QUERY_PORT])

	steam_server.server_connected.connect(_on_steam_connected)
	steam_server.server_connect_failure.connect(_on_steam_connect_failure)
	steam_server.server_disconnected.connect(_on_steam_disconnected)
	steam_server.validate_auth_ticket_response.connect(_on_validate_auth_ticket_response)

	# 로그인하기 전에 설정해야 합니다.
	steam_server.setModDir("spacewar")        # Steam에서 사용하는 게임 폴더 이름입니다.
	steam_server.setProduct(str(STEAM_APP_ID))
	steam_server.setGameDescription("GodotSteam Server on Edgegap")
	steam_server.setDedicatedServer(true)
	steam_server.setMaxPlayerCount(MAX_PLAYERS)
	steam_server.setServerName("Edgegap %s" % _env("ARBITRIUM_REQUEST_ID", "local"))
	steam_server.setMapName("arena")

	var gslt := _env("STEAM_GSLT", "")
	if gslt.is_empty():
		steam_server.logOnAnonymous()
	else:
		steam_server.logOn(gslt)  # 영구 Steam ID를 사용하려면 게임 서버 로그인 토큰이 필요합니다.
	steam_server.setAdvertiseServerActive(true)

	var peer := ENetMultiplayerPeer.new()
	var err := peer.create_server(GAME_PORT, MAX_PLAYERS)
	if err != OK:
		_fail("ENet create_server failed: %s" % error_string(err))
		return
	multiplayer.multiplayer_peer = peer
	multiplayer.peer_connected.connect(_on_peer_connected)
	multiplayer.peer_disconnected.connect(_on_peer_disconnected)
	print("SERVER listening udp=%d request_id=%s" % [GAME_PORT, _env("ARBITRIUM_REQUEST_ID", "-")])
	get_tree().create_timer(NO_PLAYER_TIMEOUT_SEC).timeout.connect(func():
		if not had_players:
			_stop_server("nobody joined"))


func _on_steam_connected() -> void:
	server_steam_id = steam_server.getSteamID()
	var ip: Dictionary = steam_server.getPublicIP()
	print("STEAM logged on steam_id=%d public_ip=%s secure=%s" % [server_steam_id,
			_ip_to_string(ip.get("ipv4", 0)), steam_server.isServerSecure()])


func _on_steam_connect_failure(result: int, retrying: bool) -> void:
	print("STEAM connect failure result=%d retrying=%s" % [result, retrying])


func _on_steam_disconnected(result: int) -> void:
	print("STEAM disconnected result=%d" % result)


func _on_peer_connected(peer_id: int) -> void:
	pending[peer_id] = {"steam_id": 0, "deadline": Time.get_ticks_msec() / 1000.0 + AUTH_TIMEOUT_SEC}
	print("PEER connected peer=%d, waiting for Steam ticket" % peer_id)
	# 클라이언트에 서버의 정보를 전달합니다. 클라이언트는 이 서버의 Steam ID에 티켓을 바인딩합니다.
	server_hello.rpc_id(peer_id, server_steam_id)


func _on_peer_disconnected(peer_id: int) -> void:
	pending.erase(peer_id)
	if players.has(peer_id):
		steam_server.endAuthSession(players[peer_id])
		players.erase(peer_id)
	print("PEER left peer=%d players=%d" % [peer_id, players.size()])
	if had_players and players.is_empty() and pending.is_empty():
		_stop_server("everyone left")


@rpc("any_peer", "reliable")
func submit_ticket(ticket: PackedByteArray, steam_id: int) -> void:
	if not multiplayer.is_server():
		return
	var peer_id := multiplayer.get_remote_sender_id()
	if not pending.has(peer_id):
		return
	var result: int = steam_server.beginAuthSession(ticket, ticket.size(), steam_id)
	print("AUTH begin peer=%d steam_id=%d result=%d" % [peer_id, steam_id, result])
	if result != BEGIN_AUTH_RESULT_OK:
		_kick(peer_id, "ticket rejected (%d)" % result)
		return
	pending[peer_id]["steam_id"] = steam_id
	# Steam이 잠시 후 validate_auth_ticket_response로 응답합니다.


func _on_validate_auth_ticket_response(steam_id: int, response: int, owner_id: int) -> void:
	for peer_id in pending.keys():
		if pending[peer_id]["steam_id"] != steam_id:
			continue
		pending.erase(peer_id)
		if response != AUTH_SESSION_RESPONSE_OK:
			steam_server.endAuthSession(steam_id)
			_kick(peer_id, "Steam auth failed (%d)" % response)
			return
		players[peer_id] = steam_id
		had_players = true
		print("AUTH ok peer=%d steam_id=%d owner=%d players=%d" % [peer_id, steam_id, owner_id, players.size()])
		welcome.rpc_id(peer_id, players.size())
		return
	# 이미 게임에 참여 중인 플레이어에 대한 응답은 Steam이 해당 세션을 종료했음을 의미합니다(차단, 다른 곳에서 로그인).
	for peer_id in players.keys():
		if players[peer_id] == steam_id and response != AUTH_SESSION_RESPONSE_OK:
			_kick(peer_id, "Steam session ended (%d)" % response)


func _check_timeouts() -> void:
	var now := Time.get_ticks_msec() / 1000.0
	for peer_id in pending.keys():
		if now > pending[peer_id]["deadline"]:
			_kick(peer_id, "no Steam ticket")


func _kick(peer_id: int, reason: String) -> void:
	print("KICK peer=%d reason=%s" % [peer_id, reason])
	pending.erase(peer_id)
	multiplayer.multiplayer_peer.disconnect_peer(peer_id)


func _stop_server(reason: String) -> void:
	if stopping:
		return
	stopping = true
	print("SERVER stopping reason=%s" % reason)
	steam_server.setAdvertiseServerActive(false)
	steam_server.logOff()
	steam_server.serverShutdown()
	var url := _env("ARBITRIUM_DELETE_URL", "")
	if url.is_empty():
		get_tree().quit()
		return
	# Edgegap: 요금 청구를 중지하도록 자체 배포를 삭제합니다.
	var http := HTTPRequest.new()
	add_child(http)
	http.request_completed.connect(func(result, code, _h, _b):
		print("SERVER self_stop result=%d http=%d" % [result, code])
		get_tree().quit())
	http.request(url, ["authorization: " + _env("ARBITRIUM_DELETE_TOKEN", "")], HTTPClient.METHOD_DELETE)


# ---------------------------------------------------------------- 클라이언트

func _start_client() -> void:
	steam = Engine.get_singleton("Steam")
	if steam == null:
		_fail("GodotSteam 애드온이 로드되지 않음")
		return
	var init: Dictionary = steam.steamInitEx(STEAM_APP_ID)
	if init.get("status", -1) != 0:
		_fail("Steam 초기화 실패. Steam이 실행 중이고 로그인되어 있나요? %s" % init)
		return
	print("CLIENT steam_id=%d name=%s" % [steam.getSteamID(), steam.getPersonaName()])

	var address := _arg("connect", "127.0.0.1:%d" % GAME_PORT)
	var host := address.get_slice(":", 0)
	var port := int(address.get_slice(":", 1))
	var peer := ENetMultiplayerPeer.new()
	var err := peer.create_client(host, port)
	if err != OK:
		_fail("ENet create_client 실패: %s" % error_string(err))
		return
	multiplayer.multiplayer_peer = peer
	multiplayer.connection_failed.connect(func(): _fail("%s에 연결할 수 없음" % address))
	multiplayer.server_disconnected.connect(func(): _status("서버 연결이 끊어졌습니다"))
	_status("%s에 연결 중..." % address)


@rpc("authority", "reliable")
func server_hello(steam_id_of_server: int) -> void:
	# 서버의 Steam ID에 연결된 티켓은 다른 서버에서 재사용할 수 없습니다.
	var ticket: Dictionary = steam.getAuthSessionTicket(steam_id_of_server)
	var bytes: PackedByteArray = ticket["buffer"].slice(0, ticket["size"])
	# Steam이 티켓을 등록하는 데 시간이 걸립니다. Steam에서 확인이 완료되면 티켓을 전송합니다.
	while true:
		var response: Array = await steam.get_auth_session_ticket_response
		if response[0] == ticket["id"]:
			if response[1] != 1:  # Steam 결과 OK
				_fail("Steam에서 티켓을 발급하지 못함(결과 %d)" % response[1])
				return
			break
	_status("연결됨. Steam 티켓(%d바이트)을 서버 %d로 전송 중" % [bytes.size(), steam_id_of_server])
	submit_ticket.rpc_id(1, bytes, steam.getSteamID())


@rpc("authority", "reliable")
func welcome(player_count: int) -> void:
	_status("Steam 인증 완료, 서버에 플레이어 %d명 접속 중" % player_count)
	if "--quit-after-auth" in OS.get_cmdline_user_args():
		await get_tree().create_timer(2.0).timeout
		get_tree().quit()


# ---------------------------------------------------------------- 헬퍼

func _status(text: String) -> void:
	print("CLIENT " + text)
	var label := get_tree().current_scene as Label
	if label:
		label.text = text


func _fail(text: String) -> void:
	push_error(text)
	print("ERROR " + text)
	if is_server_launch():
		get_tree().quit(1)
	else:
		_status(text)


static func _env(key: String, default: String) -> String:
	var value := OS.get_environment(key)
	return default if value.is_empty() else value


static func _arg(key: String, default: String) -> String:
	for a in OS.get_cmdline_user_args():
		if a.begins_with("--%s=" % key):
			return a.get_slice("=", 1)
	return default


static func _ip_to_string(ip: int) -> String:
	return "%d.%d.%d.%d" % [(ip >> 24) & 255, (ip >> 16) & 255, (ip >> 8) & 255, ip & 255]
```

{% endcode %}

☑️ 이름을 `Session`(으)로 지정해 자동 로드로 등록하고 `flush_stdout_on_print` 을 켜서 서버의 `print()` 출력이 컨테이너 로그에 즉시 표시되도록 합니다.  `project.godot`:

{% code title="project.godot" expandable="true" %}

```ini
[application]

run/flush_stdout_on_print=true

[autoload]

Session="*res://net/session.gd"
```

{% endcode %}

☑️ 준비가 되면 자리 표시자를 실제 값으로 바꿉니다: `STEAM_APP_ID`, `setModDir()`, `setGameDescription()` 및 `SERVER_VERSION`.

☑️ 편집기에서 테스트합니다. 사용자 인수로 `--server` 를 지정해 프로젝트를 실행하여 서버를 시작하고(Project Settings / Editor / Run / Main Run Args: `-- --server`), 두 번째 인스턴스를 `-- --connect=127.0.0.1:7777` 을 클라이언트 인수로 지정해 실행합니다. 서버가 티켓을 검증하면 클라이언트에 `AUTHENTICATED by Steam` 이 표시됩니다.

✅ 이제 다음 단계로 진행할 수 있습니다.

## 🐧 3. 헤드리스 Linux 서버 내보내기

Edgegap은 Linux 컨테이너를 실행하므로, Godot의 **Linux** 용 **전용 서버** 모드로 서버를 내보냅니다. 이 모드에서는 창이나 GPU 없이 헤드리스로 시작하고, 내보낸 파일에서 텍스처와 오디오를 제외합니다.

☑️ 이름이 `Edgegap Linux Server` 인 내보내기 프리셋을 추가하고(Project / Export / Add / Linux), 다음을 설정합니다:

* **내보내기 모드** (리소스 탭): 전용 서버로 내보냅니다.
* **제외할 파일/폴더 필터**: `addons/godotsteam/*`를 지정하여 서버 내보내기에 GodotSteam 서버만 포함되도록 합니다.
* **내보내기 경로**: `build/edgegap-linux-server.x86_64`.
* **PCK 포함**: 끔.

또는 다음 내용을 `export_presets.cfg` (프리셋이 이미 있다면 번호를 `[preset.0]` 다시 지정하세요):

{% code title="export\_presets.cfg" expandable="true" %}

```ini
[preset.0]

name="Edgegap Linux Server"
platform="Linux"
runnable=false
dedicated_server=true
custom_features=""
export_filter="customized"
customized_files={
"res://": "strip"
}
include_filter=""
exclude_filter="addons/godotsteam/*"
export_path="build/edgegap-linux-server.x86_64"
encryption_include_filters=""
encryption_exclude_filters=""
encrypt_pck=false
encrypt_directory=false
script_export_mode=2

[preset.0.options]

custom_template/debug=""
custom_template/release=""
debug/export_console_wrapper=0
binary_format/embed_pck=false
texture_format/s3tc_bptc=true
texture_format/etc2_astc=false
binary_format/architecture="x86_64"
```

{% endcode %}

☑️ 클라이언트 프리셋(Windows, macOS, Linux 데스크톱)의 경우 서버 애드온을 대신 제외하세요: `addons/godotsteam_server/*`.

☑️ Project / Export에서 또는 명령줄에서 서버를 내보내세요:

```bash
mkdir -p build
godot --headless --path . --export-release "Edgegap Linux Server" build/edgegap-linux-server.x86_64
```

{% hint style="info" %}
Godot은 내보내기 폴더를 만들지 않습니다. 내보내기 전에 `build/` 폴더가 있는지 확인하세요.
{% endhint %}

☑️ `build` 폴더를 확인하세요. Godot은 GDExtension과 Steamworks API 라이브러리를 바이너리 옆에 복사하며, 서버에는 다음 네 파일이 모두 필요합니다:

```
build/
├─ edgegap-linux-server.x86_64
├─ edgegap-linux-server.pck
├─ libgodotsteam_server.linux.template_release.x86_64.so
└─ libsteam_api.so
```

{% hint style="info" %}
프리셋 이름과 경로는 [Edgegap Godot 플러그인](https://github.com/edgegap/buildtool-godot-plugin)과 일치하므로 **서버 내보내기** 버튼은 이 프리셋을 재사용합니다(기존 프리셋은 변경하지 않습니다). **컨테이너화** 단계에는 다음 단계의 Dockerfile이 필요합니다. 플러그인의 기본 Dockerfile은 바이너리와 `.pck`만 복사하고, GodotSteam Server에 필요한 `.so` 파일은 복사하지 않기 때문입니다.
{% endhint %}

✅ 이제 다음 단계로 진행할 수 있습니다.

## 🐋 4. 서버 컨테이너화

Steam 게임 서버를 실행하려면 내보내기에 포함되지 않는 파일이 하나 필요합니다. **`steamclient.so`**. Steamworks API가 Steam에 연결할 때 불러오는 Steam 클라이언트 라이브러리입니다. Valve는 이 파일을 [SteamCMD](https://developer.valvesoftware.com/wiki/SteamCMD)와 함께 배포하며, Steamworks API는 이 파일을 `~/.steam/sdk64/`에서 찾습니다. 아래 Dockerfile은 첫 번째 단계에서 SteamCMD를 다운로드하고, `steamclient.so` 만 최종 이미지에 복사한 뒤 서버를 `tini`를 통해 루트가 아닌 사용자로 실행하므로 배포를 중지하면 서버도 바로 종료됩니다.

☑️ 다음 파일을 프로젝트 루트에 `Dockerfile` 로 저장합니다.

{% code title="Dockerfile" lineNumbers="true" expandable="true" %}

```docker
# 단계 1: SteamCMD로 steamclient.so를 다운로드합니다. 게임 서버가 Steam에 로그인할 때 필요하며,
# GodotSteam에 포함된 Steamworks 재배포 가능 파일에는 들어 있지 않습니다.
FROM ubuntu:24.04 AS steamcmd
RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates curl lib32gcc-s1 \
 && rm -rf /var/lib/apt/lists/*
WORKDIR /steamcmd
RUN curl -fsSL https://steamcdn-a.akamaihd.net/client/installer/steamcmd_linux.tar.gz | tar -xz \
 && ./steamcmd.sh +quit \
 && test -f linux64/steamclient.so

# 단계 2: Godot 전용 서버.
FROM ubuntu:24.04
# Edgegap Godot 플러그인과 동일한 규칙: 확장자를 제외한 프로젝트 기준 상대 경로.
ARG SERVER_BUILD_PATH=build/edgegap-linux-server

RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates tini \
 && rm -rf /var/lib/apt/lists/* \
 && useradd --create-home --uid 1001 game

# steam_api는 64비트 Steam 클라이언트 라이브러리를 ~/.steam/sdk64/에서 찾습니다.
COPY --from=steamcmd --chown=game:game /steamcmd/linux64/steamclient.so /home/game/.steam/sdk64/steamclient.so

WORKDIR /home/game/server
COPY --chown=game:game ${SERVER_BUILD_PATH}.x86_64 ./server.x86_64
COPY --chown=game:game ${SERVER_BUILD_PATH}.pck ./server.pck
# 바이너리와 함께 내보낸 GDExtension 및 Steamworks API 라이브러리.
COPY --chown=game:game build/libgodotsteam_server.linux.template_*.x86_64.so build/libsteam_api.so ./
RUN chmod +x server.x86_64

# Steam 앱 ID(480 = Spacewar, Valve의 테스트 앱). steam_appid.txt와 같은 효과입니다.
ENV SteamAppId=480

USER game
# tini가 SIGTERM을 전달하므로 배포를 중지하면 서버가 즉시 종료됩니다.
ENTRYPOINT ["/usr/bin/tini", "--", "./server.x86_64"]
```

{% endcode %}

☑️ 옆에 `.dockerignore` 를 추가해 Docker가 Godot 캐시를 빌드에 보내지 않도록 하세요:

{% code title=".dockerignore" %}

```
.godot/
.git/
```

{% endcode %}

{% hint style="info" %}
The `SteamAppId` 환경 변수는 Steamworks API에 이 서버가 어떤 게임에 속하는지 알려줍니다. 이미지를 다시 빌드하는 대신 Edgegap에서 앱 버전별로 이 값을 재정의할 수 있습니다.
{% endhint %}

☑️ 이미지를 빌드합니다. 타임스탬프를 태그로 지정하고, 절대 `latest`:

```bash
docker build --platform linux/amd64 -t my-game-server:20261109-1924 .
```

☑️ 업로드하기 전에 로컬에서 테스트합니다:

```bash
docker run --name my-game-server -p 7777:7777/udp -p 27015:27015/udp my-game-server:20261109-1924
```

로그에 서버가 Steam에 로그인하는 내용이 표시되어야 합니다.

```
[S_API] SteamAPI_Init(): Loaded '/home/game/.steam/sdk64/steamclient.so' OK.  (First tried local 'steamclient.so')
Setting breakpad minidump AppID = 480
STEAM init ok game_port=7777 query_port=27015
SERVER listening udp=7777 request_id=-
STEAM logged on steam_id=90297081554892826 public_ip=203.0.113.10 secure=false
```

{% hint style="info" %}
다음 줄 `dlopen failed trying to load: steamclient.so` 바로 앞에 `Loaded '/home/game/.steam/sdk64/steamclient.so' OK` 가 예상됩니다. Steamworks API는 먼저 작업 디렉터리에서 시도합니다.
{% endhint %}

☑️ 컴퓨터에서 Steam을 실행한 상태로, 프로젝트에서 클라이언트를 시작하고 컨테이너에 연결합니다:

```bash
godot --path . -- --connect=127.0.0.1:7777
```

클라이언트에는 `AUTHENTICATED by Steam, 1 player(s) on the server`이 표시되고, 서버 로그에는 `AUTH ok peer=... steam_id=...`가 표시됩니다. 클라이언트를 닫으면 서버 로그에 `SERVER stopping reason=everyone left` 가 표시된 후 종료됩니다(로컬에는 삭제할 배포가 없습니다).

✅ 이제 다음 단계로 진행할 수 있습니다.

## ☁️ 5. Edgegap에 업로드

☑️ 이미지를 다음으로 푸시합니다:  [Edgegap의 컨테이너 레지스트리](https://docs.edgegap.com/ko/learn/advanced-features/edgegap-container-registry.md). 프로젝트 이름, 사용자 이름, 토큰은 대시보드의  [컨테이너 레지스트리 페이지](https://app.edgegap.com/registry-management/repositories/list) 에서 확인하세요:

```bash
echo "<registry-token>" | docker login registry.edgegap.com -u "<registry-username>" --password-stdin
docker tag my-game-server:20261109-1924 registry.edgegap.com/<project>/my-game-server:20261109-1924
docker push registry.edgegap.com/<project>/my-game-server:20261109-1924
```

☑️ [애플리케이션을 만들고](https://app.edgegap.com/application-management/applications/list), 그런 다음 [새 버전을](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md) 만들어 이미지와 태그, 다음 포트를 설정합니다.

| 포트 이름       | 포트    | 프로토콜 | 용도                                                                                                               |
| ----------- | ----- | ---- | ---------------------------------------------------------------------------------------------------------------- |
| `gameport`  | 7777  | UDP  | ENet 게임 트래픽입니다. 플레이어가 이 포트로 접속합니다.                                                                               |
| `queryport` | 27015 | UDP  | Steam 서버 쿼리(A2S)용입니다. 선택 사항이며, 자세한 내용은 [#steam-server-browser](#steam-server-browser "mention")을 참조하세요. 검증은 끄세요. |

☑️ 선택적으로 버전 환경 변수를 추가합니다.

* `SteamAppId` 이미지에 포함된 App ID를 재정의합니다.
* `STEAM_GSLT` 게임 서버 로그인 토큰용입니다. 이름에 따라 시크릿으로 처리됩니다.

{% hint style="info" %}
이 스크립트에는 vCPU 0.5개와 메모리 1GB면 충분했습니다. 배포의 컨테이너 메트릭을 참고해 게임에 맞게 크기를 조정하세요.
{% endhint %}

✅ 이제 다음 단계로 진행할 수 있습니다.

## 🚀 6. 배포하고 클라이언트 연결하기

☑️ 새 버전을 [대시보드](https://app.edgegap.com/deployment-management/deployments/list)에서 내 위치와 가까운 곳에 배포합니다. 상태가 **준비됨**으로 바뀌면 컨테이너 로그에 Steam 서버가 표시됩니다.

```
STEAM init ok game_port=32137 query_port=27015
SERVER listening udp=7777 request_id=101ce07c06f7
STEAM logged on steam_id=90297081535503378 public_ip=192.46.222.253 secure=false
```

`game_port` 는 **외부** 포트로, Edgegap이 7777에 매핑한 포트입니다. 스크립트는 주입된 `ARBITRIUM_PORT_GAMEPORT_EXTERNAL` 변수에서 이 값을 읽어 Steam에 전달하므로, Steam은 플레이어가 실제로 접속할 수 있는 주소를 광고합니다.

☑️ 클라이언트를 배포의 호스트와 `gameport`:

```bash
godot --path . -- --connect=101ce07c06f7.pr.edgegap.net:32137
```

클라이언트 로그:

```
CLIENT Connecting to 101ce07c06f7.pr.edgegap.net:32137...
CLIENT Connected, sending Steam ticket (234 bytes) to server 90297081535503378
CLIENT AUTHENTICATED by Steam, 1 player(s) on the server
```

서버 로그:

```
PEER connected peer=1943168941, waiting for Steam ticket
AUTH begin peer=1943168941 steam_id=76561198040851267 result=0
AUTH ok peer=1943168941 steam_id=76561198040851267 owner=76561198040851267 players=1
```

☑️ 클라이언트를 종료합니다. 서버는 Steam에서 로그아웃하고 자체 배포를 `ARBITRIUM_DELETE_URL`을 통해 삭제하므로 배포가 자동으로 종료됩니다. 연결을 끊지 않고 사라진 클라이언트(충돌 또는 연결 끊김)는 ENet의 시간 초과가 발생하면 제거됩니다(최대 약 30초).

{% hint style="warning" %}
**실제 운영 중인 게임에서 배포를 수동으로 시작하고 주소를 복사해 붙여 넣는 방식은 적절하지 않습니다.** Edgegap [매치메이커가](https://docs.edgegap.com/ko/learn/matchmaking.md) 서버를 시작하고 매칭된 모든 클라이언트에 주소를 전달하도록 하며, Steam 인증 티켓 확인은 서버에서 수행하세요.
{% endhint %}

🙌 축하합니다. GodotSteam Server 전용 서버가 Edgegap에서 실행되고 있습니다!

## 👉 다음 단계

### Steam 서버 브라우저

Steam 서버 브라우저(`requestInternetServerList()` GodotSteam에서 사용하거나 Steam 클라이언트의 서버 목록을 사용하는 방식)는 **Edgegap 배포에는 적합하지 않습니다**. 테스트 결과, Steam은 올바른 연결 주소(공개 IP와 외부 게임 포트)로 서버를 표시하지만, 쿼리 포트는 내부 포트로 기록합니다 `27015`. Edgegap은 해당 포트를 임의의 외부 포트에 매핑하므로 Steam의 핑이 시간 초과되고 서버가 응답하지 않는 것으로 표시됩니다. 배포의 외부 `queryport` 로 전송한 A2S 쿼리에는 응답이 돌아옵니다.

대신 다음 방법 중 하나로 플레이어를 서버에 연결하세요.

* [Edgegap 매치메이커](https://docs.edgegap.com/ko/learn/matchmaking.md): 플레이어가 매치 찾기를 누르면 Edgegap이 플레이어와 가까운 서버를 시작하고 모든 클라이언트에 서버 주소를 전달합니다.
* Steam 로비: 서버가 준비되면 파티장의 로비에서 `Steam.setLobbyGameServer()` 또는 로비 데이터를 사용해 서버 주소를 저장하고, 멤버는 해당 주소를 읽어 참가합니다.
* [Edgegap 서버 브라우저](https://docs.edgegap.com/ko/learn/server-browser.md) : 플레이어가 목록에서 선택하는 상시 운영 서버에 사용합니다.

### Steam 계정 및 게임 서버 로그인 토큰

`logOnAnonymous()` 를 사용하면 서버가 시작될 때마다 새 Steam ID가 부여됩니다. 한 세션 동안만 운영되는 매치 서버에 일반적으로 사용하는 방식이며, 인증 티켓 확인에도 이 방식이면 충분합니다.

서버의 영구적인 ID(예: 플레이어가 서버를 즐겨찾기에 추가할 수 있도록 하려는 경우)가 필요하다면 [게임 서버 로그인 토큰(GSLT)](https://steamcommunity.com/dev/managegameservers) 과 `logOn(token)`을 사용해야 합니다. 각 토큰은 한 번에 실행 중인 서버 하나에서만 사용할 수 있으므로, 매치마다 배포를 하나씩 만드는 방식보다는 장시간 실행되는 서버 몇 대를 운영하는 데 적합합니다. 토큰은 버전 변수 `STEAM_GSLT` 로 저장하고, 이미지나 저장소에는 절대 넣지 마세요. 이 테스트에서는 익명 로그온만 사용했습니다.

### 인증 모드

`serverInitEx()` 에는 서버 모드를 지정합니다.

* `SERVER_MODE_NO_AUTHENTICATION` (1): Steam 확인을 수행하지 않습니다.
* `SERVER_MODE_AUTHENTICATION` (2): Steam에서 인증 티켓을 검증합니다. 이 가이드에서 사용한 모드입니다.
* `SERVER_MODE_AUTHENTICATION_AND_SECURE` (3): VAC가 활성화된 앱에서 VAC도 켭니다. `isServerSecure()` 는 Steam에서 서버를 보안 서버로 표시하면 `true` 를 반환합니다.

### 문제 해결

<details>

<summary><code>Failed to retrieve non-existent singleton 'SteamServer'</code> 또는 <code>GDExtension dynamic library not found</code></summary>

서버 내보내기에 필요한 파일이 없습니다. `libgodotsteam_server.linux.template_*.x86_64.so` 내보내기 작업에서 파일이 다음 경로에 생성되었는지 확인하세요. `build/` 그리고 Dockerfile이 이 파일을 바이너리와 같은 위치에 복사하는지도 확인하세요. Edgegap Godot 플러그인의 기본 Dockerfile은 그렇게 하지 않으므로 이 가이드의 Dockerfile을 사용하세요.

</details>

<details>

<summary><code>serverInitEx failed</code>  서버에서</summary>

* `steamclient.so` 가 다음 경로에 없습니다. `~/.steam/sdk64/`  서버를 실행하는 사용자의 경로입니다. SteamCMD 단계와 `COPY --from=steamcmd`  줄, 그리고 `USER game` 이 지정하는 홈 디렉터리를 유지하세요.
* App ID가 없습니다: `SteamAppId` 를 설정하거나 (또는 바이너리 옆에 ID가 포함된 `steam_appid.txt` 를 추가하세요.)

</details>

<details>

<summary><code>Steam init failed, is Steam running and logged in?</code>  클라이언트에서</summary>

플레이어의 컴퓨터에서 Steam 클라이언트가 실행 중이고 로그인되어 있어야 하며, 해당 계정이 App ID를 소유해야 합니다(모든 계정에서 480을 사용할 수 있습니다). Steam을 통해 실행하면 App ID는 Steam에서 가져옵니다.

</details>

<details>

<summary>클라이언트가 다음 메시지와 함께 강제 종료됩니다. <code>Steam auth failed</code>  또는  <code>ticket rejected</code></summary>

* `beginAuthSession`  결과 `1`: 티켓이 유효하지 않습니다. 티켓 버퍼의 처음 `size` 바이트만 전송하세요(`buffer.slice(0, size)`). 버퍼 전체를 전송하면 안 됩니다.
* `beginAuthSession`  결과 `2`: 해당 Steam ID의 티켓이 이미 사용 중입니다. 예를 들어 같은 Steam 계정으로 두 클라이언트가 로그인한 경우입니다.
* `validate_auth_ticket_response`  응답 `2`: 사용자가 App ID를 소유하지 않습니다. 클라이언트와 서버에서 같은 App ID를 사용하는지 확인하세요.

</details>

<details>

<summary>클라이언트가 다음 메시지와 함께 강제 종료됩니다. <code>no Steam ticket</code></summary>

클라이언트가 다음 시간 안에 티켓을 보내지 않았습니다. `AUTH_TIMEOUT_SEC`. 클라이언트 출력에서 Steam 오류를 확인하고, 티켓을 보내기 전에 클라이언트가 `get_auth_session_ticket_response` 를 기다리는지 확인하세요.

</details>

<details>

<summary>배포 로그가 비어 있음</summary>

Project Settings에서 `application/run/flush_stdout_on_print` 를 켜세요. 이 설정이 없으면, `print()` 헤드리스 서버의 출력이 버퍼에 계속 쌓입니다.

</details>

<details>

<summary>Steam에는 서버가 표시되지만 플레이어가 서버 브라우저에서 서버를 찾을 수 없습니다</summary>

Edgegap에서 예상되는 동작입니다. 자세한 내용은 [#steam-server-browser](#steam-server-browser "mention").

</details>

{% hint style="info" %}
도움이 필요하면 [Discord로 문의해 주세요](https://discord.gg/MmJf8fWjnt). 라이브 게임 지원은 [티켓 시스템을 이용해 주세요](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}
