Cool Cacti

cool-cacti/.github/workflows/lint.yaml

@@ -0,0 +1,35 @@
+# GitHub Action workflow enforcing our code style.
+
+name: Lint
+
+# Trigger the workflow on both push (to the main repository, on the main branch)
+# and pull requests (against the main repository, but from any repo, from any branch).
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+# Brand new concurrency setting! This ensures that not more than one run can be triggered for the same commit.
+# It is useful for pull requests coming from the main repository since both triggers will match.
+concurrency: lint-${{ github.sha }}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    env:
+      # The Python version your project uses. Feel free to change this if required.
+      PYTHON_VERSION: "3.12"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ env.PYTHON_VERSION }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Run pre-commit hooks
+        uses: pre-commit/action@v3.0.1

cool-cacti/.gitignore

@@ -0,0 +1,39 @@
+horizons_data/*
+!horizons_data/template.json
+!horizons_data/planets.json
+
+# Files generated by the interpreter
+__pycache__/
+*.py[cod]
+
+# Environment specific
+.venv
+venv
+.env
+env
+
+# Unittest reports
+.coverage*
+
+# Logs
+*.log
+
+# PyEnv version selector
+.python-version
+
+# Built objects
+*.so
+dist/
+build/
+
+# IDEs
+# PyCharm
+.idea/
+# VSCode
+.vscode/
+.VSCodeCounter/
+# MacOS
+.DS_Store
+
+# Ruff check
+.ruff_cache/

cool-cacti/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+# Pre-commit configuration.
+# See https://github.com/python-discord/code-jam-template/tree/main#pre-commit-run-linting-before-committing
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.2
+    hooks:
+      - id: ruff-check
+        args: [ --fix ]
+      - id: ruff-format

cool-cacti/ATTRIBUTIONS.txt

@@ -0,0 +1,30 @@
+Music: "25 oh 20 and to the stars", "something about space", "death screen clip"
+Composed and created by Elemeno Peter https://kimeklover.newgrounds.com/ 
+Licensed under CC BY-NC-SA
+
+Planet sprites generated with Pixel Planet Generator by Deep Fold 
+https://deep-fold.itch.io/pixel-planet-generator
+Software licensed under the MIT License
+
+Explosion sprites by LinkNinja
+https://linkninja.itch.io/simple-explosion-animation
+Licensed under CC-0
+
+Recycle items art by Clint Bellanger 
+https://opengameart.org/content/recycle-items-set
+Licensed under CC-BY 3.0
+
+QR Code Scanner
+https://www.hiclipart.com/free-transparent-background-png-clipart-pjnbg
+HiClipart is an open community for users to share PNG images, all PNG cliparts in HiClipart are for Non-Commercial Use
+
+3 Explosion Bangs Copyright 2012 Iwan 'qubodup' Gabovitch <http://qubodup.net>
+https://opengameart.org/content/3-background-crash-explosion-bang-sounds
+Licensed under CC-BY 3.0
+
+Rock breaking sound 
+https://opengameart.org/content/rockbreaking
+Licensed under CC-BY 3.0
+
+Scan sound from https://www.zapsplat.com
+Use with attribution

cool-cacti/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2021 Python Discord
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

cool-cacti/README.md

@@ -0,0 +1,132 @@
+# Planet Scanners: Python Discord Code Jam 2025
+
+We created a simple sprite-based, space-themed game using PyScript backed by Pyodide and its JavaScript wrapper
+capabilities to leverage JavaScript's convenient API for rendering graphics on HTML canvas elements, playing
+audio, and accessing user input. We hope this can demo as an alternative to the use of a pygame wrapper such as
+pygbag, without the need for its extra layer of abstraction, as the browser-side execution of our game doesn't use anything
+but the Python standard library and the PyScript and Pyodide modules for accessing JavaScript functionality.
+
+### The Game
+
+The introduction depicts aliens flying around space past the speed of light, about to turn on their super
+advanced intergalactic planet scanner. Today, it fails! Luckily, one of the aliens has an old Earth-based
+barcode scanner - the "wrong tool for the
+job" - that will have to do today. In the solar system overview screen, seen below, the player can select each of the solar system's planets in turn and must complete
+a scan for that planet to complete a mission.
+
+![Planet selection screen](/readme_images/game1.png)
+
+The gameplay (shown in the image below) is a variation of the classic asteroids game, where
+the player must dodge incoming asteroids to avoid ship damage and stay immobile while holding down the Spacebar
+to progress scanning.
+An animated rotating planet combined with the movement of stars off-screen in the opposite direction creates a
+simple but effective perspective of the player ship orbiting a planet.
+
+![Planet selection screen](/readme_images/game2.png)
+
+![Planet selection screen](/readme_images/game3.png)
+
+## Intended Event Frameworks
+
+We used PyScript backed by the Pyodide interpreter. We were pleasantly surprised by how few PyScript-specific
+oddities we ran into. Using the provided JavaScript wrapper capabilities felt almost as natural as writing
+JavaScript directly into the Python files, except writing in Python! To serve our single-page game app, we
+included an ultra-minimalistic Flask backend for convenience in designing, though with a little refactoring our page could
+also be served statically. There is some very minimalistic HTML and CSS to more or less create an HTML canvas to
+draw on with the appropriate styling and create the initial setup for importing our in-browser Python scripts.
+It was necessary to provide the contents of a [PyScript.json](/static/PyScript.json) file to the config attribute of the <py-script> tag
+of our [index.html](/templates/index.html) to let the PyScript environment allow the proper imports of modules
+into one another.
+
+One of the few things that adds a bit of awkwardness is needing to wrap function references passed to to JS callbacks by
+using `create_proxy`, instead of passing a reference to the `game_loop` function directly:
+```py
+from Pyodide.ffi import create_proxy
+
+def game_loop(timestamp: float) -> None:
+  ...
+
+game_loop_proxy = create_proxy(game_loop)
+window.requestAnimationFrame(game_loop_proxy)
+```
+
+On the other hand, "writing JavaScript" in Python can feel very elegant sometimes. A CanvasRenderingContext2D's
+drawing methods for
+example often take a lot of arguments to define the coordinates of objects being draw. There's heavy use of
+rectangular bounds given as four parameters: left, top, width, height. Defining a Python Rect class implementing
+the iterator protocol...
+
+```py
+@dataclass
+class Rect:
+    left: float
+    top: float
+    width: float
+    height: float
+
+    def __iter__(self) -> Iterator[float]:
+        yield self.left
+        yield self.top
+        yield self.width
+        yield self.height
+```
+
+...allows for some drawing calls to be very succinct with unpacking:
+
+```py
+# sprite_coords = Rect(0, 0, sprite_width, sprite_height)
+# dest_coords = Rect(dest_left, dest_top, dest_width, dest_height)
+ctx.fillRect(*dest_coords)
+ctx.drawImage(sprite_image, *sprite_coords, *dest_coords)
+```
+
+## Installation and Usage
+
+### Prerequisites to Run
+- Python 3.12
+- [uv](https://github.com/astral-sh/uv) is recommended for the package manager
+- An active internet connection (to fetch the Pyodide interpreter and PyScript modules from the PyScript CDN)
+### Installation
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/fluffy-marmot/codejam2025
+   ```
+
+2. Install dependencies using uv:
+   ```bash
+   uv sync
+   ```
+### Without uv
+The dependencies are listed in [`pyproject.toml`](pyproject.toml). Since the only server-side dependency for running the
+project is flask (PyScript is obtained automatically in browser as needed via CDN), the
+project can be run after cloning it by simply using
+```bash
+pip install flask
+python app.py
+```
+### Running the Game
+Running the [app.py](/app.py) file starts the simple flask server to serve the single html page, which should be at
+[http://127.0.0.1:5000](http://127.0.0.1:5000) if testing it locally. We also have a version of our game hosted
+at [https://caius.pythonanywhere.com/codejam/](https://caius.pythonanywhere.com/codejam/) although this has been
+slightly modified from the current repository to run as a single app within an already existing Django project.
+None of the files in the `/static/` directory of the hosted version have been modified, therefore in-browser functionality
+should be the same.
+
+## Individual Contributions
+
+RealisticTurtle: storyboarding, intro scene and story, game scene, star system, scanning mechanics
+
+Soosh: library research, core functionality (audio and input modules, gameloop, scene system), code integration, debris
+system
+
+Dark Zero: planet selection scene, sprites, spritesheet helper scripts, player mechanics, asteroid
+implementation, collision logic, end scene
+
+Doomy: dynamic textboxes, end scene and credits, Horizons API functionality,
+refactoring and maintenance, scanner refinement, experimented with Marimo
+
+## Game Demonstration
+
+This video is a quick demonstration of our game and its mechanics by our teammate RealisticTurtle
+
+View the demo on [Youtube](https://www.youtube.com/watch?v=J8LKGUsTeAo)

cool-cacti/app.py

@@ -0,0 +1,46 @@
+import json
+from pathlib import Path
+
+from flask import Flask, render_template
+
+""" 
+using a flask backend to serve a very simple html file containing a canvas that we draw on using
+very various pyscript scripts. We can send the planets_info variable along with the render_template
+request so that it will be accessible in the index.html template and afterwards the pyscript scripts
+"""
+app = Flask(__name__)
+
+base_dir = Path(__file__).resolve().parent
+static_dir = base_dir / "static"
+sprite_dir = static_dir / "sprites"
+audio_dir = static_dir / "audio"
+
+# contains various information and game data about planets
+with Path.open(base_dir / "horizons_data" / "planets.json", encoding='utf-8') as f:
+    planets_info = json.load(f)
+
+# create a list of available sprite files
+sprite_list = [sprite_file.stem for sprite_file in sprite_dir.iterdir() if sprite_file.is_file()]
+
+# create a list of available audio files
+audio_list = [audio_file.name for audio_file in audio_dir.iterdir()]
+
+with Path.open(static_dir / "lore.txt") as f:
+    lore = f.read()
+
+with Path.open(static_dir / "credits.txt") as f:
+    credits = f.read()
+
+@app.route("/")
+def index():
+    return render_template(
+        "index.html", 
+        planets_info=planets_info, 
+        sprite_list=sprite_list, 
+        audio_list=audio_list,
+        lore=lore,
+        credits=credits
+    )
+
+if __name__ == "__main__":
+    app.run(debug=True)