# NeoForgeCityGame

**Repository Path**: codekpy/neo-forge-city-game

## Basic Information

- **Project Name**: NeoForgeCityGame
- **Description**: 使用Java开发，基于NeoForge+MC1.21.1版本的星梦小镇游戏
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java

## README

# City Game（星梦の町）— NeoForge 模组

将 Box3JS 城市玩法（city-game）移植到 Minecraft 1.21 / NeoForge 的模组，包含经济、战斗、交通、射击与休闲玩法。

## 环境要求

- Minecraft **1.21**
- NeoForge **21.0.167**
- Java **21**
- 使用 Mojang 官方映射（Mojang mappings）

## 构建

```bash
./gradlew build
```

产物位于 `build/libs/citygame-1.0.3.jar`，放入 `mods` 目录即可。

## 玩法功能

### 经济系统
- **星梦币**：击杀怪物/鸭子、打靶、空投、签到等途径获取
- **玩家交易**：`/give <玩家名> <金额>` 转账，右键玩家查看对方资料
- **PvP 掉落**：击杀玩家获得对方 0~1/3 金币，通缉值机制
- **死亡保护**：玩家死亡保留背包物品（keepInventory 开启），仅 PvP 按比例转移星梦币
- **新手保护**：新玩家首次进服后 5 分钟内不受任何伤害，到期自动提示结束
- **每日签到**：`/checkin` 连续 7 天领奖（20~220 星梦币）

### 武器与战斗
- **弓**（8 发弹匣，伤害 10）/ **弩**（烟花火箭范围爆炸，伤害 150），商店购买解锁
- 弹药系统：射击扣弹，弹匣耗尽自动消耗背包箭矢换弹，无弹药自动扣款购买
- 武器切换：手持弓/弩自动识别当前武器（需已解锁）
- 攻击玩家增加通缉值（对方无通缉时 +2）
- 通缉值每 30 秒自动减 1 点（最低 0，仅在线递减）
- **打怪奖励**：击杀站点刷新怪物获得星梦币（僵尸 2★ / 骷髅 3★），同时降低 3 点通缉值，并计入全服击杀榜

### 世界玩法
- **商店**：弓、弩、箭矢、烟花火箭、铁毡、原木、钻石防具、食物（面包/熟鸡肉/熟牛肉/金苹果，商店 NPC 右键打开）
- **收购商**：鸡蛋/铁锭/羽毛/腐肉/骨头/生鸡肉/生鳕鱼/河豚动态回收换星梦币，回收价随 3 分钟内卖出量波动（卖出越多越低，下限 50%），与商店铁锭售价联动
- **合成**：工具商 NPC 自定义合成菜单，制作石剑/铁剑/盾牌/铁质防具/箭×8
- **附魔**：附魔师 NPC 消耗经验等级为主手剑附魔（锋利/耐久）
- **地铁**：站牌右键传送，3 星梦币/次（市中心 ⇄ 花园广场站 ⇄ 住宅区站）
- **交通**：出租马（0.05★/秒）/ 出租驴（0.025★/秒），按骑行时间计费，欠费转通缉值
- **直升机**：`/tpto` 按距离计费传送
- **打靶中心**：3 星梦币/发，3 发结算，平均环数 ×1.5 奖励
- **猎鸡（打鸭子）**：湖面生成猎鸡（原生 AI 陆地自由游荡），击杀得 0~4 星梦币，30 秒后湖面随机位置重生；湖中同步维持 ≤20 条鱼自动刷新
- **空投**：每 2 分钟投放补给掉落物（弓/箭矢/金胡萝卜/木棍/石头或铁锭/熟牛肉），首次拾取随机 20~150 星梦币，5 分钟无人拾取自动清除；启动时自动清理旧版空投箱子
- **奖励盒**：每 2 分钟随机生成装有物资的潜影盒掉落物，奖励按原版四类概率随机（回血→金苹果+熟牛肉 / 星梦币→铁锭+金锭 / 弹药→箭矢+木棍 / 武器→弓+箭矢），放置打开取物，5 分钟未拾取自动清除；生成位置不全服通报
- **地面掉落**：每 1 分钟随机掉落原木/箭矢/铁锭，3 分钟消失
- **怪物刷新**：全图僵尸/骷髅恒定 20 只（每 10 秒检测：超过即移除多余，不足即在市中心/站点附近补充，不生成苦力怕）
- **流浪商人**：市中心生成 2 个自由移动、无敌的流浪商人 NPC，右键打开自定义商店菜单，超出城区自动传回市中心
- **木桩挑战**：进入挑战区获得 20 星梦币并传送
- **时间固定**：游戏时间固定为夜晚（午夜），禁用昼夜循环，不日夜流转
- **彩蛋**：神秘人 NPC 交互随机解锁 B 站个人空间 / Gitee 链接

