Branching Tales 2.0

Branching Tales 2.0 is a web-based editor for creating interactive scrollytelling experiences, digital narratives, comics, and visual stories with branching story paths.

Stories are built from branches, tiles, and media objects, allowing authors to combine text, images, animations, and interactive navigation into a single narrative experience.

The project was developed partly at the Fernfachhochschule Schweiz (FFHS) in cooperation with a study project at the Fachhochschule Graubünden (FHGR).

Image: Editor in Branching Tales

Features

• Create stories with multiple narrative branches
• Horizontal and vertical story layouts
• Lottie-file support for animations
• Markdown-powered text tiles
• Support for images, animations, videos, and audio
• JSON-based storage (no database required)
• Import and export stories using the .b-tale format
• Asset management and file uploads
• Modular PHP and Vanilla JavaScript architecture

---

Project Structure

A story consists of the following hierarchy:

Story
 ├─ Branches
 │   ├─ Tiles
 │   │   ├─ Objects
 │   │   └─ Links

Branches

Branches represent individual narrative paths.

Supported orientations:

horizontal
vertical

Tiles

Each branch contains a sequence of tiles.

Supported tile types:

canvas
text
blank

Canvas Tile

A free-layout container for media objects.

Text Tile

Displays Markdown content stored in separate .md files.

Blank Tile

Used for spacing and layout control.

Objects

Objects can be placed inside canvas tiles.

Currently supported:

text
image
animation

Planned:

video
audio

---

JSON Structure

Story data is stored as JSON and acts as the primary data source for both the editor and the viewer.

Example structure:

{
  "storyId": "example-story",
  "storyName": "Example Story",
  "storyVisibility": "private",
  "branches": {}
}

Each story is stored inside its own directory:

/data/{storyId}/

Example:

/data/example-story/
├─ story_data.json
├─ assets
├─ markdown files
├─ images
├─ videos
├─ audio
└─ animations

A global story registry is stored in:

/data/story-list.json

---

The .b-tale File Format

Branching Tales uses the .b-tale format for importing and exporting complete stories.

Internally, a .b-tale file is a ZIP archive containing:

story_data.json
branchingtale.json
all story assets

Example metadata file:

{
  "format": "branching-tale",
  "version": "1.0"
}

The format allows stories to be transferred, archived, shared, and imported into other Branching Tales installations.

---

Requirements

Server Requirements

• PHP-enabled web server
• PHP ZIP extension (required for import/export)
• Write permissions for the /data directory

Examples:

• Apache + PHP
• Nginx + PHP-FPM
• Local PHP development server

Access Management

Branching Tales currently does not include user management or authentication.

Access control must therefore be handled yourself or externally (for example via web server configuration, VPN access, or other access restrictions). Apart from the viewer.php nothing should be publicly accessable for safety reasons.

The JSON structure already contains a reserved visibility field:

{
  "storyVisibility": "private"
}

Possible values:

private
public

Future versions may implement visibility handling based on this field.

---

Installation

1. Clone the repository

git clone https://github.com/Eric-St03/branching-tales-2-0

2. Configure the web server

Point your web server document root to the project directory.

3. Ensure write permissions

The application must be able to create and modify files inside:

/data/

4. Open the editor

Navigate to the installation URL in your browser.

---

Demo

A public demonstration instance is available at:

demo.branchingtales.ch

---

Technology Stack

Frontend

• Vanilla JavaScript (ES Modules)
• HTML
• CSS

Backend

• PHP
• JSON-based storage

Third-Party Libraries

• Bodymovin / Lottie
• zero-md
• GitHub Markdown CSS
• Highlight.js