Devs

docs & useful examples

Getting started

Introduction

In order to implement a story, it will be necessary to install one of the following packs:

Vue storyground reader is a package which includes vue components created to read stories; Js storyground reader is a javascript library which includes an optimised Vue and Vue storyground reader build, allowing for the initialization of the library without the need of further files.
The examples will show both libraries, as their functions do not vary.

Quick start

If no initialization parameter is provided, a placeholder story will be shown. In order to visualise one’s story, an exported story in jSON format will be required.

<template>
  <div id="app">
    <game :gameData="jsonStory" />
  </div>
</template>
<script>
import { game } from 'vue-storyground-reader';
import jsonStory from "./jsonStory.json";

export default {
  components: {
    game,
  },
  data() {
    return {
      jsonStory: jsonStory,
    };
  },
};
</script>

Advanced example

The story in the homepage is a perfect example of advanced use of Storyground’s functions.

Parameters

Name	Type	Default	Description
gameData	Object	La storia di default di Stoyground	The story to visualise, which can be found inside the export package in JSON format
langStory	String	“null-lang”	The language the story needs to be visualised in
width	String	“100vw”	The width of the viewer (https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units)
height	String	“100vh”	The height of the viewer (https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units)
idStory	Number	l’ID della storia assegnato da Stoyground	It assigns an ID to the viewer; in case there are multiple stories, it will ensure that the events work properly
useTheme	Boolean	true	Enables or disables the use of themes computed by the viewer
stopLink	Boolean	false	Prevents the viewer from going to a different page by showing the destination URL in a message
langEditor	String	“en”	The language in which debugging messages are shown
strings	Object	defaultStrings	Defines the strings shown in the debugging messages
canEmit	Boolean	true	Enables or disables the possiblity of emitting a function through the use of the “emit” node
showToast	Boolean	false	Allows to visualise toasts that show the values emitted by the “emit” node

Events

The viewers will trigger certain events during the navigation of the story. It’s important to know the place of each event in the life cycle of the viewer, as it’s possible to modify the data in the story thus changing its navigation itself.

Name	Description
onInit	This event starts when the viewer is initialised
beforeNavigation	It’s triggered before the viewer starts the navigation
afterNavigation	It’s triggered after the navigation has happened
emitByNodes	Any time you navigate through an emit node, this event is called

<template>
  <div v-if="counter" class="counter">
    afterNavigation called {{ counter }} times
  </div>
  <div id="app">
    <game @afterNavigation="this.counter++" />
  </div>
</template>
<style>
.counter {
  font-size: 14px;
  font-family: monospace;
  padding: 14px;
  color: red;
  text-align: center;
}
</style>
<script>
import { game } from 'vue-storyground-reader';
  
export default {
  components: {
    game,
  },
  data() {
    return {
      counter: 0,
    };
  },
};
</script>

Methods

Methods allow to get and set the data in the story.

Name	Description
getPlayerValues	Returns all associated variables to the user
getCurrentNodesValues	Returns all associated variables to the current node(s)
setStartNode	Resets the beginning node; it’s possible to use both the ID of the node and the name of the desired start node
setPlayerValues	Modifies the variables associated to the user

<template>
  <div id="app">
    <game ref="gameRef" />
  </div>
  <div class="btns-box">
    <button @click="setNewData()" id="btn-set-info">💀 Set HP to 1!</button>
    <button @click="retriveData()" id="btn-info">📝 Give me player data!</button>
  </div>
</template>
<style>
.btns-box {
  position: fixed;
  right: 15px;
  bottom: 15px;
}

button {
  font-size: 18px;
  font-family: monospace;
  margin-right: 10px;
}
</style>

<script>
export default {
  data() {},
  methods: {
    setNewData() {
      let playerValues = this.$refs.gameRef.getPlayerValues();

      let hp = playerValues.find((el) => el.slug == "HP");
      hp.level = 1;

      this.$refs.gameRef.setPlayerValues(playerValues);
    },
    retriveData() {
      alert(JSON.stringify(this.$refs.gameRef.getPlayerValues()));
    },
  },
};
</script>