{"id":47098199,"url":"https://github.com/mlms13/binary-homeworlds","last_synced_at":"2026-03-12T14:56:15.274Z","repository":{"id":330634564,"uuid":"1120346640","full_name":"mlms13/binary-homeworlds","owner":"mlms13","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-12T17:16:51.000Z","size":587,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-12T21:56:27.916Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlms13.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-21T02:28:57.000Z","updated_at":"2026-01-12T16:15:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mlms13/binary-homeworlds","commit_stats":null,"previous_names":["mlms13/binary-homeworlds"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mlms13/binary-homeworlds","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlms13%2Fbinary-homeworlds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlms13%2Fbinary-homeworlds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlms13%2Fbinary-homeworlds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlms13%2Fbinary-homeworlds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlms13","download_url":"https://codeload.github.com/mlms13/binary-homeworlds/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlms13%2Fbinary-homeworlds/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30429129,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T14:34:45.044Z","status":"ssl_error","status_checked_at":"2026-03-12T14:09:33.793Z","response_time":114,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-03-12T14:56:14.690Z","updated_at":"2026-03-12T14:56:15.263Z","avatar_url":"https://github.com/mlms13.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Binary Homeworlds - Multiplayer Game\n\nA full-stack TypeScript implementation of Binary Homeworlds with multiplayer support, featuring a React frontend, Fastify backend server, and comprehensive game rules engine.\n\n## Features\n\n- **Complete Rules Implementation**: Implements all Binary Homeworlds game rules as specified in RULES.md\n- **Multiplayer Support**: Real-time multiplayer gameplay with Socket.IO\n- **Modern UI**: React-based interface with lobby system and game board\n- **Event Sourcing**: Game state is derived by replaying actions, enabling persistence and replay functionality\n- **Type Safety**: Full TypeScript implementation with strict typing across all packages\n- **Comprehensive Testing**: Includes tests for all examples from RULES.md plus extensive edge case coverage\n\n## Architecture\n\nThe project is organized as a monorepo with three main packages:\n\n- **`packages/shared`**: Core game logic, rules engine, and shared types\n- **`packages/server`**: Fastify backend server with Socket.IO for real-time multiplayer\n- **`packages/ui-client`**: React frontend with Vite for fast development\n\n### Game Engine Components\n\nThe game engine follows an event sourcing pattern where:\n\n- **Actions** represent all possible game moves (setup, move, capture, grow, trade, sacrifice, overpopulation)\n- **Game State** is derived by applying a sequence of actions\n- **Immutability** is maintained through proper state management\n- **Validation** ensures all actions follow the game rules\n\n## Prerequisites\n\n### Required Dependencies\n\n1. **Node.js** (v18 or higher)\n2. **Redis** (required for multiplayer server)\n\n#### Installing Redis\n\n**macOS:**\n```bash\nbrew install redis\n```\n\n**Ubuntu/Debian:**\n```bash\nsudo apt-get install redis-server\n```\n\n**Windows:**\nDownload from [Redis for Windows](https://github.com/microsoftarchive/redis/releases)\n\n## Development Setup\n\n### 1. Install Dependencies\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd binary-homeworlds\n\n# Install all dependencies\nnpm install\n```\n\n### 2. Start Redis\n\n```bash\n# Start Redis server (required for multiplayer functionality)\nredis-server\n```\n\n### 3. Start Development Servers\n\n```bash\n# Start all services (shared, server, ui-client) concurrently\nnpm run dev\n```\n\n**Or start individual services:**\n\n```bash\n# Watch mode for shared package (game logic)\nnpm run dev:shared\n\n# Backend server (port 3001)\nnpm run dev:server\n\n# Frontend UI (port 3002)\nnpm run dev:ui\n```\n\n### 4. Access the Application\n\n- **UI Client**: http://localhost:3002\n- **Server API**: http://localhost:3001\n- **Health Check**: http://localhost:3001/health\n\n## Usage\n\n### Multiplayer Gameplay\n\n1. **Create a Game**: Choose between local, public, or private games\n2. **Join a Game**: Browse available public games or join with a private code\n3. **Game Setup**: Players take turns selecting stars and ships for their home systems\n4. **Play**: Take turns performing actions (move, capture, grow, trade, sacrifice)\n5. **Win**: Eliminate your opponent by capturing all their ships or destroying their home stars\n\n### Game Actions\n\n- **Move (Yellow)**: Move ships between systems\n- **Capture (Red)**: Take control of opponent ships\n- **Grow (Green)**: Create new ships\n- **Trade (Blue)**: Exchange ships for different colors\n- **Sacrifice**: Give up a ship for multiple actions\n\n## Development\n\n### Available Scripts\n\n```bash\n# Development\nnpm run dev                    # Start all services\nnpm run dev:shared            # Watch shared package\nnpm run dev:server            # Start server only\nnpm run dev:ui                # Start UI only\n\n# Building\nnpm run build                 # Build all packages\nnpm run build:shared          # Build shared package\nnpm run build:server          # Build server\nnpm run build:ui              # Build UI\n\n# Testing\nnpm run test                  # Run all tests\nnpm run test:shared           # Run shared package tests\nnpm run test:coverage -w packages/shared  # Run tests with coverage\n\n# Code Quality\nnpm run lint                  # Run ESLint\nnpm run lint:fix              # Fix ESLint issues\nnpm run format                # Format code with Prettier\nnpm run format:check          # Check code formatting\nnpm run typecheck             # Run TypeScript type checking\n```\n\n### Project Structure\n\n```\nbinary-homeworlds/\n├── packages/\n│   ├── shared/              # Game logic and rules engine\n│   ├── server/              # Backend server\n│   └── ui-client/           # React frontend\n└── RULES.md                 # Game rules documentation\n```\n\n## Testing\n\nThe project includes comprehensive tests covering:\n\n- All 11 examples from RULES.md\n- Edge cases and error conditions\n- Game setup and flow\n- Action validation\n- State management\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm run test\n\n# Run tests with coverage (shared package only)\nnpm run test:coverage -w packages/shared\n\n# Run tests in watch mode\nnpm run test:watch -w packages/shared\n```\n\n## Environment Variables\n\n### Server Configuration\n\nCreate a `.env` file in `packages/server/`:\n\n```env\nPORT=3001\nHOST=0.0.0.0\nREDIS_URL=redis://localhost:6379\n```\n\n### UI Client Configuration\n\nCreate a `.env` file in `packages/ui-client/`:\n\n```env\nVITE_SERVER_URL=http://localhost:3001\n```\n\n## Deployment\n\n### Building for Production\n\n```bash\n# Build all packages\nnpm run build\n\n# Start production server\nnpm run start -w packages/server\n```\n\n### Docker Deployment\n\nThe server can be deployed with Docker (requires Redis):\n\n```bash\n# Build server image\ndocker build -t binary-homeworlds-server packages/server/\n\n# Run with Redis\ndocker run -p 3001:3001 --link redis:redis binary-homeworlds-server\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and linting: `npm run test \u0026\u0026 npm run lint`\n5. Submit a pull request\n\n## License\n\nISC License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlms13%2Fbinary-homeworlds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlms13%2Fbinary-homeworlds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlms13%2Fbinary-homeworlds/lists"}