Skip to content

Commit c26d1ec

Browse files
marcus8448marcus8448
committed
feat: add javadocs to public api
improve implementation explanations as well
1 parent 8a55277 commit c26d1ec

File tree

16 files changed

+195
-79
lines changed

16 files changed

+195
-79
lines changed

‎src/main/generated/assets/galacticraft/lang/en_us.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -310,7 +310,7 @@
310310
"block.galacticraft.olivine_cluster": "Olivine Cluster",
311311
"block.galacticraft.orange_candle_moon_cheese_wheel": "Moon Cheese Wheel with Orange Candle",
312312
"block.galacticraft.orange_glass_fluid_pipe": "Orange Stained Glass Fluid Pipe",
313-
"block.galacticraft.oxygen_bubble_distributor": "Oxygen Bubble Distributor",
313+
"block.galacticraft.oxygen_bubble_distributor": "Bubble Distributor",
314314
"block.galacticraft.oxygen_bubble_distributor.description": "Oxygen Bubble Distributor creates a bubble of air around itself. Requires oxygen and electricity.",
315315
"block.galacticraft.oxygen_collector": "Oxygen Collector",
316316
"block.galacticraft.oxygen_collector.description": "Oxygen Collector will store oxygen collected from leaves in the surrounding area.",

‎src/main/java/dev/galacticraft/api/accessor/ChunkOxygenAccessor.java‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,29 @@
2828
import java.util.Iterator;
2929

3030
public interface ChunkOxygenAccessor {
31+
/**
32+
* {@return the {@link AtmosphereProvider atmosphere providers} that service the chunk section at the given y-position}
33+
* @param y the block y-height of the section to check.
34+
*/
3135
Iterator<AtmosphereProvider> galacticraft$getProviders(int y);
32-
Iterator<BlockPos> galacticraft$getProviderPositions(int y);
3336

34-
void galacticraft$markSectionDirty(int sectionIndex);
37+
/**
38+
* {@return the positions of the {@link AtmosphereProvider atmosphere providers} that service the chunk section at the given y-position}
39+
* @param y the block y-height of the section to check.
40+
*/
41+
Iterator<BlockPos> galacticraft$getProviderPositions(int y);
3542

43+
/**
44+
* Links the given atmospheric provider to the chunk section at the given index.
45+
* @param sectionIndex the index of the chunk section being provided to.
46+
* @param provider the location of the atmospheric provider being linked.
47+
*/
3648
void galacticraft$addAtmosphericProvider(int sectionIndex, BlockPos provider);
49+
50+
/**
51+
* Unlinks the given atmospheric provider to the chunk section at the given index.
52+
* @param sectionIndex the index of the chunk section that is no longer being provided to.
53+
* @param provider the location of the atmospheric provider being unlinked.
54+
*/
3755
void galacticraft$removeAtmosphericProvider(int sectionIndex, BlockPos provider);
3856
}

‎src/main/java/dev/galacticraft/api/accessor/GCBlockExtensions.java‎

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,25 +31,55 @@
3131
import java.util.Iterator;
3232

