Ruby VGA-Planets Viewer

Warning: currently RVV only runs on X-based systems (due to the GUI only being available in Ruby-Wise). Volunteers to port to ruby-gtk2 or ruby-qt very much appreciated.

Note: This documentation reflects RVV 0.6. If you have an older version, upgrade. If you have a newer version, I'm late in adapting these docs... (I am late, NicM's wx version is totally different from this Wise based GUI).

Running

Run RVV from the command line with:

   ruby vgap/rvv/wise.rb [gamedir [... [...]]]

where the gamedir defaults to "./" and any other set of directories can be specified. RVV will look for files in all of these directories, in the order specified; first the lower-case name, then the upper-case name, only then look in the next directory. Likely, you'll need a second directory at most, which contains files like hullspec.dat (a typical PHost trick).

RVV can be used to view maps, if only xyplan.dat is available. If that file is missing, RVV will terminate (a bit rude, but stating where it looked for the file), Since RVV is map-based. All info to view starts with the map, to get overviews. Details of objects come second.

RVV can also view hulls if only *spec* and truehull.dat are available (next to xyplan.dat...).

It is recommended to use RVV on complete games (specifically use a correct race.nm or RVV will crash pretty soon), or explicitely view the current turn only (use the --no-history option) and refrain from simulating hostruns.

History Database

RVV should launch one single window and dump a lot of text. It probably says a lot of

 (WARN) Requested TRN Universe XXX, while there is no RST Universe

. RVV tries to access gamedir/XXX/ and looks in that directory for RSTs, TRNs, configs and starmaps from turn XXX. When using PHost, it will also take util??.dat and race.nm from that directory. RVV (and also JVPC) creates these directories and copies files into them.

All these directories together thus contain a complete history of your game. If you ever wish to pass data onto a new ally or someone that takes over a game from you, everything is in there.

