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 the documentation.
37 <h1>Looking up data in YARRG</h1>
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.
45 The <a href="lookup">Market prices database</a> is the main output
46 from YARRG. It offers a variety of enquiry options.
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.
56 If this page is all too complicated for you, you may prefer to read
57 <a href="intro">the introduction</a> instead.
59 <h2>Bookmarkable URLs</h2>
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
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
72 <h2>Dynamic confirmation of meaning of text entry boxes</h2>
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".
79 <h2>Trades for route</h2>
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.
86 <p><a name="arbitrage"></a>
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.
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.
98 <h3><a name="capacity">Vessel capacity</a></h3>
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).
107 So you should specify your vessel capacity. You can enter things
111 <dd>The capacity of a sloop, leaving no allowance for rum and shot
113 <dd>The capacity of a war brig minus 1%
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
122 Evaluation is strictly from left to right.
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
138 If the first term specifies only one of mass or volume, all the
139 subsequent terms may only adjust that same value.
141 <h3><a name="losses">Expected losses</a></h3>
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
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
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
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.
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.
181 <h3><a name="capital">Available capital</a></h3>
183 If you don't specify the amount of capital you have available to
184 invest in the voyage, the trading plan will assume that your capital
185 is unlimited. If you specify an amount in PoE here, the trading plan
186 will never require you to spend more than that amount on commodities.
190 The trading plan does not take into account accumulated profits from
191 each leg of the journey when applying the available capital
192 constraint. For example, if you specify a journey from A to B to C
193 and a capital limit of 10000 PoE, the trading plan will not tell you
194 to buy 1000 peas at A for 10 PoE each, sail them to B and sell all of
195 them for 20 PoE each, and then buy 2000 beans at B for 10 PoE each and
196 sail them to C to sell for 20 PoE each even if such a trade would in
197 fact be possible. In practice this is unlikely to be a problem!