# 🛠️ pyforge-engine (Beta v0.2.0)

A blazing-fast, cross-platform 2D game engine framework combining a low-level compiled **C/OpenGL core** with a clean **Python API**. 

Unlike software-rendered libraries like Pygame which process graphics sequentially on individual CPU threads, `pyforge-engine` processes matrix math and coordinate updates directly within hardware-accelerated **GPU layers**, guaranteeing extreme frame rates, fileless in-memory asset streaming, and native 3D spatial audio architectures.

---

## 📖 Global Function Reference Guide

The entire framework operates under a single unified coordination matrix grid, mapping `(0,0)` straight to the top-left viewport boundary corner.

| Function Interface Signature | Execution Subsystem | Operational Responsibility Description |
| :--- | :--- | :--- |
| `pyforge.init(width, height, title)` | `core.c` | Initializes the GLFW graphics hardware context, configures an orthogonal 2D screen viewport grid, and boots up OpenAL audio mixers. |
| `pyforge.shape(sides)` | `core.c` | Pre-calculates relative circular coordinate node layout arrays to generate regular polygon wireframes dynamically on the GPU. |
| `pyforge.load_image(file_path)` | `engine.py` | Decodes image assets using Pillow and transfers raw byte buffers directly to VRAM texture slots completely offline. |
| `pyforge.clear_gradient(top_color, bottom_color)` | `core.c` | Wipes the active graphics pipeline frame backbuffer and paints a vertical linear gradient blend using raw RGB parameters. |
| `pyforge.drawshape(shape, x, y, size, angle, color, opacity, texture)` | `core.c` | Renders a calculated polygon mesh array using GPU hardware matrix scaling, rotation transformations, colors, or texture maps. |
| `pyforge.draw_button(x, y, w, h, bg_color)` | `engine.py` | Renders a bounded, flat flat-color rectangular UI panel box using direct absolute corner quad mesh transformations. |
| `pyforge.load_system_font(font_name, size)` | `engine.py` | Automatically queries host operating system directories (Windows, Mac, Linux) to map, draw, and compress font tiles entirely in memory. |
| `pyforge.draw_text(text, x, y, scale, color)` | `engine.py` | Draws actual string phrases onto active hardware slots by rendering pre-sliced, fileless texture quad maps from the RAM font matrix. |
| `pyforge.get_mouse_pos()` | `core.c` | Polls the native hardware pointer position and returns the absolute cursor location coordinates as an `(x, y)` tuple. |
| `pyforge.is_mouse_pressed(button)` | `core.c` | Queries your system event loop queues to check if the left mouse click button is actively compressed. |
| `pyforge.is_button_clicked(x, y, w, h)` | `engine.py` | Performs real-time bounding box intersection tests to see if a mouse click event matches a specific rectangular coordinate perimeter. |
| `pyforge.is_key_pressed(key_code)` | `core.c` | Polls the active keyboard state directly via GLFW to monitor key interaction triggers instantly. |
| `pyforge.play_sound(file_path)` | `effects.c` | Decodes a short uncompressed local `.wav` sound effect track and shoots it out of an OpenAL hardware audio channel. |
| `pyforge.play_music(file_path, loop)` | `effects.c` | Intercepts `.mp3` or `.wav` music tracks, decodes them filelessly inside RAM using `miniaudio`, and streams them continuously. |
| `pyforge.spawn_particles(x, y, color)` | `effects.c` | Allocates and spawns an explosive burst array of custom physics-tracked pixel explosion particle fragments on the GPU. |
| `pyforge.update_effects()` | `effects.c` | Computes physics velocities and fades out active particle transparency matrices during loop iterations. |
| `pyforge.get_fps()` | `engine.py` | Computes high-precision frame rate diagnostics by tracking system time deltas between active rendering loops. |
| `pyforge.refresh()` | `core.c` | Swaps the backbuffer frame data onto physical desktop monitors to lock drawing cycles tightly with user displays. |
| `pyforge.is_open()` | `core.c` | Tracks the visibility and availability metrics of the active canvas viewport window to control main application loops. |

---

## 🛠️ Feature Verification Test Scripts

Developers can copy and run these compact sandboxed files to instantly test and verify features on their local machine.

