aether-engine 1.8.0__tar.gz → 1.8.2__tar.gz

{aether_engine-1.8.0 → aether_engine-1.8.2}/MANIFEST.in

@@ -1,13 +1,16 @@
 include README.md
 include LICENSE
 include pyproject.toml
+include docs/GUIDE.md
 
 recursive-include aether *.py
 recursive-include aether *.glsl
 recursive-include aether *.vert
 recursive-include aether *.frag
 recursive-include aether *.json
+recursive-include aether *.md
 recursive-include aether/assets *
+recursive-include aether/docs *
 
 recursive-include examples *.py
 

{aether_engine-1.8.0/aether_engine.egg-info → aether_engine-1.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aether-engine
-Version: 1.8.0
+Version: 1.8.2
 Summary: 3D/2D game engine by entiti937 — OpenGL, physics, FPS, mandatory branding splash
 Home-page: https://pypi.org/project/aether-engine/
 Author: entiti937
@@ -31,13 +31,13 @@ Requires-Dist: trimesh>=3.21; extra == "models"
 Provides-Extra: build
 Requires-Dist: pyinstaller>=6.0; extra == "build"
 Provides-Extra: full
-Requires-Dist: pygame-ce>=2.5; extra == "full"
-Requires-Dist: trimesh>=3.21; extra == "full"
+Requires-Dist: freetype-py>=2.4; extra == "full"
 Requires-Dist: imageio>=2.31; extra == "full"
-Requires-Dist: pyinstaller>=6.0; extra == "full"
+Requires-Dist: trimesh>=3.21; extra == "full"
 Requires-Dist: pyyaml>=6.0; extra == "full"
+Requires-Dist: pyinstaller>=6.0; extra == "full"
+Requires-Dist: pygame-ce>=2.5; extra == "full"
 Requires-Dist: pymunk>=6.0; extra == "full"
-Requires-Dist: freetype-py>=2.4; extra == "full"
 Dynamic: author
 Dynamic: classifier
 Dynamic: description
@@ -52,7 +52,7 @@ Dynamic: summary
 # Aether Engine
 
 **3D / 2D игровой движок на Python + OpenGL**  
-**Разработчик:** entiti937 · **Версия:** 1.8.0 · **Лицензия:** MIT  
+**Разработчик:** entiti937 · **Версия:** 1.8.1 · **Лицензия:** MIT  
 **PyPI:** https://pypi.org/project/aether-engine/
 
 > Полное руководство: [`docs/GUIDE.md`](docs/GUIDE.md) · сайт: `aether website`
@@ -70,6 +70,12 @@ import aether          # правильно
 # import aether_engine  # НЕПРАВИЛЬНО — такого модуля нет
 ```
 
+## Что нового в 1.8.1
+
+- `Hud.draw_bar(x, y, w, h, value, max_value, color)` — простой и понятный вызов
+- `aether docs` печатает **полный** GUIDE.md (гайд вшит в пакет)
+- Координаты HUD явно: (0,0) = центр экрана
+
 ## Что нового в 1.8.0
 
 - `Scene.remove()` / `despawn()` / `find()`

{aether_engine-1.8.0 → aether_engine-1.8.2}/README.md

@@ -1,7 +1,7 @@
 # Aether Engine
 
 **3D / 2D игровой движок на Python + OpenGL**  
-**Разработчик:** entiti937 · **Версия:** 1.8.0 · **Лицензия:** MIT  
+**Разработчик:** entiti937 · **Версия:** 1.8.1 · **Лицензия:** MIT  
 **PyPI:** https://pypi.org/project/aether-engine/
 
 > Полное руководство: [`docs/GUIDE.md`](docs/GUIDE.md) · сайт: `aether website`
@@ -19,6 +19,12 @@ import aether          # правильно
 # import aether_engine  # НЕПРАВИЛЬНО — такого модуля нет
 ```
 
+## Что нового в 1.8.1
+
+- `Hud.draw_bar(x, y, w, h, value, max_value, color)` — простой и понятный вызов
+- `aether docs` печатает **полный** GUIDE.md (гайд вшит в пакет)
+- Координаты HUD явно: (0,0) = центр экрана
+
 ## Что нового в 1.8.0
 
 - `Scene.remove()` / `despawn()` / `find()`

{aether_engine-1.8.0 → aether_engine-1.8.2}/aether/__init__.py

@@ -31,7 +31,7 @@ from aether.audio.sfx import SfxBank
 from aether.resources.save_load import save_json, load_json
 from aether.physics.raycast import Raycaster
 
-__version__ = "1.8.0"
+__version__ = "1.8.2"
 
 from aether.graphics.voxel_mesh import ChunkedVoxelMesher
 from aether.accelerators import is_native_available, backend_name

{aether_engine-1.8.0 → aether_engine-1.8.2}/aether/cli.py

@@ -60,10 +60,15 @@ TRANSFORM
   tf.set_position(x,y,z) / set_rotation / set_scale
   tf.translate(dx,dy,dz)
 
-HUD
+HUD (координаты: 0,0 = ЦЕНТР экрана, +Y вверх; текста нет — пишите в title)
+  from aether import Hud
   engine.draw_hud = True
   hud = Hud(engine.renderer2d)
-  hud.clear(); hud.draw_crosshair(); hud.draw_bar(...); hud.draw_hotbar(...)
+  hud.clear()
+  # draw_bar(x, y, width, height, value, max_value, color)
+  hud.draw_bar(-500, 300, 200, 20, hp, 100, (0.8, 0.2, 0.2, 1.0))
+  hud.draw_crosshair()
+  engine.window.set_title(f"HP {{hp}}")
 
 FPS / КАМЕРА
   engine.enable_first_person(camera, eye_height=1.7, walk_speed=6)
@@ -96,10 +101,14 @@ NPC / НАГРАДЫ (RUST, опционально)
   engine.physics3d.create_body_for_entity(ent, collider=BoxCollider())
   engine.physics2d.create_box(x, y, w, h, mass=1.0)
 
-ВВОД
+ВВОД / МЫШЬ
   import glfw
   engine.input.get_key(glfw.KEY_W)
   engine.input.get_key_down(glfw.KEY_SPACE)
+  engine.capture_mouse(True)           # захват мыши (НЕ glfw на engine.window!)
+  dx, dy = engine.input.mouse_delta()  # движение мыши за кадр
+  engine.input.lock_cursor(False)      # отпустить курсор
+  # raw GLFW: engine.window.handle
 
 АПДЕЙТ
   engine.on_update(lambda dt: ...)
@@ -109,13 +118,13 @@ NPC / НАГРАДЫ (RUST, опционально)
   aether build my_game.py --name MyGame --console
 
 ИНСТРУМЕНТЫ
-  aether help          — эта справка
-  aether docs          — краткий гайд по API
-  aether website       — documentation site (domain in bell notifications)
+  aether help          — краткая шпаргалка
+  aether docs          — ПОЛНЫЙ гайд (весь GUIDE.md в терминал)
+  aether website       — HTML-сайт документации
   python -m aether website
   python games/aether_craft.py
 
-ПОЛНАЯ ДОКУМЕНТАЦИЯ: docs/GUIDE.md
+ПОЛНАЯ ДОКУМЕНТАЦИЯ: aether docs   |   сайт: aether website
 PyPI: https://pypi.org/project/aether-engine/
 """
 
@@ -126,12 +135,29 @@ def cmd_help(_args):
 
 
 def cmd_docs(_args):
-    guide = Path(__file__).resolve().parents[2] / "docs" / "GUIDE.md"
-    if guide.exists():
-        print(guide.read_text(encoding="utf-8"))
-    else:
-        print(QUICK_REFERENCE)
-    return 0
+    """Print the full bundled developer guide."""
+    here = Path(__file__).resolve().parent
+    candidates = [
+        here / "docs" / "GUIDE.md",
+        here.parents[1] / "docs" / "GUIDE.md",
+        here.parents[0] / "docs" / "GUIDE.md",
+    ]
+    for guide in candidates:
+        if guide.exists():
+            text = guide.read_text(encoding="utf-8")
+            try:
+                sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+            try:
+                print(text)
+            except UnicodeEncodeError:
+                sys.stdout.buffer.write(text.encode("utf-8", errors="replace"))
+                sys.stdout.buffer.write(b"\n")
+            return 0
+    print(QUICK_REFERENCE)
+    print("\n[aether docs] GUIDE.md not found in package — reinstall: pip install -U aether-engine")
+    return 1
 
 
 def cmd_build(args):
@@ -161,8 +187,8 @@ def main(argv=None):
 
     sub = parser.add_subparsers(dest="command")
 
-    sub.add_parser("help", help="Краткая справка по API и командам").set_defaults(func=cmd_help)
-    sub.add_parser("docs", help="Полная документация").set_defaults(func=cmd_docs)
+    sub.add_parser("help", help="Краткая шпаргалка").set_defaults(func=cmd_help)
+    sub.add_parser("docs", help="Полный гайд разработчика (весь GUIDE.md)").set_defaults(func=cmd_docs)
 
     p_build = sub.add_parser("build", help="Собрать игру в .exe (PyInstaller)")
     p_build.add_argument("script", help="Путь к main.py игры")

{aether_engine-1.8.0 → aether_engine-1.8.2}/aether/core/_identity.py

@@ -20,7 +20,7 @@ _B = {
     ]),
     "sig": bytes([
         230, 194, 211, 207, 194, 213, 135, 226, 201, 192, 206, 201, 194,
-        135, 150, 137, 159, 137, 151,
+        135, 150, 137, 159, 137, 149,
     ]),
 }
 

{aether_engine-1.8.0 → aether_engine-1.8.2}/aether/core/engine.py

@@ -377,6 +377,10 @@ class Engine:
             self.renderer2d.render()
             self.renderer2d.end_frame()
 
+    def capture_mouse(self, locked: bool = True):
+        """Lock/unlock cursor for custom camera control. Same as input.lock_cursor()."""
+        self.input.lock_cursor(locked)
+
     def on_update(self, callback):
         """Регистрирует callback(dt), вызываемый каждый кадр."""
         self._update_callbacks.append(callback)

{aether_engine-1.8.0 → aether_engine-1.8.2}/aether/core/input.py

@@ -57,6 +57,7 @@ class Input:
         self._mouse_buttons_prev = self._mouse_buttons.copy()
 
     def lock_cursor(self, locked: bool = True):
+        """Capture mouse for FPS / orbit camera. Use engine.input.lock_cursor(True)."""
         self.cursor_locked = locked
         mode = glfw.CURSOR_DISABLED if locked else glfw.CURSOR_NORMAL
         glfw.set_input_mode(self.window.handle, glfw.CURSOR, mode)
@@ -66,6 +67,14 @@ class Input:
         self.mouse_dx = 0.0
         self.mouse_dy = 0.0
 
+    def mouse_delta(self) -> tuple:
+        """Mouse movement since last frame (dx, dy). Requires lock_cursor(True) for FPS."""
+        return (self.mouse_dx, self.mouse_dy)
+
+    def get_cursor_pos(self) -> tuple:
+        """Window cursor position in pixels (x, y)."""
+        return (self.mouse_x, self.mouse_y)
+
     def get_key(self, key) -> bool:
         return self._keys.get(key, False)
 

aether_engine-1.8.2/aether/docs/GUIDE.md

@@ -0,0 +1,390 @@
+# Aether Engine — Full Guide (v1.8.2)
+
+**PyPI:** `pip install aether-engine` → **import:** `import aether` (NOT `aether_engine`)
+
+Commands: `aether help` | `aether docs` (this file) | `aether website`
+
+---
+
+## 1. Engine
+
+```python
+from aether import Engine
+
+engine = Engine(width=1280, height=720, title="My Game")
+engine.load_scene(scene)
+engine.on_update(my_update)      # def my_update(dt): ...
+engine.run()                    # blocks until ESC
+
+# Properties
+engine.scene          # current Scene
+engine.input          # keyboard / mouse
+engine.window         # Window (title, size, .handle for raw GLFW)
+engine.renderer       # 3D renderer
+engine.renderer2d     # 2D / HUD sprites
+engine.physics2d      # pymunk
+engine.physics3d      # lightweight 3D
+engine.time.fps       # float
+engine.free_camera    # True = built-in WASD fly (set False for custom cam)
+engine.draw_hud       # True = render HUD overlay each frame
+engine.mode           # "3d" or "2d"
+
+# Methods
+engine.set_mode("2d")
+engine.enable_first_person(camera, eye_height=1.7, walk_speed=6)
+engine.capture_mouse(True)        # lock cursor — use this, NOT glfw on window directly
+engine.on_update(callback)
+engine.run()
+engine.shutdown()
+```
+
+---
+
+## 2. Input (keyboard / mouse)
+
+**Never pass `engine.window` to glfw directly.** Use `engine.window.handle` only if you need raw GLFW.
+
+```python
+import glfw
+
+inp = engine.input
+
+# Keyboard
+inp.get_key(glfw.KEY_W)           # held
+inp.get_key_down(glfw.KEY_SPACE)  # pressed this frame
+inp.get_key_up(glfw.KEY_E)
+
+# Mouse buttons
+inp.get_mouse_button(glfw.MOUSE_BUTTON_LEFT)
+inp.get_mouse_button_down(glfw.MOUSE_BUTTON_RIGHT)
+
+# Mouse look (FPS / orbit)
+inp.lock_cursor(True)             # or engine.capture_mouse(True)
+dx, dy = inp.mouse_delta()        # movement since last frame
+# Also: inp.mouse_dx, inp.mouse_dy
+
+# Toggle capture (like Tab in free camera)
+if inp.get_key_down(glfw.KEY_TAB):
+    inp.lock_cursor(not inp.cursor_locked)
+
+# Cursor position in pixels
+x, y = inp.get_cursor_pos()
+```
+
+---
+
+## 3. Window
+
+```python
+w = engine.window
+w.set_title("HP 80 | score 5")
+w.width, w.height
+w.handle    # raw GLFW window — for glfw.get_cursor_pos(engine.window.handle) etc.
+# Do NOT: glfw.set_input_mode(engine.window, ...)  — wrong type
+# Do:     engine.input.lock_cursor(True)
+```
+
+---
+
+## 4. Scene
+
+```python
+from aether import Scene
+
+scene = Scene("Level1")
+scene.spawn(entity)
+scene.remove(entity)    # removes from scene + entity.destroy()
+scene.despawn(entity)   # alias
+found = scene.find("Player")
+scene.set_main_camera(camera)
+scene.entities        # list
+```
+
+---
+
+## 5. Entity
+
+```python
+from aether import Entity, Transform, MeshRenderer
+
+ent = Entity("Player")
+ent.add_component(Transform(position=(0, 1, 0)))
+ent.add_component(MeshRenderer(mesh=..., material=...))
+ent.get_component("Transform")
+ent.remove_component("MeshRenderer")
+ent.destroy()         # prefer scene.remove(ent)
+ent.enabled = True
+```
+
+---
+
+## 6. Transform
+
+`position`, `rotation`, `scale` = **numpy float32[3]**. Rotation in **degrees**.
+
+```python
+tf = Transform(position=(0, 1, 0), rotation=(0, 45, 0), scale=(1, 1, 1))
+tf.set_position(x, y, z)
+tf.position[:] = (1, 2, 3)
+tf.position[1] += 0.1
+tf.set_rotation(rx, ry, rz)
+tf.set_scale(sx, sy, sz)
+tf.translate(dx, dy, dz)
+tf.rotate(0, 90 * dt, 0)
+tf.look_at(target_xyz)
+tf.get_model_matrix()
+```
+
+---
+
+## 7. Camera
+
+```python
+from aether import Camera
+
+cam = Camera(position=(0, 5, 10), yaw=-90, pitch=-20, fov=60)
+cam.position = (x, y, z)
+cam.yaw, cam.pitch, cam.fov, cam.near, cam.far
+cam.front, cam.right, cam.up
+cam.look_at(player_tf.position)
+cam.rotate(mouse_dx, mouse_dy)
+cam.move_forward(dt)
+
+# Third-person — disable built-in fly camera first
+engine.free_camera = False
+cam.position = (px, py + 6, pz + 10)
+cam.look_at(target)
+```
+
+---
+
+## 8. MeshFactory
+
+```python
+from aether import MeshFactory
+
+MeshFactory.create_cube(size=1.0)
+MeshFactory.create_plane(size=10.0)
+MeshFactory.create_sphere(radius=1.0, sectors=24, stacks=16)
+MeshFactory.create_cylinder(radius=0.5, height=2.0, segments=24, capped=True)
+MeshFactory.create_pyramid(size=1.0, height=1.0)
+```
+
+---
+
+## 9. Material
+
+```python
+from aether import Material
+
+mat = Material("wood")
+mat.albedo[:] = (0.8, 0.5, 0.2)   # RGB 0..1
+mat.metallic = 0.0
+mat.roughness = 0.6
+mat.ao = 1.0
+```
+
+---
+
+## 10. HUD
+
+Origin **(0,0) = center of screen**, +Y up. **No text rendering** — use `engine.window.set_title(...)`.
+
+```python
+from aether import Hud, HudBar
+
+engine.draw_hud = True
+hud = Hud(engine.renderer2d)
+
+def update(dt):
+    hud.clear()
+    hud.draw_bar(-500, 300, 200, 20, hp, 100, (0.8, 0.2, 0.2, 1.0))
+    hud.draw_crosshair()
+    hud.draw_hotbar(7, 0, colors=[(1,0,0),(0,1,0)])
+    hud.draw_rect(0, -250, 100, 30, color=(0,0,0,0.5))
+    hud.draw_panel(0, 250, 300, 60)
+    engine.window.set_title(f"HP {hp}")
+```
+
+---
+
+## 11. Assets
+
+```python
+from aether import AssetLoader, Sprite
+
+mesh = AssetLoader.load_model("hero.glb")
+sprite = Sprite.from_image("icon.png", x=0, y=0)
+```
+
+---
+
+## 12. Physics
+
+**2D:** `engine.physics2d` (pymunk) — Y-up, sync `sprite.x, sprite.y = body.x, body.y`  
+**3D:** `engine.physics3d` — lightweight; PyBullet planned
+
+```python
+from aether import BoxCollider
+body = engine.physics3d.create_body_for_entity(ent, mass=1.0, collider=BoxCollider(size=(1,1,1)))
+```
+
+---
+
+# EXAMPLE GAMES (copy-paste)
+
+## Example A — Hello Cube (3D basics)
+
+```python
+from aether import Engine, Scene, Entity, Transform, MeshRenderer, MeshFactory, Material, Camera
+
+engine = Engine(1280, 720, "Hello Cube")
+scene = Scene("Main")
+camera = Camera(position=(0, 4, 8), yaw=-90, pitch=-25)
+scene.set_main_camera(camera)
+
+floor = Entity("Floor")
+floor.add_component(Transform(position=(0, -1, 0)))
+m = Material(); m.albedo[:] = (0.7, 0.7, 0.8)
+floor.add_component(MeshRenderer(mesh=MeshFactory.create_plane(12), material=m))
+scene.spawn(floor)
+
+cube = Entity("Cube")
+cube.add_component(Transform(position=(0, 1.5, 0), scale=(2, 2, 2)))
+m2 = Material(); m2.albedo[:] = (0.1, 1.0, 0.2)
+cube.add_component(MeshRenderer(mesh=MeshFactory.create_cube(), material=m2))
+scene.spawn(cube)
+
+engine.load_scene(scene)
+engine.run()
+```
+
+## Example B — Sphere ring (materials)
+
+```python
+import math
+from aether import Engine, Scene, Entity, Transform, MeshRenderer, MeshFactory, Material, Camera
+
+engine = Engine(1280, 720, "Spheres")
+scene = Scene("Spheres")
+scene.set_main_camera(Camera(position=(0, 5, 15), yaw=-90, pitch=-20))
+
+floor = Entity("Floor")
+fm = Material(); fm.albedo[:] = (0.55, 0.58, 0.65)
+floor.add_component(Transform(position=(0, -0.5, 0)))
+floor.add_component(MeshRenderer(mesh=MeshFactory.create_plane(14), material=fm))
+scene.spawn(floor)
+
+for i in range(12):
+    a = i * math.pi * 2 / 12
+    mat = Material(); mat.albedo[:] = (0.3 + i*0.05, 0.5, 0.8 - i*0.04)
+    s = Entity(f"S{i}")
+    s.add_component(Transform(position=(math.cos(a)*4, 0.5, math.sin(a)*4)))
+    s.add_component(MeshRenderer(mesh=MeshFactory.create_sphere(0.5), material=mat))
+    scene.spawn(s)
+
+engine.load_scene(scene)
+engine.run()
+```
+
+## Example C — First person (FPS)
+
+```python
+from aether import Engine, Scene, Entity, Transform, MeshRenderer, MeshFactory, Material, Camera
+
+engine = Engine(1280, 720, "FPS")
+scene = Scene("FPS")
+cam = Camera(position=(0, 1.7, 8), yaw=-90, fov=75)
+scene.set_main_camera(cam)
+
+floor = Entity("Floor")
+floor.add_component(Transform())
+m = Material(); m.albedo[:] = (0.3, 0.34, 0.4)
+floor.add_component(MeshRenderer(mesh=MeshFactory.create_plane(40), material=m))
+scene.spawn(floor)
+
+engine.load_scene(scene)
+engine.enable_first_person(cam)
+engine.run()
+```
+
+## Example D — 2D platformer (pymunk)
+
+```python
+import glfw
+from aether import Engine, Sprite
+
+engine = Engine(960, 540, "2D")
+engine.set_mode("2d")
+engine.free_camera = False
+r = engine.renderer2d
+r.camera.zoom = 0.035
+
+player_sprite = r.add_sprite(Sprite(x=-200, y=0, width=36, height=48, color=(0.2, 0.85, 1, 1)))
+phys = engine.physics2d
+phys.create_box(0, -120, 700, 40, static=True)
+player = phys.create_box(-200, 0, 36, 48, mass=1.0)
+
+def update(dt):
+    vx = 0
+    if engine.input.get_key(glfw.KEY_A): vx -= 260
+    if engine.input.get_key(glfw.KEY_D): vx += 260
+    phys.set_velocity(player, vx, player.vy)
+    if engine.input.get_key_down(glfw.KEY_SPACE) and abs(player.vy) < 20:
+        phys.apply_impulse(player, 0, 420)
+    player_sprite.x, player_sprite.y = player.x, player.y
+
+engine.on_update(update)
+engine.run()
+```
+
+## Example E — Custom camera + mouse (like your game)
+
+```python
+import glfw
+import math
+from aether import Engine, Scene, Entity, Transform, MeshRenderer, MeshFactory, Material, Camera, Hud
+
+engine = Engine(1280, 720, "Third Person")
+scene = Scene("Main")
+cam = Camera(position=(0, 5, 10), yaw=-90, pitch=-30)
+scene.set_main_camera(cam)
+engine.free_camera = False
+engine.capture_mouse(True)   # NOT glfw.set_input_mode(engine.window, ...)
+
+player = Entity("Player")
+ptf = Transform(position=(0, 0.5, 0))
+player.add_component(ptf)
+m = Material(); m.albedo[:] = (0.2, 0.6, 1.0)
+player.add_component(MeshRenderer(mesh=MeshFactory.create_cube(), material=m))
+scene.spawn(player)
+
+yaw, pitch, dist = 0.0, 0.6, 10.0
+engine.draw_hud = True
+hud = Hud(engine.renderer2d)
+
+def update(dt):
+    global yaw, pitch
+    if engine.input.get_key(glfw.KEY_TAB):
+        engine.capture_mouse(not engine.input.cursor_locked)
+    mdx, mdy = engine.input.mouse_delta()
+    yaw += mdx * 0.003
+    pitch = max(0.1, min(1.5, pitch - mdy * 0.003))
+    t = ptf.position
+    cam.position = (
+        t[0] + dist * math.cos(pitch) * math.sin(yaw),
+        t[1] + dist * math.sin(pitch),
+        t[2] + dist * math.cos(pitch) * math.cos(yaw),
+    )
+    cam.look_at(t)
+    hud.clear()
+    hud.draw_crosshair()
+
+engine.on_update(update)
+engine.load_scene(scene)
+engine.run()
+```
+
+---
+
+Aether Engine © entiti937