chiark / gitweb /
jpctb is now called jarrg
[ypp-sc-tools.web-live.git] / 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/jarrg';
39 my $download_version= 'test';
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 JARRG), 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 JARRG 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 JARRG, 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 JARRG to provides a YARRG/PCTB
69 Upload facility.
70
71 <p>
72
73 To upload data, run the Puzzle Pirates client with JARRG (as detailed
74 below).  You should see both the Puzzle Pirates window and the JARRG
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 Market Data" in the JARRG window.
78
79 <p>
80
81 The JARRG 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 JARRG
85 integration) before asking for help.  In particular, if the JARRG
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 %>/jarrg.tar.gz"><% $url_base %>/jarrg.tar.gz</a>
93 and unpack it.  You run jarrg from the command line.  Change
94 (<code>cd</code>) to the top level <code>jarrg</code> directory
95 which was created when you unpacked the tarball, and then run
96 <pre>
97 ./jarrg /path/to/yohoho/yohoho
98 </pre>
99 where <code>/path/to/yohoho/yohoho</code> is the location of the
100 ordinary Puzzle Pirates startup script, which is normally
101 <code>yohoho/yohoho</code> in your home directory.
102
103 <h3>Installing on Windows</h3>
104
105 Download
106 <a href="<% $url_base %>/jarrg-setup.exe"><% $url_base %>/jarrg-setup.exe</a>
107 and double-click on it.  It will either:
108 <ol>
109 <li>Just work, in which case you'll have a new icon on your desktop which
110    runs Puzzle Pirates with JARRG integrated.
111 <li>Fail, and tell you what to do next.  Usually this means installing a
112    Java Runtime Environment (or JVM) and then uninstalling and re-
113    installing Puzzle Pirates.  (Don't worry about reinstalling; you
114    won't lose any of your pirates or pieces of eight!)
115 </ol>
116
117 <h3>Installing on Macs</h3>
118
119 We believe that it should be straightforward for a MacOS expert to get
120 JARRG working properly on MacOS but we have not been able to
121 test this ourselves.  The Linux installation method is probably the
122 best starting point.
123
124 <h2>How does it work?  Is it a violation of the Terms of Service?</h2>
125
126 Essentially, JARRG is a specialised "screen reader" which instead of
127 reading information out loud, uploads it to the YARRG and PCTB
128 databases.
129
130 <p>
131
132 JARRG uses the Java Accessibility API, which is a part of the
133 Java platform.  It's a facility in Java, available for all Java
134 programs, intended to help make applications available to users with
135 disabilities: for example, it permits hooking in screen readers.  The
136 use of the Java Accessibility API was helpfully suggested by a Ringer
137 in the forums (to another developer of a third-party tool, wanting
138 help getting information out of Duty Reports).
139
140 <p>
141
142 Installing JARRG does not modify any game files, and does not
143 hook into the game itself.  It makes no permanent or global changes to
144 your overall computer, operating system or Java configuration.  And it
145 does not access (indeed, we don't think it could access) any of the
146 core game functionality which would make cheating possible.
147
148 <p>
149
150 JARRG runs the unmodified Puzzle Pirates game, but with a separate
151 copy of your system's JVM (Java Virtual Machine); that copy of the JVM
152 is configured to use the JARRG accessibility plugin.  We do this
153 (rather than configuring the computer's main JVM to use the
154 accessibility plugin) to avoid interfering with other uses of Java on
155 your computer - in particular, so that it is always possible to launch
156 Puzzle Pirates <em>without</em> JARRG (for example, in case the plugin
157 should cause any kind of problem).
158
159 <h2><a name="source">Authorship, source code and other versions</a></h2>
160
161 Thanks to Burninator for writing the core of the JARRG client.  Ian
162 Jackson and Owen Dunn adapted it to improve the installation setup (in
163 particular, to avoid modifying any of the YPP client's startup files).
164 Owen Dunn added support for uploading to YARRG, updated the build
165 system, and wrote a Windows installer.
166
167 <p>
168
169 JARRG is
170 Copyright 2006-2009 Burninator,
171 Copyright 2009-2010 Owen Dunn and
172 Copyright 2009-2010 Ian Jackson.
173 It is Free Software with <strong>NO WARRANTY</strong>, released under
174 the MIT-style two-clause licence.
175
176 <p>
177
178 The download directory can contains other versions (eg unreleased test
179 versions), which you can see here:
180  <a href="<% $url_base_base %>/"><% $url_base_base %>/</a> .
181
182 <p>
183
184 The source code for the downloadable released binaries is in the
185 <a href="<% $url_base %>/jarrg.tar.gz">Linux
186 tarball</a>.  We maintain JARRG in git, and you can get
187 source code for recent and perhaps unreleased versions from one of:
188 <pre>
189 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>
190 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>
191 </pre>
192
193
194 </div>
195 <& footer &>