# @freegamestore/games 中文文档

规范地址：https://npmcn.com/package/%40freegamestore/games/

版本：0\.20\.3
npm 元数据更新时间：2026-11-07T05:42:33.689Z
中文译文更新时间：2026-11-15T14:39:41.252Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40freegamestore/games
原文对照：https://npmcn.com/package/%40freegamestore/games/?lang=original
项目主页：https://github.com/freegamestore-online/platform#readme
源码仓库：https://github.com/freegamestore-online/platform

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：210 kB，129 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：react ^19\.0\.0
- 首次发布：2026-05-08T00:38:33.596Z
- 最新版本发布：2026-11-07T05:42:33.373Z
- 近 30 天下载量：2495（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

在FreeGameStore上——GameShell,GameTopbar等游戏的共享回放UI原始作. Brand-Consistent,卷轴自由.

## 安装

```sh
npm install @freegamestore/games
```

也可以使用：`pnpm add @freegamestore/games`、`yarn add @freegamestore/games`、`bun add @freegamestore/games`

## README

# @ freegamestore/ games (英语)

游戏的共享回放( UI) 原始 **freegamestore.online 互联网档案馆的存檔,存档日期2013-12-02**. 品牌一致布局,卷轴自由取景口锁,触控方便,并合成音效.

**版本 :** 0.19.0 (中文(简体) )

## 安装

```bash
npm i @freegamestore/games
# or
pnpm add @freegamestore/games
```

对等依赖:反应19+.

## Styling (代号为Tailwind 4)

