| Name | pyriak JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | None |
| Summary | A lightweight implementation of Entity Component System architecture |
| upload_time | 2024-09-05 01:02:07 |
| maintainer | None |
| docs_url | None |
| author | aatle |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
ecs
framework
architecture
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pyriak
[](https://pypi.org/project/pyriak)
[](https://pypi.org/project/pyriak)
[](https://github.com/python/mypy)
[](https://github.com/astral-sh/ruff)
Pyriak is a lightweight Python implementation of Entity Component System (ECS) architecture.
ECS is an alternative paradigm to object-oriented programming,
emphasizing composition and data oriented design.
This can help with structuring complex programs, especially in game development.
## Installation
```
pip install pyriak
```
## ECS implementation
There are many different styles of ECS depending on its goals.
This implementation focuses on development speed, ease of use, and architecture,
rather than performance, aligning with the principles of python.
- Entities are concrete component containers that have an ID.
- Components can be any object, and do not reference their entity.
- Systems are collections of event handlers, and are typically
implemented as modules with functions.
- Event handlers are the main control flow, invoked by processing events.
- Events can be any object, and are put in the event queue
or processed immediately.
- All resources are added to managers, and these managers are joined
together with a Space object.
- For convenience, there is an entity-like manager that contains states,
which are essentially global or singleton components.
## Usage
In your main file, create a `Space` instance. It will encapsulate the majority of the program. With no arguments, the managers are created automatically.\
The three managers are `space.systems`, `space.entities`, and `space.states`. The `Space` also has an event queue object, `space.event_queue`.
```python
# main.py
from pyriak import Space
space = Space()
```
The raw data is stored as components, states, and events. For these objects, define small classes with miminal functionality/code, comparable to structs in other languages.\
`dataclasses` and similar packages or modules are especially convenient for writing these.
```python
@dataclass
class Health:
max_value: float
value: float = 0.0
```
Entities hold the components, and can be created with the entity manager's `create()` method, or manually with the constructor (must be added to the manager).\
It is not a good idea to hold direct entity references within components or states. Each entity has a unique `.id` attribute that should be used as a stored reference instead.
```python
enemy = Entity([Health(50.0)])
space.entities.add(enemy)
player = space.entities.create(Health(100.0))
enemy.add(Target(player.id))
```
Components and states can be accessed through their owner with square bracket (subscript) notation, with the class of the component or state, like a mapping.
For entities, their id is used.
```python
enemy[Health].value -= 20.5
total_seconds = space.states[Time].elapsed
del entity[Sprite]
del space.entities[enemy.id]
```
Systems, which hold the logic and behavior, are most often implemented as module objects with functions (the module itself is the system).\
When an event is processed, the relevant event handlers of the space are called automatically. In a system module, import the `bind()` decorator from pyriak. Define a module-level function as an event handler callback and decorate it with a call to `bind()`, with the arguments being the event type (class object) and handler priority.
The callback takes arguments `space` and `event`. (The name of the function is not used.)
```python
# game_loop.py
@bind(InitializeGame, 100)
def run(space: Space, event: InitializeGame):
pass
```
Most event handlers should not return anything (return None).\
The handler priority is any object that can be compared, such as an `int` instance. The priority determines the order in which handlers for the same event type are invoked, with higher priority handlers being first.
The space processes events in two main ways:
- Call `space.process(event)`, with the event as argument. This calls the event handlers immediately, so the program will not resume until the handlers are done.
- Put the event in the space's event queue, usually with `space.post(event)`. Then, take and process events from the queue with `space.pump()`.
- `space.pump()`, with no arguments, consumes events from the queue until it is empty. Note that more events may be posted during it.
Which method to use depends on if behavior needs to execute immediately (synchronous), or can be deferred (asynchronous).
```python
# game_loop.py
@bind(InitializeGame, 100)
def run(space: Space, event: InitializeGame):
while not space.states[GameLoop].stop_game:
space.post(UpdateGame(dt))
space.pump()
space.post(RenderGame())
space.pump()
```
For the handlers of a system to work, the system **must** be added to the space's `SystemManager`.
Forgetting to add a new system after writing it is a common mistake.\
Import the system module and add it to `space.systems`.
```python
# main.py
from systems import game_loop
...
space.systems.add(game_loop)
```
Systems may optionally define callbacks `_added_()` and `_removed_()` that are invoked when the system is added to or removed from a `SystemManager`.\
The return value is ignored.
```python
# game_loop.py
def _added_(space: Space):
space.states.add(states.GameLoop(FPS))
```
In ECS, systems need to access components in bulk. This can be done with the `space.query()` method, which takes any number of component types as arguments.
The return value is an object with methods to access the data, such as `.zip()`.
```python
@bind(events.UpdateGame)
def update_physics(space: Space, event: events.UpdateGame)
for position, velocity, acceleration in space.query(
components.Position, components.Velocity, components.Acceleration
).zip():
velocity += acceleration
position += velocity
```
Those are all of the basic features needed to write a program with pyriak.
## When to use pyriak?
This package is only intended for complex, interconnected programs, especially games, which could benefit from events and data/logic separation.
Since pyriak is written in python, it does not offer any performance benefits over other paradigms.
For small programs with not many moving parts, ECS is overkill and can be slower to write.
## Installing from source
Pyriak has no package dependencies, and its source is entirely python.
The source can be installed and used, without any building or set-up.
```
pip install -U git+https://github.com/aatle/pyriak.git
```
## Help
Currently, all available resources are in the [pyriak GitHub repo](https://github.com/aatle/pyriak).
Create an issue if there are any concerns or problems.\
There is no external documentation; see docstrings for information.
In the future, an example program may be available.
Raw data
{
"_id": null,
"home_page": null,
"name": "pyriak",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ecs, framework, architecture",
"author": "aatle",
"author_email": "168398276+aatle@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/88/55/effe9e819073f79247bd1326c8b846df40d689fc5b6fad825057d43e2ce9/pyriak-0.4.1.tar.gz",
"platform": null,
"description": "# pyriak\n\n[](https://pypi.org/project/pyriak)\n[](https://pypi.org/project/pyriak)\n[](https://github.com/python/mypy)\n[](https://github.com/astral-sh/ruff)\n\nPyriak is a lightweight Python implementation of Entity Component System (ECS) architecture.\n\nECS is an alternative paradigm to object-oriented programming,\nemphasizing composition and data oriented design.\nThis can help with structuring complex programs, especially in game development.\n\n\n## Installation\n```\npip install pyriak\n```\n\n\n## ECS implementation\nThere are many different styles of ECS depending on its goals.\n\nThis implementation focuses on development speed, ease of use, and architecture,\nrather than performance, aligning with the principles of python.\n\n- Entities are concrete component containers that have an ID.\n - Components can be any object, and do not reference their entity.\n- Systems are collections of event handlers, and are typically\n implemented as modules with functions.\n- Event handlers are the main control flow, invoked by processing events.\n - Events can be any object, and are put in the event queue\n or processed immediately.\n- All resources are added to managers, and these managers are joined\n together with a Space object.\n- For convenience, there is an entity-like manager that contains states,\n which are essentially global or singleton components.\n\n\n## Usage\nIn your main file, create a `Space` instance. It will encapsulate the majority of the program. With no arguments, the managers are created automatically.\\\nThe three managers are `space.systems`, `space.entities`, and `space.states`. The `Space` also has an event queue object, `space.event_queue`.\n```python\n# main.py\nfrom pyriak import Space\n\nspace = Space()\n```\n\nThe raw data is stored as components, states, and events. For these objects, define small classes with miminal functionality/code, comparable to structs in other languages.\\\n`dataclasses` and similar packages or modules are especially convenient for writing these.\n```python\n@dataclass\nclass Health:\n max_value: float\n value: float = 0.0\n```\nEntities hold the components, and can be created with the entity manager's `create()` method, or manually with the constructor (must be added to the manager).\\\nIt is not a good idea to hold direct entity references within components or states. Each entity has a unique `.id` attribute that should be used as a stored reference instead.\n```python\nenemy = Entity([Health(50.0)])\nspace.entities.add(enemy)\n\nplayer = space.entities.create(Health(100.0))\nenemy.add(Target(player.id))\n```\n\nComponents and states can be accessed through their owner with square bracket (subscript) notation, with the class of the component or state, like a mapping.\nFor entities, their id is used.\n```python\nenemy[Health].value -= 20.5\ntotal_seconds = space.states[Time].elapsed\ndel entity[Sprite]\ndel space.entities[enemy.id]\n```\n\nSystems, which hold the logic and behavior, are most often implemented as module objects with functions (the module itself is the system).\\\nWhen an event is processed, the relevant event handlers of the space are called automatically. In a system module, import the `bind()` decorator from pyriak. Define a module-level function as an event handler callback and decorate it with a call to `bind()`, with the arguments being the event type (class object) and handler priority.\nThe callback takes arguments `space` and `event`. (The name of the function is not used.)\n```python\n# game_loop.py\n@bind(InitializeGame, 100)\ndef run(space: Space, event: InitializeGame):\n pass\n```\nMost event handlers should not return anything (return None).\\\nThe handler priority is any object that can be compared, such as an `int` instance. The priority determines the order in which handlers for the same event type are invoked, with higher priority handlers being first.\n\nThe space processes events in two main ways:\n- Call `space.process(event)`, with the event as argument. This calls the event handlers immediately, so the program will not resume until the handlers are done.\n- Put the event in the space's event queue, usually with `space.post(event)`. Then, take and process events from the queue with `space.pump()`.\n - `space.pump()`, with no arguments, consumes events from the queue until it is empty. Note that more events may be posted during it.\nWhich method to use depends on if behavior needs to execute immediately (synchronous), or can be deferred (asynchronous).\n```python\n# game_loop.py\n@bind(InitializeGame, 100)\ndef run(space: Space, event: InitializeGame):\n while not space.states[GameLoop].stop_game:\n space.post(UpdateGame(dt))\n space.pump()\n space.post(RenderGame())\n space.pump()\n```\n\nFor the handlers of a system to work, the system **must** be added to the space's `SystemManager`.\nForgetting to add a new system after writing it is a common mistake.\\\nImport the system module and add it to `space.systems`.\n```python\n# main.py\nfrom systems import game_loop\n...\nspace.systems.add(game_loop)\n```\n\nSystems may optionally define callbacks `_added_()` and `_removed_()` that are invoked when the system is added to or removed from a `SystemManager`.\\\nThe return value is ignored.\n```python\n# game_loop.py\ndef _added_(space: Space):\n space.states.add(states.GameLoop(FPS))\n```\n\nIn ECS, systems need to access components in bulk. This can be done with the `space.query()` method, which takes any number of component types as arguments.\nThe return value is an object with methods to access the data, such as `.zip()`.\n```python\n@bind(events.UpdateGame)\ndef update_physics(space: Space, event: events.UpdateGame)\n for position, velocity, acceleration in space.query(\n components.Position, components.Velocity, components.Acceleration\n ).zip():\n velocity += acceleration\n position += velocity\n```\n\nThose are all of the basic features needed to write a program with pyriak.\n\n\n## When to use pyriak?\nThis package is only intended for complex, interconnected programs, especially games, which could benefit from events and data/logic separation.\nSince pyriak is written in python, it does not offer any performance benefits over other paradigms.\nFor small programs with not many moving parts, ECS is overkill and can be slower to write.\n\n\n## Installing from source\nPyriak has no package dependencies, and its source is entirely python.\nThe source can be installed and used, without any building or set-up.\n```\npip install -U git+https://github.com/aatle/pyriak.git\n```\n\n\n## Help\nCurrently, all available resources are in the [pyriak GitHub repo](https://github.com/aatle/pyriak).\nCreate an issue if there are any concerns or problems.\\\nThere is no external documentation; see docstrings for information.\nIn the future, an example program may be available.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight implementation of Entity Component System architecture",
"version": "0.4.1",
"project_urls": {
"Issues": "https://github.com/aatle/pyriak/issues",
"Repository": "https://github.com/aatle/pyriak.git"
},
"split_keywords": [
"ecs",
" framework",
" architecture"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f1bf24653f0334b91cf590afb73e9d2a3e09d2ae1c066ca292bae2a8b36f4478",
"md5": "e2627e8e9ee0962ae7f809ab51e4305d",
"sha256": "3ead436fd3c9ddcbae5b49a77a21b69edc79fbb0563c89e842462d27794b30b2"
},
"downloads": -1,
"filename": "pyriak-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2627e8e9ee0962ae7f809ab51e4305d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 27996,
"upload_time": "2024-09-05T01:02:06",
"upload_time_iso_8601": "2024-09-05T01:02:06.045239Z",
"url": "https://files.pythonhosted.org/packages/f1/bf/24653f0334b91cf590afb73e9d2a3e09d2ae1c066ca292bae2a8b36f4478/pyriak-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8855effe9e819073f79247bd1326c8b846df40d689fc5b6fad825057d43e2ce9",
"md5": "0cd4d89481ffda2fcd254ec2dec66513",
"sha256": "208152493b3e988ddfa764ef2df0613af031d723f2af90326b1af7c21a05439b"
},
"downloads": -1,
"filename": "pyriak-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "0cd4d89481ffda2fcd254ec2dec66513",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 25123,
"upload_time": "2024-09-05T01:02:07",
"upload_time_iso_8601": "2024-09-05T01:02:07.420890Z",
"url": "https://files.pythonhosted.org/packages/88/55/effe9e819073f79247bd1326c8b846df40d689fc5b6fad825057d43e2ce9/pyriak-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-05 01:02:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aatle",
"github_project": "pyriak",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyriak"
}
