jeski 0.5.0__tar.gz

jeski-0.5.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: jeski
+Version: 0.5.0
+Summary: Jeski Project, UI-Development made simple.
+Author: Siddharth
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: pygame
+Requires-Dist: pyautogui
+Requires-Dist: keyboard
+Requires-Dist: numpy
+Requires-Dist: asteval
+Requires-Dist: mouse
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Jeski Engine
+
+**Jeski** is a Scratch-inspired 2D game engine and rapid prototyping wrapper built on top of **Pygame**. Created by **Siddharth Barnwal (Enirb)**, Jeski turns verbose Pygame boilerplate into intuitive, object-oriented building blocks—bringing sprites (`Entity`), costumes, stamps, clones, pixel-perfect mask collisions, speech/input bubbles (`Box`), geometric primitives, 1D/2D layout meshes, and multi-threaded background scripts (`Script`) to Python.
+
+| Metadata | Details |
+| :--- | :--- |
+| **Package Name** | `Jeski` |
+| **Author** | Siddharth Barnwal (`beast.barnwal` / `Enirb`) |
+| **Engine Backend** | Pygame (`pygame`, `pygame.gfxdraw`) |
+| **Python Compatibility** | Python 3.9+ |
+
+## Key Features
+
+- **Zero-Boilerplate Engine Loop**: Initialize the display window, audio mixer, clock, and asset folders in a single `INITIALIZE()` call, and refresh frames with `UPDATE()` and `SMOOTH()`.
+- **Scratch-Style `Entity` System**: Create sprites with support for `move()`, `turn()`, `pointTowards()`, `goto()`, `changeXby()`, `changeYby()`, `setSize()`, `changeSize()`, `stamp()`, and `createClone()`.
+- **Costume & Animation Management**: Attach multiple `Costume` objects to any `Entity`, cycle through frames with `nextCostume()` / `previousCostume()`, or run background sprite-sheet loops via `startAnimation()` and `blink()`.
+- **Pixel-Perfect Mask Collisions**: Built-in `touching()` and automatic rollback collision resolution (`check_collisions()`) powered by `pygame.mask`, plus live collision mask debugging (`M` key or `T` hotkey).
+- **Interactive Speech & Input Bubbles**: Prompt players with Scratch-like `askAndWait()`, `say()`, and timed `sayFor()` dialog boxes directly on the canvas.
+- **Rich Vector Shapes & Grouping**: Draw and manipulate `Rectangle`, `CurvedRectangle`, `Circle`, `Ellipse`, `Triangle`, `Polygon`, `Line`, `ZigZag`, and composite `Group` hierarchies (plus non-registered `*F` costume variants like `RectangleF` and `CircleF`).
+- **Reactive UI & Grid Meshes**: Render live global variables on screen with `Variable` and `Text`, trigger native OS dialogs via `MESSAGE`, and align objects effortlessly using `GridMesh1D` and `GridMesh2D`.
+- **Multi-Channel Audio (`SOUNDPLAYER`)**: Play, loop, fade, mute, and block on sound effects with automatic channel cleanup.
+
+## Installation
+
+Install `Jeski` from PyPI using `pip`:
+
+```bash
+pip install Jeski
+```
+
+To ensure all runtime dependencies are installed alongside `Jeski`:
+
+```bash
+pip install pygame numpy pyautogui keyboard mouse asteval safeImport
+```
+
+> **Platform Note**: Because `Jeski` uses the `keyboard` and `mouse` libraries for global hotkey polling alongside `pyautogui`, Linux users may need root permissions or X11 display access, and Windows users can use the built-in `RunAsAdmin()` helper when global hooks require elevation.
+
+## Quick Start
+
+Here is a complete, runnable example demonstrating a player sprite, geometric obstacles, live variable tracking, and keyboard controls:
+
+```python
+from Jeski import *
+
+# Optional: Set your app name before initializing
+__APPNAME__ = "SpaceDash"
+CONFIG.WINDOWTITLE = "SpaceDash - Jeski Demo"
+CONFIG.backgroundColor = (240, 244, 248)
+
+# 1. Start the Jeski Engine
+INITIALIZE(stayInActiveDirectory=True)
+
+# 2. Create a score variable and display it on screen
+score = 0
+score_label = Variable("score", x=WINDOW.w // 2, y=30, size=36, color=colors.BLUE)
+
+# 3. Create the player Entity (uses a colored rectangle if no image path is provided)
+player = Entity(
+    name="Player1",
+    x=CONFIG.centerX,
+    y=CONFIG.centerY,
+    sizeX=50,
+    sizeY=50,
+    color=colors.RED,
+    collider=True
+)
+
+# 4. Add a decorative Circle shape
+goal = Circle(center=(200, 200), radius=25, color=colors.GREEN)
+
+# 5. Main game loop
+while CORE.RUNNING:
+    UPDATE()
+
+    # Poll movement keys using Pygame's key state in CORE.KEYS
+    if CORE.KEYS[pygame.K_w] or CORE.KEYS[pygame.K_UP]:
+        player.move(6)
+    if CORE.KEYS[pygame.K_s] or CORE.KEYS[pygame.K_DOWN]:
+        player.move(-6)
+    if CORE.KEYS[pygame.K_a] or CORE.KEYS[pygame.K_LEFT]:
+        player.turn(-4)
+    if CORE.KEYS[pygame.K_d] or CORE.KEYS[pygame.K_RIGHT]:
+        player.turn(4)
+
+    # Check pixel-perfect collision with the goal circle
+    if player.touching(goal):
+        score += 1
+        goal.center = (random.randint(60, WINDOW.w - 60), random.randint(60, WINDOW.h - 60))
+        goal.refresh()
+
+    SMOOTH()
+```
+
+## Core Architecture & API Reference
+
+### 1. Engine Lifecycle (`__init__.py`)
+
+| Function | Description |
+| :--- | :--- |
+| `INITIALIZE(**kwargs)` | Initializes Pygame, mixer, fonts, `CORE.SCREEN`, `CORE.CLOCK`, and asset directories. Pass `stayInActiveDirectory=True` to keep your current working directory. Alias: `INITIALISE()`. |
+| `UPDATE()` | Clears the screen with `CONFIG.backgroundColor`, processes window/input events (`UPDATEVARS()`), updates `SOUNDPLAYER`, renders all stamps and entities (`DRAWSCREEN()`), and ticks `CORE.CLOCK` at `CONFIG.FPS`. |
+| `SMOOTH(smooth=None, noPauseWait=False)` | Sleeps for `CONFIG.smoothWait` (default `1/60` sec) and yields execution while honoring `CONFIG.PAUSED`. |
+| `SHUTDOWN()` / `QUIT()` | Stops the engine loop (`CORE.RUNNING = False`) or posts a `pygame.QUIT` event. |
+| `startConfigSync(data_dict)` | Starts a background `Script` that continuously synchronizes a dictionary of variable names with the caller's global scope. |
+
+### 2. Sprites & Entities (`entities/entity.py`)
+
+`Entity` is the core sprite class in Jeski. Every `Entity` is automatically added to `CORE.ENTITIES` (unless `type='Stamp'`) and rendered each frame.
+
+```python
+hero = Entity(
+    image="hero.png",       # Optional path to image file (or pass rawimage=Surface)
+    x=300, y=300,           # Defaults to screen center (CONFIG.centerX, CONFIG.centerY)
+    sizeX=64, sizeY=64,     # Dimensions when using procedural rectangle fallback
+    color=colors.BLUE,      # Fill color if no image is supplied
+    centered=True,          # Center sprite on (x, y)
+    collider=True           # Enable automatic collision rollback in check_collisions()
+)
+```
+
+#### Movement, Rotation & Scaling
+
+- `hero.move(steps, raw=False)`: Moves forward along `hero.direction` (clamped to window bounds unless `raw=True`).
+- `hero.turn(deg)`: Rotates the entity by `deg` degrees and checks collisions.
+- `hero.pointTowards(other_entity)`: Rotates to face another entity's `(x, y)` coordinates.
+- `hero.goto(x, y)` / `hero._goto(other_entity)`: Teleports to coordinates or another entity's position.
+- `hero.changeXby(steps)` (`chx`) / `hero.changeYby(steps)` (`chy`): Moves along a single axis with collision rollback.
+- `hero.setSize(percent)` / `hero.changeSize(delta_percent)` (`chs`) / `hero.setSizeToVal((w, h))`: Scales `original_image` smoothly using `pygame.transform.smoothscale`.
+- `hero.rotationStyle`: Set to `2` for full 360° rotation (default), `1` for left-right horizontal flip, or `0` for fixed orientation.
+
+#### Costumes, Visual Effects & Layering
+
+- `hero.addCostume(Costume(name, obj))` / `hero.removeCostume(idx)`: Manages the entity's costume list.
+- `hero.nextCostume()` / `hero.previousCostume()` / `hero.changeCostume(idx)`: Switches active appearance.
+- `hero.transparency`: Value from `0` (opaque) to `255` (invisible).
+- `hero.brightness`: Positive values (`0` to `255`) brighten via `BLEND_RGBA_ADD`; negative values darken via `BLEND_RGBA_SUB`.
+- `hero.hide()` / `hero.show()`: Toggles visibility.
+- `hero.bringToFront()` / `hero.sendToBack()`: Reorders draw priority inside `CORE.ENTITIES`.
+
+#### Clones, Stamps & Collisions
+
+- `hero.stamp(var=None, ret=False)`: Leaves a static visual copy on `CORE.STAMPS` (press `Q` at runtime to clear stamps).
+- `hero.createClone(ret=False, config=None)`: Spawns an independent `Clone` entity inheriting position, direction, costumes, and variables.
+- `hero.touching(other_or_mouse)`: Returns `True` on pixel-perfect mask overlap with another entity or `'__mouse__'`.
+- `hero.isClicked()`: Returns `True` if the mouse button is down and touching the entity's mask.
+- `hero.delete()`: Removes the entity from `CORE.ENTITIES` and any registered reference lists.
+
+#### Dialogs (`Box`)
+
+- `answer = hero.askAndWait("What is your name?")`: Opens an interactive text input box next to the entity and returns the submitted string.
+- `hero.sayFor("Hello!", timeout=2)`: Displays a speech bubble for `timeout` seconds.
+- `hero.say("Thinking...")`: Displays a persistent speech bubble bound to `hero.var['msg']` (set `hero.var['msg'] = ''` to dismiss).
+
+### 3. Geometric Shapes & Groups (`entities/shapes.py`)
+
+All shapes support `BASICDRAW` caching, masks, and `Entity` helper methods via `verifyAttributes()`. Each class also provides a `*F` subclass (e.g., `RectangleF`, `CircleF`, `PolygonF`) with `trueEntity=False` for building `Costume` objects or composite `Group` hierarchies without adding sub-parts directly to `CORE.ENTITIES`.
+
+| Shape Class | Constructor Signature |
+| :--- | :--- |
+| `Image` / `ImageF` | `Image(path, x=None, y=None, raw=False, trueEntity=True)` |
+| `Rectangle` / `RectangleF` | `Rectangle(x, y, w, h, color=colors.BLACK, trueEntity=True)` |
+| `CurvedRectangle` / `CurvedRectangleF` | `CurvedRectangle(x, y, w, h, curve, color=colors.BLACK, trueEntity=True)` |
+| `Circle` / `CircleF` | `Circle(center, radius, width=0, color=colors.BLACK, trueEntity=True)` |
+| `Ellipse` / `EllipseF` | `Ellipse(center, radiusMinor, radiusMajor, width=0, color=colors.BLACK, trueEntity=True)` |
+| `Triangle` / `TriangleF` | `Triangle(cord1, cord2, cord3, color=colors.BLACK, trueEntity=True)` |
+| `Polygon` / `PolygonF` | `Polygon(cords, color=colors.BLACK, trueEntity=True)` |
+| `Line` / `LineF` | `Line(cord1, cord2, color=colors.BLACK, width=5, trueEntity=True)` |
+| `ZigZag` / `ZigZagF` | `ZigZag(cords, color=colors.BLACK, width=5, trueEntity=True)` |
+| `Group` / `GroupF` | `Group(attributes=None, entities=None, tight=False, trueEntity=True)` |
+
+### 4. UI, Text, Grids & Meshes (`entities/ui.py`, `mesh.py`)
+
+- **`Text(text, x, y, font=None, size=40, align='center', color=colors.BLACK)`**: Renders cached Pygame font surfaces. Update properties dynamically with `text_obj.change('text', 'New Value')`.
+- **`Variable(variable_name, x, y, size=40, color=colors.BLACK)`**: Subclasses `Text` and spawns a background `Script` that watches a global variable by name (e.g., `Variable('score', 100, 50)`) and re-renders automatically whenever its value changes.
+- **`MESSAGE`**: Static wrapper around `tkinter.messagebox` providing `info()`, `warning()` / `warn()`, `error()`, `yesNo()`, `okCancel()`, `retryCancel()`, and `yesNoCancel()`.
+- **`GridMesh2D(x=10, y=10, center=True, margin=0)` & `GridMesh1D(type='x', c=10, center=True, margin=0)`**: Automatically computes cell widths/heights across `WINDOW` and positions objects added via `.add(obj, coords=(col, row))`.
+
+### 5. Animations, Audio & Concurrency (`animations.py`, `sounds.py`, `scripts.py`)
+
+- **`Script(function, starter='CORE.RUNNING', once=True, loop=None, waitUntilFinished=False)`**: Runs `function` in a daemon thread when the `starter` expression evaluates to truthy.
+- **`startAnimation(obj, costs=[0, 1, 2], fps=10)`**: Cycles `obj` through the specified costume indices at `fps` frames per second in a background `Script`.
+- **`blink(obj, fast=False)`**: Pulses an entity's brightness up to `100` and back to its original value.
+- **`SOUNDPLAYER`**:
+  - `SOUNDPLAYER.play(sound, raw=False, config={'volume': 50, 'loops': 0, 'fade_ms': 0}, untilFinished=False)`
+  - `SOUNDPLAYER.setMasterVolume(80)`
+  - `SOUNDPLAYER.fadeAll(500)` / `SOUNDPLAYER.stopAll()`
+  - `SOUNDPLAYER.mute()` / `SOUNDPLAYER.unmute()`
+
+### 6. Configuration & Built-in Shortcuts (`config.py`)
+
+Customize `WINDOW` and `CONFIG` before calling `INITIALIZE()`:
+
+```python
+WINDOW.WIDTH = 1280
+WINDOW.HEIGHT = 720
+CONFIG.WINDOWTITLE = "My Jeski Game"
+CONFIG.FPS = 60
+CONFIG.backgroundColor = colors.WHITE
+CONFIG.debug = True
+```
+
+**Built-in Runtime Hotkeys:**
+- **`M` key** (or **`T`** when `CONFIG.debug = True`): Toggles red/translucent collision mask overlays (`CONFIG.showMask`) across all entities.
+- **`Q` key**: Clears all `Stamp` entities from `CORE.ENTITIES`.
+
+## Project Structure
+
+```text
+Jeski/
+├── __init__.py          # Engine lifecycle (INITIALIZE, UPDATE, DRAWSCREEN, UPDATEVARS)
+├── __main__.py          # Built-in 2-player demo script
+├── animations.py        # Costume frame animation and brightness blink effects
+├── commands.py          # Shell execution (RunCommand), PyInstaller paths, UAC elevation
+├── config.py            # CORE state, WINDOW dimensions, CONFIG settings, colors, GUI aliases
+├── credits.py           # Author metadata
+├── deps.py              # Dependency imports and safeImport verification fallback
+├── grid.py              # Grid module stub (implemented in utils.py / __init__.py)
+├── imageTools.py        # Surface brightness and alpha manipulation helpers
+├── mesh.py              # GridMesh1D and GridMesh2D layout managers
+├── scripts.py           # Threaded Script runner and roughScript helper
+├── sounds.py            # SOUNDPLAYER multi-channel mixer controller
+├── tests.py             # Interactive live-variable entity test harness (TESTS_)
+├── utils.py             # Surface compositing, attribute verification, eval helpers, timing
+├── assets/              # Built-in WAV sound effects (alert.wav, coin.wav, Lose.wav)
+└── entities/
+    ├── __init__.py      # Exports Entity, shapes, and UI classes
+    ├── base.py          # BASICDRAW surface caching, rotation, brightness, mask overlay
+    ├── entity.py        # Core Entity, Costume, and Box (say/ask) classes
+    ├── shapes.py        # Vector shapes, Group compositor, and *F non-entity subclasses
+    ├── _shapes.py       # Legacy shapes module
+    └── ui.py            # MESSAGE dialogs, Text renderer, and reactive Variable widget
+```
+
+## Author & Credits
+
+Created and maintained by **Siddharth Barnwal** (`Enirb` / `beast.barnwal`).

