Technical Notes #2: The Codex

One of the challenges of developing LegendKeeper is handling complexity. Rather than the technological complexity of coding, I mean complexity that is exposed to the user via the interface. A world-building tool, I think, naturally leans towards high complexity. Just off the top of my head, you have spatial organization via maps, positioning and management of map pins and the things they link to, categorical organization via the wiki, contextual text manipulation via the editor, etc. There's a lot going on! Humans have a limited cognitive capacity, and an application's job is to minimize the capacity you spend on menial bullshit, and maximize the amount you can spend on what you care about. In our case, that's building cohesive, kick-ass worlds. 

Internal testing has revealed an issue with one of the main screens of LegendKeeper. You might recognize this screen from the video as "the articles" screen. This has since been renamed the "Codex", but the gist is that you use this tool when the four big categories: Places, Beings, Items, and Abilities, don't quite fit, and you want to make your own categories. Much like a codex in your favorite video game, the Codex is for world lore, ethnology, anthropology, geology, or anything else you want.

Can you see the potential issues here? As a programmer, I do love me some file directories, but I have concerns with this approach. One issue is that the UI itself forms a barrier to expansion: That is, you can see Agapanthus africanus, underneath Amaryllidaceae, is crammed up against the end of the sidebar and has wrapped the text around. Additionally, what if Agapanthus africanus was itself a category? The depth of custom categories is being arbitrarily limited by the width of the sidebar. Sure, I could add a horizontal scrollbar at the bottom, but that would be super gross. 

Another issue with this is future mobile compatibility. It could be tweaked to be tolerable on tablet, but I don't see a file-tree working out with a mobile web version. Overall, it just feels too clumsy. And one more thing: A huge tree of things is overwhelming. This approach is not reducing cognitive load enough.

Ok, but these are just like, your opinion, man! Less subjectively: this approach is slow with a large dataset. In order to render this tree, I need to scan your entire world's database to capture all the data I need to build it. There are ways of making this easier: Caching the entire tree in the browser's memory, caching the tree in the server, waiting to load child nodes of the tree until the parent node is clicked, etc, but all of these things add code complexity. 

LegendKeeper uses a fancy-schmancy caching strategy such that, once you've downloaded any data, unless the server lets you know it's changed, you don't have to download it again. The second page load of almost any page is instant (which is AWESOME, btw), but it does require some magical code on my part to rectify differences in the cached data with what the data should be. With trees, that code can be nasty: What if I move the great-great-great-great-great grandchild of an article to be it's immediate sibling? I've got to dig into the browser cache, find all of the affiliated nodes, and modify the data. This is doable and not terribly hard, but in reality, the database is already doing this for us. I don't like doing things twice! 

Additionally, once I apply changes, I need to rebuild the tree and render the new UI elements. This is fine for dozens of entries, but after a stress test of hundreds of items, I could tell the application was struggling, performance-wise. I want the Codex to be something that lives and grows with your world. I don't want lag to increase as your usage of the Codex increases---That's punishing you for using the app! 

So, with that brief (lel) overview of why this page is starting to fail me, is there another approach that solves all of these problems? To recap, this page:

• Arbitrarily limits the depth of categories
• Is not mobile friendly. 
• Could be overwhelming with lots of data.
• Has bad performance once the Codex starts becoming large.

I think I found something I like. As with anything in engineering, there are tradeoffs, but I believe this new approach solves more problems than it creates:

I've put the Codex on it's side, and now the interface is like a horizontally sliding window over it. Each "layer" is a list of things, like the sidebar of the other wiki pages, which I can then virtualize. In a nutshell, virtualization allows you to render only the UI that is visible, and reuse old UI elements with new data. In our case, this is happening while you scroll. This results in buttery smooth performance even if your categories have thousands of things in them. 

Additionally, when I add to the Codex, other layers aren't even on the screen, so I incur no extra cost for re-rendering unrelated UI elements. There are a lot of reasons why I think this approach is better, but it greatly reduced the amount of code required, greatly improved performance, and is much more mobile friendly: I can simply increase the size of the items for smaller devices.

That's probably more than you wanted to know about lists and hierarchies of things, but it was something I needed to tackle! The Codex was definitely the weakest part of LK, and now it's much better. I just need to add back in tagging and filtering, a way of knowing where you are in the tree, and a way to rewind all the way back to the root of the codex.

Dev update: I started working on the secret feature! I'd say it's about 60% done or so. I've also hired an extremely talented artist to create an absolutely MASSIVE world map for LegendKeeper. This map will be part of the LK brand and will be used in all promo materials, and will be provided to users as a usable map once the app comes out. More on that later!

Braden