lihongxun945/gobang: a JavaScript Gomoku AI built on minimax and alpha-beta pruning

What lihongxun945/gobang is for, and who should read the source

This is a Gomoku (five in a row) engine that runs entirely in the browser. The README describes the project as an implementation of the minimax algorithm with alpha-beta pruning, and answers the obvious question directly: it does not use a neural network or reinforcement learning. The author states the repository is for personal hobby research into AI and that the code has gaps. That framing matters. The audience is someone who wants to see how a game tree search is assembled in plain JavaScript, not someone shopping for a strong opponent.

The repository pairs the engine with a nine-part blog series covering game theory background, minimax search, alpha-beta pruning, the heuristic evaluation function, iterative deepening, Zobrist hashing, threat search, and performance tuning. The README notes that the tutorial code differs from the repository code but shares the same principles. That is the real deliverable: a working program plus an explanation of each piece. If you only want to play, the hosted page at gobang2.light7.cn is the shorter path.

How the search works: candidate pruning, transposition tables and threat search

The engine is a minimax search with alpha-beta pruning, refined by several standard techniques. The 2026/08/09 changelog entries describe a transposition table with upper and lower bounds, iterative deepening, a tactical quiescence search, incremental win/loss detection, and killer move ordering, with the default search depth raised to 6. The 2026/08/12 entry describes maintaining effective candidate points and a threat index incrementally, adding a restricted live-three extension in shallow search, and enabling principal variation search at the root by default. VCT (victory by continuous threats) opponent search was changed to reuse the original board and transposition table rather than rebuilding an inverted board.

Two design decisions stand out. First, candidate point generation is not a full board scan; the engine tracks which empty points are near existing stones and prunes the rest, which is why the changelog entries about candidate distance and pruning bugs matter. Second, evaluation is incremental, and the 2026/08/09 entry records a fix for incremental evaluation being affected by search order. That kind of bug is the characteristic failure mode of incremental scoring: the score depends on the order in which you updated it, not only on the board. The README does not document how the evaluation weights were chosen, so treat the scoring function as tuned by hand and by measured games rather than derived.

Installing lihongxun945/gobang and making a first move locally

The repository is a pure front-end project, so Node and npm are required. The README says Node v16 through v20 should work in theory, without claiming thorough testing. Install dependencies first, then start the development server. The npm scripts are defined in package.json and the start script runs react-app-rewired start, so the dev server is the Create React App style server rather than a custom one.

npm install
npm start

After npm start, the README indicates a local development service is launched for the React front end. The AI itself executes locally in the browser; the README notes that the first page load or a refresh needs a network connection, but once the page is open the engine runs without one. Difficulty levels map to search depth, so a higher difficulty means a deeper search and a longer wait.

The other build and test commands are listed in the README and match package.json: npm test runs the unit tests, npm run build produces the dist directory, and npm run js, npm run less and npm run watch compile JavaScript, compile Less, and watch for changes respectively. The repository also contains config-overrides.js and webpack.ai.config.js at the top level, which is where the build rewiring lives.

Measuring whether a change made the AI stronger

The most interesting part of this repository is not the engine, it is the evaluation harness. npm run ai:evaluate builds both the current working tree and a specified Git baseline, runs the two engines in separate processes, and plays the same set of openings with colors swapped. The README gives three invocations, and the flags are documented there: --games, --depth, --time-ms, --concurrency, --baseline and --output.

npm run ai:evaluate -- --games 20 --depth 2

npm run ai:evaluate -- --baseline HEAD --games 200 --depth 4 \
  --concurrency 4 --output .ai-eval/result.json

npm run ai:evaluate -- --games 200 --depth 10 --time-ms 300 --concurrency 1

The report contains wins, losses and draws, a score rate, an Elo estimate, a 95 percent confidence interval, node counts, elapsed time and average completed depth. The README states that the confidence interval is clustered by original opening family, so prefixes, rotations and mirrors of one opening are not counted as independent samples. It advises treating a strength improvement as confirmed only when the lower bound of elo95 is above zero or probabilityBetter exceeds 0.95, and warns that a small number of games only detects obvious regressions. For timed matches the README recommends --concurrency 1 so CPU contention does not distort the result.

