API Bridge

Our goal is to make every method in the Spigot API available through our scripting language, allowing you to leverage the full power of Spigot while scripting. You can access the Spigot API documentation (1.21.1) for comprehensive details on the available classes and methods, including main classes such as Player, Location, Block, ItemStack, Entity and World.

Useful links

Familiarizing yourself with these classes will help you effectively utilize the Spigot API to create dynamic and engaging experiences in your scripts.

Some links for the main classes are:

Player (Spigot-API 1.21.1-R0.1-SNAPSHOT API)

Location (Spigot-API 1.21.1-R0.1-SNAPSHOT API)

Block (Spigot-API 1.21.1-R0.1-SNAPSHOT API)

Bridging Spigot API Methods

We’ve designed our scripting language to provide a way to access Spigot API methods easily. Each method from the Spigot API is translated into a format that fits the syntax of our language, making it intuitive for developers to use.

For example, consider the Player class, which contains methods like getDisplayName() and setDisplayName().

In our scripting language, you can access these methods as follows:

To retrieve a player's display name, you can use:

player.get_display_name

or simply:

player.display_name

To set a player's display name, you can use:

player.set_display_name("Hello World")

or simply:

player.display_name = "Hello World"

For methods that start with "is" or "has" in the Spigot API, such as isSneaking or hasPermission, the prefix is dropped, and a ? is added at the end to indicate it returns a Boolean value. For example:

isSneaking() in Spigot becomes:
```
player.sneaking?
```
hasPermission("some.permission") becomes:
```
player.permission?("some.permission")
```

Code Examples

Sending a Message to a Player

This example demonstrates how to send a personalized message to a player when they join the game.

// Send a welcome message to the player
player.send_message("&aWelcome to the server, &e{{player.name}}!")

Explanation:

Sending a Message: The send_message method is used to display a message to the player. The text inside the parentheses is the content of the message.
Formatted Message: In this message, we use color codes for formatting:
- &a sets the text color to light green.
- &e sets the text color to yellow.
Personalization: The part {{player.name}} dynamically includes the player’s name in the message, making it more personal. When the message is sent, it will replace {{player.name}} with the actual name of the player, so they see something like "Welcome to the server, Steve!" when they join.

Giving an Item to a Player

// Give the player a stone
player.inventory.add_item(:STONE)

Explanation

Adding an Item: The add_item method is called on the player's inventory to add a specific item.
Item Specification: In this case, we are adding :STONE, which represents a stone block in the game. The colon (:) indicates that it is an enumeration (enum) value for item types. You can check all the materials available at Material Spigot API.
Result: When this line of code executes, a stone item is added to the player's inventory, allowing them to use it in the game.

Teleporting a Player and Placing a Block

In this example, we’ll show how to teleport a player 10 blocks upwards and then place a block at the new location.

// Get the player's current location
current_location = player.location

// Calculate the new location by adding 10 to the Y coordinate
current_location.y += 10  // Move 10 blocks up

// Teleport the player to the new location
player.teleport(current_location)

current_location.y -= 1 // Updating the location just below the old one

// Getting the block of the entity
current_location.block.type = :STONE

Explanation

// Get the player's current location
current_location = player.location

This line retrieves the player's current position in the game world. The player.location property gives us an object that contains the player's coordinates (X, Y, Z) along with the world they are in. We store this information in a variable called current_location for later use.

// Calculate the new location by adding 10 to the Y coordinate
current_location.y += 10  // Move 10 blocks up

Next, we increase the Y coordinate of current_location by 10. The Y coordinate represents the vertical position in the game world. By adding 10, we are moving the player 10 blocks higher into the air. The line current_location.y += 10 is shorthand for saying "take the current Y coordinate and add 10 to it."

// Teleport the player to the new location
player.teleport(current_location)

This line of code moves the player to the newly calculated location. The player.teleport(current_location) method is called, which takes the new coordinates and updates the player's position in the game world to that point. After this line, the player will be standing 10 blocks above where they were initially.

current_location.y -= 1 // Updating the location just below the old one

Here, we adjust the Y coordinate of new_location by subtracting 1. This changes the position to be directly below the new teleport location (which is now 10 blocks up). This step is necessary because we want to place a block just underneath where the player is now standing, not at their new height.

// Getting the block of the entity
current_location.block.type = :STONE

This line is meant to set the type of block at the updated current_location. By accessing current_location.block, we are referring to the block that is currently at the coordinates specified by current_location. Then, we set its type to :STONE, which means we want to place a stone block at that location. You can check all the block types available on Material Spigot API.

Conclusion

To truly harness the full potential of our scripting language, it's essential to familiarize yourself with the Spigot API. This knowledge will empower you to perform a wide range of actions within the game. However, many functionalities require you to access other components first. For instance, if you wish to add an item to a player's inventory, you must first access that inventory. Similarly, to set a material for a block, you'll need to retrieve the block's reference, often starting from its location.

By understanding how to navigate the Spigot API, you’ll be able to create more complex and interactive scripts, enhancing your experience and enabling you to customize your gameplay to suit your needs.

PreviousSyntax and Semantics NextCommon classes

Last updated 1 day ago