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

Purpose: Wait X time before showing the message (no typing indicator)

Usage:

I need to think about this. #delay:5s
Okay, I've decided. #delay:3s
Let me drive over there. #delay:15m
I'm back from the police station. #delay:2h

Time units:

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

Guidelines:

• Quick pause: 1-3 seconds
• Emotional pause: 3-10 seconds
• Short activity: 1-5 minutes (driving, searching)
• Longer activity: 10-60 minutes (meetings, investigations)
• Major time jump: 1+ hours (next day, later that evening)

When to use: To create pauses, build tension, or simulate time passing

---

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

---

Group Chat Tags

#contact:contact-id

Purpose: Specify who sent the message in a group conversation

Usage:

Has anyone heard from Sarah? #contact:alex
I've been trying to call her. #contact:mum
Me too, this is really strange. #contact: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

---

#unlock:conversation-id

Purpose: Make a new conversation available to the player

Usage:

Let me add Alex to this chat. #delay:2s #unlock:family-group
I've created a group with everyone. #unlock:investigation-team

Requirements:

• Conversation ID must exist in src/conversations/
• Conversation should have initial: false in its JSON file

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

---

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? #contact:alex #delay:2s
No, I thought she was with you. #contact:mum #delay:4s
She's not answering her phone. #contact:alex #delay:3s
I'm getting really worried now. #contact: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 #unlock:family-group

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 + #typing:Xs + #delay:Xs
• #link:url + #typing:Xs
• #notify:conv:knot + #delay:Xs
• #unlock:id + #typing:Xs + #delay:Xs

⚠️ Special Cases

• #contact:id - Only in group conversations
• #notify:conv:knot - Target knot must exist
• #unlock:id - Target conversation must exist

❌ Don't Do This

• Don't use #contact:id in individual conversations
• Don't reference non-existent files in #image: or #unlock:
• Don't use spaces in tag values (use hyphens instead)
• Don't forget the # symbol before tags

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 #contact:id to every message
• Verify contact IDs match your contact files
• Check conversation type is "group"

Next Steps

• See tags in action: Ink Scripting Guide
• Learn the full workflow: Getting Started
• Understand the structure: Project Structure