Package: py-starbound-dungeons
py-starbound-dungeonsThis package provides a utility to parseStarbounddungeon files and index the
materials and objects used within them. It is able to accurately parse
both PNG andTileddungeons.InstallationThe easiest way to install is to use pip:pip install py-starbound-dungeonsThe source can be found at:https://github.com/rl-starbound/py-starbound-dungeonsIndex GenerationThe utility provided by this package operates under the assumption that
the user has extracted the game's assets from its.pakfiles. Doing so
is left as an exercise for the user.To generate indices, run the command, giving it source and destination
folders:pystarbound-dungeons-indexer -s assets -d indiceswhereassetsis the path to the unpacked assets folder andindicesis the path to the folder to which the indices will be written. The
program will createindicesif it does not exist, and will overwrite
any indices that already exist underindices.On the author's laptop, the process of indexing all of the Starbound
base assets takes about 35 minutes. It needs to be re-run only if the
indexed assets change, e.g., after a new release of Starbound.Indexing Mod AssetsIn Starbound, mods are applied as an overlay virtual file system, with
the base assets (usually) forming the lowest layer, and mod assets
layered on top, either overwriting or patching lower-ranked assets. The
indexer provided in this package can be used to index mod dungeon parts
as well as those of the base game, however, users should be aware that
it does not attempt to replicate the complexity of the Starbound mod
overlay system, resulting in important limitations:It indexes only one mod at a time.It does not attempt to apply patches. It indexes only PNG and Tiled
JSON dungeon parts.For Tiled dungeon parts, it requires all referenced tilesets to exist
in the correct locations relative to the dungeon parts. In practice,
this usually means that the base game's tilesets must be symbolically
linked into the mod'stilesetsfolder prior to running the indexer.
How to do this varies based on the user's operating system, and is
left as an exercise for the user.It is highly recommended to use a separate destination folder for each
mod, as well as for the base game assets. The following is a recommended
destination folder structure for indexes for the base game and mods:${HOME}/
  starbound-indices/
    base-game/
    mod1/
    mod2/
    ...Index FormatIndices are written in comma-separated values files with the following
columns:layerfor PNG files: RGBAcolor; for Tiled files:gidor blankx-axis coordinate(non-material/mod tiles only)y-axis coordinate(non-material/mod tiles only)tileset name(Tiled materials and objects only)tileset first gid(Tiled materials and objects only)tileset offset(Tiled materials and objects only)entity typeentity nameoptional modifier(s)The primary purpose of this program is to index "interesting" entities
that appear in dungeon parts, such as materials, liquids, objects,
material mods, monsters, NPCs, vehicles, and some stagehands. The author
has chosen not to index "uninteresting" entities such as wiring,
anchors, connectors, and most stagehands. In general, "interesting"
entities as those for which a user would likely wish to search by name.Index Format NotesIn PNG dungeon parts, multiple entities may be recorded as having the
samecolor. This is because some PNG colors are declared in the.dungeonfiles to represent a combination of background layer and
foreground layer or object, or a combination of liquid and object.In PNG dungeon parts, materials and liquids are recorded only once percolor, regardless of how many times that color appears in the part.
Likewise, in Tiled dungeon parts, materials, liquids, and mods are
recorded only once perlayerin which they appear. In both cases, this
is done to avoid exploding the indices with millions of rows of the same
entities.PNG dungeons do not contain layers in the same sense that Tiled dungeons
do. For thelayerfield in PNG dungeon parts, layer names have been
assigned contextually, based on the layer in which a similar entity in a
Tiled dungeon would be placed.In Tiled dungeon parts, ifgidis blank, the three tileset fields will
also be blank, and vice versa. In most cases in Tiled dungeon parts,
whengidis not blank, it will be equal totileset first gid + tileset offset. Cases in which this equality does not hold indicate
that the object's image is flipped horizontally in the Tiled dungeon
part.Index SearchIndices will be written using the same folder structure as the dungeon
files, with one index per dungeon part file. Users can simply open and
read the indices. However, use a of text search tool, such as the Unixgreptool, will allow fast searching for specific entities.Note that, in all given examples, it is assumed that the user uses thecdcommand to enter the top-level folder of the index before entering
search commands.A simple search for any match of microwave in any part of any index:grep -Hr microwave .A search for any object beginning with the word microwave:grep -Hr ,object,microwave .Advanced text search features can be used to narrowly target searches.
For example, grep has extensive support for regular expression pattern
matching. For example, to find any type of material that contains the
word fence.grep -Hr ',material,[^,]*fence[^,]*$' .