# PECS
[](https://github.com/krummja/PECS/actions/workflows/main.yml) [](https://coveralls.io/github/krummja/PECS?branch=master)
PECS is the ✨Respectably Muscled✨ Python ECS library that aims to provide a powerful, user-friendly, and fast-as-hell framework for game development.
This library is the spiritual successor to my prior ECS library, [ECStremity](https://github.com/krummja/ECStremity). Both this and its predecessor were inspired by the JavaScript ECS library [geotic](https://github.com/ddmills/geotic), created and maintained by [@ddmills](https://github.com/ddmills). I highly recommend checking out that project as well as the excellent resources cited in its README.
What is ECS, you ask? [Check it out](https://medium.com/ingeniouslysimple/entities-components-and-systems-89c31464240d)!
## Installation
Install the package from PyPI using pip:
```
pip install pecs-framework
```
Or grab it directly from this repository:
```
pip install git+https://github.com/krummja/PECS
```
## Usage and Examples
To start flexing your PECS, import the library and set up some components. Components can be built as standard Python classes:
```python
import pecs_framework as pecs
class Position(pecs.Component):
"""Representation of an Entity's position in 2D space."""
def __init__(self, x: int = 0, y: int = 0) -> None:
self.x = x
self.y = y
@property
def xy(self) -> tuple[int, int]:
return self.x, self.y
```
As extensions of existing components:
```py
import pecs_framework as pecs
class Velocity(Position):
"""Representation of an Entity's velocity in 2D space."""
```
Or as dataclasses:
```py
import pecs_framework as pecs
from dataclasses import dataclass, field
@dataclass
class Health(pecs.Component):
"""Representation of an Entity's health."""
maximum: int = 100
current: int = field(init=False)
def __post_init__(self) -> None:
self.current = self.maximum
```
Components can have as much or as little behavior as needed, although it is generally better to keep to a strict single-repsonsibility principle. We can even have components that have no behavior at all, representing boolean flags for queries:
```py
import pecs_framework as pecs
class IsFrozen(pecs.Component):
"""Flag component denoting a frozen entity."""
```
### Queries
The easiest way to build out systems is through world queries. To make a system that tracks and updates the components relevant to movement, we might query for `Position` and `Velocity` components. Because we want our entities to move, we want to exclude those marked with the `IsFrozen` flag. Perhaps we also want to grab only those entities that can fly through `Wings` or swim through `Fins`:
```python
import pecs_framework as pecs
ecs = pecs.Engine()
domain = ecs.create_domain("World")
kinematics = domain.create_query(
all_of = [
Position,
Velocity
],
any_of = [
Wings,
Fins
],
none_of = [
IsFrozen
],
)
```
Queries can specify `all_of`, `any_of`, or `none_of` quantifiers. The query in the example above asks for entities that must have **both** `Position` **and** `Velocity`, may have (inclusive) `Wings` **or** `Fins`, and **must not** have `IsFrozen`.
We can access the result set of the query and do some operation on them every loop cycle:
```py
def process(dt):
for entity in targets.result:
entity[Position].x += entity[Velocity].x * dt
entity[Position].y += entity[Velocity].y * dt
```
For convenience, the library provides barebones system class that you can extend for your own purposes:
```py
import pecs_framework as pecs
class MovementSystem(pecs.BaseSystem):
def initialize(self) -> None:
self.query(
'movable',
all_of = [Position, Velocity],
none_of = [IsFrozen],
)
def update(self) -> None:
movables = self._queries
for entity in movables:
entity[Position].x += entity[Velocity].x
entity[Position].y += entity[Velocity].y
```
> ---
>
> **Warning:**
>
> Do not override the `__init__` method of `BaseSystem` -- use the provided `initialize` method instead.
>
> ---
### Broadcasting Events to Components
Complex interactions within and among entities can be achieved by firing events on an entity. This creates an `EntityEvent` that looks for methods on all of the entity's methods prefixed with `on_`.
```python
zombie.fire_event('attack', {
'target': survivor,
'multiplier': 1.5,
})
```
On the `zombie` entity, we might have attached an `Attacker` component with the following logic:
```python
class Attacker(pecs.Component):
def __init__(self, strength: int) -> None:
self.strength = strength
def on_attack(self, evt: pecs.EntityEvent) -> pecs.EntityEvent:
target: Entity = evt.data.target
target.fire_event('damage_taken', {
'amount': self.strength * evt.data.pultiplier,
})
evt.handle()
return evt
```
When we execute `fire_event` with the event name `attack`, the event system will find all `on_attack` methods on that entity's components. If we want the event propagation to stop at a particular component, we can call `evt.handle()` which will immediately break broadcasting down the component list. This means that we can potentially have any number of components respond to a specific event, although it may generally be safer to fire a secondary event to prevent ordering issues.
Internally, the `EntityEvent` class puts together an instance of the class `EventData`, which provides access to the properties defined in the `fire_event` call.
```python
zombie.fire_event('attack', {
'target': survivor, # <-- We defined 'target' here
'multiplier': 1.5 # <-- and 'multiplier' here
})
def on_attack(self, evt: pecs.EntityEvent) -> pecs.EntityEvent:
target = evt.data.target # --> survivor
multiplier = evt.data.multiplier # --> 1.5
```
Actions can also be defined as a tuple and passed into the `fire_event` method. This allows for easy abstraction over variables used in the event:
```python
attack_against = (lambda target : ('attack', {
'target': target,
'multiplier': 1.5
}))
zombie.fire_event(attack_against(survivor))
```
### Creating Entities from Prefabs
PECS supports defining prefab entities with preconfigured component properties. Define prefabs as `.json` files and register them with the engine:
```json
{
"name": "GameObject",
"inherit": [],
"components": [
{
"type": "Position"
},
{
"type": "Renderable",
"properties": {
"ch": "?",
"bg": [0, 0, 0],
}
},
{
"type": "Noun"
}
]
}
```
```py
import pecs_framework as pecs
import os
ROOTDIR = os.path.dirname(__file__)
PREFABS = os.path.join(ROOTDIR, 'prefabs')
ecs = pecs.Engine()
ecs.prefabs.register(PREFABS, 'game_object')
```
Now PECS will look for a file named `game_object.json` in the specified prefabs path and automatically load it for you. We can build an entity using this prefab very easily:
```py
game_object = ecs.domain.entities.create_from_prefab(
template = 'GameObject',
properties = {
'Position': {
'x': 15,
'y': 10,
},
'Renderable': {
'fg': [255, 0, 255],
},
'Noun': {
'text': 'Test Object'
}
},
alias = 'test_object_01',
)
```
Prefabs can specify other prefabs to inherit from as well. Prefabs can be defined as hierarchies of any depth and breadth. Note that properties will always be resolved from the most deeply embedded prefab to the least, overwriting with the most recent specification. If no properties are passed in the prefab or when creating from prefab, defaults from the component itself will be used.
For examples, check out the `tests` folder in this repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/krummja/PECS",
"name": "pecs-framework",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*",
"maintainer_email": "",
"keywords": "",
"author": "Jonathan Crum",
"author_email": "crumja4@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c1/e7/edc880f140cb3090ae08e3b2802397abf656e22b50361f33872df30f1b87/pecs_framework-1.3.4.tar.gz",
"platform": null,
"description": "# PECS\n[](https://github.com/krummja/PECS/actions/workflows/main.yml) [](https://coveralls.io/github/krummja/PECS?branch=master)\n\n\n\nPECS is the \u2728Respectably Muscled\u2728 Python ECS library that aims to provide a powerful, user-friendly, and fast-as-hell framework for game development.\n\nThis library is the spiritual successor to my prior ECS library, [ECStremity](https://github.com/krummja/ECStremity). Both this and its predecessor were inspired by the JavaScript ECS library [geotic](https://github.com/ddmills/geotic), created and maintained by [@ddmills](https://github.com/ddmills). I highly recommend checking out that project as well as the excellent resources cited in its README.\n\nWhat is ECS, you ask? [Check it out](https://medium.com/ingeniouslysimple/entities-components-and-systems-89c31464240d)!\n\n## Installation\n\nInstall the package from PyPI using pip:\n\n```\npip install pecs-framework\n```\n\nOr grab it directly from this repository:\n\n```\npip install git+https://github.com/krummja/PECS\n```\n\n## Usage and Examples\n\nTo start flexing your PECS, import the library and set up some components. Components can be built as standard Python classes:\n\n```python\nimport pecs_framework as pecs\n\n\nclass Position(pecs.Component):\n \"\"\"Representation of an Entity's position in 2D space.\"\"\"\n\n def __init__(self, x: int = 0, y: int = 0) -> None:\n self.x = x\n self.y = y\n\n @property\n def xy(self) -> tuple[int, int]:\n return self.x, self.y\n```\n\nAs extensions of existing components:\n\n```py\nimport pecs_framework as pecs\n\n\nclass Velocity(Position):\n \"\"\"Representation of an Entity's velocity in 2D space.\"\"\"\n\n```\n\nOr as dataclasses:\n\n```py\nimport pecs_framework as pecs\nfrom dataclasses import dataclass, field\n\n\n@dataclass\nclass Health(pecs.Component):\n \"\"\"Representation of an Entity's health.\"\"\"\n maximum: int = 100\n current: int = field(init=False)\n\n def __post_init__(self) -> None:\n self.current = self.maximum\n```\n\nComponents can have as much or as little behavior as needed, although it is generally better to keep to a strict single-repsonsibility principle. We can even have components that have no behavior at all, representing boolean flags for queries:\n\n```py\nimport pecs_framework as pecs\n\n\nclass IsFrozen(pecs.Component):\n \"\"\"Flag component denoting a frozen entity.\"\"\"\n```\n\n\n### Queries\n\nThe easiest way to build out systems is through world queries. To make a system that tracks and updates the components relevant to movement, we might query for `Position` and `Velocity` components. Because we want our entities to move, we want to exclude those marked with the `IsFrozen` flag. Perhaps we also want to grab only those entities that can fly through `Wings` or swim through `Fins`: \n\n```python\nimport pecs_framework as pecs\n\n\necs = pecs.Engine()\ndomain = ecs.create_domain(\"World\")\n\nkinematics = domain.create_query(\n all_of = [\n Position, \n Velocity\n ],\n any_of = [\n Wings, \n Fins\n ],\n none_of = [\n IsFrozen\n ],\n)\n```\n\nQueries can specify `all_of`, `any_of`, or `none_of` quantifiers. The query in the example above asks for entities that must have **both** `Position` **and** `Velocity`, may have (inclusive) `Wings` **or** `Fins`, and **must not** have `IsFrozen`.\n\nWe can access the result set of the query and do some operation on them every loop cycle:\n\n```py\ndef process(dt):\n for entity in targets.result:\n entity[Position].x += entity[Velocity].x * dt\n entity[Position].y += entity[Velocity].y * dt\n```\n\nFor convenience, the library provides barebones system class that you can extend for your own purposes:\n\n```py\nimport pecs_framework as pecs\n\n\nclass MovementSystem(pecs.BaseSystem):\n\n def initialize(self) -> None:\n self.query(\n 'movable',\n all_of = [Position, Velocity],\n none_of = [IsFrozen],\n )\n\n def update(self) -> None:\n movables = self._queries\n for entity in movables:\n entity[Position].x += entity[Velocity].x\n entity[Position].y += entity[Velocity].y\n```\n\n> ---\n> \n> **Warning:** \n> \n> Do not override the `__init__` method of `BaseSystem` -- use the provided `initialize` method instead.\n> \n> --- \n\n\n### Broadcasting Events to Components\n\nComplex interactions within and among entities can be achieved by firing events on an entity. This creates an `EntityEvent` that looks for methods on all of the entity's methods prefixed with `on_`.\n\n```python\nzombie.fire_event('attack', {\n 'target': survivor,\n 'multiplier': 1.5,\n})\n```\n\nOn the `zombie` entity, we might have attached an `Attacker` component with the following logic:\n\n```python\nclass Attacker(pecs.Component):\n\n def __init__(self, strength: int) -> None:\n self.strength = strength\n\n def on_attack(self, evt: pecs.EntityEvent) -> pecs.EntityEvent:\n target: Entity = evt.data.target\n target.fire_event('damage_taken', {\n 'amount': self.strength * evt.data.pultiplier,\n })\n evt.handle()\n return evt\n```\n\nWhen we execute `fire_event` with the event name `attack`, the event system will find all `on_attack` methods on that entity's components. If we want the event propagation to stop at a particular component, we can call `evt.handle()` which will immediately break broadcasting down the component list. This means that we can potentially have any number of components respond to a specific event, although it may generally be safer to fire a secondary event to prevent ordering issues.\n\nInternally, the `EntityEvent` class puts together an instance of the class `EventData`, which provides access to the properties defined in the `fire_event` call.\n\n```python\nzombie.fire_event('attack', {\n 'target': survivor, # <-- We defined 'target' here\n 'multiplier': 1.5 # <-- and 'multiplier' here\n})\n\ndef on_attack(self, evt: pecs.EntityEvent) -> pecs.EntityEvent:\n target = evt.data.target # --> survivor\n multiplier = evt.data.multiplier # --> 1.5\n```\n\nActions can also be defined as a tuple and passed into the `fire_event` method. This allows for easy abstraction over variables used in the event:\n\n```python\nattack_against = (lambda target : ('attack', {\n 'target': target,\n 'multiplier': 1.5\n}))\n\nzombie.fire_event(attack_against(survivor))\n```\n\n### Creating Entities from Prefabs\n\nPECS supports defining prefab entities with preconfigured component properties. Define prefabs as `.json` files and register them with the engine:\n\n```json\n{\n \"name\": \"GameObject\",\n \"inherit\": [],\n \"components\": [\n {\n \"type\": \"Position\"\n },\n {\n \"type\": \"Renderable\",\n \"properties\": {\n \"ch\": \"?\",\n \"bg\": [0, 0, 0],\n }\n },\n {\n \"type\": \"Noun\"\n }\n ]\n}\n```\n\n```py\nimport pecs_framework as pecs\nimport os\n\n\nROOTDIR = os.path.dirname(__file__)\nPREFABS = os.path.join(ROOTDIR, 'prefabs')\n\n\necs = pecs.Engine()\necs.prefabs.register(PREFABS, 'game_object')\n```\n\nNow PECS will look for a file named `game_object.json` in the specified prefabs path and automatically load it for you. We can build an entity using this prefab very easily:\n\n```py\ngame_object = ecs.domain.entities.create_from_prefab(\n template = 'GameObject',\n properties = {\n 'Position': {\n 'x': 15,\n 'y': 10,\n },\n 'Renderable': {\n 'fg': [255, 0, 255],\n },\n 'Noun': {\n 'text': 'Test Object'\n }\n },\n alias = 'test_object_01',\n)\n```\n\nPrefabs can specify other prefabs to inherit from as well. Prefabs can be defined as hierarchies of any depth and breadth. Note that properties will always be resolved from the most deeply embedded prefab to the least, overwriting with the most recent specification. If no properties are passed in the prefab or when creating from prefab, defaults from the component itself will be used.\n\nFor examples, check out the `tests` folder in this repository.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "The \u2728Respectably Muscled\u2728 Python Entity Component System",
"version": "1.3.4",
"project_urls": {
"Homepage": "https://github.com/krummja/PECS",
"Repository": "https://github.com/krummja/PECS"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eb872682d03112518b66e3dc4a7a0261c22049b2ed45cd13cf5588605d1ec2ec",
"md5": "062e7250c3471308d3232b88b9f1448c",
"sha256": "060dcbc38c7ac1f022d533b16151100cce65dffffc171a6f4e2435ae7bed464d"
},
"downloads": -1,
"filename": "pecs_framework-1.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "062e7250c3471308d3232b88b9f1448c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*",
"size": 22097,
"upload_time": "2024-03-16T06:13:05",
"upload_time_iso_8601": "2024-03-16T06:13:05.491038Z",
"url": "https://files.pythonhosted.org/packages/eb/87/2682d03112518b66e3dc4a7a0261c22049b2ed45cd13cf5588605d1ec2ec/pecs_framework-1.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c1e7edc880f140cb3090ae08e3b2802397abf656e22b50361f33872df30f1b87",
"md5": "f8decbb1e8b577cfc66bd7449caf81ae",
"sha256": "3a7b317a63655bb21aa6207b2ab85b45dde759164d823c780cd6c7ac7a32bcba"
},
"downloads": -1,
"filename": "pecs_framework-1.3.4.tar.gz",
"has_sig": false,
"md5_digest": "f8decbb1e8b577cfc66bd7449caf81ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*",
"size": 14430,
"upload_time": "2024-03-16T06:13:07",
"upload_time_iso_8601": "2024-03-16T06:13:07.325437Z",
"url": "https://files.pythonhosted.org/packages/c1/e7/edc880f140cb3090ae08e3b2802397abf656e22b50361f33872df30f1b87/pecs_framework-1.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-16 06:13:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "krummja",
"github_project": "PECS",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "deepmerge",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "rich",
"specs": []
},
{
"name": "beartype",
"specs": []
}
],
"lcname": "pecs-framework"
}
JSON
