Chart 类

Chart 类是 RCT API 的核心类，代表一个完整的谱面数据。

属性

基本属性

chart.version      # int - 谱面格式版本
chart.bpm          # List[BPM] - BPM 变化列表
chart.speed        # List[Speed] - Speed 变化列表
chart.notes        # List[Note] - Note列表

示例：

from rct_api import get_current_chart

chart = get_current_chart()
print(f"版本: {chart.version}")
print(f"BPM 数量: {len(chart.bpm)}")
print(f"Speed 数量: {len(chart.speed)}")
print(f"Note数量: {len(chart.notes)}")

方法

sort()

按时间顺序排序所有Note。

语法

chart.sort()

返回值

无

说明

  • 建议在添加或修改Note后调用
  • 确保Note按时间顺序排列
  • 影响 RCT 编辑器的显示和播放

示例

from rct_api import get_current_chart, save_current_chart, Note

chart = get_current_chart()

# 添加多个Note
chart.add_note(Note.TAP, 3000, 90)
chart.add_note(Note.TAP, 1000, 45)
chart.add_note(Note.TAP, 2000, 180)

# 排序确保顺序正确
chart.sort()

save_current_chart(chart)

filter_notes_by_time()

保留指定时间范围内的Note，删除范围外的Note。

语法

chart.filter_notes_by_time(min_time, max_time)

参数

参数类型说明
min_timefloat最小时间（毫秒）
max_timefloat最大时间（毫秒）

返回值

无

示例

from rct_api import get_current_chart, save_current_chart

chart = get_current_chart()

# 只保留 1000ms - 5000ms 的Note
original_count = len(chart.notes)
chart.filter_notes_by_time(1000, 5000)
new_count = len(chart.notes)

print(f"删除了 {original_count - new_count} 个Note")
save_current_chart(chart)

filter_notes_by_type()

保留指定类型的Note，删除其他类型。

语法

chart.filter_notes_by_type(types)

参数

参数类型说明
typesList[int]要保留的Note类型列表

返回值

无

示例

from rct_api import get_current_chart, save_current_chart, Note

chart = get_current_chart()

# 只保留 Tap 和 Flick Note
chart.filter_notes_by_type([Note.TAP, Note.FLICK])

print(f"保留了 {len(chart.notes)} 个Note")
save_current_chart(chart)

shift_time()

将所有Note、BPM、Speed 的时间平移指定偏移量。

语法

chart.shift_time(offset)

参数

参数类型说明
offsetfloat时间偏移量（毫秒），正数延后，负数提前

返回值

无

示例

from rct_api import get_current_chart, save_current_chart

chart = get_current_chart()

# 所有内容延后 1 秒
chart.shift_time(1000)

# 或者提前 0.5 秒
# chart.shift_time(-500)

save_current_chart(chart)
print("时间平移完成")

add_note()

添加新Note到谱面。

语法

chart.add_note(type, time, degree, *extra)

参数

参数类型说明
typeintNote类型（使用 Note.TAP 等常量）
timefloat时间（毫秒）
degreefloat角度（度，0-360）
*extravaries根据Note类型的额外参数

返回值

无

不同类型Note的参数

Tap Note
chart.add_note(Note.TAP, time, degree)
Flick Note
chart.add_note(Note.FLICK, time, degree)
Catch Note
chart.add_note(Note.CATCH, time, degree)
Bomb Note
chart.add_note(Note.BOMB, time, degree)
Trail Note
chart.add_note(Note.TRAIL, time, degree, delta, prev_curv, next_curv)

参数说明：

  • degree: 起始角度
  • delta: 角度变化量
  • prev_curv: 前置曲率
  • next_curv: 后置曲率
Rotate Note
chart.add_note(Note.ROTATE, time, degree, delta, prev_curv, next_curv)

参数说明：

  • degree: 起始角度
  • delta: 角度变化量
  • prev_curv: 前置曲率
  • next_curv: 后置曲率
Slide Note
chart.add_note(Note.SLIDE, time, degree, slidetype, end_degree, snap, amount, prev_curv, next_curv)

