Gomoku Web / 五子棋

An offline-first 15 × 15 Gomoku game for Web Mobile and WeChat Mini Game, built with Cocos Creator, TypeScript, and FairyGUI.

Screenshots · Features · Run Locally · Build

• Three-level AI — choose Easy, Normal, or Hard for a quick single-player match.
• Local play — challenge another player on the same device without accounts or a backend.
• Distinct variants — switch between Skill Battle and rotating Daily Challenge positions.
• Replayable progress — keep local match history, step through replays, and track achievements and statistics.

Screenshots / Preview

The following screenshots come from the tracked Cocos Web Mobile review build; they are not design mockups.

The current in-game UI is primarily Chinese. English UI localization is planned.

Home / 首页	Skill Battle / 奇招乱斗
Replay / 棋谱复盘	Achievements / 成就

Watch the recorded Web Mobile walkthrough · Browse additional review screenshots

The Web Mobile build is useful for browser review, but it only simulates WeChat-specific safe areas. Sharing, vibration, audio focus, lifecycle behavior, and final device layout still require WeChat Developer Tools or physical-device testing.

Overview / 项目简介

Gomoku Web is a mobile-oriented implementation of freestyle Gomoku on a 15 × 15 board. It is built with Cocos Creator 2.4.15, TypeScript, and FairyGUI, targets Cocos Web Mobile and WeChat Mini Game, and is designed primarily for offline, single-device play with local persistence.

Gomoku Web 是一款面向移动端的 15 × 15 五子棋，使用 Cocos Creator 2.4.15、TypeScript 与 FairyGUI 开发，可构建为 Web Mobile 和微信小游戏，主要提供离线单机及同设备双人体验。

Features / 主要功能

• AI battles and match tools — play against Easy, Normal, or Hard AI, with undo, hints, restart, rules, move previews, and optional move numbers.
• Local PvP — two players share one device and alternate turns.
• Skill Battle — the currently enabled “迷糊一子” skill temporarily excludes the opponent's latest stone from five-in-a-row detection.
• Daily Challenge — play rotating preset positions with locally stored completion progress.
• Match History and Replay — store up to 50 recent matches locally and reconstruct each game move by move.
• Local Progression — retain achievements, player level, experience, win/loss/draw statistics, streaks, settings, and difficulty preferences on the device.

Current scope: this is an offline AI/local multiplayer game. It does not include online matchmaking, cloud sync, payments, ads, or a server-side leaderboard.

Technology Stack / 技术栈

Area	Technology
Game runtime and builds	Cocos Creator 2.4.15
Gameplay code	TypeScript
UI authoring and runtime	FairyGUI
Build targets	Cocos Web Mobile and WeChat Mini Game
Local persistence	WeChat storage APIs with browser localStorage fallback
Auxiliary tooling	Node.js, Vite, and Playwright Core

Local Development / 本地运行

Prerequisites

• Git
• Cocos Creator 2.4.15
• Node.js and npm for repository tooling
• FairyGUI Editor only when changing UI source files
• WeChat Developer Tools only when testing the WeChat build

Do not open the Cocos project in a different major version merely to preview it; an automatic project upgrade may rewrite project metadata or generated assets.

Install repository tooling

git clone https://github.com/AMTYHHH/gomoku-web.git
cd gomoku-web
npm ci

Run the game from Cocos Creator

1. Open WuZiQi/ with Cocos Creator 2.4.15.
2. Wait for asset import to finish.
3. Open assets/Scene/Main.fire.
4. Start the browser preview from the editor.

The root npm run dev:tooling command starts a small auxiliary Vite information page, not the Gomoku game. Use the Cocos editor or build the Web Mobile target to run the game itself. See docs/REPOSITORY_TOOLING.md for the tooling boundary and command inventory.

Build / 构建

Web Mobile

PowerShell:

$env:COCOS_CREATOR = "<path-to-Cocos-Creator-2.4.15-executable>"
& $env:COCOS_CREATOR `
  --path ".\WuZiQi" `
  --build "platform=web-mobile;debug=false;md5Cache=false"

npm run review:serve

Then open http://127.0.0.1:7460/. The generated site is written to WuZiQi/build/web-mobile/ and is intentionally ignored by Git.

