核心API

RCT API 提供了一组核心函数，用于与 RCT 编辑器交互和操作谱面数据。

函数列表

get_current_chart()

从 RCT 编辑器获取当前正在编辑的谱面。

语法

from rct_api import get_current_chart

chart = get_current_chart()

返回值

  • 成功：返回 Chart 对象
  • 失败：返回 None

示例

from rct_api import get_current_chart

def main():
    chart = get_current_chart()
    if chart:
        print(f"谱面版本: {chart.version}")
        print(f"Note数量: {len(chart.notes)}")
        print(f"BPM 数量: {len(chart.bpm)}")
    else:
        print("错误：无法获取谱面")

if __name__ == "__main__":
    main()

注意事项

重要

始终检查返回值是否为 None！如果编辑器中没有打开谱面，此函数会返回 None，直接访问会导致脚本崩溃。

  • 此函数获取的是编辑器中的实时数据
  • 修改后需调用 save_current_chart() 才能保存

save_current_chart()

将修改后的谱面保存回 RCT 编辑器。

语法

from rct_api import save_current_chart

save_current_chart(chart)

参数

参数类型说明
chartChart修改后的谱面对象

返回值

无

示例

from rct_api import get_current_chart, save_current_chart

def main():
    chart = get_current_chart()
    if not chart:
        print("错误：无法获取谱面")
        return
    
    # 修改谱面
    chart.shift_time(1000)  # 延后 1 秒
    
    # 保存回编辑器
    save_current_chart(chart)
    print("谱面已保存")

if __name__ == "__main__":
    main()

注意事项

  • 保存前建议调用 chart.sort() 确保Note顺序正确
  • 此操作会直接修改编辑器中的谱面
  • 无法撤销，建议先备份

load_chart_from_file()

从文件加载谱面（不影响编辑器中的谱面）。

语法

from rct_api import load_chart_from_file

chart = load_chart_from_file(path)

参数

参数类型说明
pathstr谱面文件的路径

返回值

  • 成功：返回 Chart 对象
  • 失败：抛出异常

示例

from rct_api import load_chart_from_file

def main():
    try:
        chart = load_chart_from_file("charts/example.txt")
        print(f"加载成功：{len(chart.notes)} 个Note")
    except Exception as e:
        print(f"加载失败：{e}")

if __name__ == "__main__":
    main()

使用场景

  • 批量处理多个谱面文件
  • 比较不同版本的谱面
  • 从模板文件生成新谱面

save_chart_to_file()

将谱面保存到文件。

语法

from rct_api import save_chart_to_file

save_chart_to_file(chart, path)

参数

参数类型说明
chartChart要保存的谱面对象
pathstr输出文件路径

返回值

无

示例

from rct_api import get_current_chart, save_chart_to_file

def main():
    chart = get_current_chart()
    if not chart:
        print("错误：无法获取谱面")
        return
    
    # 保存到文件
    output_path = "output/modified_chart.txt"
    save_chart_to_file(chart, output_path)
    print(f"谱面已保存到：{output_path}")

if __name__ == "__main__":
    main()

使用场景

  • 导出处理后的谱面
  • 创建谱面备份
  • 批量生成谱面文件

完整工作流程示例

以下示例展示了如何组合使用这些核心函数：

# Description: 完整的谱面处理流程

from rct_api import (
    get_current_chart,
    save_current_chart,
    load_chart_from_file,
    save_chart_to_file
)

def main():
    # 1. 从编辑器获取谱面
    chart = get_current_chart()
    if not chart:
        print("错误：无法获取谱面")
        return
    
    print(f"原始Note数量：{len(chart.notes)}")
    
    # 2. 处理谱面
    chart.filter_notes_by_time(1000, 10000)
    chart.shift_time(500)
    chart.sort()
    
    print(f"处理后Note数量：{len(chart.notes)}")
    
    # 3. 保存到编辑器
    save_current_chart(chart)
    print("谱面已更新到编辑器")
    
    # 4. 同时导出到文件
    save_chart_to_file(chart, "output/processed.txt")
    print("谱面已导出到文件")

if __name__ == "__main__":
    main()
最后更新: