IMC Methods

🔧 Developer-Oriented Content*This page contains content directed towards other mod developers! If you are simply playing the game with the mod, this information is useless.*

Depending on the version of EtiMod you have, this may change. As such, versions will be documented here accordingly. The IMC receiver expects a string to be given over in a very specific format to map information.

For more information on what IMC is and how to use it, consider installing the latest MDK and looking at the example mod's main source file.

## Pre-Existing Data

Depending on the mods regularly used by Eti, some audio definitions for your mod may be already defined (this generally occurs to a very small selection of large scale, mainstream mods). If this is the case, and you have found that your mod already has a sound defined natively, fear not! You are still able to send IMC methods to override the sound. Asking for a replacement in source is entirely optional and not necessary, as an override provided by your mod will take precedence over the code-defined value in EtiMod. Still, if you wish to, you may file an issue on the Github Repository (see Reporting Bugs) to request removal of the default sound.

A list of blocks that have had sounds replaced can be found on Modded Blocks with Predefined Custom Sounds.

## Handling Malformed IMC Data

In the event that your mod sends malformed data over IMC, Forge loading will terminate, and users will be greeted with a message stating that your mod sent invalid IMC data, being instructed to report it to you.

Users should send you their crash report, which will contain more detailed information on what the failure was as well as an error code. Please look at this page for a detailed list of what every error code is, as well as what tends to cause that specific error and how you can fix it.

If users receive an error message stating your mod is at fault, **do not send them to Eti's repository to report the bug.** If you are having an issue with IMC in development, and you are certain it is caused by this mod, please report it. Check Reporting Bugs for more information.

## Methods

All parameters are separated by vertical bars `|`

## Method: registerSpiritStepSound

*registerSpiritStepSound* is the method used to tell EtiMod that when a spirit walks on (or in) a specific block from your mod, the custom spirit sound handler should treat it as if it is using a specific custom material. **This is only useful for blocks whose defined material (in your block class constructor) differs from what it might sound like.** You can verify this sound by finding its mapping on Block to Material Bindings, and preview the sound on SpiritMaterial Enum. An example might be `biomesoplenty:flesh` in the Nether, which, by rule of its vanilla material, happens to use the `SpiritMaterial.WOOL` sound for spirits. A better suited sound would be something like `SpiritMaterial.SHROOM`. To achieve this, the IMC would be sent to etimod with the following argument: `biomesoplenty:flesh|SHROOM`

Valid inputs to IMC:

* `yourBlockRsrc|spiritMtl|useIfIn`
* `yourBlockRsrc|spiritMtl`

 useIfIn | boolean (Optional) | true

The `useIfIn` parameter determines if your block's sound should be used if the player is walking while *inside of* your block (rather than walking on top of it). This is useful for things like layered snow in vanilla, where the snow layer block occupies the same `BlockPos` as the player. **Additionally, if you only need to set `useIfIn`, consider using the dedicated `setUseIfIn` IMC Method instead.**

### Implementation in EtiMod 4.4+

```
   private void enqueueIMC(final InterModEnqueueEvent event) {
       // Register yourmodid:someblock to SpiritMaterial.SHROOM, with useIfIn=false implicitly.
       InterModComms.sendTo("etimod", "registerSpiritStepSound", () -> { return "yourmodid:someblock|SHROOM" });

       // Register yourmodid:someblock to SpiritMaterial.SHROOM, with useIfIn=true explicitly.
       InterModComms.sendTo("etimod", "registerSpiritStepSound", () -> { return "yourmodid:someblock|SHROOM|true" });
   }

```

### Applicable errors

This IMC method call may raise one of the following errors:

* FAILURE\_INVALID\_ARG\_COUNT
* FAILURE\_INVALID\_TYPE
* FAILURE\_INVALID\_SPIRIT\_MATERIAL
* FAILURE\_BLOCK\_IS\_UNOWNED

## Method: registerCustomMaterialSound

