-
Notifications
You must be signed in to change notification settings - Fork 7
Telesto documentation
This page includes documentation and examples on how to use Telesto, and some tips and tricks for more advanced usage. Please note that this information is relevant to the latest plugin version only - some features and properties may not be available at all on older versions.
Current documentation version: v1.0.0.4
Whenever you see Telesto refer to an expression, that means that the result of the expression and the expression itself will be considered a mathematical expression, and its result will be evaluted. For example, the result of a numeric expression like 2+2 would be 4. Telesto will parse a numeric expression of virtually any complexity, and you can refer to some special variables in the expression as well.
^ = power
% = remainder (for modulo, see numeric function mod)
: = division
/ = division
* = multiplication
+ = addition
- = substraction
Results of these operators are numeric; 1 for true, 0 for false.
> = greater than
≥ = greater or equal than
< = less than
≤ = less or equal than
= = equal
≠ = not equal
pi = 3.1415...
pi2 = 6.2831... (pi * 2)
pi05 = 1.5707... (pi / 2)
pi025 = 0.7853... (pi / 4)
pi0125 = 0.3926... (pi / 8)
pitorad = 57.2957... (for radian/degree conversions)
piofrad = 0.0174... (for radian/degree conversions)
e = 2.7182... (base of the natural logarithm)
phi = 1.6180... (golden ratio)
major = 0.6180... (fibonacci ratio to next value)
minor = 0.3819... (fibonacci ratio to second next value)
abs(x) = absolute value of x
cos(x) = cosine of x
cosh(x) = hyperbolic cosine of x
arccos(x) = arccosine of x
cosec(x) = cosecant of x
sin(x) = sine of x
sinh(x) = hyperbolic sine of x
arcsin(x) = arcsine of x
sec(x) = secant of x
tan(x) = tangent of x
tanh(x) = hyperbolic tangent of x
arctan(x) = arctangent of x
arctan2(x, y) = arctangent of x and y
cotan(x) = cotangent of x
distance(x1, y1, x2, y2) = distance between the two given points
radtodeg(x) = converts radians to degrees
degtorad(x) = converts degrees to radians
max(...) = the largest of the specified numbers
min(...) = the smallest of the specified numbers
random(x, y) = random integer that is greater or equal to x, and less than y (x >= ... < y)
sqrt(x) = square root of x
root(x, y) = the yth root of x (root(25, 2) = square root of 25, root(125, 3) = cube root of 125)
rem(x, y) = remainder of the division of x and y (IEEE standard remainder, not the same thing as modulus)
pow(x, y) = x to the power of y
exp(x) = e to the power of x
log(x) = natural (base e) logarithm of x
log(x, y) = base y logarithm of x
round(x) = rounds x to the nearest integer
round(x, y) = rounds x with y decimals
floor(x) = rounds down the previous integer
ceiling(x) = rounds up the next integer
sign(x) = returns the sign of x (-1 = x is negative, 0 = x is zero, 1 = x is positive)
hex2dec(x) = converts a base16 (hex) number to base10 (decimal)
hex2float(x) = converts a base16 (hex) number to a single-precision floating point number
hex2double(x) = converts a base16 (hex) number to a double-precision floating point number
or(...) = returns 1 if any of the specified numbers is other than zero, 0 if not
and(...) = returns 1 if all of the specified numbers are other than zero, 0 if not
if(x,y,z) = returns y if x is non-zero, z if x is zero (for example, if (2>3,4,5) would return 5
mod(x, y) = modulus of x divided by y
Telesto generates some special variables, which can be used in your expressions. The list is as follows:
_systemtime = UNIX timestamp of the current system time
_systemtimems = UNIX timestamp of the current system time in milliseconds
_sin[x] = Samples a sine wave generated at the given frequency (x hz), range is -1 ... +1
_cos[x] = Samples a cosine wave generated at the given frequency (x hz), range is -1 ... +1
_screenwidth = Width of the game screen
_screenheight = Height of the game screen
_ffxivplayer = Name of the currently logged in player
_ffxiventity = A special array-type variable that represents all currently known entities in the game world
Special variable _ffxiventity can be addressed through several methods:
_ffxiventity[Titan] = actor with the given name in the combatant list (returns the first one found, if multiple exist)
_ffxiventity[1234ABCD] = actor with the given ID in the combatant list
Properties available _ffxiventity:
name = Name of the actor
job = Current job as a three letter acronym (AST, CUL, MIN, SMN, etc)
jobid = Numeric (internal ingame) representation of the current job
currenthp, currentmp, currentcp, currentgp = Current HP, MP, CP, and GP
maxhp, maxmp, maxcp, maxgp = Maximum HP, MP, CP, and GP
level = Level of the actor
x, y, and z = Position information of the actor
id = Hexadecimal ID of the actor
heading = Heading of the entity in radians (South 0, North ±PI)
targetid = Hexadecimal ID of the actor currently selected as target (0 is there is no target selected)
casttargetid = Hexadecimal ID of the actor the current cast is targetting (0 is there is no cast in progress)
distance = Distance from the main combatant (you) to the entity
role = Role of the actor ("Tank", "Healer", "DPS", "Crafter", "Gatherer", or blank if not available)
Telesto telegrams are JSON, and the general form is { "version": 1, "id": x, "type": y, "payload": z }, where:
- x is a numeric identifier for the telegram (not currently in use, may be used later in replies)
- y is the telegram type
- z is the payload relevant to the telegram (telegrams have their own individual payload specifications)
These are the telegrams currently available in Telesto:
Prints a message in chat log. Properties:
message: Message to print
Example: { "version": 1, "id": 123456, "type": "PrintMessage", "payload": { "message": "hello world" } }
Prints an error message in chat log. Properties:
message: Message to print
Example: { "version": 1, "id": 123456, "type": "PrintError", "payload": { "message": "hello world" } }
Executes an ingame command. Properties:
command: Command to execute ingame
Example: { "version": 1, "id": 123456, "type": "ExecuteCommand", "payload": { "command": "/mk attack1 <1>" } }
Opens a map and sets a flag marker. Properties:
coords: Is either raw for specifying raw coordinate data, or world for human-readable in-game coordinate data
territory: Id of the territory for the map link
map: Id of the map for the map link
x: X coordinate of the map link
y: Y coordinate of the map link
Example: { "version": 1, "id": 123456, "type": "OpenMap", "payload": { "territory": 160, "map": 108, "coords": "world", "x": 12, "y": 12 } }
A bundle of telegrams. The payload is simply a JSON array of telegrams.
Example: { "version": 1, "id": 123456, "type": "Bundle", "payload": [ { "id": 123456, "type": "PrintMessage", "payload": { "message": "hello world" } }, { "id": 123456, "type": "ExecuteCommand", "payload": { "command": "/mk attack1 <1>" } } ] }
Enables a doodle to be rendered. Doodles are a feature that allows you to draw things on screen, and into the game world. Please refer to Doodle specification for more details.
Disables a single doodle. Properties:
name: Name of the doodle to disable
Example: { "version": 1, "id": 123456, "type": "DisableDoodle", "payload": { "name": "meow3" } }
Disables multiple doodles by matching their IDs with the supplied regex. Properties:
regex: Pattern specifying doodles to disable
Example: { "version": 1, "id": 123456, "type": "DisableDoodleRegex", "payload": { "regex": "meow.*" } }
Subscribes to notifications, which are delivered to a HTTP endpoint. Properties:
id: Friendly unique name for the subscription, specifying a name in use will overwrite the subscription
type: Type of the subscription, currently only memory is available for monitoring memory changes
endpoint: HTTP endpoint to which notifications would be delivered.
Properties relevant for memory type:
start: Start address of the block to monitor (to get the GameObject's base address, you can use ${_addr[GameObject]}), supports numeric expressions
length: Length of the block to monitor in bytes, supports numeric expressions
representation: Representation in which notifications are delivered. If not specified, defaults to a unsigned numeric type for that length, or string otherwise. Valid types are: bool, byte, char, double, short, int, long, float, ushort, uint, ulong, and string
Example: { "version": 1, "id": 123456, "type": "Subscribe", "payload": { "id": "partysynergy", "type": "memory", "endpoint": "http://localhost:51423/", "start": "${_addr[GameObject]}+452", "length": "4" } }
Notifications delivered to the HTTP endpoint would then be formatted like this:
{"version":1,"id":1,"notificationid":"mythings","notificationtype":"hp","payload":{"objectid":"40001D88","name":"Evil Dreamer","oldvalue":"94557","newvalue":"89330"}}
Unsubscribes from a memory change notification. Properties:
id: Friendly unique name for the subscription
Example: { "version": 1, "id": 123456, "type": "Unsubscribe", "payload": { "id": "mythings" } }
Executes an in-game macro. Properties:
id: ID number of the macro (0-99)
shared: Whether referring to a personal or shared macro, defaults to false (= personal macro)
Example: { "version": 1, "id": 123456, "type": "Macro", "payload": { "shared": "true", "id": "99" } }
Displays an in-game form for the user, allowing results to be submitted. Properties:
id: ID name of the form (my_cool_form)
title: Title of the form
callback: Callback to which the results will be sent
elements: An array of form elements
If the form is submitted, data from relevant form elements will be collected into a notification: {"version":1,"id":0,"source":"FormSubmit","response":{"pact_with_satan":"True","bonk":null,"_formid":"my_cool_form"}}
If the form is cancelled or closed, the following notification will be sent to the callback: {"version":1,"id":0,"source":"FormCancel","response":{"_formid":"my_cool_form"}}
The source field in the notification is either FormSubmit or FormCancel depending on the action, and the response contains all the data from the form in case it was a submission. In both cases, an internal ID _formid will be added to the response data which will relay the ID name of the form that was acted on.
Please refer to Form element specification for more details on how to specify form elements.
Example: { "version": 1, "id": 123456, "type": "Form", "payload": { "id": "my_cool_form", "title": "My very own cool form", "callback": "http://localhost:51423", "elements": [ { "id": "blah", "type": "label", "text": "It works!" }, { "type": "checkbox", "text": "I accept the terms and conditions", "id": "pact_with_satan" }, { "type": "button", "id": "bonk", "text": "Yippee!", "action": "Submit" } ] } }
Doodles are drawings you can place on the screen, either in screen space or in the game world. There are several properties common to all doodles:
name: Name of the doodle, unique between all doodles. Specifying a second doodle with the same name will overwrite the first one.
r: Red component of the doodle's color, range from 0.0 to 1.0, default is 0 if omitted (supports numeric expressions)
g: Green component of the doodle's color, range from 0.0 to 1.0, default is 0 if omitted (supports numeric expressions)
b: Blue component of the doodle's color, range from 0.0 to 1.0, default is 0 if omitted (supports numeric expressions)
a: Alpha component (opacity) of the doodle's color, range from 0.0 to 1.0, default is 1 if omitted (supports numeric expressions)
notifyonexpiry: An optional remote endpoint to which a notification will be sent when the doodle expires for any reason
expiresin: Number of milliseconds the doodle is alive, default is 5000 if omitted (also implies expireson = timed if specified)
expireson: Specifies different ways for the doodle to expire as a comma-separated list (for ex. timed,ondeath,onwipe):
timed: Assumed by default if expiresin has been specified
ondeath: Doodle expires on player death
onwipe: Doodle expires on full party wipe (assumed by default if expireson has not been explicitly defined)
onzonechange: Doodle expires when changing zone (assumed by default if expireson has not been explicitly defined)
notloggedin: Doodle expires when not in-game (assumed by default if expireson has not been explicitly defined)
Available doodle types are as follows:
Draws a dynamically scaling arrow from one point to another. Properties:
thickness: Line thickness, 3 by default if omitted (supports numeric expressions)
from: Start point of the arrow (refer to coordinate specification for more details)
to: End point of the arrow, where it will be pointing (refer to coordinate specification for more details)
system: Which coordinate system the arrow should be placed in, screen (default) or world
Example: { "version": 1, "id": 123456, "type": "EnableDoodle", "payload": { "name": "meow2", "type": "arrow", "r": "1", "g": "1", "expiresin": "5000000", "thickness": "10", "system": "world", "from": { "coords": "entity", "name": "Summoning Bell" }, "to": { "coords": "waymark", "name": "4" } } }
Draws a beam from one point to another. Properties:
thickness: Line thickness, 3 by default if omitted (supports numeric expressions)
width: Width of the beam, 1 by default if omitted (supports numeric expressions)
length: Length of the beam, 1 by default if omitted, if negative then the beam will end at the target point instead of going through (supports numeric expressions)
from: Start point of the beam (refer to coordinate specification for more details)
at: Target of the beam, where it will be firing (refer to coordinate specification for more details)
system: Which coordinate system the arrow should be placed in, screen (default) or world
Example: { "version": 1, "id": 123456, "type": "EnableDoodle", "payload": { "name": "meow2", "type": "beam", "r": "1", "g": "1", "expiresin": "5000000", "thickness": "3", "width": "3", "length": "100", "system": "world", "from": { "coords": "entity", "name": "Summoning Bell" }, "at": { "coords": "waymark", "name": "4" } } }
Draws a circle, simple enough. Properties:
thickness: Line thickness, 1 by default if omitted (supports numeric expressions)
radius: Radius of the circle, 10 by default if omitted (supports numeric expressions)
filled: Specifies whether the circle is filled (true) or not (false, default value)
position: Center point of the circle (refer to coordinate specification for more details)
system: Which coordinate system the arrow should be placed in, screen (default) or world
Example: { "version": 1, "id": 123456, "type": "EnableDoodle", "payload": { "name": "meow3", "type": "circle", "r": "1", "g": "1", "expiresin": "1000000", "radius": "20", "system": "world", "position": { "coords": "entity", "name": "Market Board" } } }
Draws a line from one point to another. Properties:
thickness: Line thickness, 1 by default if omitted (supports numeric expressions)
start: Start point of the line (refer to coordinate specification for more details)
end: End point of the line (refer to coordinate specification for more details)
Example: { "version": 1, "id": 123456, "type": "EnableDoodle", "payload": { "name": "meow2", "type": "line", "r": "1", "g": "1", "expiresin": "5000000", "thickness": "10", "start": { "coords": "entity", "name": "Summoning Bell" }, "end": { "coords": "waymark", "name": "4" } } }
Draws a rectangle where the points are opposite vertices of each other. Properties:
thickness: Line thickness, 1 by default if omitted (supports numeric expressions)
filled: Specifies whether the circle is filled (true) or not (false, default value)
pos1: One vertex of the rectangle (refer to coordinate specification for more details)
pos2: Another, opposite vertex of the rectangle (refer to coordinate specification for more details)
system: Which coordinate system the arrow should be placed in, screen (default) or world
Example: { "version": 1, "id": 123456, "type": "EnableDoodle", "payload": { "name": "meow2", "type": "rectangle", "r": "1", "g": "1", "expiresin": "5000000", "thickness": "3", "system": "world", "pos1": { "coords": "entity", "name": "Summoning Bell" }, "pos2": { "coords": "waymark", "name": "4" } } }
Draws a text string. Properties:
position: Top left position of the text, top left aligned (refer to coordinate specification for more details)
size: Size of the text, 10 by default if omitted (supports numeric expressions)
halign: Horizontal alignment of the text; possible values are near/left (default), middle/center, and far/right
valign: Vertical alignment of the text; possible values are near/top (default), middle/center, and far/bottom
Example: { "version": 1, "id": 123456, "type": "EnableDoodle", "payload": { "name": "meow2", "type": "text", "r": "1", "g": "1", "expiresin": "1000000", "text": "HELLO WORLD!", "size": "20", "position": { "coords": "entity", "name": "Market Board" } } }
Draws a cheap knockoff waymark. Properties:
position: Location of the waymark (refer to coordinate specification for more details)
Example: { "version": 1, "id": 123456, "type": "EnableDoodle", "payload": { "name": "meow3", "type": "waymark", "g": "1", "expiresin": "5000000", "position": { "coords": "world", "x": "34", "y": "65.9", "z": "-118" } } }
Draws a image from game resources. Properties:
icon: Numeric ID of the ingame resource to display
width: Width of the image, 100% by default (supports numeric expressions, but also percentage sizes like 50%)
height: Height of the image, 100% by default (supports numeric expressions, but also percentage sizes like 50%)
halign: Horizontal alignment of the image; possible values are near/left (default), middle/center, and far/right
valign: Vertical alignment of the image; possible values are near/top (default), middle/center, and far/bottom
Example: { "version": 1, "id": 123456, "type": "EnableDoodle", "payload": { "name": "meow1", "type": "image", "expiresin": "1000000", "halign": "center", "valign": "center", "icon": "66322", "position": { "coords": "entity", "name": "Market Board" } } }
Draws a donut shape (aka Lunar Dynamo) around a point. Properties:
innerradius: Distance from the center to the inner edge of the donut, 10 by default if omitted (supports numeric expressions)
outerradius: Distance from the center to the outer edge of the donut, 15 by default if omitted (supports numeric expressions)
thickness: Line thickness, 1 by default if omitted (supports numeric expressions)
filled: Specifies whether the donut is filled (true) or not (false, default value)
position: Center point of the donut (refer to coordinate specification for more details)
Example: { "version": 1, "id": 123456, "type": "EnableDoodle", "payload": { "name": "meow3", "type": "donut", "r": "1", "g": "1", "expiresin": "1000000", "outerradius": "15", "thickness": "2", "filled": "true", "innerradius": "10", "system": "world", "position": { "coords": "entity", "name": "Player Name" } } }
Draws a cone from a point at a specific angle. Properties:
radius: Radius of the cone from the center, 10 by default if omitted (supports numeric expressions)
thickness: Line thickness, 1 by default if omitted (supports numeric expressions)
angle: Angle, or width, of the cone in radians, PI/2 by default if omitted (supports numeric expressions)
heading: Heading of the cone in radians, 0 by default if omitted (supports numeric expressions)
filled: Specifies whether the cone is filled (true) or not (false, default value)
position: Center point of the cone (refer to coordinate specification for more details)
Example: { "version": 1, "id": 123456, "type": "EnableDoodle", "payload": { "name": "meow3", "type": "cone", "r": "1", "g": "1", "expiresin": "1000000", "radius": "15", "thickness": "2", "angle": "pi025", "heading": "${_ffxiventity[Player Name].heading}", "filled": "true", "system": "world", "position": { "coords": "entity", "name": "Player Name" } } }
Doodles can have one or multiple coordinate definitions to them, and they can refer to positions on the screen, the world, in-game objects, etc. The coordinate specification is as follows:
Properties:
x: Position from the left of the screen (supports numeric expressions)
y: Position from the top of the screen (supports numeric expressions)
Example: { "coords": "screen", "x": "200", "y": "100" }
Properties:
x: Position on the x plane, what you might generally understand as left/right (supports numeric expressions)
y: Position on the y plane, what you might generally understand as up/down (supports numeric expressions)
z: Position on the z plane, what you might generally understand as forward/backward (supports numeric expressions)
Example: { "coords": "world", "x": "34", "y": "65.9", "z": "-118" }
Offsetting can be helpful when attaching something to an entity, but you want to draw something a little away from it.
Properties:
offsetx: Offset on the x plane, what you might generally understand as left/right (supports numeric expressions)
offsety: Offset on the y plane, what you might generally understand as up/down (supports numeric expressions)
offsetz: Offset on the z plane, what you might generally understand as forward/backward (supports numeric expressions)
Example: { "coords": "entity", "name": "Market Board", "offsetx": "(2+${_sin[0.2]})*cos(${_systemtimems}/1000)" }
Properties:
id: Hexadecimal ID of the entity
name: Name of the entity (returns the first one found, if multiple exist)
Example: { "coords": "entity", "id": "1234ABFD" }
Example: { "coords": "entity", "name": "Summoning Bell" }
Properties:
name: Name of the doodle; if the doodle has multiple coordinates, you can specify which one by using name/coordinate name
Example: { "coords": "doodle", "name": "My cute waymark doodle" }
Example: { "coords": "doodle", "name": "My cute line doodle/start" }
Properties:
name: Name of the waymark (any of the following: A, B, C, D, 1, 2, 3, 4)
Example: { "coords": "waymark", "name": "A" }
Forms comprise of several elements, some of which will report their value to the caller on form submission. There are several properties common to all form elements:
id: ID name of the element unique to the form
value: Default value for the element
type: Type of the element
Available element types are as follows:
Displays a clickable button on the form. Properties:
text: Text to display on the button
payload: Optional payload data
action: The action to take when button is clicked:
None: No action (default)
Payload: Execute the payload as if it was another telegram sent to Telesto
Submit: Submits the form, sending a FormSubmit to the callback
Cancel: Cancels the form, sending a FormCancel to the callback
Note that the clicked button will also report its id/value to the callback, allowing you to see which button was clicked.
Example: { "version": 1, "id": 123456, "type": "Form", "payload": { "id": "my_cool_form", "title": "My very own cool form", "callback": "http://localhost:51423", "elements": [ { "type": "button", "id": "bonk", "text": "Yippee!", "action": "Submit" } ] } }
Displays a checkbox on the form. Properties:
text: Text to display on the checkbox
Example: { "version": 1, "id": 123456, "type": "Form", "payload": { "id": "my_cool_form", "title": "My very own cool form", "callback": "http://localhost:51423", "elements": [ { "type": "checkbox", "text": "I accept the terms and conditions", "id": "pact_with_satan" } ] } }
Embeds hidden data on the form, which will get reported to the callback on submission. This element has no special properties.
Example: { "version": 1, "id": 123456, "type": "Form", "payload": { "id": "my_cool_form", "title": "My very own cool form", "callback": "http://localhost:51423", "elements": [ { "id": "my_secret_data", "type": "hidden", "text": "ssh dont let anyone see it" } ] } }
Displays an integer selection on the form. Properties:
text: Text to display on the selector
minvalue: Minimum value allowed (0 by default)
maxvalue: Maximum value allowed (10 by default)
Example: { "version": 1, "id": 123456, "type": "Form", "payload": { "id": "my_cool_form", "title": "My very own cool form", "callback": "http://localhost:51423", "elements": [ { "id": "blah", "type": "inputint", "text": "Awesomeness", "minvalue": "0", "maxvalue": "100" } ] } }
Displays a text entry box on the form. Properties:
text: Text in the input box
maxlength: Maximum length allowed (256 by default)
Example: { "version": 1, "id": 123456, "type": "Form", "payload": { "id": "my_cool_form", "title": "My very own cool form", "callback": "http://localhost:51423", "elements": [ { "id": "blah", "type": "inputtext", "text": "enter thine name brave adventurer" } ] } }
Displays a non-interactable text label on the form. Properties:
text: Text in the input box
Example: { "version": 1, "id": 123456, "type": "Form", "payload": { "id": "my_cool_form", "title": "My very own cool form", "callback": "http://localhost:51423", "elements": [ { "id": "blah", "type": "label", "text": "It works!" } ] } }
Allows for some additional layout manipulation on the form. Properties:
action: Type of layout action
Break: Adds an empty space
Separator: Adds a horizontal line separator
Example: { "version": 1, "id": 123456, "type": "Form", "payload": { "id": "my_cool_form", "title": "My very own cool form", "callback": "http://localhost:51423", "elements": [ { "type": "layout", "id": "bonk", "action": "Separator" } ] } }