scene API 参考 - PythonIDE Docs

scene 提供 Pythonista 兼容的 2D 场景 API（Swift SpriteKit 原生能力入口）。适合游戏与动画；表单/列表请用 appui。

#运行入口

text

scene.run(
    scene_instance: Scene,
    *,
    orientation: int = 0,
    frame_interval: int = 1,
    anti_alias: bool = False,
    show_fps: bool = False,
    multi_touch: bool = True,
) -> None

参数	说明
`orientation`	`DEFAULT_ORIENTATION`(0)、`PORTRAIT`(1)、`LANDSCAPE`(2)
`frame_interval`	`1`≈60fps，`2`≈30fps
`show_fps`	左上角显示帧率
`anti_alias`	抗锯齿
`multi_touch`	是否多点触控

run() 阻塞直到场景视图关闭。关闭时若子类实现了 stop() 会被调用。

#Scene 生命周期

方法	时机
`setup()`	场景首次显示前；`self.size` 已设置
`update()`	每帧；可用 `self.dt`、`self.t`、`self.frame_count`
`draw()`	Classic 模式每帧绘制
`did_evaluate_actions()`	每帧 Action 求值后
`touch_began(touch)` / `touch_moved` / `touch_ended`	触摸事件
`did_change_size()`	尺寸或方向变化
`controller_changed(key, value)`	游戏手柄状态变化
`contact_began(contact)`	物理碰撞（需配置 `contact_test_bitmask`）
`present_modal_scene(other)`	叠加模态子场景
`dismiss_modal_scene()`	关闭当前呈现的模态场景
`pause()` / `resume()`	App 前后台
`stop()`	场景被用户关闭

#场景属性

属性	类型	说明
`size`	`Size`	宽 `w`、高 `h`
`bounds`	`Rect`	场景边界
`background_color`	RGBA 元组或颜色名	背景色
`children`	`list[Node]`	子节点
`physics_world`	`PhysicsWorld`	物理世界
`safe_area_insets`	`EdgeInsets`	安全区
`dt` / `t`	`float`	帧间隔 / 运行时间（秒）
`frame_count`	`int`	帧计数
`touches`	`dict`	当前活动触摸

#节点

#Node（基类）

text

Node(position=(0, 0), *, z_position=0, scale=1, alpha=1, parent=None)

常用属性：position、rotation、x_scale、y_scale、alpha、z_position、parent、children、physics_body、blend_mode、paused、speed

常用方法：add_child、remove_from_parent、run_action、remove_action、remove_all_actions

#SpriteNode

text

SpriteNode(
    texture=None,
    position=(0, 0),
    *,
    size=None,
    color="white",
    z_position=0,
    alpha=1,
    parent=None,
)

第一个位置参数 texture：图片名、Texture 或 None（纯色块）。
纯色精灵：必须 color= 关键字，例如 SpriteNode(color="red", size=(40,40))。

#LabelNode

text

LabelNode(
    text="",
    font=("Helvetica", 20),
    position=(0, 0),
    *,
    parent=None,
)

属性 text、font（元组或名称）可读写。

#ShapeNode

text

ShapeNode(
    path=None,
    fill_color="white",
    stroke_color="clear",
    position=(0, 0),
    *,
    parent=None,
)

#Texture

python

Texture(name_or_image)

属性：size、filtering_mode（FILTERING_LINEAR / FILTERING_NEAREST）

#Action

工厂静态方法（均需 node.run_action(action) 才会执行）：

方法	签名要点
`move_to`	`(x, y, duration=0.5, timing_mode=TIMING_LINEAR)`
`move_by`	`(dx, dy, duration=0.5, timing_mode=...)`
`scale_to`	`(scale, duration=0.5, ...)` — 统一缩放
`scale_by`	相对缩放
`rotate_to` / `rotate_by`	弧度
`fade_to` / `fade_by`	透明度
`sequence(*actions)`	顺序执行
`group(*actions)`	并行执行
`repeat(action, count)`	`count=0` 配合 `repeat_forever`
`wait(duration)`	等待
`remove()`	从父节点移除
`call(func_id, ...)`	回调（通过注册 ID）

#Physics

#PhysicsBody

python

PhysicsBody.rectangle(width=0, height=0, w=0, h=0)
PhysicsBody.circle(radius=0, r=0)

附着：node.physics_body = body（自动绑定到 SpriteKit）

属性	说明
`dynamic`	是否受力和碰撞推动
`affected_by_gravity`	是否受重力
`allows_rotation`	是否可旋转
`restitution`	弹性
`friction`	摩擦
`category_bitmask` / `collision_bitmask` / `contact_test_bitmask`	碰撞过滤

