chiark / gitweb /
Obsidian: Add islands where chart scraper is confused
[ypp-sc-tools.db-test.git] / yarrg / web / intro
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  Copyright (C) 2009 Naath Cousins
9
10   YARRG's client code etc. is covered by the ordinary GNU GPL (v3 or later).
11   The YARRG website is covered by the GNU Affero GPL v3 or later, which
12    basically means that every installation of the website will let you
13    download the source.
14
15  This program is free software: you can redistribute it and/or modify
16  it under the terms of the GNU Affero General Public License as
17  published by the Free Software Foundation, either version 3 of the
18  License, or (at your option) any later version.
19
20  This program is distributed in the hope that it will be useful,
21  but WITHOUT ANY WARRANTY; without even the implied warranty of
22  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
23  GNU Affero General Public License for more details.
24
25  You should have received a copy of the GNU Affero General Public License
26  along with this program.  If not, see <http://www.gnu.org/licenses/>.
27
28  Yohoho and Puzzle Pirates are probably trademarks of Three Rings and
29  are used without permission.  This program is not endorsed or
30  sponsored by Three Rings.
31
32
33  This Mason component generates the introduction.
34
35
36 </%doc>
37 <& docshead:head &>
38 <style type="text/css">
39 <& style.css &>
40   body { margin: 0; color: #000000; background: #c5c7ae; }
41   div.emph {
42      margin-left: 1em; padding-left: 1em; padding-top: 0.01em;
43      margin-right: 1em; padding-right: 1em; padding-bottom: 0.05em;
44      background: #ffffff;
45   }
46 </style>
47 <div class="navoptbar">
48 <& navbar &>
49 </div>
50 <div class="docs">
51
52 <h1>Guide to YARRG</h1>
53
54 YARRG (Yet Another Revenue Research Gatherer) is a third-party tool
55 for helping find profitable trades and trade routes in Yohoho Puzzle
56 Pirates.  It was inspired by
57 <a href="http://pctb.crabdance.com/">PCTB</a>.
58
59 <p>
60
61 Information about commodity prices is collected by pirates like you
62 and uploaded to the YARRG server, using the special yarrg upload
63 client.  You can then query and search on this website for commodity
64 prices and good trade routes.
65
66
67 <p>
68
69 <div class="emph">
70 <h2>Quick start for experts</h2>
71
72 <h3>Straight to the commodity prices database</h3>
73
74 If you already know about trading on Puzzle Pirates, understand what
75 the YARRG website is for, and just want to get down to playing with
76 it right away, simply select your ocean:
77
78 <p>
79 <div align="center">
80 % my @oceans= ocean_list();
81 % my $delim= '';
82 % foreach my $ocean (@oceans) {
83 %       my $uri= URI->new('lookup');
84 %       $uri->query_form('ocean', $ocean) if $ocean ne 'Midnight';
85 <% $delim %><a href="<% $uri->path_query() |h %>"><% $ocean |h %></a>
86 %       $delim=' | ';
87 % }
88 </div>
89
90 <h3>But before you start ...</h3>
91
92 If you are going to use YARRG seriously you will almost certainly want
93 to upload your own data.  See <a href="upload">Uploading to YARRG</a>
94 for details.
95
96 <p>
97
98 You will also probably at some point want to read the
99 <a href="docs">Documentation for Experts</a> which covers some
100 features of the website which you might not guess just from using it.
101
102 </div>
103
104 <h2>How to use the YARRG website</h2>
105
106 YARRG is designed to help pirates make profitable trades.  It is not
107 designed as a trading tutorial and some familiarity with trading in
108 YPP is assumed. <a
109 href="http://yppedia.puzzlepirates.com/Trading">yppedia.puzzlepirates.com/Trading</a>
110 contains some advice on trading basics.
111
112 <h3>So how do I use it then?</h3> 
113
114 <p> First look at the top of the page.  You need to select your Ocean,
115 the sort of Interface you would like and the type of Query you wish to
116 ask.
117
118 <p> 
119
120 <h3>Selecting your Ocean</h3> 
121
122 <p> 
123
124 Which ocean do you want to trade on?
125 Just click on that ocean's name.
126
127 <p> 
128
129 <h3>Selecting your Interface</h3>
130
131 <p> You can choose to enter commodity and island names by typing them
132 into a text entry field or by selecting them from a drop down menu.
133 The "select from menu" option allows only a restricted number of
134 options to be entered into each field.
135
136 <p>
137
138 <h3>Type of Query</h3> 
139
140 <p> 
141
142 There are currently four types of query available which answer
143 slightly different questions.
144
145 <p> 
146
147 <h4>Trades for route</h4>
148
149 <p> 
150
151 <b>For pirates who know where they are going.</b>  Trades for route allows
152 you to enter a route that you are planning to sail and find out if
153 there are any profitable trades you can make along the way.  This is
154 for pirates who already have a definite sailing plan for some reason.
155 Under "Enter Route" you need to type (or select from menus) the names
156 of the islands or Archipelagoes that you plan to visit.  If you wish
157 to know about arbitrage opportunities at an island you can enter just
158 that island name.  If you enter only one Archipelago then you will get
159 arbitrage opportunities in that archipelago; if you enter the same
160 archipelago twice you'll get trades within that archipelago.
161
162 <p> 
163
164 <h4>Prices for commodity</h4> 
165
166 <p> 
167
168 <b>For pirates wanting to sell or buy a specific commodity</b> prices for
169 commodity returns the best buy and sell prices for the selected
170 commodity at each island where trades are available.  Type (or select
171 from a menu) the name of one commodity at a time.  This is useful for
172 pirates wishing to purchase or sell a specific commodity and wanting
173 the best price.  
174
175 <p> 
176
177 <h4>Offers at location</h4>
178
179 <p>
180
181 <b>For pirates wanting more details about commodity prices at specified
182 locations.</b> Offers at location returns all the offers to buy and sell
183 wood at the selected location(s). Type (or select) a commodity and the
184 islands (or achipelagos) you are interested in.  This is useful when
185 the best buy or sell offer is for only a small quantity: you can check
186 what the others offers are like.
187
188 <p>
189
190 <h4>Find Profitable route</h4> 
191
192 <p>
193
194 <b>For pirates just wanting to make some poe moving commodities about.</b> Find
195 Profitable Route finds you a profitable trading route: first select
196 either "open-ended" (which might take you anywhere) or "circular"
197 (which takes you back to where you started) then type (or select) your
198 starting point (or points - you may for instance have two ships in
199 different locations either of which you could use).
200
201 <p>
202
203 <h3>Data age</h3>
204
205 <p>
206
207 Data age tells you how long ago data was uploaded from each island in
208 your ocean.  Data changes very quickly and trusting old data to be
209 accurate is unlikely to be rewarding.
210
211 <p>
212
213 <h3>What do the results mean</h3>
214
215 <p>
216
217 "Prices for commodity" and "Offers at location" give very similar results;
218 there will be two tables: the first titled "Offers to BUY" your
219 commodity, the second "Offers to SELL" it.  The tables can be sorted
220 as you wish by clicking on the arrows in the headings.
221
222 <p>
223
224 "Trades for route" and "Find profitable route" both return voyage plans.
225 "Find profitable route" has an additional step to get at your results -
226 when you enter your query you are given a list of 15 good routes for
227 total profit and 15 good routes for profit per league which visit
228 different islands. Select your preferred route: perhaps you will choose
229 to take the best profit or perhaps you need to miss out one island
230 because it is blockaded or another because you don't have the charts
231 to get to or from it.  If you have asked for a trade for route or
232 after selecting the profitable route you prefer you will get a Voyage
233 trading plan - this provides you with instructions for what to do (buy
234 this, sell that, sail there).
235
236 <p>
237
238 Sometimes no useful trades are available.  In this case the results
239 section says simply "No profitable trading opportunities were found".
240
241 <p>
242
243 After this there is a table reporting the age of the data used.  And
244 then a table of "Relevant trades" which lists just about everything you
245 could want to know about each trade the plan suggests you make (yes,
246 this table is fairly complicated).  The ticky boxes down the side of
247 this table allow you to choose which trades you like the look of -
248 untick any that you are not interested in (for instance you may be
249 uninterested in trades with a low profit margin).
250
251 <p>
252
253 <h3>What are the Advanced options</h3>
254
255 <p>
256
257 These options are very useful, and not very advanced, but not needed
258 for searching the data.
259
260 <p>
261
262 <h4>Capacity</h4>
263
264 <p>
265
266 You can't trade more than fits in your hold.  If you don't say
267 anything YARRG assumes that you have infinite hold space (perhaps you
268 will go over the route many times).  You can enter a ship-type, a mass
269 or a volume; additionally you can subtract quantities of commodities
270 from a ship-type (for instance 'sloop - 10 grog' gives the capacity of
271 a sloop that has 10 grog already on board); click the ? by this field
272 to get a full description of permitted entries here.
273
274 <p>
275
276 <h4>Capital</h4>
277
278 <p>
279  
280 How much poe do you have?  If you don't say anything YARRG assumes you
281 have infinite poe to spend, but you probably don't.  Enter the amount
282 you are willing to spend on commodities for trading with.
283
284 <p>
285
286 <h4>Expected losses</h4> 
287
288 <p>
289
290 How much do you expect to lose to the dastardly brigands?  Enter either
291 a % (as eg - 1%) or a fraction (as eg - 1/100) of the goods you
292 expect to loose to Brigands.  Brigands take 10% if they defeat you,
293 but only you know how often you are defeated.  Note that this doesn't
294 include rum-consumed so you will need to account for that
295 seperately.
296
297 <p>
298
299 <h4>Max distance</h4>
300
301 <p>
302
303 How far are you willing to sail today?  The default is 20 leagues, the
304 maximum supported is 35.  Are you willing to sail all the way across
305 the ocean for a profit?  Or would you prefer to go only a short way?
306
307 <p>
308
309 <h3>Other fairly useful information</h3>
310
311 <p>
312
313 The search information is encoded in the URL - you can bookmark pages
314 for searches you want to perform a lot and go straight to them without
315 re-entering you data (or you can copy the URL and tell your hearties
316 and crew mates if you want to).  There's no need to come back to the
317 introductory page each time.
318
319 <p>
320
321 Javascript magic: when you type things into the text entry fields
322 YARRG will try to guess what you meant.  If you pause for a moment then
323 beneath the text entry field you'll see what YARRG thinks you meant.
324 If it's got it correct you don't have to type any more of that
325 commodity/island name: just go on to the next one.
326
327 <p>
328
329 You'll probably want to upload data to ensure you have fresh data
330 available.  Unfortunately YARRG only has a Linux upload client at
331 present (a windows one is in the works).  You should <a
332 href="upload">read about how to upload</a>: particularly the linked
333 README page for information about the client which contain
334 easy-to-follow instructions to download, install and run it in the
335 form of a few comand line instructions that you can copy and paste.
336
337 <p>
338
339 It's all free, both free-as-in-beer or free-as-in-speech.  If you're
340 interested, read the <a href="devel">Development pages</a> for more
341 info about how to contribute or how to run your own website using
342 YARRG data (perhaps you don't like our colour choices)
343
344
345
346 <h2>Contacting the YARRG developers</h2>
347
348 Email Ian Jackson ijackson (at) chiark.greenend.org.uk.  Or talk to
349 any Fleet Officer or above of the crew Special Circumstances on the
350 Cerulean Ocean.
351 <p>
352
353 </div>
354 <& footer &>