N6: Joining games: direct connect, LAN and server list

- LAN discovery: a listening server answers QUERY packets on its game port
  plus one (ServerBeacon, off with --no-lan). ServerBrowser scans eight game
  ports from 24650 by broadcast.
- A self-hostable list server: --list-server [--port=N] (ListServer,
  default UDP 24660). Game servers register with --list=HOST[:PORT] and
  --name=NAME; they are listed under their source address only after
  echoing a CHALLENGE token. Entries expire after 45 s, 8 per address,
  256 in all; every source is rate-limited (SourceLimiter).
- NetDiscovery messages: every QUERY is padded to 512 bytes and no answer
  is bigger, so neither service amplifies spoofed requests.
- tidewall --browse [--list=...] [--lan-target=IP] [--lan-port=N] prints
  the servers found as JSON until menus (A10) show them.
- People who connect mid-match or during results watch a living player
  (Match.watch) and take places ahead of bots in the next lobby, instead
  of being told the server is full. Bots fill only the places left when
  the match starts.
- Tests: codec round trips, size limits and a 40,000-message fuzz; list
  server with fake servers (challenge, stolen and wrong tokens, renewal,
  expiry, caps, flood); LAN scan over loopback; watchers over UDP; lobby
  backfill. make discovery-check runs it all as real processes.

