143 lines
7.3 KiB
Java
143 lines
7.3 KiB
Java
package com.aranroig.docs;
|
|
|
|
import java.util.List;
|
|
|
|
/**
|
|
* The in-game reference for every Lua global this mod exposes to user scripts.
|
|
*
|
|
* <p>This is a hand-written catalog describing the functions registered by the
|
|
* wrappers in {@code com.aranroig.wrapper} (currently {@code world} from
|
|
* {@link com.aranroig.wrapper.WorldApi} and the {@code print} helper). The
|
|
* client editor reads it to render the browsable documentation panel, so it is
|
|
* the single source of truth shown to players.</p>
|
|
*
|
|
* <p>Keep it in sync with the wrapper implementations and {@code docs/lua-api.md}.</p>
|
|
*/
|
|
public final class LuaApiDocs {
|
|
|
|
private LuaApiDocs() {
|
|
}
|
|
|
|
// ── world.* — block access ────────────────────────────────────────────
|
|
|
|
private static final FunctionDoc SET_BLOCK = new FunctionDoc(
|
|
"world.set_block",
|
|
"world.set_block(x, y, z, block)",
|
|
"Places a block and updates neighbours and clients, like /setblock does.",
|
|
List.of(
|
|
new ParamDoc("x", "number", false, "Absolute world x coordinate (F3 to read your own)."),
|
|
new ParamDoc("y", "number", false, "Absolute world y coordinate."),
|
|
new ParamDoc("z", "number", false, "Absolute world z coordinate."),
|
|
new ParamDoc("block", "string", false,
|
|
"Block id, with or without the minecraft: namespace, optionally with block states.")
|
|
),
|
|
"true on success, or false followed by a reason string.",
|
|
List.of(
|
|
"Coordinates are absolute, never relative to the player.",
|
|
"A block that cannot survive where it is put (a torch without a wall, a flower without ground) drops itself again and the call reports failure.",
|
|
"Replacing a block that holds items, such as a chest, drops its contents."
|
|
),
|
|
List.of(
|
|
new ExampleDoc("Namespace is optional; states are allowed",
|
|
"world.set_block(10, 64, -3, \"minecraft:stone\")\n"
|
|
+ "world.set_block(10, 65, -3, \"gold_block\")\n"
|
|
+ "world.set_block(10, 66, -3, \"minecraft:oak_stairs[facing=north]\")"),
|
|
new ExampleDoc("Check whether it worked",
|
|
"local ok, reason = world.set_block(10, 64, -3, \"minecraft:stone\")\n"
|
|
+ "if not ok then\n"
|
|
+ " print(\"could not place the block: \" .. reason)\n"
|
|
+ "end")
|
|
)
|
|
);
|
|
|
|
private static final FunctionDoc REMOVE_BLOCK = new FunctionDoc(
|
|
"world.remove_block",
|
|
"world.remove_block(x, y, z [, drops])",
|
|
"Removes the block at the given position.",
|
|
List.of(
|
|
new ParamDoc("x", "number", false, "Absolute world x coordinate."),
|
|
new ParamDoc("y", "number", false, "Absolute world y coordinate."),
|
|
new ParamDoc("z", "number", false, "Absolute world z coordinate."),
|
|
new ParamDoc("drops", "boolean", true,
|
|
"Pass true to break the block the way a player would (items, sound, particles).")
|
|
),
|
|
"true on success, or false followed by a reason string.",
|
|
List.of(
|
|
"Without drops the block just vanishes, silently and without items.",
|
|
"Fails with \"there is nothing to remove\" if the target is already air."
|
|
),
|
|
List.of(
|
|
new ExampleDoc("Vanish versus break",
|
|
"world.remove_block(10, 64, -3) -- vanish\n"
|
|
+ "world.remove_block(10, 65, -3, true) -- break it, dropping items")
|
|
)
|
|
);
|
|
|
|
private static final FunctionDoc GET_BLOCK = new FunctionDoc(
|
|
"world.get_block",
|
|
"world.get_block(x, y, z)",
|
|
"Returns the block id at that position, including its block states.",
|
|
List.of(
|
|
new ParamDoc("x", "number", false, "Absolute world x coordinate."),
|
|
new ParamDoc("y", "number", false, "Absolute world y coordinate."),
|
|
new ParamDoc("z", "number", false, "Absolute world z coordinate.")
|
|
),
|
|
"The block id string (ready to hand to set_block), or nil followed by a reason string.",
|
|
List.of(
|
|
"Air is the string \"minecraft:air\", and every string is truthy in Lua — compare against the id rather than testing the value.",
|
|
"The result carries block states, e.g. minecraft:grass_block[snowy=false]."
|
|
),
|
|
List.of(
|
|
new ExampleDoc("Compare against the id, not the value",
|
|
"local block = world.get_block(10, 64, -3)\n"
|
|
+ "if block ~= \"minecraft:air\" then\n"
|
|
+ " print(\"something is there: \" .. block)\n"
|
|
+ "end"),
|
|
new ExampleDoc("Copy one place to another",
|
|
"local block = world.get_block(10, 64, -3)\n"
|
|
+ "if block then\n"
|
|
+ " world.set_block(20, 70, 5, block)\n"
|
|
+ "end")
|
|
)
|
|
);
|
|
|
|
// ── print — chat output ───────────────────────────────────────────────
|
|
|
|
private static final FunctionDoc PRINT = new FunctionDoc(
|
|
"print",
|
|
"print(...)",
|
|
"Writes to the chat of the player who ran the script, tab-separated.",
|
|
List.of(),
|
|
"nothing",
|
|
List.of(
|
|
"Whole numbers go through the Lua wrapper and are printed as 12.0; concatenate them into a string to drop the decimal.",
|
|
"Runs on the server, so output appears in the running player's chat."
|
|
),
|
|
List.of(
|
|
new ExampleDoc("Print to chat",
|
|
"print(\"blocks placed:\", 12)"),
|
|
new ExampleDoc("Drop the trailing .0",
|
|
"print(\"blocks placed: \" .. 12) -- -> blocks placed: 12")
|
|
)
|
|
);
|
|
|
|
// ── The full table ────────────────────────────────────────────────────
|
|
|
|
private static final List<Topic> TOPICS = List.of(
|
|
new Topic("world", "Read and write blocks in the running player's dimension.",
|
|
List.of(SET_BLOCK, REMOVE_BLOCK, GET_BLOCK)),
|
|
new Topic("print", "Send text to the chat of the player running the script.",
|
|
List.of(PRINT))
|
|
);
|
|
|
|
/** All documented topics, in display order. */
|
|
public static List<Topic> topics() {
|
|
return TOPICS;
|
|
}
|
|
|
|
/** Flattened list of every documented function, across all topics. */
|
|
public static List<FunctionDoc> functions() {
|
|
return TOPICS.stream().flatMap(t -> t.functions().stream()).toList();
|
|
}
|
|
}
|