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><head><title>Website documentation - YARRG</title>
  37 </head><body>
  38
  39 <a href="lookup">YARRG</a> -
  40  Yet Another Revenue Research Gatherer
  41 |
  42 <a href="devel">development</a>
  43 |
  44 <a href="intro">introduction</a>
  45 |
  46 <b>documentation</b>
  47
  48 <h1>Looking up data in YARRG</h1>
  49
  50 YARRG (Yet Another Revenue Research Gatherer) is a third-party tool
  51 for helping find profitable trades and trade routes in Yohoho Puzzle
  52 Pirates.  See the <a href="intro">Introduction</a> for more details.
  53
  54 <p>
  55
  56 The <a href="lookup">Market prices database</a> is the main output
  57 from YARRG.  It offers a variety of enquiry options.
  58
  59 <p>
  60
  61 Hopefully you will be able to work it without too much help, but this
  62 documentation page contains information about the database website
  63 which you may not be able to divine from the online user interface.
  64
  65 <h2>Bookmarkable URLs</h2>
  66
  67 Mostly, you can bookmark the specific pages and queries.  Select the
  68 ocean, query page, and other combinations of options, as you wish, and
  69 perhaps fill in the actual data fields too, and bookmark the resulting
  70 URL.
  71
  72 <p>
  73
  74 (An exception to this is if you select the `Update' option from the
  75 `Trades for route' lookup; the list of (de)selected stalls is too long
  76 to fit in a URL.)
  77
  78 <h2>Dynamic confirmation of meaning of text entry boxes</h2>
  79
  80 If you have Javascript enabled, the various text entry boxes will be
  81 annotated with a brief explanation of the system's interpretation of
  82 your current entry string.  To get the actual results updated, you
  83 must still hit `Go' or `Update'.
  84
  85 <h2>Trades for route</h2>
  86
  87 Given a list of islands (or archipelagoes), provides a list of
  88 potentially profitable trades.  If the route is suitable for the trade
  89 route optimiser, it will generate a complete voyage plan, telling you
  90 which goods to buy and sell where at which stalls and prices.
  91
  92 <p>
  93
  94 If you specify only one island or one archipelago, the site shows only
  95 arbitrage trades.  If you want single-hop trades within an
  96 archipelago, you must enter the archipelago name twice.
  97
  98 <p>
  99
 100 After getting the results, you can untick various trades individually,
 101 and select `Update' to get a new plan.  The unticked trades will be
 102 excluded from the voyage plan (if any) and also from the totals.
 103
 104 <h3>Vessel capacity</h3>
 105
 106 If you don't specify a vessel or a vessel capacity, the trading plan
 107 will not take into account the fact that your voyage will be on a ship
 108 with a limited size.  This will probably result in a plan
 109 which trades excessively cumbersome goods (eg. hemp, wood, iron).
 110
 111 <p>
 112
 113 So you should specify your vessel capacity.  You can enter things
 114 like:
 115 <dl>
 116 <dt>sloop
 117 <dd>The capacity of a sloop, exactly
 118 <dt>20t 13kl
 119 <dd>20 tonnes (20,000kg), 13 kilolitres (13,000l)
 120 <dt>sloop - 100l 100kg
 121 <dd>The capacity of a sloop minus 100l, minus 100kg
 122 <dt>2t plus 500kg minus 200kg
 123 <dd>2300kg, with no limit on volume
 124 </dl>
 125
 126 Formally, the capacity is a list of terms, all but the first preceded
 127 by one of <kbd>-</kbd>, <kbd>minus</kbd>, <kbd>+</kbd>,
 128 <kbd>plus</kbd>.  Each term may specify a mass and/or a volume
 129 (separated by a space), as a number followed (without an intervening
 130 space) by a unit (<kbd>t</kbd>, <kbd>kg</kbd>, <kbd>kl</kbd> or
 131 <kbd>l</kbd>).  The first term may be a ship name or abbrevation
 132 instead.  If the first term specifies only one of mass or volume, all
 133 the subsequent terms may only adjust that same value.
 134
 135 <h3>Expected losses</h3>
 136
 137 In theory if you were guaranteed to have a trouble-free voyage it
 138 would be worth trading goods at very low margins.  However, in
 139 practice problems can arise: you may be attacked and lose your stock,
 140 or market conditions may change between your collection and delivery
 141 of the goods.
 142
 143 <p>
 144
 145 We model this by pretending that you expect to lose a fixed proportion
 146 of your stock each league you sail.  This expected loss does not
 147 appear in the trade tables (although the distance does), but it does
 148 affect the way the voyage trading plan optimiser chooses which trades
 149 to do.
 150
 151 <p>
 152
 153 Trades whose margin is less than the expected loss are never selected.
 154 For example, if you select 1% loss per league, and plan a voyage of 5
 155 leagues, then any trade with a margin of less than 5.15% would be
 156 completely excluded (5.15% not 5% because the loss works like compound
 157 interest).  Theoretically very profitable trades which are close to
 158 the expected break-even point because of the distance can also be
 159 rejected by the optimiser in favour of shorter distance trades with
 160 theoretically smaller margins.
 161
 162 <p>
 163
 164 As a guide: you may expect to lose between 0.1% and 1% per league.
 165 0.1% would correspond, for example, to losing one fight to brigands
 166 every ten 10-league voyages.
 167
 168 <p>
 169
 170 You can enter the value in the box either as a percentage, or as a
 171 fraction 1/<em>divisor</em>, eg 1/200 is the same as 0.5%; in each
 172 case it is taken as the loss for each league of the voyage.
 173
 174 <& footer &>