pystarboundmap 1.0.0b7

Description:

pystarboundmap 1.0.0b7

Python Starbound Mapper
Yet another Starbound mapper!
This project is a reasonably basic Starbound map viewer, focusing on a few
simple map introspection tasks, rather than on 100% accurate map rendering. It
does pretty much everything that I'd been hoping to have in a viewer when
starting out, such as: looking for interesting areas to head while spelunking;
checking my home base for "holes" in the background tiles; clicking on tiles to
get some detailed information such as the images being used, etc.
The app is far from perfect, and in specific could really use some performance
improvements, but my time playing Starbound is more or less at an end, and my
impetus to hack on the map viewer further is pretty much nil. A quick glance
at the screenshots below will show that the blocks are rendered as simple
squares rather than with all their borders, that platforms don't link up with
each other, and that objects aren't currently rendered in their correct
orientations (or even variations, in most cases). It doesn't yet attempt to do
correct color tinting or the like, either. What you see is what you get!
I would, of course, be happy to accept pull requests which address any of the
items on my TODO list, below -- or other features not on the TODO list -- but
I'm no longer actively developing this, myself.
Installation
Pystarboundmap requires Python 3, and is a PyQt5 app. Python 2 is not supported.
Installation to system / user / virtualenv
The easiest way to install/use the mapper is with pip, via:
$ pip install pystarboundmap

Alternatively, from a git checkout you can install with the usual setup.py syntax:
$ python setup.py install

In either case, then run it from anywhere using the pystarboundmap script:
$ pystarboundmap

Running via local git checkout
If you'd prefer to just run it from the git checkout, you can install its
dependencies with:
$ pip install -r requirements.txt

Then launch the GUI with:
$ python -m pystarboundmap.gui

Dependencies
The project makes use of the following:

Python 3
python-pillow
PyQt5
appdirs
timeago
py-starbound (by blixt)

Usage
The game will attempt to autodetect your Starbound installation directory
(which is completely untested on Windows, so please let me know if that
fails completely). If the install directory can't be found, the app will
prompt you to choose it manually (and this can be changed later via the Edit -> Settings menu).
The default "Open" dialog will let you choose a world to open first by
player name, and then by the world name. You can get a more standard
file-opening dialog with Ctrl-Shift-O, but this dialog should be much
friendlier:

The map will start out centered on the level spawn point, though if the
level contains a mech beacon, it will be centered there instead (since
levels with mech beacons generally don't have anything interesting around the
spawn point). Once on the main screen, the functionality is pretty basic:

The information about the currently-hovered tile will be shown on the lefthand
side of the screen, which can be resized by dragging on the edge. You can
scroll using the scrollbars or by click-and-drag on the map itself. You can
zoom in using the slider, or with the keyboard shortcuts + and -.
The various layers can be toggled on/off, so if you wanted to check for holes
in the background tiles of your home base, or something, that may be useful.
There are also toggles to draw the background tiles much lighter, so they're
easier to see, and toggles to show the "anchor" points for both objects and
plants. This is seen in the screenshot, where the object anchor points are in
blue. Plants will be in green.
To get more detail about a tile, click on it to bring up a dialog with the
extra details:

You can also use Ctrl-I or View -> World Info to get information about
the world itself:

The "Navigate" menu will let you go directly to a specific coordinate, the
spawn point, the level mech beacon (if one exists), the "current" player
location (if this is the map the player is currently on), or to any bookmarks
set by the user. Note that you must load the world using the by-name
dialog rather than the by-file open dialog, in order to have bookmarks
and/or current location in the Navigate menu -- that information is stored
in the Player object.

TODO

Add NPCs/Enemies/Monsters/Vehicles?

(What's a StagehandEntity, I wonder?)


Minimap

I'll have to see how feasible this is - I'd imagined just a simple
little thing to show which regions have data and which don't, with
a little box showing the currently-displayed area, but it feels like
the game populates more regions than you might expect, and I suspect
it wouldn't actually be that useful


Search for item types (ores, quest-related things?)

This is something which probably made more sense when the app was
attempting to load literally the whole map at once. Might not be
worth it with the current more-limited loaded set.


Visualization of explored areas (as defined by light sources)
Autodetect game location improvements

Theoretically we autodetect Steam install locations now (Steam detection
on Mac has at least one success, so it's only Windows Steam dir
detection that's untested)
Completely untested on Windows
Any way to detect GOG installs?
Any registry entries or whatever in general for Windows, which aren't
Steam/GOG specific?


Support for mods
Performance improvements

Resource loading:

There's probably an unnecessary PNG conversion happening during
some of the image loading, though these aren't really problematic
and we're only loading 'em on-demand now anyway.


Specific tile types

Scenes with lots of liquids get bogged down a bit...


Map loading/rendering:

This is pretty slow, and I'll have to profile it to figure out
where the slowness actually is. It's more of an annoyance at
the moment, though, since we're now only rendering the visible
areas of the map, rather than loading the entire thing at the
app startup
Render more than just a single extra region on each side?
Would like to move map loading into a separate thread so it can
happen more in the background, rather than freezing the GUI
while it loads. (Using the mouse scrollwheel especially is
quite jerky because of this.)
Keep a "history" of loaded Regions and only expire them after
they haven't been used in N redraws? That way, scrolling back
to a previously-visited area would be less likely to have to re-load.
One thing which is slower than I'd like is the expiration of
Regions. It's noticeable at 1x zoom, but my experiments with
going to 0.5x zoom produced some really pronounced pauses.
Should see if there's a way to speed that up. (Though the region
"history" in the point above would at least delay those slowdowns
for a bit.)




Rendering improvements

Parsing and using render templates (or at the very least making our
own internal representation of them) would allow materials to have
proper "edges", for platforms/pipes/rails to link up properly, etc.
Liquid levels
on/off items (light sources), open/closed doors, etc
coloration of objects/tiles
"flip" parameter
crop status

Unrelated to rendering specifically, but we could probably report
on crop progress in the tile info dialog.


Randomize tiles w/ multiple options (dirt, etc, seems to be randomly
assigned from four or five options. The randomization is fixed-seed
inside Starbound itself, and I highly doubt I'd be able to get it the
same, but maps would probably still look nicer with them randomized)
Layer improvements - right now we're right enough most of the time,
but your own space station is one which doesn't render right at all.
Should really figure out Starbound's native layer priority and use
objects' "renderLayer" property.


Handle exceptions gracefully

An easy crash reproduction is to have a map open, load it in Starbound,
then try to browse around. Starbound seems to shuffle the tree around
enough that we can no longer read it.
Make sure we gracefully handle situations where the Starbound install dir
disappears on us between runs; I suspect right now the app will just crash
and the only way to get it to run again would be to manually clear out the
config file.


Should we save the layer toggle states (and zoom level) between runs?
Also the "show biome/dungeon details" checkbox on the load dialog?
Read in codex files, to report the real name in container contents. This
will require actually lexing the config files in read_config, though,
instead of just doing the poor-man's processing we're doing now. The codex
files feature multiline strings (without anything but a dangling quote to
distinguish them), sometimes feature escaped quotes inside the text, and
sometimes feature a double-slash, which gets interpreted as a comment. Not
worth it for me, at the moment.
Would be nice if the zoom kept the map view centered on the mouse
pointer, when using the keyboard zoom shortcuts
Would be nice if the world-info caching progress bar went from 0->100%
instead of being a more generic "something is happening" bar.
Fossil display cabinets render completely wrong

LICENSE
pystarboundmap is licensed under the
New/Modified (3-Clause) BSD License.
A copy is also found in COPYING.txt.