### 排行与存档
- **排行榜**：`/rank` 全服打怪击杀榜、`/warrank` 全服通缉值榜（SavedData 持久化，实时记录）
- **备份**：`/citygamebackup list|restore` 管理员查看/恢复存档备份，支持自动定时备份与手动触发

### NPC 一览
| NPC | 位置 | 说明 |
|---|---|---|
| 新手向导 | (135, -50, 105) | 游戏引导，无敌 + 自动回血 |
| 商店助手 | (107, -50, 93) | 商店购买武器弹药，无敌 + 自动回血 |
| 流浪商人·甲/乙 | (108, -50, 93) / (106, -50, 93) | 自由移动无敌商店 NPC，右键打开商店菜单，超出城区自动传送回市中心 |
| 收购商 | (104, -50, 93) | 鸡蛋/铁锭/羽毛/腐肉/骨头动态回收换星梦币 |
| 工具商 | (105, -50, 93) | 自定义合成石剑/铁剑/盾牌/铁质防具 |
| 附魔师 | (218, -51, 164) | 消耗经验附魔（锋利/耐久） |
| 神秘人 | (76, -59, 77) | 随机彩蛋链接（B站/Gitee） |

### 界面
- **HUD**：血量 / 星梦币 / 通缉值 / 武器弹药（含背包箭矢数），每 5 秒服务端推送同步
- **主菜单**：`/menu` 可点击菜单（个人信息/存档/呼叫直升机/切换视角）

## 命令一览

| 命令 | 说明 |
|---|---|
| `/menu` | 打开主菜单 |
| `/help` | 查看游戏帮助与常用指令 |
| `/checkin` | 每日签到 |
| `/give <玩家> <金额>` | 转账星梦币 |
| `/tpto [目的地]` | 直升机传送 |
| `/map` | 获得城市地图 |
| `/rank` | 全服打怪击杀榜前十 |
| `/warrank` | 全服通缉值榜前十 |
| `/citygamebackup list/restore` | 存档备份管理（管理员） |
| `/save` | 手动存档（数据自动保存） |
| `/view` | 切换第一/第三人称视角 |

> **命令限制**：非 OP 玩家仅可执行上表游戏命令（`citygamebackup` 为管理员专用）及 DirectAuth 认证命令（`/register` `/login` `/online`），其余原版命令（`gamemode`/`tp`/`execute` 等）一律禁用并从 Tab 补全隐藏；OP（权限≥2）与服务器控制台不受限。

## 项目结构状态

### 源码结构

