🐱 南雍猫札 — Nanyang Cat Chronicles

「每一只猫猫，都值得被记住」—— 南京大学鼓楼校区猫咪探索游戏

✨ 项目简介

南雍猫札 是一款以 南京大学鼓楼校区 真实校园为蓝本的 2D 探索收集游戏。

玩家化身为一只小猫 🐱，漫步在水彩风格的校园地图中，邂逅散落在校园各处的真实猫咪。每只猫咪都有完整档案——姓名、性格、亲属关系、绝育状态、收养情况，用技术为流浪猫留下温暖的数字痕迹。

🎯 本项目同时也是编程大赛参赛作品，融合了 游戏开发 + 数据爬取 + 图像处理 + AI 智能体扩展 等多维技术。

💡 设计理念

🎯 项目初心

南京大学鼓楼校区栖息着数十只流浪猫，牠们早已成为校园文化的一部分。同学们自发成立了猫咪关爱组织，开发了「南雍猫札」微信小程序，记录每只猫咪的信息。然而，这些数据只停留在数据库里，缺少一个让人沉浸其中、真正”遇见”猫咪的入口。

于是我们想：如果能把整个鼓楼校园变成一张可探索的地图，让玩家化身为一只小猫，漫步其间，邂逅每一只真实的校园猫咪——让数据变得有温度，让记录变成体验。

🏫 校园 × 游戏：虚实融合的探索

现实世界                        游戏世界
   │                              │
   ├── 📸 真实校园照片 ──────▶ 🗺️ 地图纹理数据
   ├── 🐱 真实猫咪信息 ──────▶ 🎮 猫咪 NPC + 图鉴
   ├── 📍 真实出没地点 ──────▶ 🎯 游戏内猫咪坐标
   └── 👥 真实社区活动 ──────▶ 💬 游戏内置社区

我们不满足于做一个”校园导览”，而是希望用游戏的语言，讲好猫猫的故事。

🎨 艺术方向：水彩手绘风格

为什么不是3D写实？ —— 过于写实容易陷入”恐怖谷”，且开发成本极高
为什么不是像素风？ —— 已有同类项目采用，需要差异化
为什么选水彩？ —— 温柔、文艺、有温度，恰好契合”记录猫咪”的人文气质；同时程序化水彩算法也是比赛的技术亮点

🐱 玩家身份设计

你是一只小猫。 不是人类，不是游客，就是一只猫。

这个设计有几个巧思：

🐾 平等视角：你和其他猫咪是同类，相遇更自然
🎭 身份代入：降低”第三人称旁观”的距离感
💡 交互隐喻：小猫靠近小猫 → “打招呼”，比”人类走过去摸猫”更温柔

🧩 核心玩法循环

1
2
3

探索校园 ──→ 发现猫咪 ──→ 查看档案 ──→ 收集成就
   ↑                                      │
   └──────────── 继续寻找下只猫 ←──────────┘

借鉴了”宝可梦式探索 + 图鉴收集”的经典玩法，但做了减法：

❌ 不抓猫、不战斗——我们不是驯服者，是记录者
❌ 不强制教程——走就完事，发现是自然而然的事
✅ 靠近自动提示——不用刻意寻找
✅ 点击查看详情——想了解就了解，不想就继续逛

💬 社区：不止是游戏

猫咪的生存状况需要真实的人来关注。我们在游戏内置了社区模块：

板块	现实意义
📷 晒照	鼓励同学们拍猫、分享，形成UGC内容飞轮
🗣️ 讨论	交流猫咪动向、健康状态
💰 捐款	为绝育/医疗筹集资金，透明公示
🙋 志愿者	组织线下绝育/投喂活动

游戏的终点不是收集完数据，而是让更多人参与到关爱猫咪的行动中。

🤖 未来：AI 猫咪智能体

每只猫咪都有自己独特的性格（胆小、黏人、高冷…），我们预留了 AI 接口，未来可以：

🗣️ 猫咪对话：用户可以向特定猫咪提问，AI 模拟猫咪的”语气”回答
🗺️ 智能导航：AI 根据天气/时间推荐”今天去哪看猫”
📝 自动更新档案：社区帖子中提取信息，自动更新猫咪状态

