Rich Presence Functions - Jamiras/RATools GitHub Wiki
rich_presence_display(format_string, parameters...)
Defines the rich presence display string. Only one string may be defined per script. If this function is called multiple times, the last one will win.
format_string
is a string with zero or more placeholders that will be evaluated by the emulator at runtime. It uses the same syntax as the format
function.
For each placeholder a parameter must be defined using a rich_presence_value
or rich_presence_lookup
function.
rich_presence_value(name, expression, [format])
name
is the name to associate to the placeholder.
expression
is a memory accessor, arithmetic expression, or a function that evaluates to a memory accessor or arithmetic expression.
format
is one of the following:
VALUE
- number (default)SECS
- the value is a number of seconds that should be formatted asMM:SS
FRAMES
- the value is a number of frames that should be converted to seconds and displayed asMM:SS
POINTS
- the value should be displayed as a six digit score value followed by the word 'POINTS'MILLISECS
- the value is a number of hundredths of a second and will be displayed asMM:SS.FF
MINUTES
- the value is a number of minutes that should be formatted asHHhMM
SECS_AS_MINS
- the value is a number of seconds that should be formatted asHHhMM
FLOAT1
...FLOAT6
- the value is formatted to N digits after the decimal (FLOAT1 = 1 digit after the decimal, FLOAT3 = 3 digits after the decimal, etc).FIXED1
...FIXED3
- the value is formatted with a decimal point N spaces from the end (FIXED1 = 1 digit after the decimal).TENS
,HUNDREDS
,THOUSANDS
- the value is padded with additional 0s after the end of the value.
rich_presence_lookup(name, expression, dictionary, [fallback])
name
is the name to associate to the placeholder.
expression
is a memory accessor, arithmetic expression, or a function that evaluates to a memory accessor or arithmetic expression.
dictionary
is the key to value map used to convert the result of expression
into a string.
fallback
is an optional parameter that tells the display string what to display if the value isn't found in the dictionary. If not specified, empty string "" will be displayed when a value is not found in the dictionary.
Example
function lives() => byte(0x05D4) + 1
function stage() => byte(0x003A)
stages = { 1: "Downtown", 2: "Sewers" }
rich_presence_display("{0}, {1} lives",
rich_presence_lookup("Stage", stage(), stages),
rich_presence_value("Lives", lives())
)
rich_presence_macro(macro, expression)
macro
is the name of the built-in macro to use.
Number
- number (default)Score
- number padded with leading 0s to 6 digitsSeconds
- the value is a number of seconds that should be formatted asMM:SS
Centisecs
- the value is a number of hundredths of a second and will be displayed asMM:SS.FF
Minutes
- the value is a number of minutes that should be formatted asHHhMM
ASCIIChar
- the value is converted to a character using the ASCII lookup tableUnicodeChar
- the value is converted to a character using the UCS2 (16-bit unicode) lookup tableFloat1
...Float6
- the value is formatted to N digits after the decimal (Float1 = 1 digit after the decimal, Float3 = 3 digits after the decimal, etc).Fixed1
...Fixed3
- the value is formatted with a decimal point N spaces from the end (Fixed1 = 1 digit after the decimal).
expression
is a memory accessor, arithmetic expression, or a function that evaluates to a memory accessor or arithmetic expression.
rich_presence_conditional_display(condition, format_string, parameters...)
Defines a conditional rich presence display string. When executing the rich presence script, each condition
is examined in order. If a condition is matched, that display string will be used. If no conditions are matched, the default display string will be used. You must still provide a default display string by calling rich_presence_display
.
This function has the same structure as rich_presence_display
with the additional condition
parameter. condition
must evaluate to one or more comparisons.
Example
rich_presence_conditional_display(is_title_screen(), "Title Screen")
rich_presence_display("Playing Battle {0} in {1}",
rich_presence_value("Battle", current_level()),
rich_presence_lookup("Landscape", current_landscape(), landscapes)
)
NOTE: To actually publish the script, you have to copy the script definition to the clipboard (there's a link on the viewer for the rich presence) and paste it into the appropriate field on the website.