Skip to main content

Charz

An object oriented terminal game engine

Installation

Install using either pip or rye:

pip install charz[all]
rye add charz --features all

If you don't need the keyboard package, simply use:

pip install charz
rye add charz

Getting started

Add to project with keyboard feature:

pip install charz[keyboard]

or

rye add charz --features keyboard

Copy this code into the entry point (main.py or __init__.py)

import colex              # Color constants and styling
import keyboard           # For taking key inputs
from charz import *       # Module can be imported as namespace: "import charz"


class Player(Sprite):
    SPEED: int = 4     # Defining constant
    color = colex.RED  # In reality just a string, like "\x1b[31m" for red
    centered = True    # Apply sprite centereing - Handled by `charz`
    texture = [        # A texture may be defined as a class variable, of type `list[str]`
        "  O",
        "/ | \\",
        " / \\",
    ]

    def update(self) -> None:  # This method is called every frame
        if keyboard.is_pressed("a"):
            self.position.x -= self.SPEED * Time.delta
        if keyboard.is_pressed("d"):
            self.position.x += self.SPEED * Time.delta
        if keyboard.is_pressed("s"):
            self.position.y += self.SPEED * Time.delta
        if keyboard.is_pressed("w"):
            self.position.y -= self.SPEED * Time.delta


class Game(Engine):
    clock = Clock(fps=12)
    screen = Screen(
        auto_resize=True,
        initial_clear=True,
    )

    def __init__(self) -> None:
        Camera.current.mode = Camera.MODE_CENTERED
        self.player = Player(position=Vec2(10, 5))
    
    def update(self) -> None:
        if keyboard.is_pressed("q"):
            self.is_running = False
        if keyboard.is_pressed("e"):
            self.player.queue_free()  # `Engine` will drop reference to player
            # NOTE: Player reference is still kept alive by `Game`, but it won't be updated


if __name__ == "__main__":
    game = Game()
    game.run()

Note: If using rye, replace:

if __name__ == "__main__":

with

def main() -> None:

Rational

This project is heavily inspired by the Godot Game Engine.

Includes

  • Annotations
    • ColorValue (from package colex)
    • Self (from standard typing or from package typing-extensions)
  • Math (from package linflex)
    • lerp
    • sign
    • clamp
    • move_toward
    • Vec2
    • Vec2i
    • Vec3
  • Submodules
    • text
      • fill
      • flip_h
      • flip_v
      • fill_lines
      • flip_lines_h
      • flip_lines_v
      • rotate
  • Framework
    • Engine
    • Clock
    • Screen
    • Scene
  • Datastructures
    • AnimationSet
    • Hitbox
  • Functions
    • load_texture
  • Decorators
    • group
  • Enums
    • Group
  • Singletons
    • Time
    • AssetLoader
  • Components
    • TransformComponent
    • TextureComponent
    • ColorComponent
    • AnimatedComponent
    • ColliderComponent
  • Nodes
    • Node
    • Node2D
    • Camera
    • Sprite
    • Label
    • AnimatedSprite
  • Feature dependent*
    • SimpleMovementComponent

*: Feature dependent imports requires explicit import statements as they are lazy loaded:

# Example when using star import, with feature dependent import
from charz import *
from charz import SimpleMovementComponent

Regarding testing

Tests for charz are currently manual and only somewhat implemented. The plan is to use pytest, however, it's hard to make work since charz is meant for long-running tasks, including IO.

Versioning

charz uses SemVer, according to The Cargo Book.

License

MIT

Metadata

Release files for charz 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for charz 0.1.3
File Size Uploaded Provenance Actions
charz-0.1.3.tar.gz 28.8 kB Without provenance Details for charz-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for charz 0.1.3
File Interpreter ABI Platform Actions
charz-0.1.3-py3-none-any.whl Python 3 none any Details for charz-0.1.3-py3-none-any.whl

Total release size: 66.5 kB

Release files / charz-0.1.3.tar.gz

Download URL charz-0.1.3.tar.gz
Size 28.8 kB
Tags Source
SHA-256 checksum
How to use checksums
f7d4c2938775c338b3c724e494ee6fdf4cfd678d4aa737cbbbad2bfd8c9ab4b1
BLAKE2b-256 checksum
How to use checksums
3375125b7f9547f2cda74b3a38ddea4deb0b6e2d40e03f045e1868d320f4a1f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.15

Release files / charz-0.1.3-py3-none-any.whl

Download URL charz-0.1.3-py3-none-any.whl
Size 37.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b8aa3e53d9e99a2942c9150b8aafe4569b85d43fea12c167c359fa94846de5f0
BLAKE2b-256 checksum
How to use checksums
e8bcfd97b89f75bce8e015435567fbe4f00f05b420f2bc83a602a3b99b8dc78a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.15

Security for charz 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page