X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~yarrgweb/git?p=ypp-sc-tools.db-test.git;a=blobdiff_plain;f=yarrg%2Fweb%2Fdocs;h=564aadc72e7735fd23ecfcee705dcf23b73ee0dd;hp=0ea31cfcc35a9cb8a79facad29dfee2fb17a04bf;hb=8389c1d520e0b70f79fc2ce72b4840b0f9e96700;hpb=38888dbd9221f97b1886ee545d0113c88432556a diff --git a/yarrg/web/docs b/yarrg/web/docs index 0ea31cf..564aadc 100755 --- a/yarrg/web/docs +++ b/yarrg/web/docs @@ -33,106 +33,150 @@ -YARRG (Yet Another Revenue Research Gatherer) +Website documentation - YARRG -

Introduction to YARRG

+YARRG - + Yet Another Revenue Research Gatherer +| +development +| +introduction +| +documentation + +

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. It was inspired by -PCTB. +Pirates. See the Introduction for more details.

-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. +The Market prices database is the main output +from YARRG. It offers a variety of enquiry options. -

Market prices database

+

-The lookup page gives access to the uploaded data. +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. -

Uploading from Linux

+

Bookmarkable URLs

-The YARRG upload client uploads both to YARRG and to the -PCTB testing server. +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.

-The current official version of YARRG for use as an upload -client can browsed here: - http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/ -See particularly the -YARRG README. +(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.

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

-When new versions of the upload client are released, you can: -

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

Uploading from Windows

+

Vessel capacity

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

YARRG development, contribution and troubleshooting

+

-

Free Software (aka Open Source)

+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% +
20t 13kl +
13 tonnes (13,000kg), 20 kilolitres (20,000l) +
sloop - 100l 100kg +
The capacity of a sloop minus 100l, minus 100kg +
2t plus 500kg minus 200kg +
2300kg, with no limit on volume +
+Evaluation is strictly from left to right. -YARRG is Free Software - you may share and modify it. See the -licences for details. +

+ +Formally, the capacity is a list of terms, all but the first preceded +by one of -, minus, +, +plus. Each term may specify a mass and/or a volume +(separated by a space), as a number followed (without an intervening +space) by a unit (t, kg, kl or +l). Alternatively each term except the first may specify a +percentage, which is applied as a percentage change to the answer from +all the preceding terms. The first term may be a ship name or +abbrevation instead. 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.

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

-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 tarball of its -actually-running source code. +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.

-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. +As a guide: you may expect to lose between 0.1% and 1% per league. +0.1% would correspond, for example, to losing one fight to brigands +every ten 10-league voyages. -

Contacting the YARRG developers

+

-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. +You can enter the value in the box either as a percentage, or as a +fraction 1/divisor, eg 1/200 is the same as 0.5%; in each +case it is taken as the loss for each league of the voyage. -<& footer, isdocs => 1 &> +<& footer &>