Scratch Builder

Scratch Builder 是一个 Python 库，可通过代码生成 Scratch 3.0 项目文件（.sb3）。

• 当前版本：1.0.0.dev20261020
• Python：3.7 或更高版本
• GitHub：https://github.com/MCPwme/Scratch_Builder
• PyPI：https://pypi.org/project/scratch-builder/

安装

从 PyPI 安装：

pip install scratch_builder

或者在项目根目录安装本地源码：

pip install .

快速开始

下面的示例使用项目内的 example/cat.svg 作为角色造型，生成 example/hello.sb3：

from pathlib import Path

from scratch_builder import ScratchProject

example_dir = Path(__file__).resolve().parent / "example"
cat_image = example_dir / "cat.svg"

project = ScratchProject("我的第一个项目")
project.set_backdrop(str(cat_image), name="背景")

cat = project.add_sprite("主角", str(cat_image))
cat.x = 0
cat.y = 0
cat.size = 100
cat.direction = 90
cat.visible = True

(
    cat.when_flag_clicked()
    .go_to_xy(0, 0)
    .move_steps(100)
    .turn_right(90)
    .glide_to_xy(100, 50, 1)
)

project.save(str(example_dir / "hello.sb3"))

也可以直接运行完整示例：

python example/example.py

该脚本会在 example 目录中生成 example.sb3。生成的项目可以用 Scratch 3.0 网页版或离线编辑器打开。

项目与角色 API

创建项目、角色和舞台背景

project = ScratchProject("项目名称")
sprite = project.add_sprite("角色名称", "造型文件.svg")
project.set_backdrop("背景文件.svg", name="背景名称")
project.save("输出文件.sb3")

• ScratchProject(name="My Project")：创建项目。
• add_sprite(name="Sprite", costume_path=None)：添加角色。提供造型文件路径后会加载该造型。
• set_backdrop(file_path, name="backdrop1")：设置舞台背景。
• save(output_path)：导出 .sb3 文件。

素材路径相对于运行脚本时的工作目录解析。示例脚本使用 pathlib.Path(__file__) 定位素材，便于从其他目录运行。

角色属性

添加角色后，可设置以下属性：

sprite.x = 100
sprite.y = -50
sprite.size = 80
sprite.direction = 45
sprite.visible = True
sprite.draggable = False
sprite.rotationStyle = "all around"

事件

当前实现提供绿旗事件入口：

sprite.when_flag_clicked().move_steps(10)

事件返回积木构建器，可继续链式调用后续积木。

当前支持的积木

运动

运算报告器

当前提供以下报告器构建方法：x_position()、y_position()、direction()、add(a, b)、subtract(a, b)、multiply(a, b)、divide(a, b)、pick_random(min_val, max_val)、greater_than(a, b)、less_than(a, b)、equals(a, b)、and_op(a, b)、or_op(a, b)、not_op(a)、join(str1, str2)、letter_of(index, string)、length_of(string)、contains(string, substring)、mod(a, b)、round_num(n) 和 math_function(operator, n)。

math_function 的 operator 可使用 Scratch 数学运算名称，例如 "sqrt"、"sin" 或 "abs"。

侦测报告器与积木

当前提供：touching_mouse_pointer()、touching_edge()、touching_sprite(sprite_name)、key_pressed(key)、mouse_down()、mouse_x()、mouse_y()、distance_to_mouse()、distance_to_sprite(sprite_name)、ask_and_wait(question)、answer()、get_username()、current_date(date_type) 和 days_since_2000()。

key_pressed 支持 "space"、方向键名称和 "any" 等按键值。current_date 的 date_type 可使用 "year"、"month"、"day"、"hour"、"minute"、"second" 或 "dayofweek"。

运算和侦测方法中的报告器目前只提供积木构建接口；条件、循环以及将报告器嵌入其他积木的组合接口尚未实现。

尚未支持

当前版本尚未实现 README 旧版中提到的按键/点击/广播事件、外观与声音积木、控制积木、循环、变量和列表操作。因此这些接口不能直接在当前版本的脚本中调用。

许可证

MIT License