Aventuras/README.md

Aventuras

AI-powered interactive fiction and creative writing application built with Tauri, SvelteKit, and TypeScript.

Features

Story Modes

• Adventure Mode - Interactive fiction with multiple-choice actions and world tracking
• Creative Writing Mode - Freeform collaborative writing with AI-generated suggestions
• POV Options - First, second, or third person perspective
• Tense Control - Past or present tense narrative style

AI Integration

• OpenRouter API integration for 70+ LLM providers and models
• Streaming responses with real-time text generation
• Configurable models, temperature, and token limits
• Extended thinking/reasoning support with configurable effort levels
• Custom API endpoints for OpenAI-compatible providers
• API profiles for saving multiple configurations

Memory System

• Automatic chapter summarization to manage context windows
• Configurable token thresholds and chapter buffers
• Manual chapter creation and resummarization
• AI-powered memory retrieval for relevant past events
• Chapter metadata tracking (keywords, characters, locations, plot threads)
• In-story time tracking per chapter

Lorebook

• Unified entry system for characters, locations, items, factions, concepts, and events
• Dynamic state tracking (relationships, inventory, discoveries)
• Keyword-based and relevance-based context injection
• Hidden information and secrets system
• Aliases for flexible entry referencing
• Import/export support (JSON, YAML, SillyTavern format)
• SillyTavern character card import (V1/V2 JSON and PNG)
• AI-assisted autonomous lore management agent

Writing Tools

• Local grammar checking powered by Harper.js (WebAssembly)
• AI-powered style analysis for repetitive words and phrases
• Action suggestions that match player writing style
• Persistent action suggestions between sessions

World Tracking

• Character relationships and dispositions with portrait support
• Location visits and changes with automatic discovery
• Inventory management with equipment tracking
• Quest/story beat progression (milestones, revelations, plot points)
• In-story time tracking (years, days, hours, minutes)
• Collapsible UI cards for all world elements

Templates

• Built-in genre templates (fantasy, sci-fi, mystery, horror, slice of life)
• Custom template creation with system prompts
• Initial state configuration (protagonist, locations, items)
• Opening scene text support

Image Generation

• Embedded image generation in story entries
• AI-powered imageable scene detection
• NanoGPT provider integration
• Character portrait support for visual consistency
• Configurable image size (512x512 or 1024x1024)

Save and Restore

• Named checkpoints with full state snapshots
• Retry system for undoing actions and generating alternatives
• Character and time state preservation on retry

Network Sync

• Local network sync between devices
• QR code connection for easy pairing
• Push/pull stories between devices
• Server mode for sharing stories

UI Customization

• Multiple themes (dark, light, light solarized, retro console)
• Custom font selection (system or Google fonts)
• Adjustable text size (small, medium, large)
• Word count display toggle

Cross-Platform

• Desktop (Windows, macOS, Linux)
• Android (APK)
• iOS (planned)

Tech Stack

• Frontend: SvelteKit 5, TypeScript, Tailwind CSS
• Backend: Tauri 2 (Rust)
• Database: SQLite (via tauri-plugin-sql)
• AI: OpenRouter API
• Grammar: Harper.js (WASM)
• Icons: Lucide

Installation

Download Pre-built Binaries

Pre-compiled binaries are available on the Releases page:

Platform	Download
Windows	aventuras_x.x.x_x64-setup.exe
macOS	aventuras_x.x.x_x64.dmg
Linux	aventuras_x.x.x_amd64.deb / .AppImage
Android	aventuras_x.x.x.apk

Simply download the appropriate file for your platform and install.

Building from Source

Click to expand build instructions

Prerequisites

• Node.js 18+
• Rust (latest stable)
• For Android: Android SDK, NDK, Java 17+

Setup

# Clone the repository
git clone https://github.com/unkarelian/Aventuras.git
cd aventuras

# Install dependencies
npm install

# Run in development mode
npm run dev

# Or run with Tauri (desktop app)
npm run tauri dev

Building Desktop

npm run tauri build

Building Android

# Initialize Android target (first time only)
npm run tauri android init

# Build APK
npm run tauri android build -- --apk true

The unsigned APK will be at:

src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release-unsigned.apk

Signing APK

# Create keystore (first time only)
keytool -genkey -v -keystore release.keystore -alias myalias -keyalg RSA -keysize 2048 -validity 10000

# Align APK
zipalign -v 4 app-universal-release-unsigned.apk app-aligned.apk

# Sign APK
apksigner sign --ks release.keystore --ks-key-alias myalias --out app-release.apk app-aligned.apk

Project Structure

aventuras/
├── src/
│   ├── lib/
│   │   ├── components/     # Svelte components
│   │   │   ├── layout/     # AppShell, Header, Sidebar
│   │   │   ├── story/      # StoryView, ActionInput, etc.
│   │   │   ├── lorebook/   # Lorebook management UI
│   │   │   ├── memory/     # Chapter/memory management
│   │   │   └── world/      # Character, Location, Inventory panels
│   │   ├── services/       # Business logic
│   │   │   ├── ai/         # AI services (OpenRouter, context, memory)
│   │   │   ├── database.ts # SQLite operations
│   │   │   └── grammar.ts  # Harper grammar checking
│   │   ├── stores/         # Svelte stores (state management)
│   │   └── types/          # TypeScript interfaces
│   └── routes/             # SvelteKit routes
├── src-tauri/              # Rust backend
│   ├── src/
│   └── Cargo.toml
├── static/                 # Static assets
└── package.json

Configuration

API Key Setup

1. Get an API key from OpenRouter
2. Open Aventuras settings
3. Enter your API key in the API Settings section

Memory Configuration

Per-story memory settings:

• Token Threshold: Context size before auto-summarization (default: 24,000)
• Chapter Buffer: Recent messages protected from chapter boundaries (default: 10)
• Auto-Summarize: Enable/disable automatic chapter creation

Development

# Type checking
npm run check

# Watch mode type checking
npm run check:watch

# Build frontend only
npm run build

# Preview built frontend
npm run preview

Acknowledgments

• Tauri - Desktop/mobile app framework
• SvelteKit - Frontend framework
• OpenRouter - LLM API aggregator
• Harper - Grammar checking
• Lucide - Icon library