Repository navigation
Registration
Cobweb simplifies the process of registering custom game objects by allowing you to register them directly in the common module, eliminating the need to register them separately in each of your mod loader submodules.
Create a CobwebRegister for a registry and your mod's namespace, then declare its entries during mod initialization. Cobweb attaches NeoForge registers to its native registration events; you do not register them on an event bus yourself.
The compile-time API is shared. Runtime timing is native:
| Operation | Fabric | NeoForge |
|---|---|---|
| Entry factories | Run immediately when registering. | Run during the native registration event. |
| Entry handles | Already bound after registration. | Available before their values are bound. |
| Aliases | Applied immediately, with native conflict/write checks. | Queued, then applied before entries at registration. |
| Custom registry creation | Created and installed immediately. | Created immediately by its owner and installed at the new-registry event. |
import it.crystalnest.cobweb.api.registry.CobwebEntry;
import it.crystalnest.cobweb.api.registry.CobwebRegister;
import it.crystalnest.cobweb.api.registry.CobwebRegistry;
import net.minecraft.world.item.BlockItem;
import net.minecraft.world.item.Item;
import net.minecraft.world.level.block.Block;
public final class ModContent {
private static final CobwebRegister.Items ITEMS =
CobwebRegistry.ofItems("example");
private static final CobwebRegister.Blocks BLOCKS =
CobwebRegistry.ofBlocks("example");
public static final CobwebEntry<Item> COIN =
ITEMS.registerSimpleItem("coin", properties -> properties.stacksTo(16));
public static final CobwebEntry<Block> PEDESTAL =
BLOCKS.registerSimpleBlock("pedestal", properties -> properties.strength(2.0F));
public static final CobwebEntry<BlockItem> PEDESTAL_ITEM =
ITEMS.registerBlockItem(PEDESTAL);
private ModContent() {}
public static void register() {
// Calling this loads the class and declares its entries.
}
}Call ModContent.register() from your mod's initialization code on both loaders. Declare blocks before their block items. Keep value access lazy rather than calling .get() in a static initializer: a NeoForge handle may not yet be bound.
Use registerItem(name, MyItem::new) or registerBlock(name, MyBlock::new) for subclasses whose constructors accept properties. Both support property suppliers and transformations:
CobwebRegister.Items items = CobwebRegistry.ofItems("example");
CobwebEntry<Item> supplied = items.registerItem(
"supplied", Item::new, () -> new Item.Properties().stacksTo(1)
);
CobwebEntry<Item> transformed = items.registerItem(
"transformed", Item::new, properties -> properties.stacksTo(16)
);Suppliers run at native registration time and must return independent mutable properties. Transformations receive fresh defaults and may return replacement properties. Cobweb sets the registration ID after customization.
registerBlockItem(name, blockSupplier, propertiesSupplierOrTransformation) supports lazy properties. For a custom BlockItem constructor:
CobwebEntry<BlockItem> alternate = items.registerBlockItemLike(
"alternate_pedestal", ModContent.PEDESTAL, BlockItem::new,
properties -> properties.stacksTo(16)
);The holder shortcut registerBlockItem(holder) uses the holder key's path and the item register's namespace, even for a block from another namespace. The holder must be keyed; its value is resolved at native registration time. Block-item helpers retain block description prefixes.
Simple helpers do not create models, translations, recipes, creative-tab entries or an automatic block item.
Use CobwebRegistry.of(registryKey, namespace) or of(registry, namespace) when no specialized factory exists. register(name, supplier) accepts a native value factory. register(name, identifier -> value) supplies the full entry identifier without eagerly resolving other entries.
Use CobwebRegistry.of(Registries.MOB_EFFECT, MOD_ID) for mob effects.
ofEntityTypes returns CobwebRegister.Entities. The helper builds a vanilla entity type with its registration key:
CobwebRegister.Entities entities = CobwebRegistry.ofEntityTypes("example");
CobwebEntry<EntityType<Pig>> pet = entities.registerEntityType(
"pet", Pig::new, MobCategory.CREATURE,
builder -> builder.sized(0.9F, 0.9F)
);The builder transformation is optional. Attributes, spawn rules, rendering and other entity setup remain separate responsibilities.
CobwebRegister.DataComponents components =
CobwebRegistry.ofDataComponents("example");
CobwebEntry<DataComponentType<Integer>> charge =
components.registerComponentType(
"charge", builder -> builder.persistent(Codec.INT)
);Supply a stream codec or a persistent codec from which vanilla can derive one. Native builder validation is retained.
An explicit registry key selects another component-type registry:
CobwebRegister.DataComponents effects = CobwebRegistry.ofDataComponents(
Registries.ENCHANTMENT_EFFECT_COMPONENT_TYPE, "example"
);
CobwebEntry<DataComponentType<Integer>> power =
effects.registerComponentType("power", builder -> builder.persistent(Codec.INT));This registers a component type; it does not implement a gameplay effect. The same factory accepts a Java-created custom Registry<DataComponentType<?>>. Generic access and specialized access share registrations. For custom keys, the specialized object can be a cached view rather than the same Java object; its native registry and entry collection are shared.
Use ofPotions to build potions from fresh effect instances at registration time. By default the potion uses its entry path as the translation suffix. Pass an explicit suffix to share a name across variants.
var potions = CobwebRegistry.ofPotions("example");
var frost = potions.registerPotion("frost", () -> new MobEffectInstance[] {
new MobEffectInstance(FROST_EFFECT, 600)
});
var longFrost = potions.registerPotion("long_frost", "frost", () -> new MobEffectInstance[] {
new MobEffectInstance(FROST_EFFECT, 1200)
});Use ofCreativeModeTabs to configure a tab through the native CreativeModeTab.Builder on either loader. The default translation key is itemGroup.<namespace>.<path>. Set a title on the builder to override it.
var tabs = CobwebRegistry.ofCreativeModeTabs("example");
var tools = tabs.registerTab("tools", builder -> builder
.icon(() -> new ItemStack(HAMMER.get()))
.displayItems((params, output) -> {
output.accept(HAMMER.get());
output.accept(WRENCH.get());
}));
var materials = tabs.registerTab("materials", builder -> builder
.title(Component.translatable("example.tabs.crafting_materials"))
.icon(() -> new ItemStack(COPPER_GEAR.get()))
.displayItems((params, output) -> output.accept(COPPER_GEAR.get())));CobwebRegister.Items items = CobwebRegistry.ofItems("example");
ResourceKey<? extends Registry<Item>> registryKey = items.registryKey();
TagKey<Item> coins = items.createTagKey("coins");
TagKey<Item> sharedCoins = items.createTagKey(
Identifier.fromNamespaceAndPath("c", "coins")
);
Collection<CobwebEntry<? extends Item>> declarations = items.entries();Tag helpers create keys only. Supply tag contents through resources or the available tag-generation API.
entries() is an unmodifiable live view in declaration order. It includes NeoForge's unbound handles, excludes aliases and does not scan entries declared by other mods. namespace() and registryKey() do not resolve entry values.
A CobwebEntry<T> is a native-backed Holder.Reference<T> and a Supplier<T>. Pass it where a holder or supplier is expected, or call get() when native registration has completed. Key inspection does not require the entry value to be bound.
Binding, equality, hashing, tags, components and registry-codec behavior follow the underlying loader. NeoForge entries also delegate its native holder extensions and data maps. Do not construct entry wrappers yourself; obtain them from the register.
Compare holders with .equals(...), not ==.
CobwebRegister.Items items = CobwebRegistry.ofItems("example");
CobwebEntry<Item> wand = items.registerSimpleItem("wand");
items.addAlias("old_wand", "wand");
items.addAlias(
Identifier.fromNamespaceAndPath("old_example", "wand"),
Identifier.fromNamespaceAndPath("example", "wand")
);The string overload places both paths in the register's namespace. Full identifiers allow cross-namespace aliases. Old identifiers resolve to the target; its canonical identifier remains unchanged. Registry codecs decode an alias and encode the canonical identifier.
Declare the target before its aliases. Fabric warns if the target is missing and rejects duplicate aliases, registered sources, cycles and writes after freeze. NeoForge queues aliases, overwriting repeated declarations in its native alias map, and rejects declarations after its registration event. Cobweb does not normalize these differences.
Create a registry once, then let other namespaces contribute through of. Registry ownership is separate from an entry namespace.
import it.crystalnest.cobweb.api.registry.CobwebEntry;
import it.crystalnest.cobweb.api.registry.CobwebRegister;
import it.crystalnest.cobweb.api.registry.CobwebRegistry;
import net.minecraft.core.Registry;
import net.minecraft.resources.Identifier;
import net.minecraft.resources.ResourceKey;
public final class SpellRegistry {
public record Spell(Identifier id, int manaCost) {}
public static final ResourceKey<Registry<Spell>> KEY =
ResourceKey.createRegistryKey(id("spell"));
public static final CobwebRegister<Spell> SPELLS = CobwebRegistry.create(
KEY, "example",
new CobwebRegistry.Settings().sync(true).defaultKey(id("none"))
);
public static final CobwebEntry<Spell> NONE =
SPELLS.register("none", entryId -> new Spell(entryId, 0));
public static final CobwebEntry<Spell> FIREBALL =
SPELLS.register("fireball", entryId -> new Spell(entryId, 20));
private SpellRegistry() {}
private static Identifier id(String path) {
return Identifier.fromNamespaceAndPath("example", path);
}
public static void register() {}
}Call SpellRegistry.register() during mod initialization. Settings is immutable; each fluent call returns new settings. The overload without settings creates unsynced IDs without a fallback. A configured fallback entry must still be registered. Synchronization distributes native numeric registry IDs, not arbitrary entry definitions or Java behavior.
Another mod, initialized after the registry owner, can contribute:
CobwebRegister<SpellRegistry.Spell> addonSpells =
CobwebRegistry.of(SpellRegistry.KEY, "spell_addon");
CobwebEntry<SpellRegistry.Spell> frostbolt = addonSpells.register(
"frostbolt", entryId -> new SpellRegistry.Spell(entryId, 15)
);Creating the same registry twice fails, including attempts from different namespaces. Creation must precede Fabric's registry freeze or NeoForge's new-registry event. This API creates Java-populated static registries; it does not declare world-loaded or reloadable data-pack registries.
// Perform entry lookups after native registration has completed.
Registry<SpellRegistry.Spell> registry = SpellRegistry.SPELLS.registry();
SpellRegistry.Spell fireball = registry.getValue(
Identifier.fromNamespaceAndPath("example", "fireball")
);registry() exposes the full native static registry, including other namespaces. It differs from entries(), which tracks only that register's declarations.
The creating NeoForge register has its registry immediately; other registers throw IllegalStateException until the registry is installed. An available registry does not imply all entries have bound. Fabric resolves a static registry when obtaining its register. World-loaded registries must be obtained from the relevant world's registry access instead.
Declare a data-pack registry during mod initialization by supplying its native registry key and entry codec. Each declaration returns a CobwebDataPackRegistry<T> describing the registry and its lifetime.
ResourceKey<Registry<Integer>> SPELL_POWER =
ResourceKey.createRegistryKey(Identifier.parse("example:spell_power"));
ResourceKey<Registry<Integer>> MAGIC_RULE =
ResourceKey.createRegistryKey(Identifier.parse("example:magic_rule"));
var spellPower = CobwebRegistry.createWorldRegistry(SPELL_POWER, Codec.INT);
var magicRules = CobwebRegistry.createReloadableRegistry(MAGIC_RULE, Codec.INT);createWorldRegistry declares a registry whose entries Minecraft decodes during world loading. Reopen the world to apply changes to those entries. Choose one of these declarations:
CobwebRegistry.createWorldRegistry(KEY, CODEC); // No entry synchronization to clients.
CobwebRegistry.createWorldRegistry(KEY, CODEC, CODEC); // Synchronize using the same codec.
CobwebRegistry.createWorldRegistry(KEY, DATA_CODEC, NETWORK_CODEC); // Synchronize using a separate codec.Supplying a non-null network codec enables synchronization and requires compatible registry support on clients. A separate network codec can omit fields unnecessary to clients. It encodes on the server and decodes on clients, so it must not depend on client-only classes. It must also accept the complete data-pack JSON: Minecraft can read an entry from a matching known pack on the client instead of receiving its data from the server.
createReloadableRegistry declares a registry whose entries Minecraft decodes when the server loads its resources and on /reload. The entries stay server-side. Read live values through the active world's registry access or the server's reloadable registry lookup, respectively. A declaration handle stores the key and codec.
For the example above, place a JSON integer such as 5 in data/example/example/spell_power/fireball.json to supply the entry example:fireball. The first example is the entry namespace. The second is the namespace of the registry key. These files can come from mod resources, an external data pack, or bundled files and generation callbacks in a Cobweb data pack.
Use the same CobwebRegistry, CobwebRegister and CobwebEntry API in Fabric-only, NeoForge-only and multiloader projects. The loader module provides the native implementation; a single-loader project does not need a separate common Gradle module.
The Fabric-only RegisterProvider and Register API has been removed in v2.0.0. Replace provider.of(registry) with CobwebRegistry.of(registry, modId) and apply(name, value) with register(name, supplier). Registration returns a CobwebEntry; resolve its value only when the native loader has completed registration.
If you have any suggestions or questions about this wiki, please open an issue following the Documentation enhancement template.