diff --git a/README.md b/README.md index 1ac154c..0d00386 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,232 @@ ## Dependencies * **Java 21** -* [Fabric](https://fabricmc.net/) Loader 0.19.2 +* [Fabric](https://fabricmc.net/) Loader 0.16.1 * [Fabric API](https://modrinth.com/mod/fabric-api/version/0.116.12+1.21.1) * [Minecraft 1.21.1](https://www.minecraft.net/tr-tr/article/minecraft-java-edition-1-21-1) ## License -This template is available under the CC0 license. Feel free to learn from it and incorporate it in your own projects. +This library is available under the CC0 license. Feel free to learn from it and incorporate it in your own projects. + +## API + +### `DLItemUtil` + +Item and `ItemStack` helpers. All methods are null-safe and return `Optional` or a declared default instead of throwing on missing data. + +```java +// Get the namespaced item ID ("minecraft:air" for empty stacks) +String id = DLItemUtil.getId(stack); + +// Read / write custom_data NBT component +Optional data = DLItemUtil.getCustomData(stack); +DLItemUtil.setCustomData(stack, nbtCompound); +DLItemUtil.removeCustomDataKey(stack, "myKey"); + +// Typed custom_data shortcuts +Optional s = DLItemUtil.getCustomString(stack, "tag"); +Optional i = DLItemUtil.getCustomInt(stack, "level"); + +// Display name +Optional name = DLItemUtil.getCustomName(stack); +DLItemUtil.setCustomName(stack, "My Item"); + +// Durability +float fraction = DLItemUtil.durabilityFraction(stack); // 0.0–1.0 + +// Misc +ItemStack copy = DLItemUtil.copyOrEmpty(stack); +DLItemUtil.clampCount(stack); +``` + +--- + +### `DLNbtUtil` + +Null-safe wrappers around `NbtCompound`. Returns `Optional` or a fallback instead of 0 / empty string on missing keys. + +```java +// Safe getters → Optional +Optional s = DLNbtUtil.getString(nbt, "key"); +Optional i = DLNbtUtil.getInt(nbt, "key"); +Optional l = DLNbtUtil.getLong(nbt, "key"); +Optional b = DLNbtUtil.getBoolean(nbt, "key"); +Optional c = DLNbtUtil.getCompound(nbt, "key"); + +// Getters with fallback +String s = DLNbtUtil.getStringOr(nbt, "key", "default"); +int i = DLNbtUtil.getIntOr(nbt, "key", 0); +long l = DLNbtUtil.getLongOr(nbt, "key", 0L); +boolean b = DLNbtUtil.getBooleanOr(nbt, "key", false); + +// String lists +List list = DLNbtUtil.getStringList(nbt, "tags"); +DLNbtUtil.putStringList(nbt, "tags", List.of("a", "b")); + +// Utilities +NbtCompound copy = DLNbtUtil.copyOrEmpty(nbt); +NbtCompound merged = DLNbtUtil.merge(target, source); // source keys overwrite target +``` + +--- + +### `DLPlayerUtil` + +Server-side player utilities. All methods take a `MinecraftServer` instance. + +```java +// Lookup +Optional p = DLPlayerUtil.byName(server, "Steve"); +Optional p = DLPlayerUtil.byUuid(server, uuid); + +// Broadcast +DLPlayerUtil.broadcast(server, Text.literal("Hello!")); +DLPlayerUtil.broadcast(server, text, /* overlay */ true); // action bar +DLPlayerUtil.broadcastToOps(server, text, /* minLevel */ 2); + +// Queries +List all = DLPlayerUtil.online(server); +int count = DLPlayerUtil.onlineCount(server); +boolean on = DLPlayerUtil.isOnline(server, "Steve"); +boolean op = DLPlayerUtil.isOp(server, player); + +// Safe send (no-op if player disconnected) +DLPlayerUtil.sendIfOnline(server, uuid, Text.literal("Hi")); +``` + +--- + +### `DLServerUtil` + +Server-level helpers: worlds, time, TPS, and command execution. + +```java +// World access +ServerWorld overworld = DLServerUtil.overworld(server); +Optional nether = DLServerUtil.byDimension(server, "minecraft:the_nether"); + +// Time +long tick = DLServerUtil.currentTick(server); // absolute world age +long daytime = DLServerUtil.daytimeTick(server); // 0–23999 +boolean day = DLServerUtil.isDaytime(server); + +// Performance +double ms = DLServerUtil.meanTickMs(server); +double tps = DLServerUtil.estimatedTps(server); // capped at 20.0 + +// Run a command as the server (no leading slash) +DLServerUtil.runCommand(server, "say Hello"); + +// Info +String motd = DLServerUtil.motd(server); +boolean whitelist = DLServerUtil.isWhitelistEnabled(server); +boolean online = DLServerUtil.isOnlineMode(server); +``` + +--- + +### `DLWorldUtil` + +World, block, and position utilities. Never forces chunk loads unless stated. + +```java +// Block queries (empty if chunk not loaded) +Optional state = DLWorldUtil.getBlockState(world, pos); +boolean air = DLWorldUtil.isAir(world, pos); +boolean replaceable = DLWorldUtil.isReplaceable(world, pos); + +// Position helpers +BlockPos bp = DLWorldUtil.toBlockPos(vec3d); +Vec3d center = DLWorldUtil.blockCenter(pos); + +// Distance +double dist = DLWorldUtil.distance(a, b); +double dist2 = DLWorldUtil.distanceSquared(a, b); +boolean near = DLWorldUtil.isWithinRadius(center, pos, 16.0); + +// Chunk +ChunkPos chunk = DLWorldUtil.chunkOf(pos); +boolean loaded = DLWorldUtil.isChunkLoaded(world, pos); + +// Height +int topY = DLWorldUtil.topSolidY(world, x, z); +Optional surface = DLWorldUtil.surfacePos(world, x, z); + +// Weather & time +boolean day = DLWorldUtil.isDaytime(world); +boolean rain = DLWorldUtil.isRaining(world); +boolean thunder = DLWorldUtil.isThundering(world); +double fraction = DLWorldUtil.timeOfDayFraction(world); // 0.0–1.0 + +// Diagnostics +int entityCount = DLWorldUtil.loadedEntityCount(world); +``` + +--- + +### `DLMathUtil` + +Integer and fixed-point math. All methods use `int`/`long` to stay compatible with scoreboard arithmetic. Trig methods are scaled by `FIXED_SCALE` (1000) so results can be used directly in scoreboard operations. + +```java +// Basic +int clamped = DLMathUtil.clamp(value, 0, 100); +int root = DLMathUtil.sqrt(144); // 12 +long power = DLMathUtil.pow(2, 10); // 1024 +int mod = DLMathUtil.mod(-1, 4); // 3 (always non-negative) +int gcd = DLMathUtil.gcd(12, 8); // 4 +long lcm = DLMathUtil.lcm(4, 6); // 12 + +// Scaling / lerp +int mid = DLMathUtil.lerp(0, 100, 3, 10); // 30 +int mapped = DLMathUtil.map(5, 0, 10, 0, 200); // 100 + +// Trig (× 1000) +int s = DLMathUtil.sin(90); // 1000 +int c = DLMathUtil.cos(0); // 1000 +int a = DLMathUtil.atan2Deg(1, 1); // 45 + +// Distance +int d2 = DLMathUtil.distance2d(3, 4); // 5 +int d3 = DLMathUtil.distance3d(1, 2, 2); // 3 +int cb = DLMathUtil.distanceChebyshev(3, 5); // 5 + +// Bit / number helpers +boolean pow2 = DLMathUtil.isPowerOfTwo(64); // true +int log = DLMathUtil.log2(64); // 6 +int wrap = DLMathUtil.wrap(370, 0, 360); // 10 +int ceil = DLMathUtil.ceilDiv(7, 2); // 4 +int sign = DLMathUtil.sign(-5); // -1 +int signN = DLMathUtil.signNonZero(0); // 1 +``` + +--- + +### `DLTextUtil` + +Text and chat formatting utilities. All methods return `MutableText` for chaining. + +```java +// Prefixed feedback messages ([dataLib] prefix) +player.sendMessage(DLTextUtil.info("Loaded.")); +player.sendMessage(DLTextUtil.success("Done!")); +player.sendMessage(DLTextUtil.warn("Check your config.")); +player.sendMessage(DLTextUtil.error("Something went wrong.")); + +// Generic styling +MutableText red = DLTextUtil.colored("Danger", Formatting.RED, Formatting.BOLD); +MutableText hex = DLTextUtil.rgb("Custom", 0xFF5555); + +// Key-value lines +player.sendMessage(DLTextUtil.keyValue("Version", "5.1.1")); +player.sendMessage(DLTextUtil.keyValue("Status", "online", Formatting.GREEN)); + +// Layout helpers +player.sendMessage(DLTextUtil.separator()); +MutableText flag = DLTextUtil.bool(true); // green "true" / red "false" + +// String helpers +String clean = DLTextUtil.stripFormatting("§aGreen"); // "Green" +String clipped = DLTextUtil.truncate("A very long string", 10); // "A very lo…" +```