----- Scratch Builder -----

一个用 Python 代码生成 Scratch 3.0 项目文件（.sb3）的库,让你可以用代码的方式创建 Scratch 项目,适合批量生成教学案例、自动化创作等场景。

版本="v_1.0.0.dev20261018"

---

项目目录结构

scratch_builder v_1.0.0.dev20261016/ ├── src/ │ └── scratch_builder/ │ ├── init.py │ ├── assets.py │ ├── blocks.py │ ├── output.py │ ├── sprite.py │ └── project.py ├── example/ │ ├── python.ico │ ├── sprite.svg │ └── example.py ├── README.md ├── LICENSE ├── pyproject.toml └── .gitignore

运行环境

Python >= 3.8

---

快速开始

1. 安装依赖

进入项目根目录,执行可编辑模式安装：

pip install colorlog

该命令会自动安装唯一的第三方依赖 colorlog,无需手动配置其他库。

2. 第一个项目

from scratch_builder import ScratchProject

创建一个新的 Scratch 项目

project = ScratchProject("我的第一个 Scratch_Builder 生成项目")

设置舞台背景

project.set_backdrop("背景图片文件名(含后缀)")

添加一个角色并设置基础属性

sprite = project.add_sprite("造型文件名称(含后缀)", "角色名") sprite.x = 0 sprite.y = 0 sprite.size = 100

编写简单的绿旗启动脚本

sprite.when_flag_clicked() .move_steps(100) .turn_right(90) .say("你好,我是 Scratch_Builder 生成的角色！", 2)

导出为标准 .sb3 文件

project.save("我的项目.sb3")

生成的 .sb3 文件可以直接在 Scratch 3.0 网页版或离线编辑器中打开运行。

---

语法介绍

1. 项目创建与保存

from scratch_builder import ScratchProject

project = ScratchProject("项目名称") project.set_backdrop("背景图片.png") # 设置舞台背景 project.save("输出文件.sb3") # 保存项目

2. 角色管理

添加角色,指定初始名称和造型

sprite = project.add_sprite("造型名称","角色名")

为角色追加更多造型和声音

sprite.add_costume("造型文件") sprite.add_sound("声音文件")

直接设置角色基础属性

sprite.x = 100 # X 坐标 sprite.y = -50 # Y 坐标 sprite.size = 80 # 大小百分比 sprite.direction = 45 # 方向角度 sprite.visible = True # 是否可见

3. 事件触发积木

所有脚本都以事件积木作为开头,调用后会返回一个 BlockBuilder 对象,支持链式调用后续积木：

sprite.when_flag_clicked() # 当绿旗被点击 sprite.when_key_pressed("space") # 当按下某键 sprite.when_this_sprite_clicked() # 当角色被点击 sprite.when_i_receive("消息名") # 当接收到广播

4. 运动类积木

方法	说明	参数
move_steps(n)	移动 n 步	steps: 步数,默认 10
turn_right(d)	右转 d 度	degrees: 度数,默认 15
turn_left(d)	左转 d 度	degrees: 度数,默认 15
go_to_xy(x, y)	移到指定坐标	x, y: 坐标值
glide_to_xy(x, y, s)	滑行到坐标	x, y: 坐标；seconds: 秒数
set_x(x)	设置 X 坐标	x: 坐标值
set_y(y)	设置 Y 坐标	y: 坐标值
change_x_by(dx)	增加 X 坐标	dx: 增量
change_y_by(dy)	增加 Y 坐标	dy: 增量

5. 外观类积木

方法	说明	参数
say(msg)	显示说话气泡	message: 文本内容
say(msg, sec)	显示说话气泡并等待	message: 文本；seconds: 秒数
think(msg)	显示思考气泡	message: 文本内容
think(msg, sec)	显示思考气泡并等待	message: 文本；seconds: 秒数
switch_costume(name)	切换造型	costume_name: 造型名
next_costume()	下一个造型	无
switch_backdrop(name)	切换背景	backdrop_name: 背景名
change_size_by(n)	改变大小	change: 变化量
set_size_to(n)	设置大小	size: 百分比
show()	显示角色	无
hide()	隐藏角色	无
change_effect_by(effect, n)	改变特效	effect: 特效名；change: 变化量
set_effect_to(effect, n)	设置特效	effect: 特效名；value: 值
clear_effects()	清除图形特效	无

6. 声音类积木

方法	说明	参数
play_sound(name)	播放声音	sound_name: 声音名
play_sound_until_done(name)	播放声音等待结束	sound_name: 声音名
stop_all_sounds()	停止所有声音	无

7. 控制类积木

方法	说明	参数
wait(sec)	等待秒数	seconds: 秒数,默认 1
stop_all()	停止全部脚本	无
stop_this_script()	停止当前脚本	无
stop_other_scripts()	停止其他脚本	无

8. 循环结构

通过 Lambda 函数可以轻松实现嵌套的循环逻辑,完全贴合 Scratch 的积木结构：

重复执行 N 次

sprite.when_flag_clicked() .repeat(10, lambda b: b .move_steps(10) .turn_right(36) )

无限循环

sprite.when_flag_clicked() .forever(lambda b: b .move_steps(5) .wait(0.1) )

9. 广播系统

支持发送普通广播和等待广播完成,实现多角色之间的消息通信：

发送广播

sprite.when_flag_clicked() .broadcast("游戏开始") .wait(2) .broadcast_and_wait("回合结束")

接收广播

sprite.when_i_receive("游戏开始") .say("收到！", 2) .move_steps(50)

10. 变量系统

支持创建全局变量和角色局部变量,提供完整的变量操作方法：

全局变量（所有角色可见）

project.create_global_variable("分数", 0)

角色局部变量

sprite.create_variable("生命值", 100)

方法	说明	参数
set_variable(name, value)	设置变量值	name: 变量名；value: 值
change_variable_by(name, n)	增加变量值	name: 变量名；change: 增量
show_variable(name)	显示变量监视器	name: 变量名
hide_variable(name)	隐藏变量监视器	name: 变量名

使用示例：

sprite.when_flag_clicked() .set_variable("分数", 0) .change_variable_by("分数", 10) .show_variable("分数")

11. 列表系统

支持创建全局列表和角色局部列表,实现批量数据管理：

全局列表

project.create_global_list("物品栏", ["钥匙", "地图"])

角色局部列表

sprite.create_list("对话记录", ["你好", "再见"])

方法	说明	参数
add_to_list(name, item)	添加到末尾	name: 列表名；item: 内容
delete_from_list(name, index)	删除指定项	name: 列表名；index: 序号
delete_all_from_list(name)	删除全部	name: 列表名
insert_to_list(name, item, index)	插入到指定位置	name, item, index
replace_in_list(name, index, item)	替换指定项	name, index, item
show_list(name)	显示列表监视器	name: 列表名
hide_list(name)	隐藏列表监视器	name: 列表名

使用示例：

sprite.when_flag_clicked() .add_to_list("物品栏", "宝剑") .delete_from_list("物品栏", 1) .show_list("物品栏")

---

完整示例

更多可运行的演示代码,请查看项目内的 example/example.py 文件,里面包含了上述大部分功能的组合演示。

---

许可证

MIT License