streamlit-gomoku

A simple Gomoku game built with Streamlit.

Explore the docs »
View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Deployment
3. Usage
• How to play
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgements

About The Project

This is a literally one-day project for exploring the possibility of using Streamlit to build a game for remote players, and have some fun with my friends BTW.

Here's why I wrote this web app:

• Streamlit is a extremely powerful tool for building web apps, but not limited to SERIOUS USE.
• It's a great way to test out some of the newest features in Streamlit and packages like Streamlit Server State by whitphx.
• Just because I can.

Since time is limited, the code may look a bit untidies and sometimes buggy, though I've tried my best to avoid so. You are more than welcomed to suggest changes by forking this repo and creating a pull request or opening an issue. Thanks in advance!

Built With

Yes, it only uses framework provided by Streamlit!

Getting Started

Prerequisites

Just install the packages provided by Requirement.

pip3 install -r requirements.txt

Deployment

1. Get a copy of this repo or clone it from GitHub, OR if you prefer, you can copy gomoku.py only and run it without customized theme (NOT RECOMMENDED)
2. Get into the directory of this repo.

   cd streamlit-gomoku

3. Start the app on the fly!

   streamlit run gomoku.py

   • You can also run it on designated port (default: 8501).

     streamlit run gomoku.py --server.port=2021

4. Access the app by visiting http://localhost:<server_port> or through server URL.

Usage

The game based on Freestyle Gomoku rule.

Update: Now you can try it out on Streamlit Cloud!

How to play

Local Game

Click the Switch to Local mode button in the sidebar, then enjoy your game!

The thing is that, without clicking this button, as long as no room is created or joined, the game is the same in both game play mode

Remote Game

• This is the default game play mode, but you can switch to it by clicking Switch to Remote mode in the sidebar.
• You can create and share a room by clicking Create new room in the sidebar and copy the generated room ID to your friends
• Or you may join an existing room by pasting the room ID into the text input area and click Join room, the game will automatically sync the play status between browsers.

Roadmap

Here is a list of features I planned to be or have already been added:

• Local game play mode
• Remote game play mode
• Custom theme for eye candy
• Faster element rendering
• More rule options for balancing
• One-click room sharing
• Room management (e.g. judge if the room is full)
• Implementation of a Gomoku AI

Contributing

Any contributions you make are greatly appreciated, as I may or may not continue on this project myself for a considerably long time.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Theodore Huang (黄楠) - E-mail

Project Link: streamlit-gomoku

Acknowledgements

• Streamlit
• Streamlit server state
• Best README Template
• Img Shields