chiark / gitweb /
wip sort out Midnights
[ypp-sc-tools.web-live.git] / yarrg / web / docs
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 the documentation.
33
34
35 </%doc>
36 <& docshead &>
37 <h1>Looking up data in YARRG</h1>
38
39 YARRG (Yet Another Revenue Research Gatherer) is a third-party tool
40 for helping find profitable trades and trade routes in Yohoho Puzzle
41 Pirates.  See the <a href="intro">Introduction</a> for more details.
42
43 <p>
44
45 The <a href="lookup">Market prices database</a> is the main output
46 from YARRG.  It offers a variety of enquiry options.
47
48 <p>
49
50 Hopefully you will be able to work it without too much help, but this
51 documentation page contains information about the database website
52 which you may not be able to divine from the online user interface.
53
54 <p>
55
56 If this page is all too complicated for you, you may prefer to read
57 <a href="intro">the introduction</a> instead.
58
59 <h2>Bookmarkable URLs</h2>
60
61 Mostly, you can bookmark the specific pages and queries.  Select the
62 ocean, query page, and other combinations of options, as you wish, and
63 perhaps fill in the actual data fields too, and bookmark the resulting
64 URL.
65
66 <p>
67
68 (An exception to this is if you select the "Update" option from the
69 "Trades for route" lookup; the list of (de)selected stalls is too long
70 to fit in a URL.)
71
72 <h2>Dynamic confirmation of meaning of text entry boxes</h2>
73
74 If you have Javascript enabled, the various text entry boxes will be
75 annotated with a brief explanation of the system's interpretation of
76 your current entry string.  To get the actual results updated, you
77 must still hit "Go" or "Update".
78
79 <h2>Trades for route</h2>
80
81 Given a list of islands (or archipelagoes), provides a list of
82 potentially profitable trades.  If the route is suitable for the trade
83 route optimiser, it will generate a complete voyage plan, telling you
84 which goods to buy and sell where at which stalls and prices.
85
86 <p><a name="arbitrage"></a>
87
88 If you specify only one island or one archipelago, the site shows only
89 arbitrage trades.  If you want single-hop trades within an
90 archipelago, you must enter the archipelago name twice.
91
92 <p>
93
94 After getting the results, you can untick various trades individually,
95 and select "Update" to get a new plan.  The unticked trades will be
96 excluded from the voyage plan (if any) and also from the totals.
97
98 <h3><a name="capacity">Vessel capacity</a></h3>
99
100 If you don't specify a vessel or a vessel capacity, the trading plan
101 will not take into account the fact that your voyage will be on a ship
102 with a limited size.  This will probably result in a plan
103 which trades excessively cumbersome goods (eg. hemp, wood, iron).
104
105 <p>
106
107 So you should specify your vessel capacity.  You can enter things
108 like:
109 <dl>
110 <dt>sloop
111 <dd>The capacity of a sloop, leaving no allowance for rum and shot
112 <dt>wb - 1%
113 <dd>The capacity of a war brig minus 1%
114 <dt>13t 20kl
115 <dd>13 tonnes (13,000kg), 20 kilolitres (20,000l)
116 <dt>sloop - 10 small 40 rum
117 <dd>The capacity of a sloop which remains after
118     10 small shot and 40 rum are loaded
119 <dt>2t plus 500kg minus 200kg
120 <dd>2300kg, with no limit on volume
121 </dl>
122 Evaluation is strictly from left to right.
123
124 <p>
125
126 More formally:
127 <pre>
128  capacity-string := [ first-term term* ]
129  term := ('+' | '-' | 'plus' | 'minus') (value+ | number'%')
130  value := mass | volume
131         | integer commodity-name-or-abbreviation
132  mass := number ('t' | 'kg')
133  volume := number ('kl' | 'l')
134  first-term := mass | volume | mass volume | volume mass
135              | ship-name-or-abbreviation
136 </pre>
137
138 If the first term specifies only one of mass or volume, all the
139 subsequent terms may only adjust that same value.
140
141 <h3><a name="losses">Expected losses</a></h3>
142
143 In theory if you were guaranteed to have a trouble-free voyage it
144 would be worth trading goods at very low margins.  However, in
145 practice problems can arise: you may be attacked and lose your stock,
146 or market conditions may change between your collection and delivery
147 of the goods.
148
149 <p>
150
151 We model this by pretending that you expect to lose a fixed proportion
152 of your stock each league you sail.  This expected loss does not
153 appear in the trade tables (although the distance does), but it does
154 affect the way the voyage trading plan optimiser chooses which trades
155 to do.
156
157 <p>
158
159 Trades whose margin is less than the expected loss are never included
160 in the suggested plan.  For example, if you select 1% loss per league,
161 and plan a voyage of 5 leagues, then any trade with a margin of less
162 than 5.15% would be completely excluded (5.15% not 5% because the loss
163 works like compound interest).  Theoretically very profitable trades
164 which are close to the expected break-even point because of the
165 distance can also be rejected by the optimiser in favour of shorter
166 distance trades with theoretically smaller margins, if it's not
167 possible to do both.
168
169 <p>
170
171 As a guide: you may expect to lose between 0.01% and 1% per league.
172 For example 0.1% would correspond to losing one fight to brigands (who
173 take 10% if they win) for every 100 leagues sailed.
174
175 <p>
176
177 You can enter the value in the box either as a percentage, or as a
178 fraction 1/<em>divisor</em>, eg 1/2000 is the same as 0.05%; in each
179 case it is taken as the loss for each league of the voyage.
180
181 <h3><a name="minprofit">Minimum trade value</a></h3>
182
183 Often there are many low-volume, low-value trades.  It can be rather
184 labour-intensive to buy and sell a dozen different commodities, half
185 of which are only making a few poe each.
186
187 <p>
188
189 The "minimum trade value" specifies a minimum profit that you would
190 like to get from each (commodity, collect island, deliver island)
191 triplet.  Trades which don't meet this minimum will start out unticked in
192 the "Relevant trades" table and will not be included in the voyage
193 trading plan.
194
195 <p>
196
197 If you want to change your threshold, you have to select "Apply",
198 which will automatically tick and untick all of the tickboxes for in
199 "Relevant trades", as appropriate.  This will undo any customisation
200 of the set of trades you have already done by manually ticking and
201 unticking individual trades.
202
203 <p>
204
205 The value is an absolute poe amount, typically 5 or 10, representing
206 the minimum profit to make it worthwhile (from a time and effort point
207 of view) clicking in the YPP client to collect and deliver a
208 commodity.  Setting a higher threshold will make each island visit
209 faster, by excluding trivial transactions, and so reduce the chance
210 that market conditions change adversely during your voyage.
211
212 <h3><a name="poelimit">Caution about stalls' poe reserves</a></h3>
213
214 If you select <b>Also be cautious about stalls' poe reserves</b>,
215 YARRG will calculate a minimum amount of poe that each stall has on
216 hand (by looking at all the offers that stall is making), and never
217 plan for you to sell goods at that stall for more than the available
218 poe.
219
220 <p>
221
222 Goods planned to be bought at the stall (which might boost the stall's
223 poe reserves) are not considered, to avoid having to calculate the
224 stall's cash reserves at various different times.
225
226 <h3><a name="capital">Available capital</a></h3>
227
228 If you don't specify the amount of capital you have available to
229 invest in the voyage, the trading plan will assume that your capital
230 is unlimited.  If you specify an amount in PoE here, the trading plan
231 will never require you to spend more than that amount on commodities.
232
233 <p>
234
235 The trading plan does not take into account accumulated profits from
236 each leg of the journey when applying the available capital
237 constraint.  For example, if you specify a journey from A to B to C
238 and a capital limit of 10000 PoE, the trading plan will not tell you
239 to buy 1000 peas at A for 10 PoE each, sail them to B and sell all of
240 them for 20 PoE each, and then buy 2000 beans at B for 10 PoE each and
241 sail them to C to sell for 20 PoE each even if such a trade would in
242 fact be possible.  In practice this is unlikely to be a problem!
243
244 <h3><a name="posinclass">Locating commodities in the YPP client UI</a></h3>
245
246 In the Voyage Trading Plan, YARRG indicates after the commodity name
247 where in the YPP commodity UI each commodity can be found.  First
248 comes the initial letter of the category:
249 %     my $dbh= dbw_connect('Cerulean');
250 %     my $getclasses= $dbh->prepare(
251 %        "SELECT commodclass FROM commodclasses ORDER BY commodclass");
252 %     $getclasses->execute();
253 <%
254     join '; ', map { $_->[0] =~ m/^./ or die; "<strong>$&</strong>$'" }
255         @{ $getclasses->fetchall_arrayref() }
256 %>.
257 <p>
258
259 Then, if applicable, follows a number from <strong>0</strong> to
260 <strong>9</strong> indicating roughly where the commodity is in the
261 list of commodities of the same class.  The number indicates which
262 tenth of the list is: <strong>0</strong> for the first (top) tenth,
263 <strong>1</strong> for the 2nd, and so on, up to <strong>9</strong>
264 for the final tenth.
265
266 <p>
267 For example,
268 <blockquote>
269 <table><tr>
270 <td>Fine pink cloth&nbsp;&nbsp;
271 <td><div class=mouseover
272  title="Fine pink cloth is under Cloth, commodity 14 of 55">C 2</div>
273 </table>
274 </blockquote>
275 indicates that Fine pink cloth can be found under Cloth,
276 between 20% and 30% of the way down through the types of Cloth.
277 If you mouseover that in a suitably equipped browser you should see the
278 text:
279 <blockquote>
280 Fine pink cloth is under Cloth, commodity 14 of 55
281 </blockquote>
282 <p>
283
284 The position indicator digit isn't shown for very small
285 categories.
286
287 The exact location of the commodity in the actual game
288 client may vary because YARRG only considers the list of all possible
289 commodities, not the list of actual offers at the island in question.
290
291 </div>
292 <& footer &>