Libraries#
🚧 In Construction 🚧
Library documentation is heavily in construction. Expect hefty changes as we figure out what works best! Feel free to leave us feedback at our appropriate channels.
Checkout our list of standard libraries. Most of these libraries are optional, but some are required for compatibility reasons. All libraries in Smithed are MIT licensed and are free to be used outside the Smithed ecosystem.
General guide on Smithed Libraries
Smithed libraries will vary in shape and size but they do stick with the same format of invoking them. Most libraries contain a set of function tags which invoke specific behavior, we call these APIs (borrowed from the computing world). They essentially act as an interface into our library and most of them expect a bit of data to work on!
We pass data to our library functions primarily through two formats:
scoreboard values set on entities or fakeplayers
raw nbt stored directly in storage
Example
# Theoretical `smithed.library` API
scoreboard players set @s smithed.library 20
function #smithed.library:api
# or
data modify storage smithed.library:input message set value "my cool message"
function #smithed.library:api
Note
We use function tags instead of normal functions to interface w/ our libraries for two reasons:
Function tags ensure that a certain API is called only once
If there are multiple versions of the same library in a world, it'll always call the newest versioned function!
This is the basis of versioning (and why we use Lantern Load)!
Function tags also float the library functions to the top of the in-game autocomplete which makes it much easier to find and test!
Library Inputs
Each library may have a varying number of library functions and even more number of inputs. We use a set of tables at the top of each library's documentation to help us track what inputs mean what. Note, not all libraries have a function, some just implement behavior, such as the Prevent Aggression library!
Here's an example of one such table (from the Damage library):
#smithed.damage:entity/apply
Input Name |
Input Type |
Input Source |
Input Objective/Path |
|---|---|---|---|
'Amount of damage' |
score |
@s |
smithed.damage |
This table helps us track what data we can pass to the #smithed.damage:entity/apply function. Here, we see we need to pass in a score which presents the amount of damage on the entity @s and the objective smithed.damage.
scoreboard players set @s smithed.damage 10
function #smithed.damage:entity/apply
#smithed.actionbar:message
Input Name |
Input Type |
Input Source |
Input Objective/Path |
|---|---|---|---|
'Raw Message' |
storage |
message.raw |
smithed.actionbar:input |
'Priority Level' |
storage |
message.priority |
smithed.actionbar:input |
This table showcases how we describe storage-based data as here we have two fields we can pass in one data command!
data modify storage smithed.actionbar:input message set value {raw: "my actionbar", priority: "conditional"}
function #smithed.actionbar:message
A brief note on our mcfunction samples
Within these docs, there are several mcfunction code samples to look through. For sake of documentation, we use an expanded syntax set of mcfunction to help clarify complex structures in a simpler manner.
Normal Commands
# main
execute as @a if score @s my_obj matches 10 run summon ~ ~ ~ zombie {CustomName:'{"text": "Spooky Zombie"}', Tags: ["new"]}
execute as @e[type=zombie, tag=new] run function namespace:nested_function
# nested_function
scoreboard players set @s my_obj 10
tag @s remove new
These verbose commands represent two functions and have commands with several execute subcommands within them. While these commands are vanilla, they don't make particularly nice documentation as they are difficult to read and parse, even with syntax highlighting. Here's how the docs will represent these commands.
What you'll see here
execute as @a
if score @s my_obj matches 10
run summon ~ ~ ~ zombie {
CustomName: '{"text": "Spooky Zombie"}',
Tags: ["new"]
}
execute as @e[type=zombie, tag=new] run function namespace:nested_function:
scoreboard players set @s my_obj 10
tag @s remove new
Here, we break up long commands on multiple lines as seen in the first, long execute command. The second command showcases how we embed a function within the same file (the syntax might be recognizable to python users). We'll try to stick to simple, understandable, transformations of the vanilla commands to avoid large mismatches with how most people write commands!