The repository's own reported numbers deserve care. A 2026/08/13 run against commit 04def12 over 60 games at 150ms per move produced 33 wins, 3 draws and 24 losses, a 57.5 percent score rate and an Elo point estimate of +53, but the 95 percent interval spans -19 to +125. The README itself calls this a positive signal that is not yet statistically significant. That is an honest presentation, and it is also a warning: at 60 games the harness cannot separate a real gain from noise. The tactical suite is the cheaper check, with npm run ai:tactics, an optional --symmetries flag that generates eight rotations and mirrors per position, and --baseline-report to diff against an earlier run.

Where the browser engine falls short

The README answers the strength question without hedging: the AI uses minimax with limited optimization, and because JavaScript in the browser is the execution environment, the search depth is shallow and the playing strength will not be high. Hardware matters a lot, and the README suggests lowering the difficulty if a move takes too long. So the wrong use case is clear. Do not use this as a sparring partner if you want a serious opponent, and do not use it where a server must evaluate positions, because the engine as shipped is a front-end bundle.

A second limitation is architectural. package.json marks the project private with version 3.1.0 and no main or module entry, so it is an application, not a library you import. Reusing the search in another project means lifting source files out of src/ and wiring your own build. The README's own note that the tutorial code and the repository code differ adds friction for anyone following the blog series alongside the source.

Third, the licence is unknown. No licence file appears among the top-level repository entries, and the README does not name one. For personal study that may be tolerable; for redistribution or commercial use it is an unresolved question, and the repository's own description of itself as hobby research is not a licence grant.

The alternative inside the same account: alpha-zero-gobang

The README points to a sibling project, alpha-zero-gobang, described as an implementation of Alpha Zero principles in Tensorflow 2.x and still in development. The difference in approach is fundamental rather than incremental. This repository encodes knowledge as a hand-written evaluation function and searches a tree; the Alpha Zero approach learns a policy and value function from self-play and uses the network to guide search. That changes what you can inspect and modify. Here you can read the scoring rules and adjust a weight; there you would be training and evaluating a model.

For a reader who wants to understand search, pruning and evaluation, the minimax repository is the more direct study object, because every decision is visible in code. For a reader who wants a stronger opponent, the neural approach is the one the author is pursuing. The README presents them as complementary rather than competing, and that framing is fair: they teach different things.

Maintenance, upgrade cost and the licence question

The last push was on 2026-09-05, and the repository is not archived. The changelog is unusually active for a hobby project, with entries on 2026/08/09, 2026/08/12 and 2026/08/13 covering search fixes, a new tactical suite, and A/B strength evaluation, on top of a full rewrite in 2023/11 that moved the UI to React 18. Those 2026 entries read like work on measurement infrastructure as much as on playing strength, which is consistent with a project whose author is exploring rather than shipping.

Upgrade cost is low in dependency terms and moderate in verification terms. The dependency set is ordinary React tooling: react 18.2, antd 5.8, Redux Toolkit 1.9, axios, lodash, plus react-app-rewired and worker-loader as dev dependencies. There are no native modules and no server components. The verification cost is the real one: the README's own guidance is that a strength claim needs a clustered confidence interval with a lower bound above zero, which means hundreds of games at a fixed depth or a timed budget, run at single concurrency for timed matches. On a laptop that is a background job, not a quick check.

On licensing, the honest statement is that the repository lists no licence file and the README does not state terms. Copyright defaults apply to the source unless a licence says otherwise, and the README's remark that the code is for personal hobby research does not change that. If you intend to redistribute the code or ship it inside a product, resolve the licence with the author first; nothing in the repository grants permission. This is not legal advice, only a reading of what the repository does and does not say.

Editorial conclusion

Adopt it if you want to read or modify a self-contained minimax Gomoku engine in JavaScript, or if you want a worked example of evaluating a search change with clustered confidence intervals instead of a single win rate. Do not adopt it if you need a strong opponent, a server-side engine, or a documented library API; the README states plainly that the shallow browser search limits its strength, and the repository is a private React application rather than a published package. Before building on it, run npm install and npm run ai:evaluate -- --games 20 --depth 2 to confirm the harness works on your machine, then check the licence situation, because no licence file is listed among the top-level entries.

Frequently asked questions

Official sources

1. Issues
2. lihongxun945/gobang on GitHub
3. Project website
4. README