kaypy 0.1.0__py3-none-any.whl

kaplay/__init__.py

@@ -0,0 +1,192 @@
+"""from kaplay import * — every name here is Kaplay's own name, in
+Kaplay's own order, with Kaplay's own arguments. The Kaplay documentation
+and every Kaplay example on the internet applies to what you write here;
+only the language underneath (real, native Python, via pygame-ce) is new.
+"""
+from .vec2 import vec2, Vec2
+from .engine import Engine, current_engine, rand, randi, choose
+from .debugmod import debug
+from .level import addLevel, Level
+from .kaboom import addKaboom
+
+# ---- components ---------------------------------------------------------
+from .comps.pos import pos
+from .comps.sprite import sprite
+from .comps.shapes import rect, circle, text
+from .comps.area import area
+from .comps.body import body
+from .comps.transform import anchor, scale, color, opacity, outline, z, fixed
+from .comps.state import state
+from .comps.move import move, offscreen, tile
+from .callutil import register_or_decorate
+
+__all__ = [
+    "kaplay",
+    "loadSprite", "loadSpriteAtlas", "loadSound",
+    "setGravity", "setBackground",
+    "add", "get", "addLevel", "addKaboom",
+    "pos", "sprite", "rect", "circle", "text", "area", "body",
+    "anchor", "scale", "color", "opacity", "outline", "z", "fixed",
+    "move", "offscreen", "tile", "state",
+    "onUpdate", "onKeyDown", "onKeyPress", "onKeyRelease", "onClick",
+    "wait", "loop",
+    "scene", "go",
+    "width", "height", "center", "dt", "vec2",
+    "rand", "randi", "choose",
+    "mousePos", "toWorld",
+    "setCamPos", "setCamScale", "shake",
+    "play",
+    "debug",
+    "run",
+]
+
+
+def kaplay(width=800, height=600, background=(0, 0, 0)):
+    """Starts the engine. It has to come first, before anything else."""
+    return Engine(width=width, height=height, background=background)
+
+
+# ---- loading -------------------------------------------------------------
+
+def loadSprite(name, path, sliceX=1, sliceY=1, anims=None):
+    return current_engine().assets.loadSprite(name, path, sliceX=sliceX, sliceY=sliceY, anims=anims)
+
+
+def loadSpriteAtlas(path, atlas):
+    return current_engine().assets.loadSpriteAtlas(path, atlas)
+
+
+def loadSound(name, path):
+    return current_engine().assets.loadSound(name, path)
+
+
+def setGravity(n):
+    current_engine().setGravity(n)
+
+
+def setBackground(r, g, b):
+    current_engine().setBackground(r, g, b)
+
+
+# ---- making things --------------------------------------------------------
+
+def add(comp_list):
+    return current_engine().add(comp_list)
+
+
+def get(tag):
+    return current_engine().get(tag)
+
+
+# ---- events ----------------------------------------------------------------
+
+def onUpdate(*args):
+    """onUpdate(fn) / onUpdate(tag, fn), or as a decorator:
+
+        @onUpdate                 # every frame
+        @onUpdate("enemy")        # every frame, once per tagged object
+    """
+    if len(args) == 2:
+        tag, fn = args
+        return register_or_decorate(fn, lambda f: current_engine().events.on_update(tag, f))
+    if len(args) == 1 and callable(args[0]):
+        return current_engine().events.on_update(args[0])
+    if len(args) == 1:
+        tag = args[0]
+        return register_or_decorate(None, lambda f: current_engine().events.on_update(tag, f))
+    raise TypeError("onUpdate() takes a function, or a tag and a function")
+
+
+def onKeyDown(key, fn=None):
+    return register_or_decorate(fn, lambda f: current_engine().events.on_key_down(key, f))
+
+
+def onKeyPress(key, fn=None):
+    return register_or_decorate(fn, lambda f: current_engine().events.on_key_press(key, f))
+
+
+def onKeyRelease(key, fn=None):
+    return register_or_decorate(fn, lambda f: current_engine().events.on_key_release(key, f))
+
+
+def onClick(fn=None):
+    return register_or_decorate(fn, lambda f: current_engine().events.on_click(f))
+
+
+def wait(seconds, fn=None):
+    return register_or_decorate(fn, lambda f: current_engine().timers.wait(seconds, f))
+
+
+def loop(seconds, fn=None):
+    return register_or_decorate(fn, lambda f: current_engine().timers.loop(seconds, f))
+
+
+# ---- scenes -----------------------------------------------------------------
+
+def scene(name, fn=None):
+    """scene(name, fn), or as a decorator:
+
+        @scene("game")
+        def build_game(): ...
+    """
+    def register(f):
+        current_engine().scene(name, f)
+        return f
+    return register_or_decorate(fn, register)
+
+
+def go(name, *args):
+    current_engine().go(name, *args)
+
+
+# ---- useful values ------------------------------------------------------
+
+def width():
+    return current_engine().width()
+
+
+def height():
+    return current_engine().height()
+
+
+def center():
+    return current_engine().center()
+
+
+def dt():
+    return current_engine().dt()
+
+
+def mousePos():
+    return current_engine().mousePos()
+
+
+def toWorld(pos_):
+    return current_engine().toWorld(pos_)
+
+
+def setCamPos(pos_):
+    current_engine().setCamPos(pos_)
+
+
+def setCamScale(n):
+    current_engine().setCamScale(n)
+
+
+def shake(n=8):
+    current_engine().shake(n)
+
+
+def play(name, loop=False, paused=False, volume=1.0):
+    from .engine import SoundHandle
+    engine = current_engine()
+    if name not in engine.assets.sounds:
+        raise KeyError(f"no sound called {name!r} — loadSound(\"{name}\", ...) first")
+    return SoundHandle(engine.assets.sounds[name], loop=loop, paused=paused, volume=volume)
+
+
+def run():
+    """Not part of the Kaplay API — the loop starts on its own once your
+    script finishes. Exposed only so 'kaypy run game.py'-style tooling
+    (or a script that wants to be explicit) has something to call."""
+    current_engine().run()

