Skip to content

Reference Guide

Jump to bottom
Evansii edited this page May 3, 2019 · 34 revisions

Table of Contents
  1. Storyboard
    1. Introduction
    2. Objects/Nodes
      1. Declaration
  2. Objects in the storyboard

1. Storyboard

1.1 Introduction

A mini-game is described in a single JSON file termed storyboard.json. This file is an array of various objects (or nodes) — defined by a unique ID — belonging to one of these five categories (called class, here):

A storyboard.json is thus organized as follows:

[
  {"id":1 , "class"="scene", ...},
  {"id":5 , "class"="item", ...},
  {"id":17, "class"="switch", ...},
  {"id":22, "class"="machine", ...},
  {"id":34, "class"="sprite", ...}
]

1.2. Objects/Nodes

The storyboard describes a scene graph [Wikipedia] . Thus, in this data structure, objects are classified in two categories:

  • Group Objects containing children like scene, switch.
  • Leaf Objects like machine, item, and sprite.

1.2.1. Declaration

Each object is defined by a unique ID and at minima contains:

  • id: a numerical identifier.
  • class: a class among scene, item, target, machine, and lock.
  • description: A comment describing the object. Not use by the crazyBioGame Engine.
  • display: a section defining how the object is displayed in the scene.
  • action: a section defining how the object triggers actions depending of an event (mouse click, etc.).

The machine have a specific property features.

  • features: a parameter section defining the object's behavior.
{
  "id": 12,
  "class":"item",
  "description": "A cup",
  "features": {
    "popup" : {
      "title": "A cup of coffee"
  }
}

1.2.2. Display

The most important property of an object is the way it is displayed in the scene (with or without user interaction). There are two ways to define the rendering type:

  • The sub-property media is used to indicate the media (image, video,etc.) displayed in the scene.
  • The sub-property text when the object is an HTML element.
1.2.2.1. graphics 
...
  "display": {
    "position": [100,200],
    "width": 512,
    "height": 256,
    "media": {
      "image": "path/filename.png"
    }
  }
...
1.2.2.2. text 
...
  "display": {
    "position": [100,200],
    "width": 512,
    "height": 256,
    "text": {
      "content": "<p>Hello World!!</p>",
      "style": {
        "color": "white",
        "background": "black"
      }
    }
  }
...
1.2.2.3. target

In addition, a third sub-property targetcan be used to define an area sensitive to the mouse pointer.

1.2.3. Features

1.2.3.1. Window Popup

Except the scene, most of the objects are available via a user interaction (pointer click) and displayed in a popup window. The window contains a maximum of three parts:

  • a header ( mandatory - a single line of text)
  • a content section [optional]
  • a footer section [optional]

using the following layout.

Example of popup window

Popup Layout
A popup contains a maximum of three sub-sections corresponding to the (i) description, (ii) content, and (iii) graphics

and the corresponding JSON ...

...
  "popup": {
    "title": "Description"
    "content": [
      "<h3>Content</h3>",
      "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. ",
      "Phasellus volutpat bibendum egestas. ",
      "Sed euismod et tellus vel finibus. Quisque ac ipsum ut ipsum pulvinar hen.</p>"
    ],
    "media": {
      "image": "path/filename.png"
    }
  }
...

2. Objects in the storyboard

2.2. Sprite

In this category, we find the simplest object in the `scene. There are used as decorative elements and/or as clickable areas.

2.3. Item

The item is an object that can be stored in the inventory and used later in combination with a sprite or a composite.

2.4. Machine

The machine is an interactive object triggering an action.

There are several sub-categories used in the mini-games:

  • lock - Dedicated machine for exit
  • download
  • form - using a syntax similar to the MOODLE Gap Fill

To select a sub-category of machine, the syntax is:

  "class": <category>.<sub-category>

In the JSON storyboard, a machine of type download is defined with the following syntax.

...
  "id": 12,
  "class": "machine.download"
...

2.4.1. Lock

The lock is an interactive machine waiting for a code (numerical or not) to trigger an exit (final or to another scene/room). There are several sub-categories of lockused in the mini-games:

  • lockText
  • lockNumerical
  • lockDigit[n] where n is the number of digits.
  • lockKeypad

The property exit is mandatory for the machine.lock. This is the exit code/word.

...
  "id": 23,
  "class": "machine.lockDigit[4]"
  "exit": 0000
...

2.4.2. Download

This machine opens a popup window to download data (an image for Image Processing mini-games or a sequence in bioinformatics) that must be processed locally with dedicated softwares.

2.4.3. Form

TODO

2.5. Switch

A switch allow to group multiples elements as children in the storyboard. It is useful for element that are not displayed at the same time in the scene and that replace each other. For example, if your game contains a closed drawer, at some point, the player will find a key to unlock it. When he use the key on the drawer, the sprite can change to the one locked to another, unlocked. These 2 sprites will be placed under the same switch. For a more concrete demonstration of this example, here's the follow up code in the JSON:

...
"id": 41,
    "class": "switch",
    "description": "TV on/off",
    "display": {
      "node": [42]
    },
    "children": [42,48]
  },

...

If we stick to the previous example, the id 42 correspond to the closed drawer (displayed at the start), and the id 48 correspond to the open drawer that will be displayed later.

The property display is a little bit different from the habitual display. Here we don't provide a media but just the id of the node you to display at start (property node).

Clone this wiki locally