# word-pk

**Repository Path**: chenjunming116/word-pk

## Basic Information

- **Project Name**: word-pk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-03
- **Last Updated**: 2026-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Word PK 🎮

**A free pixel-art English word battle game — battle friends in real-time word duels.**

🌐 **Play now**: [wordbattle.top](https://wordbattle.top) — no download, no signup, works in your browser.

---

## What is Word PK?

Word PK turns English vocabulary learning into a real-time PvP battle game. Answer faster than your opponent to win — learn English through gaming instead of boring flashcards.

## Features

- ⚔️ **1v1 & 8-player battles** — real-time multiplayer word duels
- 🔁 **Synonym & Antonym mode** — pick synonyms/antonyms (reading + listening)
- 🎯 **6+ game modes** — English definitions, listening, synonyms/antonyms, picture, sentence fill, word chain
- 🏮 **240+ word packs / 818,000+ words** — Pokémon, Naruto, Marvel, Harry Potter, NBA, Chinese culture, exam vocab, A-Z English definitions
- 📱 **Zero friction** — works on phone & desktop, no download, no signup
- 👾 **Pixel-art visuals** — Minecraft-style

## Screenshots

![Home](screenshots/home.png)
![Battle](screenshots/battle.png)

## Tech Stack

- **Frontend**: vanilla JS (no framework), socket.io client
- **Backend**: Node.js + Express + socket.io
- **Word data**: JSON files under `words/` — see [word-pk-words](https://github.com/chenjunming116/word-pk-words)
- **Deployment**: cloud server (pm2), EdgeOne CDN

## Play

👉 **[wordbattle.top](https://wordbattle.top)**

---

## Self-hosting

```bash
git clone https://github.com/chenjunming116/word-pk.git
cd word-pk
npm install

# 词库请从 word-pk-words 仓库获取，解压到 words/ 目录
# https://github.com/chenjunming116/word-pk-words

node server.js          # 默认监听 3000
```

打开 <http://localhost:3000>。

### Configuration

所有密钥都**不硬编码**，按以下顺序读取：

1. **环境变量**（推荐用于生产）
2. 项目根目录的 `bridge-config.json`（**已被 .gitignore 忽略**）

| 变量 | 用途 | 必需 |
|---|---|---|
| `BRIDGE_KEY` | QQ 桥接调用服务端接口的密钥 | 用到桥接时 |
| `ONEBOT_TOKEN` | NapCat / OneBot 的 access token | 用到桥接时 |
| `TEACHER_KEY` | 教师班级管理入口密钥（**请务必修改默认值**） | 用到班级功能时 |
| `WX_SECRET` | 微信小程序 AppSecret | 用微信登录时 |
| `QQ_APPID` / `QQ_SECRET` | QQ 小程序凭据 | 用 QQ 登录时 |

示例 `bridge-config.json`：

```json
{
  "ONEBOT_TOKEN": "your-token-here",
  "BRIDGE_KEY": "your-key-here"
}
```

> ⚠️ **部署到公网前请务必修改 `TEACHER_KEY` 默认值**，并确保 `bridge-config.json`
> 不在版本控制中（`.gitignore` 已包含）。

### Runtime data

以下文件为运行时数据，**不入版本库**，各环境自行生成：
`results.json`、`users.json`、`streaks.json`、`friends.json`、`name-owners.json`、
`rank.json`、`config.json` 等。

---

## Word data

词库（246 个词库 / 818,245 词）单独开源在
**[chenjunming116/word-pk-words](https://github.com/chenjunming116/word-pk-words)**。

**数据按来源分层授权**，不是单一许可证：

| 部分 | 来源 | 许可证 |
|---|---|---|
| 原创主题词库、专业词汇 | 本项目 | CC0 1.0 |
| Wiktionary / JMdict / Tatoeba 衍生 | 开放数据集 | CC BY-SA 4.0（须署名 + 相同方式共享） |
| WordNet 释义 | Princeton University | WordNet License |
| 教材 / 考试词表 | 公开课程标准 | CC0 1.0（词表部分） |

使用词库前请阅读该仓库的 `ATTRIBUTION.md`。

---

## License

**代码以 [MIT License](LICENSE) 开源。** 你可以自由使用、修改、分发，包括商用，
只需保留版权声明。

**词库数据不适用 MIT**，按上表分层授权，详见
[word-pk-words](https://github.com/chenjunming116/word-pk-words)。

---

## Contributing

欢迎提 Issue 和 PR。词库纠错、新题型、翻译都欢迎。

本项目面向中文母语者的英语学习场景，界面中英双语。