aether-engine 1.7.1__tar.gz → 1.8.1__tar.gz

{aether_engine-1.7.1 → aether_engine-1.8.1}/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.7.1/aether_engine.egg-info → aether_engine-1.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aether-engine
-Version: 1.7.1
+Version: 1.8.1
 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: pyinstaller>=6.0; extra == "full"
-Requires-Dist: pygame-ce>=2.5; extra == "full"
-Requires-Dist: imageio>=2.31; extra == "full"
-Requires-Dist: trimesh>=3.21; extra == "full"
 Requires-Dist: pymunk>=6.0; extra == "full"
+Requires-Dist: imageio>=2.31; extra == "full"
 Requires-Dist: pyyaml>=6.0; extra == "full"
+Requires-Dist: pyinstaller>=6.0; extra == "full"
 Requires-Dist: freetype-py>=2.4; extra == "full"
+Requires-Dist: trimesh>=3.21; extra == "full"
+Requires-Dist: pygame-ce>=2.5; extra == "full"
 Dynamic: author
 Dynamic: classifier
 Dynamic: description
@@ -52,10 +52,10 @@ Dynamic: summary
 # Aether Engine
 
 **3D / 2D игровой движок на Python + OpenGL**  
-**Разработчик:** entiti937 · **Версия:** 1.7.1 · **Лицензия:** MIT  
+**Разработчик:** entiti937 · **Версия:** 1.8.1 · **Лицензия:** MIT  
 **PyPI:** https://pypi.org/project/aether-engine/
 
-> Полное руководство: [`docs/GUIDE.md`](docs/GUIDE.md)
+> Полное руководство: [`docs/GUIDE.md`](docs/GUIDE.md) · сайт: `aether website`
 
 ---
 
@@ -65,38 +65,24 @@ Dynamic: summary
 pip install -U "aether-engine[full]"
 ```
 
-## Что нового в 1.7.1
-
-- Документация: 2D-физика (pymunk), статус 3D-солвера, GLFW vs pygame-ce
-- Единый импорт компонентов из `aether`
-- Расширен раздел Performance
-
-## Что нового в 1.7.0
-
-- **AssetLoader** — загрузка любых моделей, спрайтов и текстур (OBJ/GLB/FBX/PNG/WebP/…)
-- `Sprite.from_image(path)` — быстрый импорт 2D-графики
-- Встроенный редактор **убран** (может вернуться в будущих версиях)
-
-## Showcase-игра
-
-Minecraft-like sandbox **на этом же движке**:
-
-```bash
-aether help
-aether build games/aether_craft.py --name AetherCraft
-python games/aether_craft.py
+```python
+import aether          # правильно
+# import aether_engine  # НЕПРАВИЛЬНО — такого модуля нет
 ```
 
-Там есть: воксельный мир, вид от 1 лица, ломать/ставить блоки, HUD, звуки, день/ночь, сейвы (F5/F9), урон и респавн.
+## Что нового в 1.8.1
 
-## Другие запуски
+- `Hud.draw_bar(x, y, w, h, value, max_value, color)` — простой и понятный вызов
+- `aether docs` печатает **полный** GUIDE.md (гайд вшит в пакет)
+- Координаты HUD явно: (0,0) = центр экрана
 
-```bash
-python games/orb_rush.py
-python examples/03_first_person.py
-python examples/04_physics2d.py
-aether website
-```
+## Что нового в 1.8.0
+
+- `Scene.remove()` / `despawn()` / `find()`
+- `MeshFactory.create_cylinder(...)`
+- `Camera.look_at(target)` + безопасное присвоение `cam.position = (x,y,z)`
+- HUD: `draw_rect`, `draw_panel`
+- Полный **API Reference** в документации (и `/plain/all` для ИИ)
 
 ## Минимальный код
 