jeski-0.5.0/README.md

@@ -0,0 +1,237 @@
+# Jeski Engine
+
+**Jeski** is a Scratch-inspired 2D game engine and rapid prototyping wrapper built on top of **Pygame**. Created by **Siddharth Barnwal (Enirb)**, Jeski turns verbose Pygame boilerplate into intuitive, object-oriented building blocks—bringing sprites (`Entity`), costumes, stamps, clones, pixel-perfect mask collisions, speech/input bubbles (`Box`), geometric primitives, 1D/2D layout meshes, and multi-threaded background scripts (`Script`) to Python.
+
+| Metadata | Details |
+| :--- | :--- |
+| **Package Name** | `Jeski` |
+| **Author** | Siddharth Barnwal (`beast.barnwal` / `Enirb`) |
+| **Engine Backend** | Pygame (`pygame`, `pygame.gfxdraw`) |
+| **Python Compatibility** | Python 3.9+ |
+
+## Key Features
+
+- **Zero-Boilerplate Engine Loop**: Initialize the display window, audio mixer, clock, and asset folders in a single `INITIALIZE()` call, and refresh frames with `UPDATE()` and `SMOOTH()`.
+- **Scratch-Style `Entity` System**: Create sprites with support for `move()`, `turn()`, `pointTowards()`, `goto()`, `changeXby()`, `changeYby()`, `setSize()`, `changeSize()`, `stamp()`, and `createClone()`.
+- **Costume & Animation Management**: Attach multiple `Costume` objects to any `Entity`, cycle through frames with `nextCostume()` / `previousCostume()`, or run background sprite-sheet loops via `startAnimation()` and `blink()`.
+- **Pixel-Perfect Mask Collisions**: Built-in `touching()` and automatic rollback collision resolution (`check_collisions()`) powered by `pygame.mask`, plus live collision mask debugging (`M` key or `T` hotkey).
+- **Interactive Speech & Input Bubbles**: Prompt players with Scratch-like `askAndWait()`, `say()`, and timed `sayFor()` dialog boxes directly on the canvas.
+- **Rich Vector Shapes & Grouping**: Draw and manipulate `Rectangle`, `CurvedRectangle`, `Circle`, `Ellipse`, `Triangle`, `Polygon`, `Line`, `ZigZag`, and composite `Group` hierarchies (plus non-registered `*F` costume variants like `RectangleF` and `CircleF`).
+- **Reactive UI & Grid Meshes**: Render live global variables on screen with `Variable` and `Text`, trigger native OS dialogs via `MESSAGE`, and align objects effortlessly using `GridMesh1D` and `GridMesh2D`.
+- **Multi-Channel Audio (`SOUNDPLAYER`)**: Play, loop, fade, mute, and block on sound effects with automatic channel cleanup.
+
+## Installation
+
+Install `Jeski` from PyPI using `pip`:
+
+```bash
+pip install Jeski
+```
+
+To ensure all runtime dependencies are installed alongside `Jeski`:
+
+```bash
+pip install pygame numpy pyautogui keyboard mouse asteval safeImport
+```
+
+> **Platform Note**: Because `Jeski` uses the `keyboard` and `mouse` libraries for global hotkey polling alongside `pyautogui`, Linux users may need root permissions or X11 display access, and Windows users can use the built-in `RunAsAdmin()` helper when global hooks require elevation.
+
+## Quick Start
+
+Here is a complete, runnable example demonstrating a player sprite, geometric obstacles, live variable tracking, and keyboard controls:
+
+```python
+from Jeski import *
+
+# Optional: Set your app name before initializing
+__APPNAME__ = "SpaceDash"
+CONFIG.WINDOWTITLE = "SpaceDash - Jeski Demo"
+CONFIG.backgroundColor = (240, 244, 248)
+
+# 1. Start the Jeski Engine
+INITIALIZE(stayInActiveDirectory=True)
+
+# 2. Create a score variable and display it on screen
+score = 0
+score_label = Variable("score", x=WINDOW.w // 2, y=30, size=36, color=colors.BLUE)
+
+# 3. Create the player Entity (uses a colored rectangle if no image path is provided)
+player = Entity(
+    name="Player1",
+    x=CONFIG.centerX,
+    y=CONFIG.centerY,
+    sizeX=50,
+    sizeY=50,
+    color=colors.RED,
+    collider=True
+)
+
+# 4. Add a decorative Circle shape
+goal = Circle(center=(200, 200), radius=25, color=colors.GREEN)
+
+# 5. Main game loop
+while CORE.RUNNING:
+    UPDATE()
+
+    # Poll movement keys using Pygame's key state in CORE.KEYS
+    if CORE.KEYS[pygame.K_w] or CORE.KEYS[pygame.K_UP]:
+        player.move(6)
+    if CORE.KEYS[pygame.K_s] or CORE.KEYS[pygame.K_DOWN]:
+        player.move(-6)
+    if CORE.KEYS[pygame.K_a] or CORE.KEYS[pygame.K_LEFT]:
+        player.turn(-4)
+    if CORE.KEYS[pygame.K_d] or CORE.KEYS[pygame.K_RIGHT]:
+        player.turn(4)
+
+    # Check pixel-perfect collision with the goal circle
+    if player.touching(goal):
+        score += 1
+        goal.center = (random.randint(60, WINDOW.w - 60), random.randint(60, WINDOW.h - 60))
+        goal.refresh()
+
+    SMOOTH()
+```
+
+## Core Architecture & API Reference
+
+### 1. Engine Lifecycle (`__init__.py`)
+
+| Function | Description |
+| :--- | :--- |
+| `INITIALIZE(**kwargs)` | Initializes Pygame, mixer, fonts, `CORE.SCREEN`, `CORE.CLOCK`, and asset directories. Pass `stayInActiveDirectory=True` to keep your current working directory. Alias: `INITIALISE()`. |
+| `UPDATE()` | Clears the screen with `CONFIG.backgroundColor`, processes window/input events (`UPDATEVARS()`), updates `SOUNDPLAYER`, renders all stamps and entities (`DRAWSCREEN()`), and ticks `CORE.CLOCK` at `CONFIG.FPS`. |
+| `SMOOTH(smooth=None, noPauseWait=False)` | Sleeps for `CONFIG.smoothWait` (default `1/60` sec) and yields execution while honoring `CONFIG.PAUSED`. |
+| `SHUTDOWN()` / `QUIT()` | Stops the engine loop (`CORE.RUNNING = False`) or posts a `pygame.QUIT` event. |
+| `startConfigSync(data_dict)` | Starts a background `Script` that continuously synchronizes a dictionary of variable names with the caller's global scope. |
+
+### 2. Sprites & Entities (`entities/entity.py`)
+
+`Entity` is the core sprite class in Jeski. Every `Entity` is automatically added to `CORE.ENTITIES` (unless `type='Stamp'`) and rendered each frame.
+
+```python
+hero = Entity(
+    image="hero.png",       # Optional path to image file (or pass rawimage=Surface)
+    x=300, y=300,           # Defaults to screen center (CONFIG.centerX, CONFIG.centerY)
+    sizeX=64, sizeY=64,     # Dimensions when using procedural rectangle fallback
+    color=colors.BLUE,      # Fill color if no image is supplied
+    centered=True,          # Center sprite on (x, y)
+    collider=True           # Enable automatic collision rollback in check_collisions()
+)
+```
+
+#### Movement, Rotation & Scaling
+
+- `hero.move(steps, raw=False)`: Moves forward along `hero.direction` (clamped to window bounds unless `raw=True`).
+- `hero.turn(deg)`: Rotates the entity by `deg` degrees and checks collisions.
+- `hero.pointTowards(other_entity)`: Rotates to face another entity's `(x, y)` coordinates.
+- `hero.goto(x, y)` / `hero._goto(other_entity)`: Teleports to coordinates or another entity's position.
+- `hero.changeXby(steps)` (`chx`) / `hero.changeYby(steps)` (`chy`): Moves along a single axis with collision rollback.
+- `hero.setSize(percent)` / `hero.changeSize(delta_percent)` (`chs`) / `hero.setSizeToVal((w, h))`: Scales `original_image` smoothly using `pygame.transform.smoothscale`.
+- `hero.rotationStyle`: Set to `2` for full 360° rotation (default), `1` for left-right horizontal flip, or `0` for fixed orientation.
+
+#### Costumes, Visual Effects & Layering
+
+- `hero.addCostume(Costume(name, obj))` / `hero.removeCostume(idx)`: Manages the entity's costume list.
+- `hero.nextCostume()` / `hero.previousCostume()` / `hero.changeCostume(idx)`: Switches active appearance.
+- `hero.transparency`: Value from `0` (opaque) to `255` (invisible).
+- `hero.brightness`: Positive values (`0` to `255`) brighten via `BLEND_RGBA_ADD`; negative values darken via `BLEND_RGBA_SUB`.
+- `hero.hide()` / `hero.show()`: Toggles visibility.
+- `hero.bringToFront()` / `hero.sendToBack()`: Reorders draw priority inside `CORE.ENTITIES`.
+
+#### Clones, Stamps & Collisions
+
+- `hero.stamp(var=None, ret=False)`: Leaves a static visual copy on `CORE.STAMPS` (press `Q` at runtime to clear stamps).
+- `hero.createClone(ret=False, config=None)`: Spawns an independent `Clone` entity inheriting position, direction, costumes, and variables.
+- `hero.touching(other_or_mouse)`: Returns `True` on pixel-perfect mask overlap with another entity or `'__mouse__'`.
+- `hero.isClicked()`: Returns `True` if the mouse button is down and touching the entity's mask.
+- `hero.delete()`: Removes the entity from `CORE.ENTITIES` and any registered reference lists.
+
+#### Dialogs (`Box`)
+
+- `answer = hero.askAndWait("What is your name?")`: Opens an interactive text input box next to the entity and returns the submitted string.
+- `hero.sayFor("Hello!", timeout=2)`: Displays a speech bubble for `timeout` seconds.
+- `hero.say("Thinking...")`: Displays a persistent speech bubble bound to `hero.var['msg']` (set `hero.var['msg'] = ''` to dismiss).
+
+### 3. Geometric Shapes & Groups (`entities/shapes.py`)
+
+All shapes support `BASICDRAW` caching, masks, and `Entity` helper methods via `verifyAttributes()`. Each class also provides a `*F` subclass (e.g., `RectangleF`, `CircleF`, `PolygonF`) with `trueEntity=False` for building `Costume` objects or composite `Group` hierarchies without adding sub-parts directly to `CORE.ENTITIES`.
+
+| Shape Class | Constructor Signature |
+| :--- | :--- |
+| `Image` / `ImageF` | `Image(path, x=None, y=None, raw=False, trueEntity=True)` |
+| `Rectangle` / `RectangleF` | `Rectangle(x, y, w, h, color=colors.BLACK, trueEntity=True)` |
+| `CurvedRectangle` / `CurvedRectangleF` | `CurvedRectangle(x, y, w, h, curve, color=colors.BLACK, trueEntity=True)` |
+| `Circle` / `CircleF` | `Circle(center, radius, width=0, color=colors.BLACK, trueEntity=True)` |
+| `Ellipse` / `EllipseF` | `Ellipse(center, radiusMinor, radiusMajor, width=0, color=colors.BLACK, trueEntity=True)` |
+| `Triangle` / `TriangleF` | `Triangle(cord1, cord2, cord3, color=colors.BLACK, trueEntity=True)` |
+| `Polygon` / `PolygonF` | `Polygon(cords, color=colors.BLACK, trueEntity=True)` |
+| `Line` / `LineF` | `Line(cord1, cord2, color=colors.BLACK, width=5, trueEntity=True)` |
+| `ZigZag` / `ZigZagF` | `ZigZag(cords, color=colors.BLACK, width=5, trueEntity=True)` |
+| `Group` / `GroupF` | `Group(attributes=None, entities=None, tight=False, trueEntity=True)` |
+
+### 4. UI, Text, Grids & Meshes (`entities/ui.py`, `mesh.py`)
+
+- **`Text(text, x, y, font=None, size=40, align='center', color=colors.BLACK)`**: Renders cached Pygame font surfaces. Update properties dynamically with `text_obj.change('text', 'New Value')`.
+- **`Variable(variable_name, x, y, size=40, color=colors.BLACK)`**: Subclasses `Text` and spawns a background `Script` that watches a global variable by name (e.g., `Variable('score', 100, 50)`) and re-renders automatically whenever its value changes.
+- **`MESSAGE`**: Static wrapper around `tkinter.messagebox` providing `info()`, `warning()` / `warn()`, `error()`, `yesNo()`, `okCancel()`, `retryCancel()`, and `yesNoCancel()`.
+- **`GridMesh2D(x=10, y=10, center=True, margin=0)` & `GridMesh1D(type='x', c=10, center=True, margin=0)`**: Automatically computes cell widths/heights across `WINDOW` and positions objects added via `.add(obj, coords=(col, row))`.
+
+### 5. Animations, Audio & Concurrency (`animations.py`, `sounds.py`, `scripts.py`)
+
+- **`Script(function, starter='CORE.RUNNING', once=True, loop=None, waitUntilFinished=False)`**: Runs `function` in a daemon thread when the `starter` expression evaluates to truthy.
+- **`startAnimation(obj, costs=[0, 1, 2], fps=10)`**: Cycles `obj` through the specified costume indices at `fps` frames per second in a background `Script`.
+- **`blink(obj, fast=False)`**: Pulses an entity's brightness up to `100` and back to its original value.
+- **`SOUNDPLAYER`**:
+  - `SOUNDPLAYER.play(sound, raw=False, config={'volume': 50, 'loops': 0, 'fade_ms': 0}, untilFinished=False)`
+  - `SOUNDPLAYER.setMasterVolume(80)`
+  - `SOUNDPLAYER.fadeAll(500)` / `SOUNDPLAYER.stopAll()`
+  - `SOUNDPLAYER.mute()` / `SOUNDPLAYER.unmute()`
+
+### 6. Configuration & Built-in Shortcuts (`config.py`)
+
+Customize `WINDOW` and `CONFIG` before calling `INITIALIZE()`:
+
+```python
+WINDOW.WIDTH = 1280
+WINDOW.HEIGHT = 720
+CONFIG.WINDOWTITLE = "My Jeski Game"
+CONFIG.FPS = 60
+CONFIG.backgroundColor = colors.WHITE
+CONFIG.debug = True
+```
+
+**Built-in Runtime Hotkeys:**
+- **`M` key** (or **`T`** when `CONFIG.debug = True`): Toggles red/translucent collision mask overlays (`CONFIG.showMask`) across all entities.
+- **`Q` key**: Clears all `Stamp` entities from `CORE.ENTITIES`.
+
+## Project Structure
+
+```text
+Jeski/
+├── __init__.py          # Engine lifecycle (INITIALIZE, UPDATE, DRAWSCREEN, UPDATEVARS)
+├── __main__.py          # Built-in 2-player demo script
+├── animations.py        # Costume frame animation and brightness blink effects
+├── commands.py          # Shell execution (RunCommand), PyInstaller paths, UAC elevation
+├── config.py            # CORE state, WINDOW dimensions, CONFIG settings, colors, GUI aliases
+├── credits.py           # Author metadata
+├── deps.py              # Dependency imports and safeImport verification fallback
+├── grid.py              # Grid module stub (implemented in utils.py / __init__.py)
+├── imageTools.py        # Surface brightness and alpha manipulation helpers
+├── mesh.py              # GridMesh1D and GridMesh2D layout managers
+├── scripts.py           # Threaded Script runner and roughScript helper
+├── sounds.py            # SOUNDPLAYER multi-channel mixer controller
+├── tests.py             # Interactive live-variable entity test harness (TESTS_)
+├── utils.py             # Surface compositing, attribute verification, eval helpers, timing
+├── assets/              # Built-in WAV sound effects (alert.wav, coin.wav, Lose.wav)
+└── entities/
+    ├── __init__.py      # Exports Entity, shapes, and UI classes
+    ├── base.py          # BASICDRAW surface caching, rotation, brightness, mask overlay
+    ├── entity.py        # Core Entity, Costume, and Box (say/ask) classes
+    ├── shapes.py        # Vector shapes, Group compositor, and *F non-entity subclasses
+    ├── _shapes.py       # Legacy shapes module
+    └── ui.py            # MESSAGE dialogs, Text renderer, and reactive Variable widget
+```
+
+## Author & Credits
+
+Created and maintained by **Siddharth Barnwal** (`Enirb` / `beast.barnwal`).