# 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](https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol), 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:

Path	Type	Description & sample 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`

Output	Type	Sample value
actionbar	String	Timer: 2h 43m 12s

### Current time **Description:** Reads individual timer units including ticks. **Usage:** `/function at-tapi:get/current_time`

Output	Type	Sample value
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:

Output	Type	Sample value
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

### Local version **Description:** Reads numerical patch number & version string. **Usage:** `/function at-tapi:get/local_version`

Output	Type	Sample value
numerical	Integer	103010
verbose	String	1.3.1

### 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`

Output	Type	Sample value
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`

Output	Type	Sample value
numerical	Integer	1
verbose	String	up

## Functions - Set ### Timer controls

Description & possible errors	Usage
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

Description & possible errors	Usage
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

Description & possible errors	Usage
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

Description & possible errors	Usage
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:

Trap type	Description
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: 1. Create a function that should be executed as soon as the trap is triggered 2. Run the trap creation command to register it to the API (command can be found below) 3. 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

Description & possible errors	Usage
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"}`

Output	Type	Sample value
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:** 1. Create .mcfunction file in any datapack for reward function\ This example assumes the following file path: *data/example1-cookie/function/reward.mcfunction* 2. Insert necessary commands: ``` give @a minecraft:cookie tellraw @a "You received a cookie. Thank you for playing!" ``` 3. Test function execution by running `/function example1-cookie:reward` 4. Register a new trap to conclude the example: `/function at-tapi:trap/add {type:"reach_full_hour", function:"example1-cookie:reward"}`