= Surrey Rubyists Coding Competition: Hangman

== Results

The games were played on 28th June 2011. The winner was:

threedaymonk (normal)

You can see the full results in knockout.xls. The teams had 2 hours to create their player, why not create your own player and see how you stack up!s

== Player Class

All you need to do is create a single file and implement a new hangman player class with the below methods.

You should place your player file inside the "players" folder within the hangman game folder.

Your class name must end with "Player" for it to be loaded by the game framework! Please try to make your class and file name unique in some way (with your team name for example) to avoid clashes with other players.

./players/my_awesome_super_duper_hangman_player.rb

class MyAwesomeSuperDuperHangmanPlayer def name

Return the name of your player (string)

end

def new_game(dictionary)
  # A new game has started, do any clean up from a previous game and initialise for this one. 
  # The dictionary passed is the full set of words that the phrase is selected from and is passed in as a string array: ["apple", "bear", "cat"]
end

def take_turn(pattern)
  # It's your turn. Return a guess (string) which can either be a letter, word or whole phrase.
  # The current state of your pattern is passed in the format "s_rr__/r____s_s" 
  # The pattern is made up from: underscore = missing letter, forward slash = space, letter = correctly placed
end

# If your player needs supporting classes, you can nest them inside your player class.
# This is to keep things simple for the player loader and also to avoid clashes between players.
class MySupportingClass
  # ...
end

end

== Running the game

To run the game, open a terminal/command prompt and cd to the hangman folder. Then type the following:

ruby app.rb

This will start up the game and load the valid players from the players folder. You can then select two players and start a new game. You can test your player as you develop it with the game runner. There are two sample players already in the players folder for you to play against while developing your player.

== Guessing

When you return your guess from the +take_turn+ method, you can return a single character, a single word (not multiple words) or the whole phrase. If your guess is incorrect then you are one step closer to death! If however, your guess is correct then it is inserted into your current pattern (replacing the underscores) which is passed into your +take_turn+ method next time round. Your guesses are isolated from your opponent. Here are some examples:

=== Single character guesses

1. Given the phrase "toy/story"
2. The pattern "_/___" is passed into take_turn
3. If take_turn returns the single character string "o"
4. The next time take_turn is called, it is passed "o/o"
5. If take_turn returns "z", the next call to take_turn is passed "o/o"

=== Word guesses

1. Given the phrase "toy/story"
2. The pattern "_/___" is passed into take_turn
3. If take_turn returns the word string "toy"
4. The next time taketurn is called, it is passed "toy/____"
5. Notice that only the word is replaced, not all letters in that word that appear elsewhere (t, o and y in the above example).

=== Whole phrase guesses

1. Given the phrase "toy/story"
2. The pattern "_/___" is passed into take_turn
3. If take_turn returns the phrase string "toy/story" (note to pass forward slashes to separate words)
4. Then you will win the game (provided your opponent doesn't guess the whole phrase at the same time).

=== Invalid guesses

1. Returning nil is an invalid guess
2. Returning a non-string instance is an invalid guess
3. Returning an empty string is an invalid guess
4. Returning multiple words that are not the whole phrase is an invalid guess.

All invalid guesses will count as an incorrect guess and will add a section to your gallows.

== Sample Players

There are two sample players for you to play against and see how a very basic player works:

=== StupidDemoPlayer

This player will randomly select a letter from the alphabet and return it as it's guess. It will track it's guesses and will not guess the same letter twice in a game.

=== HumanDemoPlayer

This player has no AI, it just allows a human player to enter each guess for it.

== Rules

1. Matches between players will be the best of 3 games.
2. The number of words that make up the missing phrase will increase through the rounds.
3. If your player throws an exception, you lose the game.
4. You cannot try to gain or influence information held in the game runner app or other players.
5. Matches will be 1v1. The winner is the one who finds the missing phrase first or the one that survives longer.
6. Both players will be able to take the same number of turns, therefore no advantage is gained from going first.
7. Draws are possible. In the event of 3 out of 3 draws we will continue into sudden death until one player wins (or we get bored, where we will split up the players).
8. Each turn you must make a guess. Any invalid guess (nil, empty, non-string) will result in an incorrect guess.
9. If the game runner crashes, then a rematch will be played.
10. Your player must decide the guess to make (no human or other system interaction is allowed during the game).

== Good Luck!

You will have about 2 hours to complete your player before the games start. If you have any questions just shout!

== Feedback

I'd love to hear your feedback on the event itself, and also the game code. I'm always looking to improve (even minor things) so feel free to let me know. You can get me on twitter @andypike, or post on Surrey Rubyists Group: http://groups.google.com/group/surrey-rubyists.

Further details of Surrey Rubyists can be found on the website: http://surreyrubyists.tumblr.com/