Thingo
This commit is contained in:
10
src/main/java/com/aranroig/docs/ExampleDoc.java
Normal file
10
src/main/java/com/aranroig/docs/ExampleDoc.java
Normal file
@@ -0,0 +1,10 @@
|
||||
package com.aranroig.docs;
|
||||
|
||||
/**
|
||||
* A titled Lua snippet shown in the in-game documentation.
|
||||
*
|
||||
* @param title one-line caption, may be empty
|
||||
* @param code the snippet, lines separated by {@code \n}
|
||||
*/
|
||||
public record ExampleDoc(String title, String code) {
|
||||
}
|
||||
25
src/main/java/com/aranroig/docs/FunctionDoc.java
Normal file
25
src/main/java/com/aranroig/docs/FunctionDoc.java
Normal file
@@ -0,0 +1,25 @@
|
||||
package com.aranroig.docs;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* A single documented Lua function.
|
||||
*
|
||||
* @param name full dotted name, e.g. {@code "world.set_block"}
|
||||
* @param signature the call as the player would read it, e.g. {@code world.set_block(x, y, z, block)}
|
||||
* @param summary one or two sentences on what it does; {@code \n} separates paragraphs
|
||||
* @param params positional parameters (empty for variadic helpers)
|
||||
* @param returns what the call evaluates to
|
||||
* @param notes gotchas, failure reasons, tips — each entry is one bullet
|
||||
* @param examples runnable snippets
|
||||
*/
|
||||
public record FunctionDoc(
|
||||
String name,
|
||||
String signature,
|
||||
String summary,
|
||||
List<ParamDoc> params,
|
||||
String returns,
|
||||
List<String> notes,
|
||||
List<ExampleDoc> examples
|
||||
) {
|
||||
}
|
||||
142
src/main/java/com/aranroig/docs/LuaApiDocs.java
Normal file
142
src/main/java/com/aranroig/docs/LuaApiDocs.java
Normal file
@@ -0,0 +1,142 @@
|
||||
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();
|
||||
}
|
||||
}
|
||||
12
src/main/java/com/aranroig/docs/ParamDoc.java
Normal file
12
src/main/java/com/aranroig/docs/ParamDoc.java
Normal file
@@ -0,0 +1,12 @@
|
||||
package com.aranroig.docs;
|
||||
|
||||
/**
|
||||
* One parameter of a documented Lua function.
|
||||
*
|
||||
* @param name parameter name as written in the signature, e.g. {@code "block"}
|
||||
* @param type short type name shown to the user, e.g. {@code "string"} or {@code "number"}
|
||||
* @param optional whether the parameter may be omitted
|
||||
* @param description what the parameter means
|
||||
*/
|
||||
public record ParamDoc(String name, String type, boolean optional, String description) {
|
||||
}
|
||||
14
src/main/java/com/aranroig/docs/Topic.java
Normal file
14
src/main/java/com/aranroig/docs/Topic.java
Normal file
@@ -0,0 +1,14 @@
|
||||
package com.aranroig.docs;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Top-level grouping shown in the left-hand list of the in-game docs panel,
|
||||
* e.g. the {@code world} table or the {@code print} helper.
|
||||
*
|
||||
* @param title short header, usually the Lua table name
|
||||
* @param blurb one or two sentences describing the group; {@code \n} separates paragraphs
|
||||
* @param functions the functions this topic documents
|
||||
*/
|
||||
public record Topic(String title, String blurb, List<FunctionDoc> functions) {
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
package com.aranroig.payloads;
|
||||
|
||||
import com.aranroig.Codecraft;
|
||||
import com.aranroig.editor.EditorFile;
|
||||
import net.minecraft.network.RegistryFriendlyByteBuf;
|
||||
import net.minecraft.network.codec.ByteBufCodecs;
|
||||
import net.minecraft.network.codec.StreamCodec;
|
||||
import net.minecraft.network.protocol.common.custom.CustomPacketPayload;
|
||||
import net.minecraft.resources.Identifier;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
public record ClientboundProjectFilesPayload(List<EditorFile> files) implements CustomPacketPayload {
|
||||
|
||||
public static final Identifier PROJECT_FILES_PAYLOAD_ID = Identifier.fromNamespaceAndPath(Codecraft.MOD_ID, "project_files");
|
||||
|
||||
public static final CustomPacketPayload.Type<ClientboundProjectFilesPayload> TYPE = new CustomPacketPayload.Type<>(PROJECT_FILES_PAYLOAD_ID);
|
||||
|
||||
public static final StreamCodec<RegistryFriendlyByteBuf, ClientboundProjectFilesPayload> CODEC =
|
||||
StreamCodec.composite(
|
||||
EditorFile.STREAM_CODEC.apply(ByteBufCodecs.list()),
|
||||
ClientboundProjectFilesPayload::files,
|
||||
ClientboundProjectFilesPayload::new
|
||||
);
|
||||
|
||||
@Override
|
||||
public Type<? extends CustomPacketPayload> type() {
|
||||
return TYPE;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
package com.aranroig.payloads;
|
||||
|
||||
import com.aranroig.Codecraft;
|
||||
import net.minecraft.network.RegistryFriendlyByteBuf;
|
||||
import net.minecraft.network.codec.StreamCodec;
|
||||
import net.minecraft.network.protocol.common.custom.CustomPacketPayload;
|
||||
import net.minecraft.resources.Identifier;
|
||||
|
||||
public record ServerboundRequestProjectPayload() implements CustomPacketPayload {
|
||||
|
||||
public static final Identifier REQUEST_PROJECT_PAYLOAD_ID = Identifier.fromNamespaceAndPath(Codecraft.MOD_ID, "request_project");
|
||||
|
||||
public static final CustomPacketPayload.Type<ServerboundRequestProjectPayload> TYPE = new CustomPacketPayload.Type<>(REQUEST_PROJECT_PAYLOAD_ID);
|
||||
|
||||
public static final StreamCodec<RegistryFriendlyByteBuf, ServerboundRequestProjectPayload> CODEC =
|
||||
StreamCodec.unit(new ServerboundRequestProjectPayload());
|
||||
|
||||
@Override
|
||||
public Type<? extends CustomPacketPayload> type() {
|
||||
return TYPE;
|
||||
}
|
||||
}
|
||||
22
src/main/java/com/aranroig/wrapper/ChatLogger.java
Normal file
22
src/main/java/com/aranroig/wrapper/ChatLogger.java
Normal file
@@ -0,0 +1,22 @@
|
||||
package com.aranroig.wrapper;
|
||||
|
||||
import net.minecraft.network.chat.Component;
|
||||
import net.minecraft.server.level.ServerPlayer;
|
||||
import party.iroiro.luajava.value.LuaFunction;
|
||||
|
||||
public class ChatLogger {
|
||||
public static LuaFunction print(ServerPlayer player) {
|
||||
return (lua, args) -> {
|
||||
StringBuilder sb = new StringBuilder();
|
||||
|
||||
for (int i = 0; i < args.length; i++) {
|
||||
if (i > 0) sb.append('\t');
|
||||
sb.append(args[i]);
|
||||
}
|
||||
|
||||
player.sendSystemMessage(Component.literal(sb.toString()));
|
||||
|
||||
return null;
|
||||
};
|
||||
}
|
||||
}
|
||||
223
src/main/java/com/aranroig/wrapper/WorldApi.java
Normal file
223
src/main/java/com/aranroig/wrapper/WorldApi.java
Normal file
@@ -0,0 +1,223 @@
|
||||
package com.aranroig.wrapper;
|
||||
|
||||
import com.mojang.brigadier.exceptions.CommandSyntaxException;
|
||||
import net.minecraft.commands.arguments.blocks.BlockStateParser;
|
||||
import net.minecraft.core.BlockPos;
|
||||
import net.minecraft.core.registries.BuiltInRegistries;
|
||||
import net.minecraft.server.level.ServerLevel;
|
||||
import net.minecraft.server.level.ServerPlayer;
|
||||
import net.minecraft.world.level.block.Block;
|
||||
import net.minecraft.world.level.block.Blocks;
|
||||
import net.minecraft.world.level.block.state.BlockState;
|
||||
import party.iroiro.luajava.Lua;
|
||||
import party.iroiro.luajava.value.LuaValue;
|
||||
|
||||
/**
|
||||
* The {@code world} table given to user scripts: placing, removing and reading blocks.
|
||||
*
|
||||
* <p>Coordinates are absolute world coordinates in the dimension the executing player
|
||||
* stands in. They are not limited by the player's reach, so a script can edit any block
|
||||
* of a loaded chunk.</p>
|
||||
*
|
||||
* <p>Failures are reported the Lua way: a function returns {@code false} (or {@code nil}
|
||||
* for {@code world.get_block}) followed by a short reason, so callers can write
|
||||
* {@code if not world.set_block(...) then ... end}.</p>
|
||||
*
|
||||
* <p>Registered from {@link com.aranroig.Codecraft} on the server thread, which is the
|
||||
* only thread allowed to touch the world.</p>
|
||||
*/
|
||||
public class WorldApi {
|
||||
|
||||
/** Update flags for {@link net.minecraft.world.level.Level#setBlock}: neighbours and clients. */
|
||||
private static final int UPDATE_FLAGS = Block.UPDATE_ALL;
|
||||
|
||||
/**
|
||||
* Registers the global {@code world} table.
|
||||
*
|
||||
* @param lua state to register the table on
|
||||
* @param player the player the edits belong to, which also selects the dimension
|
||||
*/
|
||||
public static void register(Lua lua, ServerPlayer player) {
|
||||
lua.newTable();
|
||||
int world = lua.getTop();
|
||||
|
||||
lua.push((L, args) -> setBlock(L, player, args));
|
||||
lua.setField(world, "set_block");
|
||||
|
||||
lua.push((L, args) -> removeBlock(L, player, args));
|
||||
lua.setField(world, "remove_block");
|
||||
|
||||
lua.push((L, args) -> getBlock(L, player, args));
|
||||
lua.setField(world, "get_block");
|
||||
|
||||
lua.setGlobal("world");
|
||||
}
|
||||
|
||||
/**
|
||||
* {@code world.set_block(x, y, z, block)}
|
||||
*
|
||||
* <p>{@code block} is a block id such as {@code "minecraft:stone"}, optionally with
|
||||
* block states: {@code "minecraft:oak_stairs[facing=north]"}. Tags are not allowed.</p>
|
||||
*/
|
||||
private static LuaValue[] setBlock(Lua lua, ServerPlayer player, LuaValue[] args) {
|
||||
if (args.length < 4) {
|
||||
return fail(lua, "usage: world.set_block(x, y, z, \"minecraft:stone\")");
|
||||
}
|
||||
|
||||
BlockPos pos = position(args);
|
||||
if (pos == null) {
|
||||
return fail(lua, "x, y and z must be numbers");
|
||||
}
|
||||
|
||||
if (args[3].type() != Lua.LuaType.STRING) {
|
||||
return fail(lua, "block must be a string, e.g. \"minecraft:stone\"");
|
||||
}
|
||||
|
||||
String description = args[3].toString();
|
||||
BlockState state;
|
||||
try {
|
||||
state = BlockStateParser.parseForBlock(BuiltInRegistries.BLOCK, description, false).blockState();
|
||||
} catch (CommandSyntaxException e) {
|
||||
return fail(lua, "'" + description + "' is not a block");
|
||||
}
|
||||
|
||||
ServerLevel level = player.level();
|
||||
String problem = blockProblem(level, pos);
|
||||
if (problem != null) {
|
||||
return fail(lua, problem);
|
||||
}
|
||||
|
||||
level.setBlock(pos, state, UPDATE_FLAGS);
|
||||
|
||||
// Read the block back instead of trusting the result of setBlock: a block that
|
||||
// cannot stay where it was put (a torch in mid-air) removes itself again.
|
||||
if (level.getBlockState(pos).getBlock() != state.getBlock()) {
|
||||
return fail(lua, "'" + description + "' does not fit at " + describe(pos));
|
||||
}
|
||||
return success(lua);
|
||||
}
|
||||
|
||||
/**
|
||||
* {@code world.remove_block(x, y, z [, drops])}
|
||||
*
|
||||
* <p>The block vanishes without drops unless {@code drops} is given as {@code true},
|
||||
* in which case it breaks as if a player had broken it.</p>
|
||||
*/
|
||||
private static LuaValue[] removeBlock(Lua lua, ServerPlayer player, LuaValue[] args) {
|
||||
if (args.length < 3) {
|
||||
return fail(lua, "usage: world.remove_block(x, y, z [, drops])");
|
||||
}
|
||||
|
||||
BlockPos pos = position(args);
|
||||
if (pos == null) {
|
||||
return fail(lua, "x, y and z must be numbers");
|
||||
}
|
||||
|
||||
ServerLevel level = player.level();
|
||||
String problem = blockProblem(level, pos);
|
||||
if (problem != null) {
|
||||
return fail(lua, problem);
|
||||
}
|
||||
|
||||
if (level.getBlockState(pos).isAir()) {
|
||||
return fail(lua, "there is nothing to remove at " + describe(pos));
|
||||
}
|
||||
|
||||
if (args.length > 3 && args[3].toBoolean()) {
|
||||
return level.destroyBlock(pos, true, player, UPDATE_FLAGS)
|
||||
? success(lua)
|
||||
: fail(lua, "could not remove the block at " + describe(pos));
|
||||
}
|
||||
|
||||
level.setBlock(pos, Blocks.AIR.defaultBlockState(), UPDATE_FLAGS);
|
||||
if (!level.getBlockState(pos).isAir()) {
|
||||
return fail(lua, "could not remove the block at " + describe(pos));
|
||||
}
|
||||
return success(lua);
|
||||
}
|
||||
|
||||
/**
|
||||
* {@code world.get_block(x, y, z)}
|
||||
*
|
||||
* <p>Returns the block id with its block states, e.g. {@code "minecraft:air"} or
|
||||
* {@code "minecraft:oak_stairs[facing=north]"}, ready to be given to set_block.</p>
|
||||
*/
|
||||
private static LuaValue[] getBlock(Lua lua, ServerPlayer player, LuaValue[] args) {
|
||||
if (args.length < 3) {
|
||||
return missing(lua, "usage: world.get_block(x, y, z)");
|
||||
}
|
||||
|
||||
BlockPos pos = position(args);
|
||||
if (pos == null) {
|
||||
return missing(lua, "x, y and z must be numbers");
|
||||
}
|
||||
|
||||
ServerLevel level = player.level();
|
||||
String problem = blockProblem(level, pos);
|
||||
if (problem != null) {
|
||||
return missing(lua, problem);
|
||||
}
|
||||
|
||||
return new LuaValue[]{ lua.from(BlockStateParser.serialize(level.getBlockState(pos))) };
|
||||
}
|
||||
|
||||
/**
|
||||
* Reads {@code x}, {@code y} and {@code z} from the first three arguments.
|
||||
*
|
||||
* @return the position, or {@code null} when one of them is not a number
|
||||
*/
|
||||
private static BlockPos position(LuaValue[] args) {
|
||||
Integer x = number(args[0]);
|
||||
Integer y = number(args[1]);
|
||||
Integer z = number(args[2]);
|
||||
if (x == null || y == null || z == null) {
|
||||
return null;
|
||||
}
|
||||
return new BlockPos(x, y, z);
|
||||
}
|
||||
|
||||
/** Reads a Lua number as an int, or {@code null} for anything else. */
|
||||
private static Integer number(LuaValue value) {
|
||||
if (value == null || value.type() != Lua.LuaType.NUMBER) {
|
||||
return null;
|
||||
}
|
||||
try {
|
||||
return (int) value.toInteger();
|
||||
} catch (RuntimeException e) {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Precondition shared by the three functions.
|
||||
*
|
||||
* @return why the block cannot be touched, or {@code null} when it can
|
||||
*/
|
||||
private static String blockProblem(ServerLevel level, BlockPos pos) {
|
||||
if (level.isOutsideBuildHeight(pos)) {
|
||||
return "y must be between " + level.getMinY() + " and " + level.getMaxY()
|
||||
+ ", not " + pos.getY();
|
||||
}
|
||||
if (!level.isLoaded(pos)) {
|
||||
return "the chunk at " + pos.getX() + ", " + pos.getZ() + " is not loaded";
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
private static String describe(BlockPos pos) {
|
||||
return pos.getX() + ", " + pos.getY() + ", " + pos.getZ();
|
||||
}
|
||||
|
||||
private static LuaValue[] success(Lua lua) {
|
||||
return new LuaValue[]{ lua.from(true) };
|
||||
}
|
||||
|
||||
private static LuaValue[] fail(Lua lua, String reason) {
|
||||
return new LuaValue[]{ lua.from(false), lua.from(reason) };
|
||||
}
|
||||
|
||||
/** Failure for {@code world.get_block}, which gives {@code nil} rather than {@code false}. */
|
||||
private static LuaValue[] missing(Lua lua, String reason) {
|
||||
return new LuaValue[]{ lua.fromNull(), lua.from(reason) };
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user