From a1bd3ee162002cae29fbaeeb801fb62daf1fa2cb Mon Sep 17 00:00:00 2001 From: zenfyr Date: Sat, 2 May 2026 22:27:51 +0700 Subject: [PATCH] docs: yeah idk --- docs/README.md | 39 +++++++++++++++++++ .../client/events/AfterFirstReload.java | 4 ++ .../pulsar/client/fakelevel/FakeLevel.java | 3 +- .../client/particles/ItemStackParticle.java | 3 ++ .../particles/ScreenParticleHelper.java | 6 +++ .../impl/VanillaParticleManager.java | 6 +++ .../dev/zenfyr/pulsar/codec/ExtraCodecs.java | 19 ++++++++- .../zenfyr/pulsar/codec/SafeEitherCodec.java | 3 ++ .../pulsar/codec/SafeEitherMapCodec.java | 3 ++ .../pulsar/codec/SafeOptionalCodec.java | 3 ++ .../creativetab/CreativeModeTabBuilder.java | 6 +++ .../CreativeModeTabBuilderImpl.java | 2 + .../pulsar/creativetab/PulsarEntriesImpl.java | 2 + 13 files changed, 96 insertions(+), 3 deletions(-) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..dccc438 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,39 @@ +# Pulsar docs + +Pulsar is a library mod, continuation of [dark-matter](https://github.com/constellation-mc/dark-matter). +unlike dark-matter, pulsar is a monolithic util mod, which users download separately. +it also opts for mojang mappings over yarn. + +these docs are accurate for the Minecraft 1.20.1 version of the mod. + +this is a quick overview of the library features, as each class provides javadoc. + +out of the more interesting utils, pulsar provides: + +## GUI Particles + +package: `client.particles` + +this util enables drawing particle-like things on top of the player's screen. +it comes with an extension to even draw vanilla particles. + +## Extended Creative Mode Tab + +package: `creativetab` + +provides a way to add multiple of the same item to the group. (e.g. air for grouping) + +on the client provides a way to add a custom tab icon renderer. + +## Mixin Util + +package: `mixin` + +the `VirtualMixins` class provides a way to add "virtual" mixin configs at runtime. +mainly useful for modular mods like Andromeda. + +## Reload Listeners + +package: `resources` + +provides an event to register reload listeners with `registryAccess` & `featureFlags` contexts. \ No newline at end of file diff --git a/src/main/java/dev/zenfyr/pulsar/client/events/AfterFirstReload.java b/src/main/java/dev/zenfyr/pulsar/client/events/AfterFirstReload.java index d3ef559..dce3eb0 100644 --- a/src/main/java/dev/zenfyr/pulsar/client/events/AfterFirstReload.java +++ b/src/main/java/dev/zenfyr/pulsar/client/events/AfterFirstReload.java @@ -3,6 +3,10 @@ package dev.zenfyr.pulsar.client.events; import net.fabricmc.fabric.api.event.Event; import net.fabricmc.fabric.api.event.EventFactory; +/** + * This event fires right after the first successful client reload, + * at the end of the mojang loading overlay and game load times are sent to the telemetry manager. + */ public interface AfterFirstReload { Event EVENT = diff --git a/src/main/java/dev/zenfyr/pulsar/client/fakelevel/FakeLevel.java b/src/main/java/dev/zenfyr/pulsar/client/fakelevel/FakeLevel.java index a08f72c..87e3219 100644 --- a/src/main/java/dev/zenfyr/pulsar/client/fakelevel/FakeLevel.java +++ b/src/main/java/dev/zenfyr/pulsar/client/fakelevel/FakeLevel.java @@ -31,7 +31,8 @@ import net.minecraft.world.level.levelgen.presets.WorldPresets; import org.jetbrains.annotations.ApiStatus; /** - * A fake {@link ClientLevel}, mainly to be used for rendering in GUIs + * A fake {@link ClientLevel}, mainly to be used for rendering in GUIs. + * this instance provides basic {@link RegistryAccess} with built-in worldgen registries bootstrapped. */ @UtilityClass public class FakeLevel { diff --git a/src/main/java/dev/zenfyr/pulsar/client/particles/ItemStackParticle.java b/src/main/java/dev/zenfyr/pulsar/client/particles/ItemStackParticle.java index 6055308..21961b1 100644 --- a/src/main/java/dev/zenfyr/pulsar/client/particles/ItemStackParticle.java +++ b/src/main/java/dev/zenfyr/pulsar/client/particles/ItemStackParticle.java @@ -9,6 +9,9 @@ import net.minecraft.client.gui.GuiGraphics; import net.minecraft.util.Mth; import net.minecraft.world.item.ItemStack; +/** + * Example screen particle which renders an item with basic physics simulation. + */ @Environment(EnvType.CLIENT) public class ItemStackParticle extends AbstractScreenParticle { diff --git a/src/main/java/dev/zenfyr/pulsar/client/particles/ScreenParticleHelper.java b/src/main/java/dev/zenfyr/pulsar/client/particles/ScreenParticleHelper.java index a5447ca..2820527 100644 --- a/src/main/java/dev/zenfyr/pulsar/client/particles/ScreenParticleHelper.java +++ b/src/main/java/dev/zenfyr/pulsar/client/particles/ScreenParticleHelper.java @@ -19,6 +19,12 @@ import net.minecraft.client.particle.Particle; import net.minecraft.core.particles.ParticleOptions; import org.jetbrains.annotations.ApiStatus; + +/** + *

