CMSC 471 -- Bohnanza Project Description -- Spring 2014

Please read this document carefully and start thinking NOW about your timeline for designing and implementing your player. The project requirements are subject to change and improvement. Good luck, and let the trading begin!

The Game of Bohnanza

The course project is to write a player for the game of Bohnanza. Bohnanza is a card game in which players have to collect sets of cards ("beans") and "harvest" their "bean fields" to earn "coins". There are quite a few constraints on what you must and must not "plant" into your bean fields. The twist is that players are allowed to trade cards with other players.

The official rules of Bohnanza can be downloaded from http://riograndegames.com/getFile.php?id=535 .

The Wikipedia page on Bohnanza (http://en.wikipedia.org/wiki/Bohnanza) has some more information about the games, including a list of spinoff games that are variations of the basic Bohnanza game.

You can play Bohnanza online at http://www.brettspielwelt.de/Spiele/Bohnanza/?nation=en .

Tournaments, Rule Deviations, and Player Requirements

Each tournament will consist of a series of three-player games, from which the winner will advance to the next playoff round. Depending on how fast the players turn out to be, we may be able to hold more rounds and take the overall performance (e.g., total gold coins) as a way to select which players will advance.

(Note that although the game is three players, we will not follow the standard Bohnanza rule of removing certain beans from the deck -- all beans will be used for all game rounds. Also, some game rounds may be two players, or possibly even four, if that seems as though it will work better in the actual tournament.)

I have not yet decided how to handle time limits -- I may impose an actual time limit (if any function takes longer than, say, 5 seconds to run, it is aborted and a default action is taken), or may just handle it by monitoring (if during game play, any player is clearly taking excessively long and delaying the tournament, that player would be disqualified). We can discuss how that should be handled as teams start to produce actual players.

Project Requirements and Grading

There are four three graded components of the project: (1) a project design, (2) your implemented system, (3) a group project report, and (4) your performance in the class tournament. Note that you will be primarily graded on the thoughtfulness and clarity of your design and presentation, and not primarily on your algorithm's performance. The reason for this is that it gives you the freedom to try a risky approach that is interesting from a design perspective but might not work very well. An approach that doesn't work very well, and is also naive, trivial, or not well motivated will receive a correspondingly trivial grade.

You should NOT just hack something together -- this is an AI class! You should think about the strategies you want to implement; what AI methods would be appropriate for such strategies; and how those AI methods can be adapted for this purpose.

Project Design (5%). You must submit a project design (via email to Dr. desJardins) by Thursday, March 27 (the usual late penalties apply). You may just send this in the body of an email, or you may attach a formatted (Word or PDF) file. Only one project design should be submitted per group.

Your project design should contain:

• The names of your team members.
• Your team name and package name (team name can be anything; package name should be a legal Lisp symbol -- no spaces and so forth).
• A short (less than one page) description of your planting strategies for Phase I, written in clear and understandable English.
• A corresponding Lisp design (main functions (including the three required functions), inputs and outputs for each function, and pseudocode for the behavior of the function). At this point you should have thought about what helper functions and computations you will need to perform in order to implement your planned strategies, and you should have corresponding Lisp functions to do that work.
• A short (less than one page) description of your trading strategies for Phase II, written in clear and understandable English. The Lisp interface for that phase has not yet been designed, but the interface will be informed by your intended designs, so you should give this some thought. Your trader will have to propose a set of trades (ranked in order of preference, and possibly with corresponding utility scores), and may have to evaluate a set of proposed trades from other agents (in which case you would have to rank-order those trades (eliminating any unacceptable trades) and possibly assign utility scores).

Implemented Lisp-based Bohnanza Players (40%). Your implementation will be graded on correctness (i.e., did you correctly implement the solution that you described in your paper), as well as design (generality, clarity, and elegance) and readability (indentation, comments, modularity, etc.) The Phase I (non-trading) and Phase II (trading) players will each be worth half of the implementation grade.

You must have a working Bohnanza player by the date of each tournament dry run (Tuesday, April 15 for Phase I and Thursday, May 8 for Phase II). If you do not submit a working player into the dry run, you will receive a 5-point penalty on that implementation grade (out of a possible 100 points). (Players that "almost work" but require some manual repair to get them working may receive a partial penalty.) You may change your code between the dry run and the tournament, but not your team/package name, since we will set up the infrastructure for running the tournament during that time window. The in-class tournaments will be held on Tuesday, April 22 (Phase I) and Tuesday, May 13 (Phase II).

Project Report (45%). Each team must submit a project report describing your approach, your experience in designing and implementing the approach, and the performance of your system. You only need to submit one report, which should cover both your Phase I and Phase II players. I would expect these reports to be somewhere in the 5-10 page range, but there is no minimum or maximum if you include all of the required information. Your report should include the following:

1. A discussion of your Bohnanza game strategies and how you developed them (by playing the game, by reading articles online, by talking about them hypothetically, by trying things out and experimenting with the code...) This discussion should have a section on your Phase I player and a separate section on your Phase II player, and can discuss what changes you made in between -- both in the basic strategy and in the trading strategy that you added for Phase II.
2. A discussion of how your implemented system draws on ideas from the AI literature. This discussion should be focused on material and concepts that we covered in class. If you do some additional outside reading from the AI literature, you should run that past me first to be sure that I would consider it to be appropriate to discuss in this section (i.e., that it is sufficiently "AI-ish"). You should cite references for the AI concepts you mention (it's OK to cite the textbook, but you should include specific section numbers). It's completely appropriate for this section to discuss methods that you would/could use for a "better Bohnanza player" that you weren't able to implement during the semester! You may have ended up with something relatively simple, but had some ambitious/interesting ideas for using planning methods or other techniques that you weren't able to get working within the scope of the semester. You should talk about those ideas here.
3. Experimental evaluation of your system. You can do this by having your player play against itself, by setting up something where you (i.e., a human player(s)) can play against your AI system, by working with another team to run your players against each other, and/or by analyzing the actual tournament play). This section should discuss what worked well, and not so well, about your player's strategies; and whether the player behaves as expected. Both qualitative/anecdotal and quantitative data should be included in this discussion.

Class Tournament (10%). As with the code, half of the tournament grade will be for Phase I, and half for Phase II. The tournament performance grade will be based on whether your player successfully runs (i.e., you have a working system at the time of the Phase I and Phase II tournaments -- about half of the credit), and on how well it actually performs in the tournament (i.e., how many coins your player earned (relative to other players) and whether it advanced to the next stage of play by winning -- about half of the credit). (Note that the latter grade, about 5% of your total project grade, is the only part of your project grade that is directly tied to performance (coins earned and win ratio). So it is important to have a player that plays well, but it's even more important to have a strong justification and clear design for your player.)

Lisp Infrastructure

• bohnanza.lisp, a Lisp-based Bohnanza game engine.
• p1-bohnanza.lisp, a naive test player.
• p2-bohnanza.lisp, an even more naive/stupid test player than P1.

As you can see in the test player files, you'll need to create a team name and place your code into a package with that name, in order for everything to run correctly. (A package is just a name space so that different teams' players don't step on each other by using the same names for their functions.)

For Phase I, you must implement the three required functions, as illustrated in the test player files: PLANT-CARD(), OPTIONALLY-PLANT-CARD(), and HANDLE-FACE-UP-CARDS(). For Phase II, there will be one or more additional required functions to handle the trading process; I have not yet designed those functions, but will be able to give you more information after spring break.

Note that you will probably want to use Lisp's optimizing compiler to make your code run faster for the actual tournament. I will develop some naming conventions for files and players so that the tournament runs smoothly; details to be announced later. All tournament rounds will be run on the gl machines, so you should be certain to test your code there even if you develop it on a different machine.

When submitting code for the dry runs and tournaments, you will need to let us know (by email to Dr. desJardins and Lianjie) what userid you have submitted your code under, the name of your main file, and what package name you are using. You should submit your code on gl using the "submit" command with the "dryrun1", "dryrun2", "tourn1", or "tourn2" projects, depending on the submission. You have one main file, which may load other files (in the same directory) as needed. To load any other files, you should use:

(load (make-pathname :directory (pathname-directory *load-pathname*) :name "FILE"))

You may find that you have some good ideas about utility functions for printing tournament results, trace your player's behavior, analyze the game state, or do other useful things. You may think that some of this code could be useful for other students. That's great! Please feel free to send any code that you develop that might be generally useful to me; I will vet it against the academic integrity policy (no sharing of solutions across teams...) and post it into a code repository.