HTMX Agario

HTMX Agario

Real-time multiplayer Agar.io clone with server-side physics. Built with Go, HTMX, WebSockets, and custom collision detection.

Go, HTMX, WebSockets, Gorilla
Started: 3/23/2024
Updated: 10/15/2024
htmx,web,game,multiplayer,go
GitHub

Overview

A fully server-side implementation of the popular multiplayer game Agar.io, demonstrating how real-time multiplayer games can be built using HTMX and WebSockets. This project pushes the boundaries of server-driven architectures by handling all game logic, physics, and collision detection on the backend.

Features

  • Real-Time Multiplayer - WebSocket-based synchronization for smooth multiplayer gameplay
  • Server-Side Physics Engine - Complete physics simulation including collision detection and mass transfer
  • Food System - Dynamic food spawning and consumption mechanics
  • Mass-Based Gameplay - Players grow by consuming food and smaller players
  • Persistent Game World - 10,000x10,000 grid with continuous play area
  • Infrastructure as Code - Terraform deployment scripts for AWS infrastructure

Technical Implementation

Architecture Stack

  • Backend: Go with Gorilla WebSocket library
  • Real-Time Communication: WebSockets for bi-directional player updates
  • Frontend: Server-side HTML templating with HTMX
  • Game Loop: Server-authoritative physics and collision detection
  • Deployment: Docker containerized with Terraform for AWS deployment

Game Engine

Physics System:

  • Custom collision detection for circle-based entities
  • Mass transfer mechanics between players
  • Viewport-based rendering (only render what the player can see)
  • Food spawning and consumption system
  • Movement based on screen/mouse coordinates

Multiplayer Architecture:

  • WebSocket connections for each player
  • Server broadcasts game state updates to all clients
  • Client sends screen dimensions and input commands
  • All game logic validated server-side to prevent cheating

Deployment

The project includes complete Terraform infrastructure for deploying to AWS:

  • Automated domain configuration
  • Route 53 hosted zone setup
  • Containerized deployment pipeline

Development Approach

This project demonstrates that even complex multiplayer games can leverage HTMX's hypermedia-driven approach when combined with WebSockets for real-time communication. By keeping all game logic server-side, it eliminates common multiplayer issues like client-side prediction and reconciliation.

Running Locally

git clone https://github.com/DeaSTL/agario-htmx
cd agario-htmx
docker compose up

Then visit localhost:8080 in your browser and start playing!