3333
public interface GCBlockExtensions {
34-
// expectation: ideally for modded blocks, transforms are done before setBlock (e.g. placement state)
35-
// this type of transformation is a bit over-eager as it breaks scenarios where you specifically want "invalid" states.
34+
/**
35+
* {@return whether this block will transform on placement due to a lack of atmosphere}
36+
* This should only be implemented if it is not possible to handle the transformation elsewhere.
37+
* @param state the state being placed
38+
*/
3639
default boolean galacticraft$hasLegacyExtinguishTransform(BlockState state) {
3740
return false;
3841
}
3942

43+
/**
44+
* Extinguishes the given state due to a lack of atmosphere.
45+
* @param pos the position of the block in-world
46+
* @param state the state being placed
47+
* @return the transformed block state.
48+
*/
4049
default BlockState galacticraft$extinguishBlockPlace(BlockPos pos, BlockState state) {
4150
return state;
4251
}
4352

53+
/**
54+
* {@return whether the given block state needs to be altered to changes in atmospheric composition}
55+
* @param state the state being checked
56+
*/
4457
default boolean galacticraft$hasAtmosphereListener(BlockState state) {
4558
return false;
4659
}
4760

61+
/**
62+
* Called when the atmospheric composition changes.
63+
* @param level the current level
64+
* @param pos the position of the block
65+
* @param state the current state of the block
66+
* @param iterator all atmospheric providers at the given position
67+
* @see #galacticraft$onAtmosphereChange(ServerLevel, BlockPos, BlockState, boolean)
68+
*/
4869
default void galacticraft$onAtmosphereChange(ServerLevel level, BlockPos pos, BlockState state, Iterator<AtmosphereProvider> iterator) {
4970
this.galacticraft$onAtmosphereChange(level, pos, state, OxygenUtil.isBreathable(pos, iterator));
5071
}
5172

73+
74+
/**
75+
* Called when the atmospheric composition changes.
76+
* For blocks that just need to know if the position is breathable or not. Should NOT be called outside this class.
77+
* @param level the current level
78+
* @param pos the position of the block
79+
* @param state the current state of the block
80+
* @param breathable whether the given position is currently breathable
81+
* @see #galacticraft$onAtmosphereChange(ServerLevel, BlockPos, BlockState, Iterator)
82+
*/
5283
default void galacticraft$onAtmosphereChange(ServerLevel level, BlockPos pos, BlockState state, boolean breathable) {
5384
}
54-
5585
}

‎src/main/java/dev/galacticraft/api/accessor/LevelOxygenAccessor.java‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,32 @@
2525
import net.minecraft.core.BlockPos;
2626
import net.minecraft.world.level.block.state.BlockState;
2727

28+
/**
29+
* @see LevelOxygenAccessorRO
30+
*/
2831
public interface LevelOxygenAccessor extends LevelOxygenAccessorRO {
32+
/**
33+
* Adds an atmospheric provider to the chunk section at the given position
34+
* @param sectionX the section x-position
35+
* @param sectionY the section y-position
36+
* @param sectionZ the section z-position
37+
* @param provider the position of the provider to add
38+
*/
2939
void galacticraft$addAtmosphericProvider(int sectionX, int sectionY, int sectionZ, BlockPos provider);
40+
41+
/**
42+
* Removes an atmospheric provider from the chunk section at the given position
43+
* @param sectionX the section x-position
44+
* @param sectionY the section y-position
45+
* @param sectionZ the section z-position
46+
* @param provider the position of the provider to remove
47+
*/
3048
void galacticraft$removeAtmosphericProvider(int sectionX, int sectionY, int sectionZ, BlockPos provider);
49+
50+
/**
51+
* Notifies the block at the given position that the atmosphere has changed.
52+
* @param pos the position where the atmosphere changed
53+
* @param state the current block state of the block where the atmosphere changed
54+
*/
3155
default void galacticraft$notifyAtmosphereChange(BlockPos pos, BlockState state) {}
3256
}

‎src/main/java/dev/galacticraft/api/block/entity/AtmosphereProvider.java‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,17 +26,50 @@
2626
import net.minecraft.world.level.block.entity.BlockEntity;
2727
import net.minecraft.world.level.block.state.BlockState;
2828

