Home

Luafy Documentation

Quick Start

Luafy loads scripts with the .lua extension. Luafy requires scripts to be placed at data/<namespace>/lua_scripts. Any .lua script will be loaded.

Command

• /lua : Root

  • lua list : Prints the Identifiers of every loaded script, plus the number of scripts

  • lua execute <script: String> [<context: NbtCompound>] : Executes the script at script. Optionally, use context to supply NBT 'context' data that can be accessed using ContextApi.

Identifier Format

Luafy script identifiers follow the pattern: <datapack namespace>:<path from 'lua_scripts' folder>

Callbacks

_callback_lua_scripts.json should be placed in the lua_scripts directory, next to the scripts. Ensure it is named exactly like this. See section on Callbacks

Luafy APIs

CommandApi

This API allows commands to be executed. The Commmand Source used is determined using the same logic as /function, using the source used to execute /lua as a base.

Function	Purpose	Parameters	Returns	Notes
command.execute	Executes the Minecraft command given using the source used to run this Lua Script.	- command: string	result: number Integer containg the result of this command.	Success is not returned.

StorageApi

This API interfaces with Data Storage; In vanilla Minecraft this can be queried using /data get storage <storage: identifier>. Data Storages hold an NBT value that is stored persistently in the World files. This makes this useful for storing "global" variables that can be accessed anywhere, as well as data serialization.

Function	Purpose	Parameters	Returns	Notes
storage.read	Gets information from a Data Storage (/data storage) and returns the NBT value in Lua. This is the 'explicit' variant, where the type is passed into the function.	- storage: string - address: string - type: string	data: any Data read from storage.	Type is explicitly defined by type. See Explicit Data Types.
storage.read_implicit	Gets information from a Data Storage (/data storage) and returns the NBT value in Lua. This is the 'implicit' variant, where the type is detected by Luafy.	- storage: string - address: string	data: any Data read from storage.	Type is implicitly detected. It is STRONGLY recommended to prefer storage.read() over this. See Internal NBT/Lua Conversions
storage.write	Converts the Lua Value at data to NBT and writes it to the specified Data Storage.	storage: string address: string data: any	nil	Type is implicitly detected.
storage.has	Checks if the Data Storage has a value at the address given.	- storage: string - address: string	result: boolean true if storage at storage has any data at address.
storage.object	Creates a convenience LuaObject to access this data storage.	- storage: string	object: table StorageLuaObject wrapping around this storage.	See LuaObjects.

ServerApi

This API interacts directly with the Server the script is executed on. This API allows you to get information about entities and players on the server, as well as the source that executed the script.

Function	Purpose	Parameters	Returns	Notes
server.get_player_names	Gets each players username.	None	names: table	Returns table with array part containing strings of each online players name.
server.get_source_name	Gets the name of the source.	None	name: string	Name of the source that executed this script. If the server executed it, this is "Server".
server.get_player_name_from_uuid	Convert UUID to username.	uuid: string	Gets UUID from username. Player must be online.
server.get_source_uuid	Convert username to UUID.	None	uuid: string (nil-able)	Gets UUID of the source. Returns nil if source is server.
server.get_online_player_uuids	Gets each players UUID	None	uuids: table	Returns table with array part containing strings of each online players UUID.
server.get_source	Gets the entity that executed this script.	None	entity: table (EntityLuaObject)	See LuaObjects.
server.get_entity_from_uuid	Gets the entity with this uuid.	- uuid: string	entity: table (EntityLuaObject)	See LuaObjects.
server.get_entity	Gets the entity matching this condition.	- selector: string	entity: table (EntityLuaObject)	selector is a string containing an Entity Selector that targets a single entity. This is formatted exactly like in commands, for example "@e[limit=1,type=player,sort=nearest]" gets the nearest player to the source. See LuaObjects.
server.get_entities	Gets the entities mathcing this condition.	- selector: string	entities: table	selector is a string containing an Entity Selector that can target multiple entities. This is formatted exactly like in commands, for example "@e[type=player,sort=nearest]" gets all players sorted by distance to the source. Returns table with array part containing EntityLuaObjects. See LuaObjects.

ContextApi

