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