Upon this, RVV creates its own database that collects The Most Current Information of all (enemy) objects. This speeds up start-up. It is stored in the same subdirectories under the name accum.txt. If you throw these files away, they will be regenerated. For security reasons, never use such a file you received from someone else (hey, you can't merge these files, even if they are from the same game: you need the RSTs and TRNs from that other person. Insist.)

Finally, RVV will keep files user.txt in the same subdirectory, containing information the user set (markers, or even additional fields of objects on the map, which are taken into account by the host-simulation).

The User Interface

Once the main window pops up, most things can/must be done with the mouse. There are also a few keys that do useful things:

TAB	Zoom in
Shift-TAB	Zoom out
Ctrl-TAB	Zoom such that the entire map fits in the window
z	Center curent object/mouse position
q	Quit RVV

Mouse will select the object stack closest by and will pop up a window with a list of those objects. Each can be selected to get (almost) all known information (see below) about that object. It will also place a crosshair to indicate where you clicked. It is supposed to show warp- and HYP circles as well, but somehow you need to let the map redraw; select something and then (depending on X backing store...) either re-select or press 'z' is a nice work-around.

It will also list minefields, ionstorms and wormholes the object stack is inside of (not just centered).

Finally, it will list multiple objects that are shown at the same location on the screen when zoomed out, but need not be at the same location in terms of in-game lightyears.

Information and Editing

When an object is selected, you'll see condensed information on top and (in the current turn, since v0.6) a series of input-widgets for fields that are not 'current' (There is no intelligence that determines which fields to show, combine or translate to something intelligible; there is no mechanism to protect you from setting illegal values, but rvv will crash on it; rvv is still beta). You can set a value, which RVV will remember and use when simulating a hostrun. There is no intelligent screen updating. The simulation won't be rerun until you have pressed Reload. Had I mentioned RVV is beta?

The source of a value is also indicated, directly after the widget:

a plain number means you saw the value in your RST in that turn,
"U" means you set the value yourself, in the turn you are now viewing,
"dXX" means rvv derived the value from turn XX, when you saw the value in your RST,
"uXX" means rvv derived the value from turn XX, when you set it yourself.

Menubar

Since RVV v0.5.7. Both Planets and Ship have a Find, Marker, Query and Summary item; Minefield has only a summary; Message has one item, which will show you (hopefully) all interesting messages for you as player, e.g. minefield scans have been interpreted and filtered out; Marker gives two simple options,

Find Pops up a window where you can fill in the ID of the planet/ship you want to find,
Marker Allows you to add a Marker, which is hooked to a planet (should be useful with Relics moving planets addon) or ship,
Query Allows an extra filter upon the selection of planets and ships, explanation in the next paragraph,
Summary For planets and ships, pops up a list as if you clicked on the map, but now with all relevant planets and ships in it (by the vertical bar and the query); For minefields, gives another type of summary.

Since 0.5.12, Ship also contains the "Hull..." entry, which pops up a hull calculator. Just click away to find the price of parts and total ship, both in minerals and megacredits. Shows mass, fueltank and cargospace as well. You can open multiple of these calculators.

Query

The query allows you to select those planets or ships for which your given line evaluates to true (plain Ruby eval() call). This enables you to select a set of objects that doesn't meet the default selecting capabilities. Note that anything unequal to nil or false in Ruby evaluates to true (that's including 0 for you C-hackers out there; that's also why the default query "pl" shows all planets, but an empty query shows none).

A few examples:

not pl.arctic? and not pl.tropical? show only planets with a normal temperature,
pl.within_range(2000, 2000, 500) show planets within 500 LY of the center of the map at (2000, 2000),
pl.nat_race == Bovinoid show only bovinoid planets,
pl.neutronium > 1000 show all planets with more than 1000 neutronium on ground,
sh.hull.name =~ /freighter/i only look at freighters (case insensitve regexp; I'll figure a better way for this in the future)
pl.id > 110 and pl.id < 200 only look at bases (planets) with ID in between 111 and 199, which may be interesting after the ship-limit has been reached, like pl.fc =~ /PB./
...

Selecting a Universe

The second topmost bar allows you to choose which universe you want to see.

Reload Button

Whenever you save data with another client, you can hit reload and RVV will read the data and update the applicable universes.

Reload will also read a new RST when placed in the gamedir.

Note: after a rehost, quit RVV, remove the subdir of the current turn number, (remove gen*.dat ?) and restart RVV.

w/History, w/User, Trn, Rst

Allows choice between four types of universes, all belonging to one turn.

w/History By far the most interesting, since it shows the most recent values for all known objects and their fields.
w/User Skips historical ("derived") data, but still shows user-entered data,
Trn Only shows the known objects and fields of this turn. This allows for a quick visual toggle, whether objects are seen this turn or not.
Rst Shows data as if you had just unpacked your RST, without giving any commands. Useful when you want to see an original value (which is mostly "had I (effectively!) set this value previous turn?" but faster than looking up the previous turn :). Also shows extra information of minefields.

SimHost

An attempt at predicting the next turn. For the moment, predicts:

Movement of ships (but running out of fuel will certainly put your ship in the wrong place), include gravitonic, hyperjump, tow, intercept,
Producing minerals and supplies with mines, factories and bovinoids,
Native and Colonists income, growth, death and happiness,
Loading and Building fighters and torpedoes on ships,
Mine laying, sweeping and decay (how to deal with max minefield size?), no scooping, yet,
Glory Devices exploding,

For the original THost only (guess when I play PHost, I'll follow suit with an implementation for PHost :) I prefer PHost, but got lured into a second THost teamgame with the people from IRC.

Verify

Verifies the host simulation, by taking the universe from the previous turn, predicting from that the RST of this turn. All failing equalities are printed. Limits comparison to what can be predicted (and even then, not exhaustive). Mean use is for the authors, to measure how well SimHost functions.

Selecting Objects

The leftmost, vertical bar allows you to pick what types of objects you want to view on the map. From top to bottom: Planets, Bases, Ships, Minefields, Ionstorms, Wormholes, Markers, 0 (objects known to be unowned) and 1-9,a,b are objects of the 11 races.

Selecting Fields

The last bar (horizontal; third from top) allows you to pick which fields are shown visually on the map itself.

distance

The 'd' stands for distance and has three modes: '--' (off, default), 49, 64, 81 and 162 to show which planets are within 49, 64, 81 and 162 LY of each other, respectively.

coverage

In dark blue areas, RVV can show what you scan, one of the following: Ships-in-range, Sensor Sweep, Minescan, Bioscan, Dark Sense and Tachyon (Loki; due to small range not very useful).

owner

'own' toggles whether objects are given a color, based on their ownership.

cargo

n, t, d, m, s, $ and cl toggle circles for neutronium, tritanium, duranium, molybdenum, supplies, mega-credits and colonist clans. (The blank button will do Fish in the future.) The radius grows with the square root of the amount (so any visible circle means there is something on the planet, but 10000 won't show a huge circle).

The dashed circles show the amount directly available (minerals on ground), the partial, full-stroke circles for the four minerals show the amount in-core, where a full circle means a density of 100%, half a circle 50% and so on.

When the colonist clans becomes pink, your colonists are less than 70% happy. The color will grow more red when they become even unhappier.

temp

Temperature. Purplish is habitable. Tropical planets are bright red, icy planets are bright blue.

natives

Lists the amount of natives (clans divided by 100), their happiness and their race. The color indicates how much mega-credits you can collect from them (when their happiness is not supposed to go down, but without additional structures on the planet). Bright white is a cash-cow, soft grey is a few mega credits only. It is a good indicator, not showing the actual amount you'll receive when you colonize the planet.

Yellow indicates bovinoids (matching the yellow for supplies).

structures

Mines, Factories, defense, Base defense and Base fighters are shown, together with the maximum. Finally, with "act" industrial activity from Sensor Sweep can be shown.

Zoom

Zooming in with a factor of 1.0 or higher will show the fields of a planet.

Zoom factor 1.0 means 1 pixel per LY. Zoom factor 2.5 means two and a half pixel per LY.

Config file

Note: config file is disabled while the options are in flux.

The file rvv-wise.cfg (as well in ~/.rvv/, in turn overridden by a file of the same name in the gamedir) can set various things. Example:

 FontName = "7x13" SwitchZoom = 1.0 PlayerColor[9] =
Wise::Color.new(105, 105, 255)

It is actually Ruby code you see there (this isn't a security hole, as long as those that can write the file can execute the ruby interpreter under the same permissions; since you shouldn't even allow other people to read your VGAP data (they might be enemies), this should be handled properly).

Command line Options

Getting in shape. Accepts: --help (print help and exit) --version (print version and exit) --turns (takes a series of numbers, comma separated, also accepts ranges, like --turns=3,5-7,12..22; default 0..12345) --no-history --no-rst (don't look for RST for current turn, still use it for history) --dont-save --recreate-history (ignore exisintg XXX/accum.txt; generate/overwrite them) --minzoom=float (default 0.01) --maxzoom=float (default 100.0) --switchzoom=float (default 1.0) --font=string (default "7x13") I don't think --quiet and --verbose do anything :)

Like this site?

EC Karma++

Kero

Home + iPAQ-screenshots

License

To Do

Find	Pops up a window where you can fill in the ID of the planet/ship you want to find,
Marker	Allows you to add a Marker, which is hooked to a planet (should be useful with Relics moving planets addon) or ship,
Query	Allows an extra filter upon the selection of planets and ships, explanation in the next paragraph,
Summary	For planets and ships, pops up a list as if you clicked on the map, but now with all relevant planets and ships in it (by the vertical bar and the query); For minefields, gives another type of summary.