This page contains links to external documentation that may be useful for several topics regarding development, as well +as other resources you might find helpful.
+Official Forge / NeoForge Docs
+ +Official Fabric Docs
+ +Other Modding Docs
+ +LDLib is the main library we're using for GTCEu-Modern.
+LDLib Docs
+ +Overview on using Mixins
+ +This is a great resource for getting started on how to use mixins, as well as a good quick reference if you're +looking for how to do something specific.
+Note that this is not exclusive to Fabric, but applies for all platforms instead.
+Unofficial Documentation
+ +Unofficial documentation for Mojang's DataFixerUpper library.
+Using Registrate
+ +Architectury Gradle Plugin
+Architectury-Wiki Gradle Plugin
+Note that we're only using Architectury's build system, not the library itself.
+Shimmer (one of our soft-dependencies) displays information about colored lights in development environments by default.
+You can turn it off using the command /shimmer coloredLightMonitor ingame.
Alternatively, if you want to disable it by default, put this in your KubeJS client scripts:
+// Disable Shimmer's colored light monitor:
+let LightCounterRender = Java.loadClass("com.lowdragmc.shimmer.client.light.LightCounter$Render")
+LightCounterRender.enable = false
+Fabric doesn't have a capability system like Forge does, but you can use several utility methods instead:
+FluidTransferHelper.getFluidTransfer(...);
+ItemTransferHelper.getItemTransfer(...);
+GTCapabilityHelper.getRecipeLogic(...)
+GTCapabilityHelper.getControllable(...)
+GTCapabilityHelper.getCoverable(...)
+GTCapabilityHelper.getToolable(...)
+GTCapabilityHelper.getWorkable(...)
+GTCapabilityHelper.getElectricItem(...)
+GTCapabilityHelper.getEnergyContainer(...)
+Note
+In general, these containers should be created as final fields (that's what we need for the
+SyncData system).
+Set their base arguments in the constructor (you can pass args for subclasses to modify).
You can create these containers via one of the following classes:
+NotifiableItemStackHandlerNotifiableFluidTankNotifiableEnergyContainerIn general, you should prefer these classes over other implementations if possible, as they notify all listeners +of internal changes to improve performance.
+IO constructor parameters:
+handlerIO: Whether the container is regarded as input or output during recipe processingcapabilityIO: Whether the player can use hoppers, pipes, cables, etc. to interact with the storageIf you don't need to use the storage for recipe processing and/or providing capabilities, you can just use one of the +following classes, as they are more lightweight:
+ItemStackTransferFluidStorageIn some cases, you might need to create a custom implementation for either of these containers.
+To do so, use either of the following interfaces:
IItemTransferIFluidTransferIEnergyContainerIn case you have special requirements to your containers, you may be able to use one of these implementations in
+conjunction with one or more regular containers.
+They generally act as a proxy to the underlying container(s), while also handling these requirements.
ItemTransferListFluidTransferListEnergyContainerListFor proxying multiple containers, limited to a specific IO direction.
+IOItemTransferListIOFluidTransferList Not merged yet
Branch: mi-ender-link
If you need to proxy any item or fluid container that needs to be rate limited for insertion and extraction, you can +use either of the following classes:
+LimitingItemTransferProxyLimitingFluidTransferProxyThe transfer limit passed as a constructor parameter will not renew automatically. Your container will therefore stop +transferring anything once this limit is reached.
+If you want to make this a rate limit instead, you will have to schedule a task that regularly resets the transfer +limit to the maximum value for your task's interval:
+public class MyCover extends CoverBehavior {
+ private LimitingFluidTransferProxy transferProxy;
+ private ConditionalSubscriptionHandler rateLimitSubscription;
+
+ public MyCover(IFluidTransfer myFluidTransfer) {
+ super(/* ... */);
+
+ transferProxy = new LimitingFluidTransferProxy(
+ myFluidTransfer,
+ 0L // Initial limit of 0, will be updated regularly in isRateLimitRefreshActive()
+ );
+ rateLimitSubscription = new ConditionalSubscriptionHandler(
+ this,
+ this::resetTransferRateLimit,
+ this::isRateLimitRefreshActive
+ );
+ }
+
+ @Override
+ public void onLoad() {
+ super.onLoad();
+ rateLimitSubscription.initialize(coverHolder.getLevel());
+ }
+
+ private void resetTransferRateLimit() {
+ if (transferProxy == null)
+ return;
+
+ transferProxy.setRemainingTransfer(transferRate.getMilliBuckets() * 20);
+ }
+
+ private boolean isRateLimitRefreshActive() {
+ // ...
+ }
+}
+In certain cases (e.g. in a cache that holds all currently loaded instances of a machine), you might need to store data +in a global (static and mutable) variable.
+When doing so, you need to ensure that remote and serverside instances don't get mixed up.
+SideLocal<T>Not yet merged
Branch: mi-ender-link
To make working with this requirement easier, You can use SideLocal<T> to store your global data.
+It is similar to Java's ThreadLocal, but operates on the game's sides instead.
If you are currently on the remote side (LDLib.isRemote() / on the client's main thread), it will return the
+remote side's instance of your data. Otherwise, you will get the server side's instance.
public class MyCache {
+ private static SideLocal<Map<UUID, MyData>> cache = new SideLocal<>(HashMap::new);
+
+ public static void cacheData(UUID id, MyData data) {
+ cache.get().put(id, data);
+ }
+
+ public static MyData getData(UUID id) {
+ return cache.get().get(id);
+ }
+}
+Alternatively to passing an initializer for both instances to SideLocal's constructor, you can also supply
+separate instances for the remote and server side.
The fluid systems of Forge and Fabric use different units. +Make sure you use the correct units whenever you're handling fluid amounts.
+To get the size of one bucket, use the following method:
+FluidHelper.getBucket(); // returns 1000 on Forge and 81000 on Fabric.
+Not yet documented
+Due to Minecraft's worldgen limitations (1), GTCEu's ore vein generation does not use the native worldgen feature system.
+Instead, we have our own system of generating ore veins separately from the actual ore placement,
+so that ores are only ever placed for the currently generating chunk.
+This page roughly describes the process of generating, caching and placing ores.
The generation can be (roughly) split up into three steps:
+This document will cover these steps from the bottom up, starting at the chunk generation mixin (ChunkGeneratorMixin.gtceu$applyBiomeDecoration()).
The ChunkGeneratorMixin holds a reference to the OrePlacer (not to be confused with OreBlockPlacer) - which is used to place the
+generated veins' blocks into the world, limited to the currently generating chunk.
When trying to generate a chunk, the OrePlacer will query the OreGenCache for a list of veins surrounding the current chunk.
The radius for querying the surrounding area is determined by the oreVeinRandomOffset config option, as well as the largest registered vein size.
+It is therefore automatically compatible with any additional (or changed default) veins registered through either KubeJS, or by an addon.
Of course, the ore gen cache can only hold a limited amount of generated veins at once (see the oreGenerationChunkCacheSize config option).
Because veins may be removed from the cache before all of their chunks are generated, it is extremely important that the ore generation is fully deterministic!
+This ensures that we do not generate ore veins that are either cut off, or have a mismatch in shape or type across chunk borders.
+It also automatically applies across game restarts, keeping continuity even then.
The only situation where ore veins will differ across chunk borders (other than certain internal changes to the generation, of course), is after +the relevant config options have been changed.
+In our case, that means that the RandomSources used for world generation must be completely new for generating each vein, so that its type, shape, offset,
+contents, etc. are not influenced by previous queries to the random generator.
+It is completely and exclusively seeded from the world's seed, as well as the chunk position.
For the random ore vein offset, we also include the vein's world generation layer in the random seed.
+This may need to include an additional component in the future, in case we add support for multiple veins per chunk and worldgen-layer.
Whenever the OreGenCache cannot find a vein for a specific chunk, it will request a list of that chunk's GeneratedVeins from the OreGenerator.
The OreGenerator is responsible for determining a vein's type, its origin (influenced by the oreVeinRandomOffset config option), as well as providing the appropriate
+randomness source to the used implementation of VeinGenerator.
Vein Origin vs Center
+A vein's origin is always the chunk it originates in, regardless of the random offset.
+The actual center of a vein is influenced by the random offset and might not be located at the chunk center - or in the same chunk at all.
Once the relevant VeinGenerator implementation has finished generating the vein's shape, it will be cached per chunk, inside a GeneratedVein.
VeinGenerator and OreBlockPlacerA vein generator is what will generate the actual shape of the vein.
+It should, however, never try to place any blocks directly. Instead, its generate() method will only return a map of OreBlockPlacers by block position, which
+are responsible for actually placing the blocks in the world, as soon as a chunk generates.
+Each OreBlockPlacer should only place either a single block, or no block.
OreBlockPlacersIn certain situations, the process of actually placing the block requires a randomness source (e.g. to determine the chance of its block being placed).
+To keep the ore generation fully deterministic in this case as well, it is recommended to generate a new seed using the supplied RandomSource at the time of
+vein shape generation. This seed should be passed into the OreBlockPlacer returned for the each block position.
Inside the OreBlockPlacer, you can then simply create a new RandomSource using the precomputed seed.
public class MyVeinGenerator {
+ public Map<BlockPos, OreBlockPlacer> generate(WorldGenLevel level, RandomSource random, GTOreDefinition entry, BlockPos origin) {
+ Map<BlockPos, OreBlockPlacer> generatedBlocks = new Object2ObjectOpenHashMap<>();
+
+ for (BlockPos pos : determineShapePositions()) {
+ final var randomSeed = random.nextLong(); // Fully deterministic regardless of chunk generation order
+ generatedBlocks.put(pos, (access, section) -> placeBlock(access, section, randomSeed, pos, entry));
+ }
+
+ return generatedBlocks;
+ }
+
+ private void placeBlock(BulkSectionAccess level, LevelChunkSection section, long randomSeed, BlockPos pos, GTOreDefinition entry) {
+ RandomSource rand = new XoroshiroRandomSource(randomSeed);
+
+ // ...
+ }
+}
+To improve its generality, RecipeLogic has been rewritten in GTCEu Modern to support inputs and outputs other than +EU, items and fluids.
+The new RecipeLogic no longer handles overclocked and parallel logic, but instead delegates it to the
+machine via IRecipeLogicMachine:
/**
+ * Override it to modify recipe on the fly e.g. applying overclock,
+ * change chance, etc
+ *
+ * @param recipe recipe from detected from GTRecipeType
+ * @return modified recipe.
+ * null -- this recipe is unavailable
+ */
+@Nullable
+GTRecipe modifyRecipe(GTRecipe recipe);
+In general, a simple electric overclocking can be done this way. For details, see OverclockingLogic and RecipeHelper
public @Nullable GTRecipe modifyRecipe(GTRecipe recipe) {
+ if (RecipeHelper.getRecipeEUtTier(recipe) > getTier()) {
+ return null;
+ }
+
+ return RecipeHelper.applyOverclock(
+ getDefinition().getOverclockingLogic(),
+ recipe,
+ getMaxVoltage()
+ );
+}
+Parallel is also not complicated to implement. Let's take the generator as an example
public @Nullable GTRecipe modifyRecipe(GTRecipe recipe) {
+ var EUt = RecipeHelper.getOutputEUt(recipe); // get the recipe's EU/t
+
+ if (EUt > 0) {
+ // calculate the max parallel limitation.
+ var maxParallel = (int) (Math.min(
+ energyContainer.getOutputVoltage(),
+ GTValues.V[overclockTier]
+ ) / EUt);
+
+ while (maxParallel > 0) {
+ // copy and apply parallel, it will affect all recipes' contents
+ // and the recipe duration.
+ var copied = recipe.copy(ContentModifier.multiplier(maxParallel));
+
+ // If the machine has enough ingredients, return copied recipe.
+ if (copied.matchRecipe(this)) {
+ copied.duration = copied.duration / maxParallel;
+
+ return copied;
+ }
+
+ // Trying to halve the number of parallelism
+ maxParallel /= 2;
+ }
+ }
+ return null;
+}
+ITickable / update()The client update is always present and you can override the clientTick() method, which works just as well as in 1.12.
But for the sake of performance, our machines are no longer always in a tickable state.
+We introduced ITickSubscription for managed tick logic.
+Understand the basic concept of subscribing to periodic updates when they are needed, and unsubscribe them when
+they are not.
Automatic output of our machine requires periodic output of internal items to an adjacent inventory. +But most of the time this logic doesn't need to be executed if any of the following conditions apply:
+Lets look at how we implement it in QuantumChest.
QuantumChest@Getter @Persisted @DescSynced
+protected boolean autoOutputItems;
+@Persisted @DropSaved
+protected final NotifiableItemStackHandler cache; // inner inventory
+protected TickableSubscription autoOutputSubs;
+protected ISubscription exportItemSubs;
+
+// update subscription, subscribe if tick logic subscription is required, unsubscribe otherwise.
+protected void updateAutoOutputSubscription() {
+ var outputFacing = getOutputFacingItems(); // get output facing
+ if ((isAutoOutputItems() && !cache.isEmpty()) // inner item non empty
+ && outputFacing != null // has output facing
+ && ItemTransferHelper.getItemTransfer(getLevel(), getPos().relative(outputFacing), outputFacing.getOpposite()) != null) { // adjacent block has inventory.
+ autoOutputSubs = subscribeServerTick(autoOutputSubs, this::checkAutoOutput); // subscribe tick logic
+ } else if (autoOutputSubs != null) { // unsubscribe tick logic
+ autoOutputSubs.unsubscribe();
+ autoOutputSubs = null;
+ }
+}
+
+// output to nearby block.
+protected void checkAutoOutput() {
+ if (getOffsetTimer() % 5 == 0) {
+ if (isAutoOutputItems() && getOutputFacingItems() != null) {
+ cache.exportToNearby(getOutputFacingItems());
+ }
+ updateAutoOutputSubscription(); // dont foget to check if it's still available
+ }
+}
+
+@Override
+public void onLoad() {
+ super.onLoad();
+ if (getLevel() instanceof ServerLevel serverLevel) {
+ // you cant call ItemTransferHelper.getItemTransfer while chunk is loading, so lets defer it next tick.
+ serverLevel.getServer().tell(new TickTask(0, this::updateAutoOutputSubscription));
+ }
+ // add a listener to listen the changes of inner inventory. (for ex, if inventory not empty anymore, we may need to unpdate logic)
+ exportItemSubs = cache.addChangedListener(this::updateAutoOutputSubscription);
+}
+
+@Override
+public void onUnload() {
+ super.onUnload(); //autoOutputSubs will be released automatically when machine unload
+ if (exportItemSubs != null) { //we should mannually release it.
+ exportItemSubs.unsubscribe();
+ exportItemSubs = null;
+ }
+}
+
+// For any change may affect the logic to invoke updateAutoOutputSubscription at a time
+@Override
+public void setAutoOutputItems(boolean allow) {
+ this.autoOutputItems = allow;
+ updateAutoOutputSubscription();
+}
+
+@Override
+public void setOutputFacingItems(Direction outputFacing) {
+ this.outputFacingItems = outputFacing;
+ updateAutoOutputSubscription();
+}
+
+@Override
+public void onNeighborChanged(Block block, BlockPos fromPos, boolean isMoving) {
+ super.onNeighborChanged(block, fromPos, isMoving);
+ updateAutoOutputSubscription();
+}
+I know the code is a kinda long, but it's for performance, and thanks to the SyncData system, we've eliminated a lot of +synchronization code, so please sacrifice a little for better performance.
+ConditionalSubscriptionHandlerFor ease of use in some situations, it is possible to eliminate some of the boilerplate code and delegate management of
+your subscription to a ConditionalSubscriptionHandler instead.
Using that class, it is possible to simply provide an update method to run every tick while the subscription is active,
+as well as a Supplier<Boolean> that determines whether it is active.
Whenever the input of its condition changes, you need to call updateSubscription() on the handler, so that it can
+re-evaluate it and take the necessary steps if it has changed.
+You should also to call this method after executing your tick logic in most cases, to ensure the subscription doesn't
+stay active any longer than it needs to.
ConditionalSubscriptionHandlerclass MyMachine extends MetaMachine implements IControllable {
+ @Persisted @Getter
+ private boolean workingEnabled = true;
+
+ private final ConditionalSubscriptionHandler subscriptionHandler;
+
+ public MyMachine() {
+ super(/* ... */);
+
+ this.subscriptionHandler = new ConditionalSubscriptionHandler(
+ this, this::update, this::isSubscriptionActive
+ );
+ }
+
+ private void update() {
+ // Only run once every second
+ if (getOffsetTimer() % 20 != 0)
+ return;
+
+ // ...
+
+ // Now that the update logic has been executed, update the subscription.
+ // This will internally check if the subscription is still active and
+ // unsubscribe otherwise.
+ subscriptionHandler.updateSubscription();
+ }
+
+ private boolean isSubscriptionActive() {
+ return isWorkingEnabled();
+ }
+
+ @Override
+ public void setWorkingEnabled(boolean workingEnabled) {
+ this.workingEnabled = workingEnabled;
+
+ // Whether the subscription is currently active depends on whether working
+ // is enabled for this machine. As soon as any of the condition inputs changes,
+ // you need to update the subscription.
+ subscriptionHandler.updateSubscription();
+ }
+
+ @Override
+ public void onLoad() {
+ super.onLoad();
+
+ // As soon as you can get a reference to the dimension/level you're in,
+ // you need to initialize your subscription handler.
+ subscriptionHandler.initialize(getLevel());
+ }
+}
+Info
+This is an overview of technical terms that are commonly used in this documentation.
+If you're not sure what something means (or how it applies to the current context), please refer to this page.
The part of the game running on a player's computer.
+It always hosts the Remote Side.
+In singleplayer mode, the Server Side is hosted on the client as well. In multiplayer mode, the client
+connects to a dedicated server instead.
See also: Server Side
+The remote side is the part of the game that is connected to the game's server side.
+It always runs on the client.
This side may not have the same amount of data available to it as the server does (see SyncData if you
+need to automatically synchronize certain data to the remote side).
+It also does not perform any tick update logic.
See also: Remote Side
+The server side is what one or more players connect to.
+In singleplayer mode, it runs on the client. In multiplayer mode, it runs on a dedicated server.
This side usually has all of the world's data available to it and runs tick update logic.
+This is therefore, where TPS impact becomes relevant. In general, use
Short for "ticks per second". Should stay at exactly 20.
+See Tick Updates and Optimization for techniques +on how to reduce performance impact.
+ + + + + + + + + + + + + + + + +@DescSynced@Persisted@RequireRerender@UpdateListenerFor serializing and synchronizing fields, LDLib's annotation-based SyncData system is used.
+Please also refer to the LDLib Wiki.
+Here is an overview of the most important annotations:
+public class MyMachine {
+ @Persisted // (1)
+ private String myPersistedField;
+
+ @DescSynced // (2)
+ private String myClientsideRelevantField;
+
+ @DescSynced @RequireRerender // (3)
+ private IO io;
+
+ @DescSynced @UpdateListener(methodName = "runAdditionalUpdate") // (4)
+ private int fieldWithAdditionalClientUpdateLogic;
+
+
+ private void runAdditionalUpdate(int newValue, int oldValue) {
+ // Run additional clientside update code here
+ }
+}
+This field is automatically serialized to and deserialized from NBT data, that will be stored with its container.
+ By default, @Persisted only applies on the server side.
For fields that need to be available on the client (or more specifically, remote) side, you can annotate them with
+ @DescSynced to make them available there as well.
+ Any changes made to the field on the server side will automatically be synchronized to the client side.
If a change of a synced field's value requires rerendering the containing block (e.g. for different overlays based
+ on a cover's IO direction), simply add the @RequireRerender annotation to it.
+ Its renderer's code will then be called again every time the field changes.
In some cases, a field may require some additional code to run on the client/remote side when it has been synced.
+ The @UpdateListener annotation allows you to define a method to be called in that case.
For serializing and synchronizing fields, LDLib's annotation-based SyncData system is used.
+Using this system, almost all boilerplate code regarding these topics can be omitted.
For more info on the SyncData annotations, please refer to the following chapters, as well as to the +LDLib Wiki.
+ + + + + + + + + + + + + + + + +If you want to contribute to the development of GTCEu Modern, please feel free to submit a +pull request with your changes.
+The following pages describe a few important concepts that you will likely run into when working with our codebase.
+LDLib Docs
+ +This mod is based on the LDLib library for a lot of comminly used functionalities.
+Please refer to its documentation as well.
Architectury Gradle Plugin
+Architectury-Wiki Gradle Plugin
+This mod is using Architectury's build system, for compatibiliy across multiple moding platforms.
+This is an overview of GTCEu's ore veins and the ore types they contain.
+Please note that these are the default settings and may be different in certain modpacks.
Height range: 10 to 80
+Height range: 10 to 80
+Height range: 10 to 140
+Height range: -10 to 160
+Height range: -15 to 45
+Height range: 30 to 60
+Height range: -10 to 60
+Height range: 0 to 50
+Height range: 10 to 60
+Height range: 15 to 60
+Height range: -10 to 60
+Height range: 30 to 70
+Height range: 30 to 80
+ +Height range: -40 to 10
+Height range: -65 to -30
+Height range: -60 to 10
+Height range: -30 to 0
+Height range: -40 to -10
+Height range: -20 to 10
+Height range: -65 to -10
+Height range: -40 to 0
+Height range: 20 to 40
+Height range: 5 to 30
+Height range: 80 to 120
+Height range: 20 to 30
+Height range: 20 to 50
+Height range: 20 to 40
+Height range: 40 to 80
+Height range: 5 to 40
+Height range: 5 to 45
+Height range: 10 to 30
+Height range: 80 to 120
+Height range: 80 to 120
+Height range: 10 to 80
+Height range: 20 to 80
+Height range: 10 to 90
+Height range: 30 to 60
+Height range: 20 to 60
+Height range: 5 to 50
+ + + + + + + + + + + + + + + + +Bronze is the most important material in the Steam Age.
+To prepare the first batch of it you will need Tin and Copper just crush the ingots with a GT mortar. And then mix them in a crafting table in 3 to 1 proportion. Then smelting to receive the ingot.
+
+
For early game steam generation you have two options:
+For water you can use a primitive pump
+
or use a water connection from any other mod.
+After unlocking steel (using a primitive blast furnace) you will get access to the high pressure versions of the boilers and allow you to produce more steam.
+Large boilers allow you to create massive amount of steam in the blink of an eye. A boiler can be constructed of many different GT materials, that will allow for different steam generation rates (consult the table below).
+| Boiler type | +Low pressure | +High pressure | +
|---|---|---|
| Solar | +6 L/T | +18 L/T | +
| Liquid | +12 L/T | +30 L/T | +
| Solid | +6 L/T | +15 L/T | +
| Boiler | +Generation | +Boil up | +Max temp | +
|---|---|---|---|
| Bronze | +800 L/T | +40s | +1074K | +
| Steel | +1800 L/T | +90s | +2074K | +
| Titanium | +3200 L/T | +160s | +3474K | +
| Tungstensteel | +6400 L/T | +160s | +6674K | +
*L/T -> Liters per tick (1L = 1mB)
+ + + + + + + + + + + + + + + + +