dspaul / compass

TTRPG rulebook library manager, bringing all your books in one place.

COMPASS

The Codex Organizer to make Pen-and-paper Adventuring Super Simple or COMPASS for short is a windows application to organize and manage all your TTRPG rulebooks, inspired by Playnite. You can download the latest version of COMPASS here.

📜 Story

If you are a fellow TTRPG enthusiast, you probably have lots of pdf's both homebrew and official from sites such as Drivethrough RPG, Humble Bundle Books, GM Binder, Homebrewery, itch.io or content from subreddits, patreon creators and kickstarters. Or perhaps you own them in digital form on sites such as D&D Beyond or Roll20. Keeping track of all these books, maps and other resources is hard and nothing is more frustrating than franticly clicking through folders in search of that one statblock you need in the heat of combat.

COMPASS solves this problem by bringing all of your resources together in one place that was designed to help you find what you need, thanks to fuzzy search, a robust filter and tagging system and a clean interface with four customizable layouts to choose from, so you only see the information that is important to you.

🧰 Features

• Unify your digital tabletop RPG sourcebook library so everything is in one place. You can import files of any type or link to a URL for online sources. You can also manually add books to include your physical collection.

• Have Redundant Access to your books by linking your books to both an offline file and an online version hosted on sites such as Google Drive and GM Binder. COMPASS will automatically fallback to another version if the preferred one is unavailable due to a lack of internet for example.

• Automatic metadata from PDF's, supported sites and books with an ISBN number thanks to Open Library.

• 

• Categorize all your books using Tags. You can add Tags for anything you like, such as:

  • The type of content like Adventure, Monsters or Setting/Lore.
  • The edition or ruleset such as DnD 5e or Pathfinder 2e.
  • The setting such as Forgotten realms or Eberron.
  • The Genre such as Horror, Fantasy or Sci-Fi.
  • Whatever works for you, you can create tags for everything.

• Map your existing folder structure onto your new tags to get organized quickly.

• Organize your tags in groups to retain the advantages of folders, without the need for file duplication.

• Filter and Sort all your books by metadata with support for separate sorting titles and negative filters.

• Visualize your library with 4 different layouts to choose from: Home, List, Cards and Tiles (see screenshots).

• Have Quick Access to your books thanks to the Home view which lists your favorites, recently opened, most opened and recently added books for your convenience.

• Group your books into collections. Each collection has their own list of tags, authors, ect. and helps you keep an overview by reducing the amount of books that are on your screen at once.

⚠️ Why am I getting warnings from Windows and Virus scanners when installing COMPASS?

The COMPASS files are not digitally signed which results in these kinds of warnings. Signing code is expensive, requires a bunch of paperwork and is just not worth it for a small project like this. If this project ever takes off and gains a large amount of users, I will look into this again. If you do not trust the executable, you can always build the code from source. To do so, simply clone the repo, install Visual Studio, open the solution file and and either build in release mode or publish.

🚧 Contributing

I created this project to solve a problem I had and as a learning opportunity. I eventually chose to release it publicly and open source because I believe others might find it useful as well. If you like this project and would like to contribute, there are many ways you can do so.

• If you find a bug, please open a github issue and report it there so it can be fixed. If you don't have a github account, you can also join the discord and share it there. Please include a clear explanation of the nature of the bug and if possible steps to reproduce it.
• If you have ideas for new features or improvements, you can put those in a github issue as well.
• As for code contributions and pull requests, I am not currently looking for contributors. There are many reasons for this but this video summarizes it pretty well. If you cannot help yourself however, all pull requests should be made against the dev branch. Dev gets merged into master with every new release.

❤️ Support the project

If you would like to support the project, you can do so in multiple ways.

• If you have any ideas or suggestion on how to make COMPASS better, you can share those in the discord or in a github issue, it helps a lot.
• Feel free to share this on forums, social media, discord servers ect. if you think it can help others.
• If you would like to financially support me so I can justify spending more time on this, help with potential costs such as code signing or just show some love, you can buy me a coffee over on ko-fi, I would greatly appreciate it.

📷 Screenshots

compass's Issues

Amount of files

Hi,

Could there be somewhere in the main view (maybe in the top bar) an indicator of the amount of files in your current view and maybe also how many are visible with your filters on, ie 15 of 200 (files visible).

