diff options
| -rw-r--r-- | README.md | 362 | ||||
| -rw-r--r-- | TODO.txt | 28 |
2 files changed, 315 insertions, 75 deletions
@@ -1,54 +1,45 @@ -# vgstash - a place to stash your game collection +# VGStash - meaningful game collection tracker -If you love video games, you've probably amassed a collection of them, across -many different systems and platforms, both physical and digital. At some point, -a player may want to know a few key pieces of information that may steer their -gaming. These questions are great for quelling boredom and keeping a gaming -backlog manageable: +VGStash is a video game collection tracker that gives the user a number of +fields to track their games with, including ownership, progress, and notes. It +also comes with a set of filters that give users the ability to make meaningful +inquiries to their collection. -* Which games do I own? -* Which games have I beaten or completed? -* Which games do I need to beat? -* What was the note I left for X game? -* Which games do I have more than one copy of? - -vgstash seeks to answer these type of questions in a simple and extensible way. +For the nerds, VGStash is written in [Python 3](https://python.org) and is +mostly powered by [SQLite](https://sqlite.org) via internal VIEWs. It's +available under the [AGPL-3.0-only][spdx-agpl3] license. # Installation -vgstash is available via `pip`: +There is a [VGStash PyPI page](https://pypi.org/project/vgstash), and it is +available via `pip`: ~~~ pip install [--user] vgstash ~~~ -Once everything's installed, just run `vgstash init` from a shell to get -started. +If you are a developer, the source can be cloned via Git: + +~~~ +git clone https://git.zlg.space/vgstash +# or, if the above isn't online... +git clone https://notabug.org/zlg/vgstash +~~~ # Concept -The core concept of vgstash is the game itself. Every game in a player's +The core data structure of VGStash is the Game. Every Game in a player's collection has a few important attributes, all of which are obvious to the player: * Title * System -* Ownership - * unowned - * physical - * digital - * both -* Progress - * unbeatable - * new - * playing - * beaten - * complete -* Notes +* Ownership – in what form do you possess it? +* Progress – how far are you in it? Think of any game that you have a history with. Let's say it was a game you bought as part of a Humble Bundle, but haven't started playing yet. Internally, -vgstash tracks it somewhat like this: +VGStash tracks it somewhat like this: ``` .--------------------------------------------------------. @@ -58,26 +49,274 @@ vgstash tracks it somewhat like this: '--------------------------------------------------------' ``` -This is the bare minimum information you need to meaningfully track a video -game in your collection. +This is the bare minimum information you need to meaningfully track a video game +in your collection. With it, you can begin to ask and answer questions you may +have about your collection. + +# Python Usage + +Importing the `vgstash` module is enough to get started! + +Here's a basic script that imports VGStash, initializes a database, records a +single game, and lists its contents: + +```python +#!/usr/bin/env python3 +# a minimalist vgstash client +import vgstash + +# Create a DB in RAM, just for fun. +mydb = vgstash.DB(path=":memory:") + +# Make sure our database schema is in place. +mydb.create_schema() + +# Define and add our game. Note that you can reference the internal numbers via +# pre-defined dictionaries. Use the integers directly at your own risk! +mygame = vgstash.Game("Golden Sun", "GBA", vgstash.OWNERSHIP["physical"], vgstash.PROGRESS["beaten"]) +mydb.add_game(mygame) + +# list out the games we have! vgstash.list_games returns an iterable, so for +# best results you'll want to output in a loop of some sort. +for game in mydb.list_games(): + print(game['title'], "for", game['system']) +``` + +If the output from the above is `Golden Sun for GBA`, everything works and +you're ready to start hacking a game collection into your code! # Command Line Usage -vgstash comes with a command line client of the same name, which gives you -high level commands to manipulate the database with. It's the reference -implementation for a vgstash client. +VGStash comes with a command line client of the same name, which gives you +high level commands to manipulate the database with. -If you wanted to add the above game to your collection, you'd do it like this: +If you wanted to add the example game from earlier to your collection, you'd do +it like this: ```bash -$ vgstash add 'FTL: Faster Than Light' Steam d n -Added FTL: Faster Than Light for Steam. You digitally own it and you have not started it. +$ vgstash add 'FTL: Faster Than Light' Steam d n "Bought-From: Humble Bundle\n\nThis game is cool." +Added FTL: Faster Than Light for Steam. You digitally own it and you have not +started it. It also has notes. +``` + +Pretty easy, huh? Each title and system added to VGStash is free-form and can be +tuned to match the user's preferences. This allows one to specify between +different platforms within another platform, such as Steam or Origin instead of +just PC. Some may want to differentiate Virtual Console games from regular games +on those systems. In either case, both are text fields. + +In the above command, the `digital` ownership was abbreviated to just `d`, and +the `new` progress was shortened to `n`. This is allowed when specifying values +for these fields! It cuts down on typos and excessive repetition. Consideration +is made for any new values in these fields, so each option should start with a +different letter and abbreviations should be forward-compatible. + +It looks like we added notes to that game, too...? + +``` +$ vgstash notes 'FTL: Faster Than Light' Steam +Notes for FTL: Faster Than Light on Steam: + +Bought-From: Humble Bundle + +This game is cool. +``` + +*Nice!* + +## Commands + +VGStash has a fairly small set of commands. For each command's description, +arguments in brackets are optional + +### add + +``` +add TITLE SYSTEM [OWNERSHIP] [PROGRESS] [NOTES] +``` + +Adds a game to the database. + +`OWNERSHIP` may be one of: physical, digital, both, member + +`PROGRESS` may be one of: unbeatable, new, playing, beaten, complete + +`NOTES` should be a fully-quoted string, with newlines escaped + +--- + +Adding a game is trickier than it seems; the OWNERSHIP and PROGRESS fields are +important to get right if you want the game tracked correctly. Here are some +game archetypes: + +* *Normal releases* can be physical, digital, or both, and any progress +* *Collections* can be physical, digital, or both, but must be unbeatable +* *Members of a collection* should be stored under the original release system, + with an ownership of 'member', and tracked progress where applicable + +In short, don't count a collection as part of your progress! Add the individual +games in that collection, then mark the collection game as unbeatable. + +Internally, members do not get listed for ownership filters, because *the +collection* is the item the user owns. Here's an example straight from ZLG's +VGStash: + +``` +Title | System | Own | Progress +----------------------------------------------------------------- +Mega Man ZX | DS | M | C +Mega Man ZX Advent | DS | M | C +Mega Man Zero | GBA | M | C +Mega Man Zero 2 | GBA | M | C +Mega Man Zero 3 | GBA | M | C +Mega Man Zero 4 | GBA | M | C +Mega Man Zero/ZX Legacy Collection | Switch | P | +``` + +As seen above, the collection game is marked `physical`, but all of its members +are marked `member`, *and* are listed under the release that's made available on +the collection. This is the correct representation of a collection and its +members. + +### delete + +``` +delete TITLE SYSTEM +``` + +Removes a game from the database. + +### export + +``` +export [-f FORMAT] [PATH] ``` -Pretty easy, huh? Each game and system added to vgstash is free-form and can be -tuned to match the user's preferences. +Exports the entire VGStash database to PATH in FORMAT format. FORMAT may be +either YAML or JSON. If FORMAT is omitted, it defaults to YAML. If PATH is +omitted, it will write to standard output (`stdout`). -## Quoting Game Titles +### import + +``` +import [-f FORMAT] [-u] [PATH] +``` + +Imports games from PATH in FORMAT format, optionally updating games that already +exist in the database. If PATH is omitted, it will read from standard input +(`stdin`). + +### list + +``` +list [FILTER] [-w WIDTH] [-r] +``` + +List games in the database, optionally using a FILTER or restricting the output +to WIDTH characters. Optionally set raw mode, outputting each row as +pipe-delimited lines instead of a table. + +--- + +Most of VGStash's power is in the `list` command. It comes with a set of default +filters that allow you to reason about your game collection. For example, this +command will show you every game marked "playing" that you also own in some way: + +```bash +$ vgstash list -w 40 playlog +Title | System | Own | Progress +---------------------------------------- +Crashmo | 3DS | D | P +Ever Oasis | 3DS | P | P +Fire Emblem | 3DS | P | P +Monster Hun | 3DS | D | P +Box Pusher | DSi | D | P +Glow Artisa | DSi | D | P +Dark Souls | PS3 | P | P +``` + +The `list` command is where you can best ask probing questions about your +collection, which can help you manage inventory, track how long a game has been +in your collection unbeaten, how many versions of a game you own, how many games +you've beaten, and so on. Here's how! + +#### How many games have I beaten? + +This one's easy! First, ask yourself if you want to target *just* the beaten +ones, or any that've been beaten *or* completed! Let's assume you want both +beaten and completed: + +``` +$ vgstash list done +``` + +"Done" is a filter name that targets *all* games in your collection that are +marked 'beaten' or 'completed'. + +Counting this list needs a little massaging. VGStash outputs a 2-line header for +its tables, so we need the raw (`-r`) flag and pass it to a line counter: + +``` +$ vgstash list -r done | wc -l +``` + +Awesome! Mine says `378`. How many have you beaten? + +#### Which games do I own? + +VGStash has a few filters for this: + +* **`physical`** tracks games whose ownership is marked physical +* **`digital`** tracks games whose ownership is marked digital +* **`owned`** tracks games marked physical, digital, *or* both + +So, let's say you're adding your digital games to your collection and you want +to double check everything's good. Easy! + +``` +$ vgstash list digital +``` + +There are also extra ownership filters: + +* **`members`** tracks games marked as being a member of a collection +* **`unowned`** tracks games you've added that you don't own (usually because + you've beaten or completed them) + +#### Which games need to be beaten or completed? + +VGStash has filters for this, too: + +* **`playlog`** tracks games whose progress is marked playing, that you own +* **`backlog`** tracks games whose progress is playing *or* new, that you own +* **`incomplete`** tracks games whose progress is beaten, but *not* completed +* **`complete`** tracks games whose progress is marked completed + +Check `vgstash list --help` for more. + +### notes + +``` +notes [-e] TITLE SYSTEM +``` + +Read (or edit, with the `-e` flag) notes for TITLE on SYSTEM. + +### update + +``` +update TITLE SYSTEM FIELD VALUE +``` + +Update the FIELD with VALUE for TITLE on SYSTEM. + +If you beat a game, for example: + +``` +$ vgstash update 'Super Mario Bros.' NES progress b +``` + +# Quoting Game Titles A note on characters: some shells treat certain characters differently. The most common ones you'll run into are punctuation, like single quotes ('), double @@ -85,7 +324,7 @@ quotes (") and exclamation points (!). You'll need to search your shell's manual for "character escaping" to get the details. Let's take a few game titles that might be problematic for a shell, and add them -to vgstash. These examples assume you're using bash (the Bourne Again SHell) or +to VGStash. These examples assume you're using bash (the Bourne Again SHell) or something comparable. First: a title with single quotes and exclamation points: @@ -138,7 +377,7 @@ you'll miss out on nice stuff like `sudo !!`. In bash, it's disabled with `set done. These tips may not work in all shells, so try using `echo` to print the title -you want before trying to add it in vgstash! If you accidentally add a game this +you want before trying to add it in VGStash! If you accidentally add a game this way, copy the title that's output in the success message and paste it into your delete command: @@ -150,40 +389,9 @@ $ vgstash delete "my gamels" PC Removed my gamels for PC from your collection. ``` -That's it! This is something that the shell does before vgstash begins +That's it! This is something that the shell does before VGStash begins processing its arguments, so please don't report any bugs dealing with quoting. -# Commands - -vgstash has a fairly small set of commands: - -* add -* delete -* export -* import -* list -* notes -* update - -The power is in the `list` command. vgstash comes with a set of default filters -that allow you to reason about your game collection. For example, this command -will show you every game marked "playing" that you also own in some way: - -```bash -$ vgstash list -w 40 playlog -Title | System | Own | Progress ----------------------------------------- -Crashmo | 3DS | D | P -Ever Oasis | 3DS | P | P -Fire Emblem | 3DS | P | P -Monster Hun | 3DS | D | P -Box Pusher | DSi | D | P -Glow Artisa | DSi | D | P -Dark Souls | PS3 | P | P -``` - -Consult `vgstash --help` for further usage information. - # Roadmap These are planned for the full 0.3 release: @@ -204,4 +412,8 @@ Goals planned for the 1.0 release: * Kivy-based interface (to release on Android via F-Droid) +# Contributing + If this interests you, please [e-mail me](mailto:zlg+vgstash@zlg.space). + +[spdx-agpl3]: https://spdx.org/licenses/AGPL-3.0-only.html @@ -4,3 +4,31 @@ * Write GUI * Write docs * How? Sphinx? Needs research + +--- + +Consider adding a 'dates' table that matches games to dates for purchase, +beating, and completing. Currently implemented via RFC2822-style headers within +the 'notes' field. More research is needed to determine if the notes field or a +table is a better way to achieve this. If an addition to the database format is +deemed necessary, a restructuring may be in order. + +--- + +One of the things curious about managing a game collection that doubles as a +backlog is, you get games on systems that were originally on other systems. How +do you classify those games? The original game is the actual content you're +playing, but you bought it for the newer system! If you track ownership +correctly, you'll put it under the new system. If you care about tracking the +original release, you're a little stuck. + +A perfect example is Virtual Console games on the Wii, WiiU, and 3DS. These +games should have their ownership tracked under Wii, WiiU, or 3DS, but the +original releases are on NES, SNES, etc. Ideally, it should be tracked as a +duplicate of the respective game on NES and SNES if you've owned or beaten them. +That hints toward needing games to have pointers of some sort, to add some +meaning to what's *truly* owned, and what's *been played through*. + +This points to the idea of release types. More experimentation is needed. + +--- |