🌟 一句话总结

用代码画一座校园，放几只猫，让路过的人停下来，看一眼。 ——这就是南雍猫札想做的事。

🎮 核心玩法

玩家（小猫）在地图中走动
      │
      ├── 🔍 靠近猫咪出没点 → 💡 发现提示！
      │
      ├── 🖱️ 点击猫咪 NPC → 📱 弹出完整档案卡片
      │     ├── 📸 猫咪照片
      │     ├── 📋 性别 / 花色 / 绝育 / 收养
      │     ├── 📝 性格描述
      │     ├── 👨‍👩‍👧 亲属关系树
      │     └── 📍 常出没地点
      │
      └── 🏆 集齐所有猫咪 → 成就解锁

功能模块	说明
🗺️ 校园探索	Unity 2D 动态生成地图，水彩纹理渲染
🐈 猫咪图鉴	弹出式信息面板，完整档案展示
🐱 玩家小猫	WASD 键盘操控 / 虚拟摇杆（移动端）
💬 社区系统	晒照 / 讨论 / 捐款 / 志愿者招募
🤖 AI 接口	猫咪 AI 助手 + 智能路线推荐（已预留）

🛠️ 技术栈

层级	技术	说明
🎮 游戏引擎	Unity 2022.3 LTS	2D Core 模板，C# 开发
🎨 渲染	SpriteRenderer + 程序化纹理	水彩风格材质
🧠 AI 扩展	REST API 接口预留	对接 LLM 智能体
🐍 数据获取	Python 爬虫 + tkinter GUI	从南雍猫札小程序抓取猫咪数据
📷 图像处理	Node.js sharp + 边缘检测	校园照片 → 地图轮廓数据
🌐 发布	Unity WebGL	浏览器直接玩

📁 项目结构

南雍猫札小项目/
│
├── 📖 README.md                          ← 你正在看的这个
│
├── 🎮 unity-game/                        ← ⭐ Unity 工程
│   ├── SETUP_GUIDE.md                    ← 详细安装步骤
│   ├── Packages/manifest.json            ← Unity 依赖包
│   └── Assets/Scripts/
│       ├── Core/GameManager.cs           ← 🎯 全局状态管理 + 全部数据类型
│       ├── Player/PlayerController.cs    ← 🐱 玩家操控（键盘+摇杆）
│       ├── NPC/CatNPC.cs                 ← 🐈 猫咪NPC（动画+交互）
│       ├── Map/MapBuilder.cs             ← 🗺️ 地图动态构建+水彩纹理
│       ├── UI/CatInfoPanel.cs            ← 📱 猫咪信息弹窗
│       ├── UI/CommunityPanel.cs          ← 💬 社区面板
│       └── Camera/CameraFollow.cs        ← 📷 相机跟随+缩放
│
├── 🐍 scripts/                           ← 数据工具链
│   ├── scraper.py                        ← 猫咪数据爬取 GUI 工具
│   ├── preprocess.js                     ← 照片→地图 预处理脚本
│   └── requirements.txt                  ← Python 依赖
│
├── 📊 data/                              ← 共用数据
│   ├── cats.json                         ← 猫咪档案（6只示例猫咪）
│   └── map-data.json                     ← 地图数据（8栋建筑+16棵树+10猫点）
│
└── 📱 (pages/ app.js ...)                ← 旧版微信小程序 Demo（保留参考）

🚀 快速开始

环境要求

软件	版本	用途
Unity Hub + Editor	2022.3 LTS	游戏开发
Python	3.9+	数据爬取
Node.js	16+	照片预处理（可选）
浏览器	Chrome / Edge	测试 WebGL 版本

1. 安装 Unity

1. 下载 Unity Hub: https://unity.com/download
2. Unity Hub → Installs → Install Editor
3. 选择 「Unity 2022.3 LTS」（⚠️ 不要选新版！）
4. 勾选 WebGL Build Support
5. 等待安装完成（约 3-5GB）

2. 创建 & 配置项目