```
src/main/java/com/starbit/citygame/
├── CityGameMod.java              # 主类：Attachment/菜单类型注册（根包）
├── ModEvents.java                # 玩家登录/死亡/PvP 核心事件（根包）
├── entity/                       # 实体控制
│   ├── TutorialNPC.java          # 新手引导 NPC
│   ├── ShopVillager.java         # 商店 NPC
│   ├── MarketNpc.java            # 收购商 NPC（动态回收）
│   ├── ToolNpc.java              # 工具商 NPC
│   ├── EnchantNpc.java           # 附魔师 NPC
│   ├── EasterEggs.java           # 彩蛋 NPC（神秘人）
│   ├── DuckHunting.java          # 猎鸡（打鸭子）+ 湖中鱼
│   ├── TransportHorse.java       # 出租马/驴
│   ├── MobSpawnManager.java      # 市中心/站点怪物刷新
│   ├── CombatHandler.java        # 弓/弩战斗与弹药系统
│   ├── WeaponSwitchHandler.java  # 武器切换识别
│   ├── WanderingTraderShop.java  # 流浪商人系统
│   └── MobKillHandler.java       # 打怪奖励 + 击杀榜记录
├── entity/ai/                    # 实体 AI 目标
│   └── NearestHighWantedTargetGoal.java # 怪物优先追捕高通缉玩家
├── mixin/                        # Mixin 修改
│   └── MixinServerPlayer.java    # 禁止打开租赁马/驴背包界面
├── menu/                         # 菜单容器
│   ├── ShopMenu.java             # 商店菜单容器
│   ├── MarketMenu.java           # 收购商出售菜单
│   ├── CraftingMenu.java         # 工具商合成菜单
│   ├── EnchantMenu.java          # 附魔菜单
│   ├── ReadOnlySlot.java         # 菜单只读槽定义
│   └── ShopItemInfo.java         # 商品信息定义
├── data/                         # 数据管理
│   ├── PlayerData.java           # 玩家数据模型（Attachment 持久化）
│   ├── PlayerDataEvents.java     # 玩家数据事件
│   ├── PlayerDataNetwork/SyncHandler/Payload # HUD 数据同步网络
│   ├── KillRankData.java         # 全服击杀榜数据
│   ├── WarRankData.java          # 全服通缉值榜数据
│   ├── DataBackupManager.java    # 存档备份
│   └── Config.java               # 模组配置
├── command/                      # 命令
│   ├── MenuCommands.java         # 主菜单 /menu
│   ├── HelpCommand.java          # 帮助 /help
│   ├── DailyCheckIn.java         # 每日签到 /checkin
│   ├── PlayerTradeHandler.java   # 转账 /give
│   ├── RankingCommands.java      # 排行榜 /rank /warrank
│   ├── CityMapCommand.java       # 城市地图 /map
│   ├── TransportTeleport.java    # 直升机传送 /tpto
│   ├── CommandRestrictions.java  # 命令白名单限制
│   └── BackupCommands.java       # 备份管理 /citygamebackup
├── world/                        # 世界玩法
│   ├── MarketManager.java        # 市场动态价格系统
│   ├── ShootingCenter.java       # 打靶中心
│   ├── SubwaySystem.java         # 地铁传送
│   ├── SupplyDrop.java           # 空投补给（掉落物）
│   ├── RewardBoxHandler.java     # 奖励盒（潜影盒掉落物，不广播位置）
│   ├── GroundLootHandler.java    # 地面掉落
│   ├── WoodenStakeChallenge.java # 木桩挑战
│   ├── WeatherManager.java       # 时间固定夜晚（禁用昼夜循环）
│   ├── WaterBodyScanner.java     # 连通水域 BFS 扫描工具
│   └── BankHandler.java          # 银行（占位，抢银行玩法待实现）
└── client/                       # 客户端界面
    ├── CoinHUDOverlay.java       # HUD 渲染
    ├── ShopScreen/CraftingScreen/EnchantScreen/MarketScreen # 菜单客户端界面
    └── ClientDataCache.java      # 客户端数据缓存
```

### 功能状态
- **已完成**：新手引导 NPC、商店、合成、附魔、打靶中心、猎鸡、木桩挑战、武器系统、地铁、传送、出租马/驴、每日签到、空投、奖励盒、地面掉落、怪物刷新、流浪商人、PvP、天气时间、打怪奖励、排行榜、备份、彩蛋、城市地图
- **待实现**：银行（抢银行玩法）

## 技术说明

- 玩家数据使用 NeoForge **Data Attachment**（Codec 序列化）持久化，登出/关服自动写盘，重进恢复
- 客户端 HUD 数据通过自定义网络包（`PlayerDataSyncPayload`）每 5 秒推送，服务端为唯一数据源
- 排行榜与通缉值榜使用 `SavedData` 持久化，服务器重启不丢失