Closes #37

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-12 17:33:32 -05:00
co-authored by Claude Opus 5.5
parent 53e81bebe1
commit f795ee3fa5
31 changed files with 1524 additions and 17 deletions
+35
View File
@@ -19,6 +19,8 @@ var config: ServerConfig
var loop: ServerLoop
## The network side, when the server was started with --listen.
var game: NetGame = null
## Makes the server findable on the LAN and in list servers, when listening.
var beacon: ServerBeacon = null
var _errors: ErrorCounter = ErrorCounter.new()
var _accumulator: float = 0.0
@@ -54,6 +56,7 @@ func _ready() -> void:
_finish(2)
return
game = NetGame.new(loop, net)
_open_beacon()
var started: Dictionary = config.to_dictionary()
started["engine"] = Engine.get_version_info()["string"]
started["tick_rate_hz"] = Tuning.TICK_RATE_HZ
@@ -72,7 +75,13 @@ func _process(delta: float) -> void:
var fields: Dictionary = {"handle": event["handle"], "name": event["name"], "players": game.net.player_count()}
if event["type"] == "left":
fields["reason"] = event["reason"]
if event.has("watching"):
fields["watching"] = event["watching"]
_log("player_" + String(event["type"]), fields)
if beacon != null:
beacon.players = game.net.player_count()
beacon.phase = loop.match_flow.phase
beacon.poll()
var due: int = UNTHROTTLED_BATCH
if not config.unthrottled:
_accumulator += delta
@@ -95,6 +104,30 @@ func _exit_tree() -> void:
_finish(0)
func _open_beacon() -> void:
if not config.lan and config.lists.is_empty():
return
beacon = ServerBeacon.new()
beacon.server_name = config.server_name
beacon.game_port = game.net.port()
beacon.max_players = game.net.max_players
for target: Dictionary in config.lists:
var host: String = String(target["host"])
var address: String = host if host.is_valid_ip_address() else IP.resolve_hostname(host)
if address.is_empty():
_log("list_unresolved", {"host": host, "message": "couldn't find list server '%s'; not registering with it" % host})
continue
beacon.add_list(address, int(target["port"]))
# Without LAN discovery the socket still has to exist to talk to list servers, so
# it takes any free port instead of the well-known one.
var error: Error = beacon.open(0 if config.lan else ServerBeacon.ANY_PORT)
if error != OK:
_log("beacon_failed", {"message": "couldn't open the discovery port %d: %s; the server can still be joined by address" % [beacon.game_port + NetDiscovery.DISCOVERY_PORT_OFFSET, error_string(error)]})
beacon = null
return
_log("beacon", {"port": beacon.port(), "lan": config.lan, "lists": config.lists.size()})
func _tick() -> void:
if config.fault == "script-error" and loop.ticks == FAULT_TICK:
_deliberate_script_error()
@@ -118,6 +151,8 @@ func _finish(requested_code: int) -> void:
var code: int = requested_code
if game != null:
game.net.close()
if beacon != null:
beacon.close()
if loop != null:
var stats: Dictionary = loop.timing_stats()
stats["state_hash"] = loop.sim.state_hash()
+152
View File
@@ -0,0 +1,152 @@
## A self-hostable list of public game servers. Game servers REGISTER every few
## seconds; clients QUERY it a page at a time. Nothing third-party is involved: anyone
## can run one with `tools/godot.sh -- --list-server [--port=N]`.
##
## A server is listed under the address its packets come from, never one it claims,
## and only after it has echoed a CHALLENGE token sent to that address, so nobody can
## list a machine they don't control. Entries expire unless renewed, there is a cap
## per address and overall, and every source is rate-limited.
class_name ListServer
extends RefCounted
## An entry not renewed within this long disappears.
const ENTRY_TTL_MSEC: int = 45000
const MAX_ENTRIES: int = 256
const MAX_PER_ADDRESS: int = 8
var limiter: SourceLimiter = SourceLimiter.new(20, 1000, 4096)
## Packets dropped as malformed, unexpected, or over a limit, so far.
var ignored: int = 0
var challenges_sent: int = 0
var queries_answered: int = 0
var _socket: PacketPeerUDP = null
var _secret: PackedByteArray = PackedByteArray()
## "address:source port" -> {"address", "info": Dictionary, "seen_msec"}.
var _entries: Dictionary = {}
func _init() -> void:
var crypto: Crypto = Crypto.new()
_secret = crypto.generate_random_bytes(16)
func listen(port: int = NetDiscovery.DEFAULT_LIST_PORT, address: String = "*") -> Error:
close()
var socket: PacketPeerUDP = PacketPeerUDP.new()
var error: Error = socket.bind(port, address)
if error != OK:
return error
_socket = socket
return OK
func port() -> int:
return _socket.get_local_port() if _socket != null else 0
func close() -> void:
if _socket != null:
_socket.close()
_socket = null
func entry_count() -> int:
return _entries.size()
## The listed servers, oldest registration first, each an INFO Dictionary with
## "address".
func servers() -> Array[Dictionary]:
var result: Array[Dictionary] = []
for key: String in _entries:
var entry: Dictionary = _entries[key]
var server: Dictionary = (entry["info"] as Dictionary).duplicate()
server["address"] = entry["address"]
result.append(server)
return result
## Handles what arrived and forgets servers that went quiet. `now_msec` is for tests.
func poll(now_msec: int = -1) -> void:
if _socket == null:
return
var now: int = now_msec if now_msec >= 0 else Time.get_ticks_msec()
for _index: int in 256:
if _socket.get_available_packet_count() <= 0:
break
var bytes: PackedByteArray = _socket.get_packet()
handle(bytes, _socket.get_packet_ip(), _socket.get_packet_port(), now)
expire(now)
## Handles one packet from `from_ip`:`from_port`, sending any answer. Public so the
## fuzz test can drive it without a socket's rate.
func handle(bytes: PackedByteArray, from_ip: String, from_port: int, now: int) -> void:
if not limiter.allow(from_ip, now):
ignored += 1
return
var query: Dictionary = NetDiscovery.decode_query(bytes)
if not query.is_empty():
_answer(int(query["page"]), from_ip, from_port)
return
var register: Dictionary = NetDiscovery.decode_register(bytes)
if register.is_empty():
ignored += 1
return
var token: int = token_for(from_ip, from_port)
if int(register["token"]) != token:
challenges_sent += 1
_send(NetDiscovery.encode_challenge(token), from_ip, from_port)
return
var key: String = "%s:%d" % [from_ip, from_port]
if not _entries.has(key):
if _entries.size() >= MAX_ENTRIES or _count_at(from_ip) >= MAX_PER_ADDRESS:
ignored += 1
return
register.erase("token")
_entries[key] = {"address": from_ip, "info": register, "seen_msec": now}
func expire(now: int) -> void:
for key: String in _entries.keys():
if now - int(_entries[key]["seen_msec"]) > ENTRY_TTL_MSEC:
_entries.erase(key)
## The token a server at this address must echo. Derived from a secret made when the
## list server starts, so there is nothing to store per challenge.
func token_for(from_ip: String, from_port: int) -> int:
var context: HashingContext = HashingContext.new()
context.start(HashingContext.HASH_SHA256)
context.update(_secret)
context.update(("%s|%d" % [from_ip, from_port]).to_utf8_buffer())
var digest: PackedByteArray = context.finish()
var token: int = digest.decode_u32(0)
return token if token != 0 else 1
func _answer(page: int, to_ip: String, to_port: int) -> void:
var listed: Array[Dictionary] = servers()
var pages: int = mini(maxi(ceili(listed.size() / float(NetDiscovery.ENTRIES_PER_PAGE)), 1), NetDiscovery.MAX_PAGES)
if page >= pages:
page = pages - 1
var first: int = page * NetDiscovery.ENTRIES_PER_PAGE
var chosen: Array[Dictionary] = listed.slice(first, first + NetDiscovery.ENTRIES_PER_PAGE)
queries_answered += 1
_send(NetDiscovery.encode_list(page, pages, chosen), to_ip, to_port)
func _count_at(address: String) -> int:
var count: int = 0
for key: String in _entries:
if _entries[key]["address"] == address:
count += 1
return count
func _send(bytes: PackedByteArray, to_ip: String, to_port: int) -> void:
if _socket == null:
return
_socket.set_dest_address(to_ip, to_port)
_socket.put_packet(bytes)
+1
View File
@@ -0,0 +1 @@
uid://bsd3tdjjfxawj
+93
View File
@@ -0,0 +1,93 @@
## Runs a ListServer as its own headless process:
##
## tools/godot.sh -- --list-server [--port=N] [--seconds=N]
##
## Logs JSON lines like the game server: a start line, a status line every minute with
## how many servers are listed, and a stop line. `--seconds` stops it after that long,
## for tests; without it, it runs until stopped. Exit codes: 0 clean, 2 bad command
## line or the port couldn't be opened.
class_name ListServerRunner
extends Node
const STATUS_EVERY_MSEC: int = 60000
var list: ListServer = ListServer.new()
var port: int = NetDiscovery.DEFAULT_LIST_PORT
var seconds: float = 0.0
var errors: Array[String] = []
var _started_msec: int = 0
var _next_status: int = 0
## Parses the arguments after `--list-server`.
func _init(args: PackedStringArray) -> void:
var start: int = args.find("--list-server")
for index: int in range(start + 1, args.size()):
var parts: PackedStringArray = args[index].split("=", true, 1)
var value: String = parts[1] if parts.size() == 2 else ""
match parts[0]:
"--port":
port = value.to_int() if value.is_valid_int() else 0
if port < 1 or port > 65535:
errors.append("--port must be between 1 and 65535, got '%s'" % value)
"--seconds":
seconds = value.to_float() if value.is_valid_float() else 0.0
if seconds <= 0.0:
errors.append("--seconds must be a number above 0, got '%s'" % value)
_:
errors.append("unknown argument '%s'" % args[index])
func _ready() -> void:
_started_msec = Time.get_ticks_msec()
if not errors.is_empty():
for problem: String in errors:
_log("config_error", {"message": problem})
get_tree().quit(2)
return
var error: Error = list.listen(port)
if error != OK:
_log("listen_failed", {"port": port, "message": "couldn't listen on UDP port %d: %s" % [port, error_string(error)]})
get_tree().quit(2)
return
Engine.max_fps = 60
_next_status = _started_msec + STATUS_EVERY_MSEC
_log("start", {"port": list.port(), "engine": Engine.get_version_info()["string"]})
func _process(_delta: float) -> void:
if list.port() == 0:
return
list.poll()
var now: int = Time.get_ticks_msec()
if now >= _next_status:
_next_status = now + STATUS_EVERY_MSEC
_log("status", _counts())
if seconds > 0.0 and now - _started_msec >= int(seconds * 1000.0):
_stop()
func _exit_tree() -> void:
if list.port() != 0:
_stop()
func _stop() -> void:
_log("stop", _counts())
list.close()
if is_inside_tree():
get_tree().quit(0)
func _counts() -> Dictionary:
return {
"servers": list.entry_count(), "queries": list.queries_answered,
"challenges": list.challenges_sent, "ignored": list.ignored, "rate_limited": list.limiter.refused,
}
func _log(event: String, fields: Dictionary) -> void:
var record: Dictionary = {"t_ms": Time.get_ticks_msec() - _started_msec, "event": event}
record.merge(fields, false)
print(JSON.stringify(record))
+1
View File
@@ -0,0 +1 @@
uid://dl6t6rs2ridvo
+13 -5
View File
@@ -45,11 +45,18 @@ func poll() -> void:
for event: Dictionary in net.events.duplicate():
var handle: int = int(event.get("handle", 0))
if event["type"] == "joined":
if loop.match_flow.join(handle):
# In the lobby they take a place; once a match is under way they watch it
# and take a place in the next one.
var watching: bool = false
if not loop.match_flow.join(handle):
watching = loop.match_flow.watch(handle)
if loop.match_flow.participants.has(handle) or watching:
adopt(handle)
_send_match(handle)
net.send(handle, NetProtocol.CHANNEL_CONTROL, world_notice(), true)
events.append(event)
var joined: Dictionary = event.duplicate()
joined["watching"] = watching
events.append(joined)
else:
net.kick(handle, NetProtocol.REASON_FULL)
elif event["type"] == "left" and sender.has_client(handle):
@@ -163,15 +170,16 @@ func match_notice() -> PackedByteArray:
## The entity a participant is watching: their own player, the player they spectate
## once eliminated, or 0 when they aren't in a match.
## once eliminated (or, for someone who arrived mid-match, from the start), or 0 when
## they aren't in a match.
func viewer_of(handle: int) -> int:
var flow: Match = loop.match_flow
if flow.phase == Match.LOBBY or flow.phase == Match.COUNTDOWN or not flow.entity_of.has(handle):
if flow.phase == Match.LOBBY or flow.phase == Match.COUNTDOWN:
return 0
var target: int = flow.spectate_target(handle)
if target != 0 and flow.entity_of.has(target):
return int(flow.entity_of[target])
return int(flow.entity_of[handle])
return int(flow.entity_of.get(handle, 0))
## An OWN message for a participant if what they carry has changed since they were
+114
View File
@@ -0,0 +1,114 @@
## Makes a game server findable. It answers LAN QUERY packets on the game port plus
## NetDiscovery.DISCOVERY_PORT_OFFSET, and, given list servers, registers with each
## every HEARTBEAT_MSEC, answering their CHALLENGE so they list it.
##
## The owner keeps `players` and `phase` current and calls poll() every frame.
class_name ServerBeacon
extends RefCounted
const HEARTBEAT_MSEC: int = 15000
## After a CHALLENGE, the answer goes out at once rather than at the next heartbeat.
const ANSWER_DELAY_MSEC: int = 0
## For open(): any free port, which LAN scans won't ask. For list servers only.
const ANY_PORT: int = -1
var server_name: String = NetDiscovery.DEFAULT_SERVER_NAME
var game_port: int = ServerConfig.DEFAULT_PORT
var max_players: int = Tuning.SOLO_PLAYERS
var players: int = 0
var phase: int = Match.LOBBY
## LAN queries answered, and packets ignored (malformed, flooding or unasked-for).
var answered: int = 0
var ignored: int = 0
## Registrations sent, and challenges answered, per list server, for tests and logs.
var registrations: int = 0
var limiter: SourceLimiter = SourceLimiter.new()
var _socket: PacketPeerUDP = null
## Each list server: {"host", "port", "token", "next_msec"}.
var _lists: Array[Dictionary] = []
## Opens the discovery socket. `port` 0 uses the game port plus the offset, ANY_PORT
## a free one; tests pass their own. Returns OK or the error.
func open(port: int = 0, address: String = "*") -> Error:
close()
var socket: PacketPeerUDP = PacketPeerUDP.new()
var wanted: int = port if port > 0 else game_port + NetDiscovery.DISCOVERY_PORT_OFFSET
if port == ANY_PORT:
wanted = 0
var error: Error = socket.bind(wanted, address)
if error != OK:
return error
_socket = socket
return OK
func is_open() -> bool:
return _socket != null
func port() -> int:
return _socket.get_local_port() if _socket != null else 0
## Adds a list server to register with. `host` must be an IP address; resolve names
## first (ServerConfig does).
func add_list(host: String, port: int) -> void:
_lists.append({"host": host, "port": port, "token": 0, "next_msec": 0})
func close() -> void:
if _socket != null:
_socket.close()
_socket = null
## What this server says about itself.
func describe() -> Dictionary:
return NetDiscovery.info(game_port, players, max_players, phase, server_name)
## Answers what arrived and sends any heartbeat that is due. `now_msec` is for tests.
func poll(now_msec: int = -1) -> void:
if _socket == null:
return
var now: int = now_msec if now_msec >= 0 else Time.get_ticks_msec()
# A bounded number per frame, so a flood can't stall the game.
for _index: int in 64:
if _socket.get_available_packet_count() <= 0:
break
var bytes: PackedByteArray = _socket.get_packet()
var from_ip: String = _socket.get_packet_ip()
var from_port: int = _socket.get_packet_port()
_received(bytes, from_ip, from_port, now)
for list: Dictionary in _lists:
if now >= int(list["next_msec"]):
_register(list, now)
func _received(bytes: PackedByteArray, from_ip: String, from_port: int, now: int) -> void:
if not limiter.allow(from_ip, now):
ignored += 1
return
if not NetDiscovery.decode_query(bytes).is_empty():
_socket.set_dest_address(from_ip, from_port)
_socket.put_packet(NetDiscovery.encode_info(describe()))
answered += 1
return
var challenge: Dictionary = NetDiscovery.decode_challenge(bytes)
if not challenge.is_empty():
# Only from a list server this server chose to register with.
for list: Dictionary in _lists:
if list["host"] == from_ip and int(list["port"]) == from_port:
list["token"] = int(challenge["token"])
list["next_msec"] = now + ANSWER_DELAY_MSEC
return
ignored += 1
func _register(list: Dictionary, now: int) -> void:
list["next_msec"] = now + HEARTBEAT_MSEC
_socket.set_dest_address(String(list["host"]), int(list["port"]))
_socket.put_packet(NetDiscovery.encode_register(int(list["token"]), describe()))
registrations += 1
+1
View File
@@ -0,0 +1 @@
uid://dyt5a2sj2qlrf
+52
View File
@@ -3,11 +3,15 @@
## tools/godot.sh -- --server [--listen] [--port=N] [--seed=N] [--players=N] [--bots=N]
## [--bot-difficulty=mixed|easy|normal|hard] [--ticks=N]
## [--unthrottled] [--log-every=N]
## [--name=NAME] [--list=HOST[:PORT]]... [--no-lan]
##
## With `--listen` the server takes network players on UDP `--port`, waits in the lobby
## for the first of them, and with any `--bots` above 0 fills each match's empty places
## with bots. Without it the match starts at once with `--players` idle slots.
##
## A listening server answers LAN discovery on its port plus one unless `--no-lan`,
## and registers with each `--list` server (see ListServer) under `--name`.
##
## Unknown or malformed arguments are errors, so a typo can't silently run the wrong
## match. See `parse()`.
class_name ServerConfig
@@ -39,6 +43,12 @@ var unthrottled: bool = false
## Logs a progress line every this many ticks. 0 turns progress lines off.
var log_every: int = 0
var fault: String = ""
## The name shown in server lists.
var server_name: String = NetDiscovery.DEFAULT_SERVER_NAME
## List servers to register with: {"host", "port"}. Hosts may be names.
var lists: Array[Dictionary] = []
## Answer LAN discovery. On by default for a listening server.
var lan: bool = true
## Human-readable problems found while parsing. Empty when the config is usable.
var errors: Array[String] = []
@@ -72,6 +82,9 @@ func to_dictionary() -> Dictionary:
"bot_difficulty": "mixed" if bot_difficulty < 0 else String(Tuning.BOT_DIFFICULTIES[bot_difficulty]["name"]),
"ticks": ticks,
"unthrottled": unthrottled,
"name": server_name,
"lan": lan and listen,
"lists": lists.size(),
}
@@ -82,6 +95,9 @@ func _parse_one(arg: String) -> void:
if arg == "--listen":
listen = true
return
if arg == "--no-lan":
lan = false
return
var parts: PackedStringArray = arg.split("=", true, 1)
if parts.size() != 2 or not arg.begins_with("--"):
errors.append("unknown argument '%s'" % arg)
@@ -118,10 +134,44 @@ func _parse_one(arg: String) -> void:
errors.append("--bot-difficulty must be mixed, easy, normal or hard, got '%s'" % value)
"--fault":
fault = value
"--name":
server_name = NetDiscovery.clean_server_name(value)
"--list":
var target: Dictionary = parse_host_port(value, NetDiscovery.DEFAULT_LIST_PORT)
if target.is_empty():
errors.append("--list needs HOST or HOST:PORT with a port from 1 to 65535, got '%s'" % value)
else:
lists.append(target)
_:
errors.append("unknown argument '%s'" % arg)
## {"host", "port"} from "HOST" or "HOST:PORT", or empty if it doesn't parse. An
## IPv6 address goes in brackets when it has a port: "[::1]:24660".
static func parse_host_port(text: String, default_port: int) -> Dictionary:
var host: String = text
var port: int = default_port
if text.begins_with("["):
var close: int = text.find("]")
if close < 0:
return {}
host = text.substr(1, close - 1)
var rest: String = text.substr(close + 1)
if not rest.is_empty():
if not rest.begins_with(":") or not rest.substr(1).is_valid_int():
return {}
port = rest.substr(1).to_int()
elif text.count(":") == 1:
var at: int = text.find(":")
host = text.substr(0, at)
if not text.substr(at + 1).is_valid_int():
return {}
port = text.substr(at + 1).to_int()
if host.is_empty() or port < 1 or port > 65535:
return {}
return {"host": host, "port": port}
func _check_int(key: String, value: String) -> bool:
if value.is_valid_int():
return true
@@ -145,5 +195,7 @@ func _validate() -> void:
errors.append("--ticks can't be negative")
if log_every < 0:
errors.append("--log-every can't be negative")
if not listen and (not lists.is_empty() or not lan):
errors.append("--list and --no-lan are for a server started with --listen")
if fault not in FAULTS:
errors.append("unknown --fault '%s'" % fault)