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 <html lang="en"><head><title>Website documentation - YARRG</title>
  37 <link rel="stylesheet" type="text/css" href="style.css">
  38 </head><body>
  39
  40 <div class="navoptbar">
  41 <a href="lookup">YARRG</a> -
  42  Yet Another Revenue Research Gatherer
  43 |
  44 <a href="intro">introduction</a>
  45 |
  46 <b>documentation</b>
  47 |
  48 <a href="devel">development</a>
  49 </div>
  50 <div class="docs">
  51
  52 <h1>Looking up data in 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.  See the <a href="intro">Introduction</a> for more details.
  57
  58 <p>
  59
  60 The <a href="lookup">Market prices database</a> is the main output
  61 from YARRG.  It offers a variety of enquiry options.
  62
  63 <p>
  64
  65 Hopefully you will be able to work it without too much help, but this
  66 documentation page contains information about the database website
  67 which you may not be able to divine from the online user interface.
  68
  69 <h2>Bookmarkable URLs</h2>
  70
  71 Mostly, you can bookmark the specific pages and queries.  Select the
  72 ocean, query page, and other combinations of options, as you wish, and
  73 perhaps fill in the actual data fields too, and bookmark the resulting
  74 URL.
  75
  76 <p>
  77
  78 (An exception to this is if you select the `Update' option from the
  79 `Trades for route' lookup; the list of (de)selected stalls is too long
  80 to fit in a URL.)
  81
  82 <h2>Dynamic confirmation of meaning of text entry boxes</h2>
  83
  84 If you have Javascript enabled, the various text entry boxes will be
  85 annotated with a brief explanation of the system's interpretation of
  86 your current entry string.  To get the actual results updated, you
  87 must still hit `Go' or `Update'.
  88
  89 <h2>Trades for route</h2>
  90
  91 Given a list of islands (or archipelagoes), provides a list of
  92 potentially profitable trades.  If the route is suitable for the trade
  93 route optimiser, it will generate a complete voyage plan, telling you
  94 which goods to buy and sell where at which stalls and prices.
  95
  96 <p><a name="arbitrage"></a>
  97
  98 If you specify only one island or one archipelago, the site shows only
  99 arbitrage trades.  If you want single-hop trades within an
 100 archipelago, you must enter the archipelago name twice.
 101
 102 <p>
 103
 104 After getting the results, you can untick various trades individually,
 105 and select `Update' to get a new plan.  The unticked trades will be
 106 excluded from the voyage plan (if any) and also from the totals.
 107
 108 <h3><a name="capacity">Vessel capacity</a></h3>
 109
 110 If you don't specify a vessel or a vessel capacity, the trading plan
 111 will not take into account the fact that your voyage will be on a ship
 112 with a limited size.  This will probably result in a plan
 113 which trades excessively cumbersome goods (eg. hemp, wood, iron).
 114
 115 <p>
 116
 117 So you should specify your vessel capacity.  You can enter things
 118 like:
 119 <dl>
 120 <dt>sloop
 121 <dd>The capacity of a sloop, leaving no allowance for rum and shot
 122 <dt>wb - 1%
 123 <dd>The capacity of a war brig minus 1%
 124 <dt>13t 20kl
 125 <dd>13 tonnes (13,000kg), 20 kilolitres (20,000l)
 126 <dt>sloop - 10 small 40 rum
 127 <dd>The capacity of a sloop which remains after
 128     10 small shot and 40 rum are loaded
 129 <dt>2t plus 500kg minus 200kg
 130 <dd>2300kg, with no limit on volume
 131 </dl>
 132 Evaluation is strictly from left to right.
 133
 134 <p>
 135
 136 More formally:
 137 <pre>
 138  capacity-string := [ first-term term* ]
 139  term := ('+' | '-' | 'plus' | 'minus') (value+ | number'%')
 140  value := mass | volume
 141         | integer commodity-name-or-abbreviation
 142  mass := number ('t' | 'kg')
 143  volume := number ('kl' | 'l')
 144  first-term := mass | volume | mass volume | volume mass
 145              | ship-name-or-abbreviation
 146 </pre>
 147
 148 If the first term specifies only one of mass or volume, all the
 149 subsequent terms may only adjust that same value.
 150
 151 <h3><a name="losses">Expected losses</a></h3>
 152
 153 In theory if you were guaranteed to have a trouble-free voyage it
 154 would be worth trading goods at very low margins.  However, in
 155 practice problems can arise: you may be attacked and lose your stock,
 156 or market conditions may change between your collection and delivery
 157 of the goods.
 158
 159 <p>
 160
 161 We model this by pretending that you expect to lose a fixed proportion
 162 of your stock each league you sail.  This expected loss does not
 163 appear in the trade tables (although the distance does), but it does
 164 affect the way the voyage trading plan optimiser chooses which trades
 165 to do.
 166
 167 <p>
 168
 169 Trades whose margin is less than the expected loss are never included
 170 in the suggested plan.  For example, if you select 1% loss per league,
 171 and plan a voyage of 5 leagues, then any trade with a margin of less
 172 than 5.15% would be completely excluded (5.15% not 5% because the loss
 173 works like compound interest).  Theoretically very profitable trades
 174 which are close to the expected break-even point because of the
 175 distance can also be rejected by the optimiser in favour of shorter
 176 distance trades with theoretically smaller margins, if it's not
 177 possible to do both.
 178
 179 <p>
 180
 181 As a guide: you may expect to lose between 0.01% and 1% per league.
 182 For example 0.1% would correspond to losing one fight to brigands (who
 183 take 10% if they win) for every 100 leagues sailed.
 184
 185 <p>
 186
 187 You can enter the value in the box either as a percentage, or as a
 188 fraction 1/<em>divisor</em>, eg 1/2000 is the same as 0.05%; in each
 189 case it is taken as the loss for each league of the voyage.
 190
 191 <h3><a name="capital">Available capital</a></h3>
 192
 193 If you don't specify the amount of capital you have available to
 194 invest in the voyage, the trading plan will assume that your capital
 195 is unlimited.  If you specify an amount in PoE here, the trading plan
 196 will never require you to spend more than that amount on commodities.
 197
 198 <p>
 199
 200 The trading plan does not take into account accumulated profits from
 201 each leg of the journey when applying the available capital
 202 constraint.  For example, if you specify a journey from A to B to C
 203 and a capital limit of 10000 PoE, the trading plan will not tell you
 204 to buy 1000 peas at A for 10 PoE each, sail them to B and sell all of
 205 them for 20 PoE each, and then buy 2000 beans at B for 10 PoE each and
 206 sail them to C to sell for 20 PoE each even if such a trade would in
 207 fact be possible.  In practice this is unlikely to be a problem!
 208
 209 </div>
 210 <& footer &>