api

API

The Reef library provides API functions users can run to perform multiple actions on a screen.

If you want to control screens and remotes by intended means, use the Remote item. Most of the screen and remote API functions are already ran by using the Remote item UI. This article is meant for people who want to purposely run then manually.

Note

All function identifiers here will be a child of reef:api/ unless specified explicitly.
Example: ~/screen/summon points to reef:api/screen/summon

Warning

API functions that are not listed here should not be ran manually.
Example: ~/screen/set_page/first_page is not meant to be ran by itself.

---

~/register/slideshow

Register a slideshow definition to the Reef registry.

Inputs

Macro argument identifier: The identifier to register this slideshow as.
Macro argument storage_path: The location of the slideshow data written as a storage identifier and NBT path.

Outputs

None
Errors: If there is no slideshow data present in the given storage path.

Example

Register a slideshow named ns:my_awesome_presentation

function reef:api/register/slideshow {identifier: "ns:my_awesome_presentation", storage_path: "ns:my_storage path.to.my_awesome_presentation"}

---

~/register/page

Register a page definition to the Reef registry.

Inputs

Macro argument identifier: The identifier to register this page as.
Macro argument storage_path: The location of the page data written as a storage identifier and NBT path.

Outputs

None
Errors: If there is no page data present in the given storage path.

Example

Register a page named ns:credits

function reef:api/register/page {identifier: "ns:credits", storage_path: "ns:my_storage path.to.credits"}

---

~/register/transition

Register a transition definition to the Reef registry.

Inputs

Macro argument identifier: The identifier to register this transition as.
Macro argument storage_path: The location of the transition data written as a storage identifier and NBT path.

Outputs

None
Errors: If there is no transition data present in the given storage path.

Example

Register a transition named ns:color_wipe

function reef:api/register/transition {identifier: "ns:color_wipe", storage_path: "ns:my_storage path.to.color_wipe"}

---

~/register/mini

Compile a Reef Mini definition back to a normal Reef slideshow definition then register it to the Reef registry.

Inputs

Macro argument identifier: The identifier to compile and register this mini definition as.
Macro argument storage_path: The location of the mini definition data written as a storage identifier and NBT path.

Outputs

Slideshow registry <namespace>:<identifier>: Identifier of the Reef Mini slideshow.
Page registry <namespace>:<identifier>/<page_index>: Compiled pages from the Reef Mini definition.
Errors: If there is no mini definition data present in the given storage path.

Compile and register a Reef Mini definition named ns:my_simple_slideshow

function reef:api/register/mini {identifier: "ns:my_simple_slideshow", storage_path: "ns:my_storage path.to.my_simple_slideshow"}

---

~/screen/summon

Summon a screen.

Inputs

Positional execution context: Determines the position and rotation of the screen.

Outputs

Entity item_display tagged reef.screen: The main screen entity.
Entity item_display tagged reef.element.transition: The transition layer of the screen. This is where transitions will play.

Example

Summoning a screen at (10, 10, 10) rotated with a slight pitch.

execute positioned 10.0 10.0 10.0 rotated 0 5 run function reef:api/screen/summon

---

~/screen/set_page

Set the current page of a screen.

Inputs

Entity execution context as <screen_entity>: The screen to select.
Macro argument page: The page index to select.

Outputs

None
Errors: If the screen hasn't loaded a slideshow.
Errors: If the page exceeds the bounds of the slideshow page count.
Warns: If the screen isn't done transitioning to the next page.

Example

Setting the page of the nearest screen to the first page.

execute as @n[type=item_display, tag=reef.screen] run function reef:api/screen/set_page {page: 0}

---

~/screen/next

Advance the current page sequence or move to the next page of a screen.

Inputs

Entity execution context as <screen_entity>: The screen to select.

Outputs

None
Errors: If the screen hasn't loaded a slideshow.
Errors: If the page exceeds the bounds of the slideshow page count.
Warns: If the screen isn't done transitioning to the next page.

Example

Advancing the slideshow of the nearest screen.

execute as @n[type=item_display, tag=reef.screen] run function reef:api/screen/next

---

~/screen/prev

Go back to the previous page of a screen.

Inputs

Entity execution context as <screen_entity>: The screen to select.

Outputs

