TIPS: The Inside Place Storymaker Manual

Introduction

This manual documents TIPS (The Inside Place Storymaker), a tool for creating interactive stories on the Playdate. You'll work primarily in Articy to build your story, and the system will handle converting it to the proper JSON format for the game engine.

Story Flow Structure

In Articy, you'll create a Flow container that holds different types of story nodes. Each node determines how the player progresses through your game.

Flow Node Types

Flow nodes can be configured as one of several types by adding specific text to their "Text" field:

Map Node Configuration

To create a map with visitable locations:

1. Create a Flow node and add map to its Text field
2. Add more configuration as needed: map, backgroundImage=map1.png, bgm=birdsong
3. Create child Flow fragments for each location on the map

Video Node Configuration

1. Create a Flow node with video in its Text field
2. Add file paths: video, videoPath=intro.pdv, audioPath=intro.wav

Cutscene Node Configuration

1. Create a Flow node with cutscene in its Text field
2. Create dialogue nodes directly inside this Flow fragment, just like any other scene
3. The scene will play automatically when reached in the story flow

Endgame Node Configuration

For endgame nodes with multiple endings, use this format:

endgame
type=endgame
endings:
Good Ending=100,ending_good.pdv,ending_good.wav
Bad Ending=50,ending_bad.pdv,ending_bad.wav
Terrible Ending=0,ending_terrible.pdv,ending_terrible.wav

Where each ending line follows the format: Name=RequiredScore,VideoPath,AudioPath

Scene Structure

In Articy, you'll build scenes by connecting dialogue nodes to create a flow of conversation and events.

A typical scene consists of dialogue nodes connected in sequence, with possible branches for choices. When exported, these scenes are converted to JSON files for the game engine.

Stage Direction Commands

Stage directions control what happens in your scenes. Add them as comma-separated key-value pairs like key=value.

Visual Elements

Audio Controls

Animation Controls

Game State

Animation Types and Parameters

For animation and portraitAnimation, the format is: type:duration:intensity

• Types:
  • shake - Shakes the element randomly in different directions
  • alarm - Creates a flashing/alert effect
  • woozy - Creates a wavy, disorienting animation
  • bounce - Makes the element bounce up and down
  • slideUp - Slides the element up into view
  • slideDown - Slides the element down into view
• Duration: Time in milliseconds (e.g., 500)
• Intensity: Strength of animation (e.g., 10)

Background Image Animations

Apply effects to background images using imageAnimation:

• handheld - Slight camera shake effect
  • Format: imageAnimation=handheld:intensity:speed
  • Example: imageAnimation=handheld:5:1
• stop - Stops any active background animation
  • Format: imageAnimation=stop

Dialogue Nodes

Dialogue nodes are the basic building blocks of a scene and can include text, speaker information, and stage directions.

{
  "id": "DFr_12345678",
  "type": "dialogue",
  "text": "Hello, world!",
  "speaker": "Character Name",
  "next": ["NextNodeId"],
  "animation": {
    "type": "slideUp",
    "duration": 500,
    "intensity": 10
  }
}

Required Fields

• id: Unique identifier for the node (usually starts with DFr_)
• type: Must be "dialogue"
• text: The text content to display
• next: Array of node IDs to proceed to (usually a single ID)

Optional Fields

• speaker: Character name to display (empty for narrator)
• menuText: Text to display in choice menus referencing this node
• Any stage direction fields as shown in previous section

Death/Fail States

You can trigger a game over or fail state from any dialogue node using the failState stage direction:

{
  "id": "DFr_DEADEND",
  "type": "dialogue",
  "text": "You feel a strange sensation as the world fades to black...",
  "failState": {
    "type": "DEATH"
  }
}

When a fail state is triggered:

1. The current scene ends
2. The player is shown a game over screen
3. Any items obtained in the current scene are removed
4. The player is returned to the map or previous safe state

To create a fail state, add failState=TYPE to your stage directions, where TYPE can be:

• DEATH - Generic death/failure
• FALL - Death by falling
• DROWN - Death by drowning
• ATTACK - Death by attack

The type affects which game over screen and sound effects are played.

Choice Nodes

Choice nodes present the player with multiple options to select from.

Creating Choices in Articy

Choices are created automatically when you connect one dialogue node to multiple subsequent dialogue nodes:

1. Create a dialogue node that will present the choices
2. Create multiple dialogue nodes for each possible choice
3. Connect the first node to all choice nodes

Configuring Choice Options

