tkunity

纯标准库、零第三方依赖（不需要 pygame）的 Unity 风格 2D 游戏编辑器 + 运行时， 把你在编辑器里拼出来的 .pyu 游戏一键导出成 Android APK 工程。

• 许可证：Apache License 2.0
• 作者：oiiaio-web 3926580760@qq.com
• 版本：2026.11.2
• Python：>= 3.8（已在 3.8 / 3.14 / 3.15 / 3.16 上测试）
• 依赖：零。只使用标准库 tkinter / json / base64 / argparse / math。Linux 上若缺少 tk 图形环境，请安装系统包 python3-tk（这不是 pip 依赖）。

版本号规则

版本号形如 YYYY.M.N，三段都是「日历 + 计数」，不是 语义化的 主.次.补丁：

2026 . 11 . 2
 │      │    └── 该月的第几个发布版本（这里是 11 月的第 2 个版本）
 │      └─────── 月份（11 月）
 └────────────── 年份（2026 年）

• 2026.11.1 = 2026 年 11 月的第 1 个版本
• 2026.11.2 = 2026 年 11 月的第 2 个版本（本版）
• 2026.12.1 = 2026 年 12 月的第 1 个版本

所以第三段只是「当月第几发」，不代表兼容性等级；同一个 YYYY.M 下的相邻版本都保证 .pyu 文件向后兼容（旧文件能直接打开，读入时自动补齐新字段）。

预发布沿用 PEP 440 的 devN 后缀，例如 2026.11.2.dev0 表示「2026 年 11 月第 2 版之前的开发快照 0」。 按 PEP 440 排序 2026.11.2.dev0 < 2026.11.2，因此 pip install tkunity 默认只会装正式版，预发布需要 pip install --pre tkunity 或精确指定版本。

一、这一版「更像 Unity」的地方

二、安装

pip install tkunity        # 从 PyPI
# 或从源码目录
pip install -e .
tkunity --version          # 查看版本
tkunity -h / -help / --help   # 三种写法功能一样

不需要 pygame、不需要 Kivy、不需要任何 pip 第三方包。

三、命令行

tkunity                          # 打开图形编辑器
tkunity edit examples/demo.pyu   # 打开编辑器并载入项目
tkunity new 游戏.pyu --width 960 --height 640
tkunity run 游戏.pyu             # 直接运行（桌面预览）
tkunity validate 游戏.pyu        # 校验组件 / 父子环 / 预制体引用
tkunity build 游戏.pyu -o out    # 导出 Android 工程
tkunity info                     # 环境与组件信息

四、编辑器

┌──────────────────── 工具栏：文件 / 撤销重做 / 预览 / 导出 ─────────────────────┐
│ 层级(父子树) │         场景画布（缩放 / 网格吸附）        │  Inspector        │
│ ＋空物体     │                                           │  名称 / 标签 / 激活 │
│ 零件库       │                                           │  父物体            │
│ 预制体       │                                           │  各组件字段        │
├──────────────┴───────────────────────────────────────────┴───────────────────┤
│ 控制台（运行日志 / 脚本输出）                                                │
└──────────────────────────────────────────────────────────────────────────────┘

常用操作

五、组件参考

六、内置动作

可用于 TapHandler.action、Timer.action：

none                    什么都不做
move-left / move-right / move-up / move-down   设置速度 240 px/s
jump                    向上初速度 430 px/s
bounce                  首次触发时给一个对角速度
stop                    速度归零
destroy                 销毁自己
toggle                  切换自身激活状态
restart                 重开场景
spawn:<预制体名>         在自己位置实例化预制体
print('文字')            打印到控制台 / logcat

桌面预览额外支持 Python 表达式，例如 x += 10、width = 200、log('hp=%d' % hp)。

导出 APK 时只保留上表的内置动作；自定义 Python 表达式与 Script 组件仅在桌面预览生效。

七、脚本（桌面预览）

Script 组件的每个生命周期都跑在受限命名空间里：

例：键盘控制左右移动

# on_update
x += scene.axis("horizontal") * 260 * dt
if y > 560:
    restart()

八、Python API

from tkunity import Project, GameObject, save

p = Project("弹球", 960, 640, background="#1e1e2e", gravity=980)

ground = GameObject("地面", 0, 560, 960, 40, tag="Ground")
ground.add_sprite("rect", fill="#45475a").add_collider()
p.add(ground)

ball = GameObject("球", 460, 100, 60, 60, tag="Player")
ball.add_sprite("oval", fill="#f38ba8")
ball.add_rigidbody(velocity_x=160, bounce=0.9)
ball.add_collider()
ball.add_animator("spin", speed=0.6)
ball.add_script(on_update="if x < 0 or x + w > 960: vx = -vx")
p.add(ball)

p.save_prefab(ball, "ball")      # 存成预制体
p.instantiate("ball", 200, 80)   # 再实例化一个
save(p, "demo.pyu")

项目 / 物体 API

九、导出 Android

tkunity build examples/demo.pyu -o ./out
cd out/android_*
# 设置 ANDROID_HOME 或在目录里放 local.properties
build_apk.bat        # Windows
./build_apk.sh       # Linux / macOS
# 产物 app/build/outputs/apk/debug/app-debug.apk

导出的 Java 渲染器（GameView.java）零第三方依赖，支持层级、旋转缩放、 刚体物理、碰撞触发器、摄像机、动画与全部内置动作。

十、限制

• 2D 简化模型：父物体的旋转不参与子物体位置计算（位移与缩放参与）；
• tkinter Canvas 不能真正旋转图片，图片精灵的旋转在桌面预览中表现为轴对齐，APK 中完整支持；
• Script 与自定义 Python 表达式不会导出到 APK（Java 侧不执行任意脚本）；
• 一个 .pyu 对应一个场景，暂不支持多场景切换。