RoleRealm-A-Story-Driven-Roleplay

An interactive AI-powered roleplay system that brings characters to life through dynamic conversations and story-driven experiences.

Screenshots

Features

• Dynamic Character Interactions - Create and interact with multiple AI characters, each with unique personalities and speaking styles
• Natural Conversations - Advanced conversation management with full context awareness
• Story Progression System - Structure your narratives with story arcs, scenes, and objectives
• Persistent Sessions - Automatic chat history and story state saving
• Context Awareness - Characters remember past interactions across sessions
• Multi-Character Support - Seamlessly manage conversations with multiple AI characters

Getting Started

Prerequisites

• Python 3.8+
• OpenRouter API key

Installation

1. Clone the repository:

   git clone https://github.com/Jit-Roy/RoleRealm.git
   cd RoleRealm
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Create a .env file and add your OpenRouter API key:

   OPENROUTER_API_KEY=your_api_key_here
   

Running RoleRealm

Simply run the main script:

python main.py

Project Structure

RoleRealm/
├── main.py                 # Main entry point
├── [Story Name]/           # Story-specific folders (e.g., "Pirate Adventure")
│   ├── characters/         # Character definition JSON files for this story
│   ├── story/              # Story JSON file (single file per story)
│   └── [story_name]_chat.json  # Saved conversation history for this story
├── managers/               # Core system managers
│   ├── characterManager.py
│   ├── timelineManager.py  # Unified timeline management (messages + scenes)
│   ├── storyManager.py
│   └── turn_manager.py
├── loaders/                # Data loaders
│   ├── character_loader.py
│   └── story_loader.py
├── helpers/                # Helper utilities
│   └── response_parser.py
└── config.py               # Configuration settings

For more info visit docs/README.md

Customization

Creating a New Story

1. Create a new folder with your story name (e.g., My Adventure)
2. Inside, create two subfolders:
   • characters/ - For character JSON files
   • story/ - For the story JSON file (single file only)

Creating Characters

Define characters in JSON format in the [Story Name]/characters/ folder. Each character should include:

• Name and traits
• Speaking style
• Background and relationships
• Goals and knowledge base

Creating Stories

Design your story in JSON format in the [Story Name]/story/ folder with:

• Story title and description
• Sequential objectives (list of objectives to achieve)
• Story progression logic

Contributing

Contributions are welcome! Feel free to submit issues or pull requests.

License

This project is open source and available under the MIT License.

This site is open source. Improve this page.