tkunity 2026.10.31__py3-none-any.whl

tkunity/__init__.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""tkunity - 纯标准库的 Unity 风格 2D 游戏编辑器与运行时，可把 .pyu 游戏导出为 Android APK 工程。
+
+Apache License 2.0 | Copyright 2026 oiiaio-web <3926580760@qq.com>
+"""
+from __future__ import annotations
+
+from .api import GameObject, Project, load, save
+from .components import BUILTIN_ACTIONS, COMPONENT_SCHEMAS, PARTS
+from .pyu import PYU_VERSION, new_project
+
+__version__ = "2026.10.31"
+__author__ = "oiiaio-web"
+__author_email__ = "3926580760@qq.com"
+__license__ = "Apache-2.0"
+
+__all__ = [
+    "__version__", "__author__", "__author_email__", "__license__",
+    "PYU_VERSION", "Project", "GameObject", "load", "save", "new_project",
+    "PARTS", "COMPONENT_SCHEMAS", "BUILTIN_ACTIONS", "help",
+]
+
+
+def help():
+    """打印 tkunity 命令帮助（等价命令行 tkunity -h / -help / --help）。"""
+    from .cli import show_help
+    show_help()

tkunity/__main__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""python -m tkunity 支持。"""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

tkunity/api.py

@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+"""面向对象的建项目 API（无需打开编辑器即可用代码做游戏）。"""
+from __future__ import annotations
+
+from . import pyu
+from .components import COMPONENT_SCHEMAS, new_component
+
+__all__ = ["Project", "GameObject", "save", "load"]
+
+
+class GameObject(object):
+    """场景中的一个物体。name/components 与 .pyu 实体一一对应。"""
+
+    def __init__(self, name, x=0, y=0, width=80, height=60, layer=0):
+        self.name = name
+        self._components = {}
+        self._components["Transform"] = {
+            "x": x, "y": y, "width": width, "height": height,
+            "rotation": 0.0, "layer": layer,
+        }
+        self._id = None  # 加入 Project 后赋值
+
+    # ---- 便捷增删组件 ----
+    def add_sprite(self, shape="rect", fill="#4C8BF5", outline="#123456", image=""):
+        return self.set_component("Sprite", shape=shape, fill=fill, outline=outline, image=image)
+
+    def add_label(self, text="文本", font_size=18, color="#000000", bold=False):
+        return self.set_component("Label", text=text, font_size=font_size, color=color, bold=bold)
+
+    def add_tap(self, action="none"):
+        return self.set_component("TapHandler", action=action)
+
+    def add_timer(self, interval_ms=1000, action="none"):
+        return self.set_component("Timer", interval_ms=interval_ms, action=action)
+
+    def set_component(self, name, **values):
+        comp = self._components.setdefault(name, new_component(name))
+        comp.update(values)
+        return self
+
+    def remove_component(self, name):
+        if name != "Transform" and name in self._components:
+            del self._components[name]
+        return self
+
+    def has(self, name):
+        return name in self._components
+
+    def get(self, name, default=None):
+        return self._components.get(name, default)
+
+    @property
+    def transform(self):
+        return self._components["Transform"]
+
+    def move(self, dx, dy):
+        t = self.transform
+        t["x"] += dx
+        t["y"] += dy
+
+    def __getitem__(self, name):
+        return self._components[name]
+
+    def to_dict(self, entity_id=None):
+        return {"id": self._id if entity_id is None else entity_id,
+                "name": self.name, "components": self._components}
+
+
+class Project(object):
+    """一个游戏项目，等价于一份 .pyu 文件。"""
+
+    def __init__(self, name="未命名项目", scene_width=960, scene_height=640, background="#1e1e2e"):
+        self._project = pyu.new_project(name, scene_width, scene_height, background)
+        self.objects = []
+
+    @property
+    def meta(self):
+        return self._project["meta"]
+
+    def add(self, obj):
+        """把一个 GameObject 加入场景（可链式）。"""
+        if not isinstance(obj, GameObject):
+            raise TypeError("Project.add 需要 GameObject")
+        eid = max([e["id"] for e in self._project["entities"]], default=0) + 1
+        obj._id = eid
+        self._project["entities"].append(obj.to_dict(eid))
+        self.objects.append(obj)
+        return obj
+
+    def embed_image(self, path):
+        """内嵌本地 PNG/GIF 图片，返回资源名。"""
+        return pyu.embed_image(self._project, path)
+
+    def to_dict(self):
+        return self._project
+
+    def save(self, path):
+        pyu.save(self._project, path)
+        return path
+
+
+def save(project, path):
+    """保存 Project（或直接传字典）到 .pyu 文件。"""
+    if isinstance(project, Project):
+        project = project.to_dict()
+    pyu.save(project, path)
+    return path
+
+
+def load(path):
+    """读取 .pyu 文件，返回项目字典（供运行时 / 编辑器使用）。"""
+    return pyu.load(path)

