GitHub - feberts/python-game-server: A lightweight server and framework for turn-based multiplayer games · GitHub

/" data-turbo-transient="true" />

Skip to content

Type / to search

Sign in<br>Sign upAppearance settings

You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

{{ message }}

feberts

python-game-server

Public

Notifications<br>You must be signed in to change notification settings

Fork

Star<br>10

main

BranchesTags

Go to file

CodeOpen more actions menu

Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit

History<br>612 Commits<br>612 Commits

.github

.github

client

client

server

server

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

gameserver.service

gameserver.service

View all files

Repository files navigation

Python game server

A lightweight server and framework for turn-based multiplayer games.

Basic Python skills are sufficient to implement clients and add new games to the server.

Overview

Features

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

Use cases

development of turn-based multiplayer games such as board or card games

programming courses in which students implement clients or new games

Quick start

To try this on your machine

start the server (server/game_server.py)

then run two clients (client/tictactoe_client.py)

The only requirement is a regular Python installation.

Implementing clients

Module game_server_api provides an API for communicating with the server. It allows you to

start or join a game session

submit moves

retrieve the game state

restart a game within the current session

This is what a simple game loop might look like (view full example here):

from game_server_api import GameServerAPI, IllegalMove

game = GameServerAPI(server='127.0.0.1', port=4711, game='TicTacToe', players=2,<br>session='mygame') # pass 'auto' to auto-join a session (default)

my_id = game.join() # start/join a session - each client is assigned an ID<br>state = game.state() # returns a dictionary representing the game state

while not state['gameover']:<br>board = state['board']<br># print game board here ...

if my_id in state['current']:<br>pos = int(input('Your turn: '))

try:<br>game.move(position=pos) # perform a move - the function accepts keyword arguments<br>except IllegalMove as e:<br># something went wrong ...<br>else:<br># opponent's turn ...

state = game.state() # to prevent polling, the function blocks until the state changes

The API module includes detailed documentation. You can also take a look at the demo clients and the Wiki.

Adding new games

Adding a new game is easy. You derive from a base class and override its methods:

Create a new module in server/games/.

Implement a class that is derived from AbstractGame.

Override the base class's methods.

Add the new class to the list of games (server/games_list.py).

To make things even easier, you can use the template (server/games/template.py). It's structured like a tutorial.

No modifications to the API are required when adding new games. It was designed to be compatible with any game. The function to submit a move accepts keyword arguments (**kwargs). These are sent to the server and passed to the game class as a dictionary. The game state is also sent back as a dictionary. This allows for a maximum of flexibility.

Operating the server

To run the server in a network, edit IP and port in the configuration file (server/config.py). Other settings can also be adjusted there, such as enabling TLS. If you intend to run the server as a systemd service, you can use the provided unit file. Server and API are implemented in plain Python. Only modules from the standard library are used. This makes the server easy to handle.

Learn more in the Wiki.

About this project

This server was developed for use in a programming course, where students learn Python as their first programming language and work on projects in small groups. Both the framework and the API are designed so that basic programming skills are sufficient to implement games and clients. However, the use of the server is not limited to educational scenarios.

Contributing

Contributions are welcome. Feel free to create a pull request, open an issue or use the Discussions section.

License

Copyright (C) 2025, 2026 Fabian Eberts. Licensed under the GPL version 3 (see LICENSE).

About<br>A lightweight server and framework for turn-based multiplayer games<br>Topics<br>board-gameseducationgame-frameworkgame-serverlightweightmultiplayerpythonsimpleturn-based<br>Resources<br>Readme<br>GPL-3.0 license<br>Activity<br>Stars<br>10 stars<br>Watchers<br>2 watching<br>Forks<br>1 fork<br>Report repository

Contributors

Languages

You can’t perform that...