Tag Reference Card

A complete reference for all Encounters Ink tags. Bookmark this page for quick lookup!

All Available Tags

Display & State Tags

#initial

Purpose: Mark messages that existed before the player joined the conversation

Usage:

Hey Sarah, where are you? #initial
I'm getting worried now. #initial

When to use: For conversation history that happened before the story starts

---

#read

Purpose: Mark messages as already read by the player

Usage:

Good morning! #initial #read
Morning! How are you? #initial #read

When to use: Combined with #initial to show messages the player has already seen

---

#me

Purpose: Indicate the message is from the player (not the character)

Usage:

I'm doing great, thanks! #me #initial #read

When to use: To show the player's previous responses in the conversation history

---

Timing Tags

#typing:Xs

Purpose: Show typing indicator for X time before displaying the message

Usage:

Let me check... #typing:3s
I found something! #typing:5s
I'm writing you a long explanation... #typing:2m
I'll send you the full story... #typing:1h

Time units:

• s - seconds (e.g., #typing:5s)
• m - minutes (e.g., #typing:2m)
• h - hours (e.g., #typing:1h)

Guidelines:

• Short messages: 1-2 seconds
• Medium messages: 2-4 seconds
• Long messages: 4-10 seconds
• Very long messages: 1-2 minutes
• Extremely long messages: Use minutes/hours sparingly

When to use: To make conversations feel realistic and natural

---

#delay:Xs or #delay:HH:MM

Purpose: Wait before showing the message - either for a duration (e.g., 5s) or until a specific time (e.g., 08:00)

Usage:

I need to think about this. #delay:5s
Good morning! #delay:08:00 #typing:4s

Formats:

• Relative: #delay:10s, #delay:5m, #delay:2h - Wait for a duration
• Absolute: #delay:08:00, #delay:14:30 - Wait until a specific time of day (24-hour format)

When to use: To create pauses, build tension, simulate time passing, or schedule messages for specific times

Learn more: See the Delay Syntax Guide for detailed examples, patterns, and how absolute time delays work

---

Combining Timing Tags

#delay:Xs #typing:Ys

How it works:

1. Wait X time (delay)
2. Show typing indicator for Y time
3. Display the message

Example:

Let me check the security footage... #delay:5s #typing:4s
Oh my god. You need to see this. #delay:2s #typing:3s
I'm driving to the club now. #delay:20m #typing:3s
Just got back. Here's what I found... #delay:1h #typing:5s

When to use: For the most realistic messaging experience

---

Media Tags

#image:filename.jpg

Purpose: Display an image in the message

Usage:

Check out my new profile pic! #image:avatar.jpg
Look what I found! #image:evidence.png

Requirements:

• Image must be in src/assets/ directory
• Use just the filename, not the full path
• Supported formats: jpg, jpeg, png, gif, webp

When to use: To show photos, evidence, screenshots, or visual content

---

#link:url

Purpose: Make the message clickable, opening a URL

Usage:

Have you seen this? #link:www.youtube.com/watch?v=example
Check this article: #link:https://example.com/news

Notes:

• URL can include or omit https://
• Players tap/click the message to open the link
• Link opens in their browser

When to use: To share websites, videos, articles, or external content

---

#audio:filename.wav

Purpose: Display an audio player in the message

Usage:

Listen to this voice message #audio:message.wav
Here's the recording from that night #audio:recording.mp3

Requirements:

• Audio file must be in stories/your-story/assets/ directory
• Use just the filename, not the full path
• Supported formats: wav, mp3, ogg, m4a

When to use: To share voice messages, recordings, or audio evidence

---

#video:filename.mp4

Purpose: Display a video player in the message

Usage:

Watch this security footage #video:footage.mp4
Check out this clip #video:video.webm

Requirements:

• Video file must be in stories/your-story/assets/ directory
• Use just the filename, not the full path
• Supported formats: mp4, webm, mov

When to use: To share video clips, security footage, or video evidence

---

#gallery:item-id

Purpose: Unlock a gallery item and display it in the message

Usage:

I found this on Sarah's cloud backup #gallery:sample-video
Check out this photo I discovered #gallery:crime-scene-photo

Requirements:

• Gallery item must be defined in stories/your-story/gallery/ directory
• Use the gallery item's id field
• Automatically unlocks the item when message is sent

When to use: To reveal photos/videos from the gallery as part of the conversation

---

Location Tags

#pin:latitude,longitude

Purpose: Display a location/map pin in the message using coordinates

Usage:

We were at this bar downtown. #pin:51.5074,-0.1278
She said she was heading home around midnight. #pin:51.5074,-0.1278

Format:

• Coordinates in decimal degrees: latitude,longitude
• Can also use + separator: latitude+longitude
• Latitude range: -90 to 90
• Longitude range: -180 to 180

When to use: To share locations using raw coordinates, show where events happened, or mark important places

Example from alex.ink:

We were at this bar downtown. Last place I saw her. #pin:51.5074,-0.1278
She said she was heading home around midnight, but she never made it.

---

#location:location-id

Purpose: Display a location/map pin in the message using a location from your locations directory

Usage:

Meet me at the coffee shop. #location:coffee-shop
I'm at the crime scene now. #location:crime-scene

Requirements:

• Location must be defined in stories/your-story/locations/ directory
• Use the location's filename without .json extension
• Automatically unlocks the location when the message is sent

When to use: To share predefined locations from your story, automatically showing them on the player's map

Example:

I found the place where Sarah was last seen. #location:coffee-shop
Check your map - I've marked the location for you.

Note: This is preferred over #pin: when working with locations defined in your story, as it automatically unlocks the location and uses the location's full details (title, description, images, etc.).

---

#location_input:prompt

Purpose: Request the player to share any location (manual entry or GPS)

Usage:

Where did you see her?
* [Send location] #location_input:Where did you see her?
  ~ temp lat = GetPlayerLocationLatitude()
  ~ temp lng = GetPlayerLocationLongitude()
  Thanks for sharing that location!
  Let me check coordinates {lat}, {lng}...
  -> next_knot

Requirements:

• Must be used with a choice
• Use GetPlayerLocationLatitude() and GetPlayerLocationLongitude() to retrieve coordinates
• Player can enter any location or use their current GPS location

When to use: When you need the player to share a location but don't require them to physically be there

---

#location_input_gps:prompt

Purpose: Request the player to share their current GPS location (enforces physical presence)

Usage:

Prove you're at the scene.
* [Send GPS location] #location_input_gps:Prove you're at the scene
  ~ temp lat = GetPlayerLocationLatitude()
  ~ temp lng = GetPlayerLocationLongitude()
  ~ temp targetLat = 51.5074
  ~ temp targetLng = -0.1278
  ~ temp distance = GetDistanceBetween(lat, lng, targetLat, targetLng)
  ~ temp isNearby = IsWithinDistance(lat, lng, targetLat, targetLng, 100)
  
  {isNearby:
    Perfect! You're at the scene. I can see you're {distance}m away.
  - else:
    Hmm, you're {distance}m away. That's quite far...
  }
  -> next_knot

Requirements:

• Must be used with a choice
• Requires the player to use their actual GPS location (cannot manually enter)
• Use with IsWithinDistance() and GetDistanceBetween() functions for location verification
• Player must grant location permissions

When to use: For location-based gameplay where the player must physically visit a location

Related Functions:

• IsWithinDistance(lat, lng, targetLat, targetLng, radiusMeters) - Check if player is within a radius
• GetDistanceBetween(lat, lng, targetLat, targetLng) - Get distance in meters between two points

See External Functions Reference for more details on location functions.

---

Message Type Tags

#system

Purpose: Display the message as a system message (no sender)

Usage:

Mum added you to the group. #system #delay:1s
Alex left the conversation. #system

Notes:

• System messages appear centered and styled differently
• Automatically marked as read
• No sender avatar or name shown

When to use: For group chat events, notifications, or meta-information

---

Player Input Tags

#text_input:prompt

Purpose: Request text input from the player

Usage:

What's your name?
* [Continue]
  # text_input:Enter your name
  ~ player_name = GetPlayerInput()
  -> confirm_name

Requirements:

• Must be used with a choice that has only one option
• Use GetPlayerInput() function to retrieve the text
• Provide a helpful prompt for the player

When to use: When you need the player to type custom text (names, locations, answers)

---

#attach_image:prompt

Purpose: Request the player to select an image from their gallery

Usage:

Can you send me a photo for verification?
* [Continue]
  # attach_image:Select a photo for identity verification
  ~ attached_item = GetAttachedGalleryItem()
  -> verify_photo

Requirements:

• Must be used with a choice that has only one option
• Use GetAttachedGalleryItem() function to get the selected image ID
• Provide a clear prompt explaining what image is needed

When to use: When you need the player to select/send a specific image

---

Group Chat Tags

#from:contact-id

Purpose: Specify who sent the message in a group conversation

Usage:

Has anyone heard from Sarah? #from:alex
I've been trying to call her. #from:mum
Me too, this is really strange. #from:dad

Requirements:

• Only works in group conversations (type: "group")
• Contact ID must exist in src/contacts/ directory
• Must match the contact's id field exactly

When to use: Every message in a group chat (except player messages)

---

Cross-Conversation Tags

#notify:conversation-id:knot-name

Purpose: Trigger a specific knot in another conversation

Usage:

// In mum.ink
I'm calling the police now! #notify:alex:on_police_called

// In alex.ink  
== on_police_called ==
Mum just called the police. #typing:3s
They're sending someone over.
-> END

Requirements:

• Conversation ID must exist in src/conversations/
• Knot must exist in that conversation's Ink file
• Use format: conversation-id:knot-name

When to use: To create interconnected storylines where events in one conversation affect others

---

#unlockConversation:conversation-id[:delay]

Purpose: Make a new conversation available to the player

Usage:

Let me add Alex to this chat. #unlockConversation:family-group
I've created a group with everyone. #unlockConversation:investigation-team
Adding them now... #unlockConversation:family-group:10s

Requirements:

• Conversation ID must exist in src/conversations/
• Conversation should have initial: false in its JSON file
• Optional delay can use time units: s (seconds), m (minutes), h (hours)

When to use: To reveal new conversations as the story progresses

Note: The old #unlock: tag still works but #unlockConversation: is preferred for clarity.

---

#unlockContact:contact-id[:delay]

Purpose: Make a new contact available to the player

Usage:

I'll send you their contact info. #unlockContact:detective-morgan
You'll get their number soon. #unlockContact:witness:30s

Requirements:

• Contact ID must exist in src/contacts/ directory
• Optional delay can use time units: s (seconds), m (minutes), h (hours)

When to use: To reveal new contacts as the story progresses

Note: Contacts are automatically unlocked when you unlock a conversation containing that contact. Use this tag only when you want to unlock a contact without unlocking a conversation (e.g., adding someone to the contact list for future reference).

---

#unlockNews:article-id[:delay]

Purpose: Unlock a news article for the player to read

Usage:

Breaking news just came in! #unlockNews:sarah-missing
Check the news in a few minutes. #unlockNews:police-statement:5m

Requirements:

• News article must exist in stories/your-story/news/ directory
• Optional delay can use time units: s (seconds), m (minutes), h (hours)

When to use: To reveal news articles that relate to the story

---

#unlockNote:note-id[:delay]

Purpose: Unlock a note for the player to read

Usage:

I'm sending you the location now. #unlockNote:secret-location
You'll get it soon. #unlockNote:secret-location:30s

Requirements:

• Note must exist in stories/your-story/notes/ directory
• Optional delay can use time units: s (seconds), m (minutes), h (hours)

When to use: To reveal notes, clues, or documents as part of the story

---

#unlockLocation:location-id[:delay]

Purpose: Unlock a location on the player's map

Usage:

I'm sending you the crime scene location. #unlockLocation:crime-scene
The location will appear on your map in 5 minutes. #unlockLocation:coffee-shop:5m

Requirements:

• Location must exist in stories/your-story/locations/ directory
• Use the location's filename without .json extension
• Optional delay can use time units: s (seconds), m (minutes), h (hours)

When to use: To reveal locations as the story progresses without sending a message with the location

Example:

I found where Sarah was last seen. Let me mark it on your map. #unlockLocation:coffee-shop
You should check it out when you get a chance.

Note: If you use #location:location-id in a message, it automatically unlocks the location, so you don't need both tags. Use #unlockLocation when you want to unlock a location without displaying it in the message.

---

Tag Combination Examples

Realistic Conversation Flow

Hey, are you there? #initial #read
Yeah, what's up? #me #initial #read
I need to tell you something... #initial #read
Let me find the right words... #typing:4s #delay:3s
Sarah is missing.

Building Tension

I'm checking the security footage now. #typing:3s
This might take a minute... #delay:5s
Wait. #delay:3s #typing:1s
Oh no. #delay:4s #typing:2s
You need to see this. #image:footage.jpg #typing:3s

Group Chat Conversation

Has anyone seen Sarah today? #from:alex #delay:2s
No, I thought she was with you. #from:mum #delay:4s
She's not answering her phone. #from:alex #delay:3s
I'm getting really worried now. #from:dad #delay:5s

Unlocking New Conversations

I think we need to bring everyone together. #typing:3s
Let me create a group chat. #delay:2s
Adding everyone now... #delay:3s #unlockConversation:family-group

Unlocking Content with Delays

I'm sending you the detective's contact. #unlockContact:detective-morgan:5s
Breaking news alert coming soon! #unlockNews:sarah-case:2m
I'll share the location in a bit. #unlockNote:meeting-spot:30s
The crime scene location will appear on your map soon. #unlockLocation:crime-scene:1m

Sharing Locations

// Using predefined location (automatically unlocks)
I found the place! Check this out. #location:coffee-shop

// Using raw coordinates
We were here last night. #pin:51.5074,-0.1278

// Unlocking without displaying in message
I'm marking the location on your map now. #unlockLocation:crime-scene
You should investigate when you can.

Player Input

What's your name?
* [Continue]
  # text_input:Enter your name
  ~ player_name = GetPlayerInput()
  Nice to meet you, {player_name}!
  -> END

Gallery Items

I found this video on Sarah's cloud backup. #gallery:sample-video
Take a look at what the security camera captured. #gallery:footage-001

Cross-Conversation Events

// In alex.ink
I'm going to call the police right now. #typing:2s
They said they'll send someone. #notify:mum:on_police_called #delay:4s

// In mum.ink
== on_police_called ==
Alex just called the police. #typing:3s #delay:5s
Thank god. I was too scared to do it myself.
-> END

Media with Timing

Let me find that photo... #typing:4s #delay:3s
Here it is! #image:photo.jpg #typing:2s
This was taken last night at the club. #typing:3s

Common Patterns

Initial Conversation History

Show what happened before the player joined:

Hey! How's it going? #initial #read
Pretty good! You? #me #initial #read
Can't complain! Want to meet up later? #initial #read
Sure! Where? #me #initial #read
How about the cafe at 3pm? #initial

Typing Simulation

Make it feel like someone is really typing:

Hmm, let me think about that... #typing:3s
Actually, you know what? #typing:2s #delay:2s
I think you might be right. #typing:2s

Time Passing

Show significant time gaps:

I'm going to check something. Be right back. #typing:2s
Okay, I'm back. #delay:10m #typing:1s
You won't believe what I found. #typing:3s

// Or for longer periods:
I need to go to the police station. #typing:2s
Just got back from talking to the detective. #delay:2h #typing:3s

Revealing Information

Build suspense when sharing important info:

I need to tell you something. #typing:2s
It's about Sarah. #typing:3s #delay:3s
She's been lying to us. #typing:2s #delay:4s
About everything. #typing:2s

Tag Rules & Limitations

✅ Can Combine

• #initial + #read + #me
• #typing:Xs + #delay:Xs
• #image:file / #audio:file / #video:file + #typing:Xs + #delay:Xs
• #gallery:id + #typing:Xs + #delay:Xs
• #link:url + #typing:Xs
• #notify:conv:knot + #delay:Xs
• #unlockConversation:id / #unlockContact:id / #unlockNews:id / #unlockNote:id + #typing:Xs + #delay:Xs
• #system + #delay:Xs

⚠️ Special Cases

• #from:id - Only in group conversations
• #notify:conv:knot - Target knot must exist
• #unlockConversation:id - Target conversation must exist
• #unlockContact:id - Target contact must exist
• #unlockNews:id - Target news article must exist
• #unlockNote:id - Target note must exist
• #unlockLocation:id - Target location must exist
• #location:id - Target location must exist, automatically unlocks
• #pin:lat,lng - Coordinates must be valid
• #gallery:id - Gallery item must be defined
• #text_input:prompt - Must be used with a single-option choice
• #attach_image:prompt - Must be used with a single-option choice
• #location_input:prompt - Must be used with a choice
• #location_input_gps:prompt - Must be used with a choice

❌ Don't Do This

• Don't use #from:id in individual conversations
• Don't reference non-existent files in media tags
• Don't reference non-existent locations in #location: or #unlockLocation:
• Don't use spaces in tag values (use hyphens instead)
• Don't forget the # symbol before tags
• Don't use #text_input, #attach_image, #location_input, or #location_input_gps without a choice
• Don't use both #location:id and #unlockLocation:id for the same location in the same message

Quick Tips

1. Test your timing - What feels right in writing might be too fast or slow in practice
2. Be consistent - Similar messages should have similar timing
3. Less is more - Don't overuse delays, they can slow down the story
4. Vary your patterns - Mix quick responses with thoughtful pauses
5. Think realistic - How would a real person text in this situation?

Troubleshooting

Tag not working?

• Check spelling and syntax
• Ensure file/conversation/contact exists
• Verify you're using the right tag for the conversation type

Timing feels wrong?

• Adjust the seconds value
• Test with real players
• Consider the message length and emotional weight

Image not showing?

• Check the file is in src/assets/
• Verify the filename is exact (including extension)
• Make sure the image file isn't corrupted

Group chat messages not showing sender?

• Add #from:id to every message
• Verify contact IDs match your contact files
• Check conversation type is "group"

Location not appearing on map?

• Check the location file exists in stories/your-story/locations/
• Verify the location ID matches the filename (without .json)
• Ensure location has been unlocked (via #location:id, #unlockLocation:id, or initial: true)
• Check for JSON syntax errors in the location file

Location not displaying in message?

• Verify you're using #location:id (not #unlockLocation:id)
• Check the location ID is correct
• Ensure the location file has valid latitude and longitude fields

Next Steps

• Learn about dynamic functions: External Functions Reference
• See tags in action: Ink Scripting Guide
• Learn the full workflow: Getting Started
• Understand the structure: Project Structure