game-framework-app-server

FastAPI-based application server that brokers messages between game clients and pluggable game logic modules.

Overview

This repository hosts a game app server that:

• exposes HTTP endpoints for polling and posting client/server messages,
• initializes game sessions using GameAppServer,
• loads game logic implementations dynamically from registered game packages,
• delegates metadata operations (list games, setup game, fetch game state) to metadata runners.

The core implementation lives in game-app-server/server.py and game-app-server/engine.py.

Repository Structure

game-framework-app-server/
	game-app-server/
		server.py          # FastAPI app and endpoints
		engine.py          # GameAppServer orchestration and game loop
		__init__.py
	Dockerfiles/
		Dockerfile
		docker-compose.yml
	docs/
		game-framework-app-server.png
		ARCHITECTURE.md
		CODEBASE_CONTEXT.md
		LOCAL_DEVELOPMENT.md
		TROUBLESHOOTING.md
	tests/
		.gitkeep
	Pipfile
	Pipfile.lock

Prerequisites

• Python 3.13 (matches Dockerfiles/Dockerfile base image)
• pipenv
• Local package artifacts referenced in Pipfile:
  • ../delirium-logic-core/dist/*.tar.gz
  • ../sample-logic-core/dist/*.tar.gz
  • ../game-framework-runners/dist/*.tar.gz
  • ../game-framework-contracts/dist/*.tar.gz

If those tarballs are missing, dependency sync will fail.

Local Setup

pip install pipenv
pipenv sync
cp .env.example .env

Environment variable used by the server:

• LOCAL_DEV (true or false, defaults to true)

Usage

Current source includes import/path inconsistencies (documented in docs/TROUBLESHOOTING.md) that may require small path fixes before startup works in a clean checkout.

Intended run patterns visible in the repository are:

# FastAPI server
pipenv run uvicorn server:app --host 0.0.0.0 --port 8000

# Engine CLI (arguments are optional)
pipenv run python game-app-server/engine.py [host_environment] [game_name]

API Surface

Defined in game-app-server/server.py:

• GET /poll_from_server
• POST /push_to_client?player_id=...
• POST /post_from_client
• GET /poll_to_client?player_id=...
• GET /get_games_for_player
• GET /setup_new_game
• GET /initialize_server
• GET /game_state

Related Repositories

• Game Framework - Runners
• Game Framework - App Server
• Game Framework - Contracts
• Sample Game UI
• Sample Game Logic

Additional Docs

• Architecture
• Codebase Context
• Local Development
• Troubleshooting