Skip to content

APIs

Jump to bottom
kyfex_uwu edited this page Feb 27, 2024 · 9 revisions

these docs are constantly under construction! if you have something you feel should be added, dont hesitate to open a feature request on github :3 (just the bug tracker)

Lua Changes

  • require, load, loadfile, and dofile have all been disabled
  • A new function loadLib has been added: it takes 1 parameter (path name relative to the m3we scripts folder, ex: "testScript.lua") and returns the object that the lua file returns
  • print prints to the Minecraft chat
  • consoleprint prints to the Minecraft console
  • A new function explore has been added: it takes 1 parameter (any object), and displays all the properties of that object in chat
  • A new function loadclass has been added: it takes 1 parameter (the class name) and returns that class. Probably not useful unless you know what you're doing ;3

Datastore API

The Datastore API is super simple: it's an empty table that can be read from or written to by any script. It is global and per-world, and there is a limitation: it can only contain strings, numbers, booleans, and other tables, and the keys can only be strings or numbers. (Also any references to the table will be lost when putting a table into the Datastore - just be careful of that)

If you would like to edit the Datastore table outside of Minecraft, look inside your save (.minecraft/saves/your save/m3we_datastore.dat). it'll be an nbt file :3

How to use:

Just use it like a regular Lua table lol

Out of courtesy to other m3we creators, consider creating a table inside the Datastore table to manage all your resources in, to avoid conflicts. A good name for this table is your Minecraft username :3

EX:

Datastore.kyfex_uwu = {}
Datastore.kyfex_uwu.globalValue = "owo"
Datastore.kyfex_uwu[7] = true

Property API

The Property API is a simple way to manage blockstates. It only has 2 functions: Properties.get and Properties.set and they each do what you would expect.

How to use:

  • Properties.get(state, nameOfProperty)
    EX: Properties.get(state, "facing")

Returns the state's value of the property specified or nil, if no property is found.

  • Properties.set(world, pos, nameOfProperty, value)
    EX: Properties.set(world, pos, "facing", "north")

Sets the property specified on a block to the value specified, and returns true if it succeeded. Pass in a table: {the current state of this block, the world this block is in, and the position of this block}, the name of the property you want to change, and the value you want to change it to.

Create API

The Create API is your go-to whenever you need to create a new Minecraft object. Each of these methods creates and returns a different object with the specified properties.

How to use:

  • Create.itemStack({properties})
    EX: Create.itemStack({ item="diamond", count=10 })

Creates a new ItemStack with the item and count specified. Count is optional, and defaults to 1. Additionally, if you pass in "empty" instead of the properties table, you get air.

  • Create.blockPos(x, y, z)
    EX: Create.blockPos(100,50,70)

Creates a block position (useful if you want to add a block to the world.)

  • Create.blockState(blockStateData)
    EX: Create.blockState({block="oak_log", properties={ axis="x" }})