For each dialogue node that represents a choice option:

1. Enter the text to display in the choice menu directly in the Menu Text field
2. Add any required item properties in the Stage Directions field:

requiredItem=item_key, fallbackText=You need a key...

Available choice properties:

Hub Nodes and Repeated Choices

TIPS supports hub nodes (choice nodes that you can loop back to repeatedly) for creating interactive dialogues with multiple selectable options. By default, previously selected options can be hidden to encourage players to explore all dialogue paths.

Hub Node Behavior

When a player returns to a hub node, previously selected options are automatically filtered out until all options have been explored. This creates a natural progression through dialogue trees and ensures players see all content.

• Options disappear after being selected once
• When all options have been explored, the full list becomes available again
• This behavior is managed automatically by the dialogue system

Creating Hub Nodes in Articy

1. Create a dialogue node that will serve as the hub (connection point)
2. Create dialogue nodes for each option branching from the hub
3. Connect option nodes back to the hub node to create loops

Example Hub Node Structure

Hub Node: "What would you like to know about?"
  ↓
  Option 1: "Tell me about your background." → Dialogue → Return to Hub
  ↓
  Option 2: "What are you working on?" → Dialogue → Return to Hub
  ↓
  Option 3: "I need to go now." → Exit dialogue

Previously selected options will not appear in the list until all options have been explored, allowing for clean dialogue progression.

Inventory System

TIPS supports two types of inventory items that serve different gameplay purposes.

Narrative Items

Narrative items advance the story when examined in the player's inventory. When selected, they trigger their own scene.

Creating Narrative Items in Articy

1. Create a new Template with properties for your item
2. Set ItemType = 0 (for narrative)
3. Set isConsumable = false (narrative items are typically not consumed)
4. Add an ItemName and ItemDescription
5. Set ItemImage to the filename (e.g., "laptop.png")

Creating Narrative Item Scenes

For each narrative item, create a corresponding Flow fragment in your main Flow:

1. Name the Flow fragment to match your item (e.g., "item_logans_laptop")
2. Add item to its Text field
3. Build the scene that plays when the player examines this item

Utility Items

Utility items are used to solve puzzles and unlock choices in dialogue. They can be consumable or reusable.

Creating Utility Items in Articy

1. Create a new Template with properties for your item
2. Set ItemType = 1 (for utility)
3. Set isConsumable = true/false depending on whether it should disappear after use
4. Add an ItemName and ItemDescription
5. Set ItemImage to the filename
6. Add an ItemHint that describes what the item does - this will be shown if the player tries to use a choice that requires this item

Using Utility Items in Dialogue

To create a choice that requires an item, add these stage directions to your dialogue node:

requiredItem=item_a_sandwich, fallbackText=You need something to eat...

Automatic Item Discard System

TIPS includes a smart system that automatically discards utility items that are no longer needed:

• When a player moves to a new map, any utility items that can only be used in completed/inaccessible locations are automatically discarded
• The player sees a message explaining that they discarded items that are no longer useful
• This keeps the inventory clean and focused on relevant items

JSON Output Structure

When converted, items appear in inventory_items.json like this:

// Narrative item example:
{
  "key": "item_logans_laptop",
  "name": "Logan's Laptop",
  "description": "The laptop from Logan's house.",
  "image": "assets/images/items/no_image.png",
  "type": "narrative",
  "consumable": false,
  "useScript": "FFr_EB82AA1A.json"
}

// Utility item example:
{
  "key": "item_a_sandwich",
  "name": "Sandwich",
  "description": "A consumable item.",
  "image": "assets/images/items/no_image.png",
  "type": "utility",
  "consumable": true,
  "usableIn": ["FFr_D09B2739", "FFr_A5F93E81", "FFr_EB82AA1A"],
  "hint": "Is soft and wet and crispy all at once."
}

Animation Controls

You can add various animations to enhance your scenes directly through stage directions in Articy.

Text Box Animations

To animate the text box containing dialogue, add an animation stage direction:

animation=shake:500:10

Format: animation=type:duration:intensity

Character Portrait Animations

To animate the character portrait, use the portraitAnimation stage direction:

portraitAnimation=slideUp:200:10

The same animation types apply to portraits. Common uses:

• portraitAnimation=shake:500:8 - Character is angry or surprised
• portraitAnimation=bounce:500:10 - Character is excited or energetic
• portraitAnimation=slideUp:300:0 - Character smoothly enters the scene
• portraitAnimation=slideDown:300:0 - Character smoothly exits the scene

