Metadata-Version: 2.5
Name: pcg-console-engine
Version: 1.0.0
Summary: Console-first game engine and UI toolkit for Python
Project-URL: Homepage, https://github.com/Umar151515/PCG
Project-URL: Documentation, https://umar151515.github.io/PCG/
Project-URL: Repository, https://github.com/Umar151515/PCG
Project-URL: Issues, https://github.com/Umar151515/PCG/issues
Author: Umar
License: MIT License
        
        Copyright (c) 2026 Umar
        
        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.
License-File: LICENSE
Keywords: ansi,ascii,console,ecs,game-engine,roguelike,terminal,truecolor,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
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: Topic :: Games/Entertainment
Classifier: Topic :: Games/Entertainment :: Arcade
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: box2d-py>=2.3.8; extra == 'all'
Requires-Dist: mkdocs-material>=9.5; extra == 'all'
Requires-Dist: mkdocs>=1.5; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'all'
Requires-Dist: simpleaudio>=1.0.4; extra == 'all'
Provides-Extra: audio
Requires-Dist: simpleaudio>=1.0.4; extra == 'audio'
Provides-Extra: box2d
Requires-Dist: box2d-py>=2.3.8; extra == 'box2d'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Description-Content-Type: text/markdown

# pcg

`pcg` is a Python toolkit for games that live in a terminal. Its main API is a
single `Game` class: state goes in `start`, logic goes in `update`, and drawing
goes in `draw`. Input, colors, UI, sound, timers and a flicker-free game loop are
already connected.

```python
from pcg import Game


class Hello(Game):
    def start(self):
        self.x, self.y = self.width // 2, self.height // 2

    def update(self, dt):
        move = self.input.direction()
        self.x += round(move.x)
        self.y += round(move.y)

    def draw(self):
        self.screen.box(0, 0, self.width, self.height, fg="dark_gray")
        self.screen.put(self.x, self.y, "@", fg="yellow")
        self.screen.center_text("Move with arrows or WASD", 1, fg="cyan")


Hello(60, 20, title="Hello").run()
```

## Install

```bash
python -m pip install pcg
```

Python 3.10 or newer is required. The engine has no required runtime
dependencies. Optional sound playback and rigid-body physics are installed with:

```bash
python -m pip install "pcg[audio]"
python -m pip install "pcg[box2d]"
```

## Why the API is small

A basic game does not need a renderer object, an event bus, a scene manager or a
manual terminal context. `Game` owns those details and exposes five useful
things:

- `self.screen`: cells, text, lines, boxes, fills, circles, bars and cached sprites;
- `self.input`: direct keys, named actions, axes and normalized direction;
- `self.ui`: themeable widgets with focus, mouse support and automatic drawing;
- `self.audio`: tones, presets and optional sampled audio;
- `after()`, `every()` and `every_frame()`: tagged game-time scheduling.

Escape exits by default. Terminal setup and restoration are automatic.

## Input

Poll a key directly:

```python
if self.input.pressed("space"):
    self.jump()

if self.input.down("left"):
    self.x -= 1
```

Or give controls semantic names:

```python
def start(self):
    self.input.bind("fire", "space", "f")

def update(self, dt):
    if self.input.pressed("fire"):
        self.fire()
```

Or register a callback:

```python
@self.on_key("space")
def jump():
    self.jump()
```

The default actions are `move_up`, `move_down`, `move_left`, `move_right`,
`confirm`, and `cancel`. `self.input.direction()` combines the movement actions
and normalizes diagonals.

## Drawing

Colors can be names, hex strings, RGB strings, or `Color` values:

```python
def draw(self):
    s = self.screen
    s.clear(bg="#0d1117")
    s.text("HP", 2, 1, fg="white")
    s.bar(5, 1, 20, self.hp, 100, fg="lime", empty_fg="dark_gray")
    s.fill(4, 5, 12, 4, char="·", fg="gray")
    s.box(3, 4, 14, 6, border="double", fg="#ffcc00")
    s.sprite(" /\\\n<  >\n \\/", 30, 8, fg="cyan")
```

Every draw starts on a clean frame. The engine compares it with the previous
frame and writes only changed terminal cells.

## UI

UI is part of every `Game`; events, resize, update and drawing are automatic.
Focus navigation, mouse input, modal dialogs, bracketed paste and menu stacks are
built in.

```python
from pcg import Button, Checkbox, Panel, Slider, TextInput, Theme, VBox


def start(self):
    self.ui.theme = Theme.midnight()
    panel = Panel((10, 3, 40, 14), title="Settings", padding=1)
    form = VBox((1, 1, 36, 10), gap=1, stretch=True)
    form.add(
        TextInput((0, 0, 20, 3), placeholder="player name", tag="name"),
        Checkbox((0, 0), "Sound", checked=True),
        Slider((0, 0, 20, 1), value=70, show_value=True),
        Button((0, 0, 20, 3), "Play", on_click=lambda _: self.begin()),
    )
    panel.add(form)
    self.ui.add(panel)
    self.ui.focus(self.ui.get("name"))
```

Available controls include `Label`, `Panel`, `Button`, `Menu`, `ListBox`,
`ProgressBar`, `TextInput`, `Checkbox`, `RadioGroup`, `Select`, `Slider`,
`Separator`, `Spinner`, `Tabs`, and `Dialog`. `VBox`, `HBox`, `Stack`, `Grid`,
and `Center` handle layout. Themes can be applied to the whole UI or one subtree.

## Timers and deterministic tests

```python
def start(self):
    self.after(2.0, self.open_door)
    self.spawn_timer = self.every(0.5, self.spawn_enemy)
```

Headless execution uses the same input, update, UI and render pipeline:

```python
game = MyGame(headless=True)
game.run_for(120, dt=1 / 60)
assert "score" in "".join(game.engine.canvas_text())
game.close()
```

Pass `seed=` to `Game` and use `self.random` for deterministic randomness.
`run_until(seconds)` is available when duration reads better than frame count.

## Project commands

```bash
pcg init my-game       # create a runnable project
cd my-game
pcg run                # run main.py
pcg check              # syntax check
pcg info               # terminal and backend diagnostics
pcg build --name MyGame
```

`pcg build` supports PyInstaller by default and Nuitka with `--tool nuitka`.

## Advanced toolkit

The compact API covers most console games. Larger projects can use the modules
underneath it: scene stacks and transitions, an ECS, collision and physics,
tilemaps, pathfinding, particles, tweens, animation, camera effects, save files,
resource loading and a debug overlay. They use the same renderer and input
pipeline, so a project can introduce them gradually.

Read the [documentation](https://umar151515.github.io/PCG/) or start with the
[quickstart](https://umar151515.github.io/PCG/quickstart/).

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .
python -m mypy pcg
python -m build
python -m twine check dist/*
```

The package is typed (`py.typed`), platform-independent, and distributed under
the MIT license.
