{"id":25193900,"url":"https://github.com/drcbeatz/chromaxen-dev","last_synced_at":"2026-04-11T10:35:00.035Z","repository":{"id":274995429,"uuid":"860725305","full_name":"DrCBeatz/chromaxen-dev","owner":"DrCBeatz","description":"ChromaXen is an open-source colour matching puzzle game, based on size-3 elementary cellular automata. (Javascript/Python/FastAPI/Docker/AWS/Terraform)","archived":false,"fork":false,"pushed_at":"2025-01-30T15:44:28.000Z","size":1952,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-09T23:39:27.750Z","etag":null,"topics":["api-gateway","aws","aws-lambda","cellular-automata","ci-cd","cloudfront","cloudwatch","css","docker","dynamodb","fast-api","game-development","github-actions","html","javascript","python","route53","s3","serverless","terraform"],"latest_commit_sha":null,"homepage":"https://chromaxen.com","language":"JavaScript","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/DrCBeatz.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}},"created_at":"2024-09-21T02:49:46.000Z","updated_at":"2025-01-30T22:05:22.000Z","dependencies_parsed_at":"2025-01-30T16:44:19.003Z","dependency_job_id":null,"html_url":"https://github.com/DrCBeatz/chromaxen-dev","commit_stats":null,"previous_names":["drcbeatz/chromaxen-dev"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrCBeatz%2Fchromaxen-dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrCBeatz%2Fchromaxen-dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrCBeatz%2Fchromaxen-dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrCBeatz%2Fchromaxen-dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DrCBeatz","download_url":"https://codeload.github.com/DrCBeatz/chromaxen-dev/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247190257,"owners_count":20898702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["api-gateway","aws","aws-lambda","cellular-automata","ci-cd","cloudfront","cloudwatch","css","docker","dynamodb","fast-api","game-development","github-actions","html","javascript","python","route53","s3","serverless","terraform"],"created_at":"2025-02-09T23:39:41.008Z","updated_at":"2025-12-30T20:25:15.472Z","avatar_url":"https://github.com/DrCBeatz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ChromaXen\n\nChromaXen is a solo puzzle game that uses size-3 Elementary Cellular Automata (ECA) rules on an 8x8 grid. Your goal is to match each row’s final column color to a target. Drag and drop rule icons onto rows, then ‘Advance’ to evolve the colors according to the selected rules. Scores are tracked by both time and fewest moves.\n\n![ChromaXen screenshot](chromaxen_screenshot.png \"ChromaXen screenshot\")\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [How to Play \u0026 Cellular Automata Explanation](#how-to-play--cellular-automata-explanation)\n3. [Features](#features)\n4. [Tech Stack](#tech-stack)\n5. [Directory Structure](#directory-structure)\n6. [Local Development](#local-development)\n   - [Prerequisites](#prerequisites)\n   - [Running the App Locally via Docker Compose](#running-the-app-locally-via-docker-compose)\n7. [Testing \u0026 Coverage](#testing--coverage)\n   - [Frontend Tests](#frontend-tests)\n   - [Backend Tests](#backend-tests)\n   - [Coverage](#coverage)\n8. [Infrastructure and Deployment](#infrastructure-and-deployment)\n   - [Terraform for AWS](#terraform-for-aws)\n   - [Dockerfiles](#dockerfiles)\n   - [Environment Variables](#environment-variables)\n9. [Contributing](#contributing)\n10. [License](#license)\n11. [Contact](#contact)\n\n---\n\n## Overview\n\nWithin this repository:\n\n- **Frontend**: A Vite-driven application (using ES6 JavaScript, HTML, and CSS) for the puzzle UI.\n- **Backend**: A FastAPI-based REST service for storing and retrieving high scores in a DynamoDB table.\n- **Infrastructure**: Terraform configurations for deploying the application on AWS, using services including S3, Lambda, DynamoDB, and API Gateway. Dockerfiles and Docker Compose are provided for local development or production.\n\n---\n\n## How to Play \u0026 Cellular Automata Explanation\n\nBelow is a detailed overview of how **Elementary Cellular Automata (ECA)** are used in ChromaXen and the basic gameplay mechanics:\n\n### Game Setup\n\n- **Board**: An 8x8 grid.\n- **Starting Pieces**: 8 randomly chosen colours (excluding black and grey) placed in column 1.\n- **Target Pieces**: 8 randomly chosen colours (including black and grey) placed in column 8.\n- **ECA Rules**: Each row has an assigned Elementary Cellular Automaton rule, displayed as a graphical icon next to column 1.\n\n### ECA Icons\n\n- Each icon shows the transition diagram for one of the [256 possible ECA rules](https://chromaxen.com/all_rules.htm).\n- An arrow icon indicates how the colour evolves on the next step (e.g., green → yellow → red).\n- A single coloured dot without an arrow indicates the colour is “frozen” for subsequent steps.\n- If an arrow points to a black or grey dot, that colour will freeze and never revert on future steps.\n\n### Gameplay\n\n1. **Colour Evolution**  \n   Each column (after the first) is determined by applying the ECA rules to the previous column.\n2. **Player Interaction**\n   - On your turn, you **select** an ECA rule icon from the left of column 1.\n   - You then **apply** this selected rule to a chosen row.\n   - The game updates the colours in that row based on the newly applied rule.\n3. **Anticipation**  \n   You must predict how each row will evolve after repeated applications of these rules, ensuring column 7 correctly transitions into column 8’s target colours.\n4. **Winning Condition**  \n   You win when the colours in column 7 will exactly match the target colours in column 8 upon the next step.\n\n### ChromaXen and 1-D Cellular Automata\n\n- **Rule-Based Transformation**: Each row follows a unique ECA rule (from 0 to 255), dictating how colours evolve from one column to the next.\n- **Colour as State**: Each coloured circle represents a cell’s current state.\n- **Local Interaction**: The colour of a circle in column _n_ depends only on its colour in column _n-1_, governed by that row’s ECA rule. Rows do not interact with each other.\n- **Deterministic Evolution**: Given starting colours and ECA rules, the sequence of colour transformations is deterministic (no randomness beyond the initial seed).\n\n### ECA Binary State to Colour Map\n\nHere is the binary-to-colour mapping used in ChromaXen:\n\n```plaintext\n000 -\u003e grey\n001 -\u003e red\n010 -\u003e orange\n011 -\u003e yellow\n100 -\u003e green\n101 -\u003e blue\n110 -\u003e purple\n111 -\u003e black\n```\n\n---\n\n## Features\n\n- **Interactive Puzzle Board**: Drag-and-drop or click-based colour transitions on an 8x8 grid.\n- **Multiple Levels \u0026 Presets**: Each level has distinct ECA rules, automatically loaded from an XML or JSON file.\n- **High Score Tracking**: A scoreboard that tracks top players (moves/time) in DynamoDB.\n- **Save/Load Game**: Export and import partial or completed game states.\n- **Randomization**: Quickly load random puzzle configurations and rules.\n- **Extensive Test Suite**: Currently ~80% coverage on the frontend, including unit tests for core modules.\n- **Dockerized Development**: Both frontend and backend can be spun up using Docker Compose.\n- **AWS-Ready Deployment**: Terraform resources to provision S3, CloudFront, DynamoDB, API Gateway, and more.\n\n---\n\n## Tech Stack\n\n- **Frontend**:\n\n  - [Vite](https://vitejs.dev/)\n  - [Node.js 18 (Alpine)](https://hub.docker.com/_/node)\n  - [Vitest](https://vitest.dev/) for testing\n\n- **Backend**:\n\n  - [Python 3.9](https://www.python.org/)\n  - [FastAPI](https://fastapi.tiangolo.com/)\n  - [Pytest](https://docs.pytest.org/) + [moto](https://github.com/spulec/moto) for DynamoDB mocking\n\n- **Infrastructure**:\n  - [Docker](https://docs.docker.com/) \u0026 [Docker Compose](https://docs.docker.com/compose/)\n  - [Terraform](https://www.terraform.io/) for AWS infrastructure provisioning\n  - [AWS Cloud Services](https://aws.amazon.com/) (CloudFront, S3, Route53, DynamoDB, API Gateway, Lambda)\n\n---\n\n## Directory Structure\n\nBelow is a high-level view of the repository structure (omitting `node_modules/` and large image directories):\n\n```plaintext\n├── backend/\n│   ├── tests/\n│   │   └── test_main.py # Pytest-based backend tests\n│   ├── main.py          # FastAPI entrypoint\n│   └── requirements.txt # Python dependencies for production\n├── frontend/\n│   ├── css/             # CSS stylesheets\n│   ├── jscript/\n│   │   ├── tests/       # Vitest-based frontend tests\n│   │   ├── main.js      # Entry point for the frontend\n│   │   ├── gameUI.js\n│   │   ├── gamelogic.js\n│   │   ├── ...          # Additional JS modules\n│   ├── index.html       # Main HTML file\n│   ├── package.json\n│   ├── package-lock.json\n│   ├── Dockerfile       # Frontend Dockerfile\n│   └── vitest.config.js # Vitest configuration\n├── coverage/            # Coverage output (frontend)\n├── docker-compose.yml   # Docker Compose for local dev\n├── Dockerfile.test      # Dockerfile for testing\n├── env.example.json     # Example environment file\n├── main.tf              # Terraform configuration\n├── requirements-test.txt # Python dependencies for test environment\n└── README.md            # This file\n```\n\n---\n\n## Local Development\n\n### Prerequisites\n\n- [Node.js 18+](https://nodejs.org/)\n- [Docker](https://docs.docker.com/get-docker/) \u0026 [Docker Compose](https://docs.docker.com/compose/)\n- [Terraform](https://developer.hashicorp.com/terraform/downloads) (optional if you want to deploy to AWS)\n- [Python 3.9+](https://www.python.org/) (if you want to use the high score functionality and run the backend tests)\n\n### Running the App Locally via Docker Compose\n\nThe **frontend** and **backend** are intended to run via Docker Compose. This also spins up a local DynamoDB instance for testing.\n\n```bash\ndocker-compose up --build\n```\n\n---\n\n- **Frontend** is served at [http://localhost:5173](http://localhost:5173).\n- **Backend** (FastAPI) is served at [http://localhost:8000](http://localhost:8000).\n- **DynamoDB** Local is available at [http://localhost:8001](http://localhost:8001).\n\n**Note**: The backend is **only** supported via Docker Compose in this project. If you need a custom setup, adapt the Docker configuration or coordinate with the existing `Dockerfile.dev`.\n\n---\n\n## Testing \u0026 Coverage\n\n### Frontend Tests\n\n- Uses [Vitest](https://vitest.dev/) with `jsdom` environment.\n- To run frontend tests:\n\n```bash\ncd frontend\nnpm install\nnpm run test\n```\n\n- Coverage reports are generated in the `frontend/coverage/` directory (HTML, LCOV, and text).\n\n### Backend Tests\n\n- Uses `pytest` + [moto](https://github.com/spulec/moto) to mock DynamoDB.\n- Run backend tests via Docker Compose (service: `test`):\n\n```bash\ndocker-compose run test\n```\n\n### Coverage\n\n- **Frontend**: Currently at **80%** test coverage.\n- **Backend**: Additional test coverage can be integrated via Pytest plugins. The existing tests focus on DynamoDB CRUD operations.\n\n---\n\n## Infrastructure and Deployment\n\n### Terraform for AWS\n\nThis repository includes Terraform configurations (`main.tf` and related files) for deploying:\n\n- **S3** for hosting the frontend,\n- **CloudFront** for CDN distribution,\n- **Route53** for DNS records,\n- **DynamoDB** for high scores,\n- **API Gateway** + **Lambda** for the backend.\n\n**Steps to Deploy**:\n\n1. **Configure AWS credentials** via `aws configure` or environment variables.\n2. **Initialize Terraform**:\n\n```bash\nterraform init\n```\n\n3. **Review Plan**:\n\n```bash\nterraform plan\n```\n\n4. **Apply**:\n\n```bash\nterraform apply\n```\n\nThis creates/updates the necessary AWS resources.\n\n---\n\n## Contributing\n\nContributions are welcome! If you’d like to improve ChromaXen or fix issues:\n\n1. **Fork** this repository.\n2. **Create** a new branch: `git checkout -b feature/my-feature`.\n3. **Commit** your changes: `git commit -m 'Add new feature'`.\n4. **Push** to your branch: `git push origin feature/my-feature`.\n5. **Open** a Pull Request describing your changes.\n\n---\n\n## License\n\nChromaXen is distributed under the [GNU General Public License 3.0](https://www.gnu.org/licenses/gpl-3.0.en.html#license-text).\n\n---\n\n## Contact\n\n- **Email**: [info@chromaxen.com](mailto:info@chromaxen.com)\n- **Primary Authors**:\n  - Gary Bourgeois (Game concept \u0026 design)\n  - Otis Runnings (Graphic Design, Programming)\n  - Bryne Carruthers (Programming, Github Repository Maintainer)\n  - Chris Rolfe (Programming)\n\nIf you encounter any issues or have questions, feel free to open an issue on GitHub or reach out via email.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrcbeatz%2Fchromaxen-dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrcbeatz%2Fchromaxen-dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrcbeatz%2Fchromaxen-dev/lists"}