参数说明：

  • degree: 起始角度
  • slidetype: Slide类型
  • end_degree: 结束角度
  • snap: 吸附参数
  • amount: 数量参数
  • prev_curv: 前置曲率
  • next_curv: 后置曲率

示例

from rct_api import get_current_chart, save_current_chart, Note

chart = get_current_chart()

# 添加 Tap Note
chart.add_note(Note.TAP, 1000, 45)

# 添加 Trail Note (起始角度0°, 变化180°)
chart.add_note(Note.TRAIL, 2000, 0, 180, 0, 0)

# 添加 Slide Note
chart.add_note(Note.SLIDE, 3000, 90, 1, 270, 4, 8, 0, 0)

chart.sort()
save_current_chart(chart)
print(f"添加了 3 个Note")

get_note_count_by_type()

统计各类型Note的数量。

语法

counts = chart.get_note_count_by_type()

返回值

字典 {note_type: count}，键为Note类型，值为数量。

示例

from rct_api import get_current_chart, Note

chart = get_current_chart()
counts = chart.get_note_count_by_type()

print("=== Note统计 ===")
print(f"Tap: {counts.get(Note.TAP, 0)}")
print(f"Flick: {counts.get(Note.FLICK, 0)}")
print(f"Slide: {counts.get(Note.SLIDE, 0)}")
print(f"Trail: {counts.get(Note.TRAIL, 0)}")
print(f"Rotate: {counts.get(Note.ROTATE, 0)}")
print(f"Catch: {counts.get(Note.CATCH, 0)}")
print(f"Bomb: {counts.get(Note.BOMB, 0)}")

get_time_range()

获取谱面的时间范围。

语法

min_time, max_time = chart.get_time_range()

返回值

元组 (min_time, max_time)，包含最小和最大时间（毫秒）。

示例

from rct_api import get_current_chart

chart = get_current_chart()
min_time, max_time = chart.get_time_range()

duration = max_time - min_time
print(f"谱面时长: {min_time}ms - {max_time}ms")
print(f"总时长: {duration}ms ({duration/1000:.2f}秒)")

find_distance_by_time()

根据 Speed 变化计算指定时间点的距离值。

语法

distance = chart.find_distance_by_time(time)

参数

参数类型说明
timefloat时间（毫秒）

返回值

浮点数 - 距离值

示例

from rct_api import get_current_chart

chart = get_current_chart()

# 计算 5000ms 时的距离
distance = chart.find_distance_by_time(5000)
print(f"5000ms 时的距离: {distance}")

find_degree_by_time()

从 Trail/Rotate Note插值计算指定时间点的旋转角度。

语法

degree = chart.find_degree_by_time(time)

参数

参数类型说明
timefloat时间（毫秒）

返回值

浮点数 - 角度（度）

示例

from rct_api import get_current_chart

chart = get_current_chart()

# 计算 3500ms 时的旋转角度
degree = chart.find_degree_by_time(3500)
print(f"3500ms 时的角度: {degree}°")

完整示例

综合操作示例

# Description: Chart 类方法综合示例

from rct_api import get_current_chart, save_current_chart, Note

def main():
    chart = get_current_chart()
    if not chart:
        print("错误：无法获取谱面")
        return
    
    # 查看基本信息
    print(f"版本: {chart.version}")
    print(f"Note数量: {len(chart.notes)}")
    
    # 获取时间范围
    min_time, max_time = chart.get_time_range()
    print(f"时间范围: {min_time}ms - {max_time}ms")
    
    # 统计Note类型
    counts = chart.get_note_count_by_type()
    print("\n=== Note统计 ===")
    for note_type, count in counts.items():
        print(f"类型 {note_type}: {count} 个")
    
    # 添加新Note
    chart.add_note(Note.TAP, 5000, 90)
    chart.add_note(Note.FLICK, 6000, 180)
    
    # 过滤Note（只保留前半部分）
    midpoint = (min_time + max_time) / 2
    chart.filter_notes_by_time(min_time, midpoint)
    
    # 时间平移
    chart.shift_time(1000)
    
    # 排序并保存
    chart.sort()
    save_current_chart(chart)
    
    print(f"\n处理完成！现有 {len(chart.notes)} 个Note")

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