RP Lite Engine

RP Lite Engine is a roleplay-focused application for running immersive character chat with optional image generation and play-mode world simulation.

It combines:

• a React frontend (vite)
• an Express API backend
• model providers (Ollama + OpenAI-compatible)
• ComfyUI workflow-based image generation
• portrait-trait extraction to keep character visuals consistent across generated images

Table of Contents

1. Features
2. Tech Stack
3. Project Structure
4. Quick Start
5. Configuration
6. API Endpoints
7. How The Main Flows Work
8. Development Workflow
9. Testing
10. Troubleshooting
11. Contributing

Features

• Multi-character roleplay chat
• Provider selection between:
  • Ollama (/api/chat through Ollama API)
  • OpenAI-compatible servers
• Auto and manual image generation from chat turns
• Character portrait upload/generation
• Portrait trait extraction (hair/face/look/accessory summary) used in chat image prompts
• Personality profile generation/repair pipeline with strict contract checks
• Roleplay world/theme setup generation pipeline with validation and repair
• Play mode with world state, items, locations, and progression
• Persistent local state for settings, chat, characters, images, and play world

Tech Stack

• Frontend: React 18, Vite
• Backend: Express 4
• Styling: CSS + Tailwind tooling available
• Runtime: Node.js 18+
• Testing: Node test runner (node --test)

Project Structure

src/
  components/
    chat/
    tabs/
  hooks/
    play-mode/
  lib/
server/
  routes/
  *.ts
tests/
  lib/
  server/

Important Files

• Frontend shell/orchestration: src/App.tsx
• Frontend helper module: src/lib/appHelpers.ts
• Portrait actions hook: src/hooks/useCharacterPortraitActions.ts
• Prompt utilities and normalization: src/lib/rpUtils.ts
• Backend bootstrap: server/index.ts
• Backend route modules:
  • server/routes/chatRoutes.ts
  • server/routes/personalityRoutes.ts
  • server/routes/roleplayRoutes.ts
  • server/routes/imageRoutes.ts

Quick Start

Prerequisites

• Node.js >=18
• npm
• Optional external services:
  • Ollama
  • OpenAI-compatible inference endpoint
  • ComfyUI for images

Install

npm ci

Development (frontend + backend)

npm run dev

• Frontend: http://localhost:5173
• API: http://localhost:8787

Production build + run

npm run build
npm run start

Docker development

docker compose up -d

Stop:

docker compose down

Rebuild image when dependencies change:

docker compose up --build -d

Configuration

Configuration is managed in the UI and persisted in localStorage.

Provider settings

• provider: ollama or openai-compatible
• ollamaBaseUrl: default http://127.0.0.1:11434
• openaiBaseUrl: default http://127.0.0.1:8000/v1
• apiKey: optional for compatible endpoints
• model: selected model name

Generation settings

• temperature
• topP
• maxTokens
• instruct template controls

Image settings

• comfyBaseUrl: default http://127.0.0.1:8188
• workflow: ComfyUI API workflow JSON
• negativePrompt
• width, height, steps, cfg, seed

Supported workflow placeholders:

• {{PROMPT}}
• {{NEGATIVE_PROMPT}}
• {{WIDTH}}, {{HEIGHT}}
• {{STEPS}}, {{CFG}}, {{SEED}}

Persisted Local Storage Keys

• rp-lite:settings:v1
• rp-lite:characters:v1
• rp-lite:active-character:v1
• rp-lite:personality-profiles:v1
• rp-lite:active-personality:v1
• rp-lite:messages:v1
• rp-lite:images:v1
• rp-lite:play-mode:v1
• rp-lite:ui-console-logs:v1
• and related UI state keys

API Endpoints

Health and models

• GET /api/health
• POST /api/models

Chat

• POST /api/chat

Personality

• POST /api/personality/generate

Roleplay setup

• POST /api/roleplay/generate

Images

• POST /api/image/generate
• POST /api/portrait/traits

How The Main Flows Work

Chat reply flow

1. Frontend composes chat context/history.
2. Backend applies runtime tuning (rpTuning) and prompt composition (prompting).
3. Provider adapter runs model request.
4. Frontend stores reply and optional auto image prompt.

Chat image flow

1. Prompt is built from current chat message in buildChatImagePrompt.
2. If portrait traits exist, they are prefixed as appearance reference.
3. Frontend calls /api/image/generate.
4. Backend resolves ComfyUI workflow placeholders and returns image URL/data URL.

Portrait trait flow

1. User uploads or generates a portrait in Characters tab.
2. Frontend calls /api/portrait/traits.
3. Backend submits image to selected provider in provider-specific format.
4. Trait text is normalized and stored in character.portraitTraits.
5. Chat image prompts reuse those traits for visual consistency.

Development Workflow

Useful npm scripts

• npm run dev - run web + API in watch mode
• npm run dev:web - run Vite only
• npm run dev:server - run Express server only
• npm run test - run all tests
• npm run test:watch - watch mode tests
• npm run lint - syntax + build checks
• npm run build - production build

Make targets

• make install
• make dev
• make test
• make linting
• make build
• make up
• make up-build
• make down
• make logs

Code organization expectations

• Keep route registration in server/routes/* and business logic in domain modules.
• Keep component files focused; move non-UI logic to hooks/helpers.
• Prefer reusable pure helpers in src/lib.
• Add tests for behavior changes under tests/lib or tests/server.

Testing

Run full test suite:

npm test

Tests are grouped by domain:

• tests/lib/* for frontend shared logic
• tests/server/* for backend/provider/prompt contracts

Troubleshooting

Model list is empty

• Verify provider base URL.
• Ensure model service is running.
• Check API key for OpenAI-compatible endpoints.

ComfyUI generation fails

• Confirm ComfyUI is reachable at configured base URL.
• Confirm workflow JSON is valid API export.
• Ensure checkpoint names and node IDs match your local setup.

Portrait traits not generated

• Ensure selected model endpoint supports image input.
• Re-upload/regenerate portrait after selecting a compatible model.
• Check UI console logs for /api/portrait/traits errors.

Docker cannot reach host services

In Docker mode, host loopback addresses are remapped through host.docker.internal. Make sure the host service is bound and reachable from Docker.

Contributing

• Use small, focused pull requests.
• Prefer Conventional Commits:
  • feat: ...
  • fix: ...
  • chore: ...
• Include:
  • what changed
  • why it changed
  • test evidence (npm test, npm run lint, etc.)

If you plan a large refactor, split it into mechanical + behavioral commits so reviews stay clear.