# hackthon ai works

**Repository Path**: love2734/hackthon-ai-works

## Basic Information

- **Project Name**: hackthon ai works
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EasyOpenWorld

2D 像素风开放世界游戏（黑客松项目）。基于分形噪声程序化生成无限地形，支持 Chunk 懒加载、植物 / 动物 / 怪物实体、多阶段生长与格子碰撞。

游戏本体位于 [`first attempt/`](first%20attempt/) 目录，仓库其余部分是工具链与工程配置。

## 技术栈

- **渲染**：[PixiJS](https://pixijs.com/) v7.3.2，通过 CDN 引入（`index.html` 中唯一的外部依赖）
- **代码**：原生 JavaScript，classic `<script>` 顺序加载，**无构建、无 npm、无打包器**
- **运行环境**：任意现代浏览器 + 本地静态服务器（PowerShell 脚本已随仓库提供）

克隆下来即可运行，不需要 `install` 任何依赖。

## 目录结构

```
.
├── first attempt/            游戏本体
│   ├── index.html            页面、样式、脚本加载顺序
│   ├── server.ps1            本地开发服务器（http://localhost:8080/）
│   ├── character.jpg         角色素材源图（仅供烘焙使用，运行时不加载）
│   └── js/
│       ├── config.js         全部可调常量：瓦片尺寸、地形、噪声参数
│       ├── noise.js          分形噪声
│       ├── world.js          地形生成、Chunk 懒加载与清理、实体碰撞查询
│       ├── entities.js       实体类型配置与实体类
│       ├── entity-manager.js 实体生成、生长、AI 移动
│       ├── tile-renderer.js  瓦片图层渲染
│       ├── character-data.js 生成物 —— 烘焙图集 + 帧坐标，勿手改
│       ├── player.js         玩家：格子步进移动、朝向、精灵帧切换
│       └── main.js           入口、游戏循环、HUD、菜单交互
├── tools/                    角色精灵图离线烘焙工具链
│   ├── bake-server.ps1       烘焙专用服务器（提供 /save 回传落盘能力）
│   ├── bake-character.html   烘焙页：启动真实游戏 → 采集已生成纹理 → 合成图集
│   ├── check-baked.ps1       校验烘焙产物（alpha 谱、网格对齐、基线不变量）
│   ├── make-character-data.ps1  把 PNG + 帧清单转为 js/character-data.js
│   └── check-runtime.html    运行时回归断言（46 项）
├── .gitattributes            统一行尾为 LF，二进制类型显式声明
└── .gitignore
```

## 本地运行

```powershell
cd "first attempt"
powershell -File server.ps1
```

浏览器打开 <http://localhost:8080/>。

> `server.ps1` 第 5 行的 `$root` 是**硬编码绝对路径**。换机器或换目录后需要同步修改，否则全部请求 404。
> 也可以用任意其它静态服务器（`python -m http.server`、VS Code Live Server 等）指向 `first attempt/`。

直接双击 `index.html` 以 `file://` 打开也能跑（角色贴图已内嵌为 data-URI，不再受协议限制），但 `fetch`/模块加载相关能力受限，建议仍走本地服务器。

### 操作说明

| 按键 | 作用 |
| --- | --- |
| `W` `A` `S` `D` / 方向键 | 移动 |
| `R` | 用新随机种子重新生成世界 |
| 菜单种子输入框 | 留空则随机；填数字可复现同一个世界（`Enter` 也可开始） |

HUD 实时显示当前坐标、世界种子、脚下地形。

## 实现要点

**世界生成**：分形噪声（4 octaves，`persistence 0.5` / `lacunarity 2.0`）驱动高度场，叠加湿度场区分森林，映射为 7 种地形 —— 深水、浅水、沙滩、草地、森林、岩石、雪地。所有参数集中在 [`config.js`](first%20attempt/js/config.js)。

**Chunk 懒加载**：`16×16` 瓦片为一个 Chunk（瓦片 `16px`），只在玩家周围生成，超出 `CHUNK_CACHE_RADIUS`（默认 4）的 Chunk 由 `world.cleanup()` 回收。`generateChunk` 会先把自己存入 Map 再填内容，以打破 `邻接水域查询 → getTile → generateChunk` 的递归环。

**实体系统**：共 11 种类型，按 `PLANT` / `ANIMAL` / `MONSTER` 分类，各自声明允许生成的地形、生成概率、生长速率与多阶段外观。

- 植物：树、甘蔗、花（4 色随机变体）、仙人掌
- 动物：牛、鸡、鱼、猪（可自主游走）
- 怪物：僵尸、骷髅、史莱姆 —— `spawnChance = 0`，当前不预生成，为夜晚刷怪机制预留；僵尸与骷髅带 `burnsInDay` 白天自焚属性

`isSolid` 实体参与阻挡，玩家移动前经 `world.hasSolidEntityAt()` 判定。

**玩家渲染**：格子步进移动（单次 `150ms`），4 方向静止帧 + 3 方向 × 4 帧行走动画（源素材无"向上"行走帧），`anchor(0.5, 1)` 对齐脚底，靠 `zIndex` 排序实现 地形 < 实体 < 玩家 的层级。

## 角色精灵图：离线烘焙

`first attempt/js/character-data.js` 是**生成物**，内容为内嵌 base64 图集 + 帧坐标，请勿手工编辑。

素材换图后按以下四步重新生成（在仓库根目录执行）：

```powershell
# 1. 起烘焙服务器（默认 8081，被占用时加 -Port <n>）
powershell -File tools\bake-server.ps1

# 2. 浏览器打开 http://localhost:8081/bake.html
#    页面自动以固定种子启动真实游戏、采集运行时纹理、合成图集并回传
#    成功标志：日志输出 BAKE_OK，并出现放大预览图
#    产物落在 tools/out/（已 gitignore）

# 3. 校验烘焙产物
powershell -File tools\check-baked.ps1

# 4. 生成运行时 JS
powershell -File tools\make-character-data.ps1
```

`tools/out/` 不入库，若该目录已被清空，第 3、4 步会报「缺少烘焙产物」，需从第 1 步重跑。

第 2 步之所以走「启动真实游戏再读取已生成纹理」，而不是在烘焙脚本里复刻算法：这样能 1:1 保留运行时管线的既有像素结果（含半透明边缘与脚底基线），零偏差且不引入实现漂移。

回归验证：起服务后打开 <http://localhost:8081/check-runtime.html>，状态行显示 `CHECK_OK`（46 项断言）即为通过。

**体积现状**：首屏自有资源（HTML + 全部 JS）约 68 KB，PixiJS 走 CDN 约 138 KB，整包 10 个请求约 200 KB。

## Git 约定

**推送请使用 SSH**，HTTPS 因账号开启了 2FA 会被拒绝：

```bash
git clone git@gitee.com:love2734/hackthon-ai-works.git
```

首次配置需让 Git 走 Windows 自带的 OpenSSH，`ssh-agent` 才会生效：

```bash
git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"
```

**提交信息**：Conventional Commits 前缀 + 中文描述，正文按文件列出改动。示例见 `git log`：

```
perf: 角色精灵图改用离线烘焙图集，移除运行时像素管线
feat: 完善角色精灵图渲染与碰撞检测
chore: 添加 .gitattributes 统一行尾策略
```

**行尾**：`.gitattributes` 设 `* text=auto eol=lf`，仓库内统一 LF。PowerShell 脚本额外要求存成 **UTF-8 with BOM**，否则 PS 5.1 会按 ANSI 解析并拆坏中文。

**不入库**：`.gitignore` 已排除调试截图（`shot*.png`、`.verify-*.png`、`.bake-*.png`）与烘焙中间产物 `tools/out/`。