kaplay/assets.py

@@ -0,0 +1,127 @@
+"""Sprite / sound loading: loadSprite, loadSpriteAtlas, loadSound.
+
+Kaplay's own troubleshooting note applies here too: "the sprite is
+invisible but the game runs" almost always means a bad path, and
+"every frame is half one pose and half the next" means sliceX doesn't
+match the sheet. We raise clear errors for the first and let the second
+happen silently (cutting a rectangle of nothing without complaint),
+exactly as Kaplay's own guide describes.
+"""
+from __future__ import annotations
+import os
+import sys
+import pygame
+
+
+class SpriteAsset:
+    def __init__(self, frames, anims=None, frame_size=None):
+        self.frames = frames  # list[pygame.Surface]
+        self.anims = anims or {}  # name -> {"from","to","speed","loop"} or int
+        self.frame_size = frame_size or (frames[0].get_width(), frames[0].get_height())
+
+
+def _load_image(path):
+    if not os.path.isfile(path):
+        raise FileNotFoundError(
+            f"loadSprite/loadSpriteAtlas: no such file {path!r} — "
+            f"check the path (the two sprite packs live in separate "
+            f"folders; a dungeon sprite is not under images/)"
+        )
+    return pygame.image.load(path).convert_alpha()
+
+
+def _slice_surface(surface, slice_x, slice_y):
+    w = surface.get_width() // slice_x
+    h = surface.get_height() // slice_y
+    frames = []
+    for row in range(slice_y):
+        for col in range(slice_x):
+            rect = pygame.Rect(col * w, row * h, w, h)
+            frame = pygame.Surface((w, h), pygame.SRCALPHA)
+            frame.blit(surface, (0, 0), rect)
+            frames.append(frame)
+    return frames, (w, h)
+
+
+def _normalize_anims(anims):
+    out = {}
+    for name, spec in (anims or {}).items():
+        if isinstance(spec, int):
+            out[name] = {"from": spec, "to": spec, "speed": 1, "loop": False}
+        else:
+            out[name] = {
+                "from": spec.get("from", 0),
+                "to": spec.get("to", 0),
+                "speed": spec.get("speed", 10),
+                "loop": spec.get("loop", False),
+            }
+    return out
+
+
+class AssetManager:
+    def __init__(self):
+        self.sprites: dict[str, SpriteAsset] = {}
+        self.sounds: dict[str, "pygame.mixer.Sound"] = {}
+        self._atlas_cache: dict[str, "pygame.Surface"] = {}
+
+    def loadSprite(self, name, path, sliceX=1, sliceY=1, anims=None):
+        if isinstance(path, (list, tuple)):
+            frames = [_load_image(p) for p in path]
+            frame_size = (frames[0].get_width(), frames[0].get_height())
+        else:
+            surface = _load_image(path)
+            if sliceX > 1 or sliceY > 1:
+                frames, frame_size = _slice_surface(surface, sliceX, sliceY)
+            else:
+                frames = [surface]
+                frame_size = (surface.get_width(), surface.get_height())
+        self.sprites[name] = SpriteAsset(frames, _normalize_anims(anims), frame_size)
+        return self.sprites[name]
+
+    def loadSpriteAtlas(self, path, atlas):
+        if path not in self._atlas_cache:
+            self._atlas_cache[path] = _load_image(path)
+        sheet = self._atlas_cache[path]
+        for name, spec in atlas.items():
+            x, y = spec["x"], spec["y"]
+            w, h = spec["width"], spec["height"]
+            region = pygame.Surface((w, h), pygame.SRCALPHA)
+            region.blit(sheet, (0, 0), pygame.Rect(x, y, w, h))
+            slice_x = spec.get("sliceX", 1)
+            slice_y = spec.get("sliceY", 1)
+            if slice_x > 1 or slice_y > 1:
+                frames, frame_size = _slice_surface(region, slice_x, slice_y)
+            else:
+                frames = [region]
+                frame_size = (w, h)
+            self.sprites[name] = SpriteAsset(
+                frames, _normalize_anims(spec.get("anims")), frame_size
+            )
+        return self.sprites
+
+    def loadSound(self, name, path):
+        if sys.platform == "emscripten":
+            # Browsers' WASM SDL2-mixer build can't reliably decode most
+            # .wav/.mp3/.aiff encodings — pygbag's own --build step flags
+            # this (see tools/build_web.py, which converts each .wav it
+            # copies into a same-named .ogg via ffmpeg when available). If
+            # that sibling .ogg exists, prefer it silently, so scripts never
+            # need an if-web branch just to pick a sound file extension.
+            ogg_path = os.path.splitext(path)[0] + ".ogg"
+            if os.path.isfile(ogg_path):
+                path = ogg_path
+        if not os.path.isfile(path):
+            raise FileNotFoundError(f"loadSound: no such file {path!r}")
+        try:
+            self.sounds[name] = pygame.mixer.Sound(path)
+        except pygame.error:
+            self.sounds[name] = None  # audio device unavailable (headless/CI)
+        return self.sounds[name]
+
+    def get_sprite(self, name) -> SpriteAsset:
+        if name not in self.sprites:
+            raise KeyError(
+                f"no sprite called {name!r} — loadSprite(\"{name}\", ...) "
+                f"must run before it is used"
+            )
+        return self.sprites[name]

