Script Metadata

Each script should include metadata comments at the beginning of the file for display in the script manager.

Required Metadata

Description

# Description: Brief description of the script
  • Chinese Support: You can now use Chinese in descriptions
  • Display Format: Prefix is automatically added based on interface language (Chinese interface shows "简介:", English interface shows "Description:")
  • Position Requirement: Must be at the beginning of the file

Example:

# Description: Count and display various types of notes

Optional Metadata

Args (Parameter Description)

# Args: Parameter description, e.g.: Start time(ms) End time(ms)

Used to describe the parameters required by the script, displayed in the script manager.

Example:

# Description: Shift all note times
# Args: Offset(ms) - Positive delays, negative advances

UI (Custom Interface)

# UI: {"fields":[...]}

Define custom input dialog, see Custom UI Dialog chapter for details.

Example:

# Description: Delete notes of specified type
# UI: {"fields":[{"name":"note_type","field_type":"select","label":"Note Type:","default_value":"bomb","options":["tap","flick","slide","bomb"]}]}

Complete Examples

Simple Script

# Description: Print chart information

from rct_api import get_current_chart

def main():
    chart = get_current_chart()
    if chart:
        print(f"Note count: {len(chart.notes)}")

if __name__ == "__main__":
    main()

Script with Parameters

# Description: Note time shift tool
# Args: Offset(ms)

import sys
from rct_api import get_current_chart, save_current_chart

def main():
    if len(sys.argv) < 2:
        print("Error: Please provide offset parameter")
        return
    
    offset = float(sys.argv[1])
    chart = get_current_chart()
    
    if chart:
        chart.shift_time(offset)
        save_current_chart(chart)
        print(f"Time shift of {offset}ms complete")

if __name__ == "__main__":
    main()

Script with Custom UI

# Description: Delete notes by type
# UI: {"fields":[{"name":"note_type","field_type":"select","label":"Type to delete:","default_value":"bomb","options":["tap","flick","bomb"]}]}

import sys
import json
from rct_api import get_current_chart, save_current_chart, Note

def main():
    if len(sys.argv) < 2:
        return
    
    params = json.loads(sys.argv[1])
    note_type = params.get('note_type')
    
    # Processing logic...
    print(f"Delete {note_type} type notes")

if __name__ == "__main__":
    main()

Notes

  1. Encoding: File must use UTF-8 encoding
  2. Position: Metadata comments must be at the beginning of the file
  3. Format: Strictly follow # Key: Value format
  4. Required: Description is required, others are optional