UrhoX CLI

用于发布游戏到 UrhoX UGC 平台的命令行工具

✨ 功能特性

• 📦 一键打包游戏资源（Lua 脚本 + 封面图）
• 🚀 快速上传到 UrhoX 平台
• ✅ 自动验证配置和文件
• 🔍 智能检测 Lua 入口文件（包含 Start() 函数）
• 🎯 支持多层级目录结构
• 🛡️ 文件哈希去重，避免重复上传
• 🌐 支持自定义服务器地址

📦 安装

全局安装（推荐）

npm install -g urhox-cli

验证安装

urhox --version

🚀 快速开始

1. 初始化配置文件

在你的游戏项目目录中运行：

urhox init

这会创建一个 urhox.json 配置文件模板。

2. 编辑配置文件

打开 urhox.json，填写你的游戏信息：

{
  "name": "我的游戏",
  "author_id": "your_username",
  "description": "这是一个很酷的游戏",
  "version": "1.0.0",
  "engine_version": "0.1.0",
  "scripts": "./Scripts",
  "cover": "./cover.png",
  "tags": ["action", "multiplayer"]
}

3. 发布游戏

urhox publish

📖 命令说明

urhox init

初始化配置文件，创建 urhox.json 模板。

urhox init

urhox validate

验证配置和文件完整性（预演模式，不上传）。

urhox validate

会检查：

• 配置文件格式是否正确
• 必填字段是否完整
• 封面图和脚本目录是否存在
• Lua 文件是否存在
• 是否能检测到入口文件

urhox publish

打包并上传游戏到平台。

# 正常发布
urhox publish

# 模拟运行（不实际上传）
urhox publish --dry-run

# 更新已存在的游戏
urhox publish --update <gameId>

选项：

• --dry-run: 模拟运行，不实际上传
• --update <gameId>: 更新已存在的游戏

⚙️ 配置文件

urhox.json 配置文件格式：

{
  "name": "游戏名称",              // 必填：游戏名称
  "author_id": "作者ID",           // 必填：作者标识（3-20个字符，仅字母数字下划线连字符）
  "description": "游戏描述",       // 可选：游戏简介
  "version": "1.0.0",             // 必填：版本号（格式：x.y.z）
  "engine_version": "0.1.0",      // 可选：引擎版本
  "scripts": "./Scripts",         // 必填：Lua 脚本目录路径
  "cover": "./cover.png",         // 必填：封面图路径（支持 PNG/JPG）
  "tags": ["action", "rpg"]       // 可选：游戏标签
}

字段说明

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | name | String | ✅ | 游戏名称 | | author_id | String | ✅ | 作者标识（3-20个字符，仅字母数字下划线连字符） | | description | String | ❌ | 游戏描述 | | version | String | ✅ | 版本号（格式：x.y.z，如 1.0.0） | | engine_version | String | ❌ | 引擎版本（默认：0.1.0） | | scripts | String | ✅ | Lua 脚本目录路径（相对或绝对路径） | | cover | String | ✅ | 封面图路径（PNG/JPG 格式） | | tags | Array | ❌ | 游戏标签数组 |

📁 项目结构示例

my-game/
├── urhox.json           # 配置文件
├── cover.png            # 封面图
└── Scripts/             # Lua 脚本目录
    ├── Main.lua         # 入口文件（包含 Start() 函数）
    ├── Player.lua
    └── Utils/
        └── Helper.lua

🎯 Lua 入口文件检测

CLI 会自动扫描所有 .lua 文件，查找包含 Start() 函数的入口文件：

-- Main.lua（会被识别为入口文件）
function Start()
    print("Game started!")
end

function Update(dt)
    -- 游戏逻辑
end

规则：

• ✅ 自动检测包含 function Start() 或 function Start ( 的文件
• ⚠️ 如果检测到多个入口文件会报错
• ⚠️ 如果未检测到入口文件会警告（使用第一个 Lua 文件作为入口）

🌐 自定义服务器地址

通过环境变量设置服务器地址：

# Linux/Mac
export URHOX_API_URL=https://your-server.com
urhox publish

# Windows PowerShell
$env:URHOX_API_URL="https://your-server.com"
urhox publish

# 或者临时设置
URHOX_API_URL=https://your-server.com urhox publish

默认地址： https://test-urhox.spark.xd.com/lishu/test

📝 完整示例

# 1. 创建游戏项目
mkdir my-awesome-game
cd my-awesome-game

# 2. 初始化配置
urhox init

# 3. 编辑 urhox.json
# {
#   "name": "My Awesome Game",
#   "author_id": "john_doe",
#   "description": "An epic adventure game",
#   "version": "1.0.0",
#   "scripts": "./Scripts",
#   "cover": "./cover.png",
#   "tags": ["adventure", "action"]
# }

# 4. 准备游戏文件
mkdir Scripts
echo 'function Start() print("Hello!") end' > Scripts/Main.lua
# 添加封面图 cover.png

# 5. 验证配置
urhox validate

# 6. 发布游戏
urhox publish

🎮 发布成功后

发布成功后会显示：

✓ 游戏发布成功！

游戏信息:
  游戏 ID: game-abc123def456
  游戏链接: https://test-urhox.spark.xd.com/lishu/test/games/game-abc123def456
  CDN 地址: https://cdn.example.com/games/game-abc123def456.zip

分享你的游戏:
  https://test-urhox.spark.xd.com/lishu/test/games/game-abc123def456

❓ 常见问题

Q: 为什么上传失败？

A: 检查以下几点：

1. 服务器是否可访问
2. URHOX_API_URL 环境变量是否正确
3. 网络连接是否正常
4. 配置文件是否正确

Q: 如何更新已发布的游戏？

A: 使用 --update 参数：

urhox publish --update game-abc123def456

Q: 支持哪些图片格式作为封面？

A: 支持 PNG 和 JPG 格式。

Q: Lua 脚本目录可以有多层级吗？

A: 可以！CLI 会递归扫描所有子目录中的 .lua 文件，并保持目录结构。

Q: 如何查看打包内容？

A: 使用 --dry-run 模式：

urhox publish --dry-run

📋 系统要求

• Node.js >= 18.0.0
• npm >= 9.0.0

🔗 相关链接

• npm 包主页
• GitHub 仓库
• UrhoX 平台文档

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Made with ❤️ by Lishu