Thanks for considering!

Bulk import?

Hey, is there a way to bulk import files? I am using OneDrive instead of Google Drive, so I just need to point it at a folder on my local computer, but I am only seeing the option to import one file at a time, which will take too long.

By the way, this tool looks awesome. I've been looking for something suitable for quite some time, and it wasn't until I added the word "RPG" into my search parameters that I actually found this. I had been thinking I might find myself needing to create my own.

Compass crashes when creating new tag group if you already have a bunch of existing groups

Describe the bug
As in title, the program crashes when creating a new tag group if you already have a bunch. I've attached the log file

Expected behavior
Not crashing?

To Reproduce
I have a main group "Systems", then I have 27 subgroups nested under that, individual ones A-Z and a numbered one. I also have a few groups nested further under those for specific systems, but at a certain point the program just crashes and any changes made since the last time the program was closed is lost.

System info (please complete the following information):

• OS: Windows 11
• Release Version 1.1

all.log

Right clicking tag (groups) to add (sub)tags

Hi!

Sorry for making many suggestions. :)

Maybe it would be easy to be able to rightclick already made tag (groups), like you can do now to edit them, to make (sub)tags that have the same colour as the parent.
ie with the following example, I could rightclick Mechanics to add a new tag 2D20 that will be blue and directly made under the Mechanics group; or I could rightclick Horror to add a new tag Cthulhu Mythos that will be red and directly made under the Horror tag.

Thanks in advance for considering!

Improve Performance by adding lazy loading

Hi DSPaul,

Hope you're doing well! I wanted to start by saying how much I love the app. However, I have some suggestions to improve the loading times for larger collections:

• Split the collection into smaller "chunks" of 100-200 books and display each chunk before loading the next batch
• Add a page system (my least favourite idea, but probably easy to implement).
• Load a group of books after scrolling down, but only on user input

Thanks for taking the time to consider my ideas. Let me know if you have any questions or need further clarification.
~Handyfon

Remove books that are no longer found

I suggest adding a feature that checks for the existence of a file at the specified path when a collection loads, and removes it if it doesn't exist. This could be accompanied by a popup. Alternatively, adding a button to prune unreferenced files would be another elegant solution.

Let me know what you think.

Thanks,
Handyfon

Endless crash loop (due to incorrect file type?)

Describe the bug
I used the folder uploading feature to upload a folder containing some pdfs but it seems there was a desktop.ini file in there somewhere that I missed, even when going through the checkboxes. When I attempted to delete it in the application, there was a crash and attempting to reboot COMPASS immediately results in crashing as well. I included the crash log here.

Crash log
all.log

• OS: Windows 11

Tag tree auto expands

Describe the bug
Since 1.1 the entire tag tree auto expands when adding or deleting a tag, even if you just collapsed all subtags.

Expected behavior
The tag tree would remember the position it had before adding the tag.

Alternate solution
A button to collapse / expand all tags.

Thanks!

Sorting of tags

Is it possible to add something to sort group content alphabetically (ie AZ and maybe ZA too)?
It could be a small arrow button (up/down) next to the group that can be clicked to change the direction (or left alone if you want to make your custom sorting), or if yet more buttons would crowd the GUI, maybe clicking the group itself could toggle the sorting? Once for AZ, second time ZA?

Tags are cropped in Card view

System info (please complete the following information):

• OS: Windows 10
• Release Version1.5.1

Undo button

Maybe an undo button would be useful?
I deleted the files from a collection (on purpose!), but I can imagine people doing it accidentally too.

Edit screen size with long tags

Describe the bug
The (bulk) edit screen content resizes based on the length of the tags in the open groups. If a tag has a very long name (in my case due to a system having a huge title), then the part of the edit screen that holds the tags takes almost the entire screen in, hiding most fields and the save/cancel button.

Expected behavior
The right side of the edit screen (holding the tags) has a max width. If a tag name is longer, then a drag bar will be added to the bottom of the right side of the edit screen so you can scroll to see the whole tag, without the left side of the edit screen (with all the other fields) being made too small to use.

Screenshots/files
Edit with long tags open:

Edit with long tags closed:

Bulk edit with long tags open:

Bulk edit with long tags closed:

