[WIDGET] Trilium Hexmap - A widget displaying fetched notes as places and people on top of a hex grid map

[QuentinLeCaignec]

UPDATE: this is still regularly updated and has been cleaned-up and made more easily configurable, check the repo and the README of that repo, link below.

https://gitlab.com/QuentinLeCaignec/trilium-hexmap

---

Hello there,

In my quest to automate things and keep track of stuff for my tabletop campaign (the main reason I use Trilium!), i've made this frankly ridiculous widget that generates a hex grid (based on promoted attributes for max x/y size, start/end values of the range of coordinates to display, and hex size which is basically a zoom level), fetches Location notes with specific attributes (in my case hex coordinates, and an optional icon to be displayed on the hex map) and displays them at their proper coordinates with conditional colors (is the note TODO, is it empty, etc) and a clickable link.
It has an optional background image url which will appear behind the grid.
It even fetches notes tagged as "agents" (NPCs) and if they are related to a location note it changes the hex's background color, the color depending on the Agent type (neutral, hostile, allied, etc..).

This seemed overkill at first but honestly it's incredibly useful, I can write and update my notes and just with a tiny bit of setting up for labels, it all shows up on this map with everything clear and easy to track!

I've used it in-game already, tracking the player's movement and clicking on the link for the prepped hex note :)
It's also convenient for me to be able to quickly tell what i've not prepared and what I need to fill in.

Had to figure out some math for the hex grid itself but that wasn't too hard, works super well.

[DannyFL]

@QuentinLeCaignec
So I may be stupid... and while I'm not okay with that, I can acknowledge it from time to time. That said, how exactly does this get integrated? I attempted to do a basic import and implement. After banging my head against the wall for an hour or so it still didn't work at all for me. Would you be willing to write a more detailed step by step implementation for me?

Cheers

[QuentinLeCaignec]

Hey, glad you find it useful!

I just pushed a new version to the repo, with some fixes and improvements.

You can now reference an Image Note to be used as the background image through a relation attribute, you don't need to reference an external URL although that's still an option!
I fixed up some errors and weirdness in the code. I added a bunch of working examples of notes, a template and how to make note creation work (you can double-click the label of an empty hex to create a new note if you properly set-up the attributes, the new version now has a working example with explanations). It still throws an error on creation but that seems to be a problem from the backend API of trilium, and I made an Issue about to see if that can be fixed.

my next step is probably going to be a polish on the code and making the attributes clearer (better names, etc), and trying to add a basic in-window UI that could do some stuff better like zooming in/out or toggling information on/off without having to modify Promoted Attributes which is a bit cumbersome.

[DannyFL]

That's awesome, thank you so much for all the time you have put into this! I was really hoping not to have to port my D&D notes over to OneNote for this purpose. Do let me know when you have a zoom in/out solution working, and I'll be happy to be a second set of eyes/tester for this. Cheers!

[QuentinLeCaignec]

Alright!
New version (1.0) with a bunch of stuff.
I moved stuff around and polished a few things. I changed the attributes to more intuitive names as well as removed the ones that don't need to be "promoted" so as to not clutter that tab. The ranges are now only two attributes (with two values separated with a comma) instead of 4, the "hex_height" attribute is called scale and is now controllable by clicking on the +/- buttons at the bottom right (changing the scale redraws the widget every time unfortunately, no way around that so far).
There's two ways of adding a background map, by linking to an image note or with an external URL.
Automatic creation of notes by double-clicking the label of an empty hex works, I removed the annoying errors that popped up when creating a note. You can also specify another note under which you want the new notes to be created, and you can specify a template note which will be used when creating a new notes (the working example has a template with pre-created hex_x and hex_y promoted attributes which is very useful).
I also changed the way the agents display on a hex, it can now handle multiple agents present on the same hex and displays each as little marker at the top of the hex, colored depending on the agent type. Those markers can be hovered and clicked which is way more convenient to keep track of who's where without having to open the location note first. If there are more than 4 agents on the same hex, a little "+" marker appears to indicate that some are now shown.

The new version also has a bunch more example notes all working to better get started on using it.

Thanks for your input and for motivating me to improve this :)

[DannyFL]

One thing I noticed was that on the promoted attributes tab, changing those values did not actually change the scale of the map. Not actually sure what it did, I wound up having to change it under owned attributes and that took effect. The only promoted attr that made a difference was the scale, which effectively turns into the zoom function. If that is how it is supposed to be, that's cool, if not, sorry to be that guy. lol, I'm happy with it the way it is now, so feel free to not update it until you feel like it. Thanks again for the help with all this!

Cheers!

[QuentinLeCaignec]

Yes, the scale is the zoom level, controllable either by changing the value (and re-rendering the widget, as always) or with the +/- buttons. The other values are ranges to render only specific part of the full map, which is useful to me because my map is enormous (80 by 60) and I'll enter for example "20,40" X and "20,30" Y in order to only render a smaller rectangle of the map, which means I can have the automatic centering of the view where I want and also improve performance because my huge map can be a bit slow when fully rendered. Keep in mind any change to attributes on a render note needs a re-render (top-right, Actions, re-render).

I updated the instructions on the README of the code repo if you missed it, explaining the attributes and what they do.

I'm glad you're happy with it. I might have other ideas for it but for my own needs it's very good right now. There's a few adjustments (some CSS tweaking, some error-proofing, default values when some attributes are not set, etc..) that's I've added and I'll push those in a new version at some point. I probably also need to fix my Timeline widget, i'm assuming that repo is broken like this one was.

For reference, this is what my own setup looks like, and it is legitimately very useful to keep track of locations, factions and agents running around my sandbox. If you need an idea of what it looks like with a lot of content :

[QuentinLeCaignec]

This will probably be the last update for now, but here's a new version, 1.2 :

I added toggle attributes to shift the map layout to vertical/horizontal, and to odd/even shifting, which means this should now work with any type of hex grid! This took some work, but as far as I've tested it seems like it works without issue.

I polished a few things like adding attribute declarations (even the non-promoted ones, more convenient to promote them if you need it), added a few "location types" icons in the CSS, added a black border to agent markers, tweaked some more CSS, updated the README.

[QuentinLeCaignec]

Small update 1.3 with a few CSS fixes (agent markers glitching on hover or cut-off at the hex border, adjusted size)

[QuentinLeCaignec]

Updated to 1.4 for trilium version 0.48.3, fixes the API breaking changes.
Changed the hex note detection to use only one attribute called "hex_coords" instead of two called "hex_x" and "hex_y", the "hex_coords" attribute is in the X.Y format where X and Y (separated by a dot) at the coordinates of the hex.

[QuentinLeCaignec]

Updated to 1.5 for trilium 0.54.2, refactors/cleans up code, fixes some breaking changes for view centering, zoom buttons placement/working, and making the render drag-scrollable.

[QuentinLeCaignec]

Updated to 1.7 for 0.62.4 !