Characters
Characters are project-scoped entities that represent speaking roles in dialog scene blocks. A character stores descriptive metadata used both in the UI and as context for AI image generation and LLM prompts.
Data model​
| Field | Type | Description |
|---|---|---|
id | number | Primary key |
projectId | number | Owning project |
name | string | Display name |
description | string | Prose description (age, appearance, personality) |
traits | string[] | Array of short trait labels |
imageUrl | string | null | URL of portrait image |
createdAt | Date | — |
Image storage​
Character images are stored under uploads/characters/<projectId>/ and served via GET /characters/file/* (no auth required, so <img> tags work directly).
AI image generation​
POST /characters/:id/generate-image calls the image generation pipeline using the character's description and traits as the prompt. The global image-generation prompt settings (admin-configurable per project) are prepended.
LLM context​
When LLM endpoints run analysis or generation for an episode, all characters in the project are included in the system context so the model can reference consistent names, appearances, and traits.
Frontend components​
| Component | Path |
|---|---|
| Character list | CharacterListPanel |
| Character form | CharacterFormModal |
| Image picker | CharacterImageSection |
| Dialog block assignment | SceneBlock (character dropdown) |
Permission scopes​
| Scope | What it guards |
|---|---|
CHARACTER_CREATE | Creating a character |
CHARACTER_EDIT | Editing name / description / traits |
CHARACTER_DELETE | Deleting a character |
CHARACTER_IMAGE_GENERATE | AI image generation |
CHARACTER_IMAGE_UPLOAD | Manual image upload |
CHARACTER_IMAGE_DELETE | Removing the portrait |