TBH Tool Repository


Identify raid targets and trigger placements.

Spyglass processes the NationStates daily dump to generate a spreadsheet that can be used to identify targets for a raid and predict their update times. It is commonly used for the purpose of setting manual triggers, which can predict the true update time of a region with high accuracy. A Spyglass thread is maintained in the NationStates Technical forum here, and a Dispatch is available here.


To run from the source code, Spyglass requires Python 3.x, and has the ability to self-install dependancies. A Windows build (executable program file, .exe) and Mac executable (currently for Intel Macs, one for M1 macs coming in soon!) are provided for users who cannot configure Python on their computers, or who do not wish to do so.

To run Spyglass, double-click on Spyglass.py (Spyglass.exe or Spyglass if you are using the executable version) and follow the instructions displayed in the resulting window. You may have to bypass a Windows warning in order to run this script. Spyglass will then generate an Excel sheet in the same folder it was ran from.

If you are unable to run Spyglass on your computer, but are able to use Google Chrome with a signed-in Google account, you may instead use Spyglass Online here. Spyglass Online uses Google Colaboratory to execute the program online and generate an Excel spreadsheet for download. After opening this link, first go to file (at the top) and then Save a copy in Drive to save a copy for yourself, in your own Google Drive. After doing that, follow the provided instructions from top to bottom.


Important: Versions 2.x of Spyglass are recommended, and only v1.4.4 or newer are approved for TBH usage, period. Older releases contain a security vulnerability.


Regions are color-coded and marked in columns A and B based on their value as targets. These markers can be used with Excel’s built in filter function to quickly identify targets.

  • GREEN — Region is founderless and passwordless
  • YELLOW — Region has an executive WA delegate and is passwordless
  • RED — Region has non-executive WA delegate and is passwordless
  • ~ — Region can be tagged
  • * — Region has non-executive WA delegate

Additionally, regions with zero World Assembly endorsements are color-coded red in column H.

Spyglass also lists a region’s embassies and the first 140 characters from their WFE in columns I and J. These columns can be filtered to quickly identify regions that are not yet or currently tagged.

Complete documentation of how to read a Spyglass sheet can also be found here.

Supported Terminal Arguments

If you need Spyglass to run unattended (e.g. through a scheduled task or Cron job), you can use the following arguments to control its behavior, in the form .\Spyglass-cli.py [-h] [-n NATION] [-o OUTFILE] [-s | -l PATH]. Documentation for this use is available here.

  • -h Show this help message and exit.
  • -n NATION Specify Nation to identify user by. In order to comply with NationStates API rules, this must be the user’s nation. Use underscores instead of spaces.
  • -o OUTFILE Specify path to write the generated timesheet in XLSX format to.
  • -s Suppress creating a debug log file. Log files are written to the current working directory.
  • -l PATH Write debug log to specified path.
  • -m Generate a minimized sheet without WFEs and embassies.

If run without arguments, Spyglass runs in interactive mode and outputs to the working directory.

(c) 2022 The Black Hawks.