CustomItemLibrary - Custom items without client-side mods
CustomItemLibrary is a library for Sponge plugins, which makes the creation of fake custom blocks and items easy. It generates a resourcepack to be used on your server. If you are not a plugin developer and you need this library for the plugins you use to work, just download it below and install it like you would install any other plugin. This library alone does not provide any gameplay features.
Preview
A custom material being placed, creating a custom block on the ground as a result.
Downloads
Latest
Old
About
Commands and Permissions
-
/cil- Required permission:
customitemlibrary.command.customitemlibrary - Lists available subcommands
- Required permission:
-
/cil give <Player> <Item ID> [Quantity]- Required permission:
customitemlibrary.command.customitemlibrary.give - Gives the target player the specified custom item
- Required permission:
-
/cil setBlock <Block ID>- Required permission:
customitemlibrary.command.customitemlibrary.setblock - Changes the block you are looking at to the specified custom block
- Required permission:
-
/cil resourcepack- Required permission:
customitemlibrary.command.customitemlibrary.resourcepack - Generates the resourcepack for the players to use; it is located at
config/customitemlibrary/resourcepack
- Required permission:
Integration
In your @Plugin annotation, add a dependency to this library. For example:
@Plugin(
id = "limefun",
name = "LimeFun",
description = "Bring things from mods to a server without mods!",
authors = {
"Limeth"
},
// This is what you should add:
dependencies = {
// Require version 0.2.3 of CustomItemLibrary or newer
@Dependency(id = "customitemlibrary", version = "[0.2.3,)")
}
)
Next, add the dependency to your build.gradle:
repositories {
// ...
maven {
name = 'jitpack'
url = 'https://jitpack.io'
}
}
dependencies {
// ...
compile 'com.github.Limeth:CustomItemLibrary:v0.2.3'
}
You should now be able to access the CustomItemLibrary classes in your code. In order to get the API class, do the following:
CustomItemService service = Sponge.getServiceManager().provide(CustomItemService.class)
.orElseThrow(() -> new IllegalStateException("Could not access the CustomItemLibrary service."));
Classes extending CustomFeatureDefinition are like ItemTypes or BlockTypes. They define the behavior, but they themselves don’t do anything. CustomFeatures, on the other hand, are classes that wrap around a DataHolder and a CustomFeatureDefinition in order to pair them together and make manipulation easier.
Definitions may be registered after the GamePostInitializationEvent with Order#AFTER_PRE was called.
Custom features may be created and used after the GameLoadCompleteEvent with Order#DEFAULT was called.
I highly recommend reading the javadocs of CustomItemService.java and all of the CustomFeatureDefinition builders in CustomFeatureDefinition.java.
Feature overview
-
CustomTool- Builder:
CustomFeatureDefinition#itemToolBuilder() - The
itemStackSnapshotmust be an item with durability - The tool does not lose the abilities the
itemStackSnapshothas; for example, a custom tool withitemStackSnapshotasItemTypes.SHEARS#getTemplate()will still be able to harvest cobwebs and leaves - Not stackable
- Item models at
assets/%PLUGIN_ID%/models/tools/%MODEL%.json
- Builder:
-
CustomMaterial- Builder:
CustomFeatureDefinition#itemMaterialBuilder() - The type of
itemStackSnapshotmust beItemTypes#SKULL - Stackable
- Item textures at
assets/%PLUGIN_ID%/textures/materials/%MODEL%.png; a 64x64 skin, or 64x16 with just the head part - Places the
CustomBlockwith the sametypeId, by default
- Builder:
-
CustomBlock- Builder:
CustomFeatureDefinition#simpleBlockBuilder() - Represented as a barrier block with an invisible armor stand equipped with an item with the model
- Custom blocks are not opaque (light shines through them)
- Minecraft cannot optimize rendering for these custom blocks, so it is highly recommended, that you only create custom blocks which would be placed sparingly – do not define blocks which are intended for building only.
- Block models at
assets/%PLUGIN_ID%/models/blocks/%MODEL%.json - When broken, by default drops the
CustomMaterialwith the sametypeId
- Builder:
Example: Creating custom tools
public static CustomToolDefinition magicWandDefinition;
@Listener
public void onGamePostInitializationDefault(GamePostInitializationEvent event) {
// During this phase, plugins using this library should register their custom item definitions.
service.register(
magicWandDefinition = CustomFeatureDefinition.itemToolBuilder()
// Required fields:
.plugin(plugin) // The owner plugin
.typeId("magic_wand") // The definition id
.itemStackSnapshot(ItemTypes.SHEARS.getTemplate()) // Used to build magic wands
.defaultModel("magic_wand_primary") // Models are located at `assets/%PLUGIN_ID%/models/tools/%MODEL%.json` in the JAR
// Optional fields:
.additionalModel("magic_wand_secondary")
.additionalAsset("textures/tools/magic_wand_texture.png")
.build()
);
}
@Listener
public void onInteractBlock(InteractBlockEvent.Secondary.MainHand event, @Root Player player) {
CustomTool magicWand = magicWandDefinition.createItem(event.getCause());
ItemStack magicWandItemStack = magicWand.getDataHolder();
// Give the player a magic wand when they right-click a block
player.setItemInHand(HandTypes.MAIN_HAND, magicWandItemStack);
}
@Listener
public void onInteractItem(InteractItemEvent.Primary.MainHand event, @Root Player player) {
player.getItemInHand(HandTypes.MAIN_HAND).flatMap(service::getItem)
// Run the following code block if the player is holding a custom item
.ifPresent(customItem -> {
CustomItemDefinition definition = customItem.getDefinition();
// Do not continue unless the player is holding a magic wand
if(definition != magicWandDefinition)
return;
CustomTool magicWand = (CustomTool) customItem;
// Change the model and update the inventory
magicWand.setModel("magic_wand_secondary");
player.setItemInHand(HandTypes.MAIN_HAND, magicWand.getDataHolder());
});
}
Example plugin
For a full example, check out the sources of the LimeFun plugin.
Support
If you have any suggestions or problems you came across, or just want to ask about something regarding this plugin, feel free to do so here, or if I’m online, feel free to message me on the Sponge IRC. I’ll be happy to help.