Background Image Animations

Apply effects to background images using imageAnimation:

imageAnimation=handheld:5:1

• handheld - Creates a subtle camera shake effect
  • Format: imageAnimation=handheld:intensity:speed
  • Intensity: How much the image moves (1-10 recommended)
  • Speed: How quickly the image moves (0.5-2 recommended)
• stop - Stops any active background animation
  • Format: imageAnimation=stop

Animation Tips

• Use animations sparingly for maximum impact
• Match the animation type to the scene's emotion or action
• Lower intensity values (5-15) usually look better than extreme values
• Animation durations between 300-1000ms work well for most effects

Map and Location Structure

The game world is organized into maps containing locations that can be visited.

Map Format in story.json

{
  "type": "map",
  "mapId": 1,
  "backgroundImage": "map1.png",
  "bgm": "birdsong",
  "unlocked": false,
  "locations": [
    {
      "name": "Location Name",
      "locationId": "FFr_12345678",
      "unlocked": true,
      "optional": false,
      "conditionalUnlock": ["FFr_PreviousLocationId"],
      "sprite": "point.png",
      "nextEvent": {
        "type": "text",
        "script": "FFr_12345678.json"
      },
      "coordinates": {
        "x": 100,
        "y": 120
      }
    }
  ]
}

Location Configuration

Each location on a map is a child Flow fragment inside the map node. Configure locations using stage directions in the Text field:

name=Secret Cave, unlocked=true, optional=false, coordinates=150:65

Available location properties:

Media Integration

TIPS supports multiple media formats.

Supported Media Types

• Background images (PNG)
• Character portraits with different moods
• Music and sound effects
• Video sequences (for cutscenes)

Video Events

{
  "type": "video",
  "videoPath": "intro2.pdv",
  "audioPath": "intro2.wav"
}

Audio Integration

TIPS supports both background music and sound effects to enhance the player experience.

Background Music (BGM)

Background music can be set for entire scenes or maps using the bgm directive:

bgm=mysterious.wav

This will play the music file until another BGM is set or the current one is stopped. To stop music, use:

bgm=

Place music files in assets/sounds/ folder with supported formats:

• WAV files - Uncompressed, highest quality but largest file size
• MP3 files - Compressed, smaller size but more CPU intensive
• ADPCM files - Recommended format with good balance of quality and performance

Sound Effects (SFX)

Trigger sound effects at specific points in dialogue with the sfx directive:

sfx=bloop

Sound effects are ideal for:

• UI feedback (selections, confirmations)
• Environmental sounds in scenes
• Item pickups or interactions

Recommended Formats

ADPCM is the preferred audio format for Playdate. You can convert to ADPCM using:

• Audacity: File > Export Audio… > File type: WAV (Microsoft), Encoding: IMA ADPCM
• ffmpeg: ffmpeg -i input.mp3 -acodec adpcm_ima_wav output.wav

Score System

TIPS tracks a player score that determines which ending they'll get.

Adding Score

• Add points with the addScore stage direction
• Example: addScore=10

Score-Based Endings

In story.json, endings can be defined based on score thresholds:

{
  "type": "endgame",
  "id": "FFr_65111FF5",
  "endings": [
    {
      "name": "Terrible Ending",
      "requiredScore": 0,
      "videoPath": "ending1.pdv",
      "audioPath": "ending1.wav"
    },
    {
      "name": "Nailed It!",
      "requiredScore": 100,
      "videoPath": "ending3.pdv",
      "audioPath": "ending3.wav"
    }
  ]
}

Conversion Process

After building your story in Articy, you'll need to convert it to the proper JSON format for the game engine. This is done using the provided Python conversion scripts.

Export From Articy

1. In Articy, go to File > Export
2. Select Custom JSON export
3. Make sure to include objects, localization, and hierarchy data
4. Export to a dedicated folder

Running the Conversion Scripts

Place the scripts scene_convert.py and story_convert.py in the same folder as your exported data, then run:

# First convert individual scenes
python scene_convert.py

# Then convert the full story structure and inventory items
python story_convert.py

This creates a /story/ subfolder containing:

• story.json: Overall story structure and flow
• inventory_items.json: All inventory items and their properties
• Individual scene files (FFr_*.json and DFr_*.json)

Importing to the Game Project

Copy all files from the /story/ folder to the assets/story folder in your game project before building.

cp -r story/* /path/to/game/assets/story/