组件的样式为 **平台上的有轨电车** (单位:千美元)[ADR-001 (中文(简体) )](https://github.com/freegamestore-online/platform/blob/main/docs/adr/001-tailwind-on-fgs-tokens.md)) (中文(简体) ). 包船的船级名称,不是CSS,所以 **您的游戏汇编它们**在 游戏 `web/src/index.css`,直接在 `@import "tailwindcss"`数字 :

```css
@import "tailwindcss";
@import "@freegamestore/games/theme.css";
@source "../node_modules/@freegamestore/games/dist";

@theme inline {
  --color-paper: var(--paper);
  --color-panel: var(--panel);
  --color-ink: var(--ink);
  --color-muted: var(--muted);
  --color-line: var(--line);
  --color-accent: var(--accent);
  --color-danger: var(--danger);
  --font-display: "Fraunces", serif;
}
```

-   `@source` 让Tailwind扫描这个软件包 `dist` 课程 组件使用。 没有它,SDK就变得不俗了.
-   `theme.css` 添加符号映射以外的组件: `animate-fgs-*` 动画及其键框(它取代 CSS 用于注入的部件, `accent-ink`, (中文(简体) ), `accent-soft` 编辑 `fgs` 半径 和文本大小。 期限和放宽改为: `--motion-*` 标志.
-   这个 `@theme inline` 块是符号映射 `template-game-*` 携带. 模板上的游戏已经拥有了它.
-   浮动 UI (Y)`GameModal`, (中文(简体) ), `GameConfirm`, (中文(简体) ), `StartScreen`, (中文(简体) ), `GameResultScreen`(中文(简体) ) 坐在不透明地上 `bg-panel` 表面。 只有它的后方是半透明的.
-   没有在运行时注射。 这个 `*_CSS` 字符串( r)`CONFETTI_CSS`, (中文(简体) ), `SCORE_POP_CSS`, (中文(简体) ), `RESULT_SCREEN_CSS`, (中文(简体) ), `START_SCREEN_CSS`以0.19.0去除; `GAME_TOKENS_CSS` 继续作为文件符号帮助者.
-   内入 `style` 仅保留运行时计算的值( 配置件) 位置、分数弹出坐标、交错指数,每个标记 `// Dynamic: …`。 。 。 . `src/styling.test.ts` 别的都失败了.
-   测试和超载的钩子 `data-fgs="…"` 属性 (单位:千美元)`result`, (中文(简体) ), `confetti`, (中文(简体) ), `start`, (中文(简体) ), `start-artwork`, (中文(简体) ), `score-popup`) (中文(简体) ). 旧的 `fgs-*` 类名已去.

## 快速启动

```tsx
import { GameShell, GameTopbar } from '@freegamestore/games'

export default function App() {
  return (
    <GameShell topbar={<GameTopbar title="Chess" />}>
      {/* your game canvas / DOM */}
    </GameShell>
  )
}
```

## 构成部分

### 游戏壳

根布局包装. 锁定游戏到 `100svh`,防止文档滚动,禁用文本选择和触摸点名。 每款游戏都以此来包装其内容.

```tsx
<GameShell topbar={<GameTopbar title="Tetris" />}>
  <MyGame />
</GameShell>
```

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `topbar` | `ReactNode?` | 顶条元素( 通常为 `<GameTopbar />`(中文(简体) ) |
| `children` | `ReactNode` | 游戏内容 — 填充剩余取景口 |

### 游戏Topbar

单曲允许上栏. 每场比赛都有相同的字体,平板字和彩色符号.

```tsx
// Simple: just the title. The score pill is hidden by default (#348)
<GameTopbar title="Tetris" />

// Opt in to the live score pill
<GameTopbar title="Tetris" score={42} showScore />

// Custom stats + play/pause controls
<GameTopbar
  title="Pac-Man"
  stats={[
    { label: 'Score', value: 1200, accent: true },
    { label: 'Lives', value: 3 },
    { label: 'Level', value: 5 },
  ]}
  rules={<p>Eat all the dots. Avoid ghosts.</p>}
  onPlayPause={togglePause}
  paused={isPaused}
  onRestart={restart}
/>
```

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `title` | `string?` | 游戏名称, 左侧 |
| `score` | `number?` | 活得分,只显示于 `showScore` 设定 |
| `showScore` | `boolean?` | 出活计分丸. 默认关闭 (# 348) |
| `stats` | `GameTopbarStat[]?` | 自定义 stat 排行( 活、 关、 时间) |
| `actions` | `ReactNode?` | 右侧按钮( 最大 2) |
| `rules` | `ReactNode?` | 游戏指令 — 显示信息图标, 打开水龙头上的覆盖 |
| `onPlayPause` | `() => void?` | 播放/暂停图标按钮 |
| `paused` | `boolean?` | 控制播放/暂停图标状态 |
| `onRestart` | `() => void?` | 启动图标按钮 |

### 游戏认证

上边栏的签名/ 相机部件 `actions` 插槽 。 签出时显示"签入",签入时显示"avatar"+降入.

```tsx
<GameTopbar title="Chess" actions={<GameAuth />} />
```

无道具——使用 `useAuth` 内部.

### 游戏按钮

触摸友好按钮. min 44px触控目标. 四变相 三相相相相.

```tsx
<GameButton variant="primary" size="lg" onClick={start}>Play Again</GameButton>
<GameButton variant="secondary" size="sm" onClick={undo}>Undo</GameButton>
<GameButton variant="ghost" size="sm" onClick={flip}>Flip</GameButton>
<GameButton variant="danger" onClick={quit}>Quit</GameButton>
```

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `children` | `ReactNode` | (必须) | 按钮内容 |
| `variant` | `'primary' | 'secondary' | 'ghost' | 'danger'` | `'primary'` | 视觉风格 |
| `size` | `'sm' | 'md' | 'lg'` | `'md'` | 触摸目标大小 |
| `onClick` | `() => void?` |  | 点击处理器 |
| `disabled` | `boolean?` | `false` | 状态 |
| `block` | `boolean?` | `false` | 全宽 |

大小 : `sm` (44个px), `md` (48个px), `lg` (56px) (英语).

### 游戏Modal

全屏模式覆盖. 关闭背景点击或退出 .

```tsx
<GameModal open={showSettings} onClose={() => setShowSettings(false)} title="Settings">
  <p>Game settings here</p>
</GameModal>
```

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `open` | `boolean` | 模式是否可见 |
| `onClose` | `() => void` | 用背景点击或逃逸调用 |
| `title` | `string?` | 页眉文本 |
| `children` | `ReactNode` | 模块内容 |

### 游戏覆盖屏幕

标准游戏覆接有分数,高分,再按下按钮.

```tsx
<GameOverScreen
  score={1200}
  highScore={1500}
  onPlayAgain={restart}
>
  <Leaderboard {...leaderboard} />
</GameOverScreen>
```

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `score` | `number` | 最后分数 |
| `highScore` | `number?` | 个人最佳(出道"新高分!"被打出后出道) |
| `onPlayAgain` | `() => void` | 再次播放处理器 |
| `children` | `ReactNode?` | 分数以下的额外内容 |

### 游戏ResultScreen

完成关卡或游戏的动画结果屏幕. 一个胜利显示 倒下孔雀和口音标题。 丢失的卡片是单独显示的. 屏幕打开时动作会集中. 使用 `GameOverScreen` 一个简单的游戏过卡. `GameResultScreen` 是动画版.

```tsx
<GameResultScreen
  tone={won ? 'win' : 'lose'}
  eyebrow="Level 4"
  title={won ? 'Level 4 cleared!' : 'Game over'}
  message={won ? undefined : 'Your tray filled up.'}
  stats={[
    { label: 'Score', value: score.toLocaleString() },
    { label: 'Moves', value: moves },
  ]}
  badge={newBest ? 'New best!' : undefined}
  action={won ? { label: 'Next level', onClick: next } : { label: 'Play again', onClick: restart }}
>
  <Leaderboard {...leaderboard} />
</GameResultScreen>
```

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `tone` | `'win' | 'lose'` | `win` 显示配置和重音标题颜色 |
| `eyebrow` | `string?` | 标题上方的小行, 如级别名称 |
| `title` | `string` | 标题 |
| `message` | `string?` | 标题下的一行 |
| `stats` | `{ label, value }[]?` | 相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. `value` 可能是一个数字 |
| `badge` | `ReactNode?` | 突出统计下行,如"新好 |
| `action` | `{ label, onClick }` | 主按键. 当屏幕打开时它会被聚焦 |
| `children` | `ReactNode?` | 徽章和动作之间的额外内容 |

屏幕覆盖了视门 并且有 `role="dialog"`运动是 `animate-fgs-*` 水电费 `theme.css` (见 [样式](https://npmcn.com/package/%40freegamestore/games/#readme-styling-tailwind-4-on-tokens), (中文(简体) ), 关闭 `prefers-reduced-motion`中, 并隐藏给玩家 谁要求少一点运动。 它的颜色来自平台标志 和它的 持续时间 `--motion-*` 符号在 [国家](https://npmcn.com/package/%40freegamestore/games/TOKENS.md),与 光主题倒计时 `theme.css`。 。 。 .

`Confetti` 用于要庆祝的游戏 在别的地方.

### 游戏确认

在 GameModal 上创建的确认/取消对话框 .

```tsx
<GameConfirm
  open={showQuit}
  title="Quit Game?"
  message="Your progress will be lost."
  onConfirm={quit}
  onCancel={() => setShowQuit(false)}
  variant="danger"
/>
```

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `open` | `boolean` |  | 是否可见 |
| `title` | `string` |  | 对话框标题 |
| `message` | `string` |  | 文本正文 |
| `onConfirm` | `() => void` |  | 确认处理器 |
| `onCancel` | `() => void` |  | 取消处理器 |
| `confirmLabel` | `string?` | `'Confirm'` | 确认按钮文本 |
| `cancelLabel` | `string?` | `'Cancel'` | 取消按钮文本 |
| `variant` | `'default' | 'danger'` | `'default'` | 确认按钮样式 |

### 游戏主题切换

压缩日月主题切换 (28px). 循环系统/轻/暗. 为上行所设计 `actions` 插槽 .

```tsx
<GameTopbar title="Chess" actions={<><GameThemeToggle /><GameTextSizeToggle /></>} />
```

没有道具.

### 游戏文本化切换

压缩文本大小切换 (28px). 周期默认/ 大/ 小 。 显示 A/A+/A-。 为上行所设计 `actions` 插槽 .

```tsx
<GameTopbar title="Chess" actions={<GameTextSizeToggle />} />
```

没有道具.

### 领导板

标签页板显示 (Top / 最近) 。 与 `useLeaderboard` 钩.

```tsx
const { topScores, recentScores, loading } = useLeaderboard('chess')

<Leaderboard topScores={topScores} recentScores={recentScores} loading={loading} />
```

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `topScores` | `LeaderboardEntry[]` | 有史以来最高分数 |
| `recentScores` | `LeaderboardEntry[]` | 最近得分 |
| `loading` | `boolean` | 装入状态 |

## 钩子

### 用户

FreeGameStore (通过 Google OAuth) 的认证状态 `auth.freegamestore.online`) (中文(简体) ).

```tsx
const { user, loading, signIn, signOut } = useAuth()
```

回返 `{ user: User | null, loading: boolean, signIn: () => void, signOut: () => void }`。 。 。 .

### 使用引导板

获取并提交分数到平台领导板.

> **今天没有领导板服务.** 领导板工人被移除(# 491),所以领导板总是空的 `submitScore` 决定 `{ ok: false }`钩子和 `<Leaderboard>` 继续导出, 因此已有的游戏会继续构建; 在本地保存高分 `localStorage`。 。 。 .

```tsx
const { topScores, recentScores, submitScore, loading, refresh } = useLeaderboard('tetris')

// Submit a score
const { ok, rank } = await submitScore(1200)
```

过 `period` (协调世界时的一天, `YYYY-MM-DD`),用于每天的棋盘,例如每日的谜题. 接受它为全局董事会:

```tsx
const today = new Date().toISOString().slice(0, 10)
const { topScores, submitScore } = useLeaderboard('tile-match', { period: today })
```

### 使用GameSunds 软件

通过Web Audio API合成音效. 0音频文件. 所有的声音自动尊重哑巴切换.

```tsx
const { playMove, playScore, playError, playGameOver, playLevelUp, playDrop, playClear, playTick } = useGameSounds()

// Play a sound (no-op when muted)
playScore()
```

| 声音 | 使用大小写 |
| --- | --- |
| `playMove` | 片段被移动,卡片被翻转,按下按钮 |
| `playScore` | 得分,匹配,正确的答案 |
| `playError` | 答错了,撞了障碍,失去了生命 |
| `playGameOver` | 游戏结束——倒数 |
| `playLevelUp` | 升级/成绩——升级 |
| `playDrop` | 硬投出/ th |
| `playClear` | 清行/ 组合 |
| `playTick` | 倒计时勾选/ 计时警告 |

### 声音

SDK的"音效提供"中的低等哑弹状态. 游戏应该检查 `muted` 在播放自定义音频之前.

```tsx
const { muted, toggle } = useSound()
if (!muted) myCustomAudio.play()
```

## 出口

```
@freegamestore/games → GameShell, GameTopbar, GameAuth, GameButton, GameModal,
                        GameOverScreen, GameConfirm, GameThemeToggle,
                        GameTextSizeToggle, Leaderboard, useAuth, useLeaderboard,
                        useGameSounds, useSound
```

## 许可证

麻省理工学院

## 常见问题

### @freegamestore/games 是什么？

在FreeGameStore上——GameShell,GameTopbar等游戏的共享回放UI原始作\. Brand-Consistent,卷轴自由\.

### 如何安装 @freegamestore/games？

在项目目录运行 npm install @freegamestore/games，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @freegamestore/games 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @freegamestore/games 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @freegamestore/games 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @freegamestore/games 可以商用吗？

@freegamestore/games 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @freegamestore/games 的下载量有多少？

根据 npm 官方下载统计，@freegamestore/games 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,495 次，日均约 83 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @freegamestore/games 还在维护吗？

最新版本 0\.20\.3 发布于 2026/11/07（8 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/05/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。