jasonhemann/Fish

The Fish Competition

The repository is a fully functioning game framework. It is both an educational and a research project. The code is derived from my Fall 2020 course called "Software Development". The "trace" branch is a first exploration of trace contracts "in the wild."

The code is still a work-in-progress.

TODO

closing the windows should shut down things
move the trace contract material into a branch.
develop a trace contract for the tournament managers.
- observer: pause time

Ideas

the tournament observer for xtest is primtive and uses too much space for large tournaments
add names to players and use those for observers and for reporting outcomes
- use the short strings for sign up
- make them unique

Install

If you wish to inspect the code easily and experiment with it, clone the repo and then install it:

$ git clone git@github.com:mfelleisen/Fish.git
$ cd Fish 
$ raco pkg install 
$ raco doc Fish

This last command will search for the docs of the newly installed "Fish Project" collection. The results are displayed in a new tab of your default browser. Follow the link to the project and peruse the documentation, including a version of this README file.

The package depends on several other repos, including Cameron Moy's trace contracts. The pkg install will download and install those.

The Idea

"Hey, that's my fish" (Bambus Spielverlag) is a board game for players eight and older. It has won several awards and nominations, including the Lucca Games Best Family Game nominee.

This repository is a framework for programming competitive "Fish" players, a variant of "Hey, that's my fish". Participants will design automated players that run on their desktops and connect to a (remote) "Fish" server. This server will run "knock out" tournaments of games consisting of two to four players each. Any misbehavior of a player---non-responsiveness due to bugs or cheating---results in immediate termination. So the competition is not just about writing great strategies but also delivering robust code.

 +----------------------------+                           +----------------------------+
 | Client                     |                           | Server                     |
 +----------------------------+                           +----------------------------+
 | player mechanism           |                           | tournament manager         |
 | strategy                   | relies on      relies on  | referees                   |
 | GUI mechanism for people?  |-----------+  +------------| observers                  |
 +----------------------------+           |  |            +----------------------------+
                                          |  |
                                          v  v
                 +---------------------------------------------------------+
                 | the common ontology of Clients and Server               |
                 +---------------------------------------------------------+
                 | player interface and protocols                          |
                 | the rules of the game, expressed as complete game trees |
                 | formulated in terms of game states                      |
                 | which are made up of boards, fish, and penguins         |
                 +---------------------------------------------------------+

The Basic Idea

The "Fish" board is an arrangement of hexagon-shaped tiles, which display some number of fish. During the start-up phase, players place their penguins on these tiles; a tile cannot hold more than one penguin. Once the players have placed their penguins, they move their penguins in straight, uninterrupted lines across the board. The lines are defined by six directions that each tile represents. When a penguin leaves a tile, the fish on the tile become the player's property and the tile is removed from the board. Given this context, an uninterrupted line is one that contains no holes and no tiles occupied by a penguin. The player with the most fish wins the game; the game permits n-fold ties.

I intend to change aspects of the game to which developers must react with changes to their code base.

What You Can Do

Without any coding, you can use this repo to

observe "AI" games, or
play interactive games.

Using Racket, you can use this repo to quickly

try out new game strategies
develop different forms of players.

Using any programming language, you can use this repo to

test remote clients ("AI players") locally
stage local and/or remote tournaments.

The communication between server and clients is TCP-based, using JSON-formatted messages.

The Common Ontology

For participants to connect to the server, they need to understand the interaction protocol, which specify the sequence of remote calls and their signatures. While each message is just a piece JSON data, the signatures interpret these pieces of data in the context of the game.

Since even a detailed interpretation may leave questions about their meaning with respect to the rules of the game. the repository's Common directory publishes the code that interprets the remote calls with respect to the server and the sample player in this repository.

Organization

The repo consists of the following folders, with the links pointing to additinal "read me" files:

directory	purpose
Admin	the logical tournament manager, referee, and game observer (todo)
Common	the common ontology: understanding the communication between game server and client player
GUI	a game view and its supporting components
Lib	functionality that should probably exist in Racket's libraries
Player	the logical sample player, both human and automated strategies
Remote	the remote proxy substitutes for the tournament manager, referee, and player
Resources	pictures
Scripts	scripts for observing games, playing games, testing remote players, and running tournaments
scribblings	the source of the scribble documentation

jasonhemann / Fish