Metadata-Version: 2.4
Name: mlxgame
Version: 0.1.1
Summary: Where MiniLibX meets imagination.
Author-email: Nora de Fitero Teijeira <nora@defitero.com>
License: MIT License
        
        Copyright (c) 2026 Nora de Fitero Teijeira.
        
        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.
        
Project-URL: Homepage, https://github.com/dde-fite/Mlx_Python_Engine
Project-URL: Bug Reports, https://github.com/dde-fite/Mlx_Python_Engine/issues
Keywords: minilibx,mlx,42,42madrid,game-engine,graphics-engine,scene-graph,ecs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Education
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python==4.13.0.92
Requires-Dist: typing_extensions==4.15.0
Dynamic: license-file

<p align="center">
    <img align="center" src="media/mlx_python_game_engine.jpg">
    <h1 align="center">Mlx Python Game Engine</h1>
</p>

<p align="center">
	<img alt="Pypi version Badge" src="https://img.shields.io/pypi/v/mlxgame">
    <img alt="License Badge" src="https://img.shields.io/github/license/dde-fite/42_a_maze_ing">
    <img alt="42 Network Badge" src="https://img.shields.io/badge/42%20Network-000000?&logo=42&logoColor=white">
</p>

Mlx Python Game Engine is a Python library for **developing video games** or **graphic applications** with the MiniLibx from 42. The idea behind this project is to achieve an experience similar to other popular graphics engines such as **Unity or Godot**.

Although the original idea behind Mlx was to make graphics development difficult to learn, this library shifts the focus of learning towards the use of tools used in the industry, **making the learning experience more useful**.


<div align="center">
    <img alt="Where MiniLibX meets imagination." src="media/example_of_nodes.jpg">
    <img alt="Like Unity but for 42." src="media/example_of_components.jpg">
</div>


## Overview
Using the ECS (Entity-Component-System) pattern, we can see the different elements that make up any game created with the Mlx Python Game Engine: **Scenes**, **Nodes**, and **Components**.

**Scenes** are like the levels or screens of any game; they can be a main menu, each level, and credits. They are composed of **Nodes**, which represent any visible or invisible object we see, such as a character, the background, a button, etc. But nodes by themselves do nothing; they are not even visible.

In order for them to be visible or do things, we have **Components**, which are what execute the logic. You can create your own components or use native ones, such as `SpriteRenderer`, which allows the node to have an image, or Input, which allows you to collect keyboard or mouse events from another component, such as pressing the W key.

![Mind map of the architecture](media/architecture.jpg)

## Features

### ECS (Entity-Component-System)

-   **Scenes**

    Simple node containers. You only need to inherit from BaseScene and call `super().__init__` with a list of nodes.

    The Z-index of the nodes is set in ascending order. The lower down the list, the further forward, and the higher up, the further back.

-   **Nodes**

    Each object in the game. They have their own name, position, subnodes, and component instances.

    They inherit from BaseNode and are initialized by calling the parent's init with name and position.

    Their syntax is very **beautiful and elegant** thanks to the use of magic functions. You can add a component with `self += Component` or access a component with `self[Component]`, even iterate through its components with a `for`.

-   **Components**

    The logic of everything. They are initialized with `on_init()` and have many native events such as `on_update()`, `on_destroy`, `on_deactivate()`, and `on_activate()`.

    They can also access the node to which they belong with `self.owner`.

    *Since components are instantiated dynamically according to the engine's criteria, the use of \_\_init\_\_ is strongly discouraged.*

### Rendering

- **Image Extensions**

    Image loading in Mlx Engine is handled via OpenCV's `imread()`. The supported extensions are:

    **Always supported:**
  | Format                | Extensions           |
  | ----------------------|----------------------|
  | Windows bitmaps       | *.bmp, *.dib         |
  | Portable image format | *.pbm, *.pgm, *.ppm  |

    **Depends on the system codecs, normally no action is required:**
  | Format                | Extensions           |
  | ----------------------|----------------------|
  | PNG                   | *.png                |
  | JPEG files            | *.jpeg, *.jpg, *.jpe |
  | JPEG 2000 files       | *.jp2                |
  | Sun rasters           | *.sr, *.ras          |
  | TIFF files            | *.tiff, *.tif        |

- **Real-time resizing (pending rotation)**

    Each node can manage its own scale, which `SpriteRenderer` will automatically collect to perform the necessary calculations that allow resizing.

- **Own rendering engine.**

    The graphics calculation works completely independently of the MLX. These are done in a buffer powered by Numpy.

    This buffer is a three-dimensional array of [y of the screen] [x of the screen] [the 4 channels of a pixel (RGBA)]. Each frame is reset, and for each node to be drawn, the calculation to draw it is performed.

    When the process is complete, the bytes of the buffer are dumped into the MiniLibX memory region and the command to draw is sent.

    ![Mind map of the architecture](media/frame_render.jpg)

- **Sprite Pooling**
    Since the original MLX is based on C, images need to be freed when not in use. But thanks to Sprite Pooling, they are **freed automatically**, and if several nodes use the same image, the same one is used to avoid reloading it, **optimizing performance**.

    When a `SpriteRenderer` (the native component for rendering images) needs an image, it checks if it is in memory. If it is not there, it is loaded into memory and noted that it is being used by that component. If it already exists, it is not reloaded and only its use is noted. Then, when it is no longer needed, it is noted that the component no longer needs it, and if no one else is using it, it is deleted.

### Input Handling
Input is managed by a manager that centralizes all interruptions. With the native Input component, you can interact with it securely from the node itself. It currently supports keyboard and mouse.

The available events are:
-   `on_press()`: When the key or button is pressed
-   `on_hold()`: When the key or button is held down
-   `on_unpress()`: When the key or button is released.


### Event System
It has a custom event system available to the user.

This works by subscribing functions to an event that can be named as desired, for example “player-dead.” Subsequently, when you want to execute the event using `trigger_event(“player-dead”)`, all functions that are listening will be called.


## Requirements

As the MiniLibX Python wrapper uses the original C library, the following packages are required:

### Arch Linux

``` bash
sudo pacman -S libxcb xcb-util-keysyms zlib libbsd vulkan-icd-loader vulkan-tools shaderc
```

### Debian/Ubuntu

``` bash
sudo apt install libxcb libxcb-keysyms libvulkan libz libbsd glslc
```

It is not necessary to have mlx installed, as the package itself contains a vendor version of it.

## Usage

Install Mlx Python Game Engine from pip.
```bash
pip install mlxgame
```
And import mlx_engine where needed.
```python
from mlxgame import EngineManager

EngineManager.init("Test",
                   (1920, 1080),
                   [Menu])
```

## Making package
```bash
python -m build
```

## Got any suggestions?

If you find any errors or have any new ideas for improving this
repository, feel free to open an Issue or Pull Request, or contact me at
my email address: nora@defitero.com