29+
/**
30+
* Describes a {@link BlockEntity} that generates an atmosphere somewhere in the world.
31+
*
32+
* @see dev.galacticraft.api.accessor.LevelOxygenAccessor
33+
* @see dev.galacticraft.api.accessor.ChunkOxygenAccessor
34+
*/
2935
public interface AtmosphereProvider {
36+
/**
37+
* {@return whether the given point is breathable}
38+
* @param x the x-coordinate to check
39+
* @param y the y-coordinate to check
40+
* @param z the z-coordinate to check
41+
*/
3042
boolean canBreathe(double x, double y, double z);
3143

44+
/**
45+
* {@return whether the given block position is breathable}
46+
* It is not defined where within the block is (or is not) breathable.
47+
* @param x the x-position to check
48+
* @param y the y-position to check
49+
* @param z the z-position to check
50+
*/
3251
default boolean canBreathe(int x, int y, int z) {
3352
return this.canBreathe(new BlockPos(x, y, z));
3453
}
3554

55+
/**
56+
* {@return whether the given block position is breathable}
57+
* It is not defined where within the block is (or is not) breathable.
58+
* @param pos the position to check
59+
*/
3660
boolean canBreathe(BlockPos pos);
3761

62+
/**
63+
* Called when a block state is updated within a chunk that has this atmospheric provider attached.
64+
* @param pos the position of block that was changed
65+
* @param newState the new state being placed at the position.
66+
*/
3867
void notifyStateChange(BlockPos pos, BlockState newState);
3968

69+
/**
70+
* Helper method to get a block entity instance.
71+
* @return {@code this}
72+
*/
4073
default BlockEntity be() {
4174
return (BlockEntity) this;
4275
}

‎src/main/java/dev/galacticraft/impl/internal/accessor/ChunkOxygenSyncer.java‎ renamed to ‎src/main/java/dev/galacticraft/impl/internal/accessor/ChunkOxygenAccessorInternal.java‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,16 @@
2222

2323
package dev.galacticraft.impl.internal.accessor;
2424

25+
import dev.galacticraft.api.accessor.ChunkOxygenAccessor;
2526
import dev.galacticraft.impl.network.s2c.OxygenUpdatePayload;
27+
import org.jetbrains.annotations.ApiStatus;
2628
import org.jetbrains.annotations.Nullable;
2729

28-
public interface ChunkOxygenSyncer {
30+
31+
public interface ChunkOxygenAccessorInternal extends ChunkOxygenAccessor {
32+
@ApiStatus.Internal
33+
void galacticraft$markSectionDirty(int sectionIndex);
34+
35+
@ApiStatus.Internal
2936
OxygenUpdatePayload.OxygenData @Nullable [] galacticraft$getPendingOxygenChanges();
3037
}

‎src/main/java/dev/galacticraft/impl/internal/mixin/oxygen/ChunkAccessMixin.java‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,8 @@
2222

2323
package dev.galacticraft.impl.internal.mixin.oxygen;
2424

25-
import dev.galacticraft.api.accessor.ChunkOxygenAccessor;
2625
import dev.galacticraft.api.block.entity.AtmosphereProvider;
27-
import dev.galacticraft.impl.internal.accessor.ChunkOxygenSyncer;
26+
import dev.galacticraft.impl.internal.accessor.ChunkOxygenAccessorInternal;
2827
import dev.galacticraft.impl.internal.accessor.ChunkSectionOxygenAccessor;
2928
import dev.galacticraft.impl.internal.oxygen.ApPosIterator;
3029
import dev.galacticraft.impl.network.s2c.OxygenUpdatePayload;
@@ -43,7 +42,7 @@
4342
import java.util.Iterator;
4443

4544
@Mixin(ChunkAccess.class)
46-
public abstract class ChunkAccessMixin implements ChunkOxygenAccessor, ChunkOxygenSyncer {
45+
public abstract class ChunkAccessMixin implements ChunkOxygenAccessorInternal {
4746
@Shadow
4847
@Final
4948
protected LevelChunkSection[] sections;

‎src/main/java/dev/galacticraft/impl/internal/mixin/oxygen/ChunkHolderMixin.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222

2323
package dev.galacticraft.impl.internal.mixin.oxygen;
2424

25-
import dev.galacticraft.impl.internal.accessor.ChunkOxygenSyncer;
25+
import dev.galacticraft.impl.internal.accessor.ChunkOxygenAccessorInternal;
2626
import dev.galacticraft.impl.network.s2c.OxygenUpdatePayload;
2727
import net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking;
2828
import net.minecraft.network.protocol.Packet;
@@ -49,7 +49,7 @@ public abstract class ChunkHolderMixin {
4949

5050
@Inject(method = "broadcastChanges", at = @At("RETURN"))
5151
private void flushOxygenPackets(LevelChunk chunk, CallbackInfo ci) {
52-
OxygenUpdatePayload.OxygenData[] data = ((ChunkOxygenSyncer) chunk).galacticraft$getPendingOxygenChanges();
52+
OxygenUpdatePayload.OxygenData[] data = ((ChunkOxygenAccessorInternal) chunk).galacticraft$getPendingOxygenChanges();
5353
if (data != null) {
5454
this.broadcast(this.playerProvider.getPlayers(chunk.getPos(), false), ServerPlayNetworking.createS2CPacket(new OxygenUpdatePayload(chunk.getPos().toLong(), data)));
5555
}

‎src/main/java/dev/galacticraft/impl/internal/mixin/oxygen/EmptyLevelChunkMixin.java‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,8 @@
2222

2323
package dev.galacticraft.impl.internal.mixin.oxygen;
2424

25-
import dev.galacticraft.api.accessor.ChunkOxygenAccessor;
2625
import dev.galacticraft.api.block.entity.AtmosphereProvider;
27-
import dev.galacticraft.impl.internal.accessor.ChunkOxygenSyncer;
26+
import dev.galacticraft.impl.internal.accessor.ChunkOxygenAccessorInternal;
2827
import dev.galacticraft.impl.network.s2c.OxygenUpdatePayload;
2928
import net.minecraft.core.BlockPos;
3029
import net.minecraft.world.level.chunk.EmptyLevelChunk;
@@ -35,7 +34,7 @@
3534
import java.util.Iterator;
3635

3736
@Mixin(EmptyLevelChunk.class)
38-
public abstract class EmptyLevelChunkMixin implements ChunkOxygenSyncer, ChunkOxygenAccessor {
37+
public abstract class EmptyLevelChunkMixin implements ChunkOxygenAccessorInternal {
3938
@Override
4039
public @Nullable OxygenUpdatePayload.OxygenData[] galacticraft$getPendingOxygenChanges() {
4140
return null;

‎src/main/java/dev/galacticraft/impl/internal/mixin/oxygen/ImposterProtoChunkMixin.java‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
import com.google.common.collect.Iterators;
2626
import dev.galacticraft.api.accessor.ChunkOxygenAccessor;
2727
import dev.galacticraft.api.block.entity.AtmosphereProvider;
28-
import dev.galacticraft.impl.internal.accessor.ChunkOxygenSyncer;
28+
import dev.galacticraft.impl.internal.accessor.ChunkOxygenAccessorInternal;
2929
import dev.galacticraft.impl.network.s2c.OxygenUpdatePayload;
3030
import net.minecraft.core.BlockPos;
3131
import net.minecraft.world.level.chunk.ImposterProtoChunk;
@@ -37,7 +37,7 @@
3737
import java.util.Iterator;
3838

3939
@Mixin(ImposterProtoChunk.class)
40-
public abstract class ImposterProtoChunkMixin implements ChunkOxygenAccessor, ChunkOxygenSyncer {
40+
public abstract class ImposterProtoChunkMixin implements ChunkOxygenAccessorInternal {
4141
@Shadow
4242
@Final
4343
private boolean allowWrites;
@@ -60,13 +60,13 @@ public abstract class ImposterProtoChunkMixin implements ChunkOxygenAccessor, Ch
6060
@Override
6161
public void galacticraft$markSectionDirty(int sectionIndex) {
6262
if (this.allowWrites) {
63-
((ChunkOxygenAccessor) this.wrapped).galacticraft$markSectionDirty(sectionIndex);
63+
((ChunkOxygenAccessorInternal) this.wrapped).galacticraft$markSectionDirty(sectionIndex);
6464
}
6565
}
6666

6767
@Override
6868
public OxygenUpdatePayload.OxygenData[] galacticraft$getPendingOxygenChanges() {
69-
return ((ChunkOxygenSyncer) this.wrapped).galacticraft$getPendingOxygenChanges();
69+
return ((ChunkOxygenAccessorInternal) this.wrapped).galacticraft$getPendingOxygenChanges();
7070
}
7171

7272
@Override

0 commit comments

Comments
 (0)