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 <%perl>
  38 my $url_base_base= 'http://yarrg.chiark.net/download/jpctb';
  39 my $download_version= '0.9.1';
  40 my $url_base= "$url_base_base/$download_version";
  41 </%perl>
  42 <h1>Uploading to YARRG</h1>
  43 <p>
  44
  45 The YARRG system has two main parts: this website which maintains a
  46 searchable database of commodity prices, and an upload client (known
  47 as YARRG JPCTB), which screenscrapes the commodity data from the
  48 Puzzle Pirates game client and uploads it to the database.
  49
  50 <p>
  51
  52 You will need to upload data yourself if there is no data for your
  53 ocean or island, or the data that is there is too old.  You should
  54 also upload when preparing a trade run, as market conditions change and
  55 you want a plan based on recent data.
  56
  57 <p>
  58
  59 The YARRG JPCTB upload client uploads both to YARRG and
  60 <a href="http://pctb.crabdance.com/">PCTB</a>.  It is intended to
  61 replace both the <a href="scraper">"yarrg"</a> and "PPAOCR" screenscrapers.
  62
  63 <h2>Instructions</h2>
  64
  65 First you must install YARRG JPCTB, following the instructions for
  66 your operating system, below.  This will not modify your Puzzle
  67 Pirates installation.  Instead, it provides you with a new way to run
  68 Puzzle Pirates which integrates it with JPCTB to provides a YARRG/PCTB
  69 Upload facility.
  70
  71 <p>
  72
  73 To upload data, run the Puzzle Pirates client with JPCTB (as detailed
  74 below).  You should see both the Puzzle Pirates window and the JPCTB
  75 window appear.  Log in normally, and visit a commodity trading screen
  76 (at a market, shoppe or vessel hold).  Select "All Commodities" in the
  77 YPP client.  Then press "Upload" in the JPCTB window.
  78
  79 <p>
  80
  81 The JPCTB integration is done via fully supported Java Accessibility
  82 interfaces, and should not disturb the normal running of Puzzle
  83 Pirates.  However, please make sure that if your YPP client misbehaves
  84 at all, you try starting it in the vanilla way (without JPCTB
  85 integration) before asking for help.  In particular, if the JPCTB
  86 startup does not work, but the ordinary Puzzle Pirates startup does,
  87 report the problem to us, not to Three Rings.
  88
  89 <h3>Installing and running on Linux</h3>
  90
  91 Download
  92 <a href="<% $url_base %>/jpctb.tar.gz"><% $url_base %>/jpctb.tar.gz</a>
  93 and unpack it.  You run it from the command line.  Change
  94 to the directory where you unpacked the tarball above, and then run
  95 <pre>
  96 ./jpctb /path/to/yohoho/yohoho
  97 </pre>
  98 where <code>/path/to/yohoho/yohoho</code> is the location of the
  99 ordinary Puzzle Pirates startup script, which is normally
 100 <code>yohoho/yohoho</code> in your home directory.
 101
 102 <h3>Installing on Windows</h3>
 103
 104 Download
 105 <a href="<% $url_base %>/jpctb-setup.exe"><% $url_base %>/jpctb-setup.exe</a>
 106 and double-click on it.  It will either:
 107 <ol>
 108 <li>Just work, in which case you'll have a new icon on your desktop which
 109    runs Puzzle Pirates with JPCTB integrated.
 110 <li>Fail, and tell you what to do next.  Usually this means installing a
 111    Java Runtime Environment (or JVM) and then uninstalling and re-
 112    installing Puzzle Pirates.  (Don't worry about reinstalling; you
 113    won't lose any of your pirates or pieces of eight!)
 114 </ol>
 115
 116 <h3>Installing on Macs</h3>
 117
 118 We believe that it should be straightforward for a MacOS expert to get
 119 YARRG JPCTB working properly on MacOS but we have not been able to
 120 test this ourselves.  The Linux installation method is probably the
 121 best starting point.
 122
 123 <h2>How does it work?  Is it a violation of the Terms of Service?</h2>
 124
 125 Essentially, JPCTB is a specialised "screen reader" which instead of
 126 reading information out loud, uploads it to the YARRG and PCTB
 127 databases.
 128
 129 <p>
 130
 131 YARRG JPCTB uses the Java Accessibility API, which is a part of the
 132 Java platform.  It's a facility in Java, available for all Java
 133 programs, intended to help make applications available to users with
 134 disabilities: for example, it permits hooking in screen readers.  The
 135 use of the Java Accessibility API was helpfully suggested by a Ringer
 136 in the forums (to another developer of a third-party tool, wanting
 137 help getting information out of Duty Reports).
 138
 139 <p>
 140
 141 Installing YARRG JPCTB does not modify any game files, and does not
 142 hook into the game itself.  It makes no permanent or global changes to
 143 your overall computer, operating system or Java configuration.  And it
 144 does not access (indeed, we don't think it could access) any of the
 145 core game functionality which would make cheating possible.
 146
 147 <p>
 148
 149 JPCTB works by running an unmodified copy of the YPP client but with
 150 a separate JVM (Java Virtual Machine) configured to use the
 151 appropriate accessibility plugin.  We do this (rather than configuring
 152 the computer's main JVM to use the JPCTB accessibility plugin) so that
 153 it is still possible to launch Puzzle Pirates <em>without</em> JPCTB
 154 (for example, in case the JPCTB client should cause any kind of
 155 problem).
 156
 157 <h2>Authorship, source code and other versions</h2>
 158
 159 Thanks to Burninator for writing the core of the JPCTB client.  Ian
 160 Jackson and Owen Dunn adapted it to improve the installation setup (in
 161 particular, to more completely avoid modifying the YPP client's
 162 startup files, which Three Rings unsurprisingly objected to).  Owen
 163 Dunn added support for uploading to YARRG, updated the build system,
 164 and wrote a Windows installer.
 165
 166 <p>
 167
 168 YARRG JPCTB is
 169 Copyright 2006-2009 Burninator,
 170 Copyright 2009-2010 Owen Dunn and
 171 Copyright 2009-2010 Ian Jackson.
 172 It is Free Software with <strong>NO WARRANTY</strong>, released under
 173 the MIT-style two-clause licence.
 174
 175 <p>
 176
 177 The download directory contains some historical versions, which you
 178 can see here:
 179 <a href="<% $url_base_base %>/"><% $url_base_base %>/</a> .
 180
 181 <p>
 182
 183 The source code for the downloadable released binaries is in the
 184 <a href="<% $url_base %>/jpctb.tar.gz">Linux
 185 tarball</a>.  We maintain YARRG JPCTB in git, and you can get
 186 source code for recent and perhaps unreleased versions from
 187 <code>git://git.yarrg.chiark.net/jpctb.git</code>.
 188
 189
 190 </div>
 191 <& footer &>