API reference
Introduction
AT's application programming interface was introduced in version 1.3.0 and is entirely mcfunction-based. Its purpose is to provide a unified way to interact with AT's timer and configuration systems, thereby facilitating implementation into external projects. All API functions are located in the at-tapi namespace and write their result values to NBT storage.
Methods
Inspired by SNMP, the API system can be divided into three request types, also known as methods:
Get: Enables reading of timer data (timer units, configuration vales, ...)
Set: Enables modifying timer data (timer units, configuration vales, ...)
Trap: Notifies based on timer events (continue, pause, reset, reach full timer unit, ...)
Result values
When invoked, API functions provide some information about the type of request as well as multiple return values, indicating whether the current request was successful or failed. This data is written to AT's main NBT storage animated-timer:data (path: at.api.result). Due to compatibility reasons (especially in cases where multiple entities are querying the API), this path cannot be changed.
In detail, the API provides the following result values:
at.api.result.data
Compound
Output data of API Get function
at.api.result.message
String
Brief description of request status Sample values: "OK", "Applied successfully", "Error: ..."
at.api.result.request_context
String
Request target / API endpoint Sample values: "full_configuration", "visibility", "remove"
at.api.result.request_method
String
Type of request Possible values: "get", "set", "trap"
at.api.result.return_code
Byte
Return code of API function Possible values: 0b - Error 1b - Success
at.api.result.success
Byte
Only set if API function returns success Possible values: 1b - Success
In addition to the return_code being accessible through NBT storage, it is also returned directly from all API functions. This enables /execute structures like this to work:
/execute if function at-tapi:set/render/caz run say Changed render type to CAZ.
Functions - Get
As there is no situation where any of the below API Get functions will fail, they always return with 1. The term "Output" refers to the values that are saved to at.api.result.data during execution.
Actionbar string
Description: Reads final actionbar string including render patterns. Prefix & suffix fields are excluded.
Usage: /function at-tapi:get/actionbar_string
actionbar
String
Timer: 2h 43m 12s
Current time
Description: Reads individual timer units including ticks.
Usage: /function at-tapi:get/current_time
tick
Integer
14
second
Integer
58
minute
Integer
3
hour
Integer
22
day
Integer
0
Full configuration
Description: Reads both visual & behavioral configuration settings.
Usage: /function at-tapi:get/full_configuration
Note: Many values, especially boolean ones, internally use numbers to represent their current state. Because of this, the API system reads both its numerical value (_num) as well as verbose one (_vrb), each of which having their own suffixes attached.
The values featured below are just a small selection of what is actually being read by the API function:
mode_num
Integer
2
mode_vrb
String
down
pattern
String
Timer: %t
prefix
String
Hello world!
static_bold1_num
Integer
0
static_bold1_vrb
String
false
animated_animation
String
purple-orange
Restore values
Description: Reads timer restore values (last manually set time thats get loaded when counting down timer is being reset).
Usage: /function at-tapi:get/restore_values
second
Integer
0
minute
Integer
0
hour
Integer
12
day
Integer
1
Timer state
Description: Reads timer paused / counting up / counting down state.
Usage: /function at-tapi:get/timer_state
numerical
Integer
1
verbose
String
up
Functions - Set
Timer controls
Control timer state (paused / running)
/function at-tapi:set/state/paused
/function at-tapi:set/state/running
Set current time Possible errors: Invalid time specified
/function at-tapi:set/time {tick:0,second:0,minute:30,hour:1,day:0}
Configuration
Control timer mode (up / down)
/function at-tapi:set/mode/up
/function at-tapi:set/mode/down
Control player requirement
/function at-tapi:set/online/ignored
/function at-tapi:set/online/required
Change render pattern Possible errors: Pattern exceeds max length Pattern cannot be empty
/function at-tapi:set/pattern {text:"%t"}
Change timer prefix
/function at-tapi:set/prefix {text:"foo "}
Change timer suffix
/function at-tapi:set/suffix {text:" bar"}
Control render type
/function at-tapi:set/render/caz
/function at-tapi:set/render/saz
/function at-tapi:set/render/snz
/function at-tapi:set/render/taz
/function at-tapi:set/render/tnz
Control style type
/function at-tapi:set/style/static
/function at-tapi:set/style/animated
Control trigger scoreboards
/function at-tapi:set/trigger/disabled
/function at-tapi:set/trigger/enabled
Control visibility
/function at-tapi:set/visibility/hidden
/function at-tapi:set/visibility/shown
Static style type
Control bold style of primary zone Possible errors: Wrong style type
/function at-tapi:set/static_bold1/false
/function at-tapi:set/static_bold1/true
Control bold style of secondary zone Possible errors: Wrong style type
/function at-tapi:set/static_bold2/false
/function at-tapi:set/static_bold2/true
Change color of primary zone Possible errors: Wrong style type
/function at-tapi:set/static_color1 {color:""}
Change color of secondary zone Possible errors: Wrong style type
/function at-tapi:set/static_color2 {color:""}
Control italic style of primary zone Possible errors: Wrong style type
/function at-tapi:set/static_italic1/false
/function at-tapi:set/static_italic1/true
Control italic style of secondary zone Possible errors: Wrong style type
/function at-tapi:set/static_italic2/false
/function at-tapi:set/static_italic2/true
Animated style type
Change animation Possible errors: Wrong style type Unknown animation
/function at-tapi:set/animated_animation {name:""}
Control bold style of animation Possible errors: Wrong style type
/function at-tapi:set/animated_bold/false
/function at-tapi:set/animated_bold/true
Control italic style of animation Possible errors: Wrong style type
/function at-tapi:set/animated_italic/false
/function at-tapi:set/animated_italic/true
Control animation direction Possible errors: Wrong style type
/function at-tapi:set/animated_direction/l2r
/function at-tapi:set/animated_direction/r2l
Control animation speed Possible errors: Wrong style type Invalid speed value
/function at-tapi:set/animated_speed {ticks:1}
API Trap functionality
As mentioned before, traps provide a way to get notified based on timer events. The API Trap system consists of several trap types, each having a distinct execution behavior:
reach_full_day
Runs at every full day, e.g. 1d 0h 0m 0s / 8d 0h 0m 0s
reach_full_hour
Runs at every full hour, e.g. 0d 3h 0m 0s / 2d 18h 0m 0s
reach_full_minute
Runs at every full minute, e.g. 0d 0h 40m 0s / 1d 2h 53m 0s
reach_zero
Runs if timer counts down to zero: 0d 0h 0m 0s
timer_continue
Runs if timer resumes, e.g. via player input or API
timer_pause
Runs if timer pauses, e.g. via player input or API
timer_reset
Runs if timer get reset by player input
Traps need to be registered in order to be executed by AT. In practice, the registration process works as follows:
Create a function that should be executed as soon as the trap is triggered
Run the trap creation command to register it to the API (command can be found below)
AT will run your function automatically if the trap type is being executed
Note: Per trap type, AT is limited to 16 functions.
Functions - Trap
Trap modification
Create / register a trap Possible errors: Unknown trap type Function limit reached
/function at-tapi:trap/add {type:"", function:""}
Remove all occurrences of function in a trap type Possible errors: Unknown trap type
/function at-tapi:trap/remove {type:"", function:""}
Viewing trap data
Description: Count & list all functions of a trap type.
Usage: /function at-tapi:trap/list {type:"trap_type"}
trap_content
List
["foo:bar", "test:run with storage baz"]
function_count
Integer
2
Examples
Example 1: Hourly rewarding every player with a cookie
Steps to reproduce:
Create .mcfunction file in any datapack for reward function This example assumes the following file path: data/example1-cookie/function/reward.mcfunction
Insert necessary commands:
give @a minecraft:cookie
tellraw @a "You received a cookie. Thank you for playing!"Test function execution by running
/function example1-cookie:rewardRegister a new trap to conclude the example:
/function at-tapi:trap/add {type:"reach_full_hour", function:"example1-cookie:reward"}
Last updated