Skip to content

ENIM Json Model Format: For Resource Pack Artists

Jump to bottom
Chris Nero edited this page Apr 12, 2018 · 19 revisions

Entity JSON model files contain model element definitions and animation declarations. The structure for these files mirrors the 1.8 block model system, using both model definition files in the models/entity/ directory and "entitystate" files in the entitystates/ directory.

Model Definition Files

Below is an example of a model definition file for the chicken.

{
    "properties": {
        "nameplate": 16,
        "shadowsize": 4.8
    },
    "elements": [
        {
            "name": "body",
            "from": [5,5,-2],
            "to": [11,13,4],
            "uv": [0,9],
            "origin": [8,5,4],
            "rotation": [-90,0,0]
        },
        {
            "name": "right_wing",
            "from": [4,7,5],
            "to": [5,11,11],
            "uv": [24,13],
            "origin": [4,11,8]
        },
        {
            "name": "left_wing",
            "from": [11,7,5],
            "to": [12,11,11],
            "uv": [24,13],
            "origin": [12,11,8]
        },
        {
            "name": "right_leg_outside",
            "from": [5,0.005,7],
            "to": [8,5.005,10],
            "uv": [26,0],
            "origin": [6.5,5,7]
        },
        {
            "name": "left_leg_outside",
            "from": [8,0.005,7],
            "to": [11,5.005,10],
            "uv": [26,0],
            "origin": [9.5,5,7]
        },
        {
            "name": "head",
            "from": [6,9,11],
            "to": [10,15,14],
            "uv": [0,0],
            "origin": [8,11,11],
            "head": true
        },
        {
            "name": "wattle",
            "parent": "head",
            "from": [7,9,13],
            "to": [9,11,15],
            "uv": [14,4]
        },
        {
            "name": "beak",
            "parent": "head",
            "from": [6,11,14],
            "to": [10,13,16],
            "uv": [14,0]
        }
    ],
    "animations": {
        "moving": {
            "scaled": true,
            "script": "biped_swing",
            "with": {
                "left": "left_leg_outside",
                "right": "right_leg_outside"
            }
        },
        "airborne": {
            "script": "chicken_wings",
            "with": {
                "left": "left_wing",
                "right": "right_wing"
            }
        }
    }
}

Model definition files contain five sections, all of which are optional. These are:

  • Properties: Properties control various aspects of the model, such as the nameplate height and held item positions.
  • Parents: Imports are references to elements or animations in other files.
  • Elements: Elements are the cuboid definitions that make up the model.
  • Element Overrides: Overrides enable the default transformations for elements to be overridden.
  • Animations: Animations define how the model moves under certain conditions.

Properties

Properties are model attributes that are not part of the other categories. They are defined in the properties tag. The complete list of properties are as follows:

  • nameplate: Number. The height at which an entity's custom name is rendered with this model.
  • shadowsize: Number. The radius of the entity's shadow in block-pixels.
  • righthand: A structure specifying the position, rotation, and scale of items in the right hand. Both position and rotation default to [0,0,0], and scale defaults to 1.
  • lefthand: Like righthand, but for items in the left hand.
  • helmet: Like righthand, but for items worn on the head. Note that this is not used for armor.

Example properties tag

"properties": {
    "nameplate": 16,
    "righthand": {
        "position": [4,12,10],
        "rotation": [90,-45,0]
    }
}

Parents

The model system uses a simple multiple-inheritance mechanism to inherit from other models. Parents are referenced by using the model file locations (relative to models/entity/) as values in a list. The entirety of the model is inherited, including animations, elements, properties, and overrides. Additionally, if multiple parent models define the same feature, the rightmost parent model's definition is used for those features. Parent models are not checked for consistency (that is, elements referred to in the model need not be defined), and child models are expected to provide the missing definitions.

Example parents tag

"parents": ["creeper","bunkernine:splootch"]

In this example, the models creeper and bunkernine:splootch are used, with features in bunkernine:splootch taking precedence over those in creeper.

Elements

Elements define the actual model. Similar to vanilla block models, elements define a set of cuboids that make up the entity model. An example of one element that defines many possible attributes is shown below.

{
    "name": "element",
    "type": "box",
    "parent": "p_element",
    "from": [0,0,0],
    "to": [16,16,16],
    "uv": [0,0],
    "origin": [8,8,8],
    "pivot": [8,0,8],
    "rotation": [0,45,0],
    "scale": [0.75,1,0.75],
    "translucent": false,
    "head": false,
    "mirrored": true,
    "tintindex": 0
}