kaplay/callutil.py

@@ -0,0 +1,54 @@
+"""Kaplay callbacks can ignore arguments they don't want: onKeyDown hands
+the key that was pressed, but `lambda: ...` takes nothing and works
+anyway, exactly as `() => ...` does in JavaScript. If you *do* want the
+argument, `lambda key: ...` gets it."""
+import inspect
+
+_sig_cache = {}
+
+
+def register_or_decorate(fn, register):
+    """Let one event function serve as both a callback and a decorator.
+
+        onKeyPress("space", jump)     # hand it a function
+        @onKeyPress("space")          # or put it above one
+        def jump(): ...
+
+    Kaplay's own form is the first one, and it stays the form every
+    Kaplay example and doc page translates into directly. The second
+    exists because a lambda can only hold one expression, and working
+    around that teaches bad habits: `lambda: p.jump() if p.isGrounded()
+    else None` has an `else None` that does nothing and exists purely to
+    satisfy a conditional expression, and `lambda: setattr(p, "pos", v)`
+    reaches for setattr only because a lambda can't assign. With a
+    decorator, both are just ordinary indented code — and the handler
+    gets a name, so it shows up in tracebacks as `jump` rather than
+    `<lambda>`.
+
+    `register` does the actual work and returns the function; this only
+    decides whether to call it now or hand back something that will.
+    """
+    if fn is not None:
+        return register(fn)
+
+    def decorator(f):
+        register(f)
+        return f          # leave the name bound to the function itself
+
+    return decorator
+
+
+def call_flexible(fn, *args):
+    n = _sig_cache.get(fn)
+    if n is None:
+        try:
+            params = inspect.signature(fn).parameters.values()
+            has_varargs = any(p.kind == p.VAR_POSITIONAL for p in params)
+            n = len(args) if has_varargs else sum(
+                1 for p in params
+                if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+            )
+        except (TypeError, ValueError):
+            n = len(args)
+        _sig_cache[fn] = n
+    return fn(*args[:n])