#PhysicsWorld

通过 scene.physics_world 访问；属性 gravity（Vector2）。

#关节

text

PinJoint(node_a, node_b, anchor)
SpringJoint(node_a, node_b, anchor_a, anchor_b, *, damping=0.5, frequency=1.0)
RopeJoint(node_a, node_b, anchor_a, anchor_b)

SpringJoint 的 damping、frequency 必须关键字传递。

#Contact

contact_began(contact) 收到 Contact：node_a、node_b、contact_point、collision_impulse。

#Classic 绘图

仅在 Scene.draw() 内调用。

函数	签名
`background(r, g, b)`	清屏
`fill(r, g, b, a=1)`	填充色
`stroke(r, g, b, a=1)`	描边色
`stroke_weight(w)`	线宽
`rect(x, y, w, h, corner_radius=0)`	矩形
`ellipse(x, y, w, h)`	椭圆外接框
`line(x1, y1, x2, y2)`	线段
`text(txt, font_name='Helvetica', font_size=16, x=0, y=0, alignment=5)`	文字
`image(name, x, y, w, h, ...)`	已加载图片
`translate` / `rotate` / `scale`	变换
`push_matrix` / `pop_matrix`	矩阵栈

#尚未实现 ⚠️

函数	行为
`image_quad(...)`	`NotImplementedError`
`triangle_strip(...)`	`NotImplementedError`

#系统与资源

函数	返回	说明
`get_screen_size()`	`Size`	屏幕点尺寸
`get_screen_scale()`	`float`	Retina 缩放
`get_safe_area_insets()`	`EdgeInsets`	安全区
`gravity()`	`Vector3`	设备加速度方向
`play_effect(name, volume=1, pitch=1)`	—	系统音效
`get_image_path(name)`	`str`	资源路径
`get_controllers()`	`list`	手柄列表

#颜色与坐标

颜色可为 'white'、'#RRGGBB'、(r,g,b)、(r,g,b,a) 或灰度浮点。
坐标原点在左下角，y 向上增大（与 UIKit/SpriteKit 场景坐标一致）。

#使用规则

保留对象用节点；即时绘制用 draw()。
每帧避免创建大量节点、阻塞 I/O、网络请求。
普通业务 UI 不要用 scene 硬做表单。

#相关文档

文档	用途
scene 概览	可运行示例与选型
scene API 索引	名称速查

#失败路径

情况	处理
权限被拒绝	在设置中开启权限后，从用户触发的回调重试
设备或能力不可用	先检查返回值或 `is_available()`，再给用户可读提示
用户取消	保留当前界面状态，不要当作成功继续流程
参数或 API 名错误	对照模块 API 参考与 schema，修正后再运行

#完整导出索引

以下名称与 scene 模块公开导出一致，供检索与 Agent 覆盖校验：

Scene, Node, SpriteNode, LabelNode, ShapeNode, EffectNode, EmitterNode, Action, Texture, Shader, SceneView, Touch, Vector2, Vector3, Size, Rect, Point, EdgeInsets, PhysicsBody, PhysicsWorld, Contact, PinJoint, SpringJoint, RopeJoint, run, get_screen_size, get_screen_scale, gravity, play_effect, get_image_path, get_controllers, get_safe_area_insets, background, fill, no_fill, stroke, no_stroke, stroke_weight, tint, no_tint, rect, ellipse, line, image, text, translate, rotate, scale, push_matrix, pop_matrix, blend_mode, use_shader, load_image, load_image_file, load_pil_image, render_text, unload_image, BLEND_NORMAL, BLEND_ADD, BLEND_MULTIPLY, DEFAULT_ORIENTATION, PORTRAIT, LANDSCAPE, TIMING_LINEAR, TIMING_EASE_IN, TIMING_EASE_IN_2, TIMING_EASE_OUT, TIMING_EASE_OUT_2, TIMING_EASE_IN_OUT, TIMING_SINODIAL, TIMING_EASE_BACK_IN, TIMING_EASE_BACK_OUT, TIMING_EASE_BACK_IN_OUT, TIMING_ELASTIC_IN, TIMING_ELASTIC_OUT, TIMING_ELASTIC_IN_OUT, TIMING_BOUNCE_IN, TIMING_BOUNCE_OUT, TIMING_BOUNCE_IN_OUT, FILTERING_LINEAR, FILTERING_NEAREST

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，请按「失败路径」排查。