AIBG - Serpent Showdown

Description

Serpent Showdown is a 1v1 versus snake game where two players battle it out on a dynamic grid. Each player starts with a snake of fixed length and a score of 1000 points. The goal is to outmaneuver your opponent by collecting items, avoiding hazards, and grabbing power-ups that either boost your score or disrupt your enemy.

The arena continuously changes throughout the match. After a set number of moves, the grid begins to shrink, forcing the snakes into closer quarters and raising the risk of collisions. The game ends when a snake crashes or when a player's score reaches zero. In a simultaneous loss, the winner is determined by the higher score or, if equal, by the longer snake.

Visuals

Docs

• Topic manual
• Topic presentation

Attribution

Created by:

• Jakov Jakovac (Topic responsible)
• Albert Maršić
• Martin Vrbovčan
• Ivan Androšević
• Barbara Jozić

License

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Usage

This topic was used in the following events:

• Zagreb 05/2025 (AIBG 9.0)

How to run

Before you begin, make sure your environment is set up to run the game. The following prerequisites will help you configure your system to run the server, agents, and visuals correctly.

Prerequisites

1. Install Node.js and npm (for server and JavaScript agent)

2. (Optional) Install Python 3.7+ (for Python agent)

3. Install an IDE with Live Server extension (for visuals)

4. Install required dependencies:

   • For server:

     cd server
     npm install

   • For JavaScript agents:

     cd agents
     npm install

   • For Python agents:

     cd agents
     pip install websockets

Game flow

1. Start the server
2. Start the visuals (they connect automatically to the server on port 3000)
3. Connect two agents using valid IDs from players.json (game starts automatically when both agents connect)
4. Server shuts down automatically after the game ends

Running the server

1. Create a players.json file in the server directory using the example:

   cp players.json.example players.json

   • Edit player IDs and names in the newly created players.json as needed

2. Start the server:

   cd server
   node server.js [port] [timeout]

   • The server runs on port defined on start or 3000 by default
   • The server accepts an optional timeout value in milliseconds (default: 150ms; use 0 to disable).
   • The server automatically creates the game object (logic) on start

Running the visuals

1. Open the project in your IDE (we recommend VS Code)
2. Right-click on visuals/index.html → "Open with Live Server"
   • Live Server extension has to be installed
3. The game visualization will open in your default browser
4. The visuals auto-connect to the server on port 3000 once the server is running

To test the game manually, add ?mode=debug query string to the end of the url, for example:

http://127.0.0.1:5500/visuals/index.html?mode=debug

Manual gameplay connects to the server using IDs "k" and "l" so remember to add them to players.json.

Running agents

JavaScript test agent

node agents/testAgent.js [playerID] [mode]

Python test agent

python agents/testAgent.py [playerID] [mode]

Modes

• "up", "down", "left", "right": Constant direction
• "random": Random valid moves
• "timeout": Delayed actions
• "survive": Avoids death and collisions
• "apple": Seeks the closest apple (most advanced)

Deploy

To deploy the game server on a VPS:

1. Install prerequisites
   Make sure git, node, and npm are installed:

   sudo apt update
   sudo apt install git nodejs npm

2. Get the project files on your VPS
   You can either clone the public repository (recommended), or use rsync/scp to copy files manually.

   • Clone the repository (recommended):

     git clone https://github.com/AIBG-vault/topic-name.git
     cd AIBG

   • Or copy files using rsync or scp:

     # Using rsync
     rsync -av /path/to/AIBG user@your-vps-ip:/home/user/
     # Or using scp
     scp -r /path/to/AIBG user@your-vps-ip:/home/user/

3. Install dependencies

   cd server
   npm install

4. Create and edit players.json

   cp players.json.example players.json
   nano players.json

   Add your teams' IDs and names.

5. Start the server

   node server.js [port] [timeout]

6. Open firewall ports
   Make sure port 3000 (or your chosen port) is open:

   sudo ufw allow 3000

Players can now connect to the server using your VPS IP and the chosen port (e.g., ws://your-vps-ip:3000).

(Optional) Set up a custom domain

For easier access, consider setting up a DNS record (e.g., topic.aibg.best.hr) that points to your VPS IP. This makes it simpler for players to connect and remember the server address.

Example WebSocket connection URLs:

• ws://topic.aibg.best.hr:3000
• ws://your-vps-ip:3000

To set up a DNS record, use your domain provider’s dashboard to create an A record pointing to your VPS.