3 This is part of the YARRG website. YARRG is a tool and website
4 for assisting players of Yohoho Puzzle Pirates.
6 Copyright (C) 2009 Ian Jackson <ijackson@chiark.greenend.org.uk>
7 Copyright (C) 2009 Clare Boothby
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
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.
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.
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/>.
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.
32 This Mason component generates information about the uploader.
37 <h1>Uploading to YARRG</h1>
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.
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.
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.
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.
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
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,
83 <h3>Installing and running on Linux</h3>
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
90 ./jpctb /path/to/yohoho/yohoho
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.
96 <h3>Installing on Windows</h3>
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:
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!)
110 <h3>Installing on Macs</h3>
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.
117 <h2>How does it work? Is it a violation of the Terms of Service?</h2>
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).
128 Essentially, JPCTB is a specialised "screen reader" which instead of
129 reading information out loud, uploads it to the YARRG and PCTB
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.
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
150 <h2>Authorship and source code</h2>
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.
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.
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>.