PlayYourTurn.com Uploader Tool
Table of contents
Download the Uploader
You can download tha latest version of the uploader, version 1.03, by clicking here.
Introduction to the Uploader
In order for PlayYourTurn.com to keep your Pitboss game of Civilization IV up to date, it needs to communicate with the Pitboss application. The way the site does this is through the use of an “Updater” tool, a program that is run on the same machine as Pitboss application.
What the application does is called “screen scraping”. It sits there, minimized in the system tray, and reads the text in the Pitboss window. It will see things like “Who: Joe” and “Score: 50″, record these things for every player, and keep records. Whenever something changes, for example a player’s score, an “event” is genrated by the tool, and sent to the PlayYourTurn.com server. It is then parsed / cleaned up, stored in the database, and is then viewable to users in the event list of the “View Game” page.
If you haven’t picked this up yet, I’ll explicitly state it here: The uploader only runs on the Pitboss server’s machine. Players of a game have no reason to download this tool.
Using the Uploader
Using the uploader is pretty simple. Since you’re running a Pitboss server and administering a game, you probably have some level of computer literacy.
Follow these simple steps to start using the uploader:
- Download the uploader. Remember, this tool is in early beta, so check back for newer versions! Generally I’ll add news posts whenever a major fix comes out.
- Create a new game on the PlayYourTurn.com website. Give the game a name, and fill in all the fields for the game settings. NOTE: The “admin password” for the game is in no way connected to Civilization or Pitboss. This is simply a password that allows you to edit the game settings later, and you will need to enter this in the uploader tool. Don’t forget it.
- DO NOT CLICK AHEAD TO THE NEXT PAGE. The PlayYourTurn.com new game page will give you a game ID. This is a unique number that represents your game in our database, and is important to remember. If you forget, you can always manually find the game in the “View My Games” or “List Games” pages. The uploader tool will need this number, so keep it handy!
- Start Pitboss. You can create a new game, or load a previous one, but PlayYourTurn.com will only have events that were generated while it was running. Jump through all the hoops, set all the options, and start the game. When you see the Pitboss window listing all of the players, you are ready to proceed to the next step.
- Start the uploader.
- If this is your first time running the uploader, it will pop up a file locator dialog box. Navigate to the Pitboss executable file. The uploader needs to know where this file is in order to run properly, and it makes a guess as to where it is, based on the default install location.
- Put in your game ID and admin password into the fields in the installer. NOTE: be very careful here, as the uploader tool does not currently tell you if you’ve input the wrong information. The uploader will only work if the game ID and password match what you received and set during the creation of the new game.
- Press the “Start the Uploader” button. The text fields will gray out, and the uploader will start doing it’s work. You can stop the uploader at any time by pressing this same button again.
- Minimize the uploader tool, sending it to the System Tray, and forget about it. It will work in the background.
- Wait a few seconds to ensure that the uploader’s initialization is complete.
- Back on the PlayYourTurn.com website, click on the link at the bottom of the new game page to set up the players for your game.
- You need to select the nation, leader, and join password for every player in the game. The website does it’s best to guess the nation and leader based on the leader name it can see in Pitboss, but if you’re starting with a game that already has human players (and therefore custom leader names), you’ll have to manually add these. The leader option can be left blank, but the nation field must be filled in, for various technical reasons. The “join password” is the password that a player needs to “claim” that civilization, and is in no way related to any passwords in Pitboss or Civilization IV. You can leave this blank to allow anyone to “claim” any civilization.
You’re done! Your game has been created, and all the players have been added! You should see your game page, and the URL for your game page should appear in your address bar. You can give this URL to everyone in your game, and they can claim their players / civilizations, and start viewing events.
Uploader Tool Changelog
Changes in 1.05
- Multiple Pitboss Server Support! Select any of the running games from the drop-down list.
- The “Refresh” button will gray out when the Uploader Tool is enabled, ot prevent the game name from getting switched.
- The Tray Icon for the Uploader Tool will now show the name of the game being run. Hover over it to see.
Changes in 1.03
- The Uploader will now wait one more “scrape cycle” before delivering “A New Turn Has Begun” events. This will keep the event order consistent for larger games.
Changes in 1.02
- The Uploader will now update the turn timer once every 5 minutes, because of issues with Pitboss’s clock.
Changes in 1.01
- Fixed the Turn Timer parser, it should now send events for all turn timer changes, and update the turn timer.
- Modified the startup routine to update the Turn Timer when the tool first starts.
Changes in 1.00
- This release was a complete overhaul of the majority of the code for the uploader, which should resolve many issues.
- Performance enhancements:
- Rewrote parsing method, completes much quicker.
- Tool does not “block” on the parsing method, allowing UI interaction.
- Tool is no longer “sluggish”, and slow to respond.
- Turn timer code rewritten. It will now always properly update.
- “New Turn” events will now always come after the corresponding “Ended Turn” event.
- “New Turn” events are parsed differently, and will more accurately clear the “Finished Turn” check marks in the player information.
- Player information will update automatically whenever the Uploader Tool connects. This will help keep the “Finished Turn” check marks accurate when the uploader has to be restarted.
- The Uploader Tool will now show it’s version number and current game year when it connects.
- Scores will now show the old and new scores, for example, “Score changed from 33 to 40″. This is only available for score changes made with the new tool. Old scores will be unchanged.
- Player name changes will now show the old and new names, for example “Name changed from Joe to Joseph”. This is only available for name changes made with the new tool. Old name changes will be unchanged.
- Better handling for “Converted to AI” and “Converted to Human” events.
Changes in 0.10
- Added code that has the Uploader Tool send the remaining turn timer for every “Finished Turn” and “New Turn” events.
Changes in 0.09
- Fixed an issue with the lost window counter. It was not being reset properly in some scenarios.
- Increased the default number of window losses from 5 to 10. You can still change this in the ini file.
Changes in 0.08
- Greatly reduced logging. “full text” screen scrapes are no longer logged. The only things that will be logged are events and errors. this should make the log files significantly smaller.
Changes in 0.07
- Added code to gradefully handle “partial screen scrapes” and “temporary losses” of the Pitboss window. The Uploader Tool will automatically retry to find the Pitboss window and get a new screen scrape. If the Uploader Tool hits the maximum number of errors in a row, it will disable itself, and pop up a message box letting the admin know that the window could not be found reliably.
- Added an INI parameter “maxWindowLosses”, to configure the maximum number of retries, as listed above. This defaults to 5 if not specified. Admins will have to manually add this value under the “General” section.
- Reduced logging. The logs are still quite large, as the “full text” screen scrapes are printed in the log. Depending on how this new updater performs in the next few days, a future version could remove these, and have significantly reduced logging.
Changes in 0.06
- Several fixes to the parsing code that was causing Array Out of Bounds errors when the Pitboss window was minimized, or obscured by other windows.
- Fixed the way the Player Number was retrieved from the Pitboss UI. This should resolve the errors where games were receiving spurious player rename events.
- Added popup messages that will alert the admin when The Uploader has lost track of the Pitboss menu. If you see this error, please report it to me and let me know what happened just prior to receiving it, and if you can reproduce it.
- Added logging. You can enable this by going to File > Enable Logging. The logging is pretty extensive, and I do not recommend using it unless you are reproducing an issue. These logs will be helpful in troubleshooting errors.
Changes in 0.05
- Logging introduced, but was always on, with no toggle.
- This was not publically available, and shared to preferred beta testers only.
Changes in 0.04
- Several changes to the parser to reduce the number of Array Out of Bounds errors. Some still remain.
- Performance enhancements.
- Tool now properly reports “Changed to AI” and “Changed to Human” events from Pitboss.
Changes in 0.03
- First public release.
- UI was added to the tool, previously being command line only.
- Added code to store info into an INI file.