Tiaoom 竞技大厅游戏开发

为 Tiaoom 竞技大厅平台开发多人在线游戏的完整指南。

•平台：https://room.adventext.fun
•仓库：https://github.com/FishPiOffical/tiaoom
•技术栈：TypeScript、Node.js、Vue 3、WebSocket

快速开始

5 分钟了解 Tiaoom

什么是 Tiaoom？
Tiaoom 是一个开放的多人在线游戏平台，支持开发和发布各种游戏。

如何开发游戏？
创建两个文件：

•后端：backend/src/games/MyGame.ts - 游戏逻辑
•前端：frontend/src/components/games/MyGameRoom.vue - 游戏界面

准备开发环境（3 步）

bash

# 1. 克隆仓库
git clone https://github.com/FishPiOffical/tiaoom.git
cd tiaoom/game

# 2. 安装依赖
npm install

# 3. 启动开发服务
npm run dev

✅ 打开 http://localhost:5173 开始开发

架构概览

系统架构

code

┌─────────────────────────────────────────────┐
│      Tiaoom 竞技大厅平台                    │
├───────────────────────┬─────────────────────┤
│   🖥️ 后端服务器        │   🌐 前端应用       │
│  (Node.js)             │  (Vue 3)            │
├───────────────────────┼─────────────────────┤
│ • GameRoom 逻辑       │ • 游戏组件          │
│ • WebSocket 通信      │ • 状态管理          │
│ • 数据持久化          │ • UI/交互           │
│ • 倒计时管理          │ • 实时更新          │
│ • 积分系统            │ • 消息展示          │
└───────────────────────┴─────────────────────┘
          ↕ WebSocket（双向实时通信）

开发流程

code

需求分析 → 设计游戏规则 → 后端实现 → 前端实现 → 集成测试 → 优化部署

核心概念速查

概念	说明
GameRoom	游戏逻辑的基类，继承它来实现你的游戏
onStart()	游戏开始时调用，初始化游戏状态
onCommand()	接收玩家指令时调用，处理游戏逻辑
getStatus()	获取当前游戏状态，用于断线重连
command()	向所有玩家广播游戏指令
commandTo()	向指定玩家发送指令
Room	房间实例，代表一场游戏
RoomPlayer	房间内的玩家对象

学习路径

📚 路径 A：快速开发简单游戏

•查看 references/quick-start.md 中的 5 分钟示例
•参考 references/examples.md 中的完整示例代码
•本地测试并部署

📚 路径 B：深入学习架构

•阅读 references/architecture.md - 系统设计
•学习 references/backend-guide.md - 后端开发
•学习 references/frontend-guide.md - 前端开发
•研究 references/examples.md - 完整游戏实现

📚 路径 C：解决具体问题

•查看 references/troubleshooting.md - 常见问题
•查找相关 API 在 references/api-reference.md 中
•参考 references/best-practices.md 中的最佳实践

常用任务速查

🎮 我想创建第一个游戏

查看 references/examples.md 中的"完整示例：抢数字游戏"，这是一个完整的工作示例，包含：

•后端完整实现
•前端完整实现
•测试步骤

⏱️ 我想实现倒计时功能

参考 references/advanced-features.md 的"倒计时实现"部分，包括：

•后端倒计时启动和管理
•前端倒计时显示
•服务器重启后恢复

💾 我想实现游戏数据持久化

查看 references/advanced-features.md 的"游戏数据管理"部分：

•如何实现 IGameData 接口
•数据库模型定义
•CRUD 操作示例

🔄 我想实现游戏回放功能

参考 references/advanced-features.md 的"游戏回放"部分：

•后端回放数据记录
•前端回放组件实现
•数据存储和检索

🐛 游戏无法通信或状态混乱

查看 references/troubleshooting.md 中的：

•"WebSocket 连接失败"
•"前端无法接收后端消息"
•"断线重连时状态混乱"

⚡ 我想优化游戏性能

参考 references/best-practices.md 的"性能优化"部分：

•避免频繁的状态广播
•使用 commandTo 发送玩家特定数据
•合理使用 saveIgnoreProps

关键文件参考

📖 references/ 目录

•quick-start.md - 最小化示例和 3 步环境设置
•architecture.md - 系统架构、数据流、关键术语
•backend-guide.md - 后端开发规范、GameRoom API、实现指南
•frontend-guide.md - 前端结构、Vue 组件、预置组件
•advanced-features.md - 倒计时、数据管理、游戏回放
•examples.md - 完整的游戏示例代码（抢数字游戏）
•best-practices.md - 代码组织、性能优化、安全性
•troubleshooting.md - 常见问题和解决方案

最小化示例

后端最小实现

typescript

import { GameRoom, IGameCommand } from '.';

export const name = 'MinGame';
export const minSize = 2;
export const maxSize = 2;
export const description = 'Minimal game example';

export default class MinGameRoom extends GameRoom {
  gameState: any = {};

  onStart() {
    // 初始化游戏状态
    this.gameState = { count: 0 };
    this.command('init', this.gameState);
  }

  onCommand(message: IGameCommand) {
    super.onCommand(message);
    // 处理游戏逻辑
  }

  getStatus(sender: any) {
    return {
      ...super.getStatus(sender),
      gameState: this.gameState,
    };
  }
}

前端最小实现

vue

<template>
  <GameView :room-player="roomPlayer" :game="game" @command="onCommand">
    <div class="flex-1 flex flex-col items-center justify-center">
      <!-- 游戏显示 -->
    </div>
  </GameView>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { RoomPlayer, Room } from 'tiaoom/client';
import { GameCore } from '@/core/game';

const props = defineProps<{
  roomPlayer: RoomPlayer & { room: Room };
  game: GameCore;
}>();

const gameState = ref<any>(null);

function onCommand(msg: any) {
  if (msg.type === 'init' || msg.type === 'status') {
    gameState.value = msg.data.gameState;
  }
}
</script>

环境要求

项目	要求
Node.js	>= 20.x
npm	>= 9.x
编辑器	VS Code（推荐）
浏览器	Chrome/Firefox（需支持 WebSocket）

项目结构

code

tiaoom/game/
├── backend/
│   ├── src/games/
│   │   └── MyGame.ts              # 你的游戏逻辑
│   └── ...
├── frontend/
│   └── src/components/games/
│       ├── MyGameRoom.vue         # 游戏主组件
│       ├── MyGameLite.vue         # 小窗组件（可选）
│       └── MyGameReplay.vue       # 回放组件（可选）
└── skills/                         # 本 Skill 所在目录
    └── SKILL.md

获取帮助

📚 官方资源

•项目仓库：https://github.com/FishPiOffical/tiaoom
•在线体验：https://room.adventext.fun
•完整文档：https://github.com/FishPiOffical/tiaoom/tree/main/docs

🔍 查找信息

•对于快速答案：查看本文档的"常用任务速查"
•对于详细指南：阅读 references/ 中的相应模块
•对于完整代码：参考 references/examples.md
•对于问题排查：查看 references/troubleshooting.md

🤝 寻求支持

•提交 Issue：在 GitHub 上报告问题
•参与讨论：在 GitHub Discussions 中交流
•分享游戏：展示你的作品

下一步

•✅ 阅读本文档快速了解架构
•✅ 查看 references/quick-start.md 进行 3 步环境设置
•✅ 研究 references/examples.md 中的完整游戏示例
•✅ 根据学习路径选择深度方向
•✅ 开始开发你的第一个游戏！

立即开始开发你的 Tiaoom 游戏吧！ 🚀