None
Errors: If the screen hasn't loaded a slideshow.
Errors: If the page exceeds the bounds of the slideshow page count.
Warns: If the screen isn't done transitioning to the next page.

Example

Going back a page of the current slideshow of the nearest screen.

execute as @n[type=item_display, tag=reef.screen] run function reef:api/screen/prev

---

~/remote/unlinked_remote/link

Open the linking dialog of the held unlinked remote in weapon.mainhand.

Inputs

Item slot weapon.mainhand: The remote to link.

Outputs

Modified item slot weapon.mainhand: A linked remote.
Errors: If the player does not have the reef.permissions.use_remote permission (See Permission System).
Errors: If the player is not holding a reef:remote Reef item with the reef:link Reef component linked field set to false.

Example

Sets the mainhand slot of the player to an Unlinked Remote and opens the linking dialog.

loot replace entity @s weapon.mainhand loot reef:remote
function reef:api/remote/unlined_remote/link

---

~/remote/linked_remote/open_slideshow_settings

Open the slideshow settings dialog (See Using the Remote).

Inputs

Entity execution context as <player>: The target player for opening the dialog

Outputs

None

---

~/remote/linked_remote/open_slideshow_settings/open_load_slideshow_dialog

Open the load slideshow sub-dialog (See Using the Remote).

Inputs

Entity execution context as <player>: The target player for opening the dialog

Outputs

None

---

~/remote/linked_remote/open_slideshow_settings/open_change_page_dialog

Open the change page sub-dialog (See Using the Remote).

Inputs

Entity execution context as <player>: The target player for opening the dialog

Outputs

None

---

~/remote/linked_remote/load_slideshow

Load a slideshow to the remote's linked screen.

Inputs

Item slot weapon.mainhand: The linked remote.
Macro argument id: Identifier of the slideshow to load.

Outputs

None
Errors: If the player is not holding a reef:remote Reef item with the reef:link Reef component linked field set to true.
Errors: If the linked remote's linked screen doesn't exist.

---

~/remote/linked_remote/change_page

Run the API function ~/screen/set_page as the screen the remote is linked to.

Inputs

Item slot weapon.mainhand: The linked remote.
Macro argument page: Page index to switch to.

Outputs

None
Errors: If the player is not holding a reef:remote Reef item with the reef:link Reef component linked field set to true.
Errors: If the linked remote's linked screen doesn't exist.

---

~/remote/linked_remote/next

Run the API function ~/screen/next as the screen the remote is linked to.

Inputs

Item slot weapon.mainhand: The linked remote.

Outputs

None
Errors: If the player is not holding a reef:remote Reef item with the reef:link Reef component linked field set to true.
Errors: If the linked remote's linked screen doesn't exist.

---

~/remote/linked_remote/prev

Run the API function ~/screen/prev as the screen the remote is linked to.

Inputs

Item slot weapon.mainhand: The linked remote.

Outputs

None
Errors: If the player is not holding a reef:remote Reef item with the reef:link Reef component linked field set to true.
Errors: If the linked remote's linked screen doesn't exist.

---

~/remote/linked_remote/clear_screen

Kill all the elements displayed on the remote's linked screen except for the transition element.

Inputs

Item slot weapon.mainhand: The linked remote.

Outputs

None
Errors: If the player is not holding a reef:remote Reef item with the reef:link Reef component linked field set to true.
Errors: If the linked remote's linked screen doesn't exist.

---

~/remote/linked_remote/remove_screen

Unlink the remote and kill the remote's linked screen and all the elements displayed on the screen.

Inputs

Item slot weapon.mainhand: The linked remote.

Outputs

Modified item slot weapon.mainhand: An unlinked remote.
Errors: If the player is not holding a reef:remote Reef item with the reef:link Reef component linked field set to true.
Errors: If the linked remote's linked screen doesn't exist.

---

~/remote/linked_remote/unlink_remote

Unlink the remote from the linked screen.

Inputs

Item slot weapon.mainhand: The linked remote.

Outputs

Modified item slot weapon.mainhand: An unlinked remote.
Errors: If the player is not holding a reef:remote Reef item with the reef:link Reef component linked field set to true.
Errors: If the linked remote's linked screen doesn't exist.

---