心景 Mindscape

心景（Mindscape）是一个基于 Taro 的沉浸式情绪景观小程序。用户可以在一片会随时间与天气变化的旷野中行走，写下当下的心情，让记忆化作种子散落在世界里，也能与他人的记忆产生共鸣。

项目特性

• 沉浸式场景体验：通过 Canvas 渲染天空、山体、地面、角色、记忆对象与生态元素。
• 轻交互叙事：长按行走，上滑创作，下滑回溯，尽量减少传统表单式操作。
• 情绪记忆生成：输入文本并选择情绪标签后，生成对应记忆对象并投放到世界坐标中。
• H5 Mock 开发：浏览器环境默认使用 mock 数据和占位图，便于前端独立迭代。
• 微信云开发接入：小程序端接入云函数、云存储和真实数据读写能力。

技术栈

• Taro 4
• React 18
• TypeScript
• Zustand
• Sass
• 微信云开发

本地开发

安装依赖

npm install

启动 H5 调试

npm run dev:h5

适合调试：

• 页面结构和样式
• 基础手势与交互
• mock 记忆数据流
• 创作面板与个人面板

启动微信小程序调试

npm run dev:weapp

建议配合微信开发者工具使用，用来验证：

• 云开发能力
• 广告组件
• 小程序 Canvas 兼容性
• 真机交互体验

代码检查

npm run lint

项目结构

src/
├── components/       业务组件，如创作面板、回溯面板、教程、主画布
├── config/           环境与运行配置
├── constants/        世界、天气、情绪、调色板常量
├── core/
│   ├── engine/       场景引擎与画布适配
│   ├── entities/     角色、粒子、记忆对象等实体
│   ├── renderer/     天空、山、地面、角色、NPC、记忆渲染器
│   └── systems/      天气、时间、BGM、手势、生态、区块管理等系统
├── hooks/            手势、音频、场景等 Hook
├── pages/            页面入口
├── services/         云函数、AI、广告、社交等服务层
├── stores/           Zustand 状态管理
├── types/            类型定义
└── utils/            工具函数

cloud/
├── memory/           记忆相关云函数
└── interact/         共鸣与举报相关云函数

核心玩法与页面流转

当前主流程在 src/pages/index/index.tsx：

1. 进入欢迎页并选择旅人角色。
2. 点击“开始旅程”后展示新手引导。
3. 进入世界后，长按开始行走。
4. 上滑打开创作面板，写下文字并选择情绪。
5. 下滑打开个人回溯面板，查看自己的记忆和共鸣记录。
6. 点击场景中的记忆对象可触发共鸣等互动。

运行模式

H5 模式

• 默认 USE_MOCK = true
• 使用本地 mock 记忆与占位图资源
• 不依赖云函数即可完成大部分前端开发

小程序模式

• 通过 wx 环境判断启用真实后端
• 使用微信云开发环境、云函数与云存储
• 适合验证真实数据、内容安全与广告流程

配置入口见 src/config/env.ts。

云函数说明

memory

• create: 创建记忆
• getByChunk: 按区块获取记忆
• getByRange: 按范围获取记忆
• getMine: 获取我的记忆
• getMyResonances: 获取我共鸣过的内容
• delete: 删除记忆
• checkSafety: 内容安全检查

interact

• resonate: 共鸣
• unresonate: 取消共鸣
• check: 检查共鸣状态
• count: 获取共鸣数
• report: 举报内容

更完整的部署说明见 cloud/README.md。

开发注意事项

不要依赖运行时 process

小程序环境没有标准 Node.js process 对象。项目当前通过 typeof wx 和编译期常量做环境判断，新增代码请保持一致。

注意 Canvas API 兼容性

微信小程序的 Canvas API 与浏览器不完全一致。新增绘制逻辑时：

• 尽量避免直接依赖兼容性弱的 API
• 使用 ctx.save() / ctx.restore() 隔离绘图状态
• 修改渲染器后同时检查 H5 与小程序效果

保持 H5 mock 可用

即使修改了真实接口，也尽量不要破坏 H5 下的 mock 开发体验。前端调试效率高度依赖 mock 模式。

后续可扩展方向

• 接入真实 AI 图像生成服务，替换当前占位图逻辑
• 增强记忆对象与世界生态的联动反馈
• 完善社交互动、举报与内容审核链路
• 增加更细粒度的性能监控与分层测试