主角光环 是一款基于 Google Gemini 大模型驱动的新一代互动小说引擎。它超越了传统的文字冒险游戏，构建了一个集成了实时多模态生成、无限平行宇宙管理、动态情感羁绊与沉浸式视听特效的完整世界模拟器。
作为“主角”，你不仅是故事的经历者，更是世界的缔造者。AI 作为“地下城主（DM）”将实时响应你的每一个意图，生成逻辑严密且充满惊喜的剧情、画面与音效。
- 双模态输入：支持传统的选项决策（Choice Mode）与高自由度的自然语言输入（Text Mode）。
- 文学叙事架构配置：在开局时可指定 10种叙事结构（如复线型、辐射型、蛛网型）和 6种高级叙事手法（如非线性叙事、嵌套式叙事、打破第四面墙），让 AI 不仅写故事，更是在进行文学创作。
- 长时记忆管理 (RAG)：内置分层记忆系统，分为
记忆区（Context Window）、剧情记忆（摘要）、长期记忆（归档）、核心记忆（不可变事实）及物品清单。 - 上帝模式 (God Mode)：提供“全局查找替换”工具，允许玩家直接修正 AI 的记忆偏差或批量修改剧情设定，不仅是玩游戏，更是写书。
- 预设事件队列 (Scheduled Events)：玩家可随时化身为“导演”，预设未来将要发生的事件（如“下一章遭遇宿敌”、“在酒馆偶遇神秘人”）。
- AI 智能编排：AI 会读取预设队列，并尝试将其自然地融入当前剧情节奏中，避免生硬转折。
- 叙事手法融合：当预设事件与“非线性叙事”等手法结合时，AI 可能会以倒叙、预知梦或侧面描写的方式来呈现该事件，极大地丰富了表现力。
- 电影级镜头调度 (Cinematic Camera)：系统能自动解析剧情中的视觉提示词（Visual Prompt），智能识别 Shot Size（景别）：
- 特写 (Close-up)：缓慢推近，聚焦情感。
- 远景 (Long Shot)：缓慢平移，展现宏大场景。
- 动态透视 (Dynamic)：应用鱼眼或大透视效果增强冲击力。
- 混合生图引擎 (Hybrid Generation)：
- Google Gemini: 用于高精度角色与关键帧生成。
- Pollinations.ai: 用于生成“无限流”动态背景（Smart Background），确保场景永远不重复且无需消耗 Key 配额。
- ModelScope / FLUX: 支持接入国内模型源进行高质量渲染。
- 动态视觉特效层:
VisualEffectsLayer根据剧情关键词（如“雷霆”、“治疗”、“黑暗”）自动触发粒子特效。
- 节点图可视化 (Canvas Tree)：采用 SVG 与 HTML 混合渲染的无限存档树，直观展示所有命运分支。支持鼠标拖拽、缩放，玩家可以像观测者一样俯瞰整个时间线。
- 无缝回溯与分支：随时点击任意历史节点，瞬间穿越回那个时刻，开辟新的平行宇宙。
- 数据导入导出：支持导出完整存档或仅导出“世界观配置”JSON，方便社区分享设定。
- 动态立绘与垫图：支持上传参考图（Ref Image）固定画风，AI 根据外貌描述实时生成角色头像。
- 原型系统 (Archetypes)：引入荣格心理学原型（如“导师”、“阴影”、“变形者”），赋予 NPC 更深层的行为逻辑。
- 好感度可视化：AI 实时分析交互，动态调整 NPC 好感度，并在 UI 上以可视化进度条呈现。
- 可视化编剧工作台：引入专业的剧情蓝图模块，允许玩家像小说家一样规划章节大纲。
- 双视图切换：
- 脑图视图 (Graph View)：基于无限画布的思维导图。支持创建“悬浮卡片”（如前置条件、关键角色、预设伏笔、灵感便签），通过拖拽连线或直接投递的方式将其“挂载”到具体章节上，直观管理剧情脉络。
- 列表视图 (List View)：适合线性规划与批量管理，支持批量修改章节字数目标、节奏（Pacing）等参数。
- 智能章节推进：每个章节包含目标字数、必触发的关键事件及硬性约束。AI 会实时监控章节内的字数增长、伏笔触发率与角色互动频次，智能判定章节是否“完结”并引导剧情进入下一章。
services/geminiService.ts: (核心大脑) 负责所有与 Google Gemini API 的通信，包括 Prompt 构建、JSON 清洗、降级策略及 Tool Calling。
hooks/useGameEngine.ts: (心脏与状态机) 管理游戏的主循环、状态流转（Setup -> Playing -> Loading）、自动存档、音频调度及全局 UI 状态。
components/screens/: 顶级页面组件（GameScreen,SetupScreen,LandingScreen,LoadGameScreen）。setup/: 设定阶段的子面板组件。plot/: (剧情蓝图子系统)PlotBlueprintModal.tsx: 蓝图系统的主容器与状态管理器。PlotGraphView.tsx: 脑图编辑器，处理节点拖拽、连线逻辑与悬浮卡片交互。PlotListView.tsx: 列表编辑器，处理章节排序与批量操作。ChapterEditor.tsx: 章节详情面板，用于精细化编辑单个章节的参数与约束。
modals/: 弹窗系统（SystemModals包含画廊/设置,GameplayModals包含历史/角色详情）。VisualEffectsLayer.tsx: Canvas 粒子特效层。TypingText.tsx: 核心打字机组件，包含实体识别与高亮逻辑。SmoothBackground.tsx: 双缓冲背景切换组件。
types.ts: 全局 TypeScript 类型定义，包含PlotChapter,FloatingNode等新结构。constants.ts: 静态配置，包含叙事架构定义、世界观预设文本等。
- 前端框架: React 19 (利用最新的 Hooks 模式)
- 语言: TypeScript (全类型覆盖，包括 Gemini SDK 类型定义)
- 样式: Tailwind CSS (大量使用
backdrop-blur,animate,clip-path等高级特性实现 Glassmorphism 和 Cassette Futurism 风格) - AI SDK: Google GenAI SDK (Gemini 2.5/3.0 Models)
- 图形: HTML5 Canvas (用于粒子特效) + SVG (用于连接线绘制)
- 配置环境: 确保拥有 Google Gemini API Key。
- 启动应用:
- 进入首页，点击“系统设置”。
- 在“AI 模型配置”中填入 API Key（若未通过环境变量注入）。
- (可选) 配置 ModelScope Key 以获得更好的绘图体验。
- 开启旅程:
- 点击“开启新人生”。
- 填写主角设定，或粘贴一段小说大纲点击“智能解析”。
- (进阶) 在“剧情蓝图”面板中，使用脑图模式规划你的故事大纲。
- 点击“启动体验”，等待世界生成。
2025-12-18 修复剧情蓝图的开篇（第一幕）字数、触发事件及互动统计进当前活跃章节的进度同步数值；修复到达章节详情设定以及总字数后没有自主跳到下一章节的bug。
2025-12-2 系统设置增加模型提供商，同时支持OpenAI兼容接口；剧情回顾增加对每一段“场景”的可编辑功能；修复完善其他若干。
2025-12-1 剧情蓝图面板新增“智能章纲”，可根据用户已有的世界观、主角档案、配角信息自动生成每一章节的章纲走向，对章节数量、每章节字数、新增配角数量、新增组织数可控。
-
环境准备
- Node.js (建议 v18+)
- npm 或 yarn
-
安装依赖
npm install
-
配置环境变量 在项目根目录创建
.env文件，填入你的 API Key：API_KEY=your_google_gemini_api_key_here # 可选：ModelScope Key 用于增强绘图 # VITE_MODELSCOPE_KEY=your_key_here
-
启动项目
npm start # 或 npm run dev
推荐使用 Vercel 或 Netlify 进行零配置部署。
- 将代码推送到 GitHub 仓库。
- 在 Vercel 中导入该仓库。
- 关键步骤：在部署配置页面的 Environment Variables 中添加：
API_KEY: 你的 Google Gemini API Key
- 点击 Deploy，等待构建完成即可访问。
- API 配额: 频繁生图可能消耗大量 Token，建议在设置中按需调整模型版本。
- 数据存储: 所有存档均存储在浏览器
LocalStorage中。清理浏览器缓存会导致存档丢失，请定期使用“导出存档”功能备份。