provides tools for creating screen particles. {@link #addScreenParticle} methods, provide a way + * to create "screen bound" particles, meaning that they stop rendering when the screen they appeared on + * is closed.

+ */ @UtilityClass @SuppressWarnings("unused") @Environment(EnvType.CLIENT) diff --git a/src/main/java/dev/zenfyr/pulsar/client/particles/impl/VanillaParticleManager.java b/src/main/java/dev/zenfyr/pulsar/client/particles/impl/VanillaParticleManager.java index 4893c17..7018ec0 100644 --- a/src/main/java/dev/zenfyr/pulsar/client/particles/impl/VanillaParticleManager.java +++ b/src/main/java/dev/zenfyr/pulsar/client/particles/impl/VanillaParticleManager.java @@ -21,6 +21,9 @@ import net.minecraft.client.particle.ParticleRenderType; import net.minecraft.client.renderer.GameRenderer; import net.minecraft.core.particles.ParticleOptions; +/** + * state manager for {@link VanillaParticle}, used to batch rendering operations. + */ public class VanillaParticleManager { public static final ThreadLocal LEVEL = ThreadLocal.withInitial(() -> null); @@ -31,6 +34,7 @@ public class VanillaParticleManager { this.screenParticles = screenParticles; } + // this method is an almost direct copy of the one in the particle engine public void render(GuiGraphics graphics) { Minecraft client = Minecraft.getInstance(); @@ -57,6 +61,8 @@ public class VanillaParticleManager { poseStack.mulPoseMatrix(pose.last().pose()); RenderSystem.applyModelViewMatrix(); + // without this, the particles will use the world's light texture, + // which in turn makes them appear dark at night. BrightLightTexture.INSTANCE.turnOnLightLayer(); Tesselator tessellator = Tesselator.getInstance(); BufferBuilder bufferBuilder = tessellator.getBuilder(); diff --git a/src/main/java/dev/zenfyr/pulsar/codec/ExtraCodecs.java b/src/main/java/dev/zenfyr/pulsar/codec/ExtraCodecs.java index 5c8c85c..6ea5e8d 100644 --- a/src/main/java/dev/zenfyr/pulsar/codec/ExtraCodecs.java +++ b/src/main/java/dev/zenfyr/pulsar/codec/ExtraCodecs.java @@ -28,7 +28,10 @@ import org.jetbrains.annotations.NotNull; @UtilityClass public class ExtraCodecs { - public static final Codec COLOR = either( + /** + * a color codec encoded as either an integer, or an array of RGB values. + */ + public static final Codec COLOR = either( Codec.INT, Codec.intRange(0, 255).listOf()) .comapFlatMap( e -> e.map(DataResult::success, integers -> { @@ -39,12 +42,18 @@ public class ExtraCodecs { }), Either::left); + /** + * a 'safe' either {@link Codec}, which returns errors from both codecs if they fail. + */ @Contract(value = "_, _ -> new", pure = true) public static @NotNull Codec> either( final Codec first, final Codec second) { return new SafeEitherCodec<>(first, second); } + /** + * a 'safe' either {@link MapCodec}, which returns errors from both codecs if they fail. + */ @Contract("_, _ -> new") public static @NotNull MapCodec> either( final MapCodec first, final MapCodec second) { @@ -80,7 +89,7 @@ public class ExtraCodecs { } /** - * A weighted list codec which accepts both lists and singular entries. + * A shuffling list codec which accepts both lists and singular entries. */ public static Codec> weightedList(Codec codec) { return either(codec, ShufflingList.codec(codec)) @@ -95,6 +104,9 @@ public class ExtraCodecs { Either::right); } + /** + * a {@link Codec}, which uses a bidirectional map to en/decode objects. + */ public static Codec mapLookup(@NotNull Codec keyCodec, @NotNull BiMap lookup) { return keyCodec.flatXmap( key -> Optional.ofNullable(lookup.get(key)) @@ -105,6 +117,9 @@ public class ExtraCodecs { .orElseGet(() -> DataResult.error(() -> "Unknown type: %s".formatted(eventType)))); } + /** + * an {@link Enum} codec, which uses enum constant names to en/decode values. + */ @ApiStatus.Experimental public static > Codec enumCodec(Class cls) { return Codec.STRING.comapFlatMap( diff --git a/src/main/java/dev/zenfyr/pulsar/codec/SafeEitherCodec.java b/src/main/java/dev/zenfyr/pulsar/codec/SafeEitherCodec.java index bf7f234..512c564 100644 --- a/src/main/java/dev/zenfyr/pulsar/codec/SafeEitherCodec.java +++ b/src/main/java/dev/zenfyr/pulsar/codec/SafeEitherCodec.java @@ -7,8 +7,11 @@ import com.mojang.datafixers.util.Pair; import com.mojang.serialization.Codec; import com.mojang.serialization.DataResult; import com.mojang.serialization.DynamicOps; +import org.jetbrains.annotations.ApiStatus; + import java.util.Objects; +@ApiStatus.Internal final class SafeEitherCodec implements Codec> { private final Codec first; private final Codec second; diff --git a/src/main/java/dev/zenfyr/pulsar/codec/SafeEitherMapCodec.java b/src/main/java/dev/zenfyr/pulsar/codec/SafeEitherMapCodec.java index 48a8470..5fa0607 100644 --- a/src/main/java/dev/zenfyr/pulsar/codec/SafeEitherMapCodec.java +++ b/src/main/java/dev/zenfyr/pulsar/codec/SafeEitherMapCodec.java @@ -4,9 +4,12 @@ package dev.zenfyr.pulsar.codec; import com.mojang.datafixers.util.Either; import com.mojang.serialization.*; +import org.jetbrains.annotations.ApiStatus; + import java.util.Objects; import java.util.stream.Stream; +@ApiStatus.Internal final class SafeEitherMapCodec extends MapCodec> { private final MapCodec first; private final MapCodec second; diff --git a/src/main/java/dev/zenfyr/pulsar/codec/SafeOptionalCodec.java b/src/main/java/dev/zenfyr/pulsar/codec/SafeOptionalCodec.java index 9e7b37a..f98985b 100644 --- a/src/main/java/dev/zenfyr/pulsar/codec/SafeOptionalCodec.java +++ b/src/main/java/dev/zenfyr/pulsar/codec/SafeOptionalCodec.java @@ -1,10 +1,13 @@ package dev.zenfyr.pulsar.codec; import com.mojang.serialization.*; +import org.jetbrains.annotations.ApiStatus; + import java.util.Objects; import java.util.Optional; import java.util.stream.Stream; +@ApiStatus.Internal final class SafeOptionalCodec extends MapCodec> { private final String name; private final Codec elementCodec; diff --git a/src/main/java/dev/zenfyr/pulsar/creativetab/CreativeModeTabBuilder.java b/src/main/java/dev/zenfyr/pulsar/creativetab/CreativeModeTabBuilder.java index a01716e..1fef46a 100644 --- a/src/main/java/dev/zenfyr/pulsar/creativetab/CreativeModeTabBuilder.java +++ b/src/main/java/dev/zenfyr/pulsar/creativetab/CreativeModeTabBuilder.java @@ -10,6 +10,9 @@ import net.minecraft.world.item.ItemStack; import net.minecraft.world.level.ItemLike; import org.jetbrains.annotations.Nullable; +/** + * An alternative creative mode tab builder with pulsar extensions. + */ public interface CreativeModeTabBuilder { static CreativeModeTabBuilder create(@NonNull ResourceLocation identifier) { @@ -28,6 +31,9 @@ public interface CreativeModeTabBuilder { CreativeModeTabBuilder texture(String texture); + /** + * unlike the vanilla collector, this one allows multiple of the same item. + */ CreativeModeTabBuilder entries(PulsarEntries.Collector collector); CreativeModeTabBuilder displayName(Component displayName); diff --git a/src/main/java/dev/zenfyr/pulsar/creativetab/CreativeModeTabBuilderImpl.java b/src/main/java/dev/zenfyr/pulsar/creativetab/CreativeModeTabBuilderImpl.java index 67f8473..36a6b86 100644 --- a/src/main/java/dev/zenfyr/pulsar/creativetab/CreativeModeTabBuilderImpl.java +++ b/src/main/java/dev/zenfyr/pulsar/creativetab/CreativeModeTabBuilderImpl.java @@ -9,7 +9,9 @@ import net.minecraft.network.chat.Component; import net.minecraft.resources.ResourceLocation; import net.minecraft.world.item.CreativeModeTab; import net.minecraft.world.item.ItemStack; +import org.jetbrains.annotations.ApiStatus; +@ApiStatus.Internal class CreativeModeTabBuilderImpl implements CreativeModeTabBuilder { private final ResourceLocation location; diff --git a/src/main/java/dev/zenfyr/pulsar/creativetab/PulsarEntriesImpl.java b/src/main/java/dev/zenfyr/pulsar/creativetab/PulsarEntriesImpl.java index 89f347d..68fbb7e 100644 --- a/src/main/java/dev/zenfyr/pulsar/creativetab/PulsarEntriesImpl.java +++ b/src/main/java/dev/zenfyr/pulsar/creativetab/PulsarEntriesImpl.java @@ -4,7 +4,9 @@ import java.util.LinkedHashSet; import java.util.LinkedList; import net.minecraft.world.item.CreativeModeTab; import net.minecraft.world.item.ItemStack; +import org.jetbrains.annotations.ApiStatus; +@ApiStatus.Internal class PulsarEntriesImpl implements PulsarEntries { private final CreativeModeTab.Output entries; -- 2.51.2