Getting Started

Welcome to LeftUnread! This guide will help you create your first interactive messaging-based scenario.

What is LeftUnread?

LeftUnread is a platform for creating immersive, interactive scenarios that unfold through realistic messaging conversations. Players receive messages from characters, make choices, and influence the narrative in real-time.

Prerequisites

Before you begin, make sure you have:

• Node.js (v16 or higher) installed - Download here
• A code editor - We recommend Visual Studio Code (free)
• Basic understanding of JSON
• Familiarity with narrative writing
• (Optional) Knowledge of the Ink scripting language

Recommended Setup

Visual Studio Code with the Ink extension provides:

• Syntax highlighting for .ink files
• Auto-completion
• Error detection while you write
• Easy file navigation

To install:

1. Download VS Code
2. Open VS Code
3. Click the Extensions icon (or press Ctrl+Shift+X / Cmd+Shift+X)
4. Search for "Ink" by inkle
5. Click Install

Quick Start

1. Create Your Project from Template

The easiest way to start is by using the GitHub template:

1. Go to the LeftUnread Scenario Example Repository
2. Click the green "Use this template" button (top right)
3. Click "Create a new repository"
4. Give your repository a name (e.g., my-leftunread-scenario)
5. Choose if you want it public or private
6. Click "Create repository"

Now clone your new repository to your computer:

git clone https://github.com/YOUR-USERNAME/your-repository-name.git
cd your-repository-name

(Replace YOUR-USERNAME and your-repository-name with your actual GitHub username and repository name)

2. Configure npm for GitHub Packages

Before installing dependencies, you need to set up authentication for GitHub Packages. Create a .npmrc file in your project root:

touch .npmrc

Open .npmrc in a text editor and add the following:

@LeftUnread:registry=https://npm.pkg.github.com

//npm.pkg.github.com/:_authToken=YOUR AUTH TOKEN

Replace YOUR AUTH TOKEN with your GitHub Personal Access Token (PAT). You can create a PAT at https://github.com/settings/tokens. Make sure it has the read:packages permission.

Security Note

Never commit your .npmrc file with your actual token to Git! The .npmrc file should be in your .gitignore. Consider using environment variables or npm config commands instead if you're working in a team.

3. Install Dependencies

npm install

4. Explore the Project Structure

Your project should look like this:

leftunread-scenario-example/
├── src/
│   ├── assets/          # Images and media files
│   ├── contacts/        # Contact definitions (JSON)
│   ├── conversations/   # Conversation configurations (JSON)
│   └── ink/            # Ink script files (.ink)
├── scripts/
│   ├── build-scenario.cjs    # Build script
│   └── publish-scenario.cjs  # Publish script
├── .env.example        # Environment variables template
└── package.json

5. Build Your Scenario

Compile your Ink scripts and package your scenario:

npm run build:scenario

This will:

• Compile all .ink files to JSON
• Copy assets to the build directory
• Generate a manifest
• Create a dist/scenario-build.zip file

6. Test Your Scenario Locally (Optional)

You can run your scenario in a browser for local testing:

npm run run:scenario

This will:

• Start a local development server
• Open your scenario in your browser at https://localhost:3000
• Automatically deploy changes when you save files
• Allow you to test your scenario interactively

Testing Workflow

1. Edit your scenario files (src/ink/*.ink, src/contacts/*.json, etc.)
2. Save your changes
3. Refresh your browser or restart the scenario to see updates
4. Test the conversation flow and player choices
5. When satisfied, build and publish with npm run build:scenario and npm run publish:scenario

::: note Restart Required After making changes to your scenario, you'll need to restart the scenario in the browser to see updates. The changes are deployed automatically, but the scenario session needs to be restarted. :::

7. Configure Publishing (Optional)

To publish your scenario to the LeftUnread server, you'll need to set up your credentials.

Step 1: Create Your Scenario

1. Go to the Scenarios Management Page
2. Click "Create New Scenario" or similar button
3. Fill in your scenario details (name, description, etc.)
4. After creation, copy the UUID from the URL in your browser's address bar
   • Example: https://leftunread.app/authors/test/scenarios/abc123-def456-...
   • The UUID is the long string of letters and numbers at the end
   • This is your SCENARIO_ID

Step 2: Get Your API Key

1. Go to the Manage Passport Tokens Page
2. Create a new API token (or use an existing one)
3. Copy the API key - you won't be able to see it again!
4. This is your API_KEY

Step 3: Configure Your Environment

1. In your project folder, copy .env.example to .env:

   cp .env.example .env

2. Open .env in a text editor and fill in your details:

   BASE_URL=https://leftunread.app
   SCENARIO_ID=your-uuid-from-step-1
   API_KEY=your-api-key-from-step-2

3. Save the file

Step 4: Publish Your Scenario

Now you can publish:

npm run publish:scenario

For Non-Technical Users

Don't worry if this seems complicated! Here's the simple version:

1. Create your scenario on the website and copy the ID from the URL
2. Get an API key from the tokens page
3. Put both into the .env file
4. Run the publish command

Understanding the Template Scenario

The template includes "The Missing Friend" - a mystery scenario where the player helps find a missing person named Sarah. This serves as a complete working example you can learn from and modify.

Key Components

Contacts (src/contacts/*.json):

• Character profiles with names, avatars, and phone numbers

Conversations (src/conversations/*.json):

• Conversation configurations linking contacts to Ink scripts
• Defines conversation types (individual or group)

Ink Scripts (src/ink/*.ink):

• The actual narrative content and branching logic
• Player choices and character responses

Assets (src/assets/):

• Character avatars and images used in the scenario

Next Steps

Now that you have the basics:

1. Understand the Project Structure - Learn about each file and folder
2. Learn Ink Scripting - Master the narrative scripting language
3. Build and Publish - Deploy your scenario to production

Tips for Beginners

Start Small

Begin with a simple conversation between two characters before creating complex branching narratives.

Test Frequently

Build and test your scenario often to catch errors early. The build script will show compilation errors.

Study the Example

The example scenario demonstrates many features - read through the Ink files to see how they work.

Getting Help

• Check the Ink documentation
• Review the example project files
• Look at the API reference for advanced features