System info (please complete the following information):

• Release Version 1.1.1

App crashes and data loss issue when adding 2000 PDFs

Describe the bug
The app crashes and loses all data when around 2000 PDFs are added. App will scan PDFs and seemingly add them before stalling out then crashing. Reopening the app it does not retain any of the data from the imported items, even ones imported before the 2000 were added.

Expected behavior
The app should be able to handle and store a vast volume of PDFs or allow for more than one "library" of books to be saved. It would be nice for each edition of D&D.

System info (please complete the following information):

• OS: Windows 11

Change paths of a file based on the given tags

Hi!

ComicRack had a plugin, https://github.com/Stonepaw/comicrack-library-organizer, where you could give certain tags/templates to a file and it would both rename and move that file. ie you could rename the cbz file to Superman Vol. 1938 #703 (November, 2010).cbz and move it to \DC Comics\Superman (1938).

It could also make new folders if the folder (ie Superman (1938) in above example) would exist yet.

Could something similar be made either based on file renames and/or tags?

No webdrivers when you change compass data path

Describe the bug
After changing path for Compass data, webdrivers can't download .

So I cannot download homebrewery cover, for example

To Reproduce
Steps to reproduce the behavior:

1. Change data path, maybe on another hard drive
2. Relaunch
3. See the error message "chrome webdriver could not be initialised"

Screenshots/files

System info (please complete the following information):

• OS: Windows 10
• latest version 1.15

Adding a date that's only a year

Describe the bug
When I add a date to a file (edit or bulk edit) that's only in a YYYY format instead of a DD/MM/YYYY format, it doesn't save it.

Expected behavior
Incomplete dates ie MM/YYYY or YYYY get accepted too.

System info (please complete the following information):

• OS: [e.g. Windows 10 22H2]
• Release Version 1.1.1

Import Folder Clears Tags

Describe the bug
Using Import Folder or Import File seems to be clearing all the tags previously applied to other imported files.

Expected behavior
Should not clear any tags

To Reproduce
Steps to reproduce the behavior:

1. Import a file (ex test.pdf)
2. Add a tag to it
3. Import another file (or folder)
4. test.pdf no longer has tags

System info (please complete the following information):

• OS: Win10
• Release Version 1.1.2

Exclude specific Subfolders from Autoimport

For most active Game I have a subfolder called "Helpers" that contain things like GM Screens, Tables but also Tokens and Pictures I want to use. These often have several hundred files in there.

I would love a way to exclude an entire Subfolder (such as tokens) from Import into Compass. So I don't get 400 files when Importing a small Indie game,

Fetch meta data with ISBN number?

I like how adding an item via ISBN number will fetch data like author, release date, etc.

I would love to be able to have this fetch happen for PDFs I have locally that also have an ISBN number.

Sorting of tags on books

Currently when you add a bunch of tags to a book (I did mine by bulk edit) it adds them seemingly randomly.
In this case, for the first group: I added them in this order:

• 7th Sea
• 1e
• Fantasy
• Swashbuckling / Pirates
• Primarily D10
• Roll and Keep
• Point Based

The order on which they appeared on the books is:

• 7th Sea
• Fantasy
• Point Based
• Roll and Keep
• 1e
• Swashbuckling / Pirates
• Primarily D10

For the second batch it changed it to the same order, but I saw I forgot to add the 7th Sea tag. When I added in a second edit, it stayed at the end.

Suggestion:

• All tags appear in a fixed alphabetical order.
• Prefered An option in the settings to choose the order the tags appear, ie. alphabetically (general), alphabetically (by tag group and tag tree).
  In the latter case, in the above example the order would be: 7th Sea, 1e, Swashbuckling / Pirates as Action / Adventure is before Fantasy, Fantasy, Primarily D10 as Dice is before Point Based, Point Based, Roll and Keep.

Tags to remove doesn't need an 'Add Tag' button

Describe the bug
When bulk editing an entries, both the 'Tags to Add' and 'Tags to Remove' options have a ' Add Tag' button.

Expected behavior
The button should only be present for 'Tags to Add'.

Screenshots/files

System info (please complete the following information):

• Release Version V1.1

Saving metadata in the files

Is there a possibility to let COMPASS save the metadata you make in the application (tags, adding of publisher, author, ISBN etc) in the file's metadata?

