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.
38 my $url_base_base= 'http://yarrg.chiark.net/download/jarrg';
40 <%def downloadurl><%args>
43 # ^ change this to change the default version
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
51 <h1>Uploading to YARRG</h1>
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.
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.
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.
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
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.
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
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.
105 <h3>Installing and running on Linux</h3>
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
113 ./jarrg /path/to/yohoho/yohoho
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.
119 <h3>Installing on Windows</h3>
122 <& downloadurl, leaf => 'jarrg-setup.exe' &>
123 and double-click on it. It will either:
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!)
133 <h3>Installing on Macs</h3>
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
140 <h2>How does it work? Is it a violation of the Terms of Service?</h2>
142 Essentially, JARRG is a specialised "screen reader" which instead of
143 reading information out loud, uploads it to the YARRG and PCTB
148 JARRG uses the Java Accessibility API, which is a part of the
149 Java platform. It's a facility in Java, available for all Java
150 programs, intended to help make applications available to users with
151 disabilities: for example, it permits hooking in screen readers. The
152 use of the Java Accessibility API was helpfully suggested by a Ringer
153 in the forums (to another developer of a third-party tool, wanting
154 help getting information out of Duty Reports).
158 Installing JARRG does not modify any game files, and does not
159 hook into the game itself. It makes no permanent or global changes to
160 your overall computer, operating system or Java configuration. And it
161 does not access (indeed, we don't think it could access) any of the
162 core game functionality which would make cheating possible.
166 JARRG runs the unmodified Puzzle Pirates game, but with a separate
167 copy of your system's JVM (Java Virtual Machine); that copy of the JVM
168 is configured to use the JARRG accessibility plugin. We do this
169 (rather than configuring the computer's main JVM to use the
170 accessibility plugin) to avoid interfering with other uses of Java on
171 your computer - in particular, so that it is always possible to launch
172 Puzzle Pirates <em>without</em> JARRG (for example, in case the plugin
173 should cause any kind of problem).
175 <h2><a name="source">Authorship, source code and other versions</a></h2>
177 Thanks to Burninator for writing the core of the JARRG client. Ian
178 Jackson and Owen Dunn adapted it to improve the installation setup (in
179 particular, to avoid modifying any of the YPP client's startup files).
180 Owen Dunn added support for uploading to YARRG, updated the build
181 system, and wrote a Windows installer.
186 Copyright 2006-2009 Burninator,
187 Copyright 2009-2010 Owen Dunn and
188 Copyright 2009-2010 Ian Jackson.
189 It is Free Software with <strong>NO WARRANTY</strong>, released under
190 the MIT-style two-clause licence.
194 The code for the downloadable binaries is in
195 in <& downloadurl, leaf=>'jarrg-source.tar.gz' &>.
196 The download directory also sometimes contains other versions
197 (eg unreleased test versions), which you can see here:
198 <& downloadurl, leaf => '', test => 0 &>
202 We maintain JARRG in git, and you can get
203 source code for recent and perhaps unreleased versions from one of:
205 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>
206 git://git.yarrg.chiark.net/jarrg-owen.git</code> <a href="http://www.chiark.greenend.org.uk/ucgi/~yarrgweb/git?p=jarrg-owen.git;a=summary">(gitweb)</a>