fairhopper/README.md

FairHopper

Game

Overview

• Rectangle board W × H
• Destination: center of a board (W / 2, H / 2)
• Initial player position: Random on board border
• Available moves:
  • left
  • right
  • up
  • down
• Optional on-board obstacles

Rules

• Goal: Reach the goal destination
• Player can't move out of board
• Player can't move if destination position contains obstacle
• Move timeout: 10s. Game is finished if timeout ocurrs.

Game States

scale 1024 width
hide empty description

state "Start Game" as StartGame
state "Move" as MovePlayer: Destination reached?
state "Destination Reached" as DestinationReached
state "Product Selection" as ProductSelection: Enable product selection for winning player
state "Product Selected" as ProductSelected
state "Selection Timeout" as SelectionTimeout
state "End Player's Game" as EndPlayer
state "Lock Game" as LockGame <<end>>
state "End Game" as EndGame <<end>>
state "Unlock game" as UnlockGame <<end>>

[*] -> StartGame
StartGame -> MovePlayer
MovePlayer <-- MovePlayer: NO
MovePlayer --> DestinationReached: YES
DestinationReached --> ProductSelection
DestinationReached -> LockGame: Lock game for all other players
ProductSelection --> ProductSelected
ProductSelection --> SelectionTimeout
ProductSelected --> EndGame: End game\nfor all players
SelectionTimeout -> EndPlayer
EndPlayer --> UnlockGame: Unlock game\n for all players

FairHopper Game Server

Requirements:

• Python 3.10+

Install virtual envirnonment

Project uses Poetry, ultimate dependency management software for Python.

Install Poetry:

pip install poetry

Install virtual environment:

poetry install

Setting up

Copy settings_template.py to settings.py.

Edit settings.py and customize application.

Starting FairHopper Game Server

make run

By default, FairHopper runs on port 8010. To run FairHopper on different port, start uvicorn directly:

poetry run uvicorn main:app --host 0.0.0.0 --port 8010 --workers=1

To activate virtual environment:

poetry shell

WebSockets server runs on port 8011. To run WS Server on different port, edit settings.py configuration.

System overview

Architecture

scale 1024 width
actor "Player 1" as P1
actor "Player 2" as P2
actor "Player 3" as P3

package Masterpiece #seashell {
    rectangle "FairHopper Game Server" #lightcyan {
        usecase API as "API Server"
        usecase Game as "Game Engine"
        usecase WS as "WS Server"
    }
    usecase Vis as "Visualisation\nService"
}

usecase ExtVis1 as "Visualisation\nService"
usecase ExtVis2 as "Visualisation\nService"

P1 -left-> API: REST API
P2 -left-> API: REST API
P3 -left-> API: REST API
API --> Game
Game --> WS: Game State
WS --> Vis: WS Game State
WS --> ExtVis1: WS Game State
WS --> ExtVis2: WS Game State

WebSockets

scale 1024 width
box "FairHopper Game Server" #lightcyan
    participant Game as "Game Engine"
    participant WS as "WS Server"
endbox
participant Client1 as "Visualisation\nClient 1"
participant Client2 as "Visualisation\nClient 2"

== Player movement mode ==

Game ->o WS: Send initial state

Client1 ->o WS: Client connect
activate WS #coral
	WS -> Client1: Game state
deactivate

Client2 ->o WS: Client connect
activate WS #coral
	WS -> Client2: Game state
deactivate

loop #lightyellow On game state change
    Game ->o WS: Game state
    activate WS #coral
        WS o-> Client1: Game state
        WS o-> Client2: Game state
    deactivate
end

== Product purchase mode ==

Game -> WS: Purchase start
activate WS #coral
	WS o-> Client1: Purchase start
	WS o-> Client2: Purchase start
deactivate

loop #lightyellow Purchase countdown timer
	Game ->o WS: Timer count down
    activate WS #coral
        WS o-> Client1: Purchase time left
        WS o-> Client2: Purchase time left
    deactivate
end
Game -> WS: Purchase done
activate WS #coral
	WS o-> Client1: Purchase done
	WS o-> Client2: Purchase done
deactivate

REST API

• Start game
• Move left
• Move right
• Move up
• Move down
• Get player info
• Get board info

Check REST API interface on FastAPI docs.

Start game

Endpoint: POST /game

Request body:

{
  "player_name": "Pero"
}

Response body:

{
  "board": {
    "width": 101,
    "height": 101
  },
  "destination": {
    "position": {
      "x": 50,
      "y": 50
    }
  },
  "player": {
    "id": "75bba7cd-a4c1-4b50-b0b5-6382c2822a25",
    "name": "Pero",
    "position": {
      "x": 0,
      "y": 10
    },
    "move_count": 0,
    "move_attempt_count": 0
  }
}

Player Move

