Dropins Reference

Dropins are reusable components that can be integrated into the text. Examples are input fields to let the reader input values such as names of heroes or dice rollers that display spinning dice and let the reader roll some random values. Other examples include components that get executed when the component position comes into view of the reader.

StoryQuest includes some ready-to-go dropins for common uses and a flexible way of creating new dropins for specific projects. Dropins can be created and changed from the web editor in the "Layout" section.

Using Dropins

Dropins are similar to statements with the difference that an author can create new dropins and can customize their behaviour. To add a dropin put the following statement into the text:

{dropinName(dropinParameters):dropinBody}

Multiple parameters are divided by , and the body can span multiple lines. In general, the dropin statement resembles the standard statements described in the QuestML Language Reference.

Available Standard Dropins

StoryQuest comes with a set of standard dropins that can be edited and customized in the web editor.

Inputfield

This displays a text input field and a save button:

{dropin(inputfield,variableName,placeholder,saveButtonLabel):textLabel}

with the following parameters:

• variableName: the variable the entered value is stored in.
• placeholder: the input field placeholder text.
• saveButtonLabel: the label of the button on the input field.
• textLabel: the text displayed above the input field.

Examples

{dropin(inputfield,heroname,Enter Name,Save):The Name of your Hero}

This displays an input field labeled The Name of your Hero with the given placeholder and button label. When the button is touched, the given value is stored in the variable heroname

Dice Roller

This provides a convinient way of rolling two dice in your text. The dropin displays two spinning dice with the ability to "stop" them by touching the dice. Stopping the dice calculates a random dice value. The resulting value is the sum of both dice, thus giving random numbers between 2 and 12:

{dropin(diceroller,variableName,minRollValueToPass,textPass,textFail):textLabel}

with the following parameters:

• variableName: the variable the random result value is stored in.
• minRollValueToPass: the minimum value for the roll to pass, can be a model variable name or a number.
• textPass: the text that is displayed when the roll passes.
• textFail: the text that is displayed when the roll fails.
• textLabel: the label describing the task, can be an expression or a text.

Links and Dice Dropins: sometimes, it is required that a dice is rolled before a choice can be made. StoryQuest includes a service method localDiceRolled to determine whether a dice on the same page has rolled. The function returns true if one or more dice on the same page has been rolled. This can be used to activate a link when a dice has been rolled:

{link(the_temple, hasVisitedTheTemple, hasTheChalice&&localDiceRolled[]):
                You have the chalice, you can enter the temple.}

Examples:

{dropin(diceroller,attackRoll,10,Success!,Sorry - Failure!):You have to roll at least 10 to land an attack!}

Displays a dice roller with a minimum pass roll of 10. The result will be stored in the variable attackRoll.

{dropin(diceroller,attackRoll,attackValue,Success!,Sorry - Failure!):
      'You have to roll at least ' + model.getValue('attackValue') + ' to land an attack!'}

Displays a dice roller with the minimum value to pass taken from the model variable attackValue. The description is also an expression stating the minimum pass value from the model. Note that on the body, a full JavaScript expression must be used, so getting values from the model has to done using model.getVariable().

Dice Challenge

This dropin displays one single dice roller and calls a function with the result. The called function must be defined (for example using the globals.js) and returns a text that is displayed on the dropin after rolling the dice:

{dropin(dicechallenge,functionName):textLabel}

with the following parameters:

• functionName: the function that is called with the random result value.
• textLabel: the label describing the task, can be an expression or a text.

Links and Dice Dropins: sometimes, it is required that a dice is rolled before a choice can be made. StoryQuest includes a service method localDiceRolled to determine whether a dice on the same page has rolled. The function returns true if one or more dice on the same page has been rolled. This can be used to activate a link when a dice has been rolled:

{link(the_temple, hasVisitedTheTemple, hasTheChalice&&localDiceRolled[]):
                You have the chalice, you can enter the temple.}

Examples:

{dropin(dicechallenge,decreaseLifeForFall):How much damage you take from the fall?}

With the function decreaseLifeForFall defined as follows:

function decreaseLifeForFall(howMuch) {
    model.setValue("life", model.getValue("life") - howMuch);
    return "You loose " + howMuch + " life points!";
}

Displays a dice roller which reduces life by the rolled value and returns a custom message.

Audio

The audio dropin displays an audio player embedded in the text. The audio file is started when the audio player scrolls into view. A decription text can be given to be displayed in the audio player box.

{dropin(audio,soundFilePath):descriptionText}

with the following parameters:

• soundFilePath: the sound file used.
• descriptionText: description text displayed in the player box.

Examples:

{dropin(audio,audiomessage1.mp3):You find a nearly destroyed audio playback device. As you press the big red button on it, static noise is hissing and the device comes to life.}

Displays a player with the given text.

Video

The video dropin displays a video player embedded in the text. The video file is started when the video player scrolls into view.

{dropin(video,pixelWidth,pixelHeight):videoFilePath}

with the following parameters:

• videoFilePath: the video file used.
• pixelWidth: width of the video in pixels.
• pixelHeight: height of the video in pixels.

Note that the width and height are just to calculate the correct aspect ratio. The video will always span the entire width of the display and the height according to the aspect given through width and height.

Examples:

{dropin(video,1280,720):message1.mp4}

Displays a player with the given text and the option to play the video in fullscreen.

Creating Dropins

Dropins can be created from within the web editor in the layout tab. Dropins are HTML fragments that can contain any CSS or JavaScript. Note that a dropin can only contain one <script> element. If the dropin needs libraries, add the needed script includes to content.html, also editable in the layout tab of the editor.

When creating HTML for the dropin, it is encouraged to use id and class names that are guaranteed to be local to the dropin. Dropins can be added to a page multiple times, so be careful when using id attributes.

The variable dropinId contains a unique id for this particular dropin instance. This can be used to select the specific dropin element with JQuery: $("#" + dropinId) refers to the enclosing dropin element of this dropin instance.

Inside the dropin, the original parameters of the specific dropin call are available for the developer:

• _dropinBody.<typename of dropin> has the body content of the last dropin of this type added to the text.
• _dropinBody.<id of dropin> has the body content of the current dropin of this type added to the text.
• _dropinParams.<typename of dropin> has an array containing the params (minus the dropin type name) of the last dropin.
• _dropinParams.<id of dropin> has an array containing the params (minus the dropin type name) of the current dropin.