Weewar-Spy v1.1

Based on weewar and weewar-ai, weewar-spy can be used to gather intel on your games.

Changes

I’m trying to keep the wiki up to date with the set of changes. Have a look there to see what each version brings to the table.

Requirements

• RubyGems
• sudo gem install xml-simple

Runtime-Specific

• Your Weewar API Key: http://weewar.com/apiToken
• sudo gem install mechanize

Development-Specific

• sudo gem install redgreen
• sudo gem install Shoulda
• sudo gem install mocha

Terminology

• Spy: Something you create and control in the gathering of game and/or user intel
• Director: You, the library user; implemented as spy.director
• Shadow, Reconnoiter, Infiltrate: Operations your spy can perform
• Debrief: How your spy reports its information

Plus the standard Weewar terminology.

Intelligence Gathered

The information returned by the Weewar API is impressive. However, combining a few elements gives you a richer picture of the games you’re playing. If Spy is employed at the beginning of a game then you can track the spending of your opponents. That last statement is not true; version 1.0 can not track spending.

Sample Output

This shows off the highlights of the debrief output. It has been truncated to aid in clarity.

Official Debrief: King of the Hill
----------------------------------------
For Director Mriffe, on: 19 Dec 2008; 02:04 EST
----------------------------------------
Round: 7; Rated: true; Pace: 3 days;
Current Player: zachart, playing for: 1 day 6 hours 24 minutes 34 seconds
--------------------
  Name: chickenorshrimp; Points: 1492; On: false
  Income: 200
	Total Units: 7; Troop Strength: 70; Efficiency: 100.00
	~~~~~~~~~~~~~~~~~~~~
	Extended Troop Info:
	Infantry => Units: 1; Strength: 10
		Heavy Troopers => Units: 1; Strength: 10
	Vehicles => Units: 6; Strength: 60
		Raiders => Units: 2; Strength: 20
		Tanks => Units: 2; Strength: 20
		Light Artillery => Units: 2; Strength: 20
	~~~~~~~~~~~~~~~~~~~~
	Total Terrains: 2; Bases: 2
--------------------
  Name: mriffe; Points: 1436; On: true
  Income: 200
	Total Units: 10; Troop Strength: 89; Efficiency: 89.00
	~~~~~~~~~~~~~~~~~~~~
	Extended Troop Info:
	Infantry => Units: 7; Strength: 70
		Troopers => Units: 7; Strength: 70
	Vehicles => Units: 3; Strength: 19
		Raiders => Units: 2; Strength: 12
		Tanks => Units: 1; Strength: 7
	~~~~~~~~~~~~~~~~~~~~
	Total Terrains: 2; Bases: 2
--------------------
* Name: zachart; Points: 1449; On: false
  Income: 200
	Total Units: 2; Troop Strength: 14; Efficiency: 70.00
	~~~~~~~~~~~~~~~~~~~~
	Extended Troop Info:
	Vehicles => Units: 2; Strength: 14
		Tanks => Units: 1; Strength: 9
		Heavy Artillery => Units: 1; Strength: 5
	~~~~~~~~~~~~~~~~~~~~
	Total Terrains: 2; Bases: 2
--------------------
x Name: c_Boi; State: finished; Result: votedout
========================================

The splat ( * ) is to quickly locate the current player.

Usage Examples

The idea is to create a Spy, controlled by you, to gather intel on the games you’re playing. There will be a number of examples and tests from which to learn how to Spy.

Currently Spy is employed upon command. It is up to you to execute a script and to capture the output.

Caution: Spy was tested and developed against a small number of games. If you have a large number of games I suggest infiltrating one game at a time. The example provided loops through the director’s games and may not be appropriate for users involved in a number of large games. YMMV

Creating A Spy

  class BlackSpy < WeewarSpy::Spy
    def initialize
      super(
        :server => 'server',   # usually 'weewar.com'
        :username => 'mriffe',
        :api_key => 'apiToken'
      )
    end
  end
  
  spy = BlackSpy.new

You have to create a subclass of WeewarSpy::Spy, passing in the target server (‘weewar.com’), your Weewar username, and your Weewar API Token.

Upon initialization, spy will retrieve your user information and the list of games in which you are playing.

  games = spy.games  # returns a hash of game ids to game names
  games = games.sort # sort the hash into an array of arrays. ex: [[1234, 'Thermonuclear War'], [5678, 'Fight to the Death']]
  game_id = games.first[0] # first element of the first game in the array is the id of that game (see above)

Infiltrating a Game

  # Takes a game id (integer).
  game = spy.infiltrate(game_id)

This operation is the most useful as it gathers the most information about a running game. From this operation you can gather information on another player’s troop strength, how many bases they have, and current income level.

Reconnoitering a Game

  # Takes a game id (integer).
  game = spy.reconnoiter(game_id)

This operation returns basic information about a game, such as number of players, round, type, etc. This is a lighter operation compared to ‘infiltrate’ but isn’t as useful. Note: spy.debrief expects an infiltrated game.

Shadowing a Player

  player = game.players.first.name # their Weewar username
  spy.shadow(player)

Shadowing a player allows you to gather information about their points, games they’re playing, and the players they prefer, etc. Note: You can not gather information about a player’s game that you are not playing. That is a constraint enforced by Weewar.

Debriefing a Game

  # Takes a WeewarSpy::Game instance.
  spy.debrief(game)

Debriefing currently only works with infiltrated games as it prepares a pseudo-report of the information gathered about a game. This operation will also be used often to review the information found during spying.

Issues and Enhancement Requests

This project is using No Kahuna to track tasks and issues. The project is located here: http://nokahuna.com/projects/3186

Authors and Contributors

Original by Mel Riffe; by extension the authors and contributors of ‘weewar’ and ‘weewar-ai’ are included.
29 October 2008