X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~yarrgweb/git?p=ypp-sc-tools.db-live.git;a=blobdiff_plain;f=yarrg%2Fweb%2Fdocs;h=10caaee8b7b659b283f84fe98ba65f7dff24575b;hp=b4eb90b8f3a8e185dd29cd1b76c50c4d57879213;hb=ea3cffe854b1c540bc68cd2218fdb2be732197fa;hpb=96b18bbb3e95f4533a0c4eb7d195825e3cb3cb04 diff --git a/yarrg/web/docs b/yarrg/web/docs old mode 100644 new mode 100755 index b4eb90b..10caaee --- a/yarrg/web/docs +++ b/yarrg/web/docs @@ -1,100 +1,295 @@ -%# This is part of the YARRG website. YARRG is a tool and website -%# for assisting players of Yohoho Puzzle Pirates. -%# -%# Copyright (C) 2009 Ian Jackson -%# Copyright (C) 2009 Clare Boothby -%# -%# YARRG's client code etc. is covered by the ordinary GNU GPL (v3 or later). -%# The YARRG website is covered by the GNU Affero GPL v3 or later, which -%# basically means that every installation of the website will let you -%# download the source. -%# -%# This program is free software: you can redistribute it and/or modify -%# it under the terms of the GNU Affero General Public License as -%# published by the Free Software Foundation, either version 3 of the -%# License, or (at your option) any later version. -%# -%# This program is distributed in the hope that it will be useful, -%# but WITHOUT ANY WARRANTY; without even the implied warranty of -%# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -%# GNU Affero General Public License for more details. -%# -%# You should have received a copy of the GNU Affero General Public License -%# along with this program. If not, see . -%# -%# Yohoho and Puzzle Pirates are probably trademarks of Three Rings and -%# are used without permission. This program is not endorsed or -%# sponsored by Three Rings. -%# -%# -%# This Mason component generates the documentation. -%# -YARRG (Yet Another Revenue Research Gatherer) - - -

Introduction to YARRG

-YARRG (Yet Another Revenue Research Gatherer) is inspired by PCTB. - -

Results

- -The lookup page gives access to the uploaded data. - -

Obtaining the client

-The current official version of YARRG for use as a client can browsed here: - http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/ - -

-See particularly the -YARRG README. - -

-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: -

-git-clone http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/.git ypp-sc-tools
-cd ypp-sc-tools
-cd yarrg
-make
-
-this will download the code into the directory ypp-sc-tools, -and build the software. +<%doc> + + This is part of the YARRG website. YARRG is a tool and website + for assisting players of Yohoho Puzzle Pirates. + + Copyright (C) 2009 Ian Jackson + Copyright (C) 2009 Clare Boothby + + YARRG's client code etc. is covered by the ordinary GNU GPL (v3 or later). + The YARRG website is covered by the GNU Affero GPL v3 or later, which + basically means that every installation of the website will let you + download the source. + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero General Public License as + published by the Free Software Foundation, either version 3 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + + Yohoho and Puzzle Pirates are probably trademarks of Three Rings and + are used without permission. This program is not endorsed or + sponsored by Three Rings. + + + This Mason component generates the documentation. + + + +<& docshead &> +

Looking up data in YARRG

+ +YARRG (Yet Another Revenue Research Gatherer) is a third-party tool +for helping find profitable trades and trade routes in Yohoho Puzzle +Pirates. See the Introduction for more details. + +

+ +The Market prices database is the main output +from YARRG. It offers a variety of enquiry options. + +

+ +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. + +

+ +If this page is all too complicated for you, you may prefer to read +the introduction instead. + +

Bookmarkable URLs

+ +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. + +

+ +(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.) + +

Dynamic confirmation of meaning of text entry boxes

+ +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". + +

Trades for route

+ +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. + +

+ +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. + +

+ +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. + +

Vessel capacity

+ +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).

-When new versions are released, you can: + +So you should specify your vessel capacity. You can enter things +like: +

+
sloop +
The capacity of a sloop, leaving no allowance for rum and shot +
wb - 1% +
The capacity of a war brig minus 1% +
13t 20kl +
13 tonnes (13,000kg), 20 kilolitres (20,000l) +
sloop - 10 small 40 rum +
The capacity of a sloop which remains after + 10 small shot and 40 rum are loaded +
2t plus 500kg minus 200kg +
2300kg, with no limit on volume +
+Evaluation is strictly from left to right. + +

+ +More formally:

-cd .../ypp-sc-tools
-git-pull
+ 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
 
-to fetch the new version. -

Free Software (aka Open Source)

+If the first term specifies only one of mass or volume, all the +subsequent terms may only adjust that same value. + +

Expected losses

+ +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. + +

+ +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. + +

+ +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. + +

+ +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. + +

+ +You can enter the value in the box either as a percentage, or as a +fraction 1/divisor, eg 1/2000 is the same as 0.05%; in each +case it is taken as the loss for each league of the voyage. + +

Minimum trade value

-YARRG is Free Software - you may share and modify it. See the -licences for details. +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.

-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 web -directory. +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.

-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, you can download an up-to-date -tarball of the -actually-running website code. +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.

-If you would like to run a (perhaps modified) copy of the YARRG -website it would be very easy for us to 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 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. + +

Caution about stalls' poe reserves

+ +If you select Also be cautious about stalls' poe reserves, +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. + +

+ +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. + +

Available capital

+ +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. + +

+ +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! + +

Locating commodities in the YPP client UI

+ +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; "$&$'" } + @{ $getclasses->fetchall_arrayref() } +%>. +

+ +Then, if applicable, follows a number from 0 to +9 indicating roughly where the commodity is in the +list of commodities of the same class. The number indicates which +tenth of the list is: 0 for the first (top) tenth, +1 for the 2nd, and so on, up to 9 +for the final tenth. + +

+For example, +

+ +
Fine pink cloth   +
C 2
+
+
+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: +
+Fine pink cloth is under Cloth, commodity 14 of 55 +
+

+ +The position indicator digit isn't shown for very small +categories. + +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. - +Also, not all commodities are always completely categorised or +ordered; we are working to add the additional data + <& footer &>