Skip to content

Commit 5ffa882

Browse files
jinwandalaohu66jinwandalaohu66
committed
README: 新增 scene 2D 游戏引擎模块和 widget 桌面小组件模块完整文档
1 parent 0d0c724 commit 5ffa882

1 file changed

Lines changed: 185 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 185 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -10,21 +10,20 @@
1010

1111
<p align="center">
1212
<a href="https://apps.apple.com/app/id6753987304">
13-
<img src="https://img.shields.io/badge/App%20Store-免费下载-black?style=for-the-badge&logo=apple" alt="Download on App Store" height="44" />
13+
<img src="https://img.shields.io/badge/App%20Store-下载-black?style=for-the-badge&logo=apple" alt="Download on App Store" height="44" />
1414
</a>
1515
&nbsp;
16-
<a href="https://github.com/jinwandalaohu66/PythonIDE-Landing">
17-
<img src="https://img.shields.io/github/stars/jinwandalaohu66/PythonIDE-Landing?style=for-the-badge&logo=github&color=orange" alt="GitHub Stars" height="44" />
16+
<a href="https://github.com/jinwandalaohu66/PythonIDE-iOS">
17+
<img src="https://img.shields.io/github/stars/jinwandalaohu66/PythonIDE-iOS?style=for-the-badge&logo=github" alt="GitHub Stars" height="44" />
1818
</a>
1919
</p>
2020

2121
<p align="center">
22-
<img src="https://img.shields.io/badge/iOS-16.2+-007AFF?style=flat-square&logo=apple" />
23-
<img src="https://img.shields.io/badge/Python-3.13-3776AB?style=flat-square&logo=python" />
24-
<img src="https://img.shields.io/badge/JavaScript-ES6+-F7DF1E?style=flat-square&logo=javascript&logoColor=black" />
25-
<img src="https://img.shields.io/badge/Swift-5.9-FA7343?style=flat-square&logo=swift" />
26-
<img src="https://img.shields.io/badge/C_Extensions-12+-44CC11?style=flat-square" />
27-
<img src="https://img.shields.io/badge/Prebuilt_Wheels-150+-8A2BE2?style=flat-square" />
22+
<img src="https://img.shields.io/badge/iOS-16.2+-blue?style=flat-square" alt="iOS 16.2+" />
23+
<img src="https://img.shields.io/badge/Python-3.13-3776AB?style=flat-square&logo=python" alt="Python 3.13" />
24+
<img src="https://img.shields.io/badge/JavaScript-ES6+-F7DF1E?style=flat-square&logo=javascript" alt="JavaScript" />
25+
<img src="https://img.shields.io/badge/Swift-5.9-FA7343?style=flat-square&logo=swift" alt="Swift" />
26+
<img src="https://img.shields.io/badge/C_Extensions-12+-brightgreen?style=flat-square" alt="C Extensions" />
2827
</p>
2928

3029
---
@@ -282,6 +281,174 @@ Pythonista 兼容的 UI 模块，用 Python 创建原生 iOS 界面（View、But
282281

283282
- **[UI 模块完整文档（中文）](docs/ui-module-zh.md)** · [Full docs (English)](docs/ui-module-en.md)
284283

