Building an extension for Owlbear Rodeo 2.0

Third-party extensions are a tried and true method of allowing the general community to add functionality to an existing piece of software. I'm sure I don't need to remind you of the plethora of browser extensions that have become available over the decades since browsers made such available. As of February 2023, Owlbear Rodeo 2.0 has expanded their application to allow third-party extensions. I will be taking you though what it was like building an extension for Owlbear, as a third-party developer. But first, a bit about me.

A Bit About Me

I am Celeste Bloodreign, co-founder of an online multiplayer 3D dice rolling platform called dddice. Our goal is to give players tools to create their own custom 3D dice to use in their RPG sessions. To really make this work, we want to allow players to bring these dice to whatever online platform their GM has chosen to run the game on.

When we saw the announcement that Owlbear Rodeo 2.0 would support extensions we knew that to realize our goals, we needed to build an extension.

The DNA of an Owlbear Rodeo Extension

Owlbear Rodeo 2.0 extensions are architected in a way that's rather dissimilar to other web based extensions that I have worked with in the past. The most common of which are browser extensions.

In the Owlbear framework everything is an iframe. The action menus, iframe. Modals, load a URL in an iframe. Tool pop ups, believe it or not, also iframe.

This has some important contrasts with how browser extensions are built. The iframe grants a high degree of sandboxing, but comes with tradeoffs. Sandboxing is a method of keeping user submitted code from being destructive. When using an iframe this is enforced by the browser.

There has been decades of work by browser manufactures and web standards committees to help prevent bad actors from misusing iframes for evil. This has the benefit of taking that responsibility off the Owlbear team, and letting them focus on the app, not the sandboxing.

The Tradeoffs of an Iframe Base Extension Model

There is a tradeoff for me, the third-party developer, however. In a browser extension, my code gets full access to the contents of the page my extension is working with. I can manipulate the HTML, directly insert new objects into the page, and change the click functionality of buttons. All of which I used for the dddice browser extension. I can do none of this from an iframe. I can only access those features of my own pages that's loaded into the iFrame, and I can't reach out into the Owlbear interface elements directly.

Like all decisions tech, this is a tradeoff with upsides and downsides. The upside is the sandboxing is straight forward, any code I write that works when not in the iframe also works when in the iframe. For browser extensions that is not the case. There are some APIs that get sandboxed when in an extension that need to be used differently than when used on a website. Code re-writing is a thing that happens.

The downside is that the extension gets broken up into many more parts than a traditional browser extension and needs to be hosted on a server by the 3rd party developer. In a browser extension you have a background script of some sort, a script for your popup menu, and content scripts that get injected. All of this is delivered at install time to the user.

In the Owlbear model the content script needs to be broken up. Each interface element needs its own script at its own URL hosted by the third party developer, and they need to be ready for the traffic that Owlbear Rodeo will send!

The Owlbear Rodeo Extensions SDK

Fear not, the Owlbear team has provided a wonderful SDK to help you interact between your extension running in the iframe and the parent app's interface elements. Even allowing you to send information across their networking between connected users.

The docs are really amazing, and explain the concepts and choices very well, so I'm not going to walk though it all here - go read them, really! What I will say is that it makes it very easy to hook into the interface in a way that looks and feels very natural to the end user. It also provides structured ways to communicate between your extension and the overall Owlbear Rodeo app infrastructure.

To use an analogy it's the difference between having a blank white page and a coloring sheet. Coloring inside the lines makes getting to a beautiful picture so much easier.

How This Turned Out For dddice

The whole experience turned out amazing for us here at dddice. Being the Guinea pig, so to speak, could have been a source of frustration. However, the team at Owlbear, as I'm sure you already know, is top notch and the experience was 👨‍🍳😘

The iframe model, though foreign at first, turned out great. I didn't have to start from scratch with a new interface. I did need to make a lot of infrastructural changes to dddice.com to allow the iframeing to work properly, specifically with regard to login & sessions. But the best part is, the months of work I put into refining the interface was all reused plug-and-play in my Owlbear Rodeo extension.

The different pages we already had in place worked really well for the iFrame model. Our rooms page became the action popover and our stream overlays were used for the full screen modal. We communicated between them, to make actions nice and smooth using the JavaStript BroadcastChannel API. We also used the Owlbear SDK to store the association between an Owlbear Rodeo game and a dddice room and to sync the room, user names, and user's chosen colors across both platforms.

For those of you who don't already have your own site, if your extension can function independently of Owlbear Rodeo the upshot for you is that users can also use some of it by directly going to your hosted URL. You lose any multiplayer communications you got from being inside Owlbear, but the basic functionality should persist.

Conclusion

Overall the developer experience was really great, much easier to get into than browser extensions. Cross domain iframes do have their limitations. They are, however, old hat to seasoned web developers and also easy for newbies to look up on Stack Overflow.

The RPG community is made up of some very creative people, and I am really excited to see what extensions others come up with!

Guest article written by Celeste Bloodreign, co-founder of dddice. Connect with her on Discord, Twitter, or YouTube.