Metadata-Version: 2.1
Name: pystarboundmap
Version: 1.0.0b7
Summary: Starbound Map Viewer
Home-page: https://github.com/apocalyptech/pystarboundmap
Author: CJ Kucera
Author-email: cj@apocalyptech.com
License: BSD License
Description: 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](https://github.com/blixt/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:
        
        [![Open By Name](https://raw.githubusercontent.com/apocalyptech/pystarboundmap/master/screenshots/open_by_world.png)](https://raw.githubusercontent.com/apocalyptech/pystarboundmap/master/screenshots/open_by_world.png)
        
        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:
        
        [![Main Window](https://raw.githubusercontent.com/apocalyptech/pystarboundmap/master/screenshots/mainwindow.png)](https://raw.githubusercontent.com/apocalyptech/pystarboundmap/master/screenshots/mainwindow.png)
        
        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:
        
        [![Tile Info](https://raw.githubusercontent.com/apocalyptech/pystarboundmap/master/screenshots/tileinfo.png)](https://raw.githubusercontent.com/apocalyptech/pystarboundmap/master/screenshots/tileinfo.png)
        
        You can also use `Ctrl-I` or `View -> World Info` to get information about
        the world itself:
        
        [![World Info](https://raw.githubusercontent.com/apocalyptech/pystarboundmap/master/screenshots/worldinfo.png)](https://raw.githubusercontent.com/apocalyptech/pystarboundmap/master/screenshots/worldinfo.png)
        
        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.
        
        [![Navigate Menu](https://raw.githubusercontent.com/apocalyptech/pystarboundmap/master/screenshots/navigate.png)](https://raw.githubusercontent.com/apocalyptech/pystarboundmap/master/screenshots/navigate.png)
        
        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](https://opensource.org/licenses/BSD-3-Clause).
        A copy is also found in [COPYING.txt](COPYING.txt).
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
