Three-dimensional-Games 0.3.0__py3-none-any.whl

three_dimensional_games/__init__.py

@@ -0,0 +1,256 @@
+"""
+Three-dimensional-Games 3D Game Engine
+======================================
+比 Ursina 更简洁：开头一行 init() 拿到 game，结尾一行 run() 启动；
+同时又像 Panda3D 一样严谨实用，内置物理、联机、三种视角控制器、
+大量贴图、补间动画、粒子、音效、触发区等模块。
+
+标准写法（开头初始化 + 结尾启动）：
+    from three_dimensional_games import *
+
+    game = init(title="我的 3D 游戏")
+
+    ground = Entity(model='plane', texture='grass', scale=50, collider='box')
+    player = FirstPerson()
+    player.y = 2
+
+    run()
+
+也兼容“省略 init / run”的极简写法（引擎会自己兜底）：
+    from three_dimensional_games import *
+    Entity(model='cube', collider='box', mass=1)
+    FirstPerson()
+    # 不用写 run()，脚本结束时也会自动运行
+"""
+
+__version__ = "0.3.0"
+__author__ = "Your Name"
+
+import atexit
+
+# ----------------------------------------------------------------------------
+# 引擎实例：init() 显式创建，或按需自动创建
+# ----------------------------------------------------------------------------
+_app = None
+_explicit_run = False
+
+
+def init(title: str = "Three-dimensional Game", **kwargs):
+    """
+    初始化游戏引擎，返回 game 对象（引擎实例）。写在脚本开头。
+
+    常用参数：
+        init(title='我的游戏', window_size=(1280, 720), fullscreen=False,
+             vsync=True, show_fps=True, background_color=(0.1, 0.1, 0.1, 1))
+    """
+    global _app
+    from .application import Application
+    if Application._instance is not None:
+        _app = Application._instance
+    else:
+        _app = Application(title=title, **kwargs)
+    return _app
+
+
+def run():
+    """启动游戏主循环。写在脚本最后一行。"""
+    global _app, _explicit_run
+    _app = _ensure_app()
+    _explicit_run = True
+    _app.run()
+
+
+def _ensure_app():
+    """确保引擎已创建（第一次创建 Entity / UI 时自动调用）"""
+    global _app
+    if _app is None:
+        from .application import Application
+        if Application._instance is not None:
+            _app = Application._instance
+        else:
+            _app = Application()
+    return _app
+
+
+def get_app():
+    """获取当前引擎实例；如果没有会自动创建一个"""
+    return _ensure_app()
+
+
+# ----------------------------------------------------------------------------
+# 核心 API（导入即可用）
+# ----------------------------------------------------------------------------
+from .application import Application
+from .entity import Entity
+from .vector import Vec2, Vec3, Vec4, to_panda_vec3, to_panda_vec2, to_panda_vec4
+from .color import Color, color
+from .scene import scene, camera
+from .input import input_handler, held_keys, mouse
+from .physics import BoxCollider, SphereCollider, MeshCollider, RigidBody, raycast, RaycastHit, physics_world
+from .models import load_model
+from .builtin_textures import TextureManager, textures as texture_manager
+from .ui import Text, Button, Slider, InputField, WindowPanel
+
+# 补间动画
+from .animation import (
+    Tween, Sequence, animate,
+    animate_position, animate_scale, animate_rotation, animate_color,
+    stop_all_tweens,
+)
+
+# 粒子
+from .particles import Particles, ParticleSystem
+
+# 音效
+from .audio import Audio, Sound, Music, tone, beep, set_master_volume
+
+# 触发区
+from .trigger import Trigger, on_enter, on_exit, clear_triggers
+
+# 存档 / 读档
+from .saveload import (
+    save, load, save_slot, load_slot, slot_path,
+    has_save, has_slot, delete_save, list_saves,
+)
+
+# 三种视角控制器 + 天空盒：名字更短，直接 FirstPerson() / SecondPerson() / ThirdPerson()
+from .prefabs import (
+    FirstPersonController,
+    SecondPersonController,
+    ThirdPersonController,
+    Sky,
+)
+FirstPerson = FirstPersonController
+SecondPerson = SecondPersonController
+ThirdPerson = ThirdPersonController
+
+# ----------------------------------------------------------------------------
+# 联机模块：host() 一行开房
+#     host(public=True)   -> 公网联机
+#     host(public=False)  -> 局域网联机
+# ----------------------------------------------------------------------------
+from .network import NetworkManager, NetworkPlayer
+
+network = NetworkManager()
+
+
+def host(public: bool = False, port: int = 5555, max_players: int = 16,
+         game_name: str = "Three-dimensional Game"):
+    """开房间。public=True 公网联机；public=False 局域网联机"""
+    _ensure_app()
+    return network.host(public=public, port=port, max_players=max_players, game_name=game_name)
+
+
+def connect(ip: str = "127.0.0.1", port: int = 5555, player_name: str = "Player"):
+    """加入别人的房间"""
+    _ensure_app()
+    return network.join(host_ip=ip, port=port, player_name=player_name)
+
+
+# ----------------------------------------------------------------------------
+# 高级射线 / 虚拟碰撞：准星射线、穿透、boxcast/spherecast/capsulecast、调试线、Layer
+# ----------------------------------------------------------------------------
+from .raycaster import (
+    Raycaster, raycaster, Layer,
+    camera_ray, screen_ray, mouse_ray, raycast_all,
+    boxcast, spherecast, capsulecast,
+    overlap_box, overlap_sphere, linecast,
+    LineRenderer, draw_line, draw_ray,
+    hit_distance_to, nearest_hit, hits_with_tag,
+)
+
+# 手柄
+from .gamepad import (
+    Gamepad, gamepad,
+    on_pad_press, on_pad_release, on_pad_axis, rumble, set_gamepad_deadzone,
+)
+
+# 语音：TTS 播报、麦克风录音、ASR 识别、联机语音
+from .voice import (
+    speak, say,
+    record, stop_recording, recognize, listen,
+    VoiceChat, voice_chat,
+    is_mic_available, is_tts_available,
+    set_voice_volume, get_voice_volume,
+    VoiceRecorder,
+)
+
+# ----------------------------------------------------------------------------
+# 常用工具函数
+# ----------------------------------------------------------------------------
+from .util import (
+    destroy,
+    invoke,
+    invoke_repeating,
+    random_range,
+    random_int,
+    random_color,
+    lerp,
+    lerp_color,
+    clamp,
+    distance,
+    sin,
+    cos,
+    tan,
+    time as get_time,
+)
+
+__all__ = [
+    "init", "run", "get_app", "Application",
+    "Entity",
+    "Vec2", "Vec3", "Vec4", "Color", "color",
+    "scene", "camera", "input_handler", "held_keys", "mouse",
+    "BoxCollider", "SphereCollider", "MeshCollider", "RigidBody", "raycast", "RaycastHit", "physics_world",
+    "load_model", "TextureManager", "texture_manager",
+    "Text", "Button", "Slider", "InputField", "WindowPanel",
+    "Tween", "Sequence", "animate",
+    "animate_position", "animate_scale", "animate_rotation", "animate_color", "stop_all_tweens",
+    "Particles", "ParticleSystem",
+    "Audio", "Sound", "Music", "tone", "beep", "set_master_volume",
+    "Trigger", "on_enter", "on_exit", "clear_triggers",
+    "save", "load", "save_slot", "load_slot", "slot_path",
+    "has_save", "has_slot", "delete_save", "list_saves",
+    "FirstPerson", "SecondPerson", "ThirdPerson", "Sky",
+    "FirstPersonController", "SecondPersonController", "ThirdPersonController",
+    "network", "NetworkManager", "NetworkPlayer", "host", "connect",
+    # 高级射线
+    "Raycaster", "raycaster", "Layer",
+    "camera_ray", "screen_ray", "mouse_ray", "raycast_all",
+    "boxcast", "spherecast", "capsulecast",
+    "overlap_box", "overlap_sphere", "linecast",
+    "LineRenderer", "draw_line", "draw_ray",
+    "hit_distance_to", "nearest_hit", "hits_with_tag",
+    # 手柄
+    "Gamepad", "gamepad",
+    "on_pad_press", "on_pad_release", "on_pad_axis", "rumble", "set_gamepad_deadzone",
+    # 语音
+    "speak", "say",
+    "record", "stop_recording", "recognize", "listen",
+    "VoiceChat", "voice_chat",
+    "is_mic_available", "is_tts_available",
+    "set_voice_volume", "get_voice_volume", "VoiceRecorder",
+    # 工具
+    "destroy", "invoke", "invoke_repeating",
+    "random_range", "random_int", "random_color",
+    "lerp", "lerp_color", "clamp", "distance",
+    "sin", "cos", "tan", "get_time",
+]
+
+__version__ = "0.3.0"
+
+
+# ----------------------------------------------------------------------------
+# 兜底：如果脚本没写 run()，程序结束时自动运行
+# （写了 run() 就完全走显式流程，不会重复运行）
+# ----------------------------------------------------------------------------
+def _auto_run():
+    if _explicit_run:
+        return
+    if _app is not None and not getattr(_app, "running", False):
+        try:
+            _app.run()
+        except Exception as exc:  # pragma: no cover
+            print(f"[Three-dimensional-Games] 自动运行结束：{exc}")
+
+
+atexit.register(_auto_run)

