How ziyulisiyuan/ai-grouproleplay works
群像本 is a local-first, multi-character roleplay engine. A user works through the web UI to configure a group and its characters, then sends a message; the server passes it to a GroupSession, which judges routing, presence and knowledge boundaries before generating character output and recording the turn. Its other major capabilities include scene-map authoring, status and verbatim-memory ledgers, auditable judgments, and replayable file storage. The README documents the runtime flow; sampled source confirms several module calls, while some feature-level links are documented but not source-verified.
Main entry points: engine.ts GroupSession · server.ts HTTP server · chat.ts LLM transport · App.tsx Web app
Components 23
User interface
- Web app
web/src/App.tsx - Chat interface
web/src/chat.tsx - Group editor
web/src/groupinfo.tsx - Web API client
web/src/api.ts - Android shell
android/app/src/main/java/com/roleplay/groupchat/MainActivity.java
Conversation runtime
- HTTP server
src/server.ts - GroupSession
src/group/engine.ts - Generation host
src/host.ts - LLM transport
src/llm/chat.ts
Roleplay systems
- Judge and router
src/group/host.ts - Fallback routing
src/group/router.ts - Presence and map
src/group/presence.ts - Knowledge ledger
src/group/knowledge.ts - Status ledger
src/group/status.ts - Character assets
src/group/persona.ts - Group authoring
src/group/scaffold.ts - Scene authoring
src/group/scene.ts
Local state and models
- StoryStore
src/store.ts - Local files
src/store.ts - Model settings
src/settings.ts - Judgment traces
src/group/thinking.ts
Other components
- User
- Configured model
Connections 27
- User → Web app: uses
README.md - Web app → Chat interface: opens chat
web/src/App.tsx - Web app → Group editor: edits group
web/src/App.tsx - Chat interface → Web API client: sends messages
web/src/chat.tsx - Group editor → Web API client: saves settings
web/src/groupinfo.tsx - Web API client → HTTP server: calls /api
README.md - HTTP server → GroupSession: runs turns
README.md - HTTP server → Group authoring: updates assets
src/server.ts - HTTP server → Scene authoring: saves descriptions
src/server.ts - GroupSession → StoryStore: opens and records
src/group/engine.ts - GroupSession → Character assets: loads characters
src/group/engine.ts - GroupSession → Judge and router: requests judgments
src/group/engine.ts - GroupSession → Presence and map: loads scene state
src/group/engine.ts - GroupSession → Status ledger: loads status
src/group/engine.ts - GroupSession → Knowledge ledger: manages knowledge
src/group/engine.ts - Judge and router → Fallback routing: falls back to
src/group/host.ts - Judge and router → LLM transport: requests judgments
src/group/host.ts - GroupSession → Generation host: generates replies
src/group/engine.ts - Generation host → LLM transport: streams output
src/host.ts - LLM transport → Model settings: resolves provider
src/host.ts - LLM transport → Configured model: sends model requests
README.md - Model settings → Local files: reads configuration
src/settings.ts - StoryStore → Local files: appends story log
src/store.ts - GroupSession → Judgment traces: records judgments
src/group/engine.ts - Group authoring → Character assets: creates character assets
src/group/scaffold.ts - Scene authoring → Local files: persists scene data
- Android shell → HTTP server: hosts on device
README.md