tkunity/cli.py

@@ -0,0 +1,106 @@
+# -*- coding: utf-8 -*-
+"""命令行入口。
+
+用法：
+    tkunity                     # 启动图形编辑器
+    tkunity edit [文件.pyu]     # 同上，可带文件
+    tkunity build 游戏.pyu -o 输出目录   # 导出 Android APK 工程
+    tkunity info                # 环境信息
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+
+
+def _print_error(msg):
+    sys.stderr.write("[tkunity] 错误: %s\n" % msg)
+
+
+def cmd_edit(args):
+    from .editor import launch_editor
+    launch_editor(args.file)
+
+
+def cmd_build(args):
+    from . import export, pyu
+    if not os.path.isfile(args.input):
+        _print_error("找不到项目文件: %s" % args.input)
+        return 1
+    project = pyu.load(args.input)
+    outdir = args.output or os.path.join(
+        os.path.dirname(os.path.abspath(args.input)),
+        "android_build_" + project["meta"].get("name", "game"))
+    files = export.build(project, outdir)
+    print("[tkunity] 已生成 Android 工程（%d 个文件）:" % len(files))
+    for f in files:
+        print("   ", f)
+    print("\n下一步:")
+    print("  1) 安装 JDK 17 与 Android SDK，并设置 ANDROID_HOME")
+    print("     （或在该目录创建 local.properties: sdk.dir=你的SDK路径）")
+    print("  2) Windows: 双击 build_apk.bat   或   执行 ./build_apk.sh")
+    print("  3) 产物: app/build/outputs/apk/debug/app-debug.apk")
+    return 0
+
+
+def cmd_info(args):
+    import tkinter
+    print("tkunity %s" % __version__)
+    print("Python: %s" % sys.version.split()[0])
+    print("tkinter: %s (Tk %s)" % (tkinter.__file__, tkinter.TkVersion))
+    print("平台: %s" % sys.platform)
+
+
+def _add_help_alias(parser):
+    """为 parser 增加 -help 别名（与内置 -h / --help 功能一致）。"""
+    parser.add_argument("-help", action="help",
+                        help="显示帮助并退出（同 -h / --help）")
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="tkunity",
+        description="tkunity %s - Unity 风格 2D 游戏编辑器（纯标准库，可导出 Android APK 工程）" % __version__,
+    )
+    _add_help_alias(parser)
+    sub = parser.add_subparsers(dest="command")
+    parser.add_argument("--version", action="version",
+                        version="%(prog)s " + __version__)
+
+    p_edit = sub.add_parser("edit", help="启动图形编辑器（可带 .pyu 文件）")
+    _add_help_alias(p_edit)
+    p_edit.add_argument("file", nargs="?", default=None)
+    p_edit.set_defaults(func=cmd_edit)
+
+    p_build = sub.add_parser("build", help="把 .pyu 游戏导出为 Android APK 工程")
+    _add_help_alias(p_build)
+    p_build.add_argument("input", help="项目文件（.pyu）")
+    p_build.add_argument("-o", "--output", default=None, help="输出目录")
+    p_build.set_defaults(func=cmd_build)
+
+    p_info = sub.add_parser("info", help="显示环境信息")
+    _add_help_alias(p_info)
+    p_info.set_defaults(func=cmd_info)
+
+    return parser
+
+
+def show_help():
+    """打印主帮助文本（等价命令行 tkunity -h / -help / --help）。"""
+    _build_parser().print_help()
+
+
+def main(argv=None):
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if getattr(args, "command", None) is None or not hasattr(args, "func"):
+        cmd_edit(argparse.Namespace(file=None))
+        return 0
+    return args.func(args) or 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tkunity/components.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+"""组件注册表与零件库。
+
+每个组件描述一组字段（类型 / 默认值），编辑器据此动态生成属性面板，
+导出器据此生成 Java 渲染器，运行时据此执行行为。
+"""
+from __future__ import annotations
+
+__all__ = [
+    "SHAPES", "COMPONENT_SCHEMAS", "PARTS", "TRANSFORM_FIELDS",
+    "BUILTIN_ACTIONS", "new_transform", "new_component", "validate_component",
+]
+
+# 组件类型
+SHAPES = ["rect", "oval", "image"]
+
+# 内置动作（桌面预览与 APK 导出通用；APK 只支持这组动作）
+BUILTIN_ACTIONS = [
+    "none",
+    "print('hello')",
+    "move-left", "move-right", "move-up", "move-down",
+    "bounce", "stop",
+]
+
+# 组件 -> 字段 -> 字段定义。type 取值: int / float / text / color / choice / bool / file
+COMPONENT_SCHEMAS = {
+    "Transform": {
+        "fields": {
+            "x":        {"type": "int",   "default": 0,    "hint": "X 坐标（px）"},
+            "y":        {"type": "int",   "default": 0,    "hint": "Y 坐标（px）"},
+            "width":    {"type": "int",   "default": 80,   "hint": "宽度（px）"},
+            "height":   {"type": "int",   "default": 60,   "hint": "高度（px）"},
+            "rotation": {"type": "float", "default": 0.0,  "hint": "旋转角度（度）"},
+            "layer":    {"type": "int",   "default": 0,    "hint": "绘制层级，越大越靠上"},
+        },
+    },
+    "Sprite": {
+        "fields": {
+            "shape":   {"type": "choice", "options": SHAPES, "default": "rect", "hint": "形状"},
+            "fill":    {"type": "color",  "default": "#4C8BF5", "hint": "填充色"},
+            "outline": {"type": "color",  "default": "#123456", "hint": "描边色"},
+            "image":   {"type": "file",   "default": "", "hint": "PNG/GIF 图片路径（shape=image 时）"},
+        },
+    },
+    "Label": {
+        "fields": {
+            "text":      {"type": "text", "default": "文本", "hint": "显示文字"},
+            "font_size": {"type": "int",   "default": 18,  "hint": "字号"},
+            "color":     {"type": "color", "default": "#000000", "hint": "文字颜色"},
+            "bold":      {"type": "bool",  "default": False, "hint": "加粗"},
+        },
+    },
+    "TapHandler": {
+        "fields": {
+            "action": {"type": "text", "default": "none", "multiline": True,
+                       "hint": "点击动作：内置动作或 Python 表达式（仅桌面预览）"},
+        },
+    },
+    "Timer": {
+        "fields": {
+            "interval_ms": {"type": "int", "default": 1000, "hint": "触发间隔（毫秒）"},
+            "action":      {"type": "text", "default": "none", "multiline": True,
+                            "hint": "定时动作：内置动作或 Python 表达式（仅桌面预览）"},
+        },
+    },
+}
+
+TRANSFORM_FIELDS = COMPONENT_SCHEMAS["Transform"]["fields"]
+
+# 零件库：编辑器左侧列表。parts = (显示名, 附加组件字典)
+PARTS = [
+    ("矩形",   {"Sprite": {"shape": "rect"}}),
+    ("椭圆",   {"Sprite": {"shape": "oval"}}),
+    ("文本",   {"Label": {}}),
+    ("图片",   {"Sprite": {"shape": "image"}}),
+    ("点击触发器", {"TapHandler": {}}),
+    ("定时器", {"Timer": {}}),
+]
+
+# 可被用户手动增删的组件（Transform 除外）
+ADDABLE_COMPONENTS = ["Sprite", "Label", "TapHandler", "Timer"]
+
+
+def new_transform(x=0, y=0, width=80, height=60, rotation=0.0, layer=0):
+    """创建一份 Transform 默认字段。"""
+    t = {k: v["default"] for k, v in TRANSFORM_FIELDS.items()}
+    t.update(x=x, y=y, width=width, height=height, rotation=rotation, layer=layer)
+    return t
+
+
+def new_component(name):
+    """按注册表创建一份组件默认字段字典。"""
+    schema = COMPONENT_SCHEMAS[name]
+    return {k: v["default"] for k, v in schema["fields"].items()}
+
+
+def validate_component(name, values):
+    """按注册表字段类型规范化（int/float 强转），返回 (ok, 修正后字典, 错误信息)。"""
+    schema = COMPONENT_SCHEMAS.get(name)
+    if schema is None:
+        return False, values, "未知组件: %s" % name
+    out = {}
+    for key, spec in schema["fields"].items():
+        raw = values.get(key, spec["default"])
+        ftype = spec["type"]
+        if ftype == "int":
+            try:
+                out[key] = int(float(raw))
+            except (TypeError, ValueError):
+                return False, values, "%s.%s 需要整数，得到 %r" % (name, key, raw)
+        elif ftype == "float":
+            try:
+                out[key] = float(raw)
+            except (TypeError, ValueError):
+                return False, values, "%s.%s 需要数字，得到 %r" % (name, key, raw)
+        elif ftype == "bool":
+            out[key] = bool(raw)
+        elif ftype == "choice":
+            if raw not in spec.get("options", []):
+                out[key] = spec["default"]
+            else:
+                out[key] = raw
+        else:  # text / color / file
+            out[key] = str(raw) if raw is not None else spec["default"]
+    return True, out, ""