*registerCustomMaterialSound* is the method used to tell EtiMod that when a spirit walks on (or in) a block using a custom-defined material from your mod, that material should be associated with the given SpiritMaterial Enum. An example might be a custom material you have named `CRYSTAL`, which you would like to associate with `SpiritMaterial.GLASS`. To achieve this, the IMC would be sent to etimod with the following argument: `com.yourmod.material.CustomMaterials.CRYSTAL|GLASS`

 spiritMtl | SpiritMaterial (as String) | "GLASS"

### Implementation in EtiMod 4.5+

```
   private void enqueueIMC(final InterModEnqueueEvent event) {
       // Pretend you have a class named CustomMaterials in package com.yourmod.material
       // In this class, you have a field:
       // public static final Material CRYSTAL = new Material.Builder(...);

       // To register this material to a given SpiritMaterial, use:
       InterModComms.sendTo("etimod", "registerCustomMaterialSound", () -> { return "com.yourmod.material.CustomMaterials.CRYSTAL|GLASS" });
   }

```

### Applicable errors

This IMC method call may raise one of the following errors:

* FAILURE\_INVALID\_ARG\_COUNT
* FAILURE\_MATERIAL\_FIELD\_IS\_PRIVATE\_AND\_LOCKED
* FAILURE\_COULD\_NOT\_RESOLVE\_CLASS
* FAILURE\_COULD\_NOT\_RESOLVE\_FIELD
* FAILURE\_FIELD\_NOT\_STATIC
* FAILURE\_NOT\_MATERIAL\_CLASS
* FAILURE\_MATERIAL\_IS\_NULL
* FAILURE\_INVALID\_SPIRIT\_MATERIAL

## Method: setUseIfIn

*setUseIfIn* is the method used to tell EtiMod that when a spirit walks in a block from your mod, the block they are inside of should be used for the step sound rather than the block directly below them. This is useful for things like layered snow, which occupy the same BlockPos as the player and simply have no collision. It is proper behavior to play the snow sound rather than the sound of the block underneath. An example might be a rain puddle block that you want to associate with stepping in water. To achieve this, the IMC would be sent with the following argument: `yourmod:puddle|true`

 useIfIn | boolean | true

Note: While it is possible to set useIfIn=false, this is completely useless and will only waste loading time. It is possible for the sake of forward compatibility in the event that a reason to append it comes up.

### Implementation in EtiMod 4.5+

```
   private void enqueueIMC(final InterModEnqueueEvent event) {
       InterModComms.sendTo("etimod", "setUseIfIn", () -> { return "yourmod:puddle|true" });
   }

```

### Applicable errors

This IMC method call may raise one of the following errors:

* FAILURE\_INVALID\_ARG\_COUNT
* FAILURE\_BLOCK\_IS\_UNOWNED
* FAILURE\_INVALID\_TYPE

## Method: requestGenericAPI

*requestGenericAPI* will cause EtiMod to send IMC data to your mod with the key `etimod-sendGenericAPI`. You should receive this IMC event. It's message will be an instance of `BiFunction<String, Object[], Object>`.

The parameters for this `BiFunction` in order are:

 return Object | The value returned from the method, or null if the method does not return a value. | --

All methods possible through the generic API are outlined on Generic API.

### Applicable errors

This IMC method call may raise one of the following errors:

* This does not raise errors.

## Method: requestComplexMaterialRegistry

*requestComplexMaterialRegistry* will cause EtiMod to send IMC data to your mod with the key `etimod-sendComplexMaterialRegistry`. You should receive this IMC event. Its message will be an instance of `BiConsumer<ResourceLocation, Function3<Entity, BlockPos, BlockPos, String>>`. **Note that this API member is useless unless you use `registerSpiritStepSound` and associate your block with a Conditional SpiritMaterial.**

The parameters for this `BiConsumer` in order are:

 Function3<...> | The input parameters in order are the entity that walked on the block, the position of the block the entity is standing on, and the position of the block the entity is standing in. The return value should be a string representing a SpiritMaterialModState. The Entity will always be a player as of version Alpha 6.0 | YourDesiredClass::someMethodWithTheRightSignature

### Applicable errors

This IMC method call may raise one of the following errors:

* This does not raise errors.