All attributes are (technically) optional and will contain default values if they are not present. Numerical values are in units of "block-pixels" at the default resolution (that is, every 1/16 of a block). Detail for attributes common to all element types is as follows.

  • type: What kind of element this defines. Valid values are box, block, and item, the default is box. Element type box defines a traditional entity model part, while types block and item define block and item models, respectively.
  • name: The element name. Element names must be lowercase and contain only letters, numbers, and underscores. As well, no two elements in a model (including imported elements) may have the same name. If a name is not specified, a unique name will be assigned to the element.
  • parent: The parent element, or null if there is no parent. When an element has a parent element, it is called a child element. A child element inherits transformation from its parent, both from animations and from default transformations. This is useful to define a group of elements that should logically move together, such as the head and facial features, or legs and feet. Typically, entity models have one element for the main body and several children defining appendages. Child elements do not lose the ability to define transformations or be animated in addition to those defined by their parent element, including defining their own origin. However, the parent's origin will still be used for transformations inherited from the parent.
  • origin: The origin of transformation of the element. The origin defaults to [0,0,0] and should be overridden for element which are transformed. The origin is used as the origin point for scaling and, if no pivot is specified, for rotation as well. There are no restrictions on the position of the origin.
  • pivot: The origin of rotation of the element. This differs from origin in that scaling is not applied about the pivot. If not specified, the pivot defaults to the value of the origin. As with the origin, there are no restrictions on the pivot's position.
  • rotation: The default rotation of the element (and its children) about its pivot, applied before any animations. There are no restrictions on the angles of rotation nor the axes of rotation.
  • scale: The scale of the element, defaults to 1. This is used to enlarge or shrink an element (and its children) relative to its origin. This may be specified as a single number or as an array of three numbers defining the scale along each axis. Scaling an element does not change its dimensions with respect to texture mapping.
  • head: Whether this element should be considered a head, defaults to false. Head elements (and their children) are rotated when rendering to face the direction the entity is looking.

Attributes specific to the box element type are as follows.

  • from: The lowermost vertex of the element. This attribute (with to) is analogous to the block model attribute of the same name, except that there are no restrictions on the position and size of the element.
  • to: The uppermost vertex of the element. This attribute (with from) is analogous to the block model attribute of the same name, except that there are no restrictions on the position and size of the element. Both from and to are measured so that the values [8,0,8] is centered and on the ground. Note: While the position of the element need not be at whole numbers, the dimensions should be whole numbers to ensure that the element renders properly.
  • uv: The texture coordinates of the element. The uv corresponds to the top left vertex of the texture map of the faces (this is equivalent to the attribute of the same name in MCWin10). The values for uv must be nonnegative and not greater than the dimensions of the texture image defined in the entitystate file.
  • translucent: Whether this element should display semitransparent pixels when rendering, defaults to false.
  • mirrored: Whether the texture for this element should be mirrored, defaults to false.
  • tintindex: Analogous to the block model property of the same name. For entities which use color overlay, this specifies which color to overlay on the element. For living entities, dyed armor uses index 2.

These are attributes specific to the block and item element types.

  • block: Defines the blockstate used for the block render type. This object contains a field id, the block id, and a field state, a map of key-value pairs representing the block state.
  • item: A string containing the item id to render. Item data is not supported.

Overrides

Element overrides are used to provide new values for default transformations of imported elements (while overrides can be used for normal declared elements, there is no reason to do this). The attributes that can be overridden are rotation and scale. For example, to enlarge the head of a baby animal, the model file would import all the elements from the adult model and override the scale of the head.

"overrides": {
    "head": { "scale": 2 }
}

In the example above, the imported element named head is being overridden with a new scale of 2.

Animations

Animations control how the model moves. The different types of animations are:

  • idle: Always animates.
  • moving: For when the entity is in motion.
  • swimming: When the entity is in or under water.
  • airborne: When the entity is in the air.
  • tracking: When the entity (a hostile mob) is targeting the player or another entity.
  • bowhold: When the entity is tracking and additionally is holding a bow.
  • jump: Plays once when the entity jumps.
  • attack: Plays when the entity attacks.
  • damage: Plays when the entity is damaged.
  • eat: Plays when the entity eats. Currently only used for sheep.
  • open: Plays when the entity opens. Currently only used for chests.
  • close: Plays when the entity closes. Currently only used for chests.

The animation types idle, moving, swimming, airborne, tracking, and bowhold are looped; the others are played once when conditions are satisfied. Within each type tag are the following:

  • scaling: (Optional) when defined, the animation is scaled relative to the speed of the entity. This is useful for walking animations where the entity's legs move farther as it moves faster.
  • tuning: (Optional) when defined, the animation speed is related to the speed of the entity. This is useful for walking animations which speed up as the entity moves faster.
  • script: The AbieScript file, relative to models/animations, that contains the animation definition.
  • with: A map that associates the script's defines with the model's elements.

Example animation tag:

"animations": {
    "moving": {
        "script": "biped_swing",
        "with": {
            "left": "left_leg",
            "right": "right_leg"
        }
    },
    "jump": {
        "script": "mymod:flip_jump",
        "with": { "entity": "body" }
    }
}

This example defines two animations, moving and jump. The script for moving is minecraft:biped_swing and for jump mymod:flip_jump.

Entitystate Files

Entitystate files are analogous to blockstate files in the 1.8 block model system and are found under entitystates/. Entitystate files specify which model is applied to the entity under which conditions, as well as specify a texture and some default transformations. Below is the entitystate file for the sign.

