utkarsh-naman/unc

1. Repository purpose and overall shape

This repo packages a “solved” Chopsticks bot around a precomputed game graph. The architecture is not a typical on-demand search engine; it is a pipeline that builds the full state graph offline, annotates it with values, then ships a runtime engine that reads the finalized graph and plays from it.

2. Core domain model

The game logic is centered on compact state representations for the two players’ hand counts and whose turn it is. The include/rules.hpp, include/utils/state_repr.hpp, and corresponding src/utils/state_repr.cpp files define the canonical representation used throughout the solver, builder, serializer, and runtime engine.

3. Move-generation subsystem

Legal game transitions are implemented as a set of focused move modules under include/utils/moves and src/utils/moves. These cover attack variations and redistribution behavior, with helpers such as arrange_*, left_to_*, right_to_*, distribute, and next_state. This subsystem is the forward edge generator for the game graph.

4. Reverse-transition / parent discovery subsystem

A parallel set of modules under include/utils/unmove and src/utils/unmove computes predecessor states. This is important because the solver is built bottom-up: instead of exploring forward from the start state, it propagates values backward from terminal positions through parent links.

5. Offline map builder pipeline

The src/MapBuilder and build/ directories contain the graph-construction utilities for initial maps such as map_0 and map_p_0. These builders create the raw state graph and the parent map artifacts that later stages consume. The presence of test_map0, test_map_p_0, and related binaries shows this stage is independently validated.

6. Value-setting / solving pipeline

src/MapValueSetter is where the graph gets solved. The files set_terminal_depth.cpp, set_suicides.cpp, and set_score.cpp indicate a staged annotation process: first mark terminal depths, then assign special values for suicide/terminal conditions, then propagate scores across the graph. The repository’s README calls this the “MaxiMax” approach, but architecturally it is a backward propagation of game values over the precomputed graph.

7. Final solved map artifact

The culmination of the offline pipeline is map_final plus supporting serialized files in bin/output/map/.... This final dataset is what the runtime consumes. The architecture depends on this artifact being complete and consistent; the bot’s runtime behavior is driven by lookup and evaluation against this precomputed map, not by running a deep search at play time.

8. Runtime engine boundary

src/UncEngine and WASM/engine_unc.cpp contain the play-time engine. This layer loads the final map, evaluates the current game state, and selects a move. It is deliberately separated from the map-building code so the deployed bot stays lightweight and deterministic.

9. Serialization boundary

serializer.cpp/.hpp, p_serializer.cpp, and state_repr.cpp/.hpp implement the file format and in-memory encoding used to move graph data between builder, solver, and engine. This is the key boundary between the algorithmic graph pipeline and the runtime consumer, and it is also what enables the preloaded .data file in the browser build.

10. WASM / browser packaging

The WASM directory contains the browser-facing build: bindings.cpp exposes the C++ engine to JavaScript via Emscripten, index.html is the demo shell, and server.py supports local serving. The generated chopsticks_bot.js, chopsticks_bot.wasm, and chopsticks_bot.data are the deployable artifacts; cdn and cdn4 hold copies for publishing.

11. Testing and verification

The tests directory contains concept checks, reference implementations, parent-map validation, and bot tests. These are important because the solution depends on graph correctness rather than heuristic quality; the tests verify that generated parent relationships and solved values match expected behavior.

12. Build system and artifact layout

The root CMakeLists.txt and the various *.txt command lists in src/MapBuilder, src/MapValueSetter, and WASM reflect a multi-stage build process rather than a single compile step. The repo contains both source and generated binaries/data, which signals that the architecture is a toolchain plus runtime, not just a library.