Quick Start Guide

A simplified guide for non-technical users to get started quickly.

What You'll Need

• A computer with internet access
• Node.js installed - Download here
• A code editor - We strongly recommend Visual Studio Code (it's free!)

Best Editor for Ink

Visual Studio Code (VS Code) is the best choice because:

• It's free and easy to use
• Has an Ink extension that helps you write scenarios
• Shows errors as you type
• Works on Windows, Mac, and Linux

To set up VS Code:

1. Download and install VS Code
2. Open VS Code
3. Click the Extensions icon on the left (looks like building blocks)
4. Search for "Ink" and install the extension by "inkle"
5. Now you can open your .ink files with syntax highlighting!

Step-by-Step Setup

1. Create Your Project from the Template

Using GitHub (Recommended):

1. Go to: https://github.com/LeftUnread/leftunread-scenario-example
2. Click the green "Use this template" button (near the top right)
3. Click "Create a new repository"
4. Fill in the details:
   • Repository name: Give it a name (e.g., my-scenario)
   • Description: Optional description of your scenario
   • Public or Private: Choose your preference
5. Click "Create repository"
6. On your new repository page, click the green "Code" button
7. Copy the URL shown
8. Open Terminal/Command Prompt (see next step)
9. Type: git clone and paste the URL, then press Enter
10. Type: cd your-repository-name (use the name you chose) and press Enter

2. Open Terminal/Command Prompt

On Windows:

• Press Windows Key + R
• Type cmd and press Enter

On Mac:

• Press Command + Space
• Type terminal and press Enter

3. Navigate to Your Project

If you haven't already (from step 1), navigate to your project folder.

In the terminal, type:

cd path/to/your/project

(Replace path/to/your/project with where you saved the files)

Example:

• Windows: cd C:\Users\YourName\Documents\my-scenario
• Mac/Linux: cd ~/Documents/my-scenario

4. Configure npm for GitHub Packages

Before installing dependencies, you need to set up authentication for GitHub Packages.

1. In your project folder, create a new file called .npmrc (you can do this in VS Code or any text editor)
2. Open .npmrc and add these two lines:

   @LeftUnread:registry=https://npm.pkg.github.com
   
   //npm.pkg.github.com/:_authToken=YOUR AUTH TOKEN

3. Replace YOUR AUTH TOKEN with your GitHub Personal Access Token
   • Go to https://github.com/settings/tokens
   • Click "Generate new token" → "Generate new token (classic)"
   • Give it a name like "npm packages"
   • Check the read:packages permission
   • Click "Generate token"
   • Copy the token (you won't see it again!)
   • Paste it in place of YOUR AUTH TOKEN in your .npmrc file
4. Save the .npmrc file

Important

Never share your .npmrc file or commit it to Git! Keep your token secret.

5. Install Dependencies

Type this and press Enter:

npm install

Wait for it to finish (this might take a minute).

6. Make Your First Build

Type this and press Enter:

npm run build:scenario

If you see "✅ Build complete", you're ready to go!

7. Test Your Scenario in the Browser (Optional)

Want to see your scenario in action before publishing? You can run it locally:

1. In the terminal, type:

   npm run run:scenario

2. Your browser should automatically open to https://localhost:3000

3. You can now test your scenario interactively!

4. To see changes after editing:

   • Save your changes to the scenario files
   • Restart the scenario in the browser (the changes are deployed automatically, but you need to restart the scenario to see them)

5. When you're done testing, press Ctrl+C in the terminal to stop the server

Testing Tip

This is perfect for testing your scenario before publishing! Make changes, save, restart the scenario, and see how it works.

Publishing Your Scenario

Before You Publish

You need two things:

1. Scenario ID - Get this from the website
2. API Key - Get this from the tokens page

Get Your Scenario ID

1. Open your web browser
2. Go to: https://leftunread.app/authors/test/scenarios
3. Click "Create New Scenario" (or similar button)
4. Fill in your scenario details
5. After creating, look at the URL in your browser
6. Copy the long string of letters and numbers at the end
   • Example: https://leftunread.app/authors/test/scenarios/abc-123-def-456
   • Copy: abc-123-def-456
7. Save this somewhere - this is your scenario ID (put it in .env as SCENARIO_ID)

Get Your API Key

1. Go to: https://leftunread.app/authors/test/manage-passport-tokens
2. Click "Create New Token" (or similar)
3. Give it a name like "My Publishing Key"
4. Copy the API key immediately - you won't see it again!
5. Save this somewhere safe - this is your API_KEY

Set Up Your .env File

1. In your project folder, find the file called .env.example
2. Make a copy of it and rename the copy to .env (just .env, no .example)
3. Open .env in a text editor
4. You'll see something like this:

   BASE_URL=
   SCENARIO_ID=
   API_KEY=

5. Fill it in like this:

   BASE_URL=https://leftunread.app
   SCENARIO_ID=abc-123-def-456
   API_KEY=your-api-key-here

   (Use your actual Scenario ID and API Key)
6. Save the file

Publish!

In the terminal, type:

npm run publish:scenario

If you see "✅ Upload complete", your scenario is published! 🎉

Making Changes to Your Scenario

Editing Scenario Content

1. Open the files in src/ink/ folder
2. Edit the .ink files with your narrative
   • Use #typing:3s to show typing indicators (can use s for seconds, m for minutes, h for hours)
   • Use #delay:5s to add pauses (can use s, m, or h)
   • See the Tag Reference for all available tags
3. Save your changes
4. Build again: npm run build:scenario
5. If there are no errors, publish: npm run publish:scenario

Common Files to Edit

• src/ink/ - Your scenario scripts (open these in VS Code!)
• src/contacts/ - Character information (JSON files)
• src/conversations/ - Conversation settings (JSON files)
• src/assets/ - Images and avatars

Using VS Code

You can open your entire project in VS Code:

1. Open VS Code
2. Click File → Open Folder
3. Select your project folder
4. Now you can edit all files easily!

Troubleshooting

"npm: command not found"

You need to install Node.js. Download it from nodejs.org.

"Failed to compile"

There's a syntax error in your Ink script. The error message will tell you which file and line number. Check that file for typos.

"Missing environment variable"

Your .env file is missing or incomplete. Make sure you created it and filled in all three values (BASE_URL, SCENARIO_ID, API_KEY).

"401 Unauthorized"

Your API key is wrong or expired. Go back to the tokens page and create a new one.

"Build artifact not found"

The build failed. Run npm run build:scenario first and fix any errors before publishing.

Tips for Beginners

Start Small

Don't try to write your whole scenario at once. Start with one simple conversation and build from there.

Test Often

Build your scenario frequently to catch errors early. It's easier to fix one small mistake than many big ones.

Save Your Credentials

Keep your Scenario ID and API Key in a safe place. You'll need them every time you publish.

Use Watch Mode

While editing, run npm run build:scenario -- --watch in the terminal. It will automatically rebuild when you save files.

Next Steps

Once you're comfortable with the basics:

• Check the Tag Reference Card for all available Ink tags
• Read the Ink Scripting Guide to learn all the features
• Check out the Project Structure to understand the files
• Learn about Building and Publishing in detail
• Set up GitHub Actions for automatic deployment

Getting Help

If you get stuck:

1. Check the error message - it usually tells you what's wrong
2. Read the relevant documentation page
3. Look at the example files to see how things work
4. Make sure you followed all the steps exactly

Remember: Everyone starts as a beginner. Take it one step at a time! 🚀