WeChat Mini Game

$env:COCOS_CREATOR = "<path-to-Cocos-Creator-2.4.15-executable>"
& $env:COCOS_CREATOR `
  --path ".\WuZiQi" `
  --build "platform=wechatgame;debug=false;md5Cache=false"

Import WuZiQi/build/wechatgame/ into WeChat Developer Tools and run a normal compile. Local developer identities and private project configuration must remain untracked.

Repository checks

After a Web Mobile build is available and npm run review:serve is running, the repository provides repeatable review checks:

npm run build
npm run test:smoke:web
npm run review:layout
npm run review:capture-quality -- http://127.0.0.1:7460/ review/screenshots/quality

npm run build is a compatibility alias for npm run build:tooling; it bundles only the auxiliary root Vite page. npm run test:smoke:web verifies the deployed public demo rather than a Cocos build produced by Repository CI. The authoritative game builds are produced by Cocos Creator. See docs/WEB_MOBILE_SMOKE_TESTS.md.

Automating Cocos Creator 2.4.15 on GitHub-hosted runners was evaluated and is not currently enabled because the legacy editor needs a GUI environment and lacks a supported, redistributable hosted-runner provisioning path. See docs/COCOS_BUILD_AUTOMATION.md.

Project Structure / 项目结构

.
├── WuZiQi/                         # Cocos Creator 2.4.15 game project
│   ├── assets/Scene/               # Main Cocos scene
│   ├── assets/Script/UiScript/     # Game rules, AI, state, storage, and UI bindings
│   ├── assets/resources/UI/        # Published FairyGUI runtime assets
│   └── build-templates/wechatgame/ # WeChat build template
├── WuZiQi_Ui/                      # Editable FairyGUI source project
├── docs/                           # Design, architecture, workflow, and release notes
├── review/                         # QA reports, screenshots, and review artifacts
├── scripts/                        # Capture, layout, packaging, and verification tools
├── index.html                      # Auxiliary static Vite information page
├── package.json                    # Auxiliary review/tooling commands
└── project.config.json             # WeChat project configuration

For UI work, edit the FairyGUI source first, publish it to WuZiQi/assets/resources/UI/, and then update TypeScript bindings if necessary. See docs/UI_BUG_WORKFLOW.md and docs/UI_COMPONENT_BINDINGS.md.

The root Node/npm workspace is auxiliary infrastructure. Its build is not a Cocos game build; see docs/REPOSITORY_TOOLING.md.

Roadmap / 路线图

Near term

• Keep third-party license notices and release packaging auditable.
• Complete full validation of the public online demo before linking it from the project homepage.
• Continue screenshot and README polish as the product evolves.
• Evaluate an appropriate continuous integration workflow for the Cocos and repository tooling checks.

Later

• Add English UI localization and establish an i18n workflow.
• Continue gameplay improvements and broader regression coverage.
• Evaluate the maintenance path for the Cocos Creator 2.4.x toolchain.
• Separate, simplify, or retire auxiliary tooling that is not part of the playable game.

The roadmap describes likely maintenance priorities, not committed release dates.

Contributing / 参与贡献

Issues and focused pull requests are welcome.

See CONTRIBUTING.md for the complete contribution workflow and SECURITY.md for responsible vulnerability reporting.

1. Open an issue before large gameplay, architecture, or UI changes.
2. Create a focused branch from master and keep commits scoped.
3. Preserve the FairyGUI-first workflow for layout and component changes.
4. Run the checks relevant to your change and include screenshots for visible UI updates.
5. Do not commit build output, local editor state, private WeChat configuration, credentials, or secrets.
6. In the pull request, explain the behavior change, affected targets, and verification performed.

AI-assisted Development

Codex is used as a development tool for code review, test execution, Git workflow checks, and iterative maintenance. Architecture, product decisions, and accepted changes remain human-directed and reviewed.

License

Original project code and assets owned by the project maintainer are licensed under the MIT License.

Third-party components, fonts, runtimes, templates, dependencies, and other separately identified materials remain under their respective licenses.

See LICENSE and THIRD_PARTY_NOTICES.md for details.