1. Unity Hub → New Project → 2D Core → 命名 NanyangCatNotes
2. 将 unity-game/Assets/Scripts/ 全部复制到 Unity 项目的 Assets/ 中
3. 将 data/cats.json 和 data/map-data.json 放到 Assets/Resources/Data/
4. Package Manager 安装: com.unity.nuget.newtonsoft-json
5. 按照 SETUP_GUIDE.md 搭建场景
6. 点 ▶️ Play 运行！

📖 详细图文教程见：unity-game/SETUP_GUIDE.md

3. 爬取猫咪数据（可选）

1
2
3

cd scripts
pip install -r requirements.txt
python scraper.py --gui

4. 导出 WebGL

1 2	File → Build Settings → WebGL → Switch Platform → Build → 输出文件夹部署到任意静态服务器

🏗️ 架构设计

┌─────────────────────────────────────────────────────┐
│                   🌐 浏览器 (WebGL)                  │
├─────────────────────────────────────────────────────┤
│                   Unity Scene                        │
│                                                      │
│  ┌─────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ 🗺️ 地图 │  │ 🐱 玩家 │  │    📷 相机跟随   │  │
│  │ MapBldr │  │PlayerCtrl│  │   CameraFollow   │  │
│  └────┬────┘  └────┬─────┘  └────────┬─────────┘  │
│       │            │                 │             │
│       │      物理检测 (CircleCast)    │             │
│       └────────────┼─────────────────┘             │
│                    │                                │
│            ┌───────┴────────┐                      │
│            │   🐈 CatNPC    │                      │
│            │  待机动画+交互  │                      │
│            └───────┬────────┘                      │
│                    │                                │
│         ┌──────────┴──────────┐                    │
│         │                     │                    │
│  ┌──────┴──────┐    ┌────────┴─────────┐         │
│  │ CatInfoPanel│    │  CommunityPanel  │         │
│  │ 📱 猫咪档案 │    │  💬 社区         │         │
│  └─────────────┘    └──────────────────┘         │
│                                                      │
├─────────────────────────────────────────────────────┤
│              🔌 API 层（预留扩展）                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐   │
│  │ REST 社区│ │ WebSocket│ │ 🤖 AI Agent      │   │
│  └──────────┘ └──────────┘ └──────────────────┘   │
├─────────────────────────────────────────────────────┤
│              🛠️ 离线工具链                           │
│  ┌──────────────┐ ┌──────────────┐                 │
│  │ 🐍 Python爬虫│ │ 📷 照片处理 │                 │
│  └──────────────┘ └──────────────┘                 │
└─────────────────────────────────────────────────────┘

🤖 AI 智能体扩展规划

GameManager.cs 已预留两个 AI 接口，后续对接 LLM 即可：

// 1. 猫咪 AI 助手 - 与猫咪"对话"
string reply = await GameManager.Instance.QueryCatAI("cat_001", "今天心情怎么样？");
// → "喵~今天太阳很好，我在北大楼晒了好久！"

// 2. AI 路线推荐
var route = await GameManager.Instance.GetRecommendedRoute();
// → ["北大楼→大黄", "大礼堂→雪球", "食堂→小橘"]

🐈 示例猫咪数据

名字	花色	性别	绝育	常出没
大黄	橘白	♂	✅	北大楼台阶
雪球	纯白	♀	✅	大礼堂梧桐树
小橘	全橘	♂	❌	食堂后门
花花	三花	♀	✅	北大楼花坛
墨墨	纯黑	♂	✅	操场看台
奶茶	玳瑁	♀	❌	已收养 🏠

🎯 开发路线图

阶段	内容	状态
v0.1	微信小程序 Demo（Canvas 水彩地图）	✅
v0.2	迁移到 Unity + 完整 C# 脚本架构	✅
v0.3	Python 爬虫工具 + 照片预处理	✅
v0.4	场景搭建 + 美术资源 + 可运行版本	🔨
v0.5	社区系统后端 + 用户登录	📋
v1.0	AI 猫咪助手 + WebGL 发布	📋

👥 团队 & 致谢

🐱 猫咪数据来源：南雍猫札微信小程序（待授权）
🏫 校园参考：南京大学鼓楼校区 VR 全景 (vr.nju.edu.cn)
🎨 水彩风格：程序化纹理生成 + 多层叠加算法

🐾 Made with ❤️ for NJU cats — 每一只流浪猫，都值得被温柔记录。