kaplay/camera.py

@@ -0,0 +1,44 @@
+from .vec2 import Vec2
+
+
+class Camera:
+    def __init__(self, width, height):
+        self.width = width
+        self.height = height
+        self.pos = Vec2(width / 2, height / 2)
+        self.scale = 1.0
+        self.shake_amount = 0.0
+        self._frame_shake_offset = Vec2(0, 0)
+
+    def setPos(self, pos):
+        self.pos = Vec2(pos.x, pos.y)
+
+    def setScale(self, n):
+        self.scale = n
+
+    def shake(self, amount=8):
+        self.shake_amount = amount
+
+    def begin_frame(self):
+        """Called once per frame by the render system: decays shake and
+        freezes this frame's random offset so every object drawn this
+        frame shakes together."""
+        if self.shake_amount <= 0:
+            self._frame_shake_offset = Vec2(0, 0)
+            return
+        import random
+        a = self.shake_amount
+        self._frame_shake_offset = Vec2(random.uniform(-a, a), random.uniform(-a, a))
+        self.shake_amount *= 0.9
+        if self.shake_amount < 0.2:
+            self.shake_amount = 0
+
+    def world_to_screen(self, world_pos: Vec2) -> Vec2:
+        center = Vec2(self.width / 2, self.height / 2)
+        return (world_pos - self.pos) * self.scale + center + self._frame_shake_offset
+
+    def screen_to_world(self, screen_pos) -> Vec2:
+        if not isinstance(screen_pos, Vec2):
+            screen_pos = Vec2(screen_pos[0], screen_pos[1])
+        center = Vec2(self.width / 2, self.height / 2)
+        return (screen_pos - center) / self.scale + self.pos

kaplay/cli.py

@@ -0,0 +1,86 @@
+"""The `kaypy` command.
+
+    kaypy new mygame      make a folder with a working game and its assets
+    kaypy web game.py     build that game as a web page and serve it
+
+Both exist because a pip install has no repo to stand in. `kaypy new` is
+what gets a student from `pip install kaypy` to something moving on
+screen without hunting for sprite files, and `kaypy web` is the same
+build tool the checkout calls `webbuild.py`.
+"""
+from __future__ import annotations
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+STARTER = Path(__file__).resolve().parent / "starter"
+
+
+def cmd_new(args) -> int:
+    dest = Path(args.name).resolve()
+    if dest.exists() and any(dest.iterdir()):
+        print(f"{dest} already exists and isn't empty — pick another name, "
+              f"or delete it first.")
+        return 1
+    if not STARTER.is_dir():
+        print("this kaypy install has no starter files in it, which shouldn't "
+              "happen — reinstall, or copy a game from the project's examples/.")
+        return 1
+
+    shutil.copytree(
+        STARTER, dest, dirs_exist_ok=True,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
+    )
+
+    here = Path.cwd()
+    try:
+        shown = dest.relative_to(here)
+    except ValueError:
+        shown = dest
+
+    print(f"Created {shown}/ — a game, and the sprites and sounds to build on.\n")
+    print("Try it:\n")
+    print(f"    cd {shown}")
+    print("    python game.py\n")
+    print("Arrow keys to move, space to jump. Then open game.py and change it.")
+    print(f"To put it on the web instead:  kaypy web game.py")
+    return 0
+
+
+def cmd_web(args) -> int:
+    from . import webbuild
+    # webbuild parses its own arguments, so hand it the ones meant for it.
+    sys.argv = ["kaypy web"] + args.rest
+    webbuild.main()
+    return 0
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="kaypy",
+        description="kaypy — a real-Python game engine with Kaplay's API.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    p_new = sub.add_parser("new", help="create a new game folder, ready to run")
+    p_new.add_argument("name", help="folder to create, e.g. mygame")
+    p_new.set_defaults(func=cmd_new)
+
+    p_web = sub.add_parser(
+        "web", help="build a game as a web page and serve it",
+        add_help=False,
+    )
+    p_web.add_argument("rest", nargs=argparse.REMAINDER,
+                       help="the game file, plus any webbuild options")
+    p_web.set_defaults(func=cmd_web)
+
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 1
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kaplay/comps/area.py

