home.md

+# The Resistance Framework
+
+## Game Stucture
+
+```mermaid
+graph TD;
+  Selection-->Voting;
+  Voting-->Mission;
+  Voting-->Announcing;
+  Mission-->Announcing;
+  Announcing-->Preparation;
+  Announcing-->Selection;
+  Preparation-->Selection;
+```
+
+Between each phase, the game checks if any of the following has occoured, if it
+has then the game is terminated and the game end callback is triggered:
+
+* 3 wins for either team (causing a win overall)
+* 5 missions have been played
+* The team fails to reach consensus on a vote (5 failed votes in a row)
+
+### Selection
+Pick the mission leader and ask the leader for a team selection.
+
+The mission leader's ```select(players, count)``` method is called. The leader returns a list of player objects that corrispond to the players the leader wishes to send on the mission. 
+
+When the leader has made a selection, the bots will be informed that a team has been selected using the `onTeamSelected(leader, team)` callback.
+
+The game will then move into the `voting` phase.
+
+### Voting Phase
+During the voting phase, each player is prompted to either vote for (return True) or against (return False) on the leader's selection.
+
+If a majority of the players vote for a team the game proceeds to the mission phase.
+If not, the leadership will pass to the next player in sequence and they will need to select a team.
+
+If the team fails to reach a majority 5 missions in a row, the game will auto-fail the game, causing a win for the spies. 
+
+### Mission Phase
+During the mission phase, if the team member is a resitance member, they will automaticlly get marked at successes. If the player is a spy, then the will be asked if they wish to fail the mission. This is done using the `sabotage()` callback. The agent should return true if they wish to fail the mission, or false if they don't want to fail it.
+
+If **any** player sabotages the mission, the mission will fail. This is consistant with the five player varient of the game.
+
+Once the mission has been resolved (success or fail) the agents will receive the ```onMissionComplete(sabotaged)``` - the value passed in represents the number of stabotages which have been resolved.
+
+#### End of the Game
+If the game hits the maximum number of missions, or the game becomes unwinnable for one of the teams, the game is terminated.
+The ```onGameComplete(wins, spies)``` callback is triggered.
+
+### Announcement Phase
+The players announce any suspictions they have about other players. This is a mapping of player to level of suspission. 
+
+Once these have been accounted for, they are shared with other players using ```onAnnouncement(source, suspissions)```. These can be used to share information between players.
+
+After the announcements are complete, the next leader is selected and the selection for the next mission begins.
+
+### Prepartion Phase
+At the end of the game, the players are told who the spies were, the ```onGameRevealed(players, spies)``` this lets the players know at the end of the game who was a spy - which can be used to reveal infomation.
+
+# Bot API
+
+## Actions
+* select - as a mission leader, select who to send on a mission
+* vote - as a player, decide if you want the players to on on the mission
+* sabotage - as a spy on the mission, decide if you want to sabotage the mission
+* announce - talk to other players about your suspissions
+
+### Helper Methods
+* Say - log/say something in global chat
+* others - list other players in the game
+
+## Callbacks
+* onGameRevealed - the game starts, this callback tells you who the players are and provides a list of spies
+* onMissionAttempt - callback that triggers before the selection phase
+* onTeamSelected - callback that triggers after a team has been selected, but before the mission takes place
+* onVoteComplete - callback for when the whole team has voted - revealing the votes
+* onMissionComplete - callback once the mission has been run - how many sabotages were there?
+* onMissionFailed - callback if the voting phase fails, **this happens if 5 votes fail**
+* onAnnouncement - callback informing the player of other people's suspissions
+* onMessage - callback when a player issues a free form chat message (probably shouldn't use this...)
+* onGameComplete - reveal the spies at the end of the game
+
+# Game State
+At all points in the game, the players have access to a shared state, ```self.game``` which holds useful infomation about the game state.
+
+* phase - the current phase of the game
+* turn - the mission number (1 to 5)
+* tries - the current attempt number (1 to 5)
+* wins - the current number of resistance wins (0 to 3)
+* losses - the current number of spy wins (0 to 3)
+* leader - the current mission leader
+* team - the currently selected team
+* players - all players currently in the game
+* votes - the current mission's votes
+* sabotages - the number of sabotages
+
+## Cheating
+You must not attempt to modify this object - if you attempt to modify the game state you will receive a mark of 0 for attempting to cheat.
\ No newline at end of file