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