284+
#### 🎮 scene 模块 — 2D 游戏引擎
285+
286+
Pythonista 兼容的 Scene 模块，用 Python 开发 2D 游戏和动画。底层基于 SpriteKit，提供**两种开发模式**：经典逐帧绘制（`draw()`）和现代节点树（Node + Action）。
287+
288+
##### 节点体系
289+
290+
| 节点 | 说明 |
291+
|------|------|
292+
| **`Node`** | 基础节点，支持 `position`、`rotation`、`alpha`、`z_position`、`physics_body` |
293+
| **`SpriteNode`** | 精灵节点，加载图片纹理，支持 `color`、`size`、`anchor_point` |
294+
| **`LabelNode`** | 文字节点，支持 `font`、`color`、`alignment` |
295+
| **`ShapeNode`** | 形状节点，支持矩形（可圆角）、椭圆，可设 `fill_color`、`stroke_color` |
296+
| **`EmitterNode`** | 粒子发射器节点 |
297+
298+
##### Action 动画系统（14 种动作）
299+
300+
| 动作 | 说明 |
301+
|------|------|
302+
| `move_to` / `move_by` | 移动到绝对位置 / 相对偏移 |
303+
| `rotate_to` / `rotate_by` | 旋转到角度 / 旋转偏移量 |
304+
| `scale_to` / `scale_by` | 缩放到倍数 / 缩放偏移 |
305+
| `fade_to` / `fade_by` | 淡入淡出到透明度 / 透明度偏移 |
306+
| `sequence` | 按顺序执行一组动作 |
307+
| `group` | 同时并行执行一组动作 |
308+
| `repeat` / `repeat_forever` | 重复执行 N 次 / 无限循环 |
309+
| `wait` | 等待指定秒数 |
310+
| `call` | 执行回调函数 |
311+
| `remove` | 从父节点移除 |
312+
313+
所有动作支持 **16 种缓动曲线**：`TIMING_LINEAR`、`TIMING_EASE_IN/OUT`、`TIMING_ELASTIC_IN/OUT`、`TIMING_BOUNCE_IN/OUT`、`TIMING_EASE_BACK_IN/OUT` 等。
314+
315+
##### 物理引擎
316+
317+
| 功能 | 说明 |
318+
|------|------|
319+
| **`PhysicsWorld`** | 场景物理世界，可设置 `gravity` 全局重力 |
320+
| **`PhysicsBody`** | 物理体，支持 `rectangle(w,h)` 和 `circle(r)` 两种形状 |
321+
| **碰撞属性** | `restitution`（弹性）、`friction`（摩擦）、`linear_damping`（阻尼）、`velocity`（速度） |
322+
| **碰撞检测** | `category_bitmask`、`collision_bitmask`、`contact_test_bitmask` 位掩码 |
323+
| **`Contact`** | 碰撞回调，包含 `node_a`、`node_b`、`contact_point`、`collision_impulse` |
324+
| **力与冲量** | `apply_impulse(x, y)` 施加冲量 |
325+
| **关节** | `PinJoint`（铰链）、`SpringJoint`（弹簧）、`RopeJoint`（绳索） |
326+
327+
##### 经典绘图 API（scene_drawing）
328+
329+
在 `Scene.draw()` 中使用的逐帧绘制函数，适合快速原型和简单动画：
330+
331+
| 函数 | 说明 |
332+
|------|------|
333+
| `background(r,g,b)` | 填充背景色 |
334+
| `fill(r,g,b,a)` / `no_fill()` | 设置 / 取消填充色 |
335+
| `stroke(r,g,b,a)` / `no_stroke()` | 设置 / 取消描边色 |
336+
| `stroke_weight(w)` | 设置描边宽度 |
337+
| `rect(x,y,w,h)` | 绘制矩形（支持圆角） |
338+
| `ellipse(x,y,w,h)` | 绘制椭圆 |
339+
| `line(x1,y1,x2,y2)` | 绘制线段 |
340+
| `image(name,x,y,w,h)` | 绘制图片 |
341+
| `text(txt,font,size,x,y)` | 绘制文字 |
342+
| `tint(r,g,b,a)` / `no_tint()` | 设置 / 取消图片着色 |
343+
| `translate` / `rotate` / `scale` | 矩阵变换 |
344+
| `push_matrix` / `pop_matrix` | 保存 / 恢复变换状态 |
345+
| `load_image_file(path)` | 从文件加载图片 |
346+
| `render_text(txt,font,size)` | 将文字渲染为纹理 |
347+
348+
##### 其他功能
349+
350+
| 功能 | 说明 |
351+
|------|------|
352+
| `Scene.touch_began/moved/ended` | 多点触摸事件回调 |
353+
| `Scene.present_modal_scene` | 模态场景（菜单、暂停画面等） |
354+
| `Scene.did_change_size` | 屏幕旋转回调 |
355+
| `run(scene, orientation, show_fps)` | 启动场景，支持竖屏/横屏/自动 |
356+
| `get_screen_size()` / `get_screen_scale()` | 屏幕尺寸与缩放因子 |
357+
| `gravity()` | 读取设备重力传感器（陀螺仪） |
358+
| `play_effect(name)` | 播放音效 |
359+
| `Texture(name)` | 加载纹理资源 |
360+
| `Shader(source)` | 自定义着色器 |
361+
| `SceneView` | 将场景嵌入 `ui.View` 中 |
362+
363+
##### 代码示例
364+
365+
```python
366+
from scene import *
367+
368+
class MyGame(Scene):
369+
def setup(self):
370+
self.background_color = (0.05, 0.05, 0.15)
371+
self.player = SpriteNode('plc:Alien_Green',
372+
position=self.size / 2,
373+
parent=self)
374+
375+
def touch_began(self, touch):
376+
self.player.run_action(
377+
Action.move_to(*touch.location, 0.3, TIMING_EASE_OUT)
378+
)
379+
380+
run(MyGame())
381+
```
382+
383+
应用内置 **16 款游戏示例**，包括贪吃蛇、Flappy Bird、打砖块、2048、水果忍者、俄罗斯方块、塔防、节奏大师、太空射击、打地鼠、重力迷宫等，可直接运行学习。
384+
385+
#### 📲 widget 模块 — iOS 桌面小组件
386+
387+
用 Python 创建 **iOS 桌面小组件**，脚本运行后自动渲染到主屏幕。支持声明式布局 DSL 和快捷模板两种模式。
388+
389+
##### 支持的组件（14 种）
390+
391+
| 组件 | 方法 | 说明 |
392+
|------|------|------|
393+
| **文字** | `w.text(content, size, weight, color, align, max_lines, design)` | 支持字号、字重、颜色、对齐、行数限制、字体设计（`rounded` / `monospaced` / `serif`） |
394+
| **图标** | `w.icon(name, size, color, weight)` | SF Symbol 图标，支持 6000+ 系统图标 |
395+
| **Emoji** | `w.emoji(content, size)` | Emoji 表情，支持自定义大小 |
396+
| **间距** | `w.spacer(length)` | 弹性间距或固定间距 |
397+
| **分割线** | `w.divider(color, opacity)` | 水平分割线 |
398+
| **进度条** | `w.progress(value, total, color, height, track_color)` | 线性进度条，支持自定义颜色和轨道色 |
399+
| **仪表盘** | `w.gauge(value, total, label, size, color, track_color, line_width)` | 圆形仪表盘，支持中心文字 |
400+
| **实时计时** | `w.timer(target, style, size, weight, color)` | WidgetKit 原生倒计时，无需刷新；支持 `timer` / `relative` / `date` / `time` / `offset` 五种样式 |
401+
| **图片** | `w.image(name, width, height, corner_radius, content_mode)` | 显示通过 `save_image()` 缓存的图片，支持 `fit` / `fill` |
402+
| **水平布局** | `w.hstack(spacing, align, background, corner_radius, url)` | `with` 语法，支持嵌套 |
403+
| **垂直布局** | `w.vstack(...)` | 同上 |
404+
| **叠加布局** | `w.zstack(...)` | 多层叠加 |
405+
| **卡片** | `w.card(background, corner_radius, padding, border_color, border_width, url)` | 带圆角、背景、边框的容器 |
406+
| **渲染输出** | `w.render(url)` | 输出最终布局，可设置点击跳转 URL |
407+
408+
##### 小组件尺寸
409+
410+
| 常量 | 说明 |
411+
|------|------|
412+
| `SMALL` | 主屏幕小组件（2×2） |
413+
| `MEDIUM` | 主屏幕中组件（4×2） |
414+
| `LARGE` | 主屏幕大组件（4×4） |
415+
| `CIRCULAR` | 锁屏圆形小组件 |
416+
| `RECTANGULAR` | 锁屏矩形小组件 |
417+
| `INLINE` | 锁屏行内小组件 |
418+
419+
通过 `widget.family` 获取当前尺寸，按需适配不同布局。
420+
421+
##### 特色功能
422+
423+
- **深色模式适配**：颜色支持 `(light_color, dark_color)` 元组，自动跟随系统
424+
- **渐变背景**：`{"gradient": ["#FF6B6B", "#4ECDC4"], "direction": "diagonal"}`，支持 4 个方向
425+
- **图片缓存**：`save_image(source, name)` 支持文件路径和 bytes，自动压缩（限 512KB）
426+
- **深链跳转**：容器和 `render()` 支持 `url` 参数，点击小组件跳转到指定页面
427+
- **快捷模板**：`widget.show(title, value, progress, rows)` 一行代码生成常用布局
428+
429+
##### 代码示例
430+
431+
```python
432+
from widget import Widget, family, SMALL, MEDIUM
433+
434+
w = Widget(background=("#1a1a2e", "#0f0f1a"))
435+
436+
with w.vstack(spacing=8, padding=12):
437+
w.text("🔥 今日目标", size=13, color="#aaa")
438+
with w.hstack(spacing=12):
439+
w.gauge(0.75, label="75%", size=50,
440+
color="#FF6B6B", track_color="#333")
441+
with w.vstack(spacing=4, align="leading"):
442+
w.text("步数 8,432", size=14, weight="semibold", color="white")
443+
w.text("目标 10,000", size=12, color="#888")
444+
w.divider(color="#333")
445+
w.progress(0.6, color="#4ECDC4", height=6, track_color="#222")
446+
447+
w.render()
448+
```
449+
450+
应用内置 **8 款小组件示例**，包括健身环、习惯追踪、学习计时、货币汇率、音乐播放器等，可直接运行体验。
451+
285452
---
286453

