Metadata-Version: 2.4
Name: scratch_builder
Version: 1.0.0.dev20261018
Summary: 用 Python 代码生成 Scratch 3.0 项目文件(.sb3)
Author-email: MCPwme <wme9522@outlook.com>
License: MIT
Project-URL: Homepage, https://github.com/MCPwme/Scratch_Builder
Project-URL: Repository, https://github.com/MCPwme/Scratch_Builder
Keywords: scratch,scratch3,education,code-generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Education
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ----- 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
