chiark / gitweb /
where-vessels: More improvements to lack-of-ownership handling
[ypp-sc-tools.db-live.git] / yarrg / README.where-vessels
1                         where-vessels
2                         =============
3
4 where-vessels displays a map of the ocean with your ships marked on it.
5
6
7 USAGE:
8 ======
9
10     $ cd .../ypp-sc-tools/yarrg
11     $ ./where-vessels [options]
12
13     Then, in your YPP client:
14       * go to the docks of any island
15       * click on the button "Where are my vessels"
16       * press Ctrl-A Ctrl-C
17
18     In where-vessels, click "Acquire"
19
20 You may well want to create a "vessel-notes" file to get the best
21 use out of where-vessels, see below.
22
23 If you don't have exactly one YPP client open and logged in then you
24 will have to pass --ocean and --pirate options.
25
26 If there was trouble acquiring the data (or loading the notes, see
27 below) you can click on the error message to open a window giving
28 information about the problem.
29
30
31 OPTIONS:
32 ========
33
34  --ocean OCEAN
35      Use map of OCEAN.  Default is to guess by looking for an
36      open Puzzle Pirates client on the same display (logged on
37      as PIRATE, if --pirate was used).
38
39  --pirate PIRATE
40      Supplies the name of your pirate.  If you also supply a notes
41      file (see below) where-vessels will treat ships belonging to
42      PIRATE as your own.  An empty argument means do not care about
43      vessel ownership.  Default is not to care about ownership without
44      notes; with notes, default is to look for a Puzzle Pirates client
45      on the same display (on OCEAN, if --ocean was used).
46
47  --notes SOURCE
48      Use SOURCE as the vessel notes.  See below.
49      SOURCE may be of the following forms:
50        empty argument            No notes, this is the default
51        SCHEME:... eg http:...    URL, fetched with Tcl's http package
52        |COMMAND ARG ARG          command (Tcl list) whose output is the notes
53        NOTES-FILE                ordinary file
54
55  --filter-separate-lock-owner
56      In the filter, show two separate 3-button filters for the lock
57      status, and the ship owner, rather than one 9-button filter with
58      an option for each combination.  (If there are no notes, only
59      one 3-button filter, for the lock status, is shown, anyway.)
60
61  --vessel-info-source RSYNC-SRC
62      Update information about vessels, subclasses, icons, etc. from
63      RSYNC-SRC.  Default is yarrg.chiark.net::yarrg/vessel-info.
64      If RSYNC-SRC is the empty string, do not update and just use
65      local data from icons/* and _vessel_info_cache.
66
67  --clipboard-file FILE
68      Use FILE as the initial clipboard containing a set of vessels to
69      display, rather than waiting for Acquire.  Useful for testing or
70      if you want to save your vessel locations for when you're not
71      logged in.  The easiest way to create a suitable FILE is
72      xclipboard
73
74  --local-html-dir DIR
75      Do not fetch ocean map from Yppedia.  Instead, use copy in DIR.
76
77
78 VESSEL NOTES:
79 =============
80
81 The information collected via the clipboard from the Yohoho Puzzle
82 Pirates client does not include any information about who owns the
83 ship.  (Sadly, it doesn't even include whether the ship is yours, even
84 though this can be seen on the screen by looking at whether the icon
85 has a blue fringe.)
86
87 It also doesn't include any information about how the ship is stocked,
88 what might be recorded on the Officer Notice Board about how it is to
89 be used, etc.
90
91 So to help you make sense of your fleet, where-vessels can read a file
92 of notes about each ship.  The lines in this file are of the form:
93   <vessel-id> <name> = <owning pirate name> [<flags>]
94
95 If your vessel-notes file doesn't mention a ship, you can click on the
96 message "1 warning(s)" below "Reload notes" and it will open a window
97 showing what the problem is.  This will include, for ships missing
98 from the notes, a template line for each ship, eg:
99     # Eta Island:
100     1730081   High Silverside               =
101 Copy and paste the line with the ship name to your vessel-notes file
102 and fill it in, eg:
103     1730081   High Silverside               =  Anaplian   T
104 You probably don't want to copy the line with the island name into
105 your vessel-notes; it's just there to help you identify and find the
106 ship in question (for example if you want to look at it in-game), but
107 it will become out of date if the ship moves.
108
109 Blank lines are ignored, as are lines starting with #.
110
111 It is best if you can arrange to have a single notes file for the
112 whole crew, and find some what to edit it collectively.
113
114 Flags:
115 ------
116
117 The "flags" field has nothing to do with the in-game political entity
118 known as a Flag.  It's a mostly free-form text field, with the
119 following properties:
120  - It is displayed next to each ship on the map (so ships with
121     non-identical flags are not grouped and counted)
122  - You can filter ships by entering a Perl regexp on the flags
123  - It may not contain spaces
124
125 It is therefore usually best to use the flags field for one-letter
126 codes referring to the properties of each ship.  Here is an example,
127 from the Special Circumstances shared vessel-notes file:
128
129 # Don't edit if you're not logged into Puzzle Pirates.
130 # To avoid simultaneous clashing edits, please coordinate with
131 # your other Fleet Officers using the in-game chat.
132
133 # Flags for the column after the owner.
134 #
135 #  L    Ship is public special use.  Eg the chart library.
136 #
137 #  S    Ship is personal special use.  Eg, personal storage
138 #       for a stall or personal trading.
139 #
140 #  P    Ship is stocked and otherwise suitable for pillaging etc:
141 #       It is normally kept well stocked with rum and cannonballs and
142 #       doesn't mind much where it's left.
143 #
144 #  T    Ship is stocked and otherwise suitable for trading or memming:
145 #       It is normally kept stocked with a little rum but few if any
146 #       cannonballs.  It doesn't mind much where it's left.
147 #
148 #  G    Ship is often used for the ad-hoc storage of commodities eg
149 #       as part of trading activities.
150 #
151 #  R    Ship is borrowable but with some restrictions; ONB has details.
152 #
153 #  A    Ship is an auxiliary vessel (eg a supply sloop) or normally
154 #       sails as part of a convoy.
155 #
156 #  DO NOT rely on this file to be up to date.  Check the Officer
157 #  Notice Board before borrowing a ship.