287454
### 🔒 隐私与个性化
@@ -302,27 +469,27 @@ Pythonista 兼容的 UI 模块，用 Python 创建原生 iOS 界面（View、But
302469

303470
| 首页 | 编辑器 |
304471
|:---:|:---:|
305-
| <img src="docs/首页.png" width="280"/> | <img src="docs/编辑页面.png" width="280"/> |
472+
| <img src="docs/首页.png" width="280" /> | <img src="docs/编辑页面.png" width="280" /> |
306473
| 文件管理、颜色标记、置顶、搜索、批量操作、回收站 | 语法高亮、智能补全、快捷输入栏、查找替换、分屏 |
307474

308475
| 控制台 | AI 助手 |
309476
|:---:|:---:|
310-
| <img src="docs/控制台页面.png" width="280"/> | <img src="docs/AI分析.png" width="280"/> |
477+
| <img src="docs/控制台页面.png" width="280" /> | <img src="docs/AI分析.png" width="280" /> |
311478
| Rich 彩色输出、进度条、多控制台切换、交互式 input() | Diff 差异对比、逐条采纳/拒绝、一键修复报错、智能装库 |
312479

313480
| 库管理 | 工具箱 |
314481
|:---:|:---:|
315-
| <img src="docs/库管理.png" width="280"/> | <img src="docs/工具箱.png" width="280"/> |
482+
| <img src="docs/库管理.png" width="280" /> | <img src="docs/工具箱.png" width="280" /> |
316483
| PyPI 搜索安装、热门库分类、进度条、版本管理、一键卸载 | 编解码、JSON、API 调试、二维码、时间戳、正则、直链下载 |
317484

