tkunity 2026.10.31__py3-none-any.whl

tkunity/export.py

@@ -0,0 +1,740 @@
+# -*- coding: utf-8 -*-
+"""APK 导出器：把 .pyu 项目字典生成一个可直接构建的 Android Studio/Gradle 工程。
+
+产物特点：
+- 纯 Java + 系统自带 org.json / android.graphics，零第三方依赖；
+- minSdk 26 / targetSdk 34，JDK 17，AGP 8.2.2，Gradle 8.5；
+- 内置动作与桌面预览一致（BUILTIN_ACTIONS：move-* / bounce / stop / print）；
+- 自定义 Python 表达式只用于桌面预览，APK 不支持（文档已注明）。
+"""
+from __future__ import annotations
+
+import json
+import os
+
+from . import __version__
+from .pyu import MAGIC
+
+__all__ = ["build", "DEFAULT_PACKAGE"]
+
+DEFAULT_PACKAGE = "com.oiiaio.tkunity"
+APP_NAME = "TkUnityGame"
+
+
+def build(project, outdir, package=DEFAULT_PACKAGE, app_name=None):
+    """生成 Android 工程到 outdir，返回生成的文件路径列表。"""
+    meta = project.get("meta", {})
+    name = app_name or meta.get("name", APP_NAME)
+    files = []
+    paths = {
+        "settings":      os.path.join(outdir, "settings.gradle"),
+        "root_build":    os.path.join(outdir, "build.gradle"),
+        "gradle_props":  os.path.join(outdir, "gradle.properties"),
+        "app_build":     os.path.join(outdir, "app", "build.gradle"),
+        "manifest":      os.path.join(outdir, "app", "src", "main", "AndroidManifest.xml"),
+        "strings":       os.path.join(outdir, "app", "src", "main", "res", "values", "strings.xml"),
+        "pyu":           os.path.join(outdir, "app", "src", "main", "assets", "game.pyu"),
+        "activity":      os.path.join(outdir, "app", "src", "main", "java", package.replace(".", "/"), "MainActivity.java"),
+        "gameview":      os.path.join(outdir, "app", "src", "main", "java", package.replace(".", "/"), "GameView.java"),
+        "bat":           os.path.join(outdir, "build_apk.bat"),
+        "sh":            os.path.join(outdir, "build_apk.sh"),
+        "readme":        os.path.join(outdir, "README_BUILD.md"),
+        "local_props":   os.path.join(outdir, "local.properties.example"),
+    }
+
+    for path in paths.values():
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+
+    def write(key, content):
+        with open(paths[key], "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(content)
+        files.append(paths[key])
+
+    write("settings", _settings_gradle())
+    write("root_build", _root_build_gradle())
+    write("gradle_props", _gradle_properties())
+    write("app_build", _app_build_gradle(package, name))
+    write("manifest", _manifest(package))
+    write("strings", _strings(name))
+    write("pyu", _pyu_blob(project))
+    write("activity", _main_activity(package))
+    write("gameview", _game_view(package, project))
+    write("bat", _build_bat())
+    write("sh", _build_sh())
+    write("readme", _build_readme(outdir, name))
+    write("local_props", "# 复制为 local.properties 并填写你的 Android SDK 路径\n# sdk.dir=C:\\\\Users\\\\you\\\\AppData\\\\Local\\\\Android\\\\Sdk\nsdk.dir=/path/to/your/android/sdk\n")
+    return files
+
+
+# ---------------------------------------------------------------- 内容生成
+def _pyu_blob(project):
+    blob = json.dumps(project, ensure_ascii=False, indent=1,
+                      separators=(",", ": ")).encode("utf-8")
+    return (MAGIC + blob).decode("utf-8")
+
+
+def _settings_gradle():
+    return """pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+rootProject.name = "TkUnityGame"
+include ':app'
+"""
+
+
+def _root_build_gradle():
+    return """plugins {
+    id 'com.android.application' version '8.2.2' apply false
+}
+"""
+
+
+def _gradle_properties():
+    return """org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+android.useAndroidX=false
+android.enableJetifier=false
+"""
+
+
+def _app_build_gradle(package, name):
+    return """plugins {
+    id 'com.android.application'
+}
+
+android {
+    namespace '%s'
+    compileSdk 34
+
+    defaultConfig {
+        applicationId "%s"
+        minSdk 26
+        targetSdk 34
+        versionCode 1
+        versionName "%s"
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+}
+
+// tkunity 游戏：零第三方依赖，无需任何 dependencies 块
+""" % (package, package, __version__)
+
+
+def _manifest(package):
+    return """<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <application
+        android:label="@string/app_name"
+        android:allowBackup="true"
+        android:theme="@android:style/Theme.Material.NoActionBar.Fullscreen">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:screenOrientation="landscape"
+            android:configChanges="orientation|screenSize|keyboardHidden">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>
+"""
+
+
+def _strings(name):
+    return """<resources>
+    <string name="app_name">%s</string>
+</resources>
+""" % name
+
+
+def _main_activity(package):
+    return """package %s;
+
+import android.app.Activity;
+import android.os.Bundle;
+import android.view.WindowManager;
+
+public class MainActivity extends Activity {
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        getWindow().addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
+        setContentView(new GameView(this));
+    }
+}
+""" % package
+
+
+def _build_readme(outdir, name):
+    return """# %s - Android 构建说明
+
+本目录由 tkunity %s 导出，是一个 **零第三方依赖** 的纯 Java Android 工程。
+
+## 构建要求
+- JDK 17
+- Android SDK（compileSdk 34）
+  - 设置环境变量 ANDROID_HOME，或把 local.properties.example 复制为 local.properties 并填写 sdk.dir
+- 无需 Android Studio，命令行即可构建
+
+## 构建
+Windows:
+    build_apk.bat
+Linux/macOS:
+    ./build_apk.sh
+
+脚本会自动下载 Gradle 8.5（若本机未安装 gradle）。
+
+## 产物
+    app/build/outputs/apk/debug/app-debug.apk
+
+## 说明
+- 游戏数据在 app/src/main/assets/game.pyu（.pyu 格式，图片 base64 内嵌）
+- 渲染器 GameView.java 使用 android.graphics.Canvas 实现，支持：
+    网格背景 / rect / oval / 图片 / 文本 / 层级 / 触摸拖动 / 点击动作 / 定时器
+- 动作支持（与桌面预览通用）：move-left move-right move-up move-down bounce stop print(...)
+- 自定义 Python 表达式仅用于桌面预览；如需更多玩法，直接修改 GameView.java 扩展。
+""" % (name, __version__)
+
+
+def _build_bat():
+    return """@echo off
+setlocal enabledelayedexpansion
+set "GRADLE_VERSION=8.5"
+set "DIR=%~dp0"
+set "TOOL_DIR=%DIR%.gradle-tool"
+set "GRADLE_HOME=%TOOL_DIR%\\gradle-%GRADLE_VERSION%"
+
+set "GRADLE_CMD="
+where gradle >nul 2>nul && set "GRADLE_CMD=gradle"
+if not defined GRADLE_CMD (
+  if not exist "%GRADLE_HOME%\\bin\\gradle.bat" (
+    echo [tkunity] 正在下载 Gradle %GRADLE_VERSION% ...
+    if not exist "%TOOL_DIR%" mkdir "%TOOL_DIR%"
+    powershell -NoProfile -ExecutionPolicy Bypass -Command ^
+      "$u='https://services.gradle.org/distributions/gradle-%GRADLE_VERSION%-bin.zip';" ^
+      "$z='%TOOL_DIR%\\gradle.zip';" ^
+      "[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12;" ^
+      "Invoke-WebRequest -Uri $u -OutFile $z;" ^
+      "Expand-Archive -Path $z -DestinationPath '%TOOL_DIR%' -Force"
+    if errorlevel 1 (
+      echo [tkunity] Gradle 下载失败，请手动下载后重试:
+      echo   https://services.gradle.org/distributions/gradle-%GRADLE_VERSION%-bin.zip
+      exit /b 1
+    )
+  )
+  set "GRADLE_CMD=%GRADLE_HOME%\\bin\\gradle.bat"
+)
+
+if not defined ANDROID_HOME (
+  if not exist "%DIR%local.properties" (
+    echo [tkunity] 未设置 ANDROID_HOME 且缺少 local.properties
+    echo   请创建 %DIR%local.properties，内容: sdk.dir=C:\\\\你的Android\\\\SDK\\\\路径
+    exit /b 1
+  )
+)
+
+cd /d "%DIR%"
+call "%GRADLE_CMD%" assembleDebug
+if errorlevel 1 (
+  echo [tkunity] 构建失败
+  exit /b 1
+)
+echo.
+echo APK: %DIR%app\\build\\outputs\\apk\\debug\\app-debug.apk
+"""
+
+
+def _build_sh():
+    return """#!/usr/bin/env bash
+set -e
+GRADLE_VERSION=8.5
+DIR="$(cd "$(dirname "$0")" && pwd)"
+TOOL_DIR="$DIR/.gradle-tool"
+GRADLE_HOME="$TOOL_DIR/gradle-$GRADLE_VERSION"
+
+if command -v gradle >/dev/null 2>&1; then
+  GRADLE_CMD=gradle
+else
+  if [ ! -x "$GRADLE_HOME/bin/gradle" ]; then
+    echo "[tkunity] downloading Gradle $GRADLE_VERSION ..."
+    mkdir -p "$TOOL_DIR"
+    (curl -fsSL -o "$TOOL_DIR/gradle.zip" \\
+         "https://services.gradle.org/distributions/gradle-$GRADLE_VERSION-bin.zip") \\
+      || (wget -q -O "$TOOL_DIR/gradle.zip" \\
+         "https://services.gradle.org/distributions/gradle-$GRADLE_VERSION-bin.zip")
+    unzip -q -o "$TOOL_DIR/gradle.zip" -d "$TOOL_DIR"
+  fi
+  GRADLE_CMD="$GRADLE_HOME/bin/gradle"
+fi
+
+if [ -z "$ANDROID_HOME" ] && [ ! -f "$DIR/local.properties" ]; then
+  echo "[tkunity] ANDROID_HOME not set and no local.properties found."
+  echo "  Create $DIR/local.properties with: sdk.dir=/path/to/your/android/sdk"
+  exit 1
+fi
+
+cd "$DIR"
+"$GRADLE_CMD" assembleDebug
+echo
+echo "APK: $DIR/app/build/outputs/apk/debug/app-debug.apk"
+"""
+
+
+def _game_view(package, project):
+    """生成 GameView.java 渲染器（含场景内置动作执行逻辑）。"""
+    return _GAME_VIEW_TEMPLATE.replace("@PACKAGE@", package)
+
+
+_GAME_VIEW_TEMPLATE = """package @PACKAGE@;
+
+import android.content.Context;
+import android.graphics.Bitmap;
+import android.graphics.BitmapFactory;
+import android.graphics.Canvas;
+import android.graphics.Color;
+import android.graphics.Paint;
+import android.graphics.Rect;
+import android.graphics.Typeface;
+import android.os.Handler;
+import android.os.Looper;
+import android.util.AttributeSet;
+import android.util.Base64;
+import android.util.Log;
+import android.view.MotionEvent;
+import android.view.View;
+
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+import java.io.ByteArrayOutputStream;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * tkunity 游戏渲染器：纯 Android 系统 API，零第三方依赖。
+ * 读取 assets/game.pyu（.pyu 格式），渲染场景并驱动动作。
+ */
+public class GameView extends View {
+    private static final String TAG = "tkunity";
+    private static final int GRID = 20;
+    private static final int TICK_MS = 16;
+
+    private JSONObject project;
+    private final List<Entity> entities = new ArrayList<>();
+    private final Map<String, Bitmap> bitmaps = new HashMap<>();
+    private final Handler handler = new Handler(Looper.getMainLooper());
+    private final Paint paint = new Paint(Paint.ANTI_ALIAS_FLAG);
+
+    private Entity dragging;
+    private float dragDX, dragDY;
+    private int sceneW = 960;
+    private int sceneH = 640;
+    private int bgColor = Color.rgb(30, 30, 46);
+    private int offsetX = 0;
+    private int offsetY = 0;
+    private long startTime;
+
+    private final Runnable ticker = new Runnable() {
+        @Override
+        public void run() {
+            long now = System.currentTimeMillis();
+            long elapsed = now - startTime;
+            for (Entity e : entities) {
+                e.tick(elapsed, sceneW, sceneH);
+            }
+            invalidate();
+            handler.postDelayed(this, TICK_MS);
+        }
+    };
+
+    public GameView(Context context) {
+        super(context);
+        init();
+    }
+
+    public GameView(Context context, AttributeSet attrs) {
+        super(context, attrs);
+        init();
+    }
+
+    public GameView(Context context, AttributeSet attrs, int defStyle) {
+        super(context, attrs, defStyle);
+        init();
+    }
+
+    private void init() {
+        loadProject();
+        startTime = System.currentTimeMillis();
+        handler.post(ticker);
+    }
+
+    private void loadProject() {
+        try {
+            InputStream in = getContext().getAssets().open("game.pyu");
+            ByteArrayOutputStream bos = new ByteArrayOutputStream();
+            byte[] buf = new byte[8192];
+            int n;
+            while ((n = in.read(buf)) != -1) {
+                bos.write(buf, 0, n);
+            }
+            in.close();
+            String text = new String(bos.toByteArray(), StandardCharsets.UTF_8);
+            int idx = text.indexOf('{');
+            project = new JSONObject(text.substring(idx));
+
+            JSONObject meta = project.optJSONObject("meta");
+            if (meta != null) {
+                sceneW = meta.optInt("scene_width", 960);
+                sceneH = meta.optInt("scene_height", 640);
+                bgColor = parseColor(meta.optString("background", "#1e1e2e"));
+            }
+            JSONArray arr = project.optJSONArray("entities");
+            if (arr == null) {
+                return;
+            }
+            for (int i = 0; i < arr.length(); i++) {
+                entities.add(Entity.fromJson(arr.optJSONObject(i)));
+            }
+        } catch (Exception e) {
+            Log.e(TAG, "load project failed", e);
+        }
+    }
+
+    @Override
+    protected void onSizeChanged(int w, int h, int oldw, int oldh) {
+        super.onSizeChanged(w, h, oldw, oldh);
+        offsetX = Math.max(0, (w - sceneW) / 2);
+        offsetY = Math.max(0, (h - sceneH) / 2);
+    }
+
+    @Override
+    protected void onDraw(Canvas canvas) {
+        super.onDraw(canvas);
+        canvas.drawColor(Color.rgb(32, 34, 40));
+        canvas.translate(offsetX, offsetY);
+
+        // 场景背景
+        canvas.drawRect(0, 0, sceneW, sceneH, paint);
+
+        // 网格
+        paint.setStyle(Paint.Style.STROKE);
+        paint.setStrokeWidth(1);
+        paint.setColor(Color.rgb(58, 58, 58));
+        for (int x = 0; x <= sceneW; x += GRID) {
+            canvas.drawLine(x, 0, x, sceneH, paint);
+        }
+        for (int y = 0; y <= sceneH; y += GRID) {
+            canvas.drawLine(0, y, sceneW, y, paint);
+        }
+
+        // 实体按 layer 升序绘制
+        List<Entity> sorted = new ArrayList<>(entities);
+        Collections.sort(sorted, new Comparator<Entity>() {
+            @Override
+            public int compare(Entity a, Entity b) {
+                int c = Integer.compare(a.layer, b.layer);
+                return c != 0 ? c : Integer.compare(a.id, b.id);
+            }
+        });
+        for (Entity e : sorted) {
+            drawEntity(canvas, e);
+        }
+    }
+
+    private void drawEntity(Canvas canvas, Entity e) {
+        if ("image".equals(e.shape) && !e.image.isEmpty()) {
+            Bitmap bmp = getBitmap(e.image);
+            if (bmp != null) {
+                canvas.drawBitmap(bmp, null,
+                        new Rect(e.x, e.y, e.x + e.width, e.y + e.height), paint);
+            }
+        } else if ("oval".equals(e.shape)) {
+            paint.setStyle(Paint.Style.FILL);
+            paint.setColor(e.fill);
+            canvas.drawOval(e.x, e.y, e.x + e.width, e.y + e.height, paint);
+            paint.setStyle(Paint.Style.STROKE);
+            paint.setStrokeWidth(2);
+            paint.setColor(e.outline);
+            canvas.drawOval(e.x, e.y, e.x + e.width, e.y + e.height, paint);
+        } else {
+            paint.setStyle(Paint.Style.FILL);
+            paint.setColor(e.fill);
+            canvas.drawRect(e.x, e.y, e.x + e.width, e.y + e.height, paint);
+            paint.setStyle(Paint.Style.STROKE);
+            paint.setStrokeWidth(2);
+            paint.setColor(e.outline);
+            canvas.drawRect(e.x, e.y, e.x + e.width, e.y + e.height, paint);
+        }
+
+        if (e.labelText != null && !e.labelText.isEmpty()) {
+            paint.setStyle(Paint.Style.FILL);
+            paint.setColor(e.labelColor);
+            paint.setTextSize(e.fontSize * getResources().getDisplayMetrics().density);
+            paint.setTypeface(e.bold ? Typeface.DEFAULT_BOLD : Typeface.DEFAULT);
+            Paint.Align oldAlign = paint.getTextAlign();
+            paint.setTextAlign(Paint.Align.CENTER);
+            Paint.FontMetrics fm = paint.getFontMetrics();
+            float cy = e.y + e.height / 2f - (fm.ascent + fm.descent) / 2f;
+            canvas.drawText(e.labelText, e.x + e.width / 2f, cy, paint);
+            paint.setTextAlign(oldAlign);
+        }
+    }
+
+    private Bitmap getBitmap(String assetName) {
+        if (bitmaps.containsKey(assetName)) {
+            return bitmaps.get(assetName);
+        }
+        try {
+            JSONObject assets = project.optJSONObject("assets");
+            if (assets == null) {
+                return null;
+            }
+            String b64 = assets.optString(assetName, "");
+            if (b64.isEmpty()) {
+                return null;
+            }
+            byte[] data = Base64.decode(b64, Base64.DEFAULT);
+            Bitmap bmp = BitmapFactory.decodeByteArray(data, 0, data.length);
+            bitmaps.put(assetName, bmp);
+            return bmp;
+        } catch (Exception e) {
+            Log.e(TAG, "decode image failed: " + assetName, e);
+            return null;
+        }
+    }
+
+    // -------------------------------------------------- 触摸
+    @Override
+    public boolean onTouchEvent(MotionEvent event) {
+        float x = event.getX() - offsetX;
+        float y = event.getY() - offsetY;
+        switch (event.getActionMasked()) {
+            case MotionEvent.ACTION_DOWN: {
+                Entity hit = hitTest(x, y);
+                if (hit != null) {
+                    dragging = hit;
+                    dragDX = x - hit.x;
+                    dragDY = y - hit.y;
+                    hit.runAction(hit.tapAction);
+                }
+                return true;
+            }
+            case MotionEvent.ACTION_MOVE: {
+                if (dragging != null) {
+                    dragging.x = Math.round(x - dragDX);
+                    dragging.y = Math.round(y - dragDY);
+                    invalidate();
+                }
+                return true;
+            }
+            case MotionEvent.ACTION_UP:
+            case MotionEvent.ACTION_CANCEL:
+                dragging = null;
+                return true;
+            default:
+                return super.onTouchEvent(event);
+        }
+    }
+
+    private Entity hitTest(float x, float y) {
+        List<Entity> sorted = new ArrayList<>(entities);
+        Collections.sort(sorted, new Comparator<Entity>() {
+            @Override
+            public int compare(Entity a, Entity b) {
+                int c = Integer.compare(b.layer, a.layer);
+                return c != 0 ? c : Integer.compare(b.id, a.id);
+            }
+        });
+        for (Entity e : sorted) {
+            if (x >= e.x && x <= e.x + e.width && y >= e.y && y <= e.y + e.height) {
+                return e;
+            }
+        }
+        return null;
+    }
+
+    // -------------------------------------------------- 工具
+    static int parseColor(String hex) {
+        try {
+            if (hex == null || hex.isEmpty()) {
+                return Color.BLACK;
+            }
+            hex = hex.trim();
+            if (hex.startsWith("#")) {
+                hex = hex.substring(1);
+            }
+            if (hex.length() == 6) {
+                return Color.rgb(Integer.parseInt(hex.substring(0, 2), 16),
+                        Integer.parseInt(hex.substring(2, 4), 16),
+                        Integer.parseInt(hex.substring(4, 6), 16));
+            }
+            if (hex.length() == 8) {
+                return Color.argb(Integer.parseInt(hex.substring(6, 8), 16),
+                        Integer.parseInt(hex.substring(0, 2), 16),
+                        Integer.parseInt(hex.substring(2, 4), 16),
+                        Integer.parseInt(hex.substring(4, 6), 16));
+            }
+        } catch (Exception ignored) {
+            // fall through
+        }
+        return Color.BLACK;
+    }
+
+    // -------------------------------------------------- 实体
+    public static class Entity {
+        int id;
+        String name = "obj";
+        int x, y, width = 80, height = 60, layer;
+        float rotation;
+        String shape = "rect";
+        int fill = Color.rgb(76, 139, 245);
+        int outline = Color.rgb(18, 52, 86);
+        String image = "";
+        String labelText = "";
+        int fontSize = 18;
+        int labelColor = Color.BLACK;
+        boolean bold = false;
+        String tapAction = "none";
+        String timerAction = "none";
+        int intervalMs = 1000;
+        long lastTick = 0;
+        long lastMove = 0;
+        int vx = 0;
+        int vy = 0;
+
+        static Entity fromJson(JSONObject o) throws Exception {
+            Entity e = new Entity();
+            e.id = o.optInt("id");
+            e.name = o.optString("name", "obj");
+            JSONObject comps = o.optJSONObject("components");
+            if (comps == null) {
+                return e;
+            }
+            JSONObject t = comps.optJSONObject("Transform");
+            if (t != null) {
+                e.x = t.optInt("x");
+                e.y = t.optInt("y");
+                e.width = t.optInt("width", 80);
+                e.height = t.optInt("height", 60);
+                e.layer = t.optInt("layer", 0);
+                e.rotation = (float) t.optDouble("rotation", 0.0);
+            }
+            JSONObject s = comps.optJSONObject("Sprite");
+            if (s != null) {
+                e.shape = s.optString("shape", "rect");
+                e.fill = parseColor(s.optString("fill", "#4C8BF5"));
+                e.outline = parseColor(s.optString("outline", "#123456"));
+                e.image = s.optString("image", "");
+            }
+            JSONObject l = comps.optJSONObject("Label");
+            if (l != null) {
+                e.labelText = l.optString("text", "");
+                e.fontSize = l.optInt("font_size", 18);
+                e.labelColor = parseColor(l.optString("color", "#000000"));
+                e.bold = l.optBoolean("bold", false);
+            }
+            JSONObject tap = comps.optJSONObject("TapHandler");
+            if (tap != null) {
+                e.tapAction = tap.optString("action", "none");
+            }
+            JSONObject tm = comps.optJSONObject("Timer");
+            if (tm != null) {
+                e.timerAction = tm.optString("action", "none");
+                e.intervalMs = tm.optInt("interval_ms", 1000);
+            }
+            return e;
+        }
+
+        void tick(long elapsed, int sceneW, int sceneH) {
+            if ((vx != 0 || vy != 0) && elapsed - lastMove >= TICK_MS) {
+                lastMove = elapsed;
+                x += vx;
+                y += vy;
+                if (x < 0) {
+                    x = 0;
+                    vx = -vx;
+                }
+                if (x + width > sceneW) {
+                    x = sceneW - width;
+                    vx = -vx;
+                }
+                if (y < 0) {
+                    y = 0;
+                    vy = -vy;
+                }
+                if (y + height > sceneH) {
+                    y = sceneH - height;
+                    vy = -vy;
+                }
+            }
+            if (!"none".equals(timerAction) && intervalMs > 0) {
+                if (elapsed - lastTick >= intervalMs) {
+                    lastTick = elapsed;
+                    runAction(timerAction);
+                }
+            }
+        }
+
+        void runAction(String action) {
+            if (action == null) {
+                return;
+            }
+            action = action.trim();
+            if (action.isEmpty() || "none".equals(action)) {
+                return;
+            }
+            if ("move-left".equals(action)) {
+                vx = -4; vy = 0;
+            } else if ("move-right".equals(action)) {
+                vx = 4; vy = 0;
+            } else if ("move-up".equals(action)) {
+                vx = 0; vy = -4;
+            } else if ("move-down".equals(action)) {
+                vx = 0; vy = 4;
+            } else if ("bounce".equals(action)) {
+                if (vx == 0 && vy == 0) {
+                    vx = 4;
+                    vy = 4;
+                }
+            } else if ("stop".equals(action)) {
+                vx = 0; vy = 0;
+            } else if (action.startsWith("print(")) {
+                Log.i(TAG, action);
+            }
+            // 其余自定义 Python 表达式仅在桌面预览中执行
+        }
+    }
+}
+}
+"""