@@ -17,6 +17,8 @@ A lightweight server and framework for turn-based multiplayer games.
 - a framework that allows new games to be added easily
 - a uniform yet flexible API for all games
 - multiple parallel game sessions
+  - you can join a specific session
+  - or auto-join the next non-full session
 - an observer mode to watch another client play
 
 ### Designed for
@@ -51,11 +53,11 @@ Here is a simplified example of the API usage:
 ```py
 from game_server_api import GameServerAPI
 
-game = GameServerAPI(server='127.0.0.1', port=4711, game='TicTacToe',
-                     token='mygame', players=2)
+game = GameServerAPI(server='127.0.0.1', port=4711, game='TicTacToe', players=2,
+                     token='mygame') # pass 'auto' to auto-join a session
 
-my_id = game.join()    # starting/joining a game - each client is assigned an ID
-game.move(position=5)  # performing a move - the function accepts keyword arguments (**kwargs)
+my_id = game.join()    # start/join a session - each client is assigned an ID
+game.move(position=5)  # perform a move - the function accepts keyword arguments (**kwargs)
 state = game.state()   # returns a dictionary representing the game state,
                        # including the ID of the current player(s)
 ```
 
@@ -51,9 +51,12 @@ def __init__(self, server, port, game, token, players=None, name=''):
         Parameters needed in order to connect to the server and to start or join
         a game session are passed to this constructor. Parameter game specifies
         the game to be started. It corresponds to the name of the game class on
-        the server. To be able to join the game session, all participants need
-        to agree on a token and pass it to the constructor. The token is used to
-        identify the game session. It can be any string.
+        the server. To be able to join a specific game session, all participants
+        need to agree on a token and pass it to the constructor. The token is
+        used to identify the game session. It can be any string. Alternatively,
+        you can have the server automatically assign you to a session by passing
+        the string 'auto' as the token. Refer to function join for more
+        information.
 
         The optional parameter players is required by function join in order to
         start a new game session with the specified number of players. If the
@@ -70,7 +73,7 @@ def __init__(self, server, port, game, token, players=None, name=''):
         server (str): server
         port (int): port number
         game (str): name of the game
-        token (str): name of the game session
+        token (str): name of the game session, 'auto' for automatic assignment
         players (int): total number of players (optional)
         name (str): player name (optional)
 
@@ -81,7 +84,7 @@ def __init__(self, server, port, game, token, players=None, name=''):
         assert type(port) == int and 0 <= port <= 65535, self._error('port')
         assert type(game) == str and len(game) > 0, self._error('game')
         assert type(token) == str and len(token) > 0, self._error('token')
-        assert players == None or type(players) == int and players > 0, self._error('players')
+        assert players is None or type(players) == int and players > 0, self._error('players')
         assert type(name) == str, self._error('name')
 
         # server:
@@ -110,8 +113,20 @@ def join(self):
         players must be passed to the constructor. If the argument is omitted,
         this function will only try to join an existing session but never start
         a new one. The argument is ignored when an existing session can be
-        joined. If a session exists but is already fully occupied by players,
-        it is terminated and a new session is started.
+        joined.
+
+        There are two ways to start or join a game session:
+
+        - By providing a shared token to the constructor. All clients using the
+          same token will join this specific game session. If such a session
+          exists but is already fully occupied by players, it is terminated and
+          a new session is started.
+        - By passing the string 'auto' as the token. This causes the server to
+          automatically assign you to an open session. If no session exists that
+          can be joined, a new one is started. Existing sessions are never
+          terminated. This method of starting and joining sessions does not
+          interfere with the above method. To achieve this, the server creates
+          unique tokens internally.
 
         The game starts as soon as the required number of clients has joined the
         game. The function then returns the player ID. The server assigns IDs in
@@ -134,6 +149,7 @@ def join(self):
 
         self._player_id = response['player_id']
         self._key = response['key']
+        self._token = response['token']
         self._request_size_max = response['request_size_max']
 
         return self._player_id
@@ -230,7 +246,8 @@ def observe(self):
         This function will return the player ID of the observed player.
 
         This function can only be called, after the specified game session has
-        already been started.
+        already been started. The observer mode is not available for auto-join
+        sessions.
 
         Returns:
         int: ID of the observed player
@@ -241,6 +258,9 @@ def observe(self):
         if type(self._name) != str or len(self._name) == 0:
             raise GameServerError('a valid name must be passed to the constructor')
 