Import tags from other collections

It's maybe linked to #24.

If I'd make separate collections for the major gaming systems I collect, I currently either need to make all tags that I want to reuse manually again, or dig into an existing's collection tags.xml to copy parts to the new collection's tags.xml (which can lead to syntax mistakes).
It would be neat to have some function within COMPASS where you can import a selection of tags from one collection to another collection.
Ie
Dungeons & Dragons has the tags

• Core
• Supplement
  • Spell
  • Item
  • Class
  • Race
  • Bestiary
• Module
• Campaign

I want to import in Call of Cthulhu

• Core
• Supplement
  • Spell
  • Bestiary
• Module
• Campaign

But not:

• Supplement
  • Item
  • Class
  • Race

An example solution could be a button Import Tags where when clicked on and selected a source (which collection you want to import from) you'd get a new window within COMPASS with a dropdown with checkboxes to choose which tags to copy over to the current collection.
Or, a new window with two columns CollectionName1 (source collection) and CollectionName2 (destination collection) where you can copy (and reorder?) tags from the source collection to the destination collection. That can be done for example with arrows (move to left to add, move to right to remove wrongly added tags within this editing session and maybe up and down to sort) or by dragging and dropping tags.
In either case, it would be important that if only a child tag would be selected, that the parent tag (for the structure) would be auto selected too. Maybe a user then could manually deselect the parent if they really need to (but that seems less relevant to me).
It would also be useful if the other data of the tag (colour) would also be copied over.

Thanks!

Tags repository

Minor (I think) request, but would it be possible to have pre-made tags that could be included on installation? Or maybe as a checkbox during the installation process. Ideally, though this would probably be more effort, an external shared repository that people can contribute to? I honestly have no idea what would even be required for something like that, I'm just spitballing.

Automatical scans of folders already in the library

Hi!

Similarly as #23 and it's suggestion to auto remove missing files from a library, I was wondering if it would be possible for COMPASS to auto scan the folders in it's library for new additions.
There could be a setting in the preferences on how many times these scan happen, or maybe even a button somewhere to manually start a scan, without the need to actually drag & drop the whole folder back in.

Thanks for considering!

Adding an extra lay-out: Folders

Hi!

I wonder if it would be feasible to add another lay-out to the options, namely 'Folders', based on your folder structure.
It would also be neat if you could then right click a folder (similarly to bulk edits) and give that folder and it's contents (even files a few folders deep) the tags you desire. It would make sorting and giving metadata to an archive much easier.

At the moment, when I readd my main folder, it scans for additions, but adds them in an unsorted bunch (or well, if I want sorted by date added or something) at the bottom. That's no issue if you only have 1 system with maybe 2-3 extra files since the last scan, but it can become problematic if you add maybe a hundred files of a dozen different systems per scan.

Thanks for considering!

Regenerate Cover / Thumbnail

Hi!

There are situations where a cover / thumbnail of a file could get corrupted or wrongly generated.
If I understand it correctly, once COMPASS generates the cover and thumbnail for a file, it will keep referencing to said cover and thumbnail. If a cover and/or thumbnail would be corrupted, you currently have (for monitored folders) remove the file from the folder, remove the "broken links/missing files" from COMPASS in the settings (or manually), close COMPASS, readd the files in the folder and start COMPASS again to get them picked up, and generate a cover and thumbnail.

Suggestion:
Being able to right click on a selection (one file or several files) and in the dropdown menu have a Regenerate Cover button (which would do both cover and thumbnail).
Or if you fear that the dropdown menu would be too crowded, a shortcut do regenerate covers for selected files, with a list of shortcuts somewhere in the settings or documentation.

Thanks!

Critical Error Upon Launching After Initial Installation

Issue:
Upon initial installation of the app, I received a critical error message after attempting to open the program. Restart of Windows did not solve the issue. Message text follows:

