RSDK 脚本开发技能

概述

本技能为 RSDK（Retro Engine 软件开发工具包）脚本与模组（mod）开发提供全面指导。涵盖 RSDKv3、RSDKv4 以及用于《Sonic Mania》的 RSDKv5，支持从对象脚本编写、场景设计到完整模组打包的全流程开发工作。

核心能力

1. RSDK 版本识别与环境配置

确定目标 RSDK 版本的方法如下：

• 用户显式指定版本（RSDKv3/v4/v5）
• 项目上下文暗示目标游戏（《Sonic Mania》= RSDKv5，《Sonic 1》/《Sonic 2》Remastered = RSDKv4/v3）
• 若未明确指定，默认采用 RSDKv5（最常用版本）

RSDK 各版本差异说明：

• RSDKv3：用于《Sonic 1》Remastered，对象脚本采用类 C 语法
• RSDKv4：用于《Sonic 2》Remastered，对象系统增强
• RSDKv5：用于《Sonic Mania》，功能最丰富，支持复杂模组开发

2. 游戏对象（Object）脚本创建

创建 RSDK 对象脚本需遵循以下流程：

1. 定义对象属性：确定对象类型（Type）、子类型（Subtype）及各项属性
2. 编写对象脚本：使用标准 RSDK 语法规则创建 .txt 格式脚本文件
3. 实现生命周期函数：Create、Update、Draw、StageLoad
4. 添加碰撞与交互逻辑：触碰响应、玩家交互行为等
5. 测试与验证：检查语法正确性及游戏内运行表现

对象脚本模板结构示例：

// Object: [ObjectName]
// Type: [TypeID]

Create:
    // 初始化代码
    return

Update:
    // 每帧更新逻辑
    return

Draw:
    // 渲染代码
    return

StageLoad:
    // 关卡加载时调用
    return

3. 场景与关卡设计

设计 RSDK 场景与关卡需执行以下步骤：

1. 场景数据结构：理解目标 RSDK 版本对应的场景格式
2. 实体布置：放置对象、设置坐标与属性参数
3. 触发器配置：设置触发区域、检查点、边界限制等
4. 图层管理：背景/前景图层组织、滚动行为控制
5. 碰撞与边界设定：配置碰撞路径与关卡物理边界

4. 代码模板与片段

本技能提供可复用的代码模板，存放于 assets/templates/ 目录中：

• 基础对象模板：仅含 Create/Update/Draw 的最小化对象
• 移动平台模板：支持多种运动模式的平台对象
• 敌人模板：具备基础 AI 行为的敌人对象
• 收集物模板：环/监视器/道具等收集逻辑
• 玩家交互模板：响应玩家接触的对象
• 动画模板：精灵动画状态控制逻辑
• 音效模板：音效播放集成逻辑

5. 完整模组开发

开发一个完整的 RSDK 模组需按以下流程进行：

1. 项目结构搭建：建立符合规范的模组目录结构
2. 对象脚本开发：编写所有自定义对象所需脚本
3. 场景修改：编辑或新建场景数据
4. 资源集成：整合精灵图、音效、背景等资源
5. 模组元数据：创建 mod.ini 或对应配置文件
6. 测试与调试：验证模组各项功能是否正常
7. 打包发布：准备模组分发所需的最终包体

RSDK 脚本参考手册

基础语法（RSDKv5）

RSDK 脚本采用类 C 语言，关键要素包括：

变量与类型：

• int：整型数值
• float：浮点型数值
• object：对象引用
• entity：实体引用

内置函数：

• GetPlayer()：获取玩家对象
• CheckCollisionBox()：矩形碰撞检测
• DrawSprite()：渲染精灵图
• PlaySfx()：播放音效
• SetAnimation()：设置精灵动画状态

对象属性：

• position.x、position.y：对象坐标位置
• velocity.x、velocity.y：运动速度矢量
• direction：朝向（0=向左，1=向右）
• visible：是否可见（渲染开关）
• active：是否激活（更新开关）

版本特异性差异

RSDKv5 增强特性：

• 通过 animator 对象实现增强型动画系统
• 引入 Collide() 函数提升碰撞检测精度与灵活性
• 通过 ScrollInfo 结构支持更精细的背景滚动控制
• 集成 ModAPI，原生支持模组加载器扩展机制

工作流指南

新建对象脚本流程

1. 明确对象用途与预期行为
2. 查阅 references/rsdkv5_api.md 获取相关 API 文档
3. 基于 assets/templates/basic_object.txt 模板创建脚本
4. 实现必需的生命周期函数
5. 将新对象加入模组的对象列表
6. 使用模组加载器在游戏内实机测试

修改已有对象流程

1. 定位原始游戏数据中的对象脚本
2. 在模组目录中创建同名覆盖脚本
3. 在保留核心功能的前提下修改目标行为
4. 进行兼容性测试以确保无异常

场景编辑工作流

1. 使用 RSDK 数据提取工具导出场景数据
2. 解析对应 RSDK 版本的场景格式
3. 修改实体布局或新建完整场景
4. 重新打包场景数据文件
5. 在游戏内测试关卡运行效果

资源索引

references/

• references/rsdkv5_api.md：完整的 RSDKv5 API 参考文档
• references/rsdkv3_api.md：RSDKv3 API 参考文档（按需查阅）
• references/rsdkv4_api.md：RSDKv4 API 参考文档（按需查阅）
• references/scene_formats.md：场景数据格式技术说明
• references/mod_structure.md：模组目录结构规范指南

assets/templates/

• assets/templates/basic_object.txt：基础对象模板
• assets/templates/moving_platform.txt：移动平台模板
• assets/templates/enemy_basic.txt：基础敌人 AI 模板
• assets/templates/collectible.txt：收集物模板
• assets/templates/player_interact.txt：玩家交互模板
• assets/templates/mod_ini.txt：mod.ini 配置模板

scripts/

• scripts/validate_syntax.py：RSDK 脚本语法校验工具
• scripts/generate_object.py：根据参数自动生成对象脚本
• scripts/package_mod.py：模组分发包生成工具

重要注意事项

• RSDK 脚本为纯文本文件，通常使用 .txt 扩展名
• 模组内对象类型 ID（Type ID）必须唯一
• 请使用对应游戏的 RSDK 模组加载器进行模组测试
• 修改前务必备份原始游戏数据
• 尊重版权——不得分发提取自原版游戏的资源资产

关键词回顾：RSDK、Retro Engine、Sonic Mania、游戏模组、对象脚本、Object script、RSDKv5、mod development、scene design、关卡设计