vc map icon only

VC Story Capabilities and Setup

1. Overview

The VC Story Plugin is a powerful extension for VC Map that enables interactive storytelling by coupling traditional web content with 3D map interactions. This plugin allows content creators to build immersive narratives that leverage the third dimension to tell facts, projects, and stories in a more comprehensible way.

2. Core Features

2.1. Interactive Storytelling Framework

The plugin provides a comprehensive framework for creating interactive stories that respond to user interactions:

  • Scroll-based Interactions: Actions triggered when users scroll through story content

  • Click-based Interactions: Actions triggered by button clicks or interactive elements

  • Iframe Integration: Stories are displayed in an iframe with seamless integration to the main VC Map application

  • Intersection Observer: Automatically detects which story section is currently visible and triggers appropriate actions

2.2. Story Configuration

2.2.1. Story Structure

Stories are configured through two main files:

  • HTML File - index.html: Contains the visual story content with styled sections

  • JSON Configuration - items.json: Defines actions and their triggers

  • Assets: The assets folder contains the images, geojson files and 3D models for the VC Story.

The HTML file is responsible for the layout and design of the story, while the JSON configuration specifies the interactive elements and their behaviors. The JSON file can include various actions that are executed based on user interactions, such as scrolling or clicking.

In the items.json all actions are created and assigned to the elements in the index.html via the id.

The main object of the items.json has four keys:

  • disableMovement: [Boolean] Defines if it is possible to move around in the map with the common control of the VC Map.

  • actions: [Array] The defined actions.

  • items: [Array] The link of the defined actions to the html elements. Here it is also determined whether it is a click or scroll interaction.

For more information on possible actions and how to use them see Story Actions. Both files work together to create a cohesive storytelling experience.

The files needed to edited in an external editor, such as Visual Studio Code, or Notepad++, etc., since the App configurator does not offer any editing capabilities for both files.

2.2.2. How to set up

To setup the VC Story the virtualcitySTORY-3.x.x folder is required. It has the following structure:

virtualcitySTORY-3.x.x.zip
  ├─ storyExample
  │   ├─ index.html
  │   ├─ items.json
  |   ├─ customStory.css
  │   ├─ assets
  │   │   ├─ lib
  │   │   │   └─ css
  │   |   │   │   └─ ...
  │   │   │   └─ fonts
  │   |   │   │   └─ ...
  │   │   ├─ geojson
  │   │   │   └─ ...
  │   │   ├─ images
  │   │   │   └─ ...
  │   │   └─ models
  │   │       └─ ...
  ├─ @vcmap-story.tar.gz
  └─ README.md

Please extract the virtualcitySTORY-3.x.x.zip file and copy the storyExample folder into the datasource-data/{your-story} folder of the Publisher. The folder contains all necessary files to create a new story. The @vcmap-story.tar.gz file contains the VC Story Plugin, which can be added to a module in the App Configurator. The @vcmap-story.tar.gz need to be added to the VC Publisher as a plugin, which can be done by following the steps below.

  1. Add the Plugin to the Publisher:

    • Open the VC Publisher Admin section (only available for admin users).

    • Navigate to the Plugins section.

    • Upload the @vcmap-story.tar.gz file.

    • The plugin will be available for use in modules.

  2. Create a New Module:

    • In the App Configurator, create a new module for the story.

    • Add the VC Story Plugin to this module.

  3. Configure the Plugin:

2.2.3. Plugin Configuration

{
  indexUrl: string;    // Path to the story HTML file
  itemsUrl: string;    // Path to the story configuration JSON
}

Steps to setup a new Story:

  1. create new folder for your story in Publisher datasource-data - e.g. datasource-data/stories/my-story

  2. download VC Story Plugin - unzip & copy the content from that folder into your newly created story folder

  3. create new module in app configurator - e.g. my-story

  4. edit the module - add the VC Story Plugin to the module

  5. edit the plugin in the App Configurator - set the indexUrl to index.html and itemsUrl to items.json, if needed, set activeOnStartup to true to automatically activate the story when the module is loaded

  6. open index.html in an external editor - customize the story content, layout, and design

  7. open items.json in an external editor - define the actions and their triggers

  8. migrate existing stories -head for Migrate existing stories if you have any

  9. edit the index.html file - customize the story content, layout, and design

  10. edit the items.json file - define the actions and their triggers, more information can be found in Story Actions Reference & How to use actions

  11. optional customStory.css - edit the customStory.css file to apply custom styles to your story

3. Summary

The VC Story Plugin provides a comprehensive platform for creating immersive, interactive 3D storytelling experiences. Its extensive action system, seamless VC Map integration, and flexible configuration options make it suitable for a wide range of applications from urban planning presentations to educational content delivery.

The plugin’s modular architecture and extensible callback system ensure that it can adapt to evolving storytelling needs while maintaining high performance and user experience standards.