Creates a block state (useful if you want to add a block to the world.) (Passing in an Enum value here should work as well, but I haven't tested it)

  • Create.inventory(size)
    EX: Create.inventory(9)

Creates an inventory with the specified size.

Create.entity

  • Create.entity.item(world, x, y, z, stack, [vx, vy, vz])
    EX: Create.entity.item(world, 10, 70, 10, Create.itemStack({...}))

Spawns an item in the world with the specified x, y, and z (and optionally with the specified velocity).

Registry API

The Registry API registers things that need to be used on both the client and the server.

How to use:

  • Registry.registerGui(guiName, guiBehavior)
    EX: Registry.registerGui("test-gui",{properties})

Registers a GUI to be used later. The guiBehavior parameter is a table, with the following properties:

  • "register" - a table with the following properties:
    • "slots" - how many slots this custom GUI has
    • "hasPlayerInventory" - whether or not this GUI renders the player's inventory. If you use Gui.playerInventory(x,y) then this should be set to true. A boolean
  • "onClient" - a function that takes 1 parameter: the GUI object. This function is in charge of rendering the GUI on the client, and runs every frame. It should be written as follows:
onClient = function(gui, mouseX, mouseY)
  (code goes here)

end
  • "onServer" - a function that takes 1 parameter: the GUI object. This function is in charge of handling things on the server side, and only runs whenever the GUI gets updated. (when an item is moved or a button is pressed) It should be written as follows:
onServer = function(gui)
  (code goes here)

end
  • "onClose" - a function that takes 2 parameters: this GUI object and the player who is closing the inventory. This function runs when the GUI is closed. It should be written as follows:
onClose = function(gui, player)
  (code goes here)

end

If onClient, onServer, or onClose are not defined, nothing bad will happen. Just make sure there is a register value with a slots property, even if the value of slots is 0. (actually i have no idea what im saying brb gotta check what happens here)

GUI API

The GUI API is the API that manages everything about GUIs: client-side, server-side, rendering, the whole thing.

How to use

  • Gui.openGui(player, guiName)
    EX: Gui.openGui(player, "test-gui")

Opens the specified GUI for the specified player by the specified block.

  • Gui.setBounds(width, height)
    EX: Gui.setBounds(176, 216)

Sets the width and height of this GUI.

  • Gui.rect(x, y, width, height)
    EX: Gui.rect(0, 0, 176, 126)

Draws a GUI rectangle with the specified properties.

  • Gui.slot(x, y, slotIndex)
    EX: Gui.slot(20, 20, 0)

Draws the GUI slot with the specified index at the specified position. Starts at 0 (tell me if i should change this)

  • Gui.drawImg(textureName, texWidth, texHeight, destX, destY, [srcX, srcY, srcW, srcH]) or
    Gui.drawImg(textureName, texWidth, texHeight, destX, destY, destW, destH, [srcX, srcY, srcW, srcH])
    EX:
    • Gui.drawImg("minecraft:block/dirt", 16, 16, 2, 2) draws dirt at the top left of the GUI
    • Gui.drawImg("minecraft:entity/blaze", 64, 32, 100, 100, 24, 24, 8, 8, 8, 8) draws a blaze face near the bottom left of the GUI

Draws from a texture at the specified position.

  • Gui.text(textToDraw, x, y)
    EX: Gui.text("Test GUI", 8, 6)

Draws the specified text at the specified position.

  • Gui.playerInventory(x, y) EX: Gui.playerInventory(0, 118)

Draws the player's inventory at the specified position.

  • Gui.getSlot(slotIndex, slotType)
    EX: Gui.getSlot(0, "inventory") or Gui.getSlot(5, "player")

Gets the specified slot from either the GUI slots or the player slots.

  • Gui.doInWorld(toDo)
    EX: Gui.doInWorld(function(world, pos) ... end)

Executes the function in the specified world at the specified position. This is generally the world and position of the block that called this function.

Enums API

The Enums API is simply a table of useful enums. For example, if you want to check if the player clicked a block with their offhand, you could say hand == Enums.OFF_HAND.

Entries

  • ActionResult
    • SUCCESS
    • CONSUME
    • CONSUME_PARTIAL
    • PASS
    • FAIL
  • Direction
    • DOWN
    • UP
    • NORTH
    • SOUTH
    • EAST
    • WEST
  • Hand
    • MAIN_HAND
    • OFF_HAND
  • RedstonePower
    • STRONG
    • WEAK

Redstone API

The Redstone API handles a bunch of things related to redstone.

How to use

  • Redstone.getPower(world, blockPos, powerType)
    EX: Redstone.getPower(world, blockPos, Enums.RedstonePower.STRONG)

Gets the power level at this location. Note: if the strong power is greater than the weak power, this function will return the strong power always instead of the weak.

  • Redstone.getEmittedPower(world, blockPos, direction)
    EX: Redstone.getEmittedPower(world, blockPos, Enums.Direction.UP)

Gets the power level emitted from this block in this direction.

Signals API

The Signals API lets you send messages from the client to the server and back.

How to use

  • Signals.registerEvent(eventName, runOnClient, runOnServer)
    EX: Signals.registerEvent("kyfex_uwu.ping", function(data) ... end, function(data) ... end)

Registers these two functions to be run whenever a message is sent with the name eventName. For example, if you call this Signals.send("ping", 4) on the client, the server will run runOnServer with data=4. Consider prefixing your event with your Minecraft username, as to avoid signal conflicts.

  • Signals.send(name, data)
    EX: Signals.send("kyfex_uwu.ping", 4)

Sends a signal to the other connection: if this is called on the client, it sends a signal to the server, and if called on the server, it sends a signal to the client.

Misc API

This API is for all the functions that don't fit anywhere else.

  • Misc.runCommand(commandToRun, world)
    EX: Misc.runCommand("give @r diamond 64", world)

Runs the specified command in the specified world. If this is run by a block, world is optional and the command will be run at the position and world of the block.

Clone this wiki locally