It seems COMPASS has run into a critical error ("The invocation of the constructor on type 'COMPASS.Windows.MainWindow' that matches the specified binding constraints threw an exception.' Line number '13' and line position '5'.).

Screenshots/files

Log: all.log

System info:

• OS: Windows 11 Home
• Release Version Version 10.0.22621 Build 22621

Auto scroll when i click on an item

Describe the bug
When in click on an item, the view is scrolling
Expected behavior
no scrolling

Screenshots/files

COMPASS.2023-10-30.21-14-54.mp4

System info (please complete the following information):

• OS: Windows 10
• Release Version 1.5.1

Can't add author without ";"

Describe the bug
When editing the author field, if you don't add a semicolon to the end of the name, the change doesn't stick. You also can't pick an author from the drop down (same issue I think)

• OS: Win 10
• Release Version 1.1.3

Crash on adjusting Tag column width

Describe the bug
After adjusting the width of all the other columns in List Layout view, I tried to make the tag column smaller and it crashed. On restart it lost all the metadata edits to the books and most of tags I had created.

To Reproduce

I've tried to reproduce the error but it hasn't crashed yet. I tried editing some of the metadata and added tags for a few minutes and adjusting the columns but it hasn't crashed again. Before, it had crashed after nearly an hour of working on it.

Screenshots/files
I've attached the all.log file. all.log

System info

• OS: Windows 10 Pro 22H2

Add columns

It would be nice to be able to sort files in a collection based on the Date Added field.
Once you have added a few hundreds (or thousands) of files to a collection, it can become hard to find which were the files added latest or which files were added at the same time.

The later can be useful if, for instance, four files belonging to the same adventure would be added and you'd want to find these four files to add tags to them.

ISBN could also be useful to have as a column.

COMPASS can't extract covers or open files when the file path is too long

Describe the bug
When importing a folder with map files (.png in this case) COMPASS will try to extract covers of all files.
It will give an error in activity log for certain images (not all) saying it can't extract a cover of these pdfs.
Since the files are images, it COMPASS should maybe recognise them as such. Weirdly enough, some covers are correct, some are just missing and a bunch are something else entirely (images not in the file).

Expected behaviour
They should all have either the correct image (see second screenshot blue square), or Cover Art Unavailable.

System info (please complete the following information):

• OS: W10
• Release Version V1.4.2

Road to Cross-platform

Analysis of the workload and feasibility of switching from WPF to AvaloniaUI, to make COMPASS work on Linux and Mac.

• Replace all windows-only code
  • Adopt Mvvm toolkit (for commands and property changed events)
  • Replace Attached Properties with styled properties
  • Replace Auto update will alternative package or write from scratch (more research needed)
  • Replace Drag and drop with cross platform alternative (more research needed)
  • Replace messagebox with cross platform alternative or write from scratch (more research needed)
  • Changes required to ISBN barcode scanner
  • Replace DotNetZip with SharpCompress
  • Managing unhandled exceptions works differently
  • Cross platform keyboard shortcuts
  • File system interactions (save, load, ect.)
  • File dialogs (select file/folder, ect.)
  • Windows management (minimize, maximize, ect.)
  • User preferences
  • Replace MsTest with NUnit
• Rewrite UI in Avalonia
  • Find different way to get Icons
  • Find different way of rendering gifs for loading animation
  • Find alternative for some controls like 5 star rating, multi select combobox, virtualizing stackpanel, ect.
  • Redo all styling
  • Redo templates
• Make cross platform installer/release pipeline

Filename in COMPASS

When importing files, COMPASS shows sometimes a different name than the filename itself. This is likely based metadata?
Sadly not all creators set this metadata in something relevant or readable.

ie the file HotOE - Handout #02 - Article - The London Times (Jan 15, 1923) gets named Microsoft PowerPoint - Presentation1 in COMPASS. That's painful if you did your best to rename the files in your archive.

Suggestion:

• Either names of files in COMPASS = filename.
• Or a dropdown in the settings with the default names (current situation) and the filenames to choose from.

I wonder if said setting could be changed it could be done on files already imported, but from monitored folders, or if I should remove all files from COMPASS and reimport them later?

Thanks!

Drag and drop import

Self-explanatory, if you have a collection open, being able to drag one or more items into Compass and automatically being added.

Shortcuts

Hi,

Could shortcuts be added to COMPASS?
I was mainly thinking about ctrl+a to select all files within the parameters of the chosen filters.

Other common shortcuts might be nice too ie ctrl+z and ctrl+y for #30. Or maybe F2 on a file to change the name without having to open the edit screen.

Just a thought. :)