This API provides access to calling other Lua Scripts with additional context without the cost of converting to NBT and back to Lua, as well as accessing 'context data' and setting output context.

Function	Purpose	Parameters	Returns	Notes
context.get	Gets the context supplied to this script execution.	None	context: table	If the context this table receives was obtained from NBT, please see Internal NBT/Lua Conversions.
context.luacall	Calls the Lua Script supplied, optionally with the context table supplied.	- script: string - context: table	nil
context.set_outctx	Sets the context output by this function, to be returned to the script that called it using context.luacall.	- context: table	nil

LuaObjects

LuaObjects are not actually objects; they're just tables with a fancy hat on. They have a little extra Java code behind them and act as utility objects wrapping around classes in Java code, to help better manage Lua Code in Luafy. A LuaObject that 'extends' another is considered a 'child' and copies all of its parent's functions and can be used as normal. Casting is done via functions. Inheritance is probably more complicated than that, but thats the principle that is used here.

AbstractLuaObject

• Base Java Class for LuaObjects.
• No Functions.

Function	Purpose	Parameters	Returns	Notes
--	--	--	--	--

StorageLuaObject

extends AbstractLuaObject

Function	Purpose	Parameters	Returns	Notes
read	Read data from storage explicitly.	- address: string - type: string	data: any Data read from storage. Type is explicitly defined at type.	See Explicit Data Types.
write	Write data to storage.	- address: string - data: any	nil
has	Check whether data exists.	- address: string	result: boolean true if storage has any data at address.

EntityLuaObject

extends AbstractLuaObject

Function	Purpose	Parameters	Returns	Notes
get_name	Gets the name of the entity.	None	name: string
get_uuid	Gets the UUID of the entity.	None	uuid: string
get_nbt	Gets the NBT of the entity.	None	nbt: table
get_type	Gets the name of the entity type.	None	type: string
test_predicate	Tests a complex predicate condition against the entity.	- predicateId: string	result: boolean	predicateId is an identifier of a predicate file. These are vanilla, and are placed in data/<namespace>/predicates See Predicates - Minecraft Wiki.
is_player	Checks if the entity is a player; i.e. it's Java class is an instanceof PlayerEntity.	None	isPlayer: boolean
is_living	Checks if the entity is a player; i.e. it's Java class is an instanceof LivingEntity.	None	isLiving: boolean
as_living	Casts this to a LivingEntityLuaObject.	None	living: table (LivingEntityLuaObject)
as_player	Casts this to a PlayerEntityLuaObject.	None	player: table (PlayerEntityLuaObject)

LivingEntityLuaObject

extends EntityLuaObject

Function	Purpose	Parameters	Returns	Notes
get_mainhand	Gets the stack in this entities main hand.	None	stack: table (ItemStackLuaObject)
get_offhand	Gets the stack in this entities off hand.	None	stack: table (ItemStackLuaObject)
get_head_stack	Gets the stack on this entities head.	None	stack: table (ItemStackLuaObject)
get_chest_stack	Gets the stack on this entities chest.	None	stack: table (ItemStackLuaObject)
get_legs_stack	Gets the stack on this entities legs.	None	stack: table (ItemStackLuaObject)
get_feet_stack	Gets the stack on this entities feet.	None	stack: table (ItemStackLuaObject)

PlayerEntityLuaObject

extends LivingEntityLuaObject

Function	Purpose	Parameters	Returns	Notes
dump_statistics	Gets a table containing the full list of this players game statisitics. This is converted from a JSON Object.	None	stats: table
get_ender_chest_items	Gets each ItemStack (as an ItemStackLuaObject) in the player's enderchest.	None	stacks: table	Returns table with array part containing ItemStackLuaObjects.

ItemStackLuaObject

extends AbstractLuaObject

Function	Purpose	Parameters	Returns	Notes
get_id	Gets the Identifier of the item this stack is of.	None	id: string
get_count	Gets the size of this stack.	None	count: number
get_nbt	Gets the NBT of this stack as a table.	None	nbt: table
set_nbt	Sets the NBT of this stack.	nbt: table	nil	See NBT / Lua Conversions.

Script Callbacks

Callback Scripts are Luafy's way of calling scripts on certain game events. These are defined in lua_scripts/_callback_lua_scripts.json in JSON format.