{
    "defaults": {
        "texture": "entity/sign",
        "size": [64,32]
    },
    "states": {
        "rotation=south": { "model": "wall_sign" },
        "rotation=north": { "model": "wall_sign", "y": 180 },
        "rotation=west" : { "model": "wall_sign", "y": -90 },
        "rotation=east" : { "model": "wall_sign", "y": 90 },

        "rotation=n": { "model": "floor_sign" },
        "rotation=nne": { "model": "floor_sign", "y": 22.5 },
        "rotation=ne": { "model": "floor_sign", "y": 45 },
        "rotation=ene": { "model": "floor_sign", "y": 67.5 },
        "rotation=e": { "model": "floor_sign", "y": 90 },
        "rotation=ese": { "model": "floor_sign", "y": 112.5 },
        "rotation=se": { "model": "floor_sign", "y": 135 },
        "rotation=sse": { "model": "floor_sign", "y": 157.5 },
        "rotation=s": { "model": "floor_sign", "y": 180 },
        "rotation=ssw": { "model": "floor_sign", "y": -157.5 },
        "rotation=sw": { "model": "floor_sign", "y": -135 },
        "rotation=wsw": { "model": "floor_sign", "y": -112.5 },
        "rotation=w": { "model": "floor_sign", "y": -90 },
        "rotation=wnw": { "model": "floor_sign", "y": -67.5 },
        "rotation=nw": { "model": "floor_sign", "y": -45 },
        "rotation=nnw": { "model": "floor_sign", "y": -22.5 }
    }
}

Entitystate files contain two sections:

  • States: A mapping of the different states for a certain entity to models and textures.
    • Note that entitystate files may also use a multipart format similar to the blockstate multipart format.
  • Defaults: Default values for most state attributes.

States

The set of states for an entity is hardcoded, but each state can be customized with completely different models and textures. The complete list of state attributes is as follows:

  • model: The model file (relative to models/entity/) that contains the model for the state. This must be an entity model, not a block or item model.
  • texture: The texture to use for the model (relative to textures/).
  • overlay: The texture overlay. The overlay is used for "bright" textures such as spider and enderman eyes.
  • size: The texture width and height. The texture size should be a whole factor of the size of the texture image, depending on the resolution of the image. Typical sizes are [64,32] and [64,64]. The size defaults to [64,32].
  • y: The rotation of the model about the vertical axis, in degrees. There are no restrictions on the value of the rotation.
  • scale: The scale of the whole model relative to the point [8,0,8]. This point is the lower center of the model. The entire model coordinates, including those used in the properties tag, are scaled. Note that, unlike with model files, the scale value must be a single number.
  • armor: The armor file (relative to models/armor/) that contains armor models for this state.

Only the model attribute is required. The others (except for armor) may be taken from the defaults tag or have default values. States may contain multiple models by putting the models in a list. This allows multiple models to be rendered for each state. This is not random models.

Defaults

If many states have the same attributes, such as texture or size, these can be put in the defaults tag to reduce repetition. Every attribute except model and armor may be put into the defaults.

Multipart

For entities which have many states, it is often easier to specify models using a predicate-based system. This system is called "multipart" because of its similarity to the blockstate system of the same name. Usage and syntax is identical, except that the pipe (|) may not be used in values to indicate logical OR. As well, conditions may be arrays in addition to compounds; an array is treated as logical OR.

Armor Files

Any living entity has the capability to render armor. Armor files define the models to use for each armor piece on a particular entity state. Below is the armor file for bipeds.

{
    "defaults": {
        "head": { "model": "biped_helmet" },
        "chest": { "model": "biped_chestplate" },
        "legs": { "model": "biped_leggings" },
        "feet": { "model": "biped_boots" }
    },
    "materials": {
        "leather": {
            "head": [
                { "model": "tinted_biped_helmet", "texture": "models/armor/leather_layer_1" },
                { "model": "biped_helmet", "texture": "models/armor/leather_layer_1_overlay" }
            ],
            "chest": [
                { "model": "tinted_biped_chestplate", "texture": "models/armor/leather_layer_1" },
                { "model": "biped_chestplate", "texture": "models/armor/leather_layer_1_overlay" }
            ],
            "legs": [
                { "model": "tinted_biped_leggings", "texture": "models/armor/leather_layer_2" },
                { "model": "biped_leggings", "texture": "models/armor/leather_layer_2_overlay" }
            ],
            "feet": [
                { "model": "tinted_biped_boots", "texture": "models/armor/leather_layer_1" },
                { "model": "biped_boots", "texture": "models/armor/leather_layer_1_overlay" }
            ]
        }
    }
}

Armor files contain two sections, both optional. However, armor pieces which do not have a model defined through either section will render as the missing model.

  • Defaults: States (in the entitystate format) for generic armor pieces of any material. These will be used for any pieces not explicitly defined, with the texture inferred from the material name.
  • Materials: Custom models for specific armor pieces. Each piece is defined first by its material (leather, iron, etc.), then by its equipment slot (legs, chest, etc.). These models override those defined as defaults.

ENIM Json Model Format

AbieScript Animations Format

The ENIM Framework

Clone this wiki locally