Hardcore Ender Expansion - IMC/API documentation
HEE 1.8 moved from API to an IMC system. IMC is a messaging system between mods, but aside from allowing other mods to easily control HEE, there is also a configuration option that lets users and modpack makers declare and run IMC messages without the need of another mod.
Each message consists of a key and the contents. You can find all available messages in the IMC sections. Each message has a specific syntax, when you click on an element marked with purple color, a popup with the explanation and examples will appear.
Click a button to show the contents. You can also use your browser"s history to return back to previous pages.
The basics
Implementing IMC using HEE configuration
The configuration file can be found in .minecraft/config/HardcoreEnderExpansion.cfg. Make sure to run the latest version of the mod at least once to generate the file.
Find the line that says S:IMC, right below it there is Write your message here. You can change replace the test message with your own IMC message. To add a new one, simply press Enter and type the next message below (make sure the new message is indented the same way as the guide message).
Each message follows this simple formatting (one space after the message key):
<message-key> <message-contents>
The message contents is always a JSON formatted text, which is also often used in Command Blocks. There is a difference though, HEE uses the original JSON format and requires properties to be surrounded by quotes. Don't worry if it sounds confusing, there will be plenty of examples.
Each message in this documentation also has a Run event, you can safely ignore these as they are only useful when using another mod to send the messages.
Implementing IMC in your own mod
There are 2 events in which IMC messages are handled in HEE: PostInit and LoadComplete.
Ideally you want to send messages in PreInit or Init, so the mod can register these changes in time - that primarily applies to block and item manipulation, where your changes will be registered in the Ender Compendium.
However it is not always possible to send messages at those points, so you can send some messages in PostInit and those will be handled in LoadComplete event.
Each message says whether it runs in PostInit or LoadComplete. Received messages will be categorized automatically, however you need to make sure not to send messages too late - if a message is expected to be present in PostInit and you send it later, that message will be marked as an error.
Example usage:
@EventHandler
public void onInit(FMLInitializationEvent event){
\tString hee = "HardcoreEnderExpansion";
\tif (Loader.isModLoaded(hee)){
\t\tFMLInterModComms.sendMessage(hee, "<message-key>", <message-contents>);
\t}
}
The message contents will in HEE always be an NBTTagCompound. You can also use a JSON formatted String which HEE will convert into NBT, since that is how IMC messages in the configuration file are constructed.
Finding errors
For security and debugging reasons, the mod logs every command into the FML log, which you can find in .minecraft/logs/fml-client-latest.log. Every entry is marked with [HEE-IMC] prefix and followed by a status message, those are explained in another section. Keep in mind that the messages can be scattered in multiple places in the log.
Each entry gives you output about the action, for example the amount of removed items. If an entry is correct but the action appears to have failed (0 items removed), it will generate a warning.
Status messages
Each message in the log is marked with a status.
[STATE] | HEE begins handling IMC messages (may appear more than 2 times). |
---|---|
[RUN] | Running an IMC message (mod, key and content). Followed by one of the status messages below. |
[ERROR] | Error parsing the IMC message. |
[OK] | Message was handled. |
[WARN] | Message was handled, but did not have an effect. |
[FAIL] | Message was not handled, usually because of a conflict. |
Using JSON
In case you have never heard of JSON or just want to refresh your memory, here is how you use the format:
Basic object:
{ "name": "my text" }
This is a very simple object that has one property called name, which contains value my text. Properties and text values need to be surrounded with quotation marks, as showed in the example.
More properties and value types:
{ "integer": 160, "decimal": 15.6, "boolean": true }
Here we have an integer, a decimal number and a boolean (true or false).
Array of values:
{ "numbers": [ 10, 15, 20, 25 ] }
Square brackets are used to specify an array of values.
Nested objects:
{ "main": { "property1": 1, "property2": 2 } }
A property can also hold an entire object of nested properties and values.
Formatter
Since the JSON object has to fit on one line, I made a formatter (and validator) where you can write the JSON object on multiple lines and then compress it. The results might vary based on your browser.
Data types
Here is a list of available data types. Don't forget that when you click a message syntax element (these are marked by purple text), you will see the explanation and examples in a popup.
Object parameters that have a default value can be omitted.
<String>
Text (with quotes around).
<Boolean>
Either true or false (no quotes).
<Integer>
Whole number (integer).
<IntegerPos>
Positive integer (no zero).
<IntegerPos0>
Positive integer or zero.
<IntegerRange>
Whole number in the specified range.
<Decimal>
Number with decimal point. 2 decimal places suggested.
<DecimalPos0>
Number with decimal point, equal to or bigger than zero. 2 decimal places suggested.
<Array (Type)>
An array of values of specified type.
Examples:
[ 1, 2, 3 ]
[ "A", "B", "C" ]
<Nbt>
NBT Compound Tag (JSON object). You can find information about NBT and how it is used in Minecraft on Minecraft Wiki.
Examples:
{ "CustomPotionEffects": [ { "Id": 1, "Amplifier": 0, "Duration": 180 }, { "Id": 6, "Amplifier": 1, "Duration": 600 } ] }
<ItemStack>
Basic item stack of any size. Press F3+H in game to display item IDs and damage.
{ "id": <String>, "damage": <IntegerRange (0-32767)>, "count": <IntegerRange (1-64)>, "tag": <Nbt> }
id minecraft: prefix can be omitted
~hee: prefix can be used as an abbreviation for HEE items
damage defaults to 0
count defaults to 1
tag defaults to an empty object
Examples:
{ "id": "ender_pearl" }
{ "id": "~hee:ghost_amulet", "damage": 1 }
{ "id": "~hee:enhanced_ender_pearl", "count": 16, "tag": { "HEE_enhancements": [ "EXPLOSIVE", "FREEZE" ] } }
<ItemDamagePair>
Simplified ItemStack that only handles the id and damage.
{ "id": <String>, "damage": <Integer> }
id see ItemStack definition of id
damage defaults to -1 (any negative value will be counted as wildcard and will accept any damage value)
Examples:
{ "id": "ender_pearl" }
{ "id": "~hee:ghost_amulet", "damage": 1 }
<WeightedItem>
ItemStack that generates in dungeon loot. Each ItemStack has a specified weight, the higher the weight the higher the chance of spawning. Weight of all items in the loot set is considered.
{ "id": <String>, "damage": <Array (IntegerRange (0-32767))>, "count": <Array (IntegerRange (1-64))>, "weight": <IntegerPos> }
id see ItemStack definition of id
damage is an array of either 1 or 2 elements (2 specify a range); defaults to [ 0 ]
count is an array of either 1 or 2 elements (2 specify a range); defaults to [ 1 ]
weight controls how often the loot spawns
Examples:
{ "id": "dye", "damage": [ 0, 15 ], "count": [ 1 ], "weight": 10 }
{ "id": "~hee:end_powder", "count": [ 3, 8 ], "weight": 95 }
<ItemPattern>
Pattern that is used to search for specific kinds of blocks and items.
{ "id": <String>, "damage": <Array (IntegerRange (0-32767))>, "tag": <Nbt> }
id minecraft: prefix can be omitted
~hee: prefix can be used as an abbreviation for HEE items
<prefix>:* using an asterisk instead of item name accepts all items from the mod (vanilla items require the minecraft: prefix)
* asterisk without prefix accepts all items in the game
damage defaults to empty array, which accepts any damage values
tag defaults to an empty object, which accepts any NBT structure
<SpawnEntry>
Information uses for mob spawning.
{ "id": <String>, "limit": <IntegerRange (1-127)>, "weight": <IntegerRange (1-127)> }
id mob name
limit maximum amount of mobs that can exist at one time
weight controls how often the mob spawns
IMC - Essence
Adding a new Dragon Essence Altar recipe
Removing Dragon Essence Altar recipes
Type determines where to look (either input or output).
Limit (optional) is the max amount of removed recipes, 0 = unlimited. { "type": <String>, "search": <ItemPattern>, "limit": <IntegerPos0> } { "type": "input", "search": { "id": "~hee:*" } } { "type": "output", "search": { "id": "brewing_stand" }, "limit": 1 }
IMC - Mobs
Making a mob immune to Ender Goo
Setting mob's Energy level
IMC - Orb
Blacklisting Instability Orb item
If all items are removed, the list will fall back to dungeon loot. { "pattern": <ItemPattern> } {}
Adding Instability Orb mobs
Removing Instability Orb mobs
IMC - Tables
Decomposition Table blacklist
Extraction Table item Energy
Adding items to Experience Table
IMC - World
Adding loot to dungeons and other objects
DungeonTowerChest, DungeonTowerFurnaceFuel, RavagedDungeonGeneral, RavagedDungeonUncommon, RavagedDungeonRare, RavagedDungeonFinalRoom, HiddenCellarNormalHomeland, HiddenCellarRareHomeland, HiddenCellarNormalLaboratory, HiddenCellarRareLaboratory, HomelandCache, LaboratorySmallChest, LaboratoryLargeChest { "list": <String>, "item": <WeightedItem> } { "list": "DungeonTowerChest", "item": { "id": "minecraft:dye", "damage": [ 0, 15 ], "count": [ 2 ], "weight": 50 } }
Removing loot from dungeons and other objects
The search pattern only handles the item name, damage and NBT data are ignored.
Limit (optional) is the max amount of removed recipes, 0 = unlimited. { "list": <String>, "search": <ItemPattern>, "limit": <IntegerPos0> } { "list": "DungeonTowerFurnaceFuel", "search": { "id": "*" }, "limit": 6 }
Adding mobs to Biome Islands
InfestedForest.Deep, InfestedForest.Ravaged, BurningMountains.Scorching, BurningMountains.Mine, EnchantedIsland.Homeland, EnchantedIsland.Laboratory
{ "biome": <String>, "mob": <SpawnEntry> } { "biome": "InfestedForest.Ravaged", "mob": { "id": "Silverfish", "limit": 32, "weight": 10 } }
IMC - System
Disabling mod integration
All integration handlers are on GitHub. Keep in mind that the IMC system will not report invalid mod IDs! { "modid": <String> } { "modid": "NotEnoughItems" }