318485
| HTML 预览 | Markdown 渲染 |
319486
|:---:|:---:|
320-
| <img src="docs/html预览.png" width="280"/> | <img src="docs/md文件.png" width="280"/> |
487+
| <img src="docs/html预览.png" width="280" /> | <img src="docs/md文件.png" width="280" /> |
321488
| 全屏网页渲染、双指缩放、alert/console 桥接 | 实时渲染，支持标题、列表、代码块、表格、任务列表 |
322489

323490
| 新建文件 | 设置 |
324491
|:---:|:---:|
325-
| <img src="docs/新建文件.png" width="280"/> | <img src="docs/设置.png" width="280"/> |
492+
| <img src="docs/新建文件.png" width="280" /> | <img src="docs/设置.png" width="280" /> |
326493
| 支持 py/js/html/css/md/json 等多种格式，可设置颜色标记 | 外观、编辑器字体、AI 配置、应用锁定、快捷指令帮助 |
327494

328495
---
@@ -331,7 +498,7 @@ Pythonista 兼容的 UI 模块，用 Python 创建原生 iOS 界面（View、But
331498

332499
<p align="center">
333500
<a href="https://apps.apple.com/app/id6753987304">
334-
<img src="https://img.shields.io/badge/App%20Store-立即下载-black?style=for-the-badge&logo=apple&logoColor=white" height="50" />
501+
<img src="https://img.shields.io/badge/App%20Store-下载-black?style=for-the-badge&logo=apple" alt="Download on App Store" height="44" />
335502
</a>
336503
</p>
337504

@@ -364,16 +531,15 @@ Pythonista 兼容的 UI 模块，用 Python 创建原生 iOS 界面（View、But
364531
- **应用内捐赠** — 支持 🍭 棒棒糖 / 🍗 鸡腿 / 🧋 奶茶 三个档位，捐赠后可解锁专属 App 图标
365532

366533
<p align="center">
367-
<img src="docs/donate-qr.jpeg" width="180" alt="赞赏码" />
368-
<br/>
534+
<img src="docs/赞赏码.jpg" width="200" alt="赞赏码" /><br/>
369535
<em>扫码赞赏 · Thank you for your support ♥</em>
370536
</p>
371537

372538
---
373539

374540
## 🙏 致谢 / Thanks
375541

376-
感谢所有使用、反馈和支持 PythonIDE 的开发者们。
542+
感谢所有使用、反馈和支持 PythonIDE 的开发者们。
377543
每一条反馈都推动着这个项目变得更好。
378544

379545
<p align="center">
@@ -384,6 +550,6 @@ Pythonista 兼容的 UI 模块，用 Python 创建原生 iOS 界面（View、But
384550

385551
<p align="center">
386552
<sub>
387-
<strong>Topics</strong> · ios · python · javascript · ide · numpy · pillow · cryptography · app-intents · siri · shortcuts · live-activity · mobile-development · swift · scripting · developer-tools
553+
<strong>Topics</strong> · ios · python · javascript · ide · numpy · pillow · cryptography · app-intents · siri · shortcuts · live-activity · mobile-development · swift · scripting · developer-tools · game-engine · widgets
388554
</sub>
389555
</p>

0 commit comments

Comments
 (0)