yoweb-scrape.txt

   1                 yoweb-scrape
   2                 ------------
   3
   4 This program can:
   5   * Fetch information for crew and pirates from yoweb
   6   * Display tables of puzzle standings
   7   * Keep track of who is on board a vessel
   8
   9 Putting this all together, it can be used to show a table of who's
  10 good at what when you're running a pillage.
  11
  12 You run it roughly like this:
  13   ./yoweb-scrape ship-aid ~/yohoho/Aristarchus_midnight_chat-log-iwj
  14 It has various other modes - see the usage message.
  15
  16
  17 Key features:
  18
  19  * Tracks boarding and departure of pirates and shows a table
  20    of currently-aboard pirates with their relevant puzzle standings in
  21    a compressed format.
  22
  23  * Shows time and nature their last interaction with you as XO
  24    (abandoning stations, being given orders) and where and when their
  25    last to-you-visible chat was.
  26
  27  * Remembers whether you have ever given the pirate an order to gun
  28    since they boarded.
  29
  30  * Caches and severely rate-limits fetches from yoweb to avoid
  31    overloading the Three Rings servers.  In ship-aid mode, will
  32    display twirling batons while you wait for data, so that crew
  33    on board info remains correct.
  34
  35  * Can sort pirates by their skills in the key duty puzzles.  Press
  36    a single keystroke to sort by:
  37       s: sailing                   b: bilging
  38       c: carpentry                 g: gunning
  39       n: navigation (duty nav)     t: treasure haul
  40       d: driving (battle nav)      a: sort by pirate name
  41    It will prefer to list near the top pirates whose other skills
  42    are weaker.  This functionality is disabled if stdin is not a tty.
  43    Other keystrokes:
  44       q: quit the program (^C works too)
  45
  46 Things you need to know:
  47
  48  * Please don't leave it running if you're not in charge.  If everyone
  49    runs yoweb-scrape all the time it will produce precisely the load
  50    on the yoweb servers that we want to avoid.
  51
  52  * You must enable the YPP client chat log.  It is disabled by
  53    default.  This can be found in the client in the options panel
  54    under `Ye'.  Contrary to what the client UI seems to suggest, the
  55    filename you specify there is not used directly: information about
  56    your pirate name and ocean are added by the client, which is good
  57    because yoweb-scrape can dig it out again.
  58
  59  * If you leave and then reboard a vessel, the list of pirates on
  60    board may be wrong.  This is because the chat log doesn't contain
  61    information about who's on board the ship when you reboard it.
  62
  63    yoweb-scrape assumes that, unless it is told otherwise (or notices
  64    for itself), the set of pirates on board doesn't change while
  65    you're off the ship (unless you're away for more than an hour, in
  66    which case it assumes the ship is empty when you return to it).
  67
  68    You can tell it otherwise with specially formatted chat messages.
  69    Messages sent or received to officer chat, and messages sent (not
  70    received) in private message, are scanned for special `commands' to
  71    yoweb-scrape.  (So you can have an officer on board the ship keep
  72    your yoweb-scrape up to date if you like.)
  73
  74    The commands are of the following format:
  75          /a <pirate>...                 /d <pirate>...
  76          /a <ship-spec>: <pirate>...    /d <ship-spec>: <pirate>...
  77    And also:
  78          /j <pirate>
  79    which simulates "<pirate> applied for the posted job".
  80
  81    <ship-spec> can be the full name of the ship, or or only the second
  82    word (the noun).  It can also be a pattern, where `*' matches any
  83    (nonempty) series of characters including spaces, and which counts
  84    if it matches either the whole ship name or just the noun.
  85
  86    For example:
  87          /a haddock: aiah
  88          /d aiah
  89          /a smart sunfish: copperkatie
  90          /a s* sunfish: anaplian
  91    These are actually sent by typing in the chat box things like:
  92          /o /d plonker
  93          /off /a hypiscles
  94    since other formulations interpret the scraper command as a YPP
  95    chat command.  This is deliberate and makes it harder to invoke by
  96    mistake.
  97
  98    If you don't specify a ship, it will assume that it's the ship that
  99    you (or the officer speaking) are on board.  (For full details of
 100    the matching algorithm, see below.)  If more than one ship is being
 101    managed with yoweb-scrape, any user who wishes to issue these
 102    commands should say:
 103          /a relevant fish: executiveofficer
 104    so that everyone else's yoweb-scrape knows which ship they're on
 105    and thus which ship their /a commands refer to.
 106
 107  * For the ship duty puzzle display, and for sorting pirates by
 108    skill, we take the best of Sailing and Rigging.
 109
 110 Other things to mention:
 111
 112  * There are some things which don't reliably appear in the chat log,
 113    for example: when you disembark, and when a pirate leaves a duty
 114    station.  That can mean that yoweb-scrape isn't always as up to
 115    date as you would like.  You'll just have to tell it manually.
 116
 117  * The `tabulate details of my whole crew' mode takes a long time
 118    to run.  This is normal; it's trying to spread the load on yoweb
 119    (perhaps excessively so).
 120
 121  * I haven't decided on a final copyright licence.  You may treat this
 122    version as GPLv3.
 123
 124  * The program will become confused when the clocks change,
 125    particularly when they go backwards.  This is due to the chat log
 126    containing timestamps in local time without a timezone.  If this
 127    bothers you, make everything be in UTC.  If it does get confused,
 128    you can fix it by logging off and logging on again (perhaps waiting
 129    until after the duplicated hour has passed) as that writes a new
 130    date record to the log and starts a new series of timestamps.
 131
 132  * It's Python so it may eat CPU and memory.
 133
 134  * You may need to install some python modules.  BeautifulSoup (yes,
 135    really!) is in the Debian package  python-beautifulsoup
 136
 137
 138 Some more details about tracking semantics:
 139
 140  * The program will notice that a pirate is on board if you give them
 141    a stationing order or they abandon a duty station (in circumstances
 142    where the game reports this in the log, which doesn't seem to be
 143    all the time), and from many of the other messages that occur.
 144
 145  * Matching for ship patterns in /a and /d commands picks the first
 146    of the following which applies and is not contradicted by any
 147    name or partial name specified in the command:
 148       - The ship we think the person telling us is on board
 149       - The ship we think we are on board
 150       - Any other ship we know about, if at least a something was
 151          specified, and provided that is not ambiguous
 152       - The specific ship name if it is completely specified,
 153          possibly recording this as a new ship
 154    <pirate> and <ship> can be in any case and will be converted to
 155    the proper mixed-case form automatically.