@@ -0,0 +1,24 @@
+"""area(): the collision box. Both objects in a collision need one —
+an object without area() is invisible to collision, and that's the
+single most common reason a collision "doesn't work"."""
+from ..gameobj import Comp
+
+
+class AreaComp(Comp):
+    id = "area"
+
+    def add(self, obj):
+        self._obj = obj
+
+    def get_rect(self):
+        from ..geometry import get_world_rect
+        return get_world_rect(self._obj)
+
+    def isHovering(self) -> bool:
+        from ..engine import current_engine
+        mx, my = current_engine().mousePos()
+        return self.get_rect().collidepoint(mx, my)
+
+
+def area():
+    return AreaComp()

kaplay/comps/body.py

@@ -0,0 +1,50 @@
+"""body(): makes an object respond to physics. isStatic=True makes it a
+wall — solid, and never moved by anything. mass=n makes it heavy but
+still pushable. Gives .jump(), .isGrounded(), .onGround()."""
+from ..gameobj import Comp
+from ..vec2 import Vec2
+
+
+class BodyComp(Comp):
+    id = "body"
+
+    def __init__(self, isStatic=False, mass=1, jumpForce=800):
+        self.isStatic = isStatic
+        self.mass = mass
+        self.jumpForce = jumpForce
+        self.vel = Vec2(0, 0)
+        self._grounded = False
+        self._pending_grounded = False
+        self._ground_handlers = []
+
+    def add(self, obj):
+        self._obj = obj
+
+    def jump(self, force=None):
+        if force is None:
+            force = self.jumpForce
+        self.vel.y = -force
+        self._grounded = False
+
+    def isGrounded(self) -> bool:
+        return self._grounded
+
+    def onGround(self, fn=None):
+        from ..callutil import register_or_decorate
+
+        def register(f):
+            self._ground_handlers.append(f)
+            return f
+
+        return register_or_decorate(fn, register)
+
+    def _apply_grounded(self, value: bool):
+        was = self._grounded
+        self._grounded = value
+        if value and not was:
+            for fn in self._ground_handlers:
+                fn()
+
+
+def body(isStatic=False, mass=1, jumpForce=800):
+    return BodyComp(isStatic=isStatic, mass=mass, jumpForce=jumpForce)

kaplay/comps/move.py

@@ -0,0 +1,67 @@
+"""move(dir, speed): drifts an object in a straight line forever.
+offscreen(destroy=True): cleans it up once it leaves the screen.
+tile(isObstacle=): marks an object as occupying a square on a grid."""
+from ..gameobj import Comp
+from ..vec2 import vec2, Vec2
+
+
+class MoveComp(Comp):
+    id = "move"
+
+    def __init__(self, direction, speed):
+        if isinstance(direction, Vec2):
+            self.direction = direction.unit()
+        else:
+            self.direction = vec2(*direction).unit()
+        self.speed = speed
+
+    def add(self, obj):
+        self._obj = obj
+
+    def update(self, obj):
+        if obj.has("pos"):
+            obj.comp("pos").move(self.direction * self.speed)
+
+
+def move(direction, speed):
+    return MoveComp(direction, speed)
+
+
+class OffscreenComp(Comp):
+    id = "offscreen"
+
+    def __init__(self, destroy=False, distance=64):
+        self.destroy = destroy
+        self.distance = distance
+
+    def add(self, obj):
+        self._obj = obj
+
+    def update(self, obj):
+        from ..engine import current_engine
+        from ..geometry import get_world_pos
+        engine = current_engine()
+        p = get_world_pos(obj)
+        d = self.distance
+        if (p.x < -d or p.x > engine.width() + d or
+                p.y < -d or p.y > engine.height() + d):
+            if self.destroy:
+                obj.destroy()
+
+
+def offscreen(destroy=False, distance=64):
+    return OffscreenComp(destroy=destroy, distance=distance)
+
+
+class TileComp(Comp):
+    id = "tile"
+
+    def __init__(self, isObstacle=False):
+        self.isObstacle = isObstacle
+
+    def add(self, obj):
+        self._obj = obj
+
+
+def tile(isObstacle=False):
+    return TileComp(isObstacle=isObstacle)