• POST /player/{id}/move/left
• POST /player/{id}/move/right
• POST /player/{id}/move/up
• POST /player/{id}/move/down

Request body: None

Response code:

• 200 OK: Destination reached
• 201 Created: Player moved successfully
• 403 Forbidden: Player id not valid, probably timeout
• 409 Conflict: Invalid move, obstacle or position out of board
• 422 Unprocessable Content: Validation error

Response body:

{
  "player": {
    "id": "string",
    "name": "Pero",
    "position": {
      "x": 50,
      "y": 50
    },
    "move_count": 10,
    "move_attempt_count": 12
  }
}

Get Player Info

GET /player/{{id}}

Request body: None

Response body:

{
  "player": {
    "id": "string",
    "name": "Pero",
    "position": {
      "x": 50,
      "y": 50
    },
    "move_count": 10,
    "move_attempt_count": 12
  }
}

Get Game Info

GET /game

Response body:

{
  "playerId": "75bba7cd-a4c1-4b50-b0b5-6382c2822a25",
  "board": {
    "width": 101,
    "height": 101
  },
  "destinationPosition": {
    "x": 50,
    "y": 50
  },
  "playerPosition": {
    "x": 0,
    "y": 10
  }
}

WebSockets

WS Data format

• json

{
  "message": message_type,
  "data": ...
}

Game state structure

Message: game_dump

Data:

{
  "board": {
    "width": 10,
    "height": 10
  },
  "destination": {
    "position": {
      "x": 5,
      "y": 5
    }
  },
  "players": [
    {
      "id": "test-player-pero",
      "name": "Pero",
      "active": true,
      "position": {
        "x": 3,
        "y": 3
      },
      "move_count": 0,
      "move_attempt_count": 0,
      "state": "CREATED"
    },
    {
      "id": "test-player-mirko",
      "name": "Mirko",
      "active": true,
      "position": {
        "x": 4,
        "y": 4
      },
      "move_count": 0,
      "move_attempt_count": 0,
      "state": "CREATED"
    }
  ],
  "layers": [
    {
      "name": "obstacles",
      "objects": [
        {
          "type": "OBSTACLE",
          "position": {
            "x": 0,
            "y": 6
          }
        },
        {
          "type": "OBSTACLE",
          "position": {
            "x": 5,
            "y": 1
          }
        },
        {
          "type": "OBSTACLE",
          "position": {
            "x": 1,
            "y": 6
          }
        }
      ]
    },
    {
      "name": "destination",
      "objects": [
        {
          "type": "DESTINATION",
          "position": {
            "x": 5,
            "y": 5
          }
        }
      ]
    },
    {
      "name": "players",
      "objects": [
        {
          "type": "PLAYER",
          "position": {
            "x": 3,
            "y": 3
          }
        },
        {
          "type": "PLAYER",
          "position": {
            "x": 4,
            "y": 4
          }
        }
      ]
    }
  ]
}

Product purchase start

Message: product_purchase_start

Data:

{
  "player": {
    "id": "test-player-pero",
    "name": "Pero",
    "active": true,
    "position": {
      "x": 10,
      "y": 10
    },
    "move_count": 1,
    "move_attempt_count": 1,
    "state": "ON_DESTINATION"
  },
  "products": [
    {
      "name": "CocaCola",
      "id": "cocacola-id",
      "description": null
    },
    {
      "name": "Pepsi",
      "id": "pepsi-id",
      "description": null
    },
    {
      "name": "Fanta",
      "id": "fanta-id",
      "description": null
    },
    {
      "name": "Snickers",
      "id": "snickers-id",
      "description": null
    },
    {
      "name": "Mars",
      "id": "mars-id",
      "description": null
    },
    {
      "name": "Burek",
      "id": "burek-id",
      "description": null
    }
  ],
  "timeout": 5
}

Product purchase timer tick

Message: product_purchase_timer_tick

Data:

{
  "time_left": 4,
  "player": {
    "id": "test-player-pero",
    "name": "Pero",
    "active": true,
    "position": {
      "x": 10,
      "y": 10
    },
    "move_count": 1,
    "move_attempt_count": 1,
    "state": "ON_DESTINATION"
  }
}

Product purchase timer done

Message: product_purchase_done

Data:

{
  "player": {
    "id": "test-player-pero",
    "name": "Pero",
    "active": true,
    "position": {
      "x": 10,
      "y": 10
    },
    "move_count": 1,
    "move_attempt_count": 1,
    "state": "ON_DESTINATION"
  },
  "product": {
    "name": "CocaCola",
    "id": "cocacola-id",
    "description": null
  }
}

If product selection timeout occured, product will be null.

Servers

• Frontend
• API
• API Docs
• FairHopper
• FairHopper SDK
• Websockets: wss://fairhopper.mjerenja.com/ws