Files
codecraft/src/main/java/com/aranroig/docs/LuaApiDocs.java
2026-10-06 17:59:26 +02:00

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();
}
}