Big UI Code Revamp, Now with Localization Support!

Whew! I’ve spend the last week or so doing a major overhaul of our UI tech. Those who have been following along know that all of our UI is implemented in straight HTML and Javascript, using chromium embedded. If that’s new information to you, here’s a refresher video to get you caught up.

After the jump, I’ll describe why the old system needed a serious rework, how we’ve improved things, and how localization into new languages will work.

The Best Laid Plans…

The UI in that video was basically my first shot at writing a dynamic web app with no page refreshes.  It relied heavily on jQuery and raw ajax calls to fetch data. It worked, but it had three big problems.

1. No mod support.
2. No localization support (wtf!)
3. Writing practically anything required A LOT of code and expertise in jQuery and the DOM.

Numbers 1 and 2 were fixable, but number 3 was a deal-killer. It’s a major blocker for those of you that want to write a UI mod, but aren’t seasoned web developers. We needed a fix! So the mission was to replace my homegrown, code-heavy solution with something that:

• Supports mods. You must be able to shove new html and js into the UI without us knowing about it.
• Supports localization. Localization must be mod-friendly too. A mod must be able to ship with multiple languages
• Far simpler method of writing basic screens and interactions.

The Solution

Long story short, our new UI stack rips out pretty much 99% all my custom js with a few off-the-shelf frameworks.

• Ember.js with Handlebars for dynamically updating web views easily
• i18next for Localization support
• less for straightforward and powerful styling of HTML
• A tiny bit of glue to stitch together all the mods into one web app.

Anatomy of a UI mod

In the new system, a UI mod consists of HTML, JS, CSS, and translation files. Suppose you’re making a music player mod that changes the in-game soundtrack to a particular tune. On disk the mod would look like this:

/mods/musicPlayer
/mods/musicPlayer/musicPlayer.html
/mods/musicPlayer/musicPlayer.js
/mods/musicPlayer/musicPlayer.css
/mods/musicPlayer/locales/en.json
/mods/musicPlayer/locales/de.json

• musicPlayer directory, all the files for the mod
• musicPlayer.html, the HTML layout for the player UI.
• musicPlayer.js, JavaScript for manipulating the player buttons and loading the correct track.
• locales directory, translation files for all of the text in the mod
• locales/en.json, English language translation file
• locales/de.json, German language translation file

You can also throw images or whatever else your mod needs in there. So the mod folder encapsulates everything the mod needs to function in the game. And of course, consistent with our philosophy on modding, the stock Stonehearth UI will be written as a bunch of mods on this framework.

Final Note on Localization

I know a lot of you are interested in multiple language support, so here’s an example localization file for the example music player mod: locales/en.json

{
    "title": "Music Player",
    "selectTrackLabel": "Select a track",
    "buttons": {
        "playButtonLabel": "Play",
        "pauseButtonLabel": "Pause"
    }
}

Pretty simple right? There are two cool things about this:

1. Mods ship with their own localization files. This was one of our requirements, but it’s worth repeating. You can support multiple languages in your mod!
2. Anyone, anywhere can add support for a new language by writing a new translation file and sticking it in the right place!