Skip to content

2.9 MetaTileEntity Changes

Jump to bottom
TechLord22 edited this page Sep 8, 2024 · 3 revisions

With GTCEu version 2.9, breaking changes have been made to MetaTileEntity registration. This document explains the steps necessary to resolving these changes without causing harm to user data.

Creating a Registry

Projects creating their own MetaTileEntity objects now require their own registry to store them. This is done by listening to the Event in CommonProxy or equivalent:

@SubscribeEvent
public static void registerMTERegistry(MTEManager.MTERegistryEvent event) {
    GregTechAPI.mteManager.createRegistry(MODID);
}

MTE Registration

MTEs should be using ResourceLocations of the appropriate modid. Do not use any modid other than your own.

DataFixers

Each mod will now have their own MTE block, and MetaBlocks.MACHINE no longer exists. The block is now per-registry.

As a result of this change, all existing in-world MTEs would normally become invalid as their blocks do not exist, however GT now provides DataFixers to resolve this.

DataFixers are applied by Forge and MC at world load time, and not sooner. Use of old existing MTE data before the world containing that data is migrated is not advised and will not be automatically migrated.

Direct MetaData ID Mapping Migration

At any point before FMLLoadCompleteEvent, do the following to utilize GTCEu's migrations to directly port MTEs and preserve metadata:

public void preInit(FMLPreInitializationEvent event) {
    MTERegistriesMigrator migrator = GregTechAPI.MIGRATIONS.registriesMigrator();
    migrator.migrate(MODID, OLD_OWNED_META_1);
    migrator.migrate(MODID, OLD_OWNED_META_2);
    migrator.migrate(MODID, IntStream.range(ID_RANGE_START, ID_RANGE_END));
}

This will migrate MTE integer metadata IDs to the new appropriate block for your modid. If you previously had an MTE with a metadata id of 1234 when registering to the GT registry, you will now have your MTE registered with id 1234 to your own new registry.

Tip

Mods are strongly encouraged to use the method utilizing an IntStream in conjunction with IntStream.range and IntStream.builder in order to vastly simplify this association process. Most projects already have their own soft-reserved ID ranges, so it should be simple to register the required associations.

MetaData Reassignment Migration

This alternative migration allows you to re-assign old metadata IDs to new ones.

If you previously had an MTE with a metadata id of 1234 when registering to the GT registry, you will now have your MTE registered with any integer id of your choosing to your own registry. You may also rename MTE registry names, as well as modify their NBT tags.

At any point before FMLLoadCompleteEvent, do the following to use this form of migration:

public void preInit(FMLPreInitializationEvent event) {
    final CompoundDataFixer forgeFixer = FMLCommonHandler.instance().getDataFixer();
    // see GTDataVersion
    ModFixs fixer = forgeFixer.init(MODID, YourDataVersion.currentVersion().ordinal());
    MTEDataMigrator migrator = new MTEDataMigrator(fixer, YourDataVersion.VERSION_X.ordinal());

    // examples
    migrator.migrateMTEMeta(MODID, originalMeta, newMeta);
    migrator.migrateMTEName(originalRegistryName, newRegistryName);
    migrator.migrateMTEData(originalRegistryName, tag -> {});
}

Important

You can only apply one round of migrations per data version. If additional migrations are needed, create a new MTEDataMigrator with the new version and perform new migrations within it. Leave old migrations intact when adding old ones, they will be applied sequentially from oldest to newest.

Caution

Only one of the above migration APIs can be used for a given metadata value. Do not apply both kinds of migration to the same value. This may result in unexpected behavior and may cause user data loss.

GroovyScript

Modpacks using GroovyScript to create MTEs do not need to perform any immediate action.

When creating an MTE using GroovyScript, use the packId field in runConfig.json as your modid when creating metaTileEntityId ResourceLocations.

GroovyScript has an MTE registry automatically created for it using packId as the modid.

GTCEu will automatically perform a Direct Metadata Mapping Migration for MTEs using metadata ids 32000 and higher.

In short: item('gregtech:machine', 32000) is now item('packid:mte', 32000).

Note

This means that GroovyScript cannot utilize MetaData Reassignment Migration for the initial migration from gregtech:machine to packid:mte for metadata values greater than or equal to 32000. Additional migrations starting from packid:mte as a basis are able to utilize it however.

Adding additional migrations in GroovyScript should be done during the preInit script loading phase. DataFixers are applied at world load time, and they cannot be reloaded.

BetterQuesting Unofficial

Questbooks for BQu can be migrated by a modpack developer using a /gt command in-game.

Important

Only the new quest save format is supported. Questbooks with the Legacy Format, or saved with /bq_admin <name> saveLegacy will not be migrated. Migrate to the new BQu format first, and then update to GTCEu 2.9.X and perform the BQu Questbook migration afterwards.

Note

TODO

Clone this wiki locally