Go-Go-Go

A full-stack multiplayer Alkkagi (Stone-Shooting) game built entirely in Go, featuring a terminal user interface (TUI), real-time WebSocket communication and game logic with physics.

Table of Contents

• Project Overview
• How to Play
• Installation
• Core Components

Project Overview

🖥️ Terminal User Interface (TUI)

• Modern TUI: Built with Bubble Tea framework for a gui-like experience in the terminal.
• Real-time Rendering: Render game state and animations by using handling custom animation logic.

🌐 Real-time Multiplayer

• WebSocket Communication: Instant game state synchronization by sending game events and animation by using Gorilla WebSocket.
• Live Message System: In-game messaging for player interaction. Messages include chat and game events.

🎮 Game Mechanics

• Physics Engine: Realistic stone collision and movement simulation with calculations for velocity and acceleration.
• Relative Positioning: Stones are positioned in game board (100x100) with relative coordinates and rendered in user's current terminal window size.

💾 Recording History

• Game Records: Automatic recording of all game sessions with saving the event history. (postgreSQL)

How to Play

1. Start: Select the start menu to match with another player. Use arrow keys or H, J, K, L keys to navigate. (see below for help)
   

2. Match: Wait for another player to join your session. when both players are ready, the game starts automatically.
   

3. Game: Use arrow keys or H, J, K, L keys to navigate and control your shoot. Press I to chat with other player. You can resize the window to see the game board and stones in more detail.

4. Win: If one player has no more stones left, the game ends and exit with an announcement of the winner.

Previews

Shoot

---

control your shoot's direction and power with arrow keys or H, J, K, L keys.

---

when you shoot, the stone will move with a physics simulation, including friction and collision detection. Make other player's stones out of the board!

Chat

---

You can chat with other player or receive game events message from the server.

Resize

---

To see the game board and stones in more real shape, you can resize the window.

Installation

Prerequisites

• Go (version 1.24.4 or later)

1. Clone the repository

git clone https://github.com/yanmoyy/go-go-go.git

2. Install dependencies

cd go-go-go
go mod download

By default, the server and client use .env file for configuration. You can use the example file already in the repository.

# Server
SERVER_PORT="8080"                # server port

# Client
HTTP_BASE="http://localhost:8080" # base URL for HTTP requests
WS_BASE="ws://localhost:8080"     # base URL for WebSocket connections

3. Run the server

go run ./cmd/server

If you want to save the game history to database, you need to specify the database configuration in .env file. And run with -db flag.

# Database (optional)
DB_HOST="localhost"               # database host
DB_PORT="5432"                    # database port
DB_USER="postgres"                # database user
DB_PASSWORD="strongpassword"      # database password
DB_NAME="go-go-go"                # database name

go run ./cmd/server -db

4. Run the client

go run ./cmd/client

Core Components

We tried to build this project from scratch, using as few dependencies as possible to learn Go deeply. Below are the main components of the project:

• Logging: Using Slog, a structured logger for Go, to debug the application, track game flow, and resolve issues.
• Testing: Go’s testing environment enabled us to write testable code and address complex challenges (e.g., physics and UI rendering). We used Require for assertions.
• Websocket: Using Gorilla WebSocket for real-time communication. We leveraged goroutines for concurrent connections and channels for message passing, following the library’s documentation and examples.
• TUI: Using Bubble Tea for a modern TUI framework, styled with Lipgloss and enhanced with Bubbles for UI components. We implemented custom UI layout components (e.g., Column, Row, FlexContainer) similar with Flutter widgets. Also, the TUI structure was inspired by opencode project.
• Responsive UI: The game board is rendered using relative coordinates, adapting to the user’s current terminal window size. Run the application and resize your terminal to see the UI adjust dynamically!
• Physics Simulation: A custom 2D physics engine for realistic stone movement and collision detection, built entirely in Go without external libraries. (That’s why we named this project “Go-Go-Go”!)

Future Plans

• Single-player mode with AI opponent
• User customization options (e.g., stone colors, board size)
• Special stone types (e.g., stones with special abilities)
• User Accounts and Authentication

Contributors

• @yanmoyy
• @Gutssssssssss

License

MIT