Flimo World

AI-Powered Interactive Story Creator - Create immersive narrative worlds with AI-generated characters, scenes, and interactive mystery gameplay.

📬 Contact: @jayfxfx on Telegram

---

✨ Features

Feature	Description
🗣️ Natural Language Creation	Describe your world in plain English and watch it come to life
🎭 AI-Generated NPCs	Unique characters with personalities, goals, and hidden secrets
🎨 AI Visuals	Environment scenes and character portraits generated by AI
🗺️ Interactive World Map	Visual world builder with draggable location markers
🔍 Mystery Game Mode	Play through stories as interactive detective games
💬 Multi-turn Editing	5-turn context memory for coherent story refinement

---

🛠 Tech Stack

Category	Technology
Frontend	React 18 + Vite
Styling	Tailwind CSS + shadcn/ui
3D Engine	Three.js + React Three Fiber
LLM	OpenRouter API (Gemini 2.5 Flash)
Image Generation	Google Gemini
Deployment	Cloudflare Pages

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• OpenRouter API Key
• Google Gemini API Key

Installation

# Clone the repository
git clone https://github.com/socekin/flimo_world.git
cd flimo_world

# Install dependencies
npm install

# Copy environment example
cp .env.example .env.local

Configuration

Edit .env.local with your API keys:

# LLM (Required)
VITE_OPENROUTER_API_KEY=your_openrouter_key
VITE_OPENROUTER_MODEL=google/gemini-3-flash-preview

# Image Generation (Required)
VITE_GEMINI_API_KEY=your_gemini_key
VITE_GEMINI_IMAGE_MODEL=gemini-2.0-flash-exp-image-generation

Development

npm run dev
# Open http://localhost:5173

Build

npm run build

---

📁 Project Structure

flimo_world/
├── src/
│   ├── agent/              # AI Agent System
│   │   ├── orchestrator/   # Workflow orchestrator
│   │   ├── router/         # Intent recognition & routing
│   │   └── skills/         # Modular skill modules (19+ skills)
│   ├── components/         # Shared React components
│   ├── pages/              # Page components (Create, Play, Game)
│   ├── game/               # 3D game mode components
│   ├── lib/                # API clients & utilities
│   └── i18n/               # Internationalization
├── public/                 # Static assets (images, videos, fonts)
└── *.json                  # Sample story & NPC data

---

🎮 How It Works

Create Mode - AI-Powered Story Generation

flowchart LR
    subgraph Input
        A[User Prompt]
    end
    
    subgraph LLM["🤖 LLM Processing"]
        B[Story World Generator]
        C[NPC Designer]
        D[Mystery Generator]
    end
    
    subgraph ImageAI["🎨 Image AI"]
        E[Environment Image]
        F[NPC Portrait]
        G[World Map Image]
    end
    
    subgraph Output
        H[Complete Story]
    end
    
    A --> B
    B --> C
    C --> D
    B --> E
    C --> F
    D --> G
    E --> H
    F --> H
    G --> H

Loading

Create Mode LLM Skills (18 Skills):

Skill	LLM Call	Description
story-world	✅	Generate world setting, background, truth
story-npc	✅	Create NPCs with personalities & secrets
mystery-world	✅	Generate mystery plot & clues
mystery-npc	✅	Create NPC dual versions (creator/player)
environment-image	✅	Generate scene images via Gemini
npc-image	✅	Generate character portraits
worldmap-layout	✅	Plan location layout on map
worldmap-image	✅	Generate final world map image

---

Play Mode - AI-Driven NPC Behavior

flowchart TD
    subgraph Init["Game Start"]
        A[Create Session] --> B[Initialize NPCs]
    end
    
    subgraph Loop["🔄 Behavior Loop"]
        C{NPC Idle?}
        D["🤖 Think API"]
        E[Get New Action]
        F[Navigate to Location]
        G[Perform Action]
    end
    
    subgraph Chat["💬 Player Interaction"]
        H[Open Chat]
        I["🤖 Chat API"]
        J[NPC Response]
        K[Update Memory]
    end
    
    B --> C
    C -->|Yes| D
    D --> E
    E --> F
    F --> G
    G --> C
    
    C -->|Player talks| H
    H --> I
    I --> J
    J --> K
    K --> C

Loading

Play Mode LLM APIs:

API	LLM Call	Description
POST /sessions	✅	Initialize NPC states with AI
POST /npcs/{id}/think	✅	NPC decides next action
POST /chat	✅	NPC responds to player
POST /interact	✅	NPC-to-NPC dialogue
POST /chat/open	✅	NPC greeting when player opens chat
POST /chat/close	✅	Summarize conversation to memory

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 License

This project is licensed under CC BY-NC-SA 4.0.

• ✅ Attribution - You must give appropriate credit
• ✅ ShareAlike - Derivatives must use the same license
• ❌ NonCommercial - Commercial use is not permitted

---

🙏 Acknowledgements

• OpenRouter - LLM API Gateway
• Google Gemini - AI Image Generation
• Three.js - 3D Graphics
• Vite - Build Tool
• Tailwind CSS - Styling

---

Made with ❤️ by Jay