Getting Started

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

What is Encounters?

Encounters is a platform for creating immersive, interactive stories 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 Encounters Story 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-encounters-story)
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:

@andy3471: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:

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

5. Build Your Story

Compile your Ink scripts and package your story:

npm run build:story

This will:

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

6. Test Your Story Locally (Optional)

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

npm run run:story

This will:

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

Testing Workflow

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

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

7. Configure Publishing (Optional)

To publish your story to the Encounters server, you'll need to set up your credentials.

Step 1: Create Your Story

1. Go to the Stories Management Page
2. Click "Create New Story" or similar button
3. Fill in your story details (name, description, etc.)
4. After creation, copy the UUID from the URL in your browser's address bar
   • Example: https://encounters.andyh.app/authors/test/stories/abc123-def456-...
   • The UUID is the long string of letters and numbers at the end
   • This is your STORY_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://encounters.andyh.app
   STORY_ID=your-uuid-from-step-1
   API_KEY=your-api-key-from-step-2

3. Save the file

Step 4: Publish Your Story

Now you can publish:

npm run publish:story

For Non-Technical Users

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

1. Create your story 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 Story

The template includes "The Missing Friend" - a mystery story 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 story

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 story 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 story often to catch errors early. The build script will show compilation errors.

Study the Example

The example story 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