{"id":19338175,"url":"https://github.com/jserv/ttt","last_synced_at":"2025-04-23T01:31:17.615Z","repository":{"id":219064334,"uuid":"748002597","full_name":"jserv/ttt","owner":"jserv","description":"An implementation of tic-tac-toe in C, featuring AI agents","archived":false,"fork":false,"pushed_at":"2025-04-21T04:24:34.000Z","size":83,"stargazers_count":36,"open_issues_count":2,"forks_count":47,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-21T05:36:16.163Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jserv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-25T04:09:49.000Z","updated_at":"2025-04-21T04:24:38.000Z","dependencies_parsed_at":"2024-03-05T15:03:32.717Z","dependency_job_id":"32a3b8aa-113f-49fc-8b61-76faf9fa1406","html_url":"https://github.com/jserv/ttt","commit_stats":null,"previous_names":["jserv/ttt"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jserv%2Fttt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jserv%2Fttt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jserv%2Fttt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jserv%2Fttt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jserv","download_url":"https://codeload.github.com/jserv/ttt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250352246,"owners_count":21416461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T03:16:33.962Z","updated_at":"2025-04-23T01:31:17.326Z","avatar_url":"https://github.com/jserv.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ttt\n\nAn implementation of [tic-tac-toe](https://en.wikipedia.org/wiki/Tic-tac-toe) in C,\nfeaturing an AI powered by the [negamax](https://en.wikipedia.org/wiki/Negamax) algorithm, the [reinforcement learning (RL)](https://en.wikipedia.org/wiki/Reinforcement_learning) algorithm, the [Monte Carlo tree search (MCTS)](https://en.wikipedia.org/wiki/Monte_Carlo_tree_search) algorithm. And the RL algorithm contains the [Monte Carlo learning](https://en.wikipedia.org/wiki/Monte_Carlo_method) algorithm and [TD learning](https://en.wikipedia.org/wiki/Temporal_difference_learning) algorithm.\n\n\n## Build\n### negamax AI\nIf you want to play with negamax AI:\nBuild the game:\n```bash\n$ make\n```\nand run:\n```bash\n$ ./ttt\n```\n### reinforcement learning AI\nIf you want to play with RL AI:\nTrain the state value table first, you could modify the hyperparameters, which are macros in `train.c`:\n- **MONTE_CARLO** : Decide whether or not to use the Monte Carlo method or the TD method.\n- **REWARD_TRADEOFF** : Decide the reward of the Markov decision model, which is a balance between the episode reward and the score from `get_score`. Those who want to fully customize the reward can modify it in the `init_agent` function.\n- **INITIAL_MULTIPLIER** : Decide the initial state value, which is the multiplier of `get_score` in the initial state value. Those who want to fully customize the initial state value can modify it in the `init_agent` function.\n- **EPSILON_GREEDY** : Decide whether or not to use epsilon-greedy exploration when training.\n- **NUM_EPISODE** : the number of game episode in training \n- **LEARNING_RATE**, **GAMMA** : $\\alpha$, $\\gamma$ in training.\n- **EPSILON_START** **EPSILON_END** : $\\epsilon$ in [Epsilon-Greedy Algorithm](https://stanford-cs221.github.io/autumn2020-extra/modules/mdps/epsilon-greedy.pdf) and it would decay exponentially.\n\n\ncompile\n```bash\n$ make train\n```\nand run:\n```\n$./train\n```\n\nBuild the game playing with RL agent, it would load the pretrained model from `train`:\n```bash\n$ make rl\n```\nand run:\n```bash\n$ ./rl\n```\n### MCTS AI\nIf you want to play with MCTS AI:  \nThere are several hyperparameters you can modify:\n- **EXPLORATION_FACTOR**  in `agents/mcts.h` :  The exploration parameter.\n- **ITERATIONS**  in `agents/mcts.h` :  Number of simulations in MCTS.\n\nBuild the game:\n```bash\n$ make mcts\n```\nand run:\n```bash\n$ ./mcts\n```\n\n### ELO rating system\nThere are several hyperparameters you can modify:\n- **N_GAMES**  in `elo.c` :  The number of games played to calculate the ELO rating.\n- **ELO_INIT**  in `elo.c` :  The initial ELO rating assigned to a player before any games are played.\n- **ELO_K**  in `elo.c` :  The coefficient used in the ELO calculation formula to determine the impact of each game's outcome on the player's rating.\n\nBuild the elo system:\n```bash\n$ make elo\n```\nand run:\n```bash\n$ ./elo\n```\n\n## Run\nThese program operate entirely in the terminal environment.\nBelow is its appearance as it awaits your next move:\n```\n 1 |  ×\n 2 |     ○\n 3 |\n---+----------\n      A  B  C\n\u003e\n```\n\nTo execute a move, enter `[column][row]`. For example:\n```\n\u003e a3\n```\n\nPress Ctrl-C to exit.\n\n## Game Rules\nThe winner is determined by the first player who successfully places `GOAL` of their marks in a row, whether it is vertically, horizontally, or diagonally, regardless of the board size.\n\nUsing the following 4x4 board games, whose `GOAL` is 3, as examples:\n\n```\n 1 |  ×  ×\n 2 |     ○  ×\n 3 |     ○\n 4 |     ○\n---+------------\n      A  B  C  D\n\u003e\n```\n\nThe player \"○\" wins the game since he placed his marks in a row vertically (B2-B3-B4).\n\n```\n 1 |  ×  ×  ○\n 2 |  ×  ○  \n 3 |  ○  \n 4 |     \n---+------------\n      A  B  C  D\n\u003e\n```\n\nThe player \"○\" wins the game since he placed his marks in a row diagonally (A3-B2-C1).\n\n```\n 1 |  o  x  \n 2 |  o  x  \n 3 |  o     x\n 4 |  o  x\n---+------------\n      A  B  C  D\n\u003e\n```\n\nThe player \"○\" wins the game if `ALLOW_EXCEED` is `1`; otherwise, the game will continue because the number of \"○\"s in a row exceeds `GOAL`.\n\n## Reference\n* [Mastering Tic-Tac-Toe with Minimax Algorithm in Python](https://levelup.gitconnected.com/3394d65fa88f)\n* [tic-tac-toe](https://github.com/jserv/tic-tac-toe): tic-tac-toe game for terminal I/O.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjserv%2Fttt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjserv%2Fttt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjserv%2Fttt/lists"}