Skip to content

Integrating Your Mod with ENIM: The ENIM Framework

Jump to bottom
Chris Nero edited this page Jun 18, 2017 · 7 revisions

Note: Up-to-date documentation for APIs (such as the animation system) can be found in doc comments in the code which may be run through a documentation generator.

ENIM provides a framework for adding customizable entity models. However, by default no entities have custom models. Vanilla entities come bundled with ENIM itself, but mod-added entities need to be added separately. This page describes the ENIM entity render framework and the steps necessary to add custom models to the entities in your mod.

The RenderState Format

(package kvverti.enim.entity.state)
Under ENIM, entity renders contain a map relating the state of an entity to a model, similar to the BlockState system for blocks in vanilla. RenderStates are exactly like IBlockStates, except that they implement a different interface and do not contain the #getBlock() method. To obtain a RenderState, call getStateManager().getDefaultState() in the render class and set the state properties appropriately.

StateManager

Each of the base render classes provides a StateManager through its getStateManager() method. The StateManager keeps track of the render's entitystates and associates each RenderState with an EntityState.

Methods of the StateManager class

The StateManager class methods are listed here. The getDefaultState() and setDefaultState(RenderState) methods will be of the most use to clients.

  • StateManager(IProperty<?>...): Constructs a StateManager which uses the given properties for the render states.
  • RenderState getDefaultState(): Returns a RenderState in the default configuration for this render.
  • void setDefaultState(RenderState): Sets the default RenderState to the configuration of the given RenderState.
  • EntityState getState(RenderState): Returns the EntityState associated with the given RenderState. Most clients should use getCurrentEntityState() in the render class instead of this method.
  • ENIMModel getModel(RenderState): Returns the java model for the given state. The java model is used only for rendering and does not contain accessible information about the custom model. To get the custom model, use getCurrentEntityState().model() in the render class.

EnumStringSerializable

When creating an IProprty<T> based on an enum, the enum must implement IStringSerializable. This interface, EnumStringSerializable, extends that interface and provides a default implementation of the getName() method which returns the lowercase representation of the enum constant name.

ReloadableRender and Entity Renders

(package kvverti.enim.entity)
The underpinnings of ENIM renders rest on this interface: ReloadableRender. The interface allows for ENIM to reload renders and their models when the resources are reloaded. While you can implement this interface directly, ENIM provides a set of base classes to extend that implement the reloading functions of the interface.

ENIMRender<T>

The abstract class ENIMRender<T> is the base class for all reloadable entity renders. All the functionality related to reloading the render and basic functionality to rendering is provided. To create a basic entity render, one need only to extend this class and implement the method getStateFromEntity(T), which returns a RenderState based on the properties of the passed entity.

LivingRender<T>

The abstract class LivingRender<T> is a subclass of ENIMRender<T> for use with living entities (those which extend EntityLivingBase). The LivingRender<T> class contains additional functionality related to the rendering of living entities, such as rendering potion effects, damage, and death colorings.

ENIMTileEntityRender<T>

The abstract class ENIMTileEntityRender<T> is the base class for all reloadable tile entity renders. This class is similar to the ENIMRender<T> class, but is for tile entities. To create a basic tile entity render, one need only extend this class and implement the method getStateFromTile(T), which returns a RenderState based on the properties of the passed tile entity.

Other Classes

In addition to the base classes above, ENIM provides other classes for the most common implementations of renders.

  • BasicRender<T>: Provides a basic implementation of ENIMRender<T> for entities that do not have multiple states.
  • BasicLivingRender<T>: Provides a basic implementation of LivingRender<T> for entities that do not have multiple states.
  • SignLikeRender<T>: Provides a render implementation for sign-like tile entities, such as the sign and banner.

Methods of the Render Classes

All the base render classes share certain methods that clients may use or override in determining the rendering for the entity. They are as follows:

  • StateManager getStateManager(): Returns the StateManager for this render.
  • EntityState getCurrentEntityState(): Returns the EntityState that is rendered in this render tick.
  • boolean shouldRender(T): Clients may override this method to control the circumstances under which the entity is rendered.
  • void preRender(T, EntityInfo): Clients may override this method to perform any necessary logic before the entity is rendered. Important: subclasses must call super.preRender(entity, info) before performing any custom logic.
  • void postRender(T, EntityInfo): Clients may override this method to perform any necessary logic after the entity is rendered. Important: subclasses must call super.postRender(entity, info) after performing any custom logic.

The Model System

(package kvverti.enim.model)
This section describes the in-memory representation of custom entity models. See the ENIM Json Model Format for details on the resource pack side. The model system provides access to the models loaded from resource packs in a manner which mirrors the structure of custom models in resource packs. All properties are read-only and immutable; these classes cannot be used to change custom models. The main classes in the model system are given below:

EntityState

The EntityState class represents an entry in the states tag of the entitystate file. It provides access to attributes defined in the entitystate file through its accessor properties.

  • model(): The entity model, as an instance of EntityModel.
  • texture(): The ResourceLocation used as the entity texture. Note that ENIM uses dynamically loaded textures so this location will not correspond to the location of the texture image in the resource path.
  • size(): The dimensions of the texture, as an int[] of length 2. The dimensions may not always correspond to the dimensions of the texture image, for example in high-resolution resource packs.
  • y(): The rotation of the model around the vertical axis, as a float.
  • scale(): The scale of the model, as a float.

EntityModel

The EntityModel class represents a complete model from the models directory in the resources. This model fully resolves the imports and overrides specified in the model file. Thus, the elements and animations returned through its accessor properties represent all of the elements and animations of the model, including imports.

  • properties(): The entity properties, as an instance of ModelProperties.
  • elements(): An ImmutableSet of the model elements, as instances of ModelElement.
  • getElement(String): A convenience to get the model element with the given name.
  • animations(): An ImmutableMap associating the different types of animations with their animations. The keys are of type Animation.Type and values of type Animation. The map only contains keys which are present in the model file, that is, are imported or explicitly defined animations.

ModelProperties

This class contains the various model properties defined in the entity model file. Properties will be added or deprecated in this class when the model system adds or removes properties.

  • nameplate(): The height at which the custom name of the entity is rendered, as a float.
  • leftHand(): The origin for items held in the left hand, as an OriginPoint.
  • rightHand(): The origin for items held in the right hand, as an OriginPoint.

OriginPoint

OriginPoints associate a point in the render coordinate space with the name of a model element. The point will undergo the same transformations as its parent element.

  • parent: The name of the parent element present in this model.
  • coords: The point of origin as a Vec3f.

ModelElement

The ModelElement class is a structure that contains the information for a single element of a model. Properties will be added or deprecated in this class when the model system adds or removes properties.

  • name(): The element name, as a String.
  • parent(): The name of the parent element of this element, as a String. Returns null if there is no parent.
  • from(): The lowest vertex of this element, as a Vec3f.
  • to(): The highest vertex, as a Vec3f.
  • uv(): The texture coordinates of the element, as an int[] of length two.
  • origin(): The origin of transformation of the element, as a Vec3f.
  • rotation(): The rotation of the element in degrees, as a Vec3f.
  • scale(): The scale of the element, as a float.
  • isTranslucent(): Whether the element should be rendered as translucent.
  • isHead(): Whether this element represents a head.

ENIM Json Model Format

AbieScript Animations Format

The ENIM Framework

Clone this wiki locally