-
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: v0.9.8.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
_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" } }
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)
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" }