+        if self._token == 'auto':
+            raise GameServerError('observer mode not available for auto-join sessions')
+
         response, err, _ = self._send({
             'type':'observe',
             'game':self._game,
 
@@ -45,6 +45,10 @@ def __init__(self):
         self._build_game_class_dict()
         self._start_clean_up()
         self._player_joins = threading.Event()
+        self._auto_join_tokens = {} # game name -> auto-join token
+        self._next_auto_join_token = 0
+        self._AUTO = 'auto'
+        self._lock = threading.Lock()
 
     def _build_game_class_dict(self):
         """
@@ -87,7 +91,9 @@ def _join(self, request):
         join. If this is the case, the request is passed to the function for
         joining a session. In all other cases, the function for starting a new
         game session is called. This implies that an already running session
-        will be terminated.
+        will be terminated. When a client makes use of the auto-join
+        functionality, a unique token is generated. In this case, sessions are
+        never terminated. A new session is created instead.
 
         Parameters:
         request (dict): request containing game name and token
@@ -108,14 +114,23 @@ def _join(self, request):
         if game_name not in self._game_classes:
             return utility.framework_error('no such game')
 
+        if token.startswith(self._AUTO) and len(token) > len(self._AUTO):
+            return utility.framework_error("token must not start with reserved prefix 'auto'")
+
+        # generate token for auto-joining clients:
+        if token == self._AUTO:
+            token = self._generate_auto_join_token(game_name, players)
+            name = '' # no observer mode for auto-join sessions
+
         # retrieve game session, if it exists:
         session, _ = self._retrieve_session(game_name, token)
 
         # start or join a session:
         if session and not session.full():
-            return self._join_session(session, name)
+            return self._join_session(session, name, token)
         elif not session and not players:
-            return utility.framework_error('no such game session')
+            return utility.framework_error(
+                'no such game session; provide the number of players to start one')
         elif session and session.full() and not players:
             return utility.framework_error('game session already full')
         else:
@@ -169,20 +184,22 @@ def _start_session(self, game_name, token, players, name):
 
         # wait for others to join:
         self._await_game_start(session)
+        self._remove_auto_join_token(game_name, token)
 
         if not session.full(): # timeout reached
             if (game_name, token) in self._game_sessions:
-                del self._game_sessions[(game_name, token)] # remove game session
+                del self._game_sessions[(game_name, token)]
             return utility.framework_error('timeout while waiting for others to join')
 
         log.info(f'Starting session {game_name}:{token}')
 
         return self._return_data({
             'player_id':player_id,
             'key':key,
+            'token':token,
             'request_size_max':config.request_size_max})
 
-    def _join_session(self, session, name):
+    def _join_session(self, session, name, token):
         """
         Joining a game session.
 
@@ -199,6 +216,7 @@ def _join_session(self, session, name):
         Parameters:
         session (GameSession): game session
         name (str): player name, can be an empty string
+        token (str): name of the game session
 
         Returns:
         dict: containing the player's ID and key
@@ -217,6 +235,7 @@ def _join_session(self, session, name):
         return self._return_data({
             'player_id':player_id,
             'key':key,
+            'token':token,
             'request_size_max':config.request_size_max})
 
     def _move(self, request):
@@ -322,7 +341,8 @@ def _observe(self, request):
         needs to know the ID of that player. This function retrieves that ID
         based on the player's name. This only works, if the player has supplied
         a name when joining the game session. The observed player's key is sent
-        to the client as well.
+        to the client as well. The observer mode is not available for auto-join
+        sessions.
 
         Parameters:
         request (dict): request containing game name, token and player to be observed
@@ -338,6 +358,9 @@ def _observe(self, request):
         token = request['token']
         player_name = request['name']
 
+        if token == self._AUTO:
+            return utility.framework_error('observer mode not available for auto-join sessions')
+
         # retrieve game session:
         session, err = self._retrieve_session(game_name, token)
         if err: # no such game or game session
@@ -429,6 +452,40 @@ def _retrieve_session(self, game_name, token):
 
         return self._game_sessions[(game_name, token)], None
 
+    def _generate_auto_join_token(self, game_name, players):
+        """
+        Generate a unique token for an auto-join session.
+
+        Parameters:
+        game_name (str): name of the game
+        players (int): total number of players
+
+        Returns:
+        str: a unique token for an auto-join session, None in case of an error
+        """
+        with self._lock:
+            if game_name not in self._auto_join_tokens:
+                if not players: return None
+                token = f'{self._AUTO}-{self._next_auto_join_token}'
+                self._next_auto_join_token += 1
+                self._auto_join_tokens[game_name] = token
+            else:
+                token = self._auto_join_tokens[game_name]
+
+            return token
+
+    def _remove_auto_join_token(self, game_name, token):
+        """
+        This function is used to remove a token from the auto-join dictionary
+        after the session has been started.
+
+        Parameters:
+        game_name (str): name of the game
+        token (str): name of the game session
+        """
+        if token.startswith(self._AUTO):
+            del self._auto_join_tokens[game_name]
+
     def _return_data(self, data):
         """
         Adds data to a dictionary to be sent back to the client. This function