yarrg/web/upload

   1 <%doc>
   2
   3  This is part of the YARRG website.  YARRG is a tool and website
   4  for assisting players of Yohoho Puzzle Pirates.
   5
   6  Copyright (C) 2009 Ian Jackson <ijackson@chiark.greenend.org.uk>
   7  Copyright (C) 2009 Clare Boothby
   8
   9   YARRG's client code etc. is covered by the ordinary GNU GPL (v3 or later).
  10   The YARRG website is covered by the GNU Affero GPL v3 or later, which
  11    basically means that every installation of the website will let you
  12    download the source.
  13
  14  This program is free software: you can redistribute it and/or modify
  15  it under the terms of the GNU Affero General Public License as
  16  published by the Free Software Foundation, either version 3 of the
  17  License, or (at your option) any later version.
  18
  19  This program is distributed in the hope that it will be useful,
  20  but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  GNU Affero General Public License for more details.
  23
  24  You should have received a copy of the GNU Affero General Public License
  25  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  26
  27  Yohoho and Puzzle Pirates are probably trademarks of Three Rings and
  28  are used without permission.  This program is not endorsed or
  29  sponsored by Three Rings.
  30
  31
  32  This Mason component generates information about the uploader.
  33
  34
  35 </%doc>
  36 <& docshead &>
  37 <h1>Uploading to YARRG</h1>
  38 <p>
  39
  40 The YARRG system has two main parts: this website which maintains a
  41 searchable database of commodity prices, and an upload client (known
  42 as YARRG JPCTB), which screenscrapes the commodity data from the
  43 Puzzle Pirates game client and uploads it to the database.
  44
  45 <p>
  46
  47 You will need to upload data yourself if there is no data for your
  48 ocean or island, or the data that is there is too old.  You should
  49 also upload when preparing trade run, as market conditions change and
  50 you want a plan based on recent data.
  51
  52 <p>
  53
  54 The YARRG JPCTB upload client uploads both to YARRG and
  55 <a href="http://pctb.crabdance.com/">PCTB</a>.  It is intended to
  56 replace both the <a href="scraper">"yarrg"</a> and "PPAOCR" screenscrapers.
  57
  58 <h2>Instructions</h2>
  59
  60 First you must install YARRG JPCTB, following the instructions for
  61 your operating system, below.  This will not modify your Puzzle
  62 Pirates installation.  Instead, it provides you with a new way to run
  63 Puzzle Pirates which has an additional YARRG/PCTB Upload function.
  64
  65 <p>
  66
  67 To upload data, run the Puzzle Pirates client with JPCTB (as detailed
  68 below), log in normally, and visit a commodity trading screen (at a
  69 market, shoppe or vessel hold).  Select "All Commodities", and hit
  70 "Upload".
  71
  72 <p>
  73
  74 The JPCTB integration is done via fully supported Java Accessibility
  75 interfaces and without modifying the Puzzle Pirates client, and should
  76 not disturb the normal running of Puzzle Pirates.  However, please
  77 make sure that if your YPP client misbehaves in any way, you try
  78 running it in the vanilla way without JPCTB integration before asking
  79 for help.  In particular, if the JPCTB startup method does not work,
  80 but the vanilla client startup method does, report the problem to us,
  81 not to Three Rings.
  82
  83 <h3>Installing and running on Linux</h3>
  84
  85 Download
  86 <a href="http://www.greenend.org.uk/owen/free/jpctb.tar.gz">http://www.greenend.org.uk/owen/free/jpctb.tar.gz</a>
  87 and unpack it.  You run it from the command line.  Change
  88 to the directory where you unpacked the tarball above, and then run
  89 <pre>
  90 ./jpctb /path/to/yohoho/yohoho
  91 </pre>
  92 where <code>/path/to/yohoho/yohoho</code> is the location of the
  93 ordinary Puzzle Pirates startup script, which is normally
  94 <code>yohoho/yohoho</code> in your home directory.
  95
  96 <h3>Installing on Windows</h3>
  97
  98 Download
  99 <a href="http://www.greenend.org.uk/owen/free/jpctb-linkfarmer/jpctp-setup.exe">http://www.greenend.org.uk/owen/free/jpctb-linkfarmer/jpctp-setup.exe</a>
 100 and double-click on it.  It will either:
 101 <nl>
 102 <li>Just work, in which case you'll have a new icon on your desktop which
 103    runs Puzzle Pirates with JPCTB integrated.
 104 <li>Fail, and tell you what to do next.  Usually this means installing a
 105    Java Runtime Environment (or JVM) and then uninstalling and re-
 106    installing Puzzle Pirates.  (Don't worry about reinstalling; you
 107    won't lose any of your pirates or pieces of eight!)
 108 </nl>
 109
 110 <h3>Installing on Macs</h3>
 111
 112 We believe that it should be straightforward for a MacOS developer or
 113 expert to get YARRG JPCTB working properly on MacOS but we have not
 114 been able to test this ourselves.  The Linux installation method is
 115 probably the best starting point.
 116
 117 <h2>How does it work?  Is it a violation of the Terms of Service?</h2>
 118
 119 YARRG JPCTB uses the Java Accessibility API, which is a part of the
 120 Java platform.  It's an interface provided for making applications
 121 available to users with disabilities, for example for hooking in
 122 screen readers.  This approach was helpfully suggested by a Ringer in
 123 the forums (to another developer of a third-party tool, wanting help
 124 getting information out of Duty Reports).
 125
 126 <p>
 127
 128 Essentially, JPCTB is a specialised "screen reader" which instead of
 129 reading information out loud, uploads it to the YARRG and PCTB
 130 databases.
 131
 132 <p>
 133
 134 Installing YARRG JPCTB does not modify any game files, and does not
 135 hook into the game itself.  It makes no permanent or global changes to
 136 your overall computer, operating system or Java configuration.  And it
 137 does not access (indeed, we don't think it could access) any of the
 138 core game functionality which would make cheating possible.
 139
 140 <p>
 141
 142 JPCTB works by running any unmodified copy of the YPP client but with
 143 a separate JVM (Java Virtual Machine) configured to use the
 144 appropriate accessibility plugin.  We do this (rather than configuring
 145 the computer's main JVM to use the JPCTB accessibility plugin) so that
 146 it is still possible to launch Puzzle Pirates <em>without</em> JPCTB
 147 (for example, in case the JPCTB client should cause any kind of
 148 problem).
 149
 150 <h2>Authorship and source code</h2>
 151
 152 Thanks to Burninator for writing the core of the JPCTB client.  Ian
 153 Jackson and Owen Dunn adapted it to improve the installation setup (in
 154 particular, to more completely avoid modifying the YPP client's
 155 startup files, which Three Rings unsurprisingly objected to).  Owen
 156 Dunn added support for uploading to YARRG and a Windows installer.
 157
 158 <p>
 159
 160 YARRG JPCTB is
 161 Copyright 2006-2009 Burninator,
 162 Copyright 2009-2010 Owen Dunn and
 163 Copyright 2009-2010 Ian Jackson.
 164 It is Free Software with <strong>NO WARRANTY</strong>, released under
 165 the MIT-style two-clause licence.
 166
 167 <p>
 168
 169 The source code for the downloadable released binaries is in the
 170 <a href="http://www.greenend.org.uk/owen/free/jpctb.tar.gz">Linux
 171 tarball</a>.  We maintain YARRG JPCTB in git, and you can get
 172 recent and perhaps unreleased versions from
 173 <code>git://git.yarrg.chiark.net/jpctb.git</code>.
 174
 175
 176 </div>
 177 <& footer &>