Skip to main content

PWA Overview

Elm Story supports export of your World to a fully compiled, installable and offline-capable web app (PWA) ready for self-hosting.

info

If you're unfamiliar with progressive web applications, check out the first part of the following video from Fireship.

Your exported World is bundled with a customized version of the Elm Story Runtime Engine (ESRE).

Offline Support

When a player first visits your self-hosted World, ESRE installs and registers a service worker with the player's browser. The worker is responsible for installing (pre-caching) and detecting revisions to your World's data and assets.

Each time an online player returns to your World, the worker will inform ESRE of any changes to the engine and ESRE will prompt the player to update. During Worldplay, in the background, the worker will periodically check for revisions every hour.

If the player's device is offline, your World will continue to work.

World Updates

ESRE uses revision feedback from the service worker and compares World versions to determine when a World update is available to the player. For example, if you self-host version 0.0.1 of your World, make changes in Elm Story and re-export and re-upload as version 0.0.2, ESRE will prompt the player to update.

caution

If you make any changes to your World, you must increase your World's metadata version number.

ESRE will throw a silent error in the player's browser console if it detects an older, incoming version than the World currently installed.

Increase Version

World version must conform to the semantic versioning standard.

Your World's version is adjusted in the Composer, via the element properties panel.

  1. In the Composer, click the World title in the World outline title bar or World tab.
  2. Under component properties, click the metadata sub panel to expand.
  3. Adjust version and press return or click save at the bottom of the form.

Increase Version

Elm Story provides feedback if the supplied format does not conform to the semver standard.

State Patching

To ensure evolving World design flexibility and retention of player progress during updates, ESRE patches and versions World state. For example, if you remove a passage in a future version that is the player's current event destination in their installation, ESRE will patch World state by rewinding the event timeline until it finds the most recent, existing event destination.

During early access, you may encounter edge cases where World state degrades after updating. Please report issues to our community subreddit r/ElmStoryWorlds.

Engine Updates

Each Elm Story release ships with a matching version of ESRE. This means that when you export your World as a PWA, your World is bundled with a version of ESRE that matches your Elm Story installation.

If your World doesn't require changes, but you want your players to enjoy the latest features of the engine, re-export with the most recent version of Elm Story and re-upload to your host.

When players receive the update prompt, changes are limited to ESRE. It is not necessary to increase your World's version.