three_dimensional_games/animation.py

@@ -0,0 +1,321 @@
+"""
+动画 / 补间系统（Tween / Animation）
+=====================================
+比 Ursina 的 animate_position / animate_scale 更通用，任意属性都能补间：
+
+    animate(entity, 'position', (5, 2, 0), duration=1.0, curve='ease_in_out')
+    animate_color(entity, color.red, duration=0.5)
+    animate_scale(entity, 3, duration=0.3)
+
+也支持把多个动画串起来顺序播放：
+
+    Sequence(
+        Tween(entity, 'position', (5, 0, 0), 1.0),
+        Tween(entity, 'position', (5, 5, 0), 1.0),
+    ).start()
+
+支持的插值曲线：
+    linear / ease_in / ease_out / ease_in_out
+    ease_in_cubic / ease_out_cubic / ease_in_out_cubic
+    smoothstep / bounce / elastic
+"""
+
+from __future__ import annotations
+import math
+from typing import Any, Callable, Optional, Union
+
+from .vector import Vec2, Vec3
+from .color import Color
+
+__all__ = [
+    "Tween", "Sequence", "animate", "animate_position",
+    "animate_scale", "animate_rotation", "animate_color",
+    "stop_all_tweens",
+]
+
+# 记录所有正在运行的补间，方便统一停止
+_active_tweens = []
+
+
+# ---------------------------------------------------------------------------
+# 曲线
+# ---------------------------------------------------------------------------
+def evaluate_curve(curve: str, t: float) -> float:
+    """把 0~1 的进度 t 按曲线映射成 0~1 的插值参数"""
+    t = max(0.0, min(1.0, t))
+    if curve in (None, "linear"):
+        return t
+    if curve == "ease_in":
+        return t * t
+    if curve == "ease_out":
+        return 1 - (1 - t) * (1 - t)
+    if curve in ("ease_in_out", "smoothstep"):
+        return t * t * (3 - 2 * t)
+    if curve == "ease_in_cubic":
+        return t ** 3
+    if curve == "ease_out_cubic":
+        return 1 - (1 - t) ** 3
+    if curve == "ease_in_out_cubic":
+        return 4 * t ** 3 if t < 0.5 else 1 - (-2 * t + 2) ** 3 / 2
+    if curve == "bounce":
+        n1, d1 = 7.5625, 2.75
+        if t < 1 / d1:
+            return n1 * t * t
+        if t < 2 / d1:
+            t -= 1.5 / d1
+            return n1 * t * t + 0.75
+        if t < 2.5 / d1:
+            t -= 2.25 / d1
+            return n1 * t * t + 0.9375
+        t -= 2.625 / d1
+        return n1 * t * t + 0.984375
+    if curve == "elastic":
+        if t == 0 or t == 1:
+            return t
+        c4 = (2 * math.pi) / 3
+        return -(2 ** (10 * t - 10)) * math.sin((t * 10 - 10.75) * c4)
+    return t
+
+
+# ---------------------------------------------------------------------------
+# 值处理：把 float / Vec2 / Vec3 / Color / tuple 拆成能插值的形式
+# ---------------------------------------------------------------------------
+def _split(value):
+    if isinstance(value, Color):
+        return "color", (value.r, value.g, value.b, value.a)
+    if isinstance(value, Vec3):
+        return "vec3", (value.x, value.y, value.z)
+    if isinstance(value, Vec2):
+        return "vec2", (value.x, value.y)
+    if isinstance(value, (tuple, list)):
+        return "tuple", tuple(float(v) for v in value)
+    return "number", (float(value),)
+
+
+def _rebuild(kind, comps):
+    if kind == "color":
+        return Color(*comps)
+    if kind == "vec3":
+        return Vec3(*comps)
+    if kind == "vec2":
+        return Vec2(*comps)
+    if kind == "tuple":
+        return tuple(comps)
+    return comps[0]
+
+
+def _clone(value):
+    if isinstance(value, Color):
+        return Color(value.r, value.g, value.b, value.a)
+    if isinstance(value, Vec3):
+        return Vec3(value.x, value.y, value.z)
+    if isinstance(value, Vec2):
+        return Vec2(value.x, value.y)
+    if isinstance(value, (tuple, list)):
+        return tuple(value)
+    return value
+
+
+def _interpolate(start, end, t):
+    kind_a, comps_a = _split(start)
+    kind_b, comps_b = _split(end)
+    if kind_a != kind_b:
+        # 类型不一致时不做插值，直接切换
+        return _clone(end) if t >= 1 else _clone(start)
+    comps = [comps_a[i] + (comps_b[i] - comps_a[i]) * t for i in range(len(comps_a))]
+    return _rebuild(kind_a, comps)
+
+
+def _dt() -> float:
+    from .util import time as _time
+    return _time.dt
+
+
+# ---------------------------------------------------------------------------
+# 单个补间
+# ---------------------------------------------------------------------------
+class Tween:
+    """
+    对某个对象的某个属性做一段补间动画。
+
+    Tween(entity, 'position', (5, 2, 0), duration=1.0, curve='ease_in_out')
+
+    :param target:      要动的是谁（一般是一个 Entity）
+    :param attr:        要动哪个属性，如 'position' / 'scale' / 'rotation' / 'color'
+    :param end_value:   目标值
+    :param duration:    持续时间（秒）
+    :param curve:       缓动曲线
+    :param delay:       延迟多久开始
+    :param loop:        是否循环播放
+    :param ping_pong:   循环时是否来回往复（A→B→A）
+    :param on_complete: 播放结束后的回调
+    """
+
+    def __init__(self, target, attr: str, end_value, duration: float = 1.0,
+                 curve: str = "linear", delay: float = 0.0, loop: bool = False,
+                 ping_pong: bool = False, on_complete: Optional[Callable] = None):
+        self.target = target
+        self.attr = attr
+        self.end_value = end_value
+        self.duration = max(float(duration), 1e-6)
+        self.curve = curve
+        self.delay = float(delay)
+        self.loop = loop
+        self.ping_pong = ping_pong
+        self.on_complete = on_complete
+
+        self.elapsed = 0.0
+        self.is_running = False
+        self._forward = True
+        self._start_value = None
+        self._task = None
+
+    # -- 内部控制 ---------------------------------------------------------
+    def _current(self):
+        return getattr(self.target, self.attr)
+
+    def _step(self, task):
+        dt = _dt()
+        self.elapsed += dt
+
+        if self.elapsed < self.delay:
+            return task.cont
+
+        t = (self.elapsed - self.delay) / self.duration
+        if t >= 1.0:
+            t = 1.0
+
+        eased = evaluate_curve(self.curve, t)
+        a, b = (self._start_value, self.end_value) if self._forward \
+            else (self.end_value, self._start_value)
+        setattr(self.target, self.attr, _interpolate(a, b, eased))
+
+        if t >= 1.0:
+            if self.on_complete:
+                self.on_complete()
+            if self.loop:
+                self.elapsed = self.delay
+                if self.ping_pong:
+                    self._forward = not self._forward
+                return task.cont
+            self.is_running = False
+            if self in _active_tweens:
+                _active_tweens.remove(self)
+            self._task = None
+            return task.done
+        return task.cont
+
+    # -- 对外 API ---------------------------------------------------------
+    def start(self):
+        """开始播放"""
+        from .application import Application
+        app = Application._instance
+        if app is None:
+            # 引擎还没起来（比如在导入阶段调），先记下起点，稍后由 animate() 兜底
+            self._start_value = _clone(self._current())
+            return self
+        self._start_value = _clone(self._current())
+        self.elapsed = 0.0
+        self.is_running = True
+        self._forward = True
+        if self not in _active_tweens:
+            _active_tweens.append(self)
+        self._task = app.taskMgr.add(self._step, f"tdg_tween_{id(self)}")
+        return self
+
+    def stop(self):
+        """立即停止"""
+        from .application import Application
+        app = Application._instance
+        if app is not None and self._task is not None:
+            try:
+                app.taskMgr.remove(self._task)
+            except Exception:
+                pass
+        self.is_running = False
+        self._task = None
+        if self in _active_tweens:
+            _active_tweens.remove(self)
+
+    @property
+    def finished(self) -> bool:
+        return not self.is_running
+
+
+class Sequence:
+    """
+    把多个 Tween 串起来，一个播完接着播下一个。
+
+        Sequence(
+            Tween(entity, 'position', (5, 0, 0), 1.0),
+            Tween(entity, 'scale', 2, 0.5),
+        ).start()
+    """
+
+    def __init__(self, *tweens, loop: bool = False):
+        self.tweens = list(tweens)
+        self.loop = loop
+        self._index = 0
+        self.is_running = False
+
+    def start(self):
+        self._index = 0
+        self.is_running = True
+        self._play_next()
+        return self
+
+    def _play_next(self):
+        if self._index >= len(self.tweens):
+            if self.loop:
+                self._index = 0
+            else:
+                self.is_running = False
+                return
+        tween = self.tweens[self._index]
+        original = tween.on_complete
+
+        def _on_done():
+            if original:
+                original()
+            self._index += 1
+            self._play_next()
+
+        tween.on_complete = _on_done
+        tween.loop = False
+        tween.start()
+
+    def stop(self):
+        for t in self.tweens:
+            t.stop()
+        self.is_running = False
+
+
+# ---------------------------------------------------------------------------
+# 便捷函数
+# ---------------------------------------------------------------------------
+def animate(target, attr: str, end_value, **kwargs) -> Tween:
+    """通用补间：把 target 的 attr 属性补间到 end_value"""
+    return Tween(target, attr, end_value, **kwargs).start()
+
+
+def animate_position(target, end_value, duration: float = 1.0, **kwargs) -> Tween:
+    return Tween(target, "position", end_value, duration=duration, **kwargs).start()
+
+
+def animate_scale(target, end_value, duration: float = 1.0, **kwargs) -> Tween:
+    return Tween(target, "scale", end_value, duration=duration, **kwargs).start()
+
+
+def animate_rotation(target, end_value, duration: float = 1.0, **kwargs) -> Tween:
+    return Tween(target, "rotation", end_value, duration=duration, **kwargs).start()
+
+
+def animate_color(target, end_value, duration: float = 1.0, **kwargs) -> Tween:
+    return Tween(target, "color", end_value, duration=duration, **kwargs).start()
+
+
+def stop_all_tweens():
+    """停止所有正在运行的补间动画"""
+    for t in list(_active_tweens):
+        t.stop()
+    _active_tweens.clear()