@@ -123,20 +109,22 @@ engine.enable_first_person(camera)
 engine.run()
 ```
 
-## Возможности
+## Частые операции
 
-- PBR 3D + sprites 2D + HUD overlay
-- FPS (`enable_first_person`) и free-look камера
-- Физика 3D/2D + raycast
-- `AssetLoader` / `ModelLoader` — OBJ/GLB/glTF/STL/FBX/STEP/… + PNG/WebP спрайты
-- Procedural SFX, JSON save/load
-- Примеры и игры в репозитории
-
-> Встроенный редактор моделей/пиксель-арт **временно убран** — планируется вернуть позже. Сейчас используйте Blender, Aseprite и т.д., файлы подгружайте через `AssetLoader`.
+```python
+scene.remove(entity)                 # удалить объект
+MeshFactory.create_cylinder(0.5, 2)  # цилиндр
+cam.look_at(player_tf.position)      # смотреть на игрока
+engine.free_camera = False           # своя камера (не WASD fly)
+```
 
-## Документация
+## Возможности
 
-Все команды, API и туториалы: **[docs/GUIDE.md](docs/GUIDE.md)**
+- PBR 3D + sprites 2D + HUD overlay
+- FPS / free-look / `look_at` follow-камера
+- Физика 2D (pymunk) + лёгкий 3D solver
+- `AssetLoader` — модели и спрайты
+- `aether website` + plain docs для LLM
 
 ---
 

aether_engine-1.8.1/README.md

@@ -0,0 +1,80 @@
+# Aether Engine
+
+**3D / 2D игровой движок на Python + OpenGL**  
+**Разработчик:** entiti937 · **Версия:** 1.8.1 · **Лицензия:** MIT  
+**PyPI:** https://pypi.org/project/aether-engine/
+
+> Полное руководство: [`docs/GUIDE.md`](docs/GUIDE.md) · сайт: `aether website`
+
+---
+
+## Установка
+
+```bash
+pip install -U "aether-engine[full]"
+```
+
+```python
+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()`
+- `MeshFactory.create_cylinder(...)`
+- `Camera.look_at(target)` + безопасное присвоение `cam.position = (x,y,z)`
+- HUD: `draw_rect`, `draw_panel`
+- Полный **API Reference** в документации (и `/plain/all` для ИИ)
+
+## Минимальный код
+
+```python
+from aether import (
+    Engine, Scene, Entity, Transform, MeshRenderer,
+    MeshFactory, Material, Camera,
+)
+
+engine = Engine(1280, 720, "Game by you — engine by entiti937")
+scene = Scene("Main")
+camera = Camera(position=(0, 2, 6), yaw=-90)
+scene.set_main_camera(camera)
+
+cube = Entity("Cube")
+cube.add_component(Transform(position=(0, 1, 0)))
+mat = Material()
+mat.albedo[:] = (0.2, 0.85, 1.0)
+cube.add_component(MeshRenderer(mesh=MeshFactory.create_cube(), material=mat))
+scene.spawn(cube)
+
+engine.load_scene(scene)
+engine.enable_first_person(camera)
+engine.run()
+```
+
+## Частые операции
+
+```python
+scene.remove(entity)                 # удалить объект
+MeshFactory.create_cylinder(0.5, 2)  # цилиндр
+cam.look_at(player_tf.position)      # смотреть на игрока
+engine.free_camera = False           # своя камера (не WASD fly)
+```
+
+## Возможности
+
+- PBR 3D + sprites 2D + HUD overlay
+- FPS / free-look / `look_at` follow-камера
+- Физика 2D (pymunk) + лёгкий 3D solver
+- `AssetLoader` — модели и спрайты
+- `aether website` + plain docs для LLM
+
+---
+
+Aether Engine © **entiti937**

{aether_engine-1.7.1 → aether_engine-1.8.1}/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.7.1"
+__version__ = "1.8.1"
 
 from aether.graphics.voxel_mesh import ChunkedVoxelMesher
 from aether.accelerators import is_native_available, backend_name

{aether_engine-1.7.1 → aether_engine-1.8.1}/aether/cli.py

@@ -15,6 +15,8 @@ QUICK_REFERENCE = f"""
 
 УСТАНОВКА
   pip install -U "aether-engine[full]"
+  # пакет на PyPI: aether-engine
+  # импорт в коде:  import aether   (НЕ aether_engine)
 
 МИНИМАЛЬНЫЙ КОД (3D)
   from aether import Engine, Scene, Entity, Transform, MeshRenderer, MeshFactory, Material, Camera
@@ -26,7 +28,8 @@ QUICK_REFERENCE = f"""
 
   cube = Entity("Cube")
   cube.add_component(Transform(position=(0, 1, 0)))
-  mat = Material(); mat.albedo[:] = (0.2, 0.9, 0.3)
+  mat = Material()
+  mat.albedo[:] = (0.2, 0.9, 0.3)
   cube.add_component(MeshRenderer(mesh=MeshFactory.create_cube(), material=mat))
   scene.spawn(cube)
 
@@ -34,6 +37,39 @@ QUICK_REFERENCE = f"""
   engine.enable_first_person(cam)   # FPS
   engine.run()                      # ESC — выход
 
+УДАЛЕНИЕ ОБЪЕКТОВ
+  scene.remove(entity)     # убрать из сцены + destroy()
+  # или entity.destroy()  # только компоненты (лучше scene.remove)
+
+ПРИМИТИВЫ MeshFactory
+  create_cube(size=1)
+  create_plane(size=10)
+  create_sphere(radius=1, sectors=24, stacks=16)
+  create_cylinder(radius=0.5, height=1, segments=24)
+  create_pyramid(size=1, height=1)
+
+КАМЕРА
+  cam.position = (x, y, z)   # numpy array под капотом
+  cam.yaw, cam.pitch, cam.fov
+  cam.look_at(target)        # смотреть на точку/игрока
+  cam.rotate(dx, dy)
+  engine.free_camera = False # если управляете камерой сами
+
+TRANSFORM
+  tf.position  # np.ndarray float32, можно tf.position[:] = (x,y,z)
+  tf.set_position(x,y,z) / set_rotation / set_scale
+  tf.translate(dx,dy,dz)
+
+HUD (координаты: 0,0 = ЦЕНТР экрана, +Y вверх; текста нет — пишите в title)
+  from aether import Hud
+  engine.draw_hud = True
+  hud = Hud(engine.renderer2d)
+  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)
   engine.free_camera = True         # WASD + Tab (мышь)
@@ -78,13 +114,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/
 """
 
@@ -95,12 +131,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):
@@ -130,8 +183,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.7.1 → aether_engine-1.8.1}/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, 144, 137, 150,
+        135, 150, 137, 159, 137, 150,
     ]),
 }
 

aether_engine-1.8.1/aether/docs/GUIDE.md

@@ -0,0 +1,270 @@
+# Aether Engine — Full Developer Guide
+
+**Version:** 1.8.1 · **Author:** entiti937 · **License:** MIT  
+**PyPI package:** `aether-engine`  
+**Python import:** `import aether`  ← NEVER `import aether_engine`
+
+Commands:
+- `aether help` — short cheat sheet
+- `aether docs` — **this full guide** (printed to terminal)
+- `aether website` — local HTML docs (+ `/plain/all` for AI)
+
+---
+
+## 0. Exact package names
+
+```bash
+pip install -U "aether-engine[full]"
+```
+
+```python
+from aether import Engine, Scene, Entity, Transform, MeshRenderer
+from aether import MeshFactory, Material, Camera, Hud, HudBar, Sprite, AssetLoader
+```
+
+---
+
+## 1. Minimal 3D game
+
+```python
+from aether import (
+    Engine, Scene, Entity, Transform, MeshRenderer,
+    MeshFactory, Material, Camera,
+)
+
+engine = Engine(1280, 720, "My Game")
+scene = Scene("Main")
+camera = Camera(position=(0, 2, 8), yaw=-90, pitch=-15)
+scene.set_main_camera(camera)
+
+cube = Entity("Cube")
+cube.add_component(Transform(position=(0, 1, 0)))
+mat = Material("green")
+mat.albedo[:] = (0.2, 0.9, 0.4)
+cube.add_component(MeshRenderer(mesh=MeshFactory.create_cube(), material=mat))
+scene.spawn(cube)
+
+engine.load_scene(scene)
+engine.enable_first_person(camera)
+engine.run()  # blocks until ESC
+```
+
+---
+
+## 2. Scene — add / remove objects
+
+```python
+scene.spawn(entity)          # add
+scene.remove(entity)         # REMOVE from scene + destroy()  ← use this to delete
+scene.despawn(entity)        # same as remove
+found = scene.find("Player") # Entity or None
+```
+
+**Important:** `entity.destroy()` alone does NOT remove it from `scene.entities`. Always prefer `scene.remove(entity)`.
+
+---
+
+## 3. Transform
+
+`position`, `rotation`, `scale` = **numpy float32 arrays** length 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.translate(dx, dy, dz)
+tf.set_rotation(rx, ry, rz)
+tf.rotate(0, 90 * dt, 0)
+tf.set_scale(sx, sy, sz)
+```
+
+---
+
+## 4. Camera
+
+```python
+cam = Camera(position=(0, 5, 10), yaw=-90, pitch=-20, fov=60)
+cam.position = (x, y, z)     # tuple OK
+cam.yaw = -45
+cam.pitch = -15
+cam.look_at(target)          # world point or player_tf.position
+cam.rotate(dx, dy)           # mouse deltas
+```
+
+Third-person follow:
+
+```python
+engine.free_camera = False   # REQUIRED when you move the camera yourself
+target = player_tf.position
+cam.position = (target[0], target[1] + 6, target[2] + 10)
+cam.look_at(target)
+```
+
+FPS: `engine.enable_first_person(camera, eye_height=1.7, walk_speed=6)`
+
+---
+
+## 5. MeshFactory — ALL primitives
+
+| Method | Signature |
+|--------|-----------|
+| cube | `create_cube(size=1.0)` |
+| plane | `create_plane(size=10.0)` |
+| sphere | `create_sphere(radius=1.0, sectors=24, stacks=16)` |
+| cylinder | `create_cylinder(radius=0.5, height=1.0, segments=24, capped=True)` |
+| pyramid | `create_pyramid(size=1.0, height=1.0)` |
+
+```python
+MeshFactory.create_cylinder(radius=0.8, height=3.0, segments=24)
+```
+
+---
+
+## 6. Material
+
+```python
+mat = Material("metal")
+mat.albedo[:] = (0.9, 0.2, 0.2)  # RGB 0..1 numpy
+mat.metallic = 0.8
+mat.roughness = 0.3
+mat.ao = 1.0
+```
+
+---
+
+## 7. HUD — exact API (read carefully)
+
+Enable overlay:
+
+```python
+from aether import Hud, HudBar
+
+engine.draw_hud = True
+hud = Hud(engine.renderer2d)
+```
+
+**Coordinates:** origin `(0,0)` = **center of the window**, +X right, +Y up.  
+Not top-left pixels. On 1280×720, top-left area ≈ `(-500, 300)`.
+
+**No bitmap text yet.** Put strings in the window title:
+
+```python
+engine.window.set_title(f"HP {hp} | score {score}")
+```
+
+### draw_bar — exact signatures
+
+```python
+# RECOMMENDED — current value + max value + color
+hud.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))
+
+# Fraction 0..1 only
+hud.draw_bar(-500, 300, 200, 20, 0.75)
+
+# HudBar object
+hud.draw_bar(-500, 300, 200, 20, HudBar("hp", value=0.75, color=(0.8, 0.2, 0.2, 1.0)))
+```
+
+### Other HUD methods
+
+```python
+hud.clear()                              # call every frame before drawing
+hud.draw_crosshair(size=10, thickness=2)
+hud.draw_hotbar(slots=7, selected=0, colors=[(1,0,0), (0,1,0)], y=-220)
+hud.draw_rect(x, y, width, height, color=(1,1,1,1), layer=70)
+hud.draw_panel(x, y, width, height)
+```
+
+Full frame example:
+
+```python
+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()
+    engine.window.set_title(f"HP {hp}")
+```
+
+---
+
+## 8. Assets
+
+```python
+from aether import AssetLoader, Sprite
+
+mesh = AssetLoader.load_model("hero.glb")
+sprite = Sprite.from_image("icon.png", x=0, y=0)
+tex_id = AssetLoader.load_texture("wall.jpg")
+```
+
+---
+
+## 9. Physics
+
+**2D (ready):** `engine.physics2d` (pymunk) — see `examples/04_physics2d.py`
+
+```python
+engine.set_mode("2d")
+pw = engine.physics2d
+ground = pw.create_box(0, -200, 600, 40, static=True)
+ball = pw.create_circle(0, 0, 20, mass=1.0)
+sprite.x, sprite.y = ball.x, ball.y   # Y-up, same space
+```
+
+**3D:** lightweight built-in solver. PyBullet/Jolt planned later.
+
+```python
+from aether import BoxCollider
+body = engine.physics3d.create_body_for_entity(ent, mass=1.0, collider=BoxCollider(size=(1,1,1)))
+```
+
+---
+
+## 10. Input / update
+
+```python
+import glfw
+
+def update(dt):
+    if engine.input.get_key(glfw.KEY_W):
+        ...
+    if engine.input.get_key_down(glfw.KEY_SPACE):
+        ...
+
+engine.on_update(update)
+```
+
+---
+
+## 11. Window vs audio
+
+- **GLFW** — window, input, OpenGL 4.6  
+- **pygame-ce** — sound mixer only (display never initialized)
+
+---
+
+## 12. CLI
+
+```bash
+aether help
+aether docs          # full guide (this file)
+aether website       # HTML docs on localhost
+aether build game.py --name MyGame
+```
+
+---
+
+## 13. Examples
+
+| File | Topic |
+|------|--------|
+| `examples/01_hello_cube.py` | Basics |
+| `examples/02_sphere_scene.py` | Materials |
+| `examples/03_first_person.py` | FPS |
+| `examples/04_physics2d.py` | 2D physics |
+
+---
+
+Aether Engine © entiti937