Comprehensive guide to using RoleRealm’s features and creating engaging interactive stories.
Timeline-Based Events Everything in RoleRealm happens on a unified timeline. Events include:
Character Memory Each character maintains their own memory of events they witnessed. This means:
Dynamic Turn Taking Characters don’t take strict turns. Instead:
Story-Driven Objectives Two levels of goals guide the narrative:
Speaking (Just type naturally)
⚡ You: I think we should explore the cave first
Your input becomes dialogue for your character.
listen - Silent observation
⚡ You: listen
skip - Prompt continuation
⚡ You: skip
progress - Check story status
⚡ You: progress
📖 STORY PROGRESS
════════════════════════════════════════════════════════════════════
Story: The Quest for the Phantom Pearl
Progress: 25% (2 of 8 objectives complete)
✓ COMPLETED OBJECTIVES:
1. Decipher the mysterious map and determine the first destination
2. Navigate through the Siren's Strait without losing the ship
→ CURRENT OBJECTIVE:
Find and explore the abandoned island marked with the skull symbol
info - Character information
⚡ You: info
Shows details about all active characters:
reset - Start fresh
⚡ You: reset
quit or exit** - Save and exit
⚡ You: quit
Note: Some commands may be added in future versions
Every AI character has three parts:
Each turn, characters evaluate:
Situation: Player asks "What do you think, Captain?"
Marina evaluates:
- Not directly addressed to me
- Topic is relevant (I care about the ship)
- Captain will probably answer
→ Decision: SILENT (Priority: 0.2)
Reasoning: "The Captain was directly asked and should answer first"
Captain evaluates:
- Directly addressed to me
- I have authority to decide
- My opinion matters here
→ Decision: SPEAK (Priority: 0.9)
Reasoning: "I was directly asked for my opinion"
Result: Captain speaks
Characters only remember what they witnessed:
# Timeline has 10 events
# Marina was present for events 1-7
# Jack entered at event 5
Marina's memory: [Event1, Event2, Event3, Event4, Event5, Event6, Event7]
Jack's memory: [Event5, Event6, Event7]
This enables:
Scene 1: Captain's Quarters
Present: Captain, Marina
Captain: *leans in conspiratorially* I didn't want to say this in front
of Jack, but I think he's been taking more than his fair share of the loot.
Marina: *eyes widen* Are you certain? That's a serious accusation.
[Marina now knows this secret, Jack does not]
Scene 2: Main Deck (30 minutes later)
Present: Captain, Marina, Jack
Jack: *walks over cheerfully* What are you two talking about?
Marina: *exchanges glance with Captain* Just discussing the route.
[Marina can choose to reveal or hide the information]
Character dialogue with action:
Captain: *slams fist on table* We sail at dawn, no exceptions!
Components:
Environmental or transitional events:
[Scene at Ship Deck] Dark storm clouds gather on the horizon as
waves crash against the hull. Thunder rumbles in the distance.
Components:
Physical actions without speech:
[ACTION] Marina: carefully unfolds the ancient map and spreads it
on the barrel, weighing down the corners with coins
Characters joining or leaving:
[ENTERED] Jack: bursts through the door, out of breath and soaking wet
[LEFT] Old Sailor: hobbles off toward the galley, muttering about
superstitious young folk
The system builds context from recent timeline:
For Characters (making decisions):
Recent events from character's memory:
Captain: *studies the map* These markings indicate dangerous waters.
You: What kind of dangers are we talking about?
Marina: *traces finger along route* Reefs, whirlpools, possibly sirens.
[Scene at Ship Deck] The wind picks up, making the sails flutter.
For You (visual display):
Recent Conversation:
💬 Captain: These markings indicate dangerous waters.
💬 You: What kind of dangers are we talking about?
💬 Marina: Reefs, whirlpools, possibly sirens.
🎬 [Scene at Ship Deck]: The wind picks up...
Automatic Saving
quit or exit[Story Name]/group_chat.jsonWhat’s Saved:
Loading
Stories have ordered objectives:
"objectives": [
"Decipher the map", // Must complete first
"Navigate the strait", // Then this
"Find the island", // Then this
...
]
Linear Progression:
When story has an objective, characters receive individual tasks:
Story Objective: “Navigate through the Siren’s Strait”
Character Objectives (assigned by AI):
Dynamic Assignment:
Frequency: Every 3-5 turns
Process:
Example Evaluation:
Story Objective: "Navigate through the Siren's Strait"
Character Status:
- Captain: "Maintain steady course" → COMPLETED
New objective: "Inspect ship for damage from rough passage"
- Marina: "Use celestial navigation" → COMPLETED
New objective: "Rest and recover from concentration effort"
- Jack: "Watch for dangers" → CONTINUING
(Still watching as they finish passage)
Story Objective Status: COMPLETE
Next Story Objective: "Find the abandoned island marked with skull symbol"
View anytime with progress command:
📖 STORY PROGRESS
════════════════════════════════════════════════════════════════════
Story: The Quest for the Phantom Pearl
Progress: 37% (3 of 8 objectives complete)
✓ COMPLETED OBJECTIVES:
1. Decipher the mysterious map and determine the first destination
2. Navigate through the Siren's Strait without losing the ship
3. Find and explore the abandoned island marked with the skull symbol
→ CURRENT OBJECTIVE:
Recover the ancient compass hidden in the island's temple ruins
CHARACTER OBJECTIVES:
Captain: Search the temple's main chamber for clues
Marina: Decipher the ancient runes on the temple walls
Jack: Keep watch for traps and dangers
UPCOMING OBJECTIVES:
5. Evade or confront the rival pirate crew hunting the same treasure
6. Use the compass to locate the underwater cave entrance
7. Solve the riddles guarding the inner chamber of the cave
8. Claim the Phantom Pearl and escape before the cave collapses
Direct Address:
You: Jack, what do you think we should do?
[Jack receives high priority to respond]
Group Questions:
You: Does anyone know how to read these symbols?
[All characters evaluate based on their knowledge]
[Character with relevant knowledge gets higher priority]
Character-to-Character:
Captain: Marina, check those navigation charts again.
Marina: *nods and unfolds the charts* Right away, Captain.
[Natural back-and-forth between AI characters]
Characters get higher priority when:
Lower priority when:
System creates scenes when:
Environmental Scene Example:
[Scene at Ancient Temple Ruins] The air grows cold as you enter the
temple. Moss covers ancient stone walls, and strange symbols glow
faintly in the darkness. Water drips somewhere in the distance.
Transition Scene Example:
[Scene Transition] Several hours pass as the crew navigates through
the treacherous waters. The sun begins to set, painting the sky
in brilliant oranges and reds.
Characters can join or leave mid-conversation:
Entry Example:
[Scene at Tavern]
Present: You, Innkeeper
You: Have you seen anything unusual lately?
Innkeeper: Well, now that you mention it...
[ENTERED] Mysterious Stranger: pushes through the door, cloak dripping
with rain, and takes a seat at the bar
Present: You, Innkeeper, Mysterious Stranger
Innkeeper: *lowers voice* Speak of the devil...
[Stranger can now participate in conversation]
[Stranger's memory starts from this point]
Exit Example:
Captain: *stands abruptly* I need to check on the crew. You lot carry on.
[LEFT] Captain: strides off toward the main deck
Present: You, Marina, Jack
[Captain no longer receives broadcasts]
[Captain's memory stops here]
[Private conversation possible]
Events that shape the narrative beyond just dialogue:
Player-Initiated (future feature):
⚡ You: /scene We travel to the temple ruins
[System generates appropriate scene transition]
AI-Generated:
❌ "What do you think?"
✓ "Captain, do you think we can make it through the storm?"
❌ "Can someone help me?"
✓ "Marina, can you help me decipher these symbols?"
❌ "I agree with the Captain"
✓ "*nods firmly* I agree with the Captain, we should sail at dawn"
✓ "I don't trust this. Something feels wrong about this treasure."
✓ "Are we really going to ignore what Jack saw?"
✓ "*challenges the Captain* With all respect, this plan is too risky"
listen Strategically
❌ "nice, friendly, helpful"
✓ "sarcastic wit, loyal to a fault, secretly insecure about magic abilities"
✓ Captain: "Gravitas, seafaring expressions, commands respect"
✓ Jack: "Casual slang, enthusiastic, interrupts with excitement"
✓ Marina: "Precise technical language, thoughtful pauses, scholarly"
✓ "Sees Jack as a younger brother, protective but frustrated by his recklessness"
vs
❌ "Friends with Jack"
✓ "Prove herself worthy despite being the youngest crew member"
✓ "Find redemption for past cowardice by being brave this time"
Solution:
MAX_CONSECUTIVE_AI_TURNS in config.py (lower = less AI chatter)Solution:
PRIORITY_RANDOMNESS for more varietySolution:
Solution:
frequency_penalty in character JSONLast Updated: December 2025
Author: Jit Roy
License: MIT