### Test 1: Geometry Matrix & Colors (`pyforge.drawshape`)
*Draws a beautiful cluster of spinning polygons showcasing the hardware matrix transform pipelines.*

```python
import pyforge

pyforge.init(1024, 768, "Pyforge Engine - Geometric Cluster Showcase")

# Pre-calculate different polygon relative node configurations
triangle = pyforge.shape(3)
square = pyforge.shape(4)
pentagon = pyforge.shape(5)
circle = pyforge.shape(36)

angle = 0.0

while pyforge.is_open():
    pyforge.clear_gradient((0.02, 0.02, 0.05), (0.08, 0.08, 0.15))
    angle += 1.0

    # Draw a vibrant matrix array of spinning shapes
    pyforge.drawshape(triangle, x=200, y=384, size=80, angle=angle, color=(0.9, 0.2, 0.2))
    pyforge.drawshape(square, x=400, y=384, size=80, angle=-angle * 0.5, color=(1.0, 0.6, 0.1))
    pyforge.drawshape(pentagon, x=600, y=384, size=80, angle=angle * 1.5, color=(0.2, 0.8, 0.4))
    pyforge.drawshape(circle, x=800, y=384, size=80, angle=0.0, color=(0.2, 0.5, 0.9))

    pyforge.refresh()
```
```html

### Test 2: Audio & Explosive Particles (`pyforge.spawn_particles`)
*Plays an active MP3 background track, triggers custom click audio, and spawns multi-colored particle bursts right under your mouse pointer.*

```python
import pyforge
import os

pyforge.init(1024, 768, "Pyforge Engine - Audio-Visual Sandbox")
pyforge.load_system_font("sans-serif", font_size=24)

# Stream background tracking music file (WAV or MP3 handled filelessly in memory!)
if os.path.exists("my_music.mp3"):
    pyforge.play_music("my_music.mp3", loop=True)

# Generate an absolute button perimeter card panel boundary box
btn_x, btn_y, btn_w, btn_h = 412, 350, 200, 60

while pyforge.is_open():
    pyforge.clear_gradient((0.05, 0.02, 0.1), (0.1, 0.05, 0.2))
    mx, my = pyforge.get_mouse_pos()

    # Hover checking bounds interaction test
    if btn_x <= mx <= (btn_x + btn_w) and btn_y <= my <= (btn_y + btn_h):
        btn_color = (0.1, 0.6, 0.3)
        if pyforge.is_button_clicked(btn_x, btn_y, btn_w, btn_h):
            # Play a short audio file effect if available, or trigger particles
            if os.path.exists("point.wav"): pyforge.play_sound("point.wav")
            pyforge.spawn_particles(mx, my, color=(0.4, 0.7, 1.0))
    else:
        btn_color = (0.2, 0.25, 0.3)

    pyforge.draw_button(btn_x, btn_y, btn_w, btn_h, bg_color=btn_color)
    pyforge.draw_text("CLICK ME", x=455, y=365, scale=0.55, color=(1.0, 1.0, 1.0))

    # Always flush and render active particle buffers right before refreshing frames
    pyforge.update_effects()
    pyforge.refresh()
```
```html


---

## 🛠️ Code Maintenance & Offline Environment Sandbox

The project includes an automated automation lifecycle manager utility script via a local workspace **`Makefile`**:

```bash
# Wipes compilation artifact directories and egg-info paths clean
make clean

# Initializes your virtual sandbox environment, updates Pillow, and compiles C extensions
make

# Instantly boots your active test_game.py simulation script frame
make run
```

---

## 🤖 AI Code-Comment Transparency Statement
For complete transparency and absolute alignment with modern engineering standard practices, all granular architectural descriptions and functional code documentation blocks written across the `src/core.c`, `src/text.c`, `src/effects.c`, and `pyforge/engine.py` codebase layout paths **were generated with the assistance of artificial intelligence**. 

These highly dense technical comments were explicitly chosen to provide thorough explanations of the low-level memory translations, buffer byte mappings, and OpenGL/OpenAL hardware pipelines, ensuring maximum developer readability and ease of long-term module maintenance.

---
*pyforge-engine v0.2.0 — Developed by Eli Andrew Tebcherany. Released under the MIT Open Source License.*
