Games:...scover(3pm)

🧊 Frozen-Bubble 💖

okay bestie, first things first, the legal bit, and I promise it's important, no skipping 🫶

Copyright © 2010 The Frozen-Bubble Team

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2, as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

---

✨ NAME ✨

Games::FrozenBubble::NetDiscover — high performance server discovery plugin for frozen bubble 👑

🦋 SYNOPSIS 🦋

like, here's the whole vibe in one go:

my $discover = Games::FrozenBubble::NetDiscover->new(
    { host => "1.2.3.4", port => 1511 },
    { host => "5.6.7.8", port => 1512 }, ...);
while($discover->pending()) {
    my @servers = $discover->found();
    for(my $server = 0; $server < @servers; $server++) {
        printf("%02i: ip %s ping %i\n",
            $server, $servers[$server]{ip}, $servers[$server]{ping});
    }
    $discover->work(0.1); # sit in a select loop for 100ms

    # update your screen, and all of that stuff, here.
}

🌸 DESCRIPTION 🌸

So Games::FrozenBubble::NetDiscover is the girl who goes around checking a whole list of servers, and she comes back with their versions, their ping times, and how many clients are currently on each one. ✨ She uses nonblocking IO and select, so she's connecting to multiple servers in parallel instead of one after the other, which means the total time elapsed goes way down. And why do we care?? Because it literally lets the user start playing frozen bubble sooner. :)

This module is built to be called from a GUI loop, bestie. It has to sit in a select loop for most of its life to get accurate ping times, but it will always come back to your loop at intervals you specify, so you can check for keystrokes and refresh the screen and all that cute stuff. 💅

Now, to get consistent results on slow dialup links, this module will only attempt to connect to one server per each 200ms. Which means: for 18 servers, that's 3.4 seconds of extra guaranteed lag 😭 BUT it also means packets from multiple servers are less likely to bump into eachother in the queue, so ping reply times are more reliable. trade-offs, we love to see it.

In the source script, there are two configuration parameters: $number_of_pings and $time_between_connections. These are set to 2 and 0.2, respectively. These two parameters decide how much bandwidth is used and how long the user waits before they can select a server. Assuming the user's internet connection can handle the traffic without extra latency from queueing or retransmissions, the worst case latency will be, in seconds:

N*L + T*(S-1)

where

N = $number_of_pings
L = the roundtrip time of the slowest server in the list, in seconds
T = $time_between_connections
S = the number of servers in the list

🌈 CONSTRUCTOR 🌈

...->new ({host => "server1", port => port}, {host => "server2", port => port}, ...)

Takes a list of servers as arguments. Every server argument should be a hash reference made of {host => host, port => port}. It hands you back a Games::FrozenBubble::NetDiscover object, which you can then use inside a GUI loop to discover all of your servers. 🎀

The host string should ideally be an IP address. A hostname string should work too, but DNS lookups will introduce extra, unpredictable latency later on. not her fault, just the way DNS is. 🙈

💜 METHODS 💜

These methods define the public API for instances of this class. iconic behaviour only.

🔥 found

Returns a list of 0 or more servers found. Each return value is a hash reference, containing the following keys:

• host — the IP address of the server
• port — the TCP port of the server
• pingtimes — array reference, contains the actual result times of 4 pings
• ping — the average roundtrip latency of the server, in ms
• freenicks — the list of players connected
• freegames — the list of open games (not yet started)
• free — the number of idle clients connected to this server
• games — the number of clients connected to this server, who are playing games
• playing — the list of players in games
• geolocs — the geolocations of players in games
• name — the self-proclaimed "name" reported by the server
• language — the preferred language reported by the server

⏳ pending

Returns non-zero if we are still waiting for a response from one or more servers; returns 0 if processing is complete. you'll know when she's done, bestie.

🛠️ work(seconds)

Enters the main loop of this module. This method requires one argument, a numeric count of seconds to work for. This is expected to be a floating point decimal, for sub-second precision. Returns the number of servers pending, just like the pending method does.

🧚 INTERNAL METHODS 🧚

These methods are only meant to be called from within the module. They are subject to change without notice. so like, don't get attached, okay? 😭

💫 try_connect

Attempts to connect to a server. Moves the first "not_started" server to the "pending" list, and creates a non-blocking IO::Socket::INET object for it. Updates the begin_time timestamp, to determine when the next server should be connected.

🌟 server_sm(connection_number)

Implements a simple state machine. Called with an index into the pending array, to indicate that data is available for reading from this server.

🚫 give_up_on(connection_number, reason)

Called if select reports a socket as has_exception. Also called if the server has a bogus version, times out, or we can't parse the IP address or something. Removes the entry from further processing, and emits an error message on stderr. it's giving closure, but make it stderr. 💀

🎀 EXPORT 🎀

None.

like. nothing. zero. the audacity. 💅

💀 BUGS 💀

implement some sort of timeout, for servers which don't respond within 5 seconds.

yeah bestie that's a TODO and it's just sitting there. known. documented. not fixed. we move. 🙈

👑 AUTHOR 👑

Mark Glines, <mark@glines.org>.

⭐ COPYRIGHT AND LICENSE ⭐

This code is donated to the frozen bubble project, www.frozen-bubble.org, so they can do whatever they want with it. Copyright is therefore assigned to those guys.

---

and that's the whole page, bestie 🫶 this was perl v5.42.3, dated 2026-08-20, from the User Contributed Perl Documentation, and it's the manual for Games::FrozenBubble::NetDiscover(3pm). go discover some servers, slay, periodt. 💖✨🎀🦋