Callbacks File

• Root:
  • advancements: List of Identifier Script Callbacks - Accepts Wildcard ("*") identifiers to reference any advancement ; Accepts script on player making advancement with identifier specified, using this player as source with elevated permission level
  • load: Script Callback ; Executes scripts on datapack load
  • tick: Script Callback ; Executes scripts every tick

Script Callback

• Root:
  • scripts: List of Script ID Strings

Identifier Script Callback

• Root:
  • id: Identifier
  • scripts: List of Script ID Strings

Internals

This section aims to simply provide information about certain aspects of Luafy's design and structure; It may be useful, it may not be.

Concepts to Java Location

These may be helpful for pinpointing bugs; they are not accurate to the structure in this repository:

Luafy Concept	Java Package (if applicable)	Java Class (if applicable)
Lua Script Resource		dev.diamond.luafy.resource.LuaScriptResourceLoader
Callbacks File Resource		dev.diamond.luafy.resource.CallbackScriptResourceLoader
/lua command		dev.diamond.luafy.command.LuaCommand
Lua Script		dev.diamond.luafy.lua.LuaScript
Lua Type Converter		dev.diamond.luafy.lua.LuaTypeConversions
Luafy APIs	dev.diamond.luafy.lua.api
Luafy LuaObjects	dev.diamond.luafy.lua.object
Luafy Lua Manager		dev.diamond.luafy.lua.LuafyLua

Mod Dependencies and Versions

as of Luafy 0.3.0

Library	Author	Version
Minecraft	Mojang	>= 1.20.4
Yarn Mappings	FabricMC	1.20.4+build.3
Fabric Loader	FabricMC	0.15.10
Fabric API	FabricMC	0.97.0+1.20.4
Figura LuaJ	LuaJ - Maintained by FiguraMC; Thank You!	3.0.8

NBT / Lua Conversions

For most of the functions within Luafy to operate, various implicit conversions between Lua and NBT must be completed. In some cases, an explicit conversion can be done instead. This table shows implicit conversions between Lua and NBT including any caveats in the conversion.

Type	Converts To	Notes
Lua Number	NBT Double
Lua String	NBT String
Lua Table (Map)	NBT Compound
Lua Table (Array)	NBT List	Lua Tables are indexed starting at one, whereas NBT Lists are indexed starting at zero. The index of an object in Lua is decremented by 1 when converted to NBT.
Lua Nil		Conversion Fails
Lua Boolean	NBT Byte	1b if true, 0b if false
--	--	--
NBT Byte	Lua Number	NBT Stores Booleans as an NBT Bytes, these will still be converted to Lua Numbers.
NBT Short	Lua Number
NBT Integer	Lua Number
NBT Long	Lua Number
NBT Float	Lua Number
NBT Double	Lua Number
NBT Compound	Lua Table (Map)
NBT List	Lua Table (Array)	Lua Tables are indexed starting at one, whereas NBT Lists are indexed starting at zero. The index of an object in NBT is incremented by 1 when converted to Lua.
NBT Byte Array	LuaTable (Array)	Lua Tables are indexed starting at one, whereas NBT Lists are indexed starting at zero. The index of an object in NBT is incremented by 1 when converted to Lua.
NBT Integer Array	LuaTable (Array)	Lua Tables are indexed starting at one, whereas NBT Lists are indexed starting at zero. The index of an object in NBT is incremented by 1 when converted to Lua.
NBT Long Array	LuaTable (Array)	Lua Tables are indexed starting at one, whereas NBT Lists are indexed starting at zero. The index of an object in NBT is incremented by 1 when converted to Lua.

Explicit Data Types

In some cases, an Explicit Conversion can take place instead of an implicit one. This ensures you get the type you want, and if the conversion is bad an error is thrown.

Parameter	Lua Type	Applicable NBT Type(s)	Additional Note
"STR"	String	String
"NUM"	Number	Byte, Short, Integer, Long, Float, Double
"BOOL"	Boolean	Byte
"OBJ"	Table	Compound	Tables within tables are also deserialized.
"LIST"	Table	List, Byte Array, Integer Array, Long Array	Table with Number indexes.