</%doc>
-<html><head><title>YARRG (Yet Another Revenue Research Gatherer)</title>
-</head><body>
-
-<h1>Introduction to YARRG</h1>
+<& docshead &>
+<h1>Looking up data in YARRG</h1>
YARRG (Yet Another Revenue Research Gatherer) is a third-party tool
for helping find profitable trades and trade routes in Yohoho Puzzle
-Pirates. It was inspired by
-<a href="http://pctb.crabdance.com/">PCTB</a>.
+Pirates. See the <a href="intro">Introduction</a> for more details.
+
+<p>
+
+The <a href="lookup">Market prices database</a> is the main output
+from YARRG. It offers a variety of enquiry options.
<p>
-The system has two main parts: this website which maintains a
-searchable database of commodity prices, and an upload client, which
-screenscrapes the commodity data from the Puzzle Pirates game client
-and uploads it to the database.
+Hopefully you will be able to work it without too much help, but this
+documentation page contains information about the database website
+which you may not be able to divine from the online user interface.
-<h2><a href="lookup">Market prices database</a></h2>
+<p>
-The <a href="lookup">lookup page</a> gives access to the uploaded data.
+If this page is all too complicated for you, you may prefer to read
+<a href="intro">the introduction</a> instead.
-<h2>Uploading from Linux</h2>
+<h2>Bookmarkable URLs</h2>
-The YARRG upload client uploads both to YARRG and to the
-<a href="pctb.ilk.org">PCTB testing server</a>.
+Mostly, you can bookmark the specific pages and queries. Select the
+ocean, query page, and other combinations of options, as you wish, and
+perhaps fill in the actual data fields too, and bookmark the resulting
+URL.
<p>
-The current official version of YARRG for use as an upload
-client can browsed here:
- <a href="/~ijackson/ypp-sc-tools/master/">http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/</a>
-See particularly the
-<a href="/~ijackson/ypp-sc-tools/master/yarrg/README">YARRG README</a>.
+(An exception to this is if you select the "Update" option from the
+"Trades for route" lookup; the list of (de)selected stalls is too long
+to fit in a URL.)
+
+<h2>Dynamic confirmation of meaning of text entry boxes</h2>
+
+If you have Javascript enabled, the various text entry boxes will be
+annotated with a brief explanation of the system's interpretation of
+your current entry string. To get the actual results updated, you
+must still hit "Go" or "Update".
+
+<h2>Trades for route</h2>
+
+Given a list of islands (or archipelagoes), provides a list of
+potentially profitable trades. If the route is suitable for the trade
+route optimiser, it will generate a complete voyage plan, telling you
+which goods to buy and sell where at which stalls and prices.
+
+<p><a name="arbitrage"></a>
+
+If you specify only one island or one archipelago, the site shows only
+arbitrage trades. If you want single-hop trades within an
+archipelago, you must enter the archipelago name twice.
+
+<p>
+
+After getting the results, you can untick various trades individually,
+and select "Update" to get a new plan. The unticked trades will be
+excluded from the voyage plan (if any) and also from the totals.
+
+<h3><a name="capacity">Vessel capacity</a></h3>
+
+If you don't specify a vessel or a vessel capacity, the trading plan
+will not take into account the fact that your voyage will be on a ship
+with a limited size. This will probably result in a plan
+which trades excessively cumbersome goods (eg. hemp, wood, iron).
<p>
-To install the client, install the `git' version control system
-and the other dependencies listed in the `Installation requirements'
-section of the README and then run:
-<pre>
-git-clone http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/.git ypp-sc-tools
-cd ypp-sc-tools
-cd yarrg
-make
-</pre>
-this will download the code into the directory <code>ypp-sc-tools</code>,
-and build the software.
+
+So you should specify your vessel capacity. You can enter things
+like:
+<dl>
+<dt>sloop
+<dd>The capacity of a sloop, leaving no allowance for rum and shot
+<dt>wb - 1%
+<dd>The capacity of a war brig minus 1%
+<dt>13t 20kl
+<dd>13 tonnes (13,000kg), 20 kilolitres (20,000l)
+<dt>sloop - 10 small 40 rum
+<dd>The capacity of a sloop which remains after
+ 10 small shot and 40 rum are loaded
+<dt>2t plus 500kg minus 200kg
+<dd>2300kg, with no limit on volume
+</dl>
+Evaluation is strictly from left to right.
<p>
-When new versions of the upload client are released, you can:
+More formally:
<pre>
-cd .../ypp-sc-tools
-git-pull
-cd yarrg
-make
+ capacity-string := [ first-term term* ]
+ term := ('+' | '-' | 'plus' | 'minus') (value+ | number'%')
+ value := mass | volume
+ | integer commodity-name-or-abbreviation
+ mass := number ('t' | 'kg')
+ volume := number ('kl' | 'l')
+ first-term := mass | volume | mass volume | volume mass
+ | ship-name-or-abbreviation
</pre>
-to fetch the new version.
-<h2>Uploading from Windows</h2>
+If the first term specifies only one of mass or volume, all the
+subsequent terms may only adjust that same value.
+
+<h3><a name="losses">Expected losses</a></h3>
+
+In theory if you were guaranteed to have a trouble-free voyage it
+would be worth trading goods at very low margins. However, in
+practice problems can arise: you may be attacked and lose your stock,
+or market conditions may change between your collection and delivery
+of the goods.
-There is not currently an upload client for Windows which feeds data
-into YARRG. It would probably be straightforward to modify the
-Windows PCTB v5 upload client to upload to YARRG as well. The
-mechanism and format for uploading is documented in
-<a href="/~ijackson/ypp-sc-tools/master/yarrg/README.devel">README.devel</a>.
+<p>
-<h1>YARRG development, contribution and troubleshooting</h1>
+We model this by pretending that you expect to lose a fixed proportion
+of your stock each league you sail. This expected loss does not
+appear in the trade tables (although the distance does), but it does
+affect the way the voyage trading plan optimiser chooses which trades
+to do.
-<h2>Free Software (aka Open Source)</h2>
+<p>
-YARRG is Free Software - you may share and modify it. See the
-licences for details.
+Trades whose margin is less than the expected loss are never included
+in the suggested plan. For example, if you select 1% loss per league,
+and plan a voyage of 5 leagues, then any trade with a margin of less
+than 5.15% would be completely excluded (5.15% not 5% because the loss
+works like compound interest). Theoretically very profitable trades
+which are close to the expected break-even point because of the
+distance can also be rejected by the optimiser in favour of shorter
+distance trades with theoretically smaller margins, if it's not
+possible to do both.
<p>
-Not only the client but also the webserver code is Free. The website
-code can be found in the same tree as above, in the <code>web</code>
-directory.
+As a guide: you may expect to lose between 0.01% and 1% per league.
+For example 0.1% would correspond to losing one fight to brigands (who
+take 10% if they win) for every 100 leagues sailed.
<p>
-But in case we have made changes but not yet pushed them
-(perhaps because we haven't done a release), and to make it easy for
-anyone else who runs a copy of the website to provide everyone with
-the source for their version, the website code itself lets you download
-an up-to-date <a href="source.tar.gz">tarball</a> of its
-actually-running source code.
+You can enter the value in the box either as a percentage, or as a
+fraction 1/<em>divisor</em>, eg 1/2000 is the same as 0.05%; in each
+case it is taken as the loss for each league of the voyage.
+
+<h3><a name="minprofit">Minimum trade value</a></h3>
+Often there are many low-volume, low-value trades. It can be rather
+labour-intensive to buy and sell a dozen different commodities, half
+of which are only making a few poe each.
+
+<p>
+
+The "minimum trade value" specifies a minimum profit that you would
+like to get from each (commodity, collect island, deliver island)
+triplet. Trades which don't meet this minimum will start out unticked in
+the "Relevant trades" table and will not be included in the voyage
+trading plan.
+
+<p>
+
+If you want to change your threshold, you have to select "Apply",
+which will automatically tick and untick all of the tickboxes for in
+"Relevant trades", as appropriate. This will undo any customisation
+of the set of trades you have already done by manually ticking and
+unticking individual trades.
+
+<p>
+
+The value is an absolute poe amount, typically 5 or 10, representing
+the minimum profit to make it worthwhile (from a time and effort point
+of view) clicking in the YPP client to collect and deliver a
+commodity. Setting a higher threshold will make each island visit
+faster, by excluding trivial transactions, and so reduce the chance
+that market conditions change adversely during your voyage.
+
+<h3><a name="poelimit">Caution about stalls' poe reserves</a></h3>
+
+If you select <b>Also be cautious about stalls' poe reserves</b>,
+YARRG will calculate a minimum amount of poe that each stall has on
+hand (by looking at all the offers that stall is making), and never
+plan for you to sell goods at that stall for more than the available
+poe.
+
+<p>
+
+Goods planned to be bought at the stall (which might boost the stall's
+poe reserves) are not considered, to avoid having to calculate the
+stall's cash reserves at various different times.
+
+<h3><a name="capital">Available capital</a></h3>
+
+If you don't specify the amount of capital you have available to
+invest in the voyage, the trading plan will assume that your capital
+is unlimited. If you specify an amount in PoE here, the trading plan
+will never require you to spend more than that amount on commodities.
+
+<p>
+
+The trading plan does not take into account accumulated profits from
+each leg of the journey when applying the available capital
+constraint. For example, if you specify a journey from A to B to C
+and a capital limit of 10000 PoE, the trading plan will not tell you
+to buy 1000 peas at A for 10 PoE each, sail them to B and sell all of
+them for 20 PoE each, and then buy 2000 beans at B for 10 PoE each and
+sail them to C to sell for 20 PoE each even if such a trade would in
+fact be possible. In practice this is unlikely to be a problem!
+
+<h3><a name="posinclass">Locating commodities in the YPP client UI</a></h3>
+
+In the Voyage Trading Plan, YARRG indicates after the commodity name
+where in the YPP commodity UI each commodity can be found. First
+comes the initial letter of the category:
+% my $dbh= dbw_connect('Midnight');
+% my $getclasses= $dbh->prepare(
+% "SELECT commodclass FROM commodclasses ORDER BY commodclass");
+% $getclasses->execute();
+<%
+ join '; ', map { $_->[0] =~ m/^./ or die; "<strong>$&</strong>$'" }
+ @{ $getclasses->fetchall_arrayref() }
+%>.
+<p>
+
+Then, if applicable, follows a number from <strong>0</strong> to
+<strong>9</strong> indicating roughly where the commodity is in the
+list of commodities of the same class. The number indicates which
+tenth of the list is: <strong>0</strong> for the first (top) tenth,
+<strong>1</strong> for the 2nd, and so on, up to <strong>9</strong>
+for the final tenth.
+
+<p>
+For example,
+<blockquote>
+<table><tr>
+<td>Fine pink cloth
+<td><div class=mouseover
+ title="Fine pink cloth is under Cloth, commodity 14 of 55">C 2</div>
+</table>
+</blockquote>
+indicates that Fine pink cloth can be found under Cloth,
+between 20% and 30% of the way down through the types of Cloth.
+If you mouseover that in a suitably equipped browser you should see the
+text:
+<blockquote>
+Fine pink cloth is under Cloth, commodity 14 of 55
+</blockquote>
<p>
-If you would like to run a (perhaps modified) copy of the YARRG
-website it would be very easy for us to make our system send you
-copies of updates submitted by users of the official YARRG client, in
-the format expected by the code you'll be running. Please just ask
-us.
+The position indicator digit isn't shown for very small
+categories.
-<h2>Contacting the YARRG developers</h2>
+The exact location of the commodity in the actual game
+client may vary because YARRG only considers the list of all possible
+commodities, not the list of actual offers at the island in question.
-Email Ian Jackson ijackson (at) chiark.greenend.org.uk. Or talk to
-any Fleet Officer or above of the crew Special Circumstances on the
-Midnight Ocean.
+Also, not all commodities are always completely categorised or
+ordered; we are working to add the additional data
-<& footer, isdocs => 1 &>
+</div>
+<& footer &